Every public type, function and value. Signatures are the ones the compiler writes; the notes are the documentation comments in the source.
moonbitstack/moontoml
TOML 1.0.0: read a document into a Json tree, and write a Json tree back as TOML.
error Refused
Why a document was refused.
Redefined is the rule that matters most: §1 says a key may be defined only once, and so may a table, so a second definition is an error rather than a value that wins. It is the rule that makes a TOML file safe to append to.
pub(all) suberror Refused {
Unexpected(At, Char)
Truncated(At)
BadEscape(At)
BadNumber(At)
BadDate(At)
Redefined(At, String)
Trailing(At)
TooDeep(At)
BadUtf8(At)
}
pub fn Refused::at(Self) -> At
Where the refusal happened.
Every variant carries a position, so a caller reporting a line does not have to match all nine of them to get at it.
struct At
Where in the source something is: the offset in code units, and the line and column a person counts from one.
pub(all) struct At {
at : Int32
line : Int32
column : Int32
}
struct Flavor
How a document is read.
The preset is strict. Build another with Flavor::new, or update one in place with { ..strict, depth: 64 }.
There is no knob for a repeated key. TOML 1.0.0 §1 makes redefinition an error, not a policy, so making it configurable would be offering to read a document the format says is not one.
pub(all) struct Flavor {
depth : Int32
}
pub fn Flavor::new(depth? : Int32) -> Self
A flavor by name, every knob with the preset's value.
struct Real
A float, and the text it was written as.
TOML spells one number many ways — 1e06, 1000000.0, 1_000_000.0 — and a document read and written again should not turn one spelling into another. The text is kept whenever the source had one and it is also a JSON spelling, since that is what a tree of Json can carry; a float built in code has none and is written from its value.
pub(all) struct Real {
value : Double
repr : String?
}
pub fn Real::new(Double) -> Self
A float from its value alone.
enum Value
A TOML value, kind for kind.
A Json tree has no date-time and only one number, so loads reads a timestamp into text and a 64-bit integer into a double. decode reads the same document and keeps what the format says it is, which is what writing it back without guessing needs.
pub(all) enum Value {
String(String)
Integer(Int64)
Float(Real)
Boolean(Bool)
Datetime(@moondate.Moment)
Array(Array[Value])
Table(Map[String, Value])
}
pub fn Value::array(Array[Self]) -> Self
An array value.
pub fn Value::boolean(Bool) -> Self
A boolean value.
pub fn Value::integer(Int64) -> Self
An integer value.
pub fn Value::string(String) -> Self
A string value.
pub fn Value::table(Map[String, Self]) -> Self
A table value, which is what a document is.
pub fn Value::to_json(Self) -> @json.Json
Functions
pub fn decode(StringView, flavor? : Flavor) -> Value raise Refused
The document in src, kind for kind.
TOML defines one document rather than a stream, so there is no plural form of this. This is the reading that keeps every distinction the format makes: a date is a date and not text, and an integer is 64 bits and not a double.
pub fn decode_bytes(BytesView, flavor? : Flavor, bom? : Bool) -> Value raise Refused
The document in src, decoded as UTF-8.
TOML 1.0.0 §1 says a file is UTF-8 and does not allow a byte-order mark; bom skips one anyway, because an editor on Windows writes it and refusing the file helps nobody. Pass bom=false to hold the format to its word.
pub fn dump(@json.Json, sort? : Bool) -> Bytes
The same, as UTF-8 bytes.
pub fn dumps(@json.Json, sort? : Bool) -> String
Write a Json tree as a TOML document.
Tables go under their own headers and scalars stay at the level they are on, so the output reads like a configuration file someone wrote rather than one a program emitted. An array of tables is written as [[…]] when every one of its elements is a table, and inline otherwise, which is the only honest choice: TOML has no way to spell an array mixing tables with scalars across headers.
sort orders keys by name; off, they keep the order the tree has. A document read by this module and written again carries the same values, but not necessarily the same layout — TOML can spell the same tree several ways.
A Json tree says "string" for what may have been a date-time, so this leans on the spelling: a string that is a date-time is written as one. encode writes a Value and needs no such guess.
pub fn encode(Value, sort? : Bool) -> String
Write a tree of Value as a TOML document.
Each value keeps the kind it has: a String is quoted even when it reads like a date, an Integer is written as the 64 bits it holds, and a Datetime is written bare, because turning it into a quoted string would change what it is.
pub fn encode_bytes(Value, sort? : Bool) -> Bytes
The same, as UTF-8 bytes.
pub fn load(BytesView, flavor? : Flavor, bom? : Bool) -> @json.Json raise Refused
The document in src, decoded as UTF-8, as a tree of Json.
TOML 1.0.0 §1 says a file is UTF-8 and does not allow a byte-order mark; bom skips one anyway, because an editor on Windows writes it and refusing the file helps nobody. Pass bom=false to hold the format to its word.
pub fn loads(StringView, flavor? : Flavor) -> @json.Json raise Refused
The document in src, as a tree of Json.
A date-time comes out as its RFC 3339 text and an integer as a Json number, because a Json tree has no place to keep either apart; decode is the reading that keeps them.
Values
pub let depth : Int32
How deep a document may nest.
500 is the preset: deep enough for real configuration, shallow enough that a hostile document cannot run the stack out.
pub let strict : Flavor
The preset.