interrotron 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-19mode

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in interrotron.gemspec
+gemspec
+gem 'rake'
+gem 'hashie', require: "hashie/mash"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Andrew Cholakian
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# Interrotron
+
+[![Build Status](https://secure.travis-ci.org/andrewvc/interrotron.png?branch=master)](http://travis-ci.org/andrewvc/interrotron)
+
+A simple non-turing complete lisp meant to be embedded in apps as a rules engine. It is intentionally designed to limit the harm evaluated code can do (in contrast to a straight ruby 'eval') and is constrained to:
+
+* Be totally sandboxed by default
+* Always finish executing (no infinite loops)
+* Let you easily add variables and functions (simply pass in a hash defining them)
+* Be a small, single file
+
+## Installation
+
+Either add the `interrotron` gem, or just copy and paste [interratron.rb](https://github.com/andrewvc/interrotron/blob/master/lib/interrotron.rb)
+
+## Usage
+
+```ruby
+# Injecting a variable and evaluating a function is easy!
+Interrotron.run('(> 51 custom_var)', :custom_var => 10) 
+# => true
+
+#You can inject functions just as easily
+Interrotron.run("(doubler (+ 2 2))", :doubler => proc {|a| a*2 })
+# => 8
+
+# You can even pre-compile scripts for speed / re-use!
+tron = Interrotron.new(:is_valid => proc {|a| a.reverse == 'oof'})
+compiled = tron.compile("(is_valid my_param)")
+compiled.call(:my_param => 'foo')
+# => true
+compiled.call(:my_param => 'bar')
+#=> false
+
+# Since interrotron is meant for business rules, it handles dates as a 
+# native type as instances of ruby's DateTime class. You can use literals
+# for that like so:
+Interrotron.run('(> #dt{2010-09-04} start_date)', start_date: DateTime.parse('2012-12-12'))
+# => true
+
+# You can, of course, create arbitarily complex exprs
+Interrotron.run("(if false
+                     (+ 4 -3)
+                     (- 10 (+ 2 (+ 1 1))))")
+# => 6
+
+# Additionally, it is possible to constrain execution to a maximum number of
+# operations by passing in a third argument
+Interrotron.run("str (+ 1 2) (+ 3 4) (+ 5 7))", {}, 4)
+# => raises Interrotron::OpsThresholdError since 4 operations were executed
+
+```
+
+The following functions and variables are built in to Interrotron (and more are on the way!):
+```clojure
+(if pred then else) ; it's an if / else statement
+(cond pred1 clause1 pred2 clause2 true fallbackclause) ; like a case statement
+(and e1, e2, ...) ; logical and, returns last arg if true
+(or e1, e2, ...) ; logical or, returns first true arg
+(not expr) ; negates
+(! expr) ; negates
+(identity expr) ; returns its argument
+(str s1, s2, ...) ; converts its args to strings, also concatenates them
+(floor expr) ; equiv to num.floor
+(ceil expr) ; equiv to num.ceil
+(round expr) ; equiv to num.round
+(max lst) ; returns the largest element in a list
+(min lst) ; returns the smallest element in a list
+(to_i expr) ; int conversion
+(to_f expr) ; float conversion
+(rand) ; returns a random float between 0 and 1
+(upcase str) ; uppercases a string
+(downcase) ; lowercases a string
+(now) ; returns the current DateTime
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,16 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new('spec') do |t|
+  t.rspec_opts = '--tag ~integration'
+end
+
+RSpec::Core::RakeTask.new('spec:integration') do |t|
+  t.pattern = 'spec/integration/*_spec.rb'
+end
+
+task :default => :spec
+

data/interrotron.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/interrotron/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Andrew Cholakian"]
+  gem.email         = ["andrew@andrewvc.com"]
+  gem.description   = %q{A tiny, embeddable, lisp VM}
+  gem.summary       = %q{A lisp VM meant to run with guarantees on execution for business rules}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "interrotron"
+  gem.require_paths = ["lib"]
+  gem.version       = Interrotron::VERSION
+  gem.add_development_dependency "rspec", "~> 2.6"
+end

data/lib/interrotron.rb

@@ -0,0 +1,240 @@
+require "interrotron/version"
+require 'date'
+require 'hashie/mash'
+
+# This is a Lispish DSL meant to define business rules
+# in environments where you do *not* want a turing complete language.
+# It comes with a very small number of builtin functions, all overridable.
+#
+# It is meant to aid in creating a DSL that can be executed in environments
+# where code injection could be dangerous.
+#
+# To compile and run, you could, for example:
+#     Interrotron.new().compile('(+ a_custom_var 2)').call("a_custom_var" => 4)
+#     Interrotron.new().compile.run('(+ a_custom_var 4)', :vars => {"a_custom_var" => 2})
+#     => 6
+# You can inject your own custom functions and constants via the :vars option.
+#
+# Additionally, you can cap the number of operations exected with the :max_ops option
+# This is of limited value since recursion is not a feature
+#
+class Interrotron
+  class ParserError < StandardError; end
+  class InvalidTokenError < ParserError; end
+  class SyntaxError < ParserError; end
+  class UndefinedVarError < ParserError; end
+  class OpsThresholdError < StandardError; end
+  class InterroArgumentError < StandardError; end
+
+  class Macro
+    def initialize(&block)
+      @block = block
+    end
+    def call(*args)
+      @block.call(*args)
+    end
+  end
+
+  class Token
+    attr_accessor :type, :value
+    def initialize(type,value)
+      @type = type
+      @value = value
+    end
+  end
+  
+  TOKENS = [
+            [:lpar, /\(/],
+            [:rpar, /\)/],
+            [:fn, /fn/],
+            [:var, /[A-Za-z_><\+\>\<\!\=\*\/\%\-]+/],
+            [:num, /(\-?[0-9]+(\.[0-9]+)?)/],
+            [:datetime, /#dt\{([^\{]+)\}/, {capture: 1}],
+            [:spc, /\s+/, {discard: true}],
+            [:str, /"([^"\\]*(\\.[^"\\]*)*)"/, {capture: 1}],
+            [:str, /'([^'\\]*(\\.[^'\\]*)*)'/, {capture: 1}]
+           ]
+
+  # Quote a ruby variable as a interrotron one
+  def self.qvar(val)
+    Token.new(:var, val.to_s)
+  end
+
+  DEFAULT_VARS = Hashie::Mash.new({
+    'if' => Macro.new {|i,pred,t_clause,f_clause| i.vm_eval(pred) ? t_clause : f_clause },
+    'cond' => Macro.new {|i,*args|
+                 raise InterroArgumentError, "Cond requires at least 3 args" unless args.length >= 3
+                 raise InterroArgumentError, "Cond requires an even # of args!" unless args.length.even?
+                 res = qvar('nil')
+                 args.each_slice(2).any? {|slice|
+                   pred, expr = slice
+                   res = expr if i.vm_eval(pred)
+                 }
+                 res
+    },
+    'and' => Macro.new {|i,*args| args.all? {|a| i.vm_eval(a)} ? args.last : qvar('false')  },
+    'or' => Macro.new {|i,*args| args.detect {|a| i.vm_eval(a) } || qvar('false') },
+    'array' => proc {|*args| args},
+    'identity' => proc {|a| a},
+    'not' => proc {|a| !a},
+    '!' => proc {|a| !a},
+    '>' => proc {|a,b| a > b},
+    '<' => proc {|a,b| a < b},
+    '>=' => proc {|a,b| a >= b},
+    '<=' => proc {|a,b| a <= b},
+    '='  => proc {|a,b| a == b},
+    '!=' => proc {|a,b| a != b},
+    'true' => true,
+    'false' => false,
+    'nil' => nil,
+    '+' => proc {|*args| args.reduce(&:+)},
+    '-' => proc {|*args| args.reduce(&:-)},
+    '*' => proc {|*args| args.reduce(&:*)},
+    '/' => proc {|a,b| a / b},
+    '%' => proc {|a,b| a % b},
+    'floor' =>  proc {|a| a.floor},
+    'ceil' => proc {|a| a.ceil},
+    'round' => proc {|a| a.round},
+    'max' => proc {|arr| arr.max},
+    'min' => proc {|arr| arr.min},
+    'first' => proc {|arr| arr.first},
+    'last' => proc {|arr| arr.last},
+    'length' => proc {|arr| arr.length},
+    'to_i' => proc {|a| a.to_i},
+    'to_f' => proc {|a| a.to_f},
+    'rand' => proc { rand },
+    'upcase' => proc {|a| a.upcase},
+    'downcase' => proc {|a| a.downcase},
+    'now' => proc { DateTime.now },
+    'str' => proc {|*args| args.reduce("") {|m,a| m + a.to_s}}
+  })
+
+  def initialize(vars={},max_ops=nil)
+    @max_ops = max_ops
+    @instance_default_vars = DEFAULT_VARS.merge(vars)
+  end
+
+  def reset!
+    @op_count = 0
+    @stack = [@instance_default_vars]
+  end
+  
+  # Converts a string to a flat array of Token objects
+  def lex(str)
+    return [] if str.nil?
+    tokens = []
+    while str.length > 0
+      matched_any = TOKENS.any? {|name,matcher,opts|
+        opts ||= {}
+        matches = matcher.match(str)
+        if !matches || !matches.pre_match.empty?
+          false
+        else
+          mlen = matches[0].length
+          str = str[mlen..-1]
+          m = matches[opts[:capture] || 0]
+          tokens << Token.new(name, m) unless opts[:discard] == true
+          true
+        end
+      }
+      raise InvalidTokenError, "Invalid token at: #{str}" unless matched_any
+    end
+    tokens
+  end
+  
+  # Transforms token values to ruby types
+  def cast(t)
+    new_val = case t.type
+              when :num
+                t.value =~ /\./ ? t.value.to_f : t.value.to_i
+              when :datetime
+                DateTime.parse(t.value)
+              else
+                t.value
+              end
+    t.value = new_val
+    t
+  end
+  
+  def parse(tokens)
+    return [] if tokens.empty?
+    expr = []
+    t = tokens.shift
+    if t.type == :lpar
+      while t = tokens[0]
+        if t.type == :lpar
+          expr << parse(tokens)
+        else
+          tokens.shift
+          break if t.type == :rpar
+          expr << cast(t)
+        end
+      end
+    elsif t.type != :rpar
+      tokens.shift
+      expr << cast(t)
+      #raise SyntaxError, "Expected :lparen, got #{t} while parsing #{tokens}"
+    end
+    expr
+  end
+  
+  def resolve_token(token)
+    case token.type
+    when :var
+      frame = @stack.reverse.find {|frame| frame.has_key?(token.value) }
+      raise UndefinedVarError, "Var '#{token.value}' is undefined!" unless frame
+      frame[token.value]
+    else
+      token.value
+    end
+  end
+  
+  def register_op
+    return unless @max_ops
+    @op_count += 1
+    raise OpsThresholdError, "Exceeded max ops(#{@max_ops}) allowed!" if @op_count && @op_count > @max_ops
+  end
+  
+  def vm_eval(expr,max_ops=nil)
+    return resolve_token(expr) if expr.is_a?(Token)
+    return nil if expr.empty?
+    register_op
+    
+    head = vm_eval(expr[0])
+    if head.is_a?(Macro)
+      expanded = head.call(self, *expr[1..-1])
+      vm_eval(expanded)
+    else
+      args = expr[1..-1].map {|e|vm_eval(e)}
+
+      head.is_a?(Proc) ? head.call(*args) : head
+    end
+  end
+
+  # Returns a Proc than can be executed with #call
+  # Use if you want to repeatedly execute one script, this
+  # Will only lex/parse once
+  def compile(str)
+    tokens = lex(str)
+    ast = parse(tokens)
+
+    proc {|vars,max_ops|
+      reset!
+      @max_ops = max_ops
+      @stack = [@instance_default_vars.merge(vars)]
+      vm_eval(ast)
+    }
+  end
+
+  def self.compile(str)
+    Interrotron.new().compile(str)
+  end
+
+  def run(str,vars={},max_ops=nil)
+    compile(str).call(vars,max_ops)
+  end
+
+  def self.run(str,vars={},max_ops=nil)
+    Interrotron.new().run(str,vars,max_ops)
+  end
+end

data/lib/interrotron/version.rb

@@ -0,0 +1,3 @@
+class Interrotron
+  VERSION = "0.0.1"
+end

data/spec/interrotron_spec.rb

@@ -0,0 +1,154 @@
+require 'interrotron'
+
+describe "running" do
+  
+  def run(s,vars={},max_ops=nil)
+    Interrotron.run(s,vars,max_ops)
+  end
+  
+  it "should exec identity correctly" do
+    run("(identity 2)").should == 2
+  end
+
+  describe "and" do
+    it "should return true if all truthy" do
+      run("(and 1 true 'ohai')").should be_true
+    end
+    it "should return false if not all truthy" do
+      run("(and 1 true false)").should be_false
+    end
+  end
+
+  describe "or" do
+    it "should return true if all truthy" do
+      run("(or 1 true 'ohai')").should be_true
+    end
+    it "should return true if some truthy" do
+      run("(or 1 true false)").should be_true
+    end
+    it "should return false if all falsey" do
+      run("(or nil false)").should be_false
+    end
+  end
+
+  describe "evaluating a single tokens outside on sexpr" do
+    it "simple values should return themselves" do
+      run("28").should == 28
+    end
+    it "vars should dereference" do
+      run("true").should == true
+    end
+  end
+
+  describe "nested expressions" do
+    it "should execute a simple nested expr correctly" do
+      run("(+ (* 2 2) (% 5 4))").should == 5
+    end
+    
+    it "should execute complex nested exprs correctly" do
+      run("(if false (+ 4 -3) (- 10 (+ 2 (+ 1 1))))").should == 6
+    end
+  end
+
+  describe "custom vars" do
+    it "should define custom vars" do
+      run("my_var", "my_var" => 123).should == 123
+    end
+    it "should properly execute proc custom vars" do
+      run("(my_proc 4)", "my_proc" => proc {|a| a*2 }).should == 8
+    end
+  end
+
+  describe "date times" do
+    it "should parse and compare them properly" do
+      run('(> #dt{2010-09-04} start_date)', start_date: DateTime.parse('2012-12-12'))
+    end
+  end
+
+  describe "cond" do
+    it "should work for a simple case where there is a match" do
+      run("(cond (> 1 2) (* 2 2)
+                 (< 5 10) 'ohai')").should == 'ohai'
+    end
+    it "should return nil when no matches available" do
+      run("(cond (> 1 2) (* 2 2)
+                 false 'ohai')").should == nil
+    end
+    it "should support true as a fallthrough clause" do
+      run("(cond (> 1 2) (* 2 2)
+                 false 'ohai'
+                 true  'backup')").should == 'backup'
+    end
+  end
+
+  describe "intermediate compilation" do
+    it "should support compiled scripts" do
+      # Setup an interrotron obj with some default vals
+      tron = Interrotron.new(:is_valid => proc {|a| a.reverse == 'oof'})
+      compiled = tron.compile("(is_valid my_param)")
+      compiled.call(:my_param => 'foo').should == true
+      compiled.call(:my_param => 'bar').should == false
+    end
+  end
+
+  describe "higher order functions" do
+    it "should support calculating a fn at the head" do
+      run('((or * +) 5 5)').should == 25
+    end
+  end
+
+  describe "array" do
+    it "should return a ruby array" do
+      run("(array 1 2 3)").should == [1, 2, 3]
+    end
+
+    it "should detect max vals correctly" do
+      run("(max (array 82 10 100 99.5))").should == 100
+    end
+
+    it "should detect min vals correctly" do
+      run("(min (array 82 10 100 99.5))").should == 10
+    end
+    
+    it "should let you get the head" do
+      run("(first (array 1 2 3))").should == 1
+    end
+
+    it "should let you get the tail" do
+      run("(last (array 1 2 3))").should == 3
+    end
+
+    it "should let you get the length" do
+      run("(length (array 1 2 3 'bob'))").should == 4
+    end
+
+    it "should implement detect correctly in the positive case" do
+      pending "not now"
+      #run("(detect (> 10 n) (array 1 5 30 1))").should 
+    end
+  end
+
+  describe "functions" do
+    it "should have access to vars they've bound" do
+      pending
+      run("((fn (n) (* n 2)) 5)").should == 10
+    end
+  end
+
+  describe "readme examples" do
+    it "should execute the simple custom var one" do
+      Interrotron.run('(> 51 custom_var)', 'custom_var' => 10).should == true
+    end
+  end
+
+  describe "op counter" do
+    it "should not stop scripts under or at the threshold" do
+      run("(str (+ 1 2) (+ 3 4) (+ 5 7))", {}, 4)
+    end
+    it "should terminate with the proper exception if over the threshold" do
+      proc {
+        run("(str (+ 1 2) (+ 3 4) (+ 5 7))", {}, 3)
+      }.should raise_exception(Interrotron::OpsThresholdError)
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: interrotron
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Andrew Cholakian
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70244487965700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: *70244487965700
+description: A tiny, embeddable, lisp VM
+email:
+- andrew@andrewvc.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- interrotron.gemspec
+- lib/interrotron.rb
+- lib/interrotron/version.rb
+- spec/interrotron_spec.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A lisp VM meant to run with guarantees on execution for business rules
+test_files:
+- spec/interrotron_spec.rb