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:

gem "verbatim"

Install the gem locally:

bundle install

Use

Define a schema, call .parse, use readers or #[] / #to_s:

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):

ApiVersion.new(major: 1, minor: 0).to_s  # => "1.0"

Semantic Version Schema (Built-in)

Verbatim::Schemas::SemVer encodes Semantic Versioning 2.0.0 core version, optional prerelease and build metadata.

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-style YYYY.0M.0D layout with zero-padding on #to_s.

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.

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 and verbatim.gemspec).

verbatim

Development