predicator 1.2.1 → 2.0.0

data/lib/predicator/tagged/reader.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Tagged
+    # Text to value: the decoding half of the codec.
+    # A private constant of Tagged: its functions are reached only through
+    # Tagged.decode and Tagged.encode, which document what they answer.
+    #
+    # @api private
+    module Reader
+      DURATION_UNITS = %w[years months weeks days hours minutes seconds].freeze
+      DATE_TEXT = /\A(\d{4})-(\d{2})-(\d{2})\z/
+      DATETIME_TEXT = /\A(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:[.,](\d+))?(Z|[+-]\d{2}(?::?\d{2})?)\z/
+      OFFSET_TEXT = /\A([+-])(\d{2}):?(\d{2})?\z/
+      READERS = { "date" => :read_date, "datetime" => :read_datetime, "duration" => :read_duration }.freeze
+
+      module_function
+
+      def read(text)
+        utf8 = text.encoding == Encoding::UTF_8 ? text : text.dup.force_encoding(Encoding::UTF_8)
+        Refused.raise!("malformed_json", "the text is not valid UTF-8") unless utf8.valid_encoding?
+        value(parse(utf8), 1)
+      end
+
+      # JSON.parse keeps the written form of a number: `1` is an Integer and
+      # `1.0` and `1e2` are Floats. Only an exponent too large for a Float
+      # reads as an infinity, which value refuses. Its own nesting limit only
+      # bounds the parser's recursion (how it counts differs between json
+      # versions); value counts the levels exactly.
+      def parse(text)
+        JSON.parse(text, max_nesting: DEPTH_LIMIT + 2)
+      rescue JSON::NestingError => e
+        Refused.raise!("depth_limit_exceeded", e.message)
+      rescue JSON::ParserError => e
+        Refused.raise!("malformed_json", e.message)
+      end
+
+      def value(json, depth)
+        case json
+        when Hash then map(json, depth)
+        when Array then deep(depth) && json.map { |member| value(member, depth + 1) }
+        when Float then finite(json)
+        else json
+        end
+      end
+
+      def map(json, depth)
+        deep(depth)
+        return tag(json, depth) if json.key?("$type")
+
+        json.transform_values { |member| value(member, depth + 1) }
+      end
+
+      def finite(number)
+        return number if number.finite?
+
+        Refused.raise!("non_finite_number", "the number #{number} is not finite")
+      end
+
+      def deep(depth)
+        return true if depth <= DEPTH_LIMIT
+
+        Refused.raise!("depth_limit_exceeded", "the text nests past #{DEPTH_LIMIT} levels")
+      end
+
+      # A duration's value is a map one level inside its tag's braces.
+      def tag(json, depth)
+        return UNDEFINED if json == { "$type" => "undefined" }
+
+        reader = READERS[json["$type"]]
+        deep(depth + 1) if reader == :read_duration
+        decoded = send(reader, json["value"]) if reader && json.keys.sort == ["$type", "value"]
+        decoded || Refused.raise!("invalid_tagged_value",
+                                  "a #{json["$type"].inspect} tag with the keys #{json.keys.sort.inspect} " \
+                                  "is not a tagged value")
+      end
+
+      def read_date(text)
+        match = text.is_a?(String) && DATE_TEXT.match(text)
+        return unless match
+
+        year, month, day = match.captures.map { |part| Integer(part, 10) }
+        Date.new(year:, month:, day:) if Civil.civil?(year, month, day)
+      end
+
+      # Read as the reference's ISO parser reads one: a T or a space between
+      # the date and the time; a fraction after a full stop or a comma, of
+      # any count of digits (read to microseconds; the encoder writes none or
+      # six); and an offset of Z, +HH:MM, +HHMM or +HH (either sign) read as
+      # the instant it names. The one offset refused is the literal "-00:00";
+      # "-0000" and "-00" read as UTC, as the reference reads them. An offset
+      # that moves the instant outside the years 0 to 9999 is refused, since
+      # the encoder could not write it back.
+      def read_datetime(text)
+        match = text.is_a?(String) && DATETIME_TEXT.match(text)
+        return unless match
+
+        *parts, fraction, zone = match.captures
+        offset = read_offset(zone)
+        local = offset && local_instant(parts.map { |part| Integer(part, 10) }, fraction)
+        local && in_carried_years(local.with(epoch_seconds: local.epoch_seconds - offset))
+      end
+
+      def in_carried_years(instant)
+        instant if Civil.date_of(instant).year.between?(0, 9999)
+      end
+
+      def local_instant((year, month, day, hour, minute, second), fraction)
+        return unless Civil.civil?(year, month, day) && hour <= 23 && minute <= 59 && second <= 59
+
+        microsecond = Integer("#{fraction}000000"[0, 6], 10)
+        Civil.instant_at(Date.new(year:, month:, day:), hour, minute, second, microsecond:)
+      end
+
+      def read_offset(zone)
+        return 0 if zone == "Z"
+        return if zone == "-00:00"
+
+        sign, hours, minutes = OFFSET_TEXT.match(zone).captures
+        hours = hours.to_i # two digits, by OFFSET_TEXT
+        minutes = minutes.to_i # two digits, or absent and zero
+        seconds = (hours * 3600) + (minutes * 60)
+        return if hours > 23 || minutes > 59
+
+        sign == "-" ? -seconds : seconds
+      end
+
+      # The seven units are always written; milliseconds only when it is not
+      # zero, so an absent one reads as zero.
+      def read_duration(json)
+        return unless json.is_a?(Hash) && (DURATION_UNITS - json.keys).empty?
+        return unless (json.keys - DURATION_UNITS - ["milliseconds"]).empty? && json.values.all?(Integer)
+
+        Duration.new(**json.transform_keys(&:to_sym))
+      end
+    end
+    private_constant :Reader
+  end
+end

data/lib/predicator/tagged/writer.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Tagged
+    # Value to text: the encoding half of the codec.
+    # A private constant of Tagged: its functions are reached only through
+    # Tagged.decode and Tagged.encode, which document what they answer.
+    #
+    # @api private
+    module Writer
+      DURATION_UNITS = %w[years months weeks days hours minutes seconds].freeze
+      LITERALS = { nil => "null", true => "true", false => "false" }.freeze
+
+      module_function
+
+      def write(value) = text(value, 1, {}.compare_by_identity)
+
+      def text(value, depth, ancestors)
+        return LITERALS.fetch(value) if LITERALS.key?(value)
+
+        case value
+        when Integer then value.to_s
+        when Float then float(value)
+        when String then string(value)
+        when Array, Hash then container(value, depth, ancestors)
+        else tag(value, depth)
+        end
+      end
+
+      def float(value)
+        Refused.raise!("non_finite_number", "the float #{value} is not finite") unless value.finite?
+        value.to_s
+      end
+
+      # A String in another encoding is written as its UTF-8 transcoding; one
+      # that is not valid in its own encoding, or has no UTF-8 form, is not a
+      # predicator string.
+      def string(value)
+        utf8 = value.valid_encoding? ? value.encode(Encoding::UTF_8) : nil
+        JSON.generate(utf8 || Refused.raise!("unsupported_value", "#{value.inspect} has no UTF-8 form"))
+      rescue EncodingError
+        Refused.raise!("unsupported_value", "#{value.inspect} has no UTF-8 form")
+      end
+
+      def container(value, depth, ancestors)
+        deep(depth)
+        Refused.raise!("cyclic_value", "the value contains itself") if ancestors.key?(value)
+
+        ancestors[value] = true
+        written = value.is_a?(Array) ? list(value, depth, ancestors) : map(value, depth, ancestors)
+        ancestors.delete(value)
+        written
+      end
+
+      def deep(depth)
+        Refused.raise!("depth_limit_exceeded", "the value nests past #{DEPTH_LIMIT} levels") if depth > DEPTH_LIMIT
+      end
+
+      def list(list, depth, ancestors)
+        "[#{list.map { |member| text(member, depth + 1, ancestors) }.join(",")}]"
+      end
+
+      def map(map, depth, ancestors)
+        Refused.raise!("reserved_map_key", "a map with a \"$type\" key would read back as a tag") if map.key?("$type")
+
+        members = map.map do |key, member|
+          Refused.raise!("unsupported_value", "a map key is a String, not #{key.inspect}") unless key.is_a?(String)
+          "#{string(key)}:#{text(member, depth + 1, ancestors)}"
+        end
+        "{#{members.join(",")}}"
+      end
+
+      # A tag is one level of braces; a duration's value is a second.
+      def tag(value, depth)
+        written = tag_text(value)
+        deep(depth + (value.is_a?(Duration) ? 1 : 0))
+        written
+      end
+
+      def tag_text(value)
+        case value
+        when Undefined then '{"$type":"undefined"}'
+        when Date then %({"$type":"date","value":"#{carried(value, value.year)}"})
+        when DateTime then %({"$type":"datetime","value":"#{carried(value, Civil.date_of(value).year)}"})
+        when Duration then duration(value)
+        else Refused.raise!("unsupported_value", "#{value.inspect} is not a predicator value")
+        end
+      end
+
+      # The encoding carries four-digit years; a date or an instant outside
+      # them has no text that reads back as itself.
+      def carried(value, year)
+        return value.to_s if year.between?(0, 9999)
+
+        Refused.raise!("invalid_tagged_value", "#{value.inspect} is outside the years 0 to 9999 the encoding carries")
+      end
+
+      def duration(value)
+        units = DURATION_UNITS.map { |unit| %("#{unit}":#{value.public_send(unit)}) }
+        units << %("milliseconds":#{value.milliseconds}) unless value.milliseconds.zero?
+        %({"$type":"duration","value":{#{units.join(",")}}})
+      end
+    end
+    private_constant :Writer
+  end
+end

data/lib/predicator/tagged.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "values"
+require_relative "errors"
+require_relative "result"
+
+module Predicator
+  # A codec for the conformance corpus's tagged-value encoding, loaded with
+  # `require "predicator/tagged"` and by nothing else in the package.
+  #
+  # JSON carries most of predicator's values as themselves: integers, floats,
+  # strings, booleans, lists, maps (objects with String keys) and null (Ruby's
+  # nil). Four do not fit, and the encoding carries each as an object with a
+  # `$type` key:
+  #
+  #   {"$type":"date","value":"2026-08-06"}                    a Predicator::Date
+  #   {"$type":"datetime","value":"2026-08-06T12:00:00Z"}      a Predicator::DateTime
+  #   {"$type":"duration","value":{"years":0,...,"seconds":0}} a Predicator::Duration
+  #   {"$type":"undefined"}                                    Predicator::UNDEFINED
+  #
+  # The encoding is the corpus's apparatus, specified by predicator-ex's
+  # conformance/README.md at the tag conformance/SOURCE.json names. It is
+  # offered here for a host that persists instructions or values as JSON; it
+  # is not part of what conformance means.
+  #
+  # Both directions answer a {Predicator::Result}, a failed one carrying a
+  # {CodecError}, whatever the text or the value holds (decode raises
+  # ArgumentError only when it is handed something other than a String);
+  # {decode!} and {encode!} raise {Predicator::Error} instead. An
+  # integer stays an Integer and a float a Float across a round trip: `1`
+  # decodes to 1 and `1.0` to 1.0, and 1.0 encodes as `1.0`.
+  module Tagged
+    # The deepest a text may nest its brackets and braces, 100 levels, a
+    # tag's own braces counted. Both directions hold to it, so every text
+    # {encode} writes is one {decode} reads.
+    DEPTH_LIMIT = 100
+    private_constant :DEPTH_LIMIT
+
+    # Why a text could not be decoded or a value encoded. Its reason is one
+    # of these tokens:
+    #
+    # - "malformed_json": the text is not JSON (or not UTF-8)
+    # - "depth_limit_exceeded": the text or value nests past 100 levels
+    # - "non_finite_number": a number that is not finite
+    # - "invalid_tagged_value": an object with a `$type` key that is not one
+    #   of the four tags, or a tag whose value is not what the tag carries;
+    #   on encode, a date or a datetime outside the years the encoding carries
+    # - "reserved_map_key": on encode, a map with a `$type` key, which would
+    #   read back as a tag
+    # - "cyclic_value": on encode, a list or map that contains itself
+    # - "unsupported_value": on encode, something that is not a predicator
+    #   value (a Symbol, a map key that is not a String, a String with no
+    #   UTF-8 form, any other object)
+    #
+    # @!attribute [r] reason
+    #   @return [String] the token
+    # @!attribute [r] message
+    #   @return [String] a sentence for a person
+    CodecError = Data.define(:reason, :message) do
+      # @return [String] "CodecError"
+      def type = "CodecError"
+    end
+
+    # Signals a refusal from inside a walk; never leaves this module.
+    class Refused < StandardError
+      attr_reader :reason
+
+      def initialize(reason, message)
+        @reason = reason
+        super(message)
+      end
+
+      def self.raise!(reason, message) = raise(new(reason, message))
+    end
+    private_constant :Refused
+
+    # Decodes a text in the tagged encoding into a predicator value.
+    #
+    # @example
+    #   Predicator::Tagged.decode('{"x":{"$type":"undefined"}}').value
+    #   # => {"x" => Predicator::UNDEFINED}
+    #
+    # @param text [String]
+    # @return [Result] the value, or a {CodecError}
+    # @raise [ArgumentError] when text is not a String
+    def self.decode(text)
+      raise ArgumentError, "decode takes a String, not #{text.class}" unless text.is_a?(String)
+
+      refusing { Reader.read(text) }
+    end
+
+    # As {decode}, answering the value itself.
+    #
+    # @param text [String]
+    # @return [Object] the value
+    # @raise [Predicator::Error] carrying the {CodecError}
+    def self.decode!(text) = unwrap(decode(text))
+
+    # Encodes a predicator value as text in the tagged encoding.
+    #
+    # @example
+    #   Predicator::Tagged.encode([1, 1.0, Predicator::Date.new(2026, 8, 6)]).value
+    #   # => '[1,1.0,{"$type":"date","value":"2026-08-06"}]'
+    #
+    # @param value [Object]
+    # @return [Result] the text, or a {CodecError}
+    def self.encode(value) = refusing { Writer.write(value) }
+
+    # As {encode}, answering the text itself.
+    #
+    # @param value [Object]
+    # @return [String] the text
+    # @raise [Predicator::Error] carrying the {CodecError}
+    def self.encode!(value) = unwrap(encode(value))
+
+    def self.refusing
+      Results.ok(yield)
+    rescue Refused => e
+      Results.failure(CodecError.new(reason: e.reason, message: e.message))
+    end
+
+    def self.unwrap(result)
+      raise Error, result.error unless result.ok?
+
+      result.value
+    end
+
+    private_class_method :refusing, :unwrap
+  end
+end
+
+require_relative "tagged/reader"
+require_relative "tagged/writer"

data/lib/predicator/values.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "civil"
+
+module Predicator
+  # predicator's undefined: an absence, where no value was ever supplied. It
+  # is a value of its own and never Ruby's nil, which is predicator's null (a
+  # value that is present and empty); the two are distinct in the language.
+  # There is exactly one instance, {Predicator::UNDEFINED}, compared by
+  # identity. The class is private to the package; the instance is the
+  # value a host holds.
+  class Undefined
+    # @return [String] how the one instance prints
+    def inspect = "Predicator::UNDEFINED"
+    alias to_s inspect
+
+    # The one instance is its own copy, so identity survives a dup or clone.
+    # @return [Undefined] self
+    def dup = self
+
+    # @return [Undefined] self
+    def clone(**) = self
+
+    private_class_method :new
+  end
+
+  # The one {Undefined} instance.
+  UNDEFINED = Undefined.send(:new).freeze
+  private_constant :Undefined
+
+  # A civil date: a year, a month and a day on the proleptic Gregorian
+  # calendar, with no time of day and no zone. It is an immutable value,
+  # equal to and hashed like any other date with the same three parts.
+  #
+  # @!attribute [r] year
+  #   @return [Integer] the year; any Integer, though the tagged encoding
+  #     carries 0 to 9999 only
+  # @!attribute [r] month
+  #   @return [Integer] the month, 1 to 12
+  # @!attribute [r] day
+  #   @return [Integer] the day of the month, 1 to the month's length
+  Date = Data.define(:year, :month, :day) do
+    # @param year [Integer]
+    # @param month [Integer]
+    # @param day [Integer]
+    # @raise [ArgumentError] unless the three parts name a calendar date
+    def initialize(year:, month:, day:)
+      unless Civil.civil?(year, month, day)
+        raise ArgumentError, "#{[year, month, day].inspect} does not name a calendar date"
+      end
+
+      super
+    end
+
+    # The date as ISO 8601 text, `YYYY-MM-DD`, for a year from 0 to 9999.
+    # Other years are written with as many digits as they take and a leading
+    # minus sign below zero, which ISO 8601 leaves to agreement.
+    #
+    # @return [String]
+    def to_s
+      digits = format("%04d", year.abs)
+      "#{"-" if year.negative?}#{digits}-#{format("%02d", month)}-#{format("%02d", day)}"
+    end
+
+    # @return [String]
+    def inspect = "#<Predicator::Date #{self}>"
+  end
+
+  # An instant in UTC: a whole number of seconds since 1970-01-01T00:00:00Z
+  # and a microsecond within that second, the sub-second precision the
+  # reference's ISA states for an instant. It is an immutable value, equal to
+  # and hashed like any other at the same instant.
+  #
+  # @!attribute [r] epoch_seconds
+  #   @return [Integer] whole seconds since the epoch, negative before it
+  # @!attribute [r] microsecond
+  #   @return [Integer] the microsecond of that second, 0 to 999999
+  DateTime = Data.define(:epoch_seconds, :microsecond) do
+    # @param epoch_seconds [Integer]
+    # @param microsecond [Integer] 0 to 999999
+    # @raise [ArgumentError] when a part is not an Integer in its range
+    def initialize(epoch_seconds:, microsecond: 0)
+      unless epoch_seconds.is_a?(Integer) && Civil.within?(microsecond, 999_999)
+        raise ArgumentError, "#{[epoch_seconds, microsecond].inspect} is not an instant"
+      end
+
+      super
+    end
+
+    # The instant as canonical ISO 8601 text in UTC: the fraction left out
+    # when the microsecond is zero and exactly six digits when it is not
+    # (the form the tagged encoding and the reference's string cast both
+    # write).
+    #
+    # @return [String]
+    def to_s
+      fraction = microsecond.zero? ? "" : format(".%06d", microsecond)
+      format("%<date>sT%<hour>02d:%<minute>02d:%<second>02d%<fraction>sZ",
+             date: Civil.date_of(self), hour:, minute:, second:, fraction:)
+    end
+
+    # @return [String]
+    def inspect = "#<Predicator::DateTime #{self}>"
+
+    private
+
+    # The hour of the day, 0 to 23, the minute and the second, in UTC.
+    def hour = seconds_of_day / 3600
+    def minute = (seconds_of_day % 3600) / 60
+    def second = seconds_of_day % 60
+
+    def seconds_of_day = epoch_seconds % Civil::SECONDS_PER_DAY
+  end
+
+  # A duration: the eight units the reference's duration carries, every one
+  # present and defaulting to zero. The set never varies with the units an
+  # expression named. It is an immutable value.
+  #
+  # @!attribute [r] years
+  #   @return [Integer]
+  # @!attribute [r] months
+  #   @return [Integer]
+  # @!attribute [r] weeks
+  #   @return [Integer]
+  # @!attribute [r] days
+  #   @return [Integer]
+  # @!attribute [r] hours
+  #   @return [Integer]
+  # @!attribute [r] minutes
+  #   @return [Integer]
+  # @!attribute [r] seconds
+  #   @return [Integer]
+  # @!attribute [r] milliseconds
+  #   @return [Integer]
+  Duration = Data.define(:years, :months, :weeks, :days, :hours, :minutes, :seconds, :milliseconds) do
+    # Every unit given defaults to zero.
+    #
+    # @raise [ArgumentError] when a unit is not an Integer
+    def initialize(years: 0, months: 0, weeks: 0, days: 0, hours: 0, minutes: 0, seconds: 0, milliseconds: 0)
+      units = { years:, months:, weeks:, days:, hours:, minutes:, seconds:, milliseconds: }
+      wrong = units.reject { |_, amount| amount.is_a?(Integer) }
+      raise ArgumentError, "a duration's units are Integers: #{wrong.inspect}" unless wrong.empty?
+
+      super(**units)
+    end
+  end
+end

data/lib/predicator/version.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 module Predicator
-  VERSION = "1.2.1"
+  # The gem's version.
+  VERSION = "2.0.0"
 end