dms-parser 0.5.0

data/lib/dms/types.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Dms
+  # Marker subclass of Hash for unordered tables (SPEC §"Unordered tables").
+  # Built only by `Dms.decode_document_unordered` /
+  # `Dms.decode_lite_document_unordered` (and the `--ignore-order` CLI flag).
+  # Iteration order is **arbitrary** — keys are shuffled at end-of-build so
+  # callers cannot accidentally depend on insertion order.
+  #
+  # Full-mode `Dms.encode` raises a `RuntimeError` on any tree containing an
+  # `UnorderedHash`; lite-mode `Dms.encode_lite` accepts them and emits in
+  # whatever iteration order they expose.
+  class UnorderedHash < Hash; end
+
+  # Raised by `Dms.decode*` on malformed source. Carries the (line,
+  # column) of the first offending byte plus the bare error text.
+  class DecodeError < StandardError
+    attr_reader :line, :column, :text
+
+    def initialize(line, column, message)
+      @line   = line
+      @column = column
+      @text   = message
+      super("#{line}:#{column}: #{message}")
+    end
+  end
+
+  # Deprecated alias. Use `Dms::DecodeError`. Referencing this constant
+  # emits a one-shot warning via `deprecate_constant`.
+  ParseError = DecodeError
+  deprecate_constant :ParseError
+
+  # Raised by `Dms.encode` (and `Dms.encode_lite`) when the value tree
+  # cannot be emitted — e.g. full-mode round-trip refusing a Document
+  # that contains a `Dms::UnorderedHash`. See SPEC §encode.
+  class EncodeError < StandardError; end
+
+  # Marker classes for datetime variants. The inner string is already
+  # spec-validated by the parser.
+  class LocalDate
+    attr_reader :value
+    def initialize(value); @value = value; end
+    def ==(o); o.is_a?(LocalDate) && @value == o.value; end
+    alias eql? ==
+    def hash; [LocalDate, @value].hash; end
+    def to_s; @value; end
+  end
+
+  class LocalTime
+    attr_reader :value
+    def initialize(value); @value = value; end
+    def ==(o); o.is_a?(LocalTime) && @value == o.value; end
+    alias eql? ==
+    def hash; [LocalTime, @value].hash; end
+    def to_s; @value; end
+  end
+
+  class LocalDateTime
+    attr_reader :value
+    def initialize(value); @value = value; end
+    def ==(o); o.is_a?(LocalDateTime) && @value == o.value; end
+    alias eql? ==
+    def hash; [LocalDateTime, @value].hash; end
+    def to_s; @value; end
+  end
+
+  class OffsetDateTime
+    attr_reader :value
+    def initialize(value); @value = value; end
+    def ==(o); o.is_a?(OffsetDateTime) && @value == o.value; end
+    alias eql? ==
+    def hash; [OffsetDateTime, @value].hash; end
+    def to_s; @value; end
+  end
+
+  # A captured comment.
+  # `content` is raw source incl. delimiters.
+  # `kind` is :line or :block.
+  Comment = Struct.new(:content, :kind)
+
+  # An attached comment.
+  # `position` is :leading, :trailing, :floating, or :inner.
+  # `path` is an Array of String (key) / Integer (index).
+  AttachedComment = Struct.new(:comment, :position, :path)
+
+  # Round-trip original-form records (SPEC §to_dms).
+  HeredocModifierCall = Struct.new(:name, :args)
+
+  class StringForm
+    attr_reader :kind, :flavor, :label, :modifiers
+    def initialize(kind, flavor: nil, label: nil, modifiers: nil)
+      @kind = kind; @flavor = flavor; @label = label; @modifiers = modifiers
+    end
+    def self.basic;    new(:basic); end
+    def self.literal;  new(:literal); end
+    def self.heredoc(flavor, label, modifiers)
+      new(:heredoc, flavor: flavor, label: label, modifiers: modifiers.to_a)
+    end
+    def ==(o)
+      o.is_a?(StringForm) && @kind == o.kind && @flavor == o.flavor &&
+        @label == o.label && @modifiers == o.modifiers
+    end
+    alias eql? ==
+    def hash; [StringForm, @kind, @flavor, @label, @modifiers].hash; end
+  end
+
+  class OriginalLiteral
+    attr_reader :kind, :integer_lit, :string_form
+    def initialize(kind, integer_lit: nil, string_form: nil)
+      @kind = kind; @integer_lit = integer_lit; @string_form = string_form
+    end
+    def self.integer(lit); new(:integer, integer_lit: lit); end
+    def self.string(form); new(:string, string_form: form); end
+  end
+
+  # Parsed DMS document.
+  class Document
+    attr_accessor :meta, :body, :comments, :original_forms
+
+    def initialize(meta, body, comments = [], original_forms = [])
+      @meta = meta
+      @body = body
+      @comments = comments
+      @original_forms = original_forms
+    end
+
+    def front_matter; @meta; end
+  end
+end

data/lib/dms.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+# DMS decoder/encoder - Ruby port of the Rust/Python reference.
+#
+# Public API (SPEC v0.14):
+#   Dms.decode(src)            -> body value
+#   Dms.decode_document(src)   -> Document(body, meta, comments, original_forms)
+#   Dms.encode(doc)            -> DMS source string (round-trip emitter)
+#   Dms.decode_lite(src)       -> body value, lite mode
+#   Dms.encode_lite(doc)       -> DMS source string, canonical-form emit
+#
+# Legacy aliases (deprecated, removed next release):
+#   Dms.parse / Dms.parse_document / Dms.parse_lite / Dms.to_dms /
+#   Dms.to_dms_lite — emit a one-shot deprecation warning and forward.
+#
+# Spec: https://gitlab.com/flo-labs/pub/dms/-/blob/main/SPEC.md
+
+require "dms/types"
+require "dms/parser"
+require "dms/emitter"
+require "dms/tier1"
+
+module Dms
+  VERSION = "0.3.0"
+
+  # Capability flag — this port ships lite-mode decode + lite-mode encode_lite.
+  # See SPEC §Decoding modes — full and lite.
+  SUPPORTS_LITE_MODE = true
+
+  # Capability flag — this port ships unordered-table decode mode.
+  # See SPEC §Unordered tables.
+  SUPPORTS_IGNORE_ORDER = true
+
+  # ---------- Canonical decode/encode (SPEC v0.14) ----------
+
+  # Decode a DMS source string and return the body value tree.
+  def self.decode(src)
+    Parser.parse_document(src).body
+  end
+
+  # Decode a DMS source string and return the full Document
+  # (body, meta, comments, original_forms).
+  def self.decode_document(src)
+    Parser.parse_document(src)
+  end
+
+  # Lite-mode decode: same data tree, no comment AST, no original_forms.
+  # Not suitable for `encode` round-trip. SPEC §Decoding modes — full and lite.
+  def self.decode_lite(src)
+    Parser.parse_lite_document(src).body
+  end
+
+  def self.decode_lite_document(src)
+    Parser.parse_lite_document(src)
+  end
+
+  # Unordered full-mode decode (SPEC §"Unordered tables"). Body tables are
+  # built as `Dms::UnorderedHash` (a Hash subclass) with keys shuffled at
+  # end-of-build so callers cannot rely on insertion order. Front matter
+  # remains insertion-ordered.
+  #
+  # `Dms.encode` (full-mode round-trip) refuses Documents containing
+  # unordered tables — use `Dms.encode_lite` for canonical emit.
+  def self.decode_document_unordered(src)
+    Parser.parse_document_unordered(src)
+  end
+
+  # Unordered lite-mode decode. The fastest read-only path: no comment AST,
+  # no original_forms, body tables built as `Dms::UnorderedHash` with
+  # shuffled key order. SPEC §"Unordered tables".
+  def self.decode_lite_document_unordered(src)
+    Parser.parse_lite_document_unordered(src)
+  end
+
+  # Front-matter-only decode (SPEC §Front-matter-only decode). Scans
+  # leading trivia + `+++` + contents + `+++` and stops; the body is
+  # not tokenized. Returns the front-matter Hash (empty when the FM
+  # block is empty), or nil when the document has no FM at all.
+  # In-FM diagnostics are byte-identical to a full decode and raise
+  # `Dms::DecodeError`. Required at tier 0 — there is no capability
+  # flag for this entry point.
+  def self.decode_front_matter(src)
+    Parser.parse_front_matter_only(src)
+  end
+
+  # Encode a parsed Document back to DMS source (SPEC §encode). Refuses
+  # Documents containing `Dms::UnorderedHash` — use `encode_lite` for
+  # canonical emit of unordered Documents.
+  def self.encode(doc)
+    Emitter._encode_full(doc)
+  end
+
+  # Canonical-form emit. Drops comments and original_forms. Accepts
+  # both full-mode and lite-mode Documents. SPEC §encode.
+  def self.encode_lite(doc)
+    Emitter._encode_lite(doc)
+  end
+
+  # Capability flag (SPEC §"Unordered tables"). True iff this port ships
+  # `decode_document_unordered` / `decode_lite_document_unordered` with
+  # spec-correct semantics. Callers probe before opting in.
+  def self.supports_ignore_order
+    true
+  end
+
+  # ---------- Deprecated aliases (parse/to_dms era, SPEC < 0.14) ----------
+  #
+  # Removed in the next release. Keep dispatch trivial — they exist
+  # purely as a compatibility shim over the canonical names.
+
+  @_deprecation_warned = {}
+
+  def self._warn_deprecated(old, new_name)
+    return if @_deprecation_warned[old]
+    @_deprecation_warned[old] = true
+    warn "[DEPRECATION] `Dms.#{old}` is deprecated and will be removed " \
+         "in the next release. Use `Dms.#{new_name}` instead.",
+         uplevel: 2
+  end
+
+  def self.parse(src)
+    _warn_deprecated(:parse, :decode)
+    decode(src)
+  end
+
+  def self.parse_document(src)
+    _warn_deprecated(:parse_document, :decode_document)
+    decode_document(src)
+  end
+
+  def self.parse_lite(src)
+    _warn_deprecated(:parse_lite, :decode_lite)
+    decode_lite(src)
+  end
+
+  def self.parse_lite_document(src)
+    _warn_deprecated(:parse_lite_document, :decode_lite_document)
+    decode_lite_document(src)
+  end
+
+  def self.parse_document_unordered(src)
+    _warn_deprecated(:parse_document_unordered, :decode_document_unordered)
+    decode_document_unordered(src)
+  end
+
+  def self.parse_lite_document_unordered(src)
+    _warn_deprecated(:parse_lite_document_unordered,
+                     :decode_lite_document_unordered)
+    decode_lite_document_unordered(src)
+  end
+
+  def self.to_dms(doc)
+    _warn_deprecated(:to_dms, :encode)
+    encode(doc)
+  end
+
+  def self.to_dms_lite(doc)
+    _warn_deprecated(:to_dms_lite, :encode_lite)
+    encode_lite(doc)
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: dms-parser
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Filip Lopes
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-05 00:00:00.000000000 Z
+dependencies: []
+description: Ruby parser for DMS, a data syntax with strong typing, ordered maps,
+  multi-line heredocs, and front-matter metadata.
+email:
+executables:
+- dms-encoder
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE-APACHE
+- LICENSE-MIT
+- README.md
+- bin/dms-encoder
+- lib/dms.rb
+- lib/dms/emitter.rb
+- lib/dms/parser.rb
+- lib/dms/tier1.rb
+- lib/dms/types.rb
+homepage: https://gitlab.com/flo-labs/pub/dms-rb
+licenses:
+- MIT OR Apache-2.0
+metadata:
+  source_code_uri: https://gitlab.com/flo-labs/pub/dms-rb
+  bug_tracker_uri: https://gitlab.com/flo-labs/pub/dms-rb/-/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby parser for DMS, a data syntax with strong typing, ordered maps, multi-line
+  heredocs, and front-matter metadata.
+test_files: []