predicator 1.2.0 → 2.0.0

data/lib/predicator/parser/operators.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Parser
+    # The operator levels of the expression grammar, from `OR` down to the
+    # prefix operators, read into the parse that includes this module.
+    module Operators
+      # Each level's operator tokens and the operator each one is.
+      OR = { or_op: :or, or_or: :or }.freeze
+      AND = { and_op: :and, and_and: :and }.freeze
+      ADDITIVE = { plus: :add, minus: :subtract }.freeze
+      MULTIPLICATIVE = { multiply: :multiply, divide: :divide, modulo: :modulo }.freeze
+      NEGATIONS = %i[not_op bang].freeze
+      UNARY = { minus: :minus, bang: :bang }.freeze
+
+      # The comparison and membership tokens: the node each builds and its
+      # operator.
+      RELATIONS = {
+        gt: [Ast::Comparison, :gt], lt: [Ast::Comparison, :lt], gte: [Ast::Comparison, :gte],
+        lte: [Ast::Comparison, :lte], equal_equal: [Ast::Comparison, :equal_equal], ne: [Ast::Comparison, :ne],
+        strict_equal: [Ast::Comparison, :strict_eq], strict_ne: [Ast::Comparison, :strict_ne],
+        in_op: [Ast::Membership, :in], contains_op: [Ast::Membership, :contains]
+      }.freeze
+
+      # A bare `=` where an expression goes on.
+      EQUALS = "'=' is not an equality operator - use '==' for equality. " \
+               "Assignment is only valid at the start of a statement."
+
+      private
+
+      def logical_or = chain(OR, :logical_and) { |_, left, right, at| Ast::LogicalOr.new(left:, right:, **at) }
+
+      def logical_and = chain(AND, :logical_not) { |_, left, right, at| Ast::LogicalAnd.new(left:, right:, **at) }
+
+      def addition = chain(ADDITIVE, :multiplication) { |*parts| arithmetic(*parts) }
+
+      def multiplication = chain(MULTIPLICATIVE, :unary) { |*parts| arithmetic(*parts) }
+
+      def arithmetic(operator, left, right, at) = Ast::Arithmetic.new(operator:, left:, right:, **at)
+
+      # A left-associative level: operands read by the method named, joined
+      # by the operators given, each join built by the block.
+      def chain(operators, operand)
+        left = send(operand)
+        while (operator = operators[peek.type])
+          token = advance
+          right = send(operand)
+          left = yield(operator, left, right, infix(token, left, right))
+        end
+        left
+      end
+
+      # The higher of the bang's two places: here it negates a whole
+      # comparison, below the comparison it negates an operand.
+      def logical_not
+        return comparison unless NEGATIONS.include?(peek.type)
+
+        token = advance
+        operand = descend { logical_not }
+        Ast::LogicalNot.new(operand:, **prefixed(token, operand))
+      end
+
+      def comparison
+        left = addition
+        refuse("assignment_in_expression", EQUALS, peek) if at?(:eq)
+        kind, operator = RELATIONS[peek.type]
+        return left unless kind
+
+        token = advance
+        right = addition
+        kind.new(operator:, left:, right:, **infix(token, left, right))
+      end
+
+      # A minus never folds into the number after it: `-5` is a negation.
+      def unary
+        operator = UNARY[peek.type]
+        return postfix unless operator
+
+        token = advance
+        operand = descend { unary }
+        Ast::Unary.new(operator:, operand:, **prefixed(token, operand))
+      end
+    end
+    private_constant :Operators
+  end
+end

data/lib/predicator/parser/postfix.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Parser
+    # The postfix steps after a primary, read in a loop into the parse that
+    # includes this module: an index, a property and a cast. Each step's
+    # node is positioned at what it accesses - the key, the property name,
+    # the type name - and spans from its object's start.
+    module Postfix
+      # Each step's opening token and the method that reads the rest.
+      STEPS = { lbracket: :index, dot: :property, double_colon: :cast }.freeze
+
+      # The tokens that may name a property: an identifier, and the five
+      # relative-date words, which the lexer reserves.
+      PROPERTY_NAMES = %i[identifier last_op next_op ago_op from_op now_op].freeze
+
+      private
+
+      def postfix
+        node = primary
+        while (step = STEPS[peek.type])
+          advance
+          node = send(step, node)
+        end
+        node
+      end
+
+      def index(object)
+        key_token = peek
+        key = expression
+        close = expect(:rbracket, "expected_close_bracket", "Expected ']' but found")
+        Ast::BracketAccess.new(object:, key:, position: start_of(key_token), span: reaching(object, close))
+      end
+
+      def property(object)
+        name = peek
+        unless PROPERTY_NAMES.include?(name.type)
+          refuse("expected_property_name", "Expected property name after '.' but found #{describe(name)}", name)
+        end
+        advance
+        Ast::PropertyAccess.new(object:, property: name.value, position: start_of(name), span: reaching(object, name))
+      end
+
+      # The type name is an identifier matched against the seven names, so
+      # each stays usable as a variable, a property and an object key.
+      def cast(expression)
+        name = expect(:identifier, "expected_type_name", "Expected a type name after '::' but found")
+        unless CAST_TYPE_NAMES.include?(name.value)
+          refuse("unknown_cast_type",
+                 "Unknown cast type '#{name.value}' - expected one of: #{CAST_TYPE_NAMES.join(", ")}", name)
+        end
+        Ast::Cast.new(expression:, type_name: name.value, position: start_of(name), span: reaching(expression, name))
+      end
+    end
+    private_constant :Postfix
+  end
+end

data/lib/predicator/parser/primaries.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Parser
+    # The primaries: literals, identifiers, calls, parentheses, lists,
+    # objects and relative dates written `next` or `last`, read into the
+    # parse that includes this module. Each reader takes the token that
+    # started it, already consumed.
+    module Primaries
+      # The reader for each token a primary may start with; any other token
+      # is refused.
+      READERS = {
+        integer: :number, fractional_number: :fraction, float: :literal, boolean: :literal,
+        undefined: :literal, null: :literal, date: :literal, datetime: :literal, string: :string,
+        identifier: :identifier, function_name: :call, qualified_function_name: :call,
+        lparen: :parenthesized, lbracket: :list, lbrace: :object, next_op: :relative_date,
+        last_op: :relative_date, if_kw: :statement_keyword, else_kw: :statement_keyword,
+        while_kw: :statement_keyword
+      }.freeze
+
+      # What a primary may be, in the refusal of anything else.
+      EXPECTED = "Expected number, string, boolean, date, datetime, identifier, function call, list, object, " \
+                 "or '(' but found"
+
+      private
+
+      def primary
+        reader = READERS.fetch(peek.type, :not_a_primary)
+        send(reader, advance)
+      end
+
+      def not_a_primary(token) = refuse("expected_primary", "#{EXPECTED} #{describe(token)}", token)
+
+      def statement_keyword(token)
+        refuse("statement_keyword", "'#{token.value}' is a statement keyword, not an expression - control flow " \
+                                    "is only valid in a program (Predicator.parse_program/2).", token)
+      end
+
+      def literal(token) = Ast::Literal.new(value: token.value, **leaf(token))
+
+      # A whole number, or the first component of a duration.
+      def number(token) = duration_from(token.value, start_of(token)) || literal(token)
+
+      # A number with a point that a unit follows, which the lexer writes
+      # only before a unit; without one, no primary starts with it.
+      def fraction(token) = duration_from(token.value, start_of(token)) || not_a_primary(token)
+
+      def string(token) = Ast::StringLiteral.new(value: token.value, quote: token.quote, **leaf(token))
+
+      def identifier(token) = Ast::Identifier.new(name: token.value, **leaf(token))
+
+      # A parenthesis keeps its expression's node and position and widens
+      # its span to the parentheses.
+      def parenthesized(open)
+        inner = expression
+        close = expect(:rparen, "expected_close_paren", "Expected ')' but found")
+        inner.with(span: between(start_of(open), end_of(close)))
+      end
+
+      # A call's name stays whole: the lexer writes a dotted name as one
+      # token only where a parenthesis follows it.
+      def call(name)
+        expect(:lparen, "expected_primary", EXPECTED)
+        arguments = items(:rparen) { expression }
+        close = expect(:rparen, "expected_close_paren", "Expected ')' but found")
+        Ast::FunctionCall.new(name: name.value, arguments:, **delimited(name, close))
+      end
+
+      def list(open)
+        elements = items(:rbracket) { expression }
+        close = expect(:rbracket, "expected_close_bracket", "Expected ']' but found")
+        Ast::ListLiteral.new(elements:, **delimited(open, close))
+      end
+
+      def object(open)
+        entries = items(:rbrace) { entry }
+        close = expect(:rbrace, "expected_close_brace", "Expected '}' but found")
+        Ast::ObjectLiteral.new(entries:, **delimited(open, close))
+      end
+
+      # Comma-separated items up to the closing token, which is left for the
+      # caller; none when it comes first.
+      def items(closer)
+        return [] if at?(closer)
+
+        found = [yield]
+        while at?(:comma)
+          advance
+          found << yield
+        end
+        found
+      end
+
+      # A key, bare or quoted, a colon and a value.
+      def entry
+        token = peek
+        style = token.type == :identifier ? :identifier : token.quote
+        unless %i[identifier string].include?(token.type)
+          refuse("expected_object_key", "Expected identifier or string for object key but found #{describe(token)}",
+                 token)
+        end
+        advance
+        key = Ast::ObjectKey.new(name: token.value, style:, **leaf(token))
+        expect(:colon, "expected_object_colon", "Expected ':' after object key but found")
+        [key, expression]
+      end
+
+      # `next` or `last` and a bare duration; anything else after the word
+      # is refused at the token it started at.
+      def relative_date(keyword)
+        direction = keyword.type == :next_op ? :next : :last
+        start = peek
+        duration = descend { primary }
+        unless duration.is_a?(Ast::Duration)
+          refuse("expected_duration", "Expected duration after '#{direction}' but found #{describe(start)}", start)
+        end
+        Ast::RelativeDate.new(duration:, direction:, **prefixed(keyword, duration))
+      end
+    end
+    private_constant :Primaries
+  end
+end

data/lib/predicator/parser/statements.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Parser
+    # The statement grammar over the expression grammar, read into the parse
+    # that includes this module: sequences, assignments, `if` with its
+    # optional `else` and `else if`, `while`, and blocks.
+    module Statements
+      # The statements a keyword starts.
+      KEYWORDS = { if_kw: :if_statement, while_kw: :while_statement, else_kw: :stray_else }.freeze
+
+      # What an assignment may write: an identifier and any run of property
+      # and bracket accesses.
+      ACCESSES = [Ast::PropertyAccess, Ast::BracketAccess].freeze
+
+      private
+
+      # One statement or more up to the terminator, which is left for the
+      # caller. A separator is followed by another statement unless it is
+      # the one the terminator may follow; without one, another follows
+      # only a statement that ended in a closing brace.
+      def statement_sequence(terminator)
+        statements = [statement]
+        statements << statement while continues?(statements.last, terminator)
+        statements
+      end
+
+      def continues?(last, terminator)
+        return !at?(terminator) && (last.is_a?(Ast::If) || last.is_a?(Ast::While)) unless at?(:semicolon)
+
+        advance
+        !at?(terminator)
+      end
+
+      def statement
+        reader = KEYWORDS[peek.type]
+        reader ? send(reader, advance) : assignment_or_expression
+      end
+
+      def stray_else(token)
+        refuse("unexpected_else", "Unexpected 'else' - an 'else' block must follow an 'if' block.", token)
+      end
+
+      # What is left over after a finished statement.
+      def after_statement(token)
+        stray_else(token) if token.type == :else_kw
+        refuse("trailing_token", "Unexpected token #{describe(token)} after statement", token)
+      end
+
+      # An assignment when an addition-level expression is followed by `=`,
+      # and an expression read again from the start otherwise: a probe that
+      # was refused, or no `=` after it, is discarded.
+      def assignment_or_expression
+        start = @index
+        target = catch(REFUSED) { descend { addition } }
+        if target.is_a?(Lexer::Refusal) || !at?(:eq)
+          @index = start
+          return expression
+        end
+
+        assignment(target, advance)
+      end
+
+      # Past the `=`, a left side that is not a location is refused at it.
+      def assignment(target, equals)
+        unless location?(target)
+          refuse("unassignable_location", "Left side of '=' must be an assignable location - an identifier, " \
+                                          "a property access, or a bracket access.", equals)
+        end
+        value = expression
+        Ast::Assignment.new(target:, value:, **infix(equals, target, value))
+      end
+
+      def location?(node)
+        node = node.object while ACCESSES.any? { |access| node.is_a?(access) }
+        node.is_a?(Ast::Identifier)
+      end
+
+      def if_statement(keyword)
+        condition = expression
+        then_block = block
+        else_block = else_clause
+        Ast::If.new(condition:, then_block:, else_block:, **prefixed(keyword, else_block || then_block))
+      end
+
+      # An `else if` is an else block holding the one `if`, at its position
+      # and over its span; it nests a level as a block does.
+      def else_clause
+        return unless at?(:else_kw)
+
+        advance
+        return block unless at?(:if_kw)
+
+        nested = descend { if_statement(advance) }
+        Ast::Block.new(statements: [nested], position: nested.position, span: nested.span)
+      end
+
+      def while_statement(keyword)
+        condition = expression
+        body = block
+        Ast::While.new(condition:, body:, **prefixed(keyword, body))
+      end
+
+      # Braces around zero statements or more, one level deeper.
+      def block
+        open = expect(:lbrace, "expected_open_brace", "Expected '{' to open a block but found")
+        statements = at?(:rbrace) ? [] : descend { statement_sequence(:rbrace) }
+        close = expect(:rbrace, "expected_close_brace", "Expected '}' to close the block but found")
+        Ast::Block.new(statements:, **delimited(open, close))
+      end
+    end
+    private_constant :Statements
+  end
+end

data/lib/predicator/parser/token_text.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Parser
+    # How a refusal's message names a token, in the reference's words: the
+    # word connectives uppercase whatever case the source wrote, the end of
+    # input in words, a string in double quotes, and every other token that
+    # carries a value as its kind and that value in single quotes. Read into
+    # the parse that includes this module.
+    module TokenText
+      # The tokens named without their value.
+      FIXED = {
+        undefined: "'undefined'", null: "'null'", gt: "'>'", lt: "'<'", gte: "'>='", lte: "'<='", eq: "'='",
+        ne: "'!='", equal_equal: "'=='", strict_equal: "'==='", strict_ne: "'!=='", and_op: "'AND'",
+        or_op: "'OR'", not_op: "'NOT'", in_op: "'IN'", contains_op: "'CONTAINS'", ago_op: "'ago'",
+        from_op: "'from'", now_op: "'now'", next_op: "'next'", last_op: "'last'", lparen: "'('", rparen: "')'",
+        lbracket: "'['", rbracket: "']'", lbrace: "'{'", rbrace: "'}'", colon: "':'", double_colon: "'::'",
+        comma: "','", semicolon: "';'", dot: "'.'", plus: "'+'", minus: "'-'", multiply: "'*'", divide: "'/'",
+        modulo: "'%'", and_and: "'&&'", or_or: "'||'", bang: "'!'", if_kw: "'if'", else_kw: "'else'",
+        while_kw: "'while'", eof: "end of input"
+      }.freeze
+
+      # The kind a token carrying a value is named by.
+      KINDS = {
+        integer: "number", float: "number", fractional_number: "number", boolean: "boolean", date: "date",
+        datetime: "datetime", identifier: "identifier", function_name: "function",
+        qualified_function_name: "function", duration_unit: "duration unit"
+      }.freeze
+
+      private
+
+      def describe(token)
+        return FIXED.fetch(token.type) if FIXED.key?(token.type)
+        return %(string "#{token.value}") if token.type == :string
+
+        "#{KINDS.fetch(token.type)} '#{spelling(token.value)}'"
+      end
+
+      # A float as the reference writes one; an infinite one, which the
+      # lexer answers for a decimal too long for a finite Float where the
+      # reference's lexer raises, as Ruby writes it.
+      def spelling(value)
+        case value
+        when Float then value.finite? ? FloatText.spell(value) : value.to_s
+        when Lexer::Fraction then "#{value.whole}.#{value.fraction}"
+        else value.to_s
+        end
+      end
+    end
+    private_constant :TokenText
+  end
+end