verbatim 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b75beb6061fd54c18171fd501e92c6a90daee024dab8b18fc232cf0ec6b4a21e
+  data.tar.gz: fa29a0a2aa2348a6f1cb45a77beef2f310525a76780f0aa8a1d69474ef09224c
+SHA512:
+  metadata.gz: a1ffa058b4c70bc06dac53b5c98e254ec332944d30ebe4d63ace45d1d7da1ad2f5867f025f97aa97b17ad405011190dd4c03818a38e2a30b461e5eda87a9080b
+  data.tar.gz: 335e1735ecbb0e2fc49d8f19e23d888a1d81a6d65336b01467ee3011ade95fc236be68476746c877ff62da1026b02066b53881a8872a09d64506fadd8777ba63

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- (nothing yet)
+
+### Changed
+
+- `Schema.parse` enforces a maximum input length of 128 characters (`Verbatim::Schema::MAX_INPUT_LEN`).
+
+## [0.1.0] - 2026-04-08
+
+### Added
+
+- `Verbatim::Schema` DSL: `delimiter`, `segment` with `optional`, `lead`, `delimiter_after`, and type-specific options.
+- Built-in segment types: `:uint`, `:int`, `:token`, `:string`, `:semver_ids`.
+- `Verbatim::Schemas::SemVer` and `Verbatim::Schemas::CalVer`.
+- `.parse` / `.format`, value API: readers, `#[]`, `#to_h`, `#to_s`, equality, `Comparable` (SemVer uses 2.0.0 precedence).
+- `Verbatim::ParseError` with message, string, index, and segment.
+- Instance `#with(**attrs)`; `#succ` / `#pred` on `Schema` (default `NotImplementedError`), with CalVer (calendar day) and SemVer (patch bump / core predecessor) implementations.
+- MIT `LICENSE` included in the gem.
+
+[Unreleased]: https://github.com/dsdugal/verbatim/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dsdugal/verbatim/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dustin Dugal
+
+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,133 @@
+# Verbatim
+
+Verbatim is a Ruby gem for **declarative version string schemas**. You subclass `Verbatim::Schema`, declare ordered segments in a class-level Domain-Specific Language (DSL), then **parse** strings into structured values and **format** them back with `#to_s`.
+
+Requires **Ruby 3.2+**.
+
+## Installation
+
+Add to your project's Gemfile:
+
+```ruby
+gem "verbatim"
+```
+
+Install the gem locally:
+
+```bash
+bundle install
+```
+
+## Use
+
+Define a schema, call `.parse`, use readers or `#[]` / `#to_s`:
+
+```ruby
+require "verbatim"
+
+class ApiVersion < Verbatim::Schema
+  delimiter "."
+  segment :major, :uint
+  segment :minor, :uint
+end
+
+v = ApiVersion.parse("2.15")
+v.major  # => 2
+v.minor  # => 15
+v[:minor]  # => 15
+v.to_s   # => "2.15"
+```
+
+Build an instance by hand (useful for tests or construction from other data):
+
+```ruby
+ApiVersion.new(major: 1, minor: 0).to_s  # => "1.0"
+```
+
+## Semantic Version Schema (Built-in)
+
+`Verbatim::Schemas::SemVer` encodes [Semantic Versioning 2.0.0](https://semver.org/) core version, optional prerelease and build metadata.
+
+```ruby
+v = Verbatim::Schemas::SemVer.parse("1.0.0-rc.1+exp.sha.5114f85")
+v.major       # => 1
+v.minor       # => 0
+v.patch       # => 0
+v.prerelease  # => "rc.1"
+v.build       # => "exp.sha.5114f85"
+v.to_s        # => "1.0.0-rc.1+exp.sha.5114f85"
+```
+
+## Calendar Version Schema (Built-in)
+
+`Verbatim::Schemas::CalVer` follows a common [Calendar Versioning](https://calver.org/)-style **YYYY.0M.0D** layout with **zero-padding** on `#to_s`.
+
+```ruby
+v = Verbatim::Schemas::CalVer.parse("2026.4.8")
+v.to_s  # => "2026.04.08"
+```
+
+## DSL Reference
+
+#### `delimiter(string)`:
+Sets the default string placed **between** consecutive segments when neither segment uses a `lead`.
+
+#### `segment(name, type, **options)`:
+Declares one segment, in order. Duplicate names are rejected.
+
+
+| Option                  | Meaning                                                                                                                                                                                                                                                                                                       |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `optional: true`        | With `lead`: if the input does not start with `lead`, the segment is `nil` and parsing continues. Optional segments without `lead` are not treated specially (use `lead` for optional tails such as SemVer prerelease/build).                                                                                 |
+| `lead: "..."`           | Literal prefix **before** this segment’s value (for example `"-"` or `"+"`). Consumed on parse; emitted on `#to_s`. No default delimiter is consumed before a segment that has a `lead`.                                                                                                                      |
+| `delimiter_after:`      | `:inherit` (default): after this segment, the next segment (if it has no `lead`) is separated with the schema’s default delimiter. `:none`: do not insert the default delimiter before the next segment (typical before optional `-` / `+` tails). Or pass a string for a fixed delimiter after this segment. |
+| Other keyword arguments | Passed through to the segment **type** (for example `leading_zeros: false` on `:uint`, `pattern:` on `:string`, `terminator:` on `:semver_ids`).                                                                                                                                                              |
+
+
+### Object API
+
+- **Access:** reader per segment (e.g. `#major`), plus `#[](name)` and `#to_h`.
+- **`#to_s`:** formats in segment order; omits `nil` optional segments.
+- **`#with(**attrs)`:** returns a **new** instance of the same schema with merged segment values.
+- **`#succ` / `#pred`:** previous and next along a schema-specific sequence. The base `Verbatim::Schema` raises `NotImplementedError`; override in subclasses or use `#with` to bump fields yourself.
+- **Equality:** `#==`, `#eql?`, and `#hash` use the schema class and segment values.
+- **`Comparable`:** same-class instances sort together (`nil` optionals before non-`nil` in each slot); different schema classes are incomparable. `Verbatim::Schemas::SemVer` uses SemVer 2.0.0 precedence.
+- **`.parse`** returns a frozen instance.
+
+### Class methods
+
+- `YourSchema.parse(string)` → instance
+- `YourSchema.format(instance)` → canonical string (same rules as `#to_s`)
+
+## Segment Types
+
+
+| Type          | Description                                                                                          | Options                                                                                                                                                                                                 |
+| ------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:uint`       | Non-empty ASCII digits → `Integer`; format with `Integer#to_s`, optionally zero-padded via `pad:`    | `leading_zeros: false` disallows multi-digit values with a leading `0`. `pad: N` formats with at least `N` digits (e.g. `pad: 2` → `"08"`). `minimum:` / `maximum:` validate the integer after parsing. |
+| `:int`        | Optional leading `-`, then digits → `Integer`; format with `Integer#to_s` (negative values allowed)  | —                                                                                                                                                                                                       |
+| `:token`      | Maximal run of `[0-9A-Za-z-]` → string; format the same string                                       | —                                                                                                                                                                                                       |
+| `:string`     | Rest of input must match anchored `options[:pattern]`; format `value.to_s`                           | `pattern:` (required Regexp).                                                                                                                                                                           |
+| `:semver_ids` | Dot-separated SemVer identifiers until end of string or `terminator`; format joins segments with `.` | `terminator:` (e.g. `"+"` so prerelease stops before build metadata).                                                                                                                                   |
+
+
+## Custom Segment Types
+
+Register a handler object that responds to `parse(cursor, segment, parse_ctx)` and `format(value, segment)`. Parsing should advance `cursor` and return the Ruby value; formatting returns the string fragment for that segment. Use `Verbatim::Cursor` (`#peek`, `#advance`, `#remainder`, `#starts_with?`, `#eos?`) and `segment.options` for type-specific configuration.
+
+```ruby
+Verbatim::Types.register(:my_token, my_handler)
+
+class MySchema < Verbatim::Schema
+  delimiter "."
+  segment :x, :my_token
+end
+```
+
+## Errors
+
+Input is interpreted as UTF-8; version strings are expected to be compatible with that. `Schema.parse` rejects strings longer than `Verbatim::Schema::MAX_INPUT_LEN` (**128** characters, by UTF-8 codepoint count) with `Verbatim::ParseError`. Failed parses raise `Verbatim::ParseError` with `#message`, `#string` (input), `#index` (0-based **character** index into the string), and `#segment`.
+
+## License
+
+MIT (see [LICENSE](LICENSE) and [verbatim.gemspec](verbatim.gemspec)).

data/lib/verbatim/cursor.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Verbatim
+  # Character-position cursor over a UTF-8 string; used by the parser and custom type handlers.
+  #
+  # @api public
+  #
+  class Cursor
+    # @return [String] the full string being scanned (UTF-8)
+    attr_reader :string
+    # @return [Integer] current zero-based character index into {#string}
+    attr_reader :pos
+
+    # @param string [String] input; re-encoded to UTF-8
+    # @return [void]
+    #
+    def initialize(string)
+      @string = string.encode(Encoding::UTF_8)
+      @pos = 0
+    end
+
+    # Checks if the cursor is at the end of the string.
+    #
+    # @return [Boolean] +true+ if no characters remain after {#pos}
+    #
+    def eos?
+      pos >= string.length
+    end
+
+    # Returns the remainder of the string from the current position to the end.
+    #
+    # @return [String] substring from {#pos} through end of {#string}
+    #
+    def remainder
+      string[pos..] || ""
+    end
+
+    # Returns up to +count+ characters at {#pos}, or empty string at end.
+    #
+    # @param count [Integer] number of characters to peek (default 1)
+    # @return [String] up to +count+ characters at {#pos}, or empty string at end
+    #
+    def peek(count = 1)
+      string[pos, count] || ""
+    end
+
+    # Advances the cursor by +delta+ characters.
+    #
+    # @param delta [Integer] number of character positions to advance (default 1)
+    # @return [void]
+    #
+    def advance(delta = 1)
+      @pos += delta
+    end
+
+    # Checks if the cursor starts with a given prefix.
+    #
+    # @param prefix [String] literal prefix to test
+    # @return [Boolean] +true+ if {#string} at {#pos} starts with +prefix+
+    #
+    def starts_with?(prefix)
+      string[pos, prefix.length] == prefix
+    end
+  end
+end

data/lib/verbatim/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Verbatim
+  # Raised when a string does not match the expected schema layout.
+  #
+  # @api public
+  #
+  class ParseError < StandardError
+    # @return [String] the full input string that was being parsed
+    attr_reader :string
+    # @return [Integer] zero-based character index of the error position in {#string}
+    attr_reader :index
+    # @return [Symbol, nil] segment name when known, or +nil+
+    attr_reader :segment
+
+    # @param message [String] human-readable error description
+    # @param string [String] full input string
+    # @param index [Integer] character index where parsing failed
+    # @param segment [Symbol, nil] segment name when applicable
+    # @return [void]
+    #
+    def initialize(message, string:, index:, segment: nil)
+      super(message)
+      @string = string
+      @index = index
+      @segment = segment
+    end
+  end
+end

data/lib/verbatim/parser.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Verbatim
+  # Fills a {Schema} instance by consuming a string according to the schema’s segment list.
+  #
+  # @api public
+  #
+  class Parser
+    # @param schema_class [Class] subclass of {Schema}
+    # @param string [String] input to parse
+    # @return [void]
+    #
+    def initialize(schema_class, string)
+      @schema_class = schema_class
+      @cursor = Cursor.new(string)
+    end
+
+    # Consumes {#initialize}’s string and writes segment values into +instance+.
+    #
+    # @param instance [Schema] unfrozen or frozen target; receives {#Schema#assign_segment}
+    # @return [Schema] +instance+
+    # @raise [ParseError] on malformed input or trailing data
+    #
+    def parse_into(instance)
+      segments = @schema_class.segments
+
+      segments.each_with_index do |segment, i|
+        if segment.optional? && segment.lead? && !@cursor.starts_with?(segment.lead)
+          instance.assign_segment(segment.name, nil)
+          next
+        end
+
+        if i.positive? && !segment.lead?
+          delim = effective_delimiter_after(segments[i - 1])
+          expect_delimiter!(delim, segment) if delim && !delim.empty?
+        end
+
+        if segment.lead?
+          expect_lead!(segment)
+          @cursor.advance(segment.lead.length)
+        end
+
+        value = Types.parse(segment.type, @cursor, segment, self)
+        instance.assign_segment(segment.name, value)
+      end
+
+      unless @cursor.eos?
+        raise ParseError.new(
+          "unexpected trailing data #{@cursor.remainder.inspect}",
+          string: @cursor.string,
+          index: @cursor.pos,
+          segment: nil
+        )
+      end
+
+      instance
+    end
+
+    private
+
+    # Expects a delimiter at the cursor.
+    #
+    # @param delim [String, nil]
+    # @param segment [Segment]
+    # @return [void]
+    # @raise [ParseError] if +delim+ is present but not at the cursor
+    #
+    def expect_delimiter!(delim, segment)
+      return if delim.nil? || delim.empty?
+
+      unless @cursor.starts_with?(delim)
+        raise ParseError.new(
+          "expected delimiter #{delim.inspect}",
+          string: @cursor.string,
+          index: @cursor.pos,
+          segment: segment.name
+        )
+      end
+      @cursor.advance(delim.length)
+    end
+
+    # Expects a lead at the cursor.
+    #
+    # @param segment [Segment]
+    # @return [void]
+    # @raise [ParseError] if the cursor does not start with +segment.lead+
+    #
+    def expect_lead!(segment)
+      return if @cursor.starts_with?(segment.lead)
+
+      raise ParseError.new(
+        "expected #{segment.lead.inspect}",
+        string: @cursor.string,
+        index: @cursor.pos,
+        segment: segment.name
+      )
+    end
+
+    # Returns the effective delimiter after a segment.
+    #
+    # @param segment [Segment]
+    # @return [String, nil] delimiter string to expect after +segment+, or +nil+
+    #
+    def effective_delimiter_after(segment)
+      case segment.delimiter_after
+      when :inherit then @schema_class.default_delimiter
+      when :none then nil
+      else segment.delimiter_after.to_s
+      end
+    end
+  end
+end