/ 
DMS-Parser-0.5.3
/ DMS::Parser

NAME

DMS::Parser - Pure-Perl parser for DMS, a data syntax with strong typing, ordered maps, multi-line heredocs, and front-matter metadata

SYNOPSIS

use DMS::Parser;

my $src = do { local $/; <STDIN> };
my $doc = DMS::Parser::decode($src);

# Keep metadata and comments
my $full = DMS::Parser::decode_document($src);

# Tier-1 (decorator-aware) parse
my $t1 = DMS::Parser::decode_t1($src);

# Round-trip via the emitter
use DMS::Parser::Emitter;
print DMS::Parser::Emitter::encode($full);

DESCRIPTION

DMS (Data Meta Syntax) is a config and data format. This module is the pure-Perl reference parser. It produces native Perl values plus a small set of blessed type sentinels for DMS scalars that do not map cleanly to Perl bare scalar types (booleans, integer-vs-float distinction, dates).

For the language specification see https://gitlab.com/flo-labs/pub/dms.

FUNCTIONS

decode($src)

Decode a DMS source string. Returns a Perl value tree where:

  • Tables become HASH references (insertion-ordered via Tie::IxHash).

  • Lists become ARRAY references.

  • Strings become plain Perl scalars.

  • DMS scalars without a clean Perl analogue become blessed type sentinels (see "TYPE SENTINELS").

Throws on parse error with a line:col: message diagnostic.

decode_document($src)

Like "decode" but returns a Document hashref with keys body, meta, comments, and original_forms. Needed for full round-trip emit via DMS::Parser::Emitter.

decode_lite($src)

Like "decode" but skips comment and literal-form tracking. ~2x faster on large documents. Body values are identical to decode.

decode_lite_document($src)

Like "decode_document" but lite mode (no comment/form tracking).

decode_front_matter($src)

Parse only the front-matter block +++ ... +++. Returns a hashref or undef when the document has no front matter.

decode_t1($src)

Tier-1 parse (decorator-aware). Returns a hashref with keys tier, imports, body, decorators, and _raw_doc. See DMS::Parser::Tier1 for the full schema.

TYPE SENTINELS

The following blessed classes are returned for DMS scalar types that have no clean Perl analogue. All are blessed scalar refs (one allocation per value).

DMS::Parser::Bool

DMS true / false. value() returns 1 or 0.

DMS::Parser::Integer

DMS integer. On 64-bit Perl stored as a native IV. Methods: value(), bstr() (decimal string), is_neg().

DMS::Parser::Float

DMS float. value() returns the NV.

DMS::Parser::LocalDate

DMS local date (e.g. 2024-01-15). value() returns the string.

DMS::Parser::LocalTime

DMS local time (e.g. 14:30:00). value() returns the string.

DMS::Parser::LocalDateTime

DMS local date-time (e.g. 2024-01-15T14:30:00). value() returns the string.

DMS::Parser::OffsetDateTime

DMS offset date-time (e.g. 2024-01-15T14:30:00Z). value() returns the string.

DMS::Parser::Index

Path-segment marker distinguishing list-index steps from string-key steps in comment path arrays. value() returns the integer index.

DMS::Parser::UnorderedTable

Marker class for body tables from the *_unordered entry points. Underlying storage is a plain hashref (no Tie::IxHash). encode (full mode) refuses to round-trip a Document containing this type; use encode_lite.

SEE ALSO

AUTHOR

Filip Lopes

LICENSE

Dual-licensed under the Apache License 2.0 and the MIT license, at your option.