NAME
DMS::Parser::XS - XS (C-backed) parser for DMS, a data syntax with strong typing, ordered maps, multi-line heredocs, and front-matter metadata
SYNOPSIS
use DMS::Parser::XS;
my $src = do { local $/; <STDIN> };
my $doc = DMS::Parser::XS::decode($src); # hashref / arrayref / scalar / blessed type
# Full Document (with meta, comments)
my $full = DMS::Parser::XS::decode_document($src);
# Lite mode — no comment/form tracking, fastest path
my $body = DMS::Parser::XS::decode_lite($src);
# Round-trip encode (pure-Perl emitter, shared with DMS::Parser)
my $dms = DMS::Parser::XS::encode($full);
# Fast canonical emit via C-side lite emitter
my $canonical = DMS::Parser::XS::encode_lite($full);DESCRIPTION
DMS::Parser::XS is the XS binding to the C reference parser (https://gitlab.com/flo-labs/pub/dms-c). It exposes the same public API as DMS::Parser (pure-Perl) so the two backends are drop-in interchangeable — the Document shape, type sentinels, and emitter are identical.
Typical speedup versus the pure-Perl parser: ~20x on large documents in lite mode. The C sources (dms.c / dms.h) plus their utf8proc dependency are vendored in the tarball under vendor/dms-c/, so no separate C library installation is required.
FUNCTIONS
decode($src)
Decode a DMS source string. Returns the body value tree (same shape as "decode" in DMS::Parser).
decode_document($src)
Like "decode" but returns a full Document hashref with body, meta, comments, and original_forms.
decode_lite($src)
Like "decode" but skips comment and literal-form tracking. Fastest parse mode; body values are identical to "decode".
decode_lite_document($src)
Like "decode_document" but lite mode.
decode_front_matter($src)
Parse only the front-matter block +++ ... +++. Returns a hashref or undef when the document has no front matter.
decode_document_unordered($src)
Like "decode_document" but converts all body tables to DMS::Parser::UnorderedTable (plain hashrefs, no insertion-order tracking).
encode($doc)
Re-emit the Document as DMS source. Delegates to DMS::Parser::Emitter. Preserves comments and original literal forms.
encode_lite($doc)
Emit canonical DMS source. Uses the C-side lite emitter when available, falling back to DMS::Parser::Emitter.
decode_t1($src)
Decode a tier-1 DMS document (_dms_tier: 1 front-matter key). Returns a hashref with keys tier, imports, body, decorators, and _raw_doc, matching the shape returned by "decode_t1" in DMS::Parser::Tier1.
The decorator-scanning and import-validation logic is implemented in pure Perl (DMS::Parser::Tier1); the tier-0 sub-parse is routed through the XS C parser for the performance benefit. Dies with "line:col: message\n" on parse or validation error.
DEPENDENCIES
Requires a C compiler at build time. The C DMS parser sources and utf8proc are bundled under vendor/dms-c/ — no external C library is needed.
SEE ALSO
DMS::Parser (pure-Perl backend), DMS::Parser::Emitter, https://gitlab.com/flo-labs/pub/dms (language spec), https://gitlab.com/flo-labs/pub/dms-c (C parser)
AUTHOR
Filip Lopes
LICENSE
Dual-licensed under the Apache License 2.0 and the MIT license, at your option.