predicator 1.2.0 → 2.0.0

data/lib/predicator/evaluator/order.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # The order of two values for the ordering operators of `compare`, as
+    # the reference's ISA (docs/isa.md, section 5, `compare`) states it.
+    # Pairs are matched and compared for equality by {Compare}.
+    #
+    # The module holds no state.
+    module Order
+      # The answer a list walk gives for a member pair that does not decide
+      # the order, so the walk steps to the next position.
+      LEVEL = :level
+
+      # Where each kind of member sits in the reference's term order, for a
+      # member pair of two different kinds: a number, then false, null, true
+      # and undefined, then the map-like values (a map, a duration, a date, a
+      # datetime), then a list, then a string.
+      MEMBER_RANKS = { number: 0, map: 5, duration: 5, chronological: 5, list: 6, string: 7 }.freeze
+
+      # The rank of each member that is one value of its own kind.
+      SINGLE_RANKS = { false => 1, nil => 2, true => 3 }.freeze
+
+      module_function
+
+      # The order of a type-matched pair (-1, 0 or 1), or nil when the pair
+      # has none. Strings order by byte, which for UTF-8 is code point order
+      # and no collation. Two maps and two durations have no order: the
+      # reference leaves map ordering unspecified for a sibling.
+      def order(left, right) = Compare.peers?(left, right) ? peer_order(left, right) : nil
+
+      def peer_order(left, right)
+        case Compare.kind(left)
+        when :number, :string then left <=> right
+        when :boolean then (left ? 1 : 0) <=> (right ? 1 : 0)
+        when :chronological then Compare.instant(left) <=> Compare.instant(right)
+        when :list then list_order(left, right)
+        end
+      end
+
+      # Two lists from the front: the first member pair that differs decides,
+      # and a proper prefix orders before the longer list.
+      #
+      # The walk is iterative: a member pair of two lists is walked as a list
+      # of its own on an explicit stack of frames (the two lists and the
+      # position reached), so lists nested deeper than the stack are ordered
+      # rather than exhausting it. Any answer other than level decides the
+      # whole order at once. A nested pair that ends level (every member
+      # pair level, the sizes equal) is equal by instant, which is what makes
+      # a member pair level, so its parent steps to the next position.
+      def list_order(left, right)
+        frames = [[left, right, 0]]
+        until frames.empty?
+          step = frame_step(frames)
+          return step unless step == LEVEL
+        end
+        LEVEL
+      end
+
+      # One step of the walk over the top frame: LEVEL to go on, else the
+      # whole walk's answer.
+      def frame_step(frames)
+        outer, inner, at = frames.last
+        return frame_end(frames) if at == [outer.size, inner.size].min
+
+        frames.last[2] = at + 1
+        pair = [outer[at], inner[at]]
+        pair.all?(Array) ? descend(frames, pair) : member_order(*pair)
+      end
+
+      # Walks a member pair of two lists as a frame of its own.
+      def descend(frames, pair)
+        frames.push([*pair, 0])
+        LEVEL
+      end
+
+      # The end of the top frame, its lists ordered by size: that order
+      # decides the walk when it is not level or when it is the outermost
+      # frame.
+      def frame_end(frames)
+        outer, inner, = frames.pop
+        order = outer.size <=> inner.size
+        frames.empty? || !order.zero? ? order : LEVEL
+      end
+
+      # One member pair of a list walk: LEVEL when it does not decide, else
+      # the order it decides, or nil when it has none. Two members of
+      # different kinds are placed by the reference's term order (rank); two
+      # nulls, two undefineds, two falses or two trues are level; a date
+      # member orders before a datetime member, as term order places them.
+      def member_order(left, right)
+        ranks = [rank(left), rank(right)]
+        return ranks.first <=> ranks.last unless ranks.first == ranks.last
+        return LEVEL if (1..4).cover?(ranks.first)
+        return left.is_a?(Predicator::Date) ? -1 : 1 if Compare.date_against_datetime?(left, right)
+        return LEVEL if Compare.loose_equal?(left, right, by_instant: left.is_a?(Hash) && right.is_a?(Hash))
+
+        differing_order(left, right)
+      end
+
+      # A member pair of one kind that is not equal: its order, LEVEL when it
+      # orders level and is equal by instant, or nil.
+      def differing_order(left, right)
+        order = order(left, right)
+        return order unless order&.zero?
+
+        Compare.loose_equal?(left, right, by_instant: true) ? LEVEL : nil
+      end
+
+      # A member's rank in term order (MEMBER_RANKS, SINGLE_RANKS); undefined
+      # ranks 4. A value outside the domain has no rank.
+      def rank(member)
+        return 4 if Compare.undefined?(member)
+
+        SINGLE_RANKS.fetch(member) { MEMBER_RANKS[Compare.kind(member)] }
+      end
+    end
+    private_constant :Order
+  end
+end

data/lib/predicator/evaluator/rich_types.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # A clock that failed: it answered something other than a
+    # {Predicator::DateTime}, or raised a StandardError. Raised by the read of
+    # the clock wherever an instruction reads the time, and rescued by the
+    # run's loop ({Machine}), which stops the run with the EvaluationError it
+    # carries (reason clock_failed). It never leaves an evaluation.
+    class ClockFault < StandardError
+      attr_reader :error
+
+      def initialize(message)
+        @error = EvaluationError.new(reason: "clock_failed", message:)
+        super
+      end
+    end
+    private_constant :ClockFault
+
+    # The rich-type opcodes, as the reference's ISA (docs/isa.md, section 5)
+    # states them: the handlers {Machine} runs for `duration`,
+    # `relative_date`, `object_new` and `object_set`.
+    #
+    # `relative_date` is the one opcode here whose answer depends on the
+    # time. It reads the clock the caller passed to the evaluation, through
+    # `now`, which reads that clock at most once per evaluation.
+    #
+    # A duration is read as the map the ISA (section 3) makes it: its eight
+    # units under their names. So `relative_date` takes a duration or a
+    # plain map, whose unit names it reads (an absent unit is zero, any
+    # other key is ignored, and a unit that is not an Integer is refused);
+    # and `object_set` writes into a plain map or a duration, which answers
+    # a plain map of its eight units and the key written. Any other value,
+    # a date and a datetime included (section 3 types them apart from a
+    # map), is refused with the reason section 5 names for a non-map,
+    # invalid_stack_value.
+    module RichTypes
+      # Every unit spelling `duration` accepts, and the unit each names.
+      UNIT_SPELLINGS = {
+        years: %w[y year years], months: %w[mo month months], weeks: %w[w week weeks],
+        days: %w[d day days], hours: %w[h hour hours], minutes: %w[m min minute minutes],
+        seconds: %w[s sec second seconds], milliseconds: %w[ms millisecond milliseconds]
+      }.flat_map { |unit, spellings| spellings.map { |spelling| [spelling, unit] } }.to_h.freeze
+
+      # Which way each direction `relative_date` accepts moves the time.
+      DIRECTIONS = { "ago" => -1, "last" => -1, "future" => 1, "next" => 1 }.freeze
+
+      private
+
+      # Pushes the duration the unit pairs name, every unit they do not name
+      # at zero. A later pair naming a unit overwrites an earlier one. A pair
+      # that is not an Integer and a String is refused before its unit is
+      # read, and pairs are read in order, so the first bad pair decides.
+      def duration(at, pairs)
+        units = {}
+        pairs.each do |pair|
+          return invalid_duration("invalid_duration_format", "is not [integer, unit]", pair) unless unit_pair?(pair)
+
+          unit = UNIT_SPELLINGS[pair.last]
+          return invalid_duration("invalid_duration_unit", "names no unit", pair) unless unit
+
+          units[unit] = pair.first
+        end
+        push(at, Duration.new(**units))
+      end
+
+      def unit_pair?(pair) = pair.is_a?(Array) && pair.size == 2 && pair.first.is_a?(Integer) && pair.last.is_a?(String)
+
+      def invalid_duration(reason, says, pair)
+        EvaluationError.new(reason:, message: "duration pair #{pair.inspect} #{says}")
+      end
+
+      # Pops a duration, or a map read as one, and pushes the evaluation's
+      # current time moved by it: back for "ago" and "last", forward for
+      # "future" and "next". The stack depth is checked first, then the
+      # popped value, then the direction.
+      def relative_date(at, direction)
+        return insufficient("relative_date") if @stack.empty?
+
+        moved = as_duration(@stack.pop)
+        return invalid_stack_value("relative_date", "a duration") unless moved
+
+        sign = DIRECTIONS[direction]
+        unless sign
+          return EvaluationError.new(reason: "invalid_direction",
+                                     message: "relative_date does not accept #{direction.inspect}")
+        end
+
+        push(at, Chronology.shift(now, moved, sign))
+      end
+
+      # The current time of this evaluation: the clock's answer the first
+      # time it is asked for, and the same instant every time after. A clock
+      # that answers anything but a {Predicator::DateTime}, or raises a
+      # StandardError, raises ClockFault, which stops the run with a failed
+      # result whichever instruction read it; an exception that is not a
+      # StandardError propagates.
+      def now = @now ||= read_clock
+
+      def read_clock
+        instant = @clock.call
+        return instant if instant.is_a?(Predicator::DateTime)
+
+        raise ClockFault, "the clock answered #{instant.inspect}, not a Predicator::DateTime"
+      rescue ClockFault
+        raise
+      rescue StandardError => e
+        raise ClockFault, "the clock raised: #{e.inspect}"
+      end
+
+      # A duration as it is, a plain map as the duration its unit names make
+      # (an absent unit zero, any other key ignored), or nil when the value
+      # is neither or a unit is not an Integer.
+      def as_duration(value)
+        return value if value.is_a?(Duration)
+        return unless value.is_a?(Hash)
+
+        units = Access::DURATION_UNITS.to_h { |name| [name.to_sym, value.fetch(name, 0)] }
+        Duration.new(**units) if units.each_value.all?(Integer)
+      end
+
+      def object_new(at) = push(at, {})
+
+      # Pops the value, then the map beneath it, and pushes a copy of that
+      # map with key set to the value. The map popped is not changed: it may
+      # be one the context holds. A duration beneath the value is the map of
+      # its eight units, so the answer is a plain map. The depth is checked
+      # before the map.
+      def object_set(at, key)
+        return insufficient("object_set") if @stack.size < 2
+
+        value = @stack.pop
+        target = @stack.pop
+        target = Access.units(target) if target.is_a?(Duration)
+        return invalid_stack_value("object_set", "a map beneath the value") unless target.is_a?(Hash)
+
+        push(at, target.merge(key => value))
+      end
+
+      def invalid_stack_value(opcode, wanted)
+        EvaluationError.new(reason: "invalid_stack_value", message: "#{opcode} expects #{wanted}")
+      end
+    end
+    private_constant :RichTypes
+  end
+end

data/lib/predicator/evaluator/statements.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # The statement opcodes and the statement-level jumps, as the reference's
+    # ISA (docs/isa.md, section 5) states them: the handlers {Machine} runs
+    # for `store`, `pop`, `jump`, `pop_jump_if_falsy` and `jump_backward`.
+    #
+    # `store` is the one opcode that writes the context. It never changes a
+    # map or a list it writes through: each write builds a new context that
+    # shares every branch the path does not pass through, so the context the
+    # caller passed stays as it was, and a refused write leaves no partial
+    # write behind ({Location}).
+    #
+    # `jump_backward` is the one back edge. Each back edge taken spends one
+    # of the evaluation's loop budget; one that finds the budget spent stops
+    # the run with loop_budget_exceeded, so a budget of n lets n back edges
+    # through. A program with no back edge halts within its length in steps,
+    # since every other jump goes forward.
+    module Statements
+      private
+
+      # Pops the value, then count location segments beneath it, and writes
+      # the value into the context at the path those segments name, the
+      # deepest-pushed segment first (the root). Too few values is
+      # insufficient operands; a segment that is not a String or an Integer
+      # is a type mismatch, checked before anything is written; a write the
+      # path cannot take is refused as {Location} says. Pushes nothing.
+      def store(at, count)
+        return insufficient("store") if @stack.size < count + 1
+
+        value = @stack.pop
+        path = @stack.pop(count)
+        bad = path.index { |segment| !segment.is_a?(String) && !segment.is_a?(Integer) }
+        return mismatch("store", "a string or an integer segment", path[bad]) if bad
+
+        written = Location.put(@context, path, value)
+        return written if written.is_a?(EvaluationError)
+
+        @context = written
+        at + 1
+      end
+
+      # `pop`, the statement boundary: discards the stack top, keeping it as
+      # the value statement mode answers. An empty stack is insufficient
+      # operands; the empty_stack rule belongs to the halt alone.
+      def discard(at)
+        return insufficient("pop") if @stack.empty?
+
+        @last_value = @stack.pop
+        at + 1
+      end
+
+      def jump(at, offset) = at + offset
+
+      # Pops the condition whatever it is: false, null and undefined jump,
+      # exactly true falls through, and anything else is a type mismatch.
+      def pop_jump_if_falsy(at, offset)
+        return insufficient("pop_jump_if_falsy") if @stack.empty?
+
+        condition = @stack.pop
+        truth = truth(condition)
+        return mismatch("pop_jump_if_falsy", "a boolean", condition) if truth.nil?
+
+        truth ? at + 1 : at + offset
+      end
+
+      # A target before the first instruction is a malformed operand, an
+      # unknown instruction, whatever the budget holds.
+      def jump_backward(at, offset)
+        return unknown(at) if offset > at
+        return loop_budget_exceeded if @budget.zero?
+
+        @budget -= 1
+        at - offset
+      end
+
+      def loop_budget_exceeded
+        EvaluationError.new(reason: "loop_budget_exceeded",
+                            message: "the loop budget is spent at a backward jump")
+      end
+    end
+    private_constant :Statements
+
+    # The write `store` makes, as the reference writes a location: each
+    # interior slot that is missing, null or undefined becomes a list when
+    # the segment after it is an Integer and a map otherwise; a duration is
+    # written through as the plain map of its eight units; the leaf is
+    # overwritten whatever it holds. A map takes a String or an Integer key.
+    # A list takes an index of at least 0, and an index past its end pads the
+    # gap with undefined. Every container on the path is copied, never
+    # changed.
+    #
+    # The refusals are EvaluationErrors: not_assignable for an empty path,
+    # not_a_container for a slot that holds anything else (a date and an
+    # instant included) or a list given a String, and invalid_index for a
+    # negative index.
+    module Location
+      # The context with value written at path, or the EvaluationError that
+      # refuses the write.
+      def self.put(context, path, value)
+        return refusal("not_assignable", "store has no location to write") if path.empty?
+
+        catch(:refused) { write(context, path, value) }
+      end
+
+      def self.write(container, path, value)
+        segment, *rest = path
+        return set(container, segment, value) if rest.empty?
+
+        set(container, segment, write(vivify(fetch(container, segment), rest.first), rest, value))
+      end
+
+      def self.fetch(container, segment)
+        return container.fetch(segment, nil) if container.is_a?(Hash)
+
+        index!(segment)
+        container[segment]
+      end
+
+      def self.vivify(slot, following)
+        case slot
+        when nil, UNDEFINED then following.is_a?(Integer) ? [] : {}
+        when Hash, Array then slot
+        when Duration then Access.units(slot)
+        else throw :refused, refusal("not_a_container", "store cannot write into #{slot.inspect}")
+        end
+      end
+
+      def self.set(container, segment, value)
+        return container.merge(segment => value) if container.is_a?(Hash)
+
+        index!(segment)
+        list = container.dup
+        list.fill(UNDEFINED, list.size...segment)
+        list[segment] = value
+        list
+      end
+
+      def self.index!(segment)
+        throw :refused, refusal("not_a_container", "store cannot write a key into a list") unless segment.is_a?(Integer)
+        throw :refused, refusal("invalid_index", "store cannot write at index #{segment}") if segment.negative?
+      end
+
+      def self.refusal(reason, message) = EvaluationError.new(reason:, message:)
+
+      private_class_method :write, :fetch, :vivify, :set, :index!, :refusal
+    end
+    private_constant :Location
+  end
+end