vieter-v
/
v
2
0
Fork 0
Code Issues Pull Requests Releases Activity

toml: correct documentation (#11976)

pull/11981/head
Larpon 2021-09-26 06:34:47 +02:00 committed by GitHub
parent 863dd0b23e
commit da47638f42
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 56 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
vlib/toml/any.v
View File

@ -5,7 +5,7 @@ module toml
import time 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 pub type Any = Null
| []Any | []Any
| bool | bool

35
vlib/toml/ast/types.v
View File

@ -58,12 +58,13 @@ pub fn (v Value) to_json() string {
// found in a TOML document. // found in a TOML document.
pub type DateTimeType = Date | DateTime | Time pub type DateTimeType = Date | DateTime | Time
// str returns the `string` representation of the `DateTimeType` type.
pub fn (dtt DateTimeType) str() string { pub fn (dtt DateTimeType) str() string {
return dtt.text return dtt.text
} }
// value queries a value from the map. // 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 { pub fn (v map[string]Value) value(key string) &Value {
null := &Value(Null{}) null := &Value(Null{})
key_split := key.split('.') 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') // 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 { pub fn (v map[string]Value) exists(key string) bool {
key_split := key.split('.') key_split := key.split('.')
if key_split[0] in v.keys() { if key_split[0] in v.keys() {
@ -107,12 +108,14 @@ pub fn (v map[string]Value) exists(key string) bool {
return false return false
} }
// Comment is the data representation of a TOML comment (`# This is a comment`).
pub struct Comment { pub struct Comment {
pub: pub:
text string text string
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `Comment` type.
pub fn (c Comment) str() string { pub fn (c Comment) str() string {
mut s := typeof(c).name + '{\n' mut s := typeof(c).name + '{\n'
s += ' text: \'$c.text\'\n' s += ' text: \'$c.text\'\n'
@ -128,16 +131,20 @@ pub:
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `Null` type
pub fn (n Null) str() string { pub fn (n Null) str() string {
return n.text 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 struct Quoted {
pub: pub:
text string text string
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `Quoted` type.
pub fn (q Quoted) str() string { pub fn (q Quoted) str() string {
mut str := typeof(q).name + '{\n' mut str := typeof(q).name + '{\n'
str += ' text: \'$q.text\'\n' str += ' text: \'$q.text\'\n'
@ -146,12 +153,16 @@ pub fn (q Quoted) str() string {
return str 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 struct Bare {
pub: pub:
text string text string
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `Bare` type.
pub fn (b Bare) str() string { pub fn (b Bare) str() string {
mut str := typeof(b).name + '{\n' mut str := typeof(b).name + '{\n'
str += ' text: \'$b.text\'\n' str += ' text: \'$b.text\'\n'
@ -160,12 +171,16 @@ pub fn (b Bare) str() string {
return str 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 struct Bool {
pub: pub:
text string text string
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `Bool` type.
pub fn (b Bool) str() string { pub fn (b Bool) str() string {
mut str := typeof(b).name + '{\n' mut str := typeof(b).name + '{\n'
str += ' text: \'$b.text\'\n' str += ' text: \'$b.text\'\n'
@ -174,12 +189,16 @@ pub fn (b Bool) str() string {
return str 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 struct Number {
pub: pub:
text string text string
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `Number` type.
pub fn (n Number) str() string { pub fn (n Number) str() string {
mut str := typeof(n).name + '{\n' mut str := typeof(n).name + '{\n'
str += ' text: \'$n.text\'\n' str += ' text: \'$n.text\'\n'
@ -188,12 +207,16 @@ pub fn (n Number) str() string {
return str 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 struct Date {
pub: pub:
text string text string
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `Date` type.
pub fn (d Date) str() string { pub fn (d Date) str() string {
mut str := typeof(d).name + '{\n' mut str := typeof(d).name + '{\n'
str += ' text: \'$d.text\'\n' str += ' text: \'$d.text\'\n'
@ -202,6 +225,8 @@ pub fn (d Date) str() string {
return str 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 struct Time {
pub: pub:
text string text string
@ -209,6 +234,7 @@ pub:
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `Time` type.
pub fn (t Time) str() string { pub fn (t Time) str() string {
mut str := typeof(t).name + '{\n' mut str := typeof(t).name + '{\n'
str += ' text: \'$t.text\'\n' str += ' text: \'$t.text\'\n'
@ -218,6 +244,8 @@ pub fn (t Time) str() string {
return str 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 struct DateTime {
pub: pub:
text string text string
@ -226,6 +254,7 @@ pub:
time Time time Time
} }
// str returns the `string` representation of the `DateTime` type.
pub fn (dt DateTime) str() string { pub fn (dt DateTime) str() string {
mut str := typeof(dt).name + '{\n' mut str := typeof(dt).name + '{\n'
str += ' text: \'$dt.text\'\n' str += ' text: \'$dt.text\'\n'
@ -236,11 +265,13 @@ pub fn (dt DateTime) str() string {
return str return str
} }
// EOF is the data representation of the end of the TOML document.
pub struct EOF { pub struct EOF {
pub: pub:
pos token.Position pos token.Position
} }
// str returns the `string` representation of the `EOF` type.
pub fn (e EOF) str() string { pub fn (e EOF) str() string {
mut str := typeof(e).name + '{\n' mut str := typeof(e).name + '{\n'
str += ' pos: $e.pos\n' str += ' pos: $e.pos\n'

2
vlib/toml/checker/checker.v
View File

@ -14,6 +14,8 @@ pub struct Checker {
scanner &scanner.Scanner scanner &scanner.Scanner
} }
// check checks the `ast.Value` and all it's children
// for common errors.
pub fn (c Checker) check(n &ast.Value) ? { pub fn (c Checker) check(n &ast.Value) ? {
walker.walk(c, n) ? walker.walk(c, n) ?
} }

2
vlib/toml/input/input.v
View File

@ -11,6 +11,8 @@ pub:
file_path string // '/path/to/file.toml' 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() ? { pub fn (c Config) validate() ? {
if c.file_path != '' && c.text != '' { if c.file_path != '' && c.text != '' {
error(@MOD + '.' + @FN + error(@MOD + '.' + @FN +

22
vlib/toml/parser/parser.v
View File

@ -9,9 +9,7 @@ import toml.util
import toml.token import toml.token
import toml.scanner import toml.scanner
// Scanner contains the necessary fields for the state of the scan process. // Parser contains the necessary fields for keeping the state of the parsing 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`.
pub struct Parser { pub struct Parser {
pub: pub:
config Config config Config
@ -31,8 +29,8 @@ mut:
ast_root &ast.Root = &ast.Root{} ast_root &ast.Root = &ast.Root{}
} }
// Config is used to configure a Scanner instance. // Config is used to configure a Parser instance.
// Only one of the fields `text` and `file_path` is allowed to be set at time of configuration. // `run_checks` is used to en- or disable running of the strict `checker.Checker` type checks.
pub struct Config { pub struct Config {
pub: pub:
scanner &scanner.Scanner 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 // 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 // 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. // 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 { 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)}') util.printdbg(@MOD + '.' + @STRUCT + '.' + @FN, 'locating "$p.root_map_key" in map ${ptr_str(p.root_map)}')
mut t := &map[string]ast.Value{} 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) 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) { pub fn (mut p Parser) sub_table_key(key string) (string, string) {
mut ks := key.split('.') mut ks := key.split('.')
last := ks.last() last := ks.last()
@ -140,10 +141,11 @@ pub fn (mut p Parser) sub_table_key(key string) (string, string) {
return ks.join('.'), last return ks.join('.'), last
} }
// find_sub_table returns a reference to a map if found in `table` given a "dotted" key ('aa.bb.cc'). // 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_in_table will // 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 // 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. // 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 { pub fn (mut p Parser) find_sub_table(key string) ?&map[string]ast.Value {
mut ky := p.root_map_key + '.' + key mut ky := p.root_map_key + '.' + key
if p.root_map_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) 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 // 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 // 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. // 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 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 { pub fn (mut p Parser) sub_key() ?string {
util.printdbg(@MOD + '.' + @STRUCT + '.' + @FN, 'parsing nested key...') util.printdbg(@MOD + '.' + @STRUCT + '.' + @FN, 'parsing nested key...')
key := p.key() ? key := p.key() ?

10
vlib/toml/toml.v
View File

@ -67,9 +67,9 @@ pub fn parse_text(text string) ?Doc {
} }
} }
// parse parses the TOML document provided in `input`. // parse parses the TOML document provided in `toml`.
// parse automatically try to determine if the type of `input` is a file or text. // parse automatically try to determine if the type of `toml` is a file or text.
// For explicit parsing of input see `parse_file` or `parse_text`. // For explicit parsing of input types see `parse_file` or `parse_text`.
pub fn parse(toml string) ?Doc { pub fn parse(toml string) ?Doc {
mut input_config := input.Config{} mut input_config := input.Config{}
if !toml.contains('\n') && os.is_file(toml) { 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 { pub fn (d Doc) to_json() string {
return d.ast.to_json() return d.ast.to_json()
} }
@ -119,7 +119,7 @@ fn (d Doc) ast_to_any(value ast.Value) Any {
return Any(Null{}) return Any(Null{})
// TODO decide this // TODO decide this
// panic(@MOD + '.' + @STRUCT + '.' + @FN + // panic(@MOD + '.' + @STRUCT + '.' + @FN +
// ' failed converting "$date_str" to iso8601: $err') // ' failed converting "$date_str" to rfc3339: $err')
} }
} else if value is ast.Time { } else if value is ast.Time {
time_str := (value as ast.Time).text time_str := (value as ast.Time).text