verbatim 0.1.0

data/lib/verbatim/schema.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Verbatim
+  # Base class for declarative version (or token) schemas. Subclasses declare {#segment}s and use {.parse}.
+  # Each {.segment} defines a public instance reader with the same name as the segment.
+  #
+  # @api public
+  #
+  class Schema
+    include Comparable
+
+    # Maximum number of characters allowed in the string passed to {.parse} (UTF-8 codepoint count).
+    #
+    MAX_INPUT_LEN = 128
+
+    class << self
+      # Subclasses must call +super+ and initialize {#segments}, {#default_delimiter}, and {#segment_names}.
+      #
+      # @param subclass [Class]
+      # @return [void]
+      #
+      def inherited(subclass)
+        super
+
+        subclass.instance_variable_set(:@segments, [])
+        subclass.instance_variable_set(:@default_delimiter, ".")
+        subclass.instance_variable_set(:@segment_names, [])
+      end
+
+      # @return [Array<Segment>] segments in declaration order
+      #
+      def segments
+        @segments ||= []
+      end
+
+      # Sets or returns the default delimiter between segments (when the next segment has no +lead+).
+      #
+      # @param value [String, nil] if +nil+, returns the current default without changing it
+      # @return [String] the active default delimiter
+      #
+      def delimiter(value = nil)
+        @default_delimiter ||= "."
+        return @default_delimiter if value.nil?
+
+        @default_delimiter = value.to_s
+      end
+
+      alias default_delimiter delimiter
+
+      # Declares a segment and defines an instance reader for +name+.
+      #
+      # @param name [Symbol]
+      # @param type [Symbol] registered in {Types.register}
+      # @param optional [Boolean]
+      # @param lead [String, nil]
+      # @param delimiter_after [Symbol, String] +:inherit+, +:none+, or explicit string
+      # @param options [Hash] forwarded to the type handler (e.g. +pad:+, +pattern:+)
+      # @return [void]
+      # @raise [ArgumentError] on duplicate segment +name+
+      #
+      def segment(name, type, optional: false, lead: nil, delimiter_after: :inherit, **options)
+        name = name.to_sym
+        @segment_names ||= []
+        @segments ||= []
+        @default_delimiter ||= "."
+
+        raise ArgumentError, "duplicate segment #{name.inspect}" if @segment_names.include?(name)
+
+        @segment_names << name
+
+        segments << Segment.new(
+          name: name,
+          type: type.to_sym,
+          optional: optional,
+          lead: lead&.to_s,
+          delimiter_after: delimiter_after,
+          options: options
+        )
+
+        define_reader(name)
+      end
+
+      # Parses a string into a new instance of the schema class.
+      #
+      # @param string [String]
+      # @return [Schema] a frozen instance populated from +string+
+      # @raise [ParseError] on invalid input or if +string+ is longer than {#MAX_INPUT_LEN}
+      #
+      def parse(string)
+        if string.length > MAX_INPUT_LEN
+          raise ParseError.new(
+            "input exceeds maximum length of #{MAX_INPUT_LEN} characters (#{string.length} given)",
+            string: string,
+            index: MAX_INPUT_LEN,
+            segment: nil
+          )
+        end
+
+        allocate.tap do |instance|
+          instance.send(:initialize_values)
+          Parser.new(self, string).parse_into(instance)
+          instance.freeze
+        end
+      end
+
+      # Formats an instance of the schema class into a canonical string.
+      #
+      # @param instance [Schema] same class as this schema
+      # @return [String] canonical string for +instance+
+      # @raise [ArgumentError] if a required segment value is missing
+      #
+      def format(instance)
+        parts = []
+
+        segments.each_with_index do |segment, index|
+          value = instance.send(segment.name)
+          next if value.nil? && segment.optional?
+
+          raise ArgumentError, "missing required segment #{segment.name}" if value.nil?
+
+          if index.zero?
+            parts << Types.format(segment.type, value, segment)
+          elsif segment.lead?
+            parts << segment.lead.to_s << Types.format(segment.type, value, segment)
+          else
+            delim = delimiter_before_format(segments, index)
+            parts << delim if delim && !delim.empty?
+            parts << Types.format(segment.type, value, segment)
+          end
+        end
+
+        parts.join
+      end
+
+      private
+
+      # Defines a public instance reader for +name+.
+      #
+      # @param name [Symbol]
+      # @return [void]
+      #
+      def define_reader(name)
+        define_method(name) { @values[name] }
+      end
+
+      # Returns the delimiter before the given segment when formatting.
+      #
+      # @param segments [Array<Segment>]
+      # @param index [Integer] index of the segment being formatted
+      # @return [String, nil] delimiter before that segment when formatting
+      #
+      def delimiter_before_format(segments, index)
+        return if index.zero?
+
+        prev = segments[index - 1]
+
+        case prev.delimiter_after
+        when :inherit then delimiter(nil)
+        when :none then nil
+        else prev.delimiter_after.to_s
+        end
+      end
+    end
+
+    # @param values [Hash] segment name => parsed value
+    # @return [void]
+    #
+    def initialize(**values)
+      initialize_values
+
+      values.each { |name, value| assign_segment(name.to_sym, value) }
+    end
+
+    # Assigns a value to a segment.
+    #
+    # @param name [Symbol, String]
+    # @param value [Object]
+    # @return [void]
+    # @raise [FrozenError] if +self+ is frozen
+    #
+    def assign_segment(name, value)
+      @values[name.to_sym] = value
+    end
+
+    # Returns the value of a segment.
+    #
+    # @param name [Symbol, String]
+    # @return [Object] segment value, or +nil+ if unset
+    #
+    def [](name)
+      @values[name.to_sym]
+    end
+
+    # Returns a copy of the internal segment values.
+    #
+    # @return [Hash{Symbol => Object}] copy of internal segment values
+    #
+    def to_h
+      @values.dup
+    end
+
+    # Returns a new instance of the same schema with segment values merged over +self+.
+    #
+    # @param overrides [Hash] segment names (symbols or strings) => new values
+    # @return [Schema] unfrozen instance; does not mutate +self+
+    #
+    def with(**overrides)
+      base = self.class.segments.each_with_object({}) { |s, h| h[s.name] = @values[s.name] }
+      self.class.new(**base.merge(overrides.transform_keys(&:to_sym)))
+    end
+
+    # Next sequential value for this schema. The base implementation raises; subclasses
+    # may override (e.g. {Schemas::CalVer}, {Schemas::SemVer}).
+    #
+    # @return [Schema]
+    # @raise [NotImplementedError] unless overridden
+    #
+    def succ
+      raise NotImplementedError, "#{self.class} does not define #succ; override it or use #with"
+    end
+
+    # Previous sequential value for this schema. The base implementation raises; subclasses
+    # may override (e.g. {Schemas::CalVer}, {Schemas::SemVer}).
+    #
+    # @return [Schema]
+    # @raise [NotImplementedError] unless overridden
+    #
+    def pred
+      raise NotImplementedError, "#{self.class} does not define #pred; override it or use #with"
+    end
+
+    # Returns the canonical string representation of the instance.
+    #
+    # @return [String] {.format}(+self+)
+    #
+    def to_s
+      self.class.format(self)
+    end
+
+    # Returns a string representation of the instance.
+    #
+    # @return [String]
+    #
+    def inspect
+      attrs = self.class.segments.map { |segment| "#{segment.name}=#{@values[segment.name].inspect}" }.join(", ")
+
+      "#<#{self.class.name} #{attrs}>"
+    end
+
+    # Compares two instances of the same class.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    #
+    def ==(other)
+      other.is_a?(self.class) && @values == other.instance_variable_get(:@values)
+    end
+
+    alias eql? ==
+
+    # Returns a hash code for the instance.
+    #
+    # @return [Integer] hash consistent with {#eql?}
+    #
+    def hash
+      [self.class, @values].hash
+    end
+
+    # Compares two instances of the same class in segment declaration order;
+    # +nil+ optional values sort before non-+nil+. Subclasses (e.g. {Schemas::SemVer}) may override.
+    #
+    # @param other [Object]
+    # @return [Integer, nil] -1, 0, 1, or +nil+ if not comparable (different class or incomparable values)
+    #
+    def <=>(other)
+      return nil unless other.is_a?(self.class)
+
+      segs = self.class.segments
+      i = 0
+      while i < segs.length
+        segment = segs[i]
+        comparison = compare_values_for_sort(@values[segment.name], other.send(segment.name))
+        return nil if comparison.nil?
+
+        return comparison if comparison != 0
+
+        i += 1
+      end
+
+      0
+    end
+
+    private
+
+    # Compares two values for sort order.
+    #
+    # @param left [Object, nil]
+    # @param right [Object, nil]
+    # @return [Integer, nil]
+    #
+    def compare_values_for_sort(left, right)
+      if left.nil? && right.nil?
+        0
+      elsif left.nil?
+        -1
+      elsif right.nil?
+        1
+      else
+        comparison = left <=> right
+
+        return if comparison.nil?
+
+        comparison
+      end
+    end
+
+    # Initializes the internal segment values.
+    #
+    # @return [void]
+    #
+    def initialize_values
+      @values = {}
+    end
+  end
+end

data/lib/verbatim/schemas/calver.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "date"
+
+require_relative "../errors"
+require_relative "../cursor"
+require_relative "../segment"
+require_relative "../types"
+require_relative "../parser"
+require_relative "../schema"
+
+module Verbatim
+  module Schemas
+    # Calendar-style +YYYY.0M.0D+ version (+year+, zero-padded +month+ and +day+ in {#to_s}).
+    #
+    # Parsing accepts unpadded or padded numeric components (e.g. +2026.4.8+ or +2026.04.08+).
+    # This does not enforce real calendar dates (+2026.02.31+ parses); add your own validation if needed.
+    #
+    # @api public
+    #
+    class CalVer < Schema
+      delimiter "."
+
+      segment :year, :uint, pad: 4
+      segment :month, :uint, pad: 2, minimum: 1, maximum: 12
+      segment :day, :uint, pad: 2, minimum: 1, maximum: 31
+
+      # Next calendar day.
+      #
+      # @return [CalVer]
+      # @raise [ArgumentError] if the current date is invalid for +Date+ (e.g. Feb 30)
+      #
+      def succ
+        step_calendar(1)
+      end
+
+      # Previous calendar day.
+      #
+      # @return [CalVer]
+      # @raise [ArgumentError] if the current date is invalid for +Date+ (e.g. Feb 30)
+      #
+      def pred
+        step_calendar(-1)
+      end
+
+      private
+
+      # @param delta [Integer] days to add (+1 / +-1+)
+      # @return [CalVer]
+      #
+      def step_calendar(delta)
+        d = Date.new(year, month, day) + delta
+        with(year: d.year, month: d.month, day: d.day)
+      rescue ArgumentError, Date::Error => e
+        raise ArgumentError, "invalid calendar date for CalVer#succ/#pred: #{e.message}"
+      end
+    end
+  end
+end

data/lib/verbatim/schemas/semver.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../cursor"
+require_relative "../segment"
+require_relative "../types"
+require_relative "../parser"
+require_relative "../schema"
+require_relative "semver_compare"
+
+module Verbatim
+  module Schemas
+    # Semantic Versioning 2.0.0 schema (+major.minor.patch+ with optional +-prerelease+ and ++build+).
+    #
+    # @api public
+    #
+    class SemVer < Schema
+      delimiter "."
+
+      segment :major, :uint, leading_zeros: false
+      segment :minor, :uint, leading_zeros: false
+      segment :patch, :uint, leading_zeros: false, delimiter_after: :none
+      segment :prerelease, :semver_ids,
+              optional: true,
+              lead: "-",
+              terminator: "+"
+      segment :build, :semver_ids,
+              optional: true,
+              lead: "+"
+
+      # Next release along the core line: increments +patch+ and clears prerelease and build.
+      #
+      # @return [SemVer]
+      #
+      def succ
+        with(patch: patch + 1, prerelease: nil, build: nil)
+      end
+
+      # Previous plain release: decrements +patch+, or borrows from +minor+ or +major+ (lower fields zeroed).
+      # Only defined when +prerelease+ and +build+ are both absent; raises otherwise.
+      #
+      # @return [SemVer]
+      # @raise [ArgumentError] if prerelease or build is set, or if this is +0.0.0+
+      #
+      def pred
+        if prerelease || build
+          raise ArgumentError,
+                "SemVer#pred is only defined for plain major.minor.patch (no prerelease or build)"
+        end
+
+        if patch.positive?
+          with(patch: patch - 1)
+        elsif minor.positive?
+          with(minor: minor - 1, patch: 0)
+        elsif major.positive?
+          with(major: major - 1, minor: 0, patch: 0)
+        else
+          raise ArgumentError, "no predecessor for 0.0.0"
+        end
+      end
+
+      # SemVer 2.0.0 precedence: core numeric, then prerelease via {SemVerCompare}.
+      # Build metadata does not affect precedence; compared last for stable sorting only.
+      #
+      # @param other [Object]
+      # @return [Integer, nil] -1, 0, 1, or +nil+ if +other+ is not a {SemVer}
+      def <=>(other)
+        return nil unless other.is_a?(SemVer)
+
+        comparison = major <=> other.major
+        return comparison if comparison != 0
+
+        comparison = minor <=> other.minor
+        return comparison if comparison != 0
+
+        comparison = patch <=> other.patch
+        return comparison if comparison != 0
+
+        comparison = SemVerCompare.prerelease(prerelease, other.prerelease)
+        return comparison if comparison != 0
+
+        (build || "").to_s <=> (other.build || "").to_s
+      end
+    end
+  end
+end

data/lib/verbatim/schemas/semver_compare.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Verbatim
+  module Schemas
+    # SemVer 2.0.0 precedence for prerelease identifiers (+major+/+minor+/+patch+ compared separately in {SemVer#<=>}).
+    #
+    # @api public
+    #
+    module SemVerCompare
+      module_function
+
+      # Compares prerelease strings per SemVer 2.0.0.
+      # +nil+ means a release and sorts *after* any prerelease for the same core.
+      #
+      # @param left [String, nil]
+      # @param right [String, nil]
+      # @return [Integer] -1, 0, or 1
+      #
+      def prerelease(left, right)
+        case [left.nil?, right.nil?]
+        when [true, true] then 0
+        when [true, false] then 1
+        when [false, true] then -1
+        else
+          compare_prerelease_identifiers(left.split(".", -1), right.split(".", -1))
+        end
+      end
+
+      # Compares prerelease identifiers.
+      #
+      # @param ids_a [Array<String>]
+      # @param ids_b [Array<String>]
+      # @return [Integer] -1, 0, or 1
+      #
+      def compare_prerelease_identifiers(ids_a, ids_b)
+        i = 0
+        loop do
+          a_miss = i >= ids_a.length
+          b_miss = i >= ids_b.length
+          if a_miss && b_miss
+            return 0
+          elsif a_miss
+            return -1
+          elsif b_miss
+            return 1
+          end
+
+          comparison = compare_identifier(ids_a[i], ids_b[i])
+          return comparison if comparison != 0
+
+          i += 1
+        end
+      end
+
+      # Compares a single prerelease identifier.
+      #
+      # @param one [String]
+      # @param two [String]
+      # @return [Integer] -1, 0, or 1
+      #
+      def compare_identifier(one, two)
+        one_num = numeric_identifier?(one)
+        two_num = numeric_identifier?(two)
+        if one_num && two_num
+          Integer(one, 10) <=> Integer(two, 10)
+        elsif one_num
+          -1
+        elsif two_num
+          1
+        else
+          one <=> two
+        end
+      end
+
+      # Checks if a token is a numeric-only prerelease identifier.
+      #
+      # @param token [String]
+      # @return [Boolean] +true+ if +token+ is numeric-only per SemVer identifier rules
+      #
+      def numeric_identifier?(token)
+        token.match?(/\A[0-9]+\z/) && (token == "0" || token.match?(/\A[1-9]\d*\z/))
+      end
+    end
+  end
+end

data/lib/verbatim/segment.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Verbatim
+  # Immutable description of one field in a {Schema} (name, type, delimiters, options).
+  #
+  # @api public
+  #
+  class Segment
+    # @return [Symbol] segment field name
+    attr_reader :name
+    # @return [Symbol] registered type key (e.g. +:uint+)
+    attr_reader :type
+    # @return [Boolean] whether the segment may be omitted when its +lead+ is absent
+    attr_reader :optional
+    # @return [String, nil] literal prefix before the value (e.g. +-+), or +nil+
+    attr_reader :lead
+    # @return [Symbol, String] +:inherit+, +:none+, or an explicit delimiter string after this segment
+    attr_reader :delimiter_after
+    # @return [Hash] type-specific options (frozen)
+    attr_reader :options
+
+    # @param name [Symbol]
+    # @param type [Symbol]
+    # @param optional [Boolean]
+    # @param lead [String, nil]
+    # @param delimiter_after [Symbol, String] +:inherit+ (default), +:none+, or delimiter string
+    # @param options [Hash] extra options passed to the type handler
+    # @return [void]
+    #
+    def initialize(name:, type:, optional: false, lead: nil, delimiter_after: :inherit, options: {})
+      @name = name
+      @type = type
+      @optional = optional
+      @lead = lead
+      @delimiter_after = delimiter_after
+      @options = options.freeze
+      freeze
+    end
+
+    # Checks if the segment is optional.
+    #
+    # @return [Boolean] +true+ if {#optional} is +true+
+    #
+    def optional?
+      optional
+    end
+
+    # Checks if the segment has a lead.
+    #
+    # @return [Boolean] +true+ if {#lead} is non-empty
+    #
+    def lead?
+      !lead.nil? && !lead.empty?
+    end
+  end
+end