tiny.preserves.text

1/// The error both text readers return when input nests past `maximum`. Code calling either text2/// reader matches on it, so input nested too deeply stands apart from other bad input. The error3/// set holds one tag, `NestingLimitExceeded`, which also belongs to `ParseError` and to the text4/// reader's `DecodeError`.5pub const Error = error{NestingLimitExceeded};

1/// The deepest nesting the text readers accept: 256 levels. Tests and callers that build deep input2/// read it for that bound. The top value sits at level 0, and each record, sequence, set,3/// dictionary, annotation and `#:` embedded value adds a level. Opening a level at 256 fails, so4/// 256 nested levels read and 257 fail. `parse` and `decode` stop at the same depth for the same5/// text.6pub const maximum: Level = 256;

1pub const text = @import("text/root.zig");

1//! A text syntax for values, with two readers and two writers. People write and read this form by2//! hand, so a reader meets text that a person typed. A caller needs to know which text each reader3//! accepts, what the decoded value owns, and what stops deeply nested input. Each level of nesting4//! costs the readers a level of recursion, and text can nest as deep as its length allows.5//! Hand-written text lists set elements and dictionary entries in any order, and can repeat them.6//! The syntax is the text syntax of the [Preserves](https://preserves.dev/) data language, which7//! the package keeps.8//!9//! Both readers stop at 256 levels of nesting (`max_nesting_depth`), and each record, sequence,10//! set, dictionary, annotation and `#:` embedded value adds a level. Depth is the one bound:11//! neither reader limits input size, item count or memory. Both readers reject a repeated set12//! element or dictionary key. The reader `parse` then sorts sets and dictionaries, and the reader13//! `decode` keeps the written order. The two writers are `encode`, which refuses discards,14//! captures, binds and rest patterns, and `toText`, which writes them. Both readers copy every15//! string they keep, so the decoded value owns all its memory and borrows nothing from the text.16//!17//! `parse` reads `# ` comments, and reads `#:` embedded values into `AnyEmbedded` values. `decode`18//! rejects `# ` comments, and rejects `#:` embedded values whose type is `NoEmbedded` or19//! `AnyEmbedded`. Both readers read a bare token with underscores between digits, such as `1_000`,20//! as a symbol. `encode` writes the symbol `1_000` bare, so `parse` reads it back as a symbol.21//! `encode` writes a `'` inside a quoted symbol as `\'`, `parse` accepts `\'` and `\"` in strings22//! and quoted symbols, and `decode` accepts `\'` in quoted symbols and `\"` in strings, and rejects23//! `\'` in strings and `\"` in quoted symbols with `BadEscape`. `decode` checks strings and symbols24//! as UTF-8, and `parse` returns `InvalidUtf8` for invalid UTF-8 in strings and symbols.25const preserves = @import("../root.zig");26const format = @import("format.zig");27const parser = @import("parser.zig");28const nesting = @import("nesting.zig");29pub const reader = @import("reader.zig");30pub const writer = @import("writer.zig");3132const value_mod = preserves.value;33const embedded_mod = preserves.embedded_mod;34const parse_error_mod = preserves.parse_error;35const integer_mod = preserves.integer_mod;3637/// An embedded value that points to a payload of the host program, with optional functions to38/// compare, hash, free and copy it. Code that builds embedded values for `parse`, `toText` or39/// `Value` names it. It is the type of the embedded values in the text namespace's values. `parse`40/// makes each `#:` embedded value one of these, owning the value it read.41pub const AnyEmbedded = embedded_mod.AnyEmbedded;42/// The value type `parse` returns and `toText` writes: `Value(AnyEmbedded)`. Code that reads data43/// files names it as the value each file decodes to. `Value.Domain` names the type of its embedded44/// values, so a caller can pass it to `decode`.45pub const Value = value_mod.Value(AnyEmbedded);46/// The error set `parse` returns, the same set as `preserves.ParseError`. Code that calls `parse`47/// switches on it.48pub const ParseError = parse_error_mod.ParseError;49pub const NestingError = nesting.Error;50pub const max_nesting_depth = nesting.maximum;51pub const toText = format.toText;52pub const parse = parser.parse;53pub const decode = reader.decode;54pub const encode = writer.encode;