dms-parser 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8c14f1d20d52d7187a1d070cd97a73489c7ecf26d33f36e1b7caec2800e5ebf7
+  data.tar.gz: c23cd13f0f751281b72245f2ae5c4193b705c44ffc7154208146d2af06535bfd
+SHA512:
+  metadata.gz: e54215e05be86f064095579e879b0a45518b2b221dfea42d0c2314bce3f45863ba2be8098f460ebd82acd5e1387339b280ddb7718271f3f3fd0e61c42fec2999
+  data.tar.gz: aa9925ba49da2e63580c171a6d08f91db92ad5b4a6a5623fcca75ac8a26ef21102935ebed7323069f16cc3d03f01493f98a4cc5636fb7625ed492d402c7523a5

data/LICENSE-APACHE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filip Lopes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,166 @@
+<p align="center"><a href="https://gitlab.com/flo-labs/pub/dms"><img src="assets/logo.png" alt="DMS" width="120"></a></p>
+
+# dms-rb
+
+Ruby parser for **[DMS](https://gitlab.com/flo-labs/pub/dms)**, a data syntax with strong typing, ordered maps,
+multi-line heredocs, and front-matter metadata.
+
+Two gems live in this repo, both with the same Ruby API and value shape:
+
+| gem    | implementation                       | when to use                          |
+| ------ | ------------------------------------ | ------------------------------------ |
+| `dms`  | pure Ruby                            | portable; no C toolchain required    |
+| `dms-c`| C extension wrapping the dms-c decoder | hot paths; ~2× faster than pure Ruby |
+
+## Install
+
+```sh
+gem install dms          # pure Ruby
+gem install dms-c        # native (C) extension, same API
+```
+
+## Usage
+
+```ruby
+require "dms"            # or:  require "dms_c"
+
+src = File.read("config.dms")
+
+# Body-only (drops front matter and comments after decode).
+body = Dms.decode(src)   # or:  DmsC.decode(src)
+
+# Full document (preserves comments + literal forms for encode round-trip).
+doc = Dms.decode_document(src)
+doc.meta              # Hash | nil  — nil when there is no `+++` block
+doc.body              # decoded root value
+doc.comments          # Array of Dms::AttachedComment
+doc.original_forms    # Array of [path, Dms::OriginalLiteral]
+
+# Re-emit DMS source.
+output = Dms.encode(doc)
+```
+
+> **Migrating from `parse`/`to_dms`?** SPEC v0.14 renamed the canonical
+> entry points. The old names (`Dms.parse`, `Dms.parse_document`,
+> `Dms.parse_lite`, `Dms.to_dms`, `Dms.to_dms_lite`, and the matching
+> `DmsC.parse*`) still work as deprecated aliases — each emits a
+> one-shot warning on first call, then forwards to the canonical name.
+> They will be removed in the next release.
+
+Tables are insertion-ordered Hashes (Ruby Hashes preserve insertion
+order since 1.9). Lists are Arrays. Datetimes are wrapped types: the
+pure module returns `Dms::LocalDate` / `Dms::LocalTime` /
+`Dms::LocalDateTime` / `Dms::OffsetDateTime` class instances; the C
+extension returns plain `{ __dms_type:, value: }` hashes with the same
+data. Encoders that detect via `__dms_type` + `value` work unchanged
+across both gems.
+
+## Working with comments and heredocs
+
+DMS preserves comments through decode → mutate → re-emit (SPEC
+§Comments). Attach a comment to a value *after* decoding and have it
+round-trip through `Dms.encode`:
+
+```ruby
+require "dms"
+
+doc = Dms.decode_document("db:\n  port: 8080\n")
+
+# Mutate a value in place.
+doc.body["db"]["port"] = 5432
+
+# Attach a leading line comment to db.port.
+doc.comments << Dms::AttachedComment.new(
+  Dms::Comment.new("# bumped after LB change", :line),
+  :leading,
+  ["db", "port"],
+)
+
+puts Dms.encode(doc)
+```
+
+### Forcing a heredoc on emit
+
+Strings parse and re-emit in their source form. To switch a basic-quoted
+string to a heredoc (or to construct one from scratch), append an
+`OriginalLiteral.string` record to `doc.original_forms` keyed by the
+value's path:
+
+```ruby
+doc.body["db"]["greeting"] = "Hello, friend.\nWelcome aboard.\n"
+
+doc.original_forms << [
+  ["db", "greeting"],
+  Dms::OriginalLiteral.string(
+    Dms::StringForm.heredoc(
+      :basic_triple,    # or :literal_triple for '''
+      nil,              # nil = unlabeled (terminator is """ / ''')
+      [],               # _trim(...), _fold_paragraphs(), …
+    ),
+  ),
+]
+```
+
+Round-trip rules (SPEC §Round-trip semantics): comments stick to
+*still-present* nodes; deleting a node drops its comments; newly
+inserted nodes start with no comments. The first `original_forms`
+entry per path wins, so override a parser-recorded form by replacing
+rather than appending if the key is already present.
+
+## Performance
+
+50,000-key flat document (~700 KB), best-of-5, startup-subtracted,
+Ruby 3.3 on Windows 11:
+
+| tier        | DMS gem   | time      | JSON peer | time     | YAML peer | time      | DMS / JSON | DMS / YAML |
+|-------------|-----------|-----------|-----------|----------|-----------|-----------|------------|------------|
+| pure Ruby   | `dms`     | 115.8 ms  | n/a       | —        | n/a       | —         | n/a        | n/a        |
+| native (C)  | `dms-c`   | 56.5 ms   | `json`    | 21.4 ms  | `psych`   | 260.4 ms  | 2.63×      | **0.22× — DMS ~4.6× faster** |
+
+Ruby's stdlib `json` and `psych` are both C-backed; there's no
+widely-used pure-Ruby alternative for either, so JSON and YAML peers
+only appear in the FFI tier (same situation as Node). The pure-Ruby
+DMS port is reported on its own — no fair pure-vs-pure peer to
+compare against.
+
+The C extension is ~2× faster than pure Ruby; against C-backed peers
+DMS is ~2.6× the JSON cost (the cost of carrying comments, ordered
+keys, and source-form metadata) and ~5× faster than libyaml.
+
+Reproduce with:
+
+```sh
+ruby bench/run_formats.rb
+```
+
+## Build & test
+
+```sh
+# pure gem:
+bundle install
+bundle exec rake test
+
+# native (C) gem:
+cd dms-c/ext/dms_c && ruby extconf.rb && make
+```
+
+The C-extension build needs Ruby's MSYS toolchain on Windows or a
+standard `cc` + `make` on Unix; mkmf handles the platform detection.
+
+## Conformance
+
+The fixture corpus lives in
+[dms-tests](https://gitlab.com/flo-labs/pub/dms-tests) (4500+ pairs).
+Clone it once as a sibling:
+
+```sh
+cd ..
+git clone https://gitlab.com/flo-labs/pub/dms-tests.git
+```
+
+The `dms-encoder` binary reads DMS from stdin and writes tagged JSON to
+stdout, matching the format the conformance runner consumes.
+
+## License
+
+Dual-licensed: MIT or Apache-2.0, your choice.

data/bin/dms-encoder

@@ -0,0 +1,234 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# DMS -> tagged-JSON encoder for the conformance suite.
+# Reads DMS source from stdin, writes tagged JSON to stdout.
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "json"
+require "dms"
+
+# Force UTF-8 output: tagged JSON uses ensure_ascii=False equivalent
+# (we write raw UTF-8) so stdout must accept it. Disable CRLF translation.
+$stdout.set_encoding("UTF-8")
+$stdin.set_encoding("UTF-8")
+if RUBY_PLATFORM =~ /mswin|mingw/
+  $stdout.binmode
+end
+
+# Match Rust ryu / Python repr shortest float. Ruby's Float#to_s is shortest
+# round-trip, but uses "1e+100" style; strip the +.
+def shortest_float(v)
+  s = v.to_s
+  if s.include?("e")
+    mantissa, exp = s.split("e", 2)
+    exp = exp[1..] if exp.start_with?("+")
+    "#{mantissa}e#{exp}"
+  elsif !s.include?(".")
+    s + ".0"
+  else
+    s
+  end
+end
+
+def tag(v)
+  case v
+  when true
+    { "type" => "bool", "value" => "true" }
+  when false
+    { "type" => "bool", "value" => "false" }
+  when Integer
+    { "type" => "integer", "value" => v.to_s }
+  when Float
+    s =
+      if v.nan?
+        "nan"
+      elsif v.infinite?
+        v.infinite? > 0 ? "inf" : "-inf"
+      else
+        shortest_float(v)
+      end
+    { "type" => "float", "value" => s }
+  when Dms::OffsetDateTime
+    { "type" => "offset-datetime", "value" => v.value }
+  when Dms::LocalDateTime
+    { "type" => "local-datetime", "value" => v.value }
+  when Dms::LocalDate
+    { "type" => "local-date", "value" => v.value }
+  when Dms::LocalTime
+    { "type" => "local-time", "value" => v.value }
+  when String
+    { "type" => "string", "value" => v }
+  when Hash
+    out = {}
+    v.each { |k, x| out[k] = tag(x) }
+    out
+  when Array
+    v.map { |x| tag(x) }
+  else
+    raise "cannot encode #{v.class}"
+  end
+end
+
+# Walks ARGV looking for `--name N` and returns N (or default if missing /
+# invalid). Mirror of the Rust encoder's parse_usize_flag for protocol
+# parity. See dms-tests/TESTS.md §3a.
+def parse_int_flag(args, name, default = 0)
+  i = args.index(name)
+  return default if i.nil? || i + 1 >= args.length
+
+  Integer(args[i + 1])
+rescue ArgumentError, TypeError
+  default
+end
+
+def parse_str_flag(args, name)
+  i = args.index(name)
+  return nil if i.nil? || i + 1 >= args.length
+
+  args[i + 1]
+end
+
+# Build the tagged-JSON output string for `doc` (matches default path).
+def emit_tagged_json(doc)
+  body_tagged = tag(doc.body)
+  out =
+    if doc.meta.nil?
+      body_tagged
+    else
+      meta_tagged = {}
+      doc.meta.each { |k, v| meta_tagged[k] = tag(v) }
+      { "_meta" => meta_tagged, "_body" => body_tagged }
+    end
+  # Match Python's `json.dumps(out, indent=2, ensure_ascii=False) + "\n"`.
+  JSON.pretty_generate(out, indent: "  ") + "\n"
+end
+
+# Dispatch full vs lite encode. Caller has already validated lite
+# availability when relevant.
+def emit_dms(doc, lite)
+  if lite
+    # Guarded by caller — should never reach here when not available.
+    Dms.encode_lite(doc)
+  else
+    Dms.encode(doc)
+  end
+end
+
+# Bench mode: parse stdin once (untimed, already done by caller), then loop
+# the emit step N times printing one `iter <i> <ns>` per call. Uses
+# Process::CLOCK_MONOTONIC for nanosecond-resolution monotonic timestamps.
+# See dms-tests/TESTS.md §3a.
+def run_bench(doc, roundtrip, lite, iters, warmup)
+  # Warmup: a few untimed emits so allocator / JIT / icache settle.
+  warmup.times do
+    if roundtrip
+      _ = emit_dms(doc, lite)
+    else
+      _ = emit_tagged_json(doc)
+    end
+  end
+  out = $stdout
+  iters.times do |i|
+    t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+    s =
+      if roundtrip
+        emit_dms(doc, lite)
+      else
+        emit_tagged_json(doc)
+      end
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - t0
+    # Keep `s` referenced so the optimizer can't elide the work.
+    s.length if s
+    out.printf("iter %d %d\n", i, elapsed)
+  end
+  out.flush
+end
+
+args = ARGV
+roundtrip = args.include?("--roundtrip")
+
+# --tier=1: tier-1 wrapper JSON output.
+tier_flag = args.include?("--tier=1") ? 1 : 0
+
+# --ignore-order: opts into the unordered parse mode (SPEC §Unordered
+# tables). dms-rb honours this at runtime by building body tables as
+# `Dms::UnorderedHash` with shuffled key order; full-mode `to_dms` then
+# refuses such Documents (use `--mode lite` for canonical emit). Falls
+# back to DMS_IGNORE_ORDER env var.
+ignore_order = args.include?("--ignore-order") || !ENV["DMS_IGNORE_ORDER"].to_s.empty?
+
+# --mode {full,lite} (default: full). In --roundtrip mode this picks
+# to_dms vs to_dms_lite. Falls back to DMS_MODE env var. Default
+# tagged-JSON mode currently ignores --mode (output shape is fixed by
+# the conformance contract).
+mode_arg = parse_str_flag(args, "--mode") || ENV["DMS_MODE"] || "full"
+case mode_arg
+when "full"
+  lite = false
+when "lite"
+  lite = true
+else
+  $stderr.puts "0:0: --mode must be full|lite, got #{mode_arg.inspect}"
+  exit 1
+end
+
+# Bench mode flags. See dms-tests/TESTS.md §3a.
+bench_iters = parse_int_flag(args, "--bench-iters", 0)
+bench_warmup = parse_int_flag(args, "--bench-warmup", 3)
+
+src = $stdin.read
+
+# Empty / whitespace-only stdin → exit 0 (startup probe used by bench harness).
+if src.nil? || src.strip.empty?
+  exit 0
+end
+
+begin
+  # Tier-1 decode path: parse with decorator awareness, emit wrapper JSON.
+  if tier_flag == 1
+    doc_t1 = Dms::Tier1.parse(src)
+    out = Dms::Tier1.emit_t1_json(doc_t1, method(:tag))
+    $stdout.write(JSON.pretty_generate(out, indent: "  ") + "\n")
+    exit 0
+  end
+
+  # Decode mode dispatch: `--ignore-order` opts into unordered backing
+  # (SPEC §"Unordered tables"); `--mode lite` (or DMS_MODE=lite) routes
+  # through the lite decoder even on the tagged-JSON conformance path.
+  # Tagged JSON is mode-invariant (same value tree); the dispatch lets
+  # the conformance harness exercise either decoder under one driver.
+  doc =
+    if lite && ignore_order
+      Dms.decode_lite_document_unordered(src)
+    elsif lite
+      Dms.decode_lite_document(src)
+    elsif ignore_order
+      Dms.decode_document_unordered(src)
+    else
+      Dms.decode_document(src)
+    end
+rescue Dms::DecodeError => e
+  warn e.message
+  exit 1
+rescue StandardError => e
+  warn "0:0: #{e.message}"
+  exit 1
+end
+
+if bench_iters > 0
+  run_bench(doc, roundtrip, lite, bench_iters, bench_warmup)
+  exit 0
+end
+
+begin
+  if roundtrip
+    $stdout.write(emit_dms(doc, lite))
+  else
+    $stdout.write(emit_tagged_json(doc))
+  end
+rescue StandardError => e
+  warn "0:0: #{e.message}"
+  exit 1
+end