omghax-einstein 0.1.0

data/lib/einstein/nodes.rb

@@ -0,0 +1,155 @@
+require "einstein/visitors"
+
+module Einstein
+  module Nodes
+    # Base class for all Einstein nodes.
+    class Node
+      include Einstein::Visitors
+
+      # Initializes a new instance of this node with the given +value+.
+      def initialize(value)
+        @value = value
+      end
+
+      # The value of this node.
+      attr_accessor :value
+
+      # Implements the visitor pattern by calling a method named
+      # visit_SomeNode when visiting a class named SomeNode.  This way we
+      # separate the tree traversal logic from the nodes themselves, which
+      # makes it easier to modify the visitors, or to add new ones.
+      def accept(visitor, &block)
+        klass = self.class.ancestors.find do |ancestor|
+          visitor.respond_to?("visit_#{ancestor.name.split(/::/)[-1]}")
+        end
+
+        if klass
+          visitor.send("visit_#{klass.name.split(/::/)[-1]}", self, &block)
+        else
+          raise "No visitor for '#{self.class}'"
+        end
+      end
+
+      # Evaluate this node against the given +scope+.  Returns a numeric value
+      # calculated by walking the AST with an instance of EvaluateVisitor.
+      def evaluate(scope = {})
+        EvaluateVisitor.new(scope).accept(self)
+      end
+
+      # Performs a "pretty print" of this node.
+      def to_s
+        PrettyPrintVisitor.new.accept(self)
+      end
+
+      # Also use #to_s for inspecting a node in IRB.
+      alias_method :inspect, :to_s
+
+      # Returns this node as an s-expression.  Built by walking the AST with
+      # an instance of SexpVisitor.
+      def to_sexp
+        SexpVisitor.new.accept(self)
+      end
+    end
+
+    # Node representing an entire Einstein statement.  This is the root-level
+    # node of the parser.  This node's +value+ is the tree of expressions that
+    # make up a single logical statement.
+    class StatementNode < Node
+    end
+
+    # Node representing a number.  This is a terminal node.
+    class NumberNode < Node
+    end
+
+    # Node representing a unary + (plus) operation.  Not to be confused with
+    # the addition operator, this node is generated when you specify a number
+    # with an explicit positive sign.
+    # 
+    # Example:
+    #   # This would generate a UnaryPlusNode with the value 1.25.
+    #   +1.25
+    class UnaryPlusNode < Node
+    end
+
+    # Node representing a unary - (minus) operation.  Not to be confused with
+    # the subtraction operator, this node is generated when you specify a
+    # negative number.
+    #  
+    # Example:
+    #   # This would generate a UnaryMinusNode with the value 3.3.
+    #   -3.3
+    class UnaryMinusNode < Node
+    end
+
+    # Node representing a bitwise NOT operation.
+    class BitwiseNotNode < Node
+    end
+
+    # Base class for all binary nodes.  Binary nodes operate on two values.
+    class BinaryNode < Node
+      # Initializes a new instance of this node with the given +left+ and
+      # +right+ values.
+      def initialize(left, right)
+        super(right)
+        @left = left
+      end
+
+      # The secondary value given to #initialize.
+      attr_reader :left
+    end
+
+    # Node representing an exponential raise.  This node's +left+ value is the
+    # base, and the +right+ value is the exponent.
+    class ExponentNode < BinaryNode
+    end
+
+    # Node representing multiplication of two values.
+    class MultiplyNode < BinaryNode
+    end
+
+    # Node representing division of two values.
+    class DivideNode < BinaryNode
+    end
+
+    # Node representing modulus of two values.
+    class ModulusNode < BinaryNode
+    end
+
+    # Node representing addition of two nodes.
+    class AddNode < BinaryNode
+    end
+
+    # Node representing subtraction of two nodes.
+    class SubtractNode < BinaryNode
+    end
+
+    # Node representing an LSHIFT (left shift) operation.  This node's +left+
+    # value is the number to be shifted, and the +right+ value is the number
+    # of bits to shift the value by.
+    class LeftShiftNode < BinaryNode
+    end
+
+    # Node representing an RSHIFT (right shift) operation.  This node's +left+
+    # value is the number to be shifted, and the +right+ value is the number
+    # of bits to shift the value by.
+    class RightShiftNode < BinaryNode
+    end
+
+    # Node representing a bitwise AND operation.
+    class BitwiseAndNode < BinaryNode
+    end
+
+    # Node representing a bitwise XOR operation.
+    class BitwiseXorNode < BinaryNode
+    end
+
+    # Node representing a bitwise OR operation.
+    class BitwiseOrNode < BinaryNode
+    end
+
+    # Node representing a variable lookup.  This node's +value+ is the
+    # variable's name, as a string.
+    class ResolveNode < Node
+    end
+  end
+end

data/lib/einstein/parser.rb

@@ -0,0 +1,60 @@
+require "einstein/generated_parser"
+require "einstein/tokenizer"
+
+module Einstein
+  class Parser < GeneratedParser
+    # Tokenizer instance that is shared between instances of Parser.
+    TOKENIZER = Tokenizer.new
+
+    def initialize
+      @tokens = []
+      @logger = nil
+      @terminator = false
+    end
+
+    # Logger object to receive debugging information when a parsing error
+    # occurs.  If this is nil, no information will be output.
+    attr_accessor :logger
+
+    # Parses the given +expression+ using TOKENIZER, and returns an instance
+    # of StatementNode, which represents an AST.  You can take this AST and
+    # perform evaluations on it using #evaluate, or transform it into an
+    # s-expression using #to_sexp.
+    # 
+    # Example:
+    #   # Parse the expression "x + 3".
+    #   ast = Einstein::Parser.new.parse("x + 3")
+    # 
+    #   # Evaluate the expression with a given scope.
+    #   ast.evaluate(:x => 5) # => 8
+    # 
+    #   # Return the expression as an s-expression.
+    #   ast.to_sexp # => [:add, [:resolve, "x"], [:lit, 3]]
+    def parse(expression)
+      @tokens = TOKENIZER.tokenize(expression)
+      @position = 0
+      StatementNode.new(do_parse)
+    end
+
+    private
+
+    def on_error(error_token_id, error_value, value_stack)
+      if logger
+        logger.error(token_to_str(error_token_id))
+        logger.error("error value: #{error_value}")
+        logger.error("error stack: #{value_stack.inspect}")
+      end
+      super
+    end
+
+    # Used by Racc::Parser to step through tokens.
+    def next_token
+      begin
+        return [false, false] if @position >= @tokens.length
+        n_token = @tokens[@position]
+        @position += 1
+      end while [:COMMENT, :WS].include?(n_token[0])
+      n_token
+    end
+  end
+end

data/lib/einstein/tokenizer.rb

@@ -0,0 +1,112 @@
+module Einstein
+  class Token
+    # The default transformer used by instances of Token when no block is
+    # given to #initialize.
+    DEFAULT_TRANSFORMER = lambda { |name, value| [name, value] }
+
+    def initialize(name, value, &transformer)
+      @name = name
+      @value = value
+      @transformer = transformer || DEFAULT_TRANSFORMER
+    end
+
+    # This token's name (eg. :NUMBER, :IDENT).
+    attr_accessor :name
+
+    # This token's value (eg. 1, "x").
+    attr_accessor :value
+
+    # The block given to this token's #initialize method.  This block is
+    # called by #to_racc_token.
+    attr_accessor :transformer
+
+    # Converts this token to a format that Racc expects.  This is an array of
+    # the format [name, value].
+    # 
+    # Examples:
+    #   [:NUMBER, 2.20]
+    #   [:IDENT, "x"]
+    def to_racc_token
+      @transformer.call(name, value)
+    end
+  end
+
+  class Lexeme
+    def initialize(name, pattern, &block)
+      @name = name
+      @pattern = pattern
+      @block = block
+    end
+
+    def match(string)
+      match = @pattern.match(string)
+      return Token.new(@name, match.to_s, &@block) if match
+      match
+    end
+  end
+
+  class Tokenizer
+    LITERALS = {
+      # Punctuators
+      "**" => :RAISE,
+      "<<" => :LSHIFT,
+      ">>" => :RSHIFT
+    }
+
+    def initialize(&block)
+      @lexemes = []
+
+      token(:COMMENT, /\A\/(?:\*(?:.)*?\*\/|\/[^\n]*)/m)
+
+      # A regexp to match floating point literals (but not integer literals).
+      token(:NUMBER, /\A\d+\.\d*(?:[eE][-+]?\d+)?|\A\d+(?:\.\d*)?[eE][-+]?\d+|\A\.\d+(?:[eE][-+]?\d+)?/m) do |type, value|
+        value.gsub!(/\.(\D)/, '.0\1') if value =~ /\.\w/
+        value.gsub!(/\.$/, '.0') if value =~ /\.$/
+        value.gsub!(/^\./, '0.') if value =~ /^\./
+        [type, eval(value)]
+      end
+      token(:NUMBER, /\A0[bBxX][\da-fA-F]+|\A0[0-7]*|\A\d+/) do |type, value|
+        [type, eval(value)]
+      end
+
+      token(:LITERALS,
+        Regexp.new(LITERALS.keys.sort_by { |x| x.length }.reverse.map { |x| "\\A#{x.gsub(/([|+*^])/, '\\\\\1')}" }.join('|')
+      )) do |type, value|
+        [LITERALS[value], value]
+      end
+
+      token(:IDENT, /\A(\w|\$)+/)
+
+      token(:WS, /\A[\s\r\n]*/m)
+
+      token(:SINGLE_CHAR, /\A./) do |type, value|
+        [value, value]
+      end
+    end
+
+    def tokenize(string)
+      tokens = []
+      while string.length > 0
+        longest_token = nil
+
+        @lexemes.each { |lexeme|
+          match = lexeme.match(string)
+          next if match.nil?
+          longest_token = match if longest_token.nil?
+          next if longest_token.value.length >= match.value.length
+          longest_token = match
+        }
+
+        string = string.slice(Range.new(longest_token.value.length, -1))
+        tokens << longest_token
+      end
+      tokens.map { |x| x.to_racc_token }
+    end
+
+    private
+
+    def token(name, pattern = nil, &block)
+      @lexemes << Lexeme.new(name, pattern, &block)
+    end
+  end
+end

data/lib/einstein/version.rb

@@ -0,0 +1,9 @@
+module Einstein #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/lib/einstein/visitors.rb

@@ -0,0 +1,291 @@
+module Einstein
+  module Visitors
+    class Visitor
+      TERMINAL_NODES = %w{
+        Number Resolve
+      }
+      SINGLE_VALUE_NODES = %w{
+        BitwiseNot Statement UnaryMinus UnaryPlus
+      }
+      BINARY_NODES = %w{
+        Add BitwiseAnd BitwiseOr BitwiseXor Divide Exponent LeftShift Modulus
+        Multiply RightShift Subtract
+      }
+
+      def accept(target)
+        target.accept(self)
+      end
+
+      TERMINAL_NODES.each do |type|
+        define_method("visit_#{type}Node") { |o| }
+      end
+
+      SINGLE_VALUE_NODES.each do |type|
+        define_method("visit_#{type}Node") do |o|
+          o.value.accept(self)
+        end
+      end
+
+      BINARY_NODES.each do |type|
+        define_method("visit_#{type}Node") do |o|
+          [o.left && o.left.accept(self), o.value && o.value.accept(self)]
+        end
+      end
+    end
+
+    # This visitor walks the AST and evaluates the values of the nodes.
+    class EvaluateVisitor < Visitor
+      # Initialize a new instance of this visitor with the given +scope+, as a
+      # hash.  This +scope+ should provide a mapping of variable names to
+      # values.
+      def initialize(scope)
+        super()
+
+        # Convert the scope hash keys from symbols to strings.
+        @scope = scope.inject({}) do |hash, (key, value)|
+          hash[key.to_s] = value
+          hash
+        end
+      end
+
+      # Returns the value of +o+.
+      def visit_NumberNode(o)
+        o.value
+      end
+
+      # Returns the value of +o+.
+      def visit_UnaryPlusNode(o)
+        o.value.accept(self)
+      end
+
+      # Returns the negated value of +o+.
+      def visit_UnaryMinusNode(o)
+        -o.value.accept(self)
+      end
+
+      # Raises the left value of +o+ by the right value of +o+.
+      def visit_ExponentNode(o)
+        o.left.accept(self) ** o.value.accept(self)
+      end
+
+      # Multiplies the left and right values of +o+.
+      def visit_MultiplyNode(o)
+        o.left.accept(self) * o.value.accept(self)
+      end
+
+      # Divides the left value of +o+ by the right value of +o+.  Raises
+      # ZeroDivisionError if the right value of +o+ is zero.
+      def visit_DivideNode(o)
+        dividend = o.value.accept(self)
+        raise ZeroDivisionError, "divided by zero" if dividend == 0
+        o.left.accept(self) / dividend
+      end
+
+      # Performs a modulus operation for the left and right values of +o+.
+      def visit_ModulusNode(o)
+        o.left.accept(self) % o.value.accept(self)
+      end
+
+      # Adds the left and right values of +o+.
+      def visit_AddNode(o)
+        o.left.accept(self) + o.value.accept(self)
+      end
+
+      # Subtracts the right value of +o+ by the left value of +o+.
+      def visit_SubtractNode(o)
+        o.left.accept(self) - o.value.accept(self)
+      end
+
+      # Performs a bitwise AND with the left and right values of +o+.
+      def visit_BitwiseAndNode(o)
+        o.left.accept(self) & o.value.accept(self)
+      end
+
+      # Performs a bitwise XOR with the left and right values of +o+.
+      def visit_BitwiseXorNode(o)
+        o.left.accept(self) ^ o.value.accept(self)
+      end
+
+      # Performs a bitwise OR with the left and right values of +o+.
+      def visit_BitwiseOrNode(o)
+        o.left.accept(self) | o.value.accept(self)
+      end
+
+      # Performs a lookup for the value of +o+ inside this visitor's scope. 
+      # Raises ResolveError if the variable is not in scope.
+      def visit_ResolveNode(o)
+        raise ResolveError, "undefined variable: #{o.value}" unless @scope.has_key?(o.value)
+        @scope[o.value]
+      end
+    end
+
+    # This visitor walks the AST and builds a "pretty print" of the values.
+    # This means that it returns an unambiguous string representation of the
+    # tree.  All binary expressions are wrapped in parentheses.  This visitor
+    # is used when calling #inspect on a node.
+    class PrettyPrintVisitor < Visitor
+      # Example: 4
+      def visit_NumberNode(o)
+        o.value.inspect
+      end
+
+      # Example: +4
+      def visit_UnaryPlusNode(o)
+        "+#{o.value.accept(self)}"
+      end
+
+      # Example: -4
+      def visit_UnaryMinusNode(o)
+        "-#{o.value.accept(self)}"
+      end
+
+      # Example: ~4
+      def visit_BitwiseNotNode(o)
+        "~#{o.value.accept(self)}"
+      end
+
+      # Example: (2 ** 3)
+      def visit_ExponentNode(o)
+        "(#{o.left.accept(self)} ** #{o.value.accept(self)})"
+      end
+
+      # Example: (2 * 3)
+      def visit_MultiplyNode(o)
+        "(#{o.left.accept(self)} * #{o.value.accept(self)})"
+      end
+
+      # Example: (6 / 3)
+      def visit_DivideNode(o)
+        "(#{o.left.accept(self)} / #{o.value.accept(self)})"
+      end
+
+      # Example: (7 % 3)
+      def visit_ModulusNode(o)
+        "(#{o.left.accept(self)} % #{o.value.accept(self)})"
+      end
+
+      # Example: (5 + 8)
+      def visit_AddNode(o)
+        "(#{o.left.accept(self)} + #{o.value.accept(self)})"
+      end
+
+      # Example: (6 - 3)
+      def visit_SubtractNode(o)
+        "(#{o.left.accept(self)} - #{o.value.accept(self)})"
+      end
+
+      # Example: (8 << 2)
+      def visit_LeftShiftNode(o)
+        "(#{o.left.accept(self)} << #{o.value.accept(self)})"
+      end
+
+      # Example: (8 >> 2)
+      def visit_RightShiftNode(o)
+        "(#{o.left.accept(self)} >> #{o.value.accept(self)})"
+      end
+
+      # Example: (4 & 16)
+      def visit_BitwiseAndNode(o)
+        "(#{o.left.accept(self)} & #{o.value.accept(self)})"
+      end
+
+      # Example: (4 ^ 6)
+      def visit_BitwiseXorNode(o)
+        "(#{o.left.accept(self)} ^ #{o.value.accept(self)})"
+      end
+
+      # Example: (4 | 6)
+      def visit_BitwiseOrNode(o)
+        "(#{o.left.accept(self)} | #{o.value.accept(self)})"
+      end
+
+      # Example: x
+      def visit_ResolveNode(o)
+        o.value
+      end
+    end
+
+    # This visitor walks the AST and returns an s-expression.
+    class SexpVisitor < Visitor
+      # Example: [:lit, 3]
+      def visit_NumberNode(o)
+        [:lit, o.value]
+      end
+
+      # Example: [:u_plus, [:lit, 3]]
+      def visit_UnaryPlusNode(o)
+        [:u_plus, super]
+      end
+
+      # Example: [:u_minus, [:lit, 3]]
+      def visit_UnaryMinusNode(o)
+        [:u_minus, super]
+      end
+
+      # Example: [:bitwise_not, [:lit, 3]]
+      def visit_BitwiseNotNode(o)
+        [:bitwise_not, super]
+      end
+
+      # Example: [:raise, [:lit, 2], [:lit, 3]]
+      def visit_ExponentNode(o)
+        [:raise, *super]
+      end
+
+      # Example: [:multiply, [:lit, 2], [:lit, 3]]
+      def visit_MultiplyNode(o)
+        [:multiply, *super]
+      end
+
+      # Example: [:divide, [:lit, 4], [:lit, 2]]
+      def visit_DivideNode(o)
+        [:divide, *super]
+      end
+
+      # Example: [:modulus, [:lit, 3], [:lit, 5]]
+      def visit_ModulusNode(o)
+        [:modulus, *super]
+      end
+
+      # Example: [:add, [:lit, 2], [:lit, 2]]
+      def visit_AddNode(o)
+        [:add, *super]
+      end
+
+      # Example: [:subtract, [:lit, 5], [:lit, 2]]
+      def visit_SubtractNode(o)
+        [:subtract, *super]
+      end
+
+      # Example: [:lshift, [:lit, 2], [:lit, 3]]
+      def visit_LeftShiftNode(o)
+        [:lshift, *super]
+      end
+
+      # Example: [:rshift, [:lit, 8], [:lit, 2]]
+      def visit_RightShiftNode(o)
+        [:rshift, *super]
+      end
+
+      # Example: [:bitwise_and, [:lit, 4], [:lit, 2]]
+      def visit_BitwiseAndNode(o)
+        [:bitwise_and, *super]
+      end
+
+      # Example: [:bitwise_xor, [:lit, 4], [:lit, 2]]
+      def visit_BitwiseXorNode(o)
+        [:bitwise_xor, *super]
+      end
+
+      # Example: [:bitwise_or, [:lit, 4], [:lit, 2]]
+      def visit_BitwiseOrNode(o)
+        [:bitwise_or, *super]
+      end
+
+      # Example: [:resolve, "x"]
+      def visit_ResolveNode(o)
+        [:resolve, o.value]
+      end
+    end
+  end
+end

data/lib/einstein.rb

@@ -0,0 +1,56 @@
+$:.unshift File.dirname(__FILE__)
+
+require "einstein/parser"
+
+# == Basic Usage
+# 
+# If you're only interested in evaluating expressions, you can simply call
+# Einstein.evaluate:
+# 
+#   Einstein.evaluate("1 + 2 + 3") # => 6
+# 
+# You can use variables as well, but you must supply their values:
+# 
+#   Einstein.evaluate("x * 4", :x => 5) # => 20
+#   Einstein.evaluate("x + y + z", :x => 3, :y => 4, :z => 5) # => 12
+# 
+# == Prepared Statements
+# 
+# If you're going to be performing the same operation over a large set of
+# different values, and performance is a concern, you can have Einstein parse
+# the expression once beforehand, and return a statement object (technically,
+# an instance of Einstein::Nodes::StatementNode).  You can then pass your
+# values directly to this statement for much faster processing, rather than
+# making Einstein parse the same formula over and over again each time.
+# 
+#   # This will return a prepared statement.
+#   stmt = Einstein.parse("x + y")
+# 
+#   # You can then evaluate this statement against different inputs.
+#   stmt.evaluate(:x => 1, :y => 2) # => 3
+#   stmt.evaluate(:x => 25, :y => 30) # => 55
+module Einstein
+  # Base class for all Einstein errors.
+  class Error < StandardError
+  end
+
+  # Raised when a variable's name cannot be resolved.
+  class ResolveError < Error
+  end
+
+  # Raised when division by zero occurs.
+  class ZeroDivisionError < Error
+  end
+
+  # Parse the given +expression+ and return the AST as
+  def self.parse(expression)
+    Parser.new.parse(expression)
+  end
+
+  # Evaluate the given +expression+ with the given +scope+.  Any variables
+  # used by the +expression+, but undeclared in the +scope+, will cause a
+  # Einstein::ResolveError to be raised.
+  def self.evaluate(expression, scope = {})
+    parse(expression).evaluate(scope)
+  end
+end