Parsing TOML

Lanexio Parser supports both TOML v1.0.0 and v1.1.0 through a single package. Choose your version explicitly, or use the default (v1.1.0).

Quick start

1. Install the package.

   pnpm

   pnpm add @lanexio/parser-grammar-toml

   npm

   npm install @lanexio/parser-grammar-toml

   yarn

   yarn add @lanexio/parser-grammar-toml

2. Parse a TOML document.

   import { parseToml } from '@lanexio/parser-grammar-toml';
   
   const encoder = new TextEncoder();
   const tree = parseToml(encoder.encode(`
     [server]
     host = "0.0.0.0"
     port = 8080
   
     [database]
     url = "postgres://localhost"
     pool = 10
   `));

Version selection

Use parseToml10 for TOML v1.0.0 syntax and parseToml11 for v1.1.0 constructs like dotted keys in inline tables and hex float literals. parseToml defaults to v1.1.0.

import { parseToml10, parseToml11 } from '@lanexio/parser-grammar-toml';

const v1 = parseToml10(encoder.encode('[table]\nkey = "value"'));
const v2 = parseToml11(encoder.encode('a.b.c = 42'));

Inspecting the tree

Tables become TomlTable nodes, key-value pairs become TomlKvPair nodes, and arrays become TomlArray nodes. Values carry type flags for string, integer, float, boolean, datetime, and array-of-types.

import { TomlKind } from '@lanexio/parser-grammar-toml';

const cursor = tree.cursor();
cursor.gotoFirstChild();

console.log(cursor.current.kind === TomlKind.TomlTable); // true

Escape sequences

TOML 1.1.0 adds the \e escape (ESC character, U+001B) and \xHH byte escape to the existing \b, \t, \n, \f, \r, \", \\, \uXXXX, and \UXXXXXXXX escapes from TOML 1.0.0.

# All valid escape sequences
string_val = "Tab:\t Newline:\n Quote:\" Backslash:\\"
hex_val = "\x48\x65\x6C\x6C\x6F"           # "Hello" (TOML 1.1.0 only)
esc_val = "\e"                               # ESC character (TOML 1.1.0 only)
unicode = "Hello"   # "Hello"
big_unicode = "\U0001F600"                   # Unicode beyond BMP

Version-aware parsing of escapes

The \xHH escape is only valid in TOML 1.1.0 mode. In TOML 1.0.0 mode, \x is a reserved escape sequence and produces an Error node.

The \e escape is valid in both TOML 1.0.0 and 1.1.0 per the toml-test reference suite.

import { parseToml10, parseToml11 } from '@lanexio/parser-grammar-toml';

const bytes = new TextEncoder();

// \xHH accepted in 1.1.0, rejected in 1.0.0
const v11 = parseToml11(bytes.encode('val = "\\x48"'));
console.log(v11.root.hasError); // false

const v10 = parseToml10(bytes.encode('val = "\\x48"'));
console.log(v10.root.hasError); // true

// \e accepted in both versions
const ev11 = parseToml11(bytes.encode('val = "\\e"'));
console.log(ev11.root.hasError); // false

const ev10 = parseToml10(bytes.encode('val = "\\e"'));
console.log(ev10.root.hasError); // false

Escape sequence reference

Escape	Code Point	Description	TOML Version
\b	U+0008	Backspace	1.0.0+
\t	U+0009	Tab	1.0.0+
\n	U+000A	Line Feed	1.0.0+
\f	U+000C	Form Feed	1.0.0+
\r	U+000D	Carriage Return	1.0.0+
\"	U+0022	Quotation Mark	1.0.0+
\\	U+005C	Backslash	1.0.0+
\e	U+001B	Escape (ESC)	1.0.0+
\xHH	varies	Byte escape (2 hex digits)	1.1.0+
\uXXXX	U+0000-U+FFFF	Unicode (4 hex digits)	1.0.0+
\UXXXXXXXX	U+0000-U+10FFFF	Unicode (8 hex digits)	1.0.0+

See also

• TOML reference page
• TOML conformance