/ 
DMS-Parser-0.5.3
/ DMS::Parser::Tier1

NAME

DMS::Parser::Tier1 - Tier-1 DMS decoder: decorator calls, imports, sigil lexing

SYNOPSIS

# Typically called via the high-level wrapper:
use DMS::Parser;
my $result = DMS::Parser::decode_t1($src);
# $result->{tier}       — 0 or 1
# $result->{imports}    — arrayref of ImportSpec hashrefs
# $result->{body}       — value tree (same shape as decode())
# $result->{decorators} — arrayref of decorator entry hashrefs

# Internal helpers (advanced use):
use DMS::Parser::Tier1;
my $imports = DMS::Parser::Tier1::extract_imports($fm_hashref);
my ($clean_body, $raw_decs) = DMS::Parser::Tier1::scan_body($body_text, $imports);

DESCRIPTION

DMS::Parser::Tier1 implements the tier-1 DMS decoder. Tier-1 documents carry an _dms_tier: 1 key in their front matter and may contain decorator calls — sigil-prefixed annotations attached to values at leading, inner, trailing, or flow-inner positions.

This module is internal-ish: most callers should use DMS::Parser::decode_t1 rather than calling these helpers directly. The public functions are documented here for integrators who need low-level access to the sigil lexer or import extractor.

FUNCTIONS

decode_t1($src)

Main entry point. Parses $src as a tier-0 or tier-1 DMS document. Returns a hashref:

  • tier — integer 0 or 1.

  • imports — arrayref of ImportSpec hashrefs (empty for tier-0 docs). Each ImportSpec has keys dialect, version, ns, bind, allow, deny, alias.

  • body — the decoded value tree (same shape as DMS::Parser::decode).

  • decorators — arrayref of decorator entry hashrefs, each with path, calls (hashref of sigil → arrayref of call records), and comments.

  • _raw_doc — the underlying tier-0 Document (for callers that need the full Document including front matter and comments).

Dies with a line:col: message diagnostic on parse or validation error.

extract_imports($meta_hashref)

Extract and validate the _dms_imports list from a parsed front-matter hashref. Returns an arrayref of ImportSpec hashrefs. Dies on validation error (bad semver, binding collision, invalid sigil, etc.).

scan_body($body_src, $imports, $line_offset)

Scan the body source text for decorator calls. Returns ($clean_body, $raw_decs) where $clean_body has all decorator tokens removed (safe to feed to the tier-0 parser) and $raw_decs is an arrayref of raw decorator records.

is_sigil_char($char)

Returns true if $char is in the tier-0 reserved ASCII decorator sigil set (! @ $ % ^ & * | ~ ` . , > < ; ? =).

resolve_call($sigil, $ns, $fn_name, $imports)

Resolve a decorator call through the import table. Returns ($family, $canonical_fn). Dies on unknown namespace, ambiguous family, or deny-listed function.

SEE ALSO

DMS::Parser, DMS::Parser::Emitter, https://gitlab.com/flo-labs/pub/dms

AUTHOR

Filip Lopes

LICENSE

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