From da47638f42d7a93d6a769772b5a54445cde4d07f Mon Sep 17 00:00:00 2001 From: Larpon Date: Sun, 26 Sep 2021 06:34:47 +0200 Subject: [PATCH] toml: correct documentation (#11976) --- vlib/toml/any.v | 2 +- vlib/toml/ast/types.v | 35 +++++++++++++++++++++++++++++++++-- vlib/toml/checker/checker.v | 2 ++ vlib/toml/input/input.v | 2 ++ vlib/toml/parser/parser.v | 22 +++++++++++++--------- vlib/toml/toml.v | 10 +++++----- 6 files changed, 56 insertions(+), 17 deletions(-) diff --git a/vlib/toml/any.v b/vlib/toml/any.v index 5782243540..1d28abfa58 100644 --- a/vlib/toml/any.v +++ b/vlib/toml/any.v @@ -5,7 +5,7 @@ module toml import time -// Pretty much all json2 types plus time.Time +// Pretty much all the same builtin types as the `json2.Any` type plus `time.Time` pub type Any = Null | []Any | bool diff --git a/vlib/toml/ast/types.v b/vlib/toml/ast/types.v index a55c762da9..b7e0b4ecaf 100644 --- a/vlib/toml/ast/types.v +++ b/vlib/toml/ast/types.v @@ -58,12 +58,13 @@ pub fn (v Value) to_json() string { // found in a TOML document. pub type DateTimeType = Date | DateTime | Time +// str returns the `string` representation of the `DateTimeType` type. pub fn (dtt DateTimeType) str() string { return dtt.text } // value queries a value from the map. -// `key` should be in "dotted" form e.g.: `"a.b.c.d"` +// `key` should be in "dotted" form (`a.b.c`). pub fn (v map[string]Value) value(key string) &Value { null := &Value(Null{}) key_split := key.split('.') @@ -88,7 +89,7 @@ pub fn (v map[string]Value) value(key string) &Value { // TODO return error(@MOD + '.' + @STRUCT + '.' + @FN + ' key "$key" does not exist') } -// value queries a value from the map. +// exists returns true if the "dotted" `key` path exists in the map. pub fn (v map[string]Value) exists(key string) bool { key_split := key.split('.') if key_split[0] in v.keys() { @@ -107,12 +108,14 @@ pub fn (v map[string]Value) exists(key string) bool { return false } +// Comment is the data representation of a TOML comment (`# This is a comment`). pub struct Comment { pub: text string pos token.Position } +// str returns the `string` representation of the `Comment` type. pub fn (c Comment) str() string { mut s := typeof(c).name + '{\n' s += ' text: \'$c.text\'\n' @@ -128,16 +131,20 @@ pub: pos token.Position } +// str returns the `string` representation of the `Null` type pub fn (n Null) str() string { return n.text } +// Quoted is the data representation of a TOML quoted type (`"quoted-key" = "I'm a quoted value"`). +// Quoted types can appear both as keys and values in TOML documents. pub struct Quoted { pub: text string pos token.Position } +// str returns the `string` representation of the `Quoted` type. pub fn (q Quoted) str() string { mut str := typeof(q).name + '{\n' str += ' text: \'$q.text\'\n' @@ -146,12 +153,16 @@ pub fn (q Quoted) str() string { return str } +// Bare is the data representation of a TOML bare type (`bare_key = ...`). +// Bare types can appear only as keys in TOML documents. Otherwise they take the +// form of Bool or Numbers. pub struct Bare { pub: text string pos token.Position } +// str returns the `string` representation of the `Bare` type. pub fn (b Bare) str() string { mut str := typeof(b).name + '{\n' str += ' text: \'$b.text\'\n' @@ -160,12 +171,16 @@ pub fn (b Bare) str() string { return str } +// Bool is the data representation of a TOML boolean type (`... = true`). +// Bool types can appear only as values in TOML documents. Keys named `true` or `false` +// are considered as Bare types. pub struct Bool { pub: text string pos token.Position } +// str returns the `string` representation of the `Bool` type. pub fn (b Bool) str() string { mut str := typeof(b).name + '{\n' str += ' text: \'$b.text\'\n' @@ -174,12 +189,16 @@ pub fn (b Bool) str() string { return str } +// Number is the data representation of a TOML number type (`25 = 5e2`). +// Number types can appear both as keys and values in TOML documents. +// Number can be integers, floats, infinite, NaN - they can have exponents (`5e2`) and be sign prefixed (`+2`). pub struct Number { pub: text string pos token.Position } +// str returns the `string` representation of the `Number` type. pub fn (n Number) str() string { mut str := typeof(n).name + '{\n' str += ' text: \'$n.text\'\n' @@ -188,12 +207,16 @@ pub fn (n Number) str() string { return str } +// Date is the data representation of a TOML date type (`YYYY-MM-DD`). +// Date types can appear both as keys and values in TOML documents. +// Keys named like dates e.g. `1980-12-29` are considered Bare key types. pub struct Date { pub: text string pos token.Position } +// str returns the `string` representation of the `Date` type. pub fn (d Date) str() string { mut str := typeof(d).name + '{\n' str += ' text: \'$d.text\'\n' @@ -202,6 +225,8 @@ pub fn (d Date) str() string { return str } +// Time is the data representation of a TOML time type (`HH:MM:SS.milli`). +// Time types can appear only as values in TOML documents. pub struct Time { pub: text string @@ -209,6 +234,7 @@ pub: pos token.Position } +// str returns the `string` representation of the `Time` type. pub fn (t Time) str() string { mut str := typeof(t).name + '{\n' str += ' text: \'$t.text\'\n' @@ -218,6 +244,8 @@ pub fn (t Time) str() string { return str } +// DateTime is the data representation of a TOML date-time type (`YYYY-MM-DDTHH:MM:SS.milli`). +// DateTime types can appear only as values in TOML documents. pub struct DateTime { pub: text string @@ -226,6 +254,7 @@ pub: time Time } +// str returns the `string` representation of the `DateTime` type. pub fn (dt DateTime) str() string { mut str := typeof(dt).name + '{\n' str += ' text: \'$dt.text\'\n' @@ -236,11 +265,13 @@ pub fn (dt DateTime) str() string { return str } +// EOF is the data representation of the end of the TOML document. pub struct EOF { pub: pos token.Position } +// str returns the `string` representation of the `EOF` type. pub fn (e EOF) str() string { mut str := typeof(e).name + '{\n' str += ' pos: $e.pos\n' diff --git a/vlib/toml/checker/checker.v b/vlib/toml/checker/checker.v index dd99ccc642..feaed8af5d 100644 --- a/vlib/toml/checker/checker.v +++ b/vlib/toml/checker/checker.v @@ -14,6 +14,8 @@ pub struct Checker { scanner &scanner.Scanner } +// check checks the `ast.Value` and all it's children +// for common errors. pub fn (c Checker) check(n &ast.Value) ? { walker.walk(c, n) ? } diff --git a/vlib/toml/input/input.v b/vlib/toml/input/input.v index 2b7f199a53..a7b9064429 100644 --- a/vlib/toml/input/input.v +++ b/vlib/toml/input/input.v @@ -11,6 +11,8 @@ pub: file_path string // '/path/to/file.toml' } +// validate returns an optional error if more than one of the fields +// in `Config` has a non-default value (empty string). pub fn (c Config) validate() ? { if c.file_path != '' && c.text != '' { error(@MOD + '.' + @FN + diff --git a/vlib/toml/parser/parser.v b/vlib/toml/parser/parser.v index 0b7711ef88..5f3906af65 100644 --- a/vlib/toml/parser/parser.v +++ b/vlib/toml/parser/parser.v @@ -9,9 +9,7 @@ import toml.util import toml.token import toml.scanner -// Scanner contains the necessary fields for the state of the scan process. -// the task the scanner does is also refered to as "lexing" or "tokenizing". -// The Scanner methods are based on much of the work in `vlib/strings/textscanner`. +// Parser contains the necessary fields for keeping the state of the parsing process. pub struct Parser { pub: config Config @@ -31,8 +29,8 @@ mut: ast_root &ast.Root = &ast.Root{} } -// Config is used to configure a Scanner instance. -// Only one of the fields `text` and `file_path` is allowed to be set at time of configuration. +// Config is used to configure a Parser instance. +// `run_checks` is used to en- or disable running of the strict `checker.Checker` type checks. pub struct Config { pub: scanner &scanner.Scanner @@ -116,10 +114,11 @@ fn (mut p Parser) expect(expected_token token.Kind) ? { } } -// find_table returns a reference to a map if found in the root table given a "dotted" key ('a.b.c'). +// find_table returns a reference to a map if found in the *root* table given a "dotted" key (`a.b.c`). // If some segments of the key does not exist in the root table find_table will // allocate a new map for each segment. This behavior is needed because you can // reference maps by multiple keys "dotted" (separated by "." periods) in TOML documents. +// See also `find_in_table`. pub fn (mut p Parser) find_table() ?&map[string]ast.Value { util.printdbg(@MOD + '.' + @STRUCT + '.' + @FN, 'locating "$p.root_map_key" in map ${ptr_str(p.root_map)}') mut t := &map[string]ast.Value{} @@ -133,6 +132,8 @@ pub fn (mut p Parser) find_table() ?&map[string]ast.Value { return p.find_in_table(mut t, p.root_map_key) } +// sub_table_key returns the logic parts of a dotted key (`a.b.c`) for +// use with the `find_sub_table` method. pub fn (mut p Parser) sub_table_key(key string) (string, string) { mut ks := key.split('.') last := ks.last() @@ -140,10 +141,11 @@ pub fn (mut p Parser) sub_table_key(key string) (string, string) { return ks.join('.'), last } -// find_sub_table returns a reference to a map if found in `table` given a "dotted" key ('aa.bb.cc'). -// If some segments of the key does not exist in the input map find_in_table will +// find_sub_table returns a reference to a map if found in the *root* table given a "dotted" key (`a.b.c`). +// If some segments of the key does not exist in the input map find_sub_table will // allocate a new map for the segment. This behavior is needed because you can // reference maps by multiple keys "dotted" (separated by "." periods) in TOML documents. +// See also `find_in_table`. pub fn (mut p Parser) find_sub_table(key string) ?&map[string]ast.Value { mut ky := p.root_map_key + '.' + key if p.root_map_key == '' { @@ -161,7 +163,7 @@ pub fn (mut p Parser) find_sub_table(key string) ?&map[string]ast.Value { return p.find_in_table(mut t, ky) } -// find_in_table returns a reference to a map if found in `table` given a "dotted" key ('aa.bb.cc'). +// find_in_table returns a reference to a map if found in `table` given a "dotted" key (`a.b.c`). // If some segments of the key does not exist in the input map find_in_table will // allocate a new map for the segment. This behavior is needed because you can // reference maps by multiple keys "dotted" (separated by "." periods) in TOML documents. @@ -206,6 +208,8 @@ pub fn (mut p Parser) find_in_table(mut table map[string]ast.Value, key string) return t } +// sub_key parses next tokens as sub/nested keys. This is the also referred to as +// a "dotted" key (`a.b.c`). sub_key returns a string in dotted form. pub fn (mut p Parser) sub_key() ?string { util.printdbg(@MOD + '.' + @STRUCT + '.' + @FN, 'parsing nested key...') key := p.key() ? diff --git a/vlib/toml/toml.v b/vlib/toml/toml.v index 236a7ccc8f..0ae18d187b 100644 --- a/vlib/toml/toml.v +++ b/vlib/toml/toml.v @@ -67,9 +67,9 @@ pub fn parse_text(text string) ?Doc { } } -// parse parses the TOML document provided in `input`. -// parse automatically try to determine if the type of `input` is a file or text. -// For explicit parsing of input see `parse_file` or `parse_text`. +// parse parses the TOML document provided in `toml`. +// parse automatically try to determine if the type of `toml` is a file or text. +// For explicit parsing of input types see `parse_file` or `parse_text`. pub fn parse(toml string) ?Doc { mut input_config := input.Config{} if !toml.contains('\n') && os.is_file(toml) { @@ -95,7 +95,7 @@ pub fn parse(toml string) ?Doc { } } -// to_json returns a compact json string of the complete document +// to_json returns a compact json string of the complete document. pub fn (d Doc) to_json() string { return d.ast.to_json() } @@ -119,7 +119,7 @@ fn (d Doc) ast_to_any(value ast.Value) Any { return Any(Null{}) // TODO decide this // panic(@MOD + '.' + @STRUCT + '.' + @FN + - // ' failed converting "$date_str" to iso8601: $err') + // ' failed converting "$date_str" to rfc3339: $err') } } else if value is ast.Time { time_str := (value as ast.Time).text