BarkML is a declarative configuration format that is inspired by other languages shuch as toml, hcl and more. It was created initially to be used with operational tools and generative tooling. The language defaults to utf-8 parsing and the language supports self-referential macro replacements.
Control statements are generally used for specifying metadata related to the file, section or blocks. They are assignment statements to any variable starting with $
Syntax:
$<name> = (!<label>)? <value>
Example:
$control_id = !MyProgram 1.0.0
The above example could be a way to define what schema this barkml utilizes. Note schema checking is currently not implemented directly in BarkML, it is on the writer of a tool using BarkML to define and check for a schema.
The top-most grouping of data in BarkML are sections. Sections look identical to sections in TOML. Unlike TOML though BarkML does not allow nested sections. Sections are meant to be global groupings in a configuration file.
Syntax:
[<name>|"<name>"]
<child-statements...>
Example:
[section-a]
foo = "bar"
["section-b"]
foo = "baz"
NOTE: If the use case of the configuration file is to be sent over network or streamed to a service for some reason, the use of sections should be avoided as if the data sent is cutoff it could still result in a valid BarkML file. Instead use blocks as defined below to group statements in this use case
BarkML supports the definition of comments by defining lines starting with # followed by one white space. Any back to back lines with # will be concatenated into a multiline comment.
Syntax:
# <any text without a newline>
# <...>
Example:
# This is a comment in BarkML
BarkML supports grouping and labeling a set of statements as blocks. These blocks can have 0 or more labels associated with them of any value type. If you wish to fetch or refer to a block in a macro or from the walker class the scope id will always be the id + labels all joined with '.'
Syntax:
<id> [<label>] {
<child-statements...>
}
The standard assignment statement will define a single entry of data. Like with control statements a value can be given an optional label as well, this can be useful for declaring types for a value for the tool handling the config file.
Syntax:
[<id> | "<id>"] = (!<label>)? <value>
Examples:
foo = "bar"
"baz" = 3.14
Integers are specified as numerical values and unless provided a suffix will be read as a signed 64-bit number. Numbers can be specified with precision utilizing the following suffices
| Suffix | Precision |
|---|---|
| u8 | Unsigned 8-byte |
| u16 | Unsigned 16-byte |
| u32 | Unsigned 32-byte |
| u64 | Unsigned 64-byte |
| u128 | Unsigned 128-byte |
| i8 | Signed 8-byte |
| i16 | Signed 16-byte |
| i32 | Signed 32-byte |
| i64 | Signed 64-byte |
| i128 | Signed 128-byte |
Examples:
5
-2
5u32
-2i64
Floating point numbers are read by default as 64-byte floating point unless one of the below suffixes are provided. Floating point numbers can be specified with exponents as well.
| Suffix | Precision |
|---|---|
| f32 | 32-byte |
| f64 | 64-byte |
Examples:
3.14
3.14f32
-5.2
5.2e10
5.2e+10
3.1e-10
30.0E+2
BarkML supports inline semantic version declarations. However to prevent collision with floating point numbers, any semantic version must specify at least ..
Examples:
1.0.0
0.1.0-beta.1
0.1.0-prerelease-build.5
BarkML also supports the definition of version requirements. The only exception is that currently the wildcard '*' support is not explicitly supported (it is still inferred when not specifying every part of version). You also must always specify a requirement operator in barkml.
>1.1
^4
~5.3
Strings can be defined either with a single quote or a double quote. Both are effectively parsed identically.
Examples:
'my-string'
"my string value"
BarkML supports storing random byte data via base64 encoded byte strings. To avoid any confusion with what
standard of base64 is used between configuration files, BarkML standardizes on expecting URL Safe with No Padding
base64 data. This rust crate will automatically encode and decode any Vec<u8> data to and from this encoding standard.
Examples:
# binarystring in base64
b'YmluYXJ5c3RyaW5n'
Label values are identifiers prefixed by !. These are primarily used before a value in an assignment statement or control statement, but also can be used by themselves as a symbol value.
Examples:
!MyLabel
BarkML supports the use of multiple identifiers to define boolean values in configuration files
Options for True
- true
- True
- TRUE
- yes
- Yes
- YES
- on
- On
- ON
Options for False
- false
- False
- FALSE
- no
- No
- NO
- off
- Off
- OFF
BarkML also supports multiple identifiers to define a null value
Options
- null
- Null
- NULL
- nil
- Nil
- NIL
- none
- None
- NONE
BarkML supports dynamic arrays, meaning that the type of the sub entry of any array does not
have to match. Arrays are always wrapped in [] and can contain 0 or more values delimited by commas
Example:
[5, 3.14, 'foo']
BarkML also supports the definition of tables
Example:
{
foo = 5,
"bar" = 3.14
}
BarkML supports the use of self referential macros. These macros will at parse time lookup and replace values with a previously defined value. These macro values must reference data via a root path from the top of the configuration file. Macro replacements are full replacements
Example:
version = "1.0.0"
[section]
val = 5
[section-b]
parent-version = m!version
other-val = m!section.val
BarkML also allows the use of macro replacements inside of a string declaration. A macro string
can define one or more replacements by utilizing {} inside of the string
version = "1.0.0"
motd = m'Hello from {version}'
NOTE: Macro strings must only use single quotes
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.