predicator 1.2.1 → 2.0.0

data/lib/predicator/emitter/chains.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Emitter
+    # Chains, emitted into the walk that includes this module. A chain is a
+    # run of nodes each leaning on the one child the source writes beside it
+    # rather than inside it: a postfix step's object, a binary operator's
+    # left operand. The parser reads a chain in a loop, and so does this
+    # walk: it collects the spine, emits the innermost operand, then each
+    # link from the inside out, which is the post-order a recursive walk
+    # would give. Only the spine is flattened; a right operand or a key goes
+    # through the walk a level deeper.
+    module Chains
+      # The nodes a chain is made of.
+      KINDS = [Ast::PropertyAccess, Ast::BracketAccess, Ast::Cast, Ast::Comparison, Ast::Arithmetic,
+               Ast::Membership, Ast::LogicalAnd, Ast::LogicalOr].freeze
+
+      private
+
+      def chain(root)
+        spine = [root]
+        spine << leaning(spine.last) while KINDS.include?(leaning(spine.last).class)
+        spine.reverse.each_with_object(visit(leaning(spine.last))) { |node, out| link(node, out) }
+      end
+
+      def leaning(node)
+        case node
+        when Ast::PropertyAccess, Ast::BracketAccess then node.object
+        when Ast::Cast then node.expression
+        else node.left
+        end
+      end
+
+      # Appends one link's own instructions to the chain emitted so far.
+      def link(node, out)
+        case node
+        when Ast::LogicalAnd, Ast::LogicalOr then jump_over(node, out)
+        when Ast::PropertyAccess, Ast::Cast then out << own(node, step(node))
+        else out.concat(visit(node.is_a?(Ast::BracketAccess) ? node.key : node.right)) << own(node, step(node))
+        end
+      end
+
+      # The instruction a link emits after its operands.
+      def step(node)
+        case node
+        when Ast::PropertyAccess then ["access", node.property]
+        when Ast::Cast then ["cast", node.type_name]
+        when Ast::BracketAccess then ["bracket_access"]
+        else OPCODES.fetch(node.operator).dup
+        end
+      end
+
+      # `and` and `or`: a jump between the operands, past the right one.
+      def jump_over(node, out)
+        right = visit(node.right)
+        opcode = node.is_a?(Ast::LogicalAnd) ? "jump_if_falsy_or_pop" : "jump_if_true_or_pop"
+        out.push(own(node, [opcode, right.size + 1])).concat(right)
+      end
+    end
+    private_constant :Chains
+  end
+end

data/lib/predicator/emitter/statements.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Emitter
+    # A program's statements, emitted into the walk that includes this
+    # module. Every statement leaves the stack as it found it: an assignment
+    # ends in the `store` that consumes its value, an expression in a `pop`,
+    # and an `if` or a `while` consumes its condition in the jump that tests
+    # it. The jumps are relative, counted from the jump itself, and carry the
+    # statement's own position and span.
+    module Statements
+      # The instructions of a statement sequence, one statement after
+      # another.
+      def statements(list) = list.each_with_object([]) { |statement, out| out.concat(statement(statement)) }
+
+      private
+
+      def statement(node)
+        case node
+        when Ast::Assignment then assignment(node)
+        when Ast::If then if_statement(node)
+        when Ast::While then while_statement(node)
+        else visit(node) << own(node, ["pop"])
+        end
+      end
+
+      # The condition, a falsy jump past the then block (and past the jump
+      # that ends it, when there is an else block), the block, then that
+      # jump past the else block.
+      def if_statement(node)
+        then_block = block(node.then_block)
+        else_block = node.else_block && block(node.else_block)
+        out = visit(node.condition) << own(node, ["pop_jump_if_falsy", then_block.size + (else_block ? 2 : 1)])
+        out.concat(then_block)
+        else_block ? jump_past(node, else_block, out) : out
+      end
+
+      # The jump that ends a then block, past the else block, then that block.
+      def jump_past(node, else_block, out) = out.push(own(node, ["jump", else_block.size + 1])).concat(else_block)
+
+      def block(node) = statements(node.statements)
+
+      # The condition, a falsy jump past the body and its back edge, the
+      # body, then the back edge to the condition's first instruction.
+      def while_statement(node)
+        out = visit(node.condition)
+        back = out.size
+        body = statements(node.body.statements)
+        out.push(own(node, ["pop_jump_if_falsy", body.size + 2])).concat(body)
+        out << own(node, ["jump_backward", back + body.size + 1])
+      end
+
+      # The location's segments root first, the value, and the store.
+      def assignment(node)
+        root, links = location(node.target)
+        out = [own(root, ["lit", root.name])]
+        segments = [root] + links.map { |link| segment(link, out) }
+        out.concat(visit(node.value))
+        out << Entry.new(instruction: ["store", segments.size], position: root.position, span: node.span, segments:)
+      end
+
+      # A location's root identifier and its accesses, root first.
+      def location(target)
+        links = []
+        while target.is_a?(Ast::PropertyAccess) || target.is_a?(Ast::BracketAccess)
+          links.unshift(target)
+          target = target.object
+        end
+        [target, links]
+      end
+
+      # Appends one access's segment, answering the node behind it: a
+      # property's name, or a bracket's key.
+      def segment(link, out)
+        if link.is_a?(Ast::BracketAccess)
+          out.concat(visit(link.key))
+          return link.key
+        end
+
+        out << own(link, ["lit", link.property])
+        link
+      end
+    end
+    private_constant :Statements
+  end
+end

data/lib/predicator/emitter.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require_relative "values"
+require_relative "errors"
+require_relative "lexer"
+require_relative "ast"
+require_relative "parser"
+require_relative "emitter/chains"
+require_relative "emitter/statements"
+
+module Predicator
+  # The compiler's last stage: the syntax tree the {Parser} builds in, the
+  # instruction list the evaluator runs out, or the one refusal that stopped
+  # it. It is a post-order walk, the reference's: an operand's instructions
+  # come before the instruction that consumes it, and the short-circuiting
+  # pair puts its jump between its two operands, since what the jump skips
+  # is the right one.
+  #
+  # The operands are predicator values, the ones the evaluator takes: a date
+  # literal is a {Predicator::Date}, a decimal a Float, `undefined`
+  # {Predicator::UNDEFINED}. Written in the conformance corpus's tagged
+  # encoding they are the corpus's instructions.
+  #
+  # The shapes the walk emits:
+  #
+  # - a literal is `lit`; a list whose every element is a literal or a
+  #   string is one `lit` carrying the list, and any other list is its
+  #   elements then `make_list`;
+  # - an object is `object_new`, then each entry's value and an
+  #   `object_set` of its key, in the order written;
+  # - `a and b` is `a`, a `jump_if_falsy_or_pop` past `b`, then `b`; `or`
+  #   the same with `jump_if_true_or_pop`;
+  # - in a program, an assignment is its location's segments (the root's
+  #   name, each property's name, each bracket's key), its value and a
+  #   `store` of the segment count; any other expression statement is the
+  #   expression and a `pop`; an `if` is its condition, a
+  #   `pop_jump_if_falsy` past the then block (and past the `jump` that ends
+  #   it when there is an else block), the block, and that `jump` past the
+  #   else block; a `while` is its condition, a `pop_jump_if_falsy` past the
+  #   body and its back edge, the body, then a `jump_backward` to the
+  #   condition's first instruction.
+  #
+  # Each instruction is annotated with the position and the span of the node
+  # that emitted it ({Entry}); an `object_set` carries its key's, a `store`
+  # its location root's position and its statement's span, and a `pop` the
+  # expression's own. Every store also carries the node behind each segment
+  # of the location it writes: the root, each property access, each bracket
+  # key.
+  #
+  # One refusal is not the reference's, whose compiler raises there: a
+  # decimal literal too large for a finite Float is refused with the reason
+  # `number_out_of_range`, over the literal, as a value.
+  #
+  # A chain the parser read in a loop (nodes leaning on their left operand
+  # or their object, as a run of binary operators or of postfix steps
+  # builds) is walked in a loop here too, so a long chain takes no deeper a
+  # stack than a short one; anything nested inside a node is walked a level
+  # deeper, which the parser's depth limit bounds. Where the stack the walk
+  # runs on runs out all the same, the source is refused under the parser's
+  # reason, `nesting_depth_exceeded`, rather than raising.
+  #
+  # The module holds no state; each call walks with its own {Walk}. It is
+  # private to the package.
+  module Emitter
+    # One instruction and the node behind it: that node's position and span,
+    # and on a `store` the node behind each segment, root first (nil on any
+    # other instruction).
+    Entry = Data.define(:instruction, :position, :span, :segments)
+
+    # The message a decimal literal too large for a finite Float is refused
+    # with. The reference has none: its compiler raises there.
+    OUT_OF_RANGE = "Number literal is outside the range this implementation can represent"
+
+    # The opcode each operator node emits, frozen: each instruction emitted
+    # is a copy, so no caller holds the table's own arrays.
+    OPCODES = {
+      gt: %w[compare GT], lt: %w[compare LT], gte: %w[compare GTE], lte: %w[compare LTE],
+      equal_equal: %w[compare EQ], ne: %w[compare NE], strict_eq: %w[compare STRICT_EQ],
+      strict_ne: %w[compare STRICT_NE], add: ["add"], subtract: ["subtract"], multiply: ["multiply"],
+      divide: ["divide"], modulo: ["modulo"], in: ["in"], contains: ["contains"], minus: ["unary_minus"],
+      bang: ["unary_bang"]
+    }.transform_values(&:freeze).freeze
+
+    # The tag a refusal is thrown with, to the catch around a walk.
+    REFUSED = :refused
+
+    # Emits one expression.
+    #
+    # @param node [Object] an {Ast} node
+    # @return [Array<Entry>, Lexer::Refusal] the annotated instructions, or
+    #   the refusal
+    def self.emit(node) = Walk.new.run(node) { |walk| walk.visit(node) }
+
+    # Emits a program, one statement after another.
+    #
+    # @param program [Ast::Program]
+    # @return [Array<Entry>, Lexer::Refusal] the annotated instructions, or
+    #   the refusal
+    def self.emit_program(program) = Walk.new.run(program) { |walk| walk.statements(program.statements) }
+
+    # One walk of one tree. A refusal is thrown to the catch around the whole
+    # walk and is never seen outside this class.
+    class Walk
+      include Chains
+      include Statements
+
+      # The method that emits each kind of expression node.
+      VISITS = {
+        Ast::Literal => :literal, Ast::StringLiteral => :literal, Ast::Identifier => :identifier,
+        Ast::Unary => :prefixed, Ast::LogicalNot => :prefixed, Ast::ListLiteral => :list,
+        Ast::ObjectLiteral => :object, Ast::FunctionCall => :call, Ast::Duration => :duration,
+        Ast::RelativeDate => :relative_date
+      }.merge(Chains::KINDS.to_h { |kind| [kind, :chain] }).freeze
+
+      # The walk in the block, or the refusal it threw; a stack exhausted
+      # before the walk finished is refused over the whole tree.
+      def run(root)
+        catch(REFUSED) { yield self }
+      rescue SystemStackError
+        refuse(root, "nesting_depth_exceeded", "Expression nests deeper than the stack this compilation runs " \
+                                               "on can follow, short of the depth limit of " \
+                                               "#{Parser::DEPTH_LIMIT} levels", thrown: false)
+      end
+
+      # The instructions of one expression node.
+      def visit(node) = send(VISITS.fetch(node.class), node)
+
+      private
+
+      def literal(node) = [own(node, ["lit", value_of(node)])]
+
+      def identifier(node) = [own(node, ["load", node.name])]
+
+      # A unary operator or `not`: the operand, then the operator.
+      def prefixed(node)
+        visit(node.operand) << own(node, node.is_a?(Ast::LogicalNot) ? ["not"] : OPCODES.fetch(node.operator).dup)
+      end
+
+      # A list whose every element is a literal or a string is one `lit`
+      # carrying the list; any other list is its elements and `make_list`.
+      def list(node)
+        if node.elements.all? { |element| [Ast::Literal, Ast::StringLiteral].include?(element.class) }
+          return [own(node, ["lit", node.elements.map { |element| value_of(element) }])]
+        end
+
+        each_visited(node.elements) << own(node, ["make_list", node.elements.size])
+      end
+
+      # `object_new`, then each entry's value and an `object_set` carrying
+      # its key's position, in the order written.
+      def object(node)
+        node.entries.each_with_object([own(node, ["object_new"])]) do |(key, value), out|
+          out.concat(visit(value)) << own(key, ["object_set", key.name])
+        end
+      end
+
+      def call(node) = each_visited(node.arguments) << own(node, ["call", node.name, node.arguments.size])
+
+      # One instruction carrying the units in the order written.
+      def duration(node) = [own(node, ["duration", node.units.map { |amount, unit| [amount, unit] }])]
+
+      def relative_date(node) = visit(node.duration) << own(node, ["relative_date", node.direction.to_s])
+
+      def each_visited(nodes) = nodes.each_with_object([]) { |node, out| out.concat(visit(node)) }
+
+      # A literal's value; a Float the domain has no finite member for is
+      # refused over the literal.
+      def value_of(node)
+        value = node.value
+        refuse(node, "number_out_of_range", OUT_OF_RANGE) if value.is_a?(Float) && !value.finite?
+        value
+      end
+
+      def own(node, instruction) = Entry.new(instruction:, position: node.position, span: node.span, segments: nil)
+
+      # The refusal over a node, thrown to the catch around the walk or,
+      # outside it, answered.
+      def refuse(node, reason, message, thrown: true)
+        refusal = Lexer::Refusal.new(error: ParseError.new(reason:, message:, position: node.position),
+                                     span: node.span)
+        thrown ? throw(REFUSED, refusal) : refusal
+      end
+    end
+    private_constant :Walk
+  end
+  private_constant :Emitter
+end

data/lib/predicator/errors.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Predicator
+  # A place in source text: a line and a column, both counted from 1. The
+  # reference reports positions in this shape.
+  #
+  # @!attribute [r] line
+  #   @return [Integer] the line, from 1
+  # @!attribute [r] column
+  #   @return [Integer] the column, from 1
+  Position = Data.define(:line, :column) do
+    # @raise [ArgumentError] unless both are Integers of at least 1
+    def initialize(line:, column:)
+      unless [line, column].all? { |part| part.is_a?(Integer) && part >= 1 }
+        raise ArgumentError, "a position is a line and a column from 1, not #{[line, column].inspect}"
+      end
+
+      super
+    end
+  end
+
+  # What every error value has, built into each of the four classes below.
+  # The type names the class, and with the reason it is normative: the
+  # conformance corpus matches an expected error on exactly those two. The
+  # message is for a person and is not normative. The position is where in
+  # the source the failure is, where the reference gives one.
+  module ErrorValue
+    # The error's type as the corpus spells it, which is its class's name.
+    #
+    # @return [String]
+    def type = self.class.name.delete_prefix("Predicator::")
+
+    private
+
+    def check(reason, message, position, position_required: false)
+      raise ArgumentError, "reason must be a String, not #{reason.inspect}" unless reason.is_a?(String)
+      raise ArgumentError, "message must be a String, not #{message.inspect}" unless message.is_a?(String)
+      return if position.is_a?(Position) || (position.nil? && !position_required)
+
+      raise ArgumentError, "position must be a Predicator::Position#{" or nil" unless position_required}, " \
+                           "not #{position.inspect}"
+    end
+  end
+  private_constant :ErrorValue
+
+  # A source text that does not parse. It is not an evaluation outcome, so
+  # the corpus never expects one; its reason is this package's own token for
+  # the refusal, and it always knows its position.
+  #
+  # @!attribute [r] reason
+  #   @return [String] a structured token naming the refusal
+  # @!attribute [r] message
+  #   @return [String] a sentence for a person; not normative
+  # @!attribute [r] position
+  #   @return [Position] where in the source the refusal is
+  ParseError = Data.define(:reason, :message, :position) do
+    include ErrorValue
+
+    # @raise [ArgumentError] when a field has the wrong type
+    def initialize(reason:, message:, position:)
+      check(reason, message, position, position_required: true)
+      super
+    end
+  end
+
+  # An evaluation failure that is neither a type mismatch nor an unbound
+  # variable: an empty stack at halt, too few operands, an unknown
+  # instruction, a division by zero, a failed call.
+  #
+  # @!attribute [r] reason
+  #   @return [String] the normative reason token, e.g. "division_by_zero"
+  # @!attribute [r] message
+  #   @return [String] a sentence for a person; not normative
+  # @!attribute [r] position
+  #   @return [Position, nil] where in the source the failing instruction
+  #     came from, when that is known
+  EvaluationError = Data.define(:reason, :message, :position) do
+    include ErrorValue
+
+    # @raise [ArgumentError] when a field has the wrong type
+    def initialize(reason:, message:, position: nil)
+      check(reason, message, position)
+      super
+    end
+  end
+
+  # An operand an opcode refused on its type. The reason is the operation
+  # that refused it, e.g. "add".
+  #
+  # @!attribute [r] reason
+  #   @return [String] the normative reason token
+  # @!attribute [r] message
+  #   @return [String] a sentence for a person; not normative
+  # @!attribute [r] position
+  #   @return [Position, nil] where in the source, when that is known
+  TypeMismatchError = Data.define(:reason, :message, :position) do
+    include ErrorValue
+
+    # @raise [ArgumentError] when a field has the wrong type
+    def initialize(reason:, message:, position: nil)
+      check(reason, message, position)
+      super
+    end
+  end
+
+  # A variable the context does not bind, reported as an error rather than
+  # as undefined.
+  #
+  # @!attribute [r] reason
+  #   @return [String] the normative reason token, e.g. "unbound_variable"
+  # @!attribute [r] message
+  #   @return [String] a sentence for a person; not normative
+  # @!attribute [r] position
+  #   @return [Position, nil] where in the source, when that is known
+  UndefinedVariableError = Data.define(:reason, :message, :position) do
+    include ErrorValue
+
+    # @raise [ArgumentError] when a field has the wrong type
+    def initialize(reason:, message:, position: nil)
+      check(reason, message, position)
+      super
+    end
+  end
+
+  # The exception a raising variant raises. It carries the error value a
+  # result would have answered, so a caller that rescues it reads the same
+  # type, reason and position.
+  class Error < StandardError
+    # @return [Object] the error value: a {ParseError}, an
+    #   {EvaluationError}, a {TypeMismatchError}, an
+    #   {UndefinedVariableError}, or a {Predicator::Tagged::CodecError}
+    attr_reader :error
+
+    # @param error [Object] an error value; its message is the exception's
+    def initialize(error)
+      @error = error
+      super(error.message)
+    end
+  end
+end

data/lib/predicator/evaluator/access.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # Member and index access, membership and list construction, as the
+    # reference's ISA (docs/isa.md, section 5) states them: the handlers
+    # {Machine} runs for `access`, `bracket_access`, `in`, `contains` and
+    # `make_list`, and the rules they read through.
+    #
+    # A duration reads as the map its shape is, as the reference's ISA
+    # (section 3) makes it normative: each of its eight unit names answers
+    # that unit, and any other key misses. A duration is one value wherever
+    # it came from, a literal, an opcode or the host.
+    module Access
+      # The keys a duration answers.
+      DURATION_UNITS = %w[years months weeks days hours minutes seconds milliseconds].freeze
+
+      # The one-of-a-kind values a map key may be besides a String and an
+      # Integer: the reference admits its atoms, which are these.
+      ATOM_KEYS = [true, false, nil, UNDEFINED].freeze
+
+      # The plain map a duration is: each of its eight unit names to that
+      # unit.
+      def self.units(duration) = DURATION_UNITS.to_h { |name| [name, duration.public_send(name)] }
+
+      private
+
+      # Reads the named member off the popped target. A miss, and a target
+      # that is not a map or a duration, the null value included, answer
+      # undefined: access never fails but on an empty stack.
+      def access(at, property)
+        return insufficient("access") if @stack.empty?
+
+        push(at, member(@stack.pop, property))
+      end
+
+      # Pops the key, then the target. A list takes a non-negative Integer and
+      # misses past either end; any other key is a type mismatch. A map, a
+      # duration, a date or a datetime (each a map in the reference) takes a
+      # String, an Integer, a boolean, null or undefined and misses on a key it
+      # does not hold; any other key is a type mismatch. Any other target
+      # answers undefined whatever the key.
+      def bracket_access(at)
+        return insufficient("bracket_access") if @stack.size < 2
+
+        key = @stack.pop
+        target = @stack.pop
+        case target
+        when Array then list_index(at, target, key)
+        when Hash, Duration, Predicator::Date, Predicator::DateTime then map_key(at, target, key)
+        else push(at, UNDEFINED)
+        end
+      end
+
+      def list_index(at, list, key)
+        return mismatch("bracket_access", "an integer index", key) unless key.is_a?(Integer)
+
+        push(at, key.negative? || key >= list.size ? UNDEFINED : list[key])
+      end
+
+      def map_key(at, target, key)
+        unless key.is_a?(String) || key.is_a?(Integer) || ATOM_KEYS.any? { |atom| atom.equal?(key) }
+          return mismatch("bracket_access", "a string key", key)
+        end
+
+        push(at, member(target, key))
+      end
+
+      def member(target, key)
+        case target
+        when Hash then target.fetch(key, UNDEFINED)
+        when Duration then DURATION_UNITS.include?(key) ? target.public_send(key) : UNDEFINED
+        else UNDEFINED
+        end
+      end
+
+      def membership_in(at) = membership(at, "in")
+      def membership_contains(at) = membership(at, "contains")
+
+      # `left in right` and `left contains right`: undefined on either side
+      # answers undefined; otherwise the list side (right for in, left for
+      # contains) must be a list. A member matches by the equality `EQ` uses,
+      # with one difference: it answers false where `EQ` answers undefined,
+      # so null is found in a list holding null and undefined never is.
+      def membership(at, operation)
+        return insufficient(operation) if @stack.size < 2
+
+        right = @stack.pop
+        left = @stack.pop
+        return push(at, UNDEFINED) if UNDEFINED.equal?(left) || UNDEFINED.equal?(right)
+
+        list, sought = operation == "in" ? [right, left] : [left, right]
+        return mismatch(operation, "a list", list) unless list.is_a?(Array)
+
+        push(at, list.any? { |item| Compare.loose_equal?(sought, item, by_instant: false) })
+      end
+
+      # Pops count values and pushes them as one list, deepest first, which
+      # is source order.
+      def make_list(at, count)
+        return insufficient("make_list") if @stack.size < count
+
+        push(at, @stack.pop(count))
+      end
+    end
+    private_constant :Access
+  end
+end