flea 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,274 +0,0 @@
-= Flea
-
-Flea is a tiny Lisp interpreter implemented in Ruby. Flea is not designed to be a production language, instead it is designed to be an example of how simple it can be to bootstrap the core of a small flexible language. Flea essentially defines an informal subset of Scheme, just enough to be fun and interesting.
-
-=== A Quick Example
-
-This is the classic 'guess the number' program implemented in Flea:
-
-  (define number (+ (rand 9) 1))
-
-  (display "\n\nI'm thinking of a number between 1 and 10,\n")
-  (display "try to guess it!\n\n")
-
-  (define user-guess 
-    (lambda () 
-      (display "Take a guess - ")
-      (define guess (string-to-num (gets)))
-      (if (equal? guess number)
-        (display "Good guess!\n")
-        (begin
-          (if (greater-than? guess number)
-            (display "Lower!\n")
-            (display "Higher!\n"))
-          (user-guess)))))
-
-  (user-guess)
-
-=== Installation
-
-For ease of use the Flea is packaged as a RubyGem. Providing you already have Ruby and RubyGems installing Flea is as easy as entering the following command in a terminal:
-
-  gem install flea
-  
-Mac OS X and most Unix/Linux distributions come with an installation of Ruby and RubyGems. If you do not have Ruby and RubyGems installed please check the {Ruby website for instructions}[http://www.ruby-lang.org/en/downloads/].
-
-=== Usage
-
-After Flea is installed you can run a program by typing the following on the command line:
-
-  flea /path/to/program
-  
-You can also launch Flea's interactive shell by simply calling `flea` with no arguments.
-
-=== Author & Credits
-
-Author:: {Aaron Gough}[mailto:aaron@aarongough.com]
-
-Copyright (c) 2010 {Aaron Gough}[http://thingsaaronmade.com/] ({thingsaaronmade.com}[http://thingsaaronmade.com/]), released under the MIT license
-
----
-
-== API Documentation and More Info
-
-=== More Info
-
-Flea's core is only about 100 lines of code, and provides a simple interface that is used to build the rest of the language. Flea is highly extensible because of its foreign function interface which allows Ruby Proc objects to be defined and then executed within the context of the Flea interpreter. The entire standard library of the language is implemented using this foreign function interface. For example, here is the implementation of the multiplication operator:
-
-  (define * 
-    (native_function "
-      Proc.new() do |arguments, interpreter|
-        tmp = arguments.map {|item| interpreter.evaluate(item)}
-        tmp.inject {|sum, n| sum * n}
-      end
-    "))
-    
-=== API
-
-Flea comes with a small but thoughtful standard library that includes functions for:
-
-==== Output
-
-(display) Outputs data to STDOUT:
-
-  (display "test")
-  # => test
-
-  (display '(1 2 3))
-  # => (1 2 3)
-
-==== Input
-
-(read) Reads and parses an s-expression from STDIN:
-
-  (read) # user enters '(1 2 3)'
-  # => (1 2 3)
-
-(gets) Reads a string from STDIN:
-
-  (gets) # user enters '(1 2 3)'
-  # => "(1 2 3)"
-
-==== Variables
-
-(define) Sets a variable:
-
-  (define test 1)
-  (display test)
-  # => 1
-
-(set!) Re-defines an existing variable:
-
-  (define test 1)
-  (set! test 2)
-  (display test)
-  # => 2  
-
-==== Numeric operations
-
-(+) Add one or more numbers:
-  
-  (+ 1 2 3)
-  # => 6
-
-(-) Subtract one or more numbers:
-
-  (- 10 2 1)
-  # => 7
-
-(*) Multiply one or more numbers:
-
-  (* 10 2 4)
-  # => 80
-
-(/) Divide one or more numbers:
-
-  (/ 100 2 2)
-  # => 25
-
-(greater-than?) Returns true if it's first argument is greater than all the others, false otherwise:
-
-  (greater-than? 10 2 3 4)
-  # => #t
-  
-  (greater-than? 1 2 3 4)
-  # => #f
-
-(less-than?) Returns true if it's first argument is smaller than all the others, false otherwise:
-
-  (less-than? 1 3 4 5)
-  # => #t
-  
-  (less-than? 50 2 45 100)
-   # => #f
-
-(equal?) and (=) Return true if all their arguments are the same, false otherwise:
-
-  (equal? 1 1 1)
-  # => #t
-  
-  (= 1 2 3)
-  # => #f
-
-==== List creation and manipulation
-
-(list) Creates a new list from it's arguments:
-
-  (list (+ 1 2) "test" (rand 10))
-  # => (3 "test" 5)
-
-(list?) Returns true if it's first argument is a list, false otherwise:
-
-  (list? '())
-  # => #t
-  
-  (list? 1)
-  # => #f
-
-(list-tail) Returns a new list created by removing the first n elements of the provided list:
-
-  (define a '(1 2 3 4 5 6))
-  (list-tail a 3)
-  # => (4 5 6)
-
-(car) Returns the first item of a list:
-
-  (car '(1 2 3))
-  # => 1
-
-(cdr) Returns the remainder of a list:
-
-  (cdr '(1 2 3))
-  # => (2 3)
-
-(cons) Creates a new list by using it's first argument as the CAR it's second argument as the CDR:
-
-  (cons '(1 2 3) 3)
-  # => ((1 2 3) 3)
-  
-  (cons 1 2)
-  # => (1 2)
-  
-  (cons 1 (2 3 4))
-  # => (1 2 3 4)
-
-(append) Creates a new list by concatenating it's arguments, it's first argument must be a list:
-
-  (append '(1 2) '(3 4) 5)
-  # => (1 2 3 4 5)
-
-(null?) Returns true if it's first argument is null (the empty list):
-
-  (null '())
-  # => #t
-  
-  (null '(1 2 3))
-  # => #f
-  
-  (null? 1)
-  # => #f
-
-==== Conditionals
-
-(if) If it's first argument is true then it will execute it's first code block, otherwise it will execute the second code block (if any):
-
-  (if (equal? 1 1)
-    (display "true")
-    (display "false"))
-  # => true
-  
-  (if (equal? 2 1)
-    (display "true")
-    (display "false"))
-  # => false
-
-==== Function creation
-
-(lambda) Creates a new function:
-
-  (define adder
-    (lambda (a)
-      (+ a 10)))
-      
-  (adder 5)
-  # => 15
-
-For more info on lambda syntax read the {R5RS Scheme specification}[http://schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-7.html#%_sec_4.1.4]
-
-==== Type conversion
-
-(string-to-num) Converts a string containing a number into a numeric literal:
-
-  (string-to-num "123")
-  # => 123
-
-==== Misc
-
-(rand) Returns a random number less than or equal to it's first argument:
-
-  (rand 10)
-  # => 1
-  
-  (rand 10)
-  # => 6
-
-==== Foreign function interface
-
-(native_function) Takes a string representing a Ruby Proc object and returns it in a form that is able to be called like any other Flea function. The proc must take two arguments (arguments and interpreter):
-
-  (define test
-    (native_function "
-      Proc.new() do |arguments, interpreter|
-        puts "Arguments class: " + arguments.class
-        puts "Arguments: " + arguments.inspect
-        puts "Interpreter class: " + interpreter.class
-        puts "foo"
-      end
-    ")
-  
-  (test 1 2 3 4)
-  # => Arguments class: Array
-       Arguments: [1, 2, 3, 4]
-       Interpreter class: Flea::Interpreter
-       foo
-

data/Rakefile

@@ -1,36 +0,0 @@
-require 'rubygems'
-require 'any-spec'
-require 'rspec/core/rake_task'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "flea"
-    gemspec.summary = "A tiny but flexible Lisp interpreter written in Ruby"
-    gemspec.description = "Flea is an extremely simple, but extremely extensible Lisp interpreter written in Ruby."
-    gemspec.email = "aaron@aarongough.com"
-    gemspec.homepage = "http://github.com/aarongough/flea"
-    gemspec.authors = ["Aaron Gough"]
-    gemspec.rdoc_options << '--line-numbers' << '--inline-source'
-    gemspec.extra_rdoc_files = ['README.rdoc', 'MIT-LICENSE']
-    gemspec.add_dependency "sexpistol"
-    gemspec.add_development_dependency "any-spec"
-    gemspec.executables << 'flea'
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: gem install jeweler"
-end
-
-task :test => [:spec, :anyspec]
-
-task :anyspec do
-  test_runner = AnySpec::TestRunner.new("./bin/flea", "./flea-language-spec/flea-language-spec.yaml")
-  test_runner.run_tests
-end
-
-desc "Run the specs for Flea"
-RSpec::Core::RakeTask.new do |t|
-  t.rspec_opts = "-c"
-  t.fail_on_error = false
-  t.verbose = false
-end

data/VERSION

@@ -1 +0,0 @@
-0.1.0

data/flea-language-spec/test-cases/04-comma-quoting/01-comma-quoting.scm

@@ -1,5 +0,0 @@
-(display '(1 "Hello!" #t #f))
-
-----
-
-assert_output "(1 Hello! #t #f)"

data/spec/flea/environment_spec.rb

@@ -1,114 +0,0 @@
-require File.dirname(__FILE__) + '/../spec_helper'
-
-describe "Flea" do
-  describe "::Environment" do
-    
-    include Flea
-    
-    describe ".new" do
-      it "should return an environment object" do
-        Environment.new.should be_an Environment
-      end
-      
-      it "should return an environment object with no parent" do
-        environment = Environment.new
-        environment.parent.should be_nil
-      end
-      
-      it "should return an environment object with the specified parent" do
-        parent_environment = mock("Environment")
-        environment = Environment.new(parent_environment)
-        environment.parent.should be parent_environment
-      end
-      
-      it "should add base variables for #t and #f" do
-        environment = Environment.new
-        environment.should have_variable :"#t"
-        environment.should have_variable :"#f"
-        environment.find(:"#t").should be_true
-        environment.find(:"#f").should be_false
-      end
-    end
-    
-    describe "#has_variable?" do
-      context "without a parent" do
-        before :each do
-          @environment = Environment.new
-        end
-        
-        it "should return false if the variable is not set in the current environment" do
-          @environment.should_not have_variable :test
-        end
-        
-        it "should return true if the variable is set in the current environment" do
-          @environment.define(:test, 1)
-          @environment.should have_variable :test
-        end
-      end
-      
-      context "with a parent" do
-        before :each do
-          @parent_environment = Environment.new
-          @environment = Environment.new(@parent_environment)
-        end
-        
-        it "should return false if the variable is not set in the parent environment" do
-          @environment.should_not have_variable :test
-        end
-        
-        it "should return true if the variable is set in the parent environment" do
-          @parent_environment.define(:test, 1)
-          @environment.should have_variable :test
-        end
-      end
-    end
-    
-    describe "#define" do
-      it "should set a variable to the supplied value" do
-        env = Environment.new
-        result = env.define(:test, 1)
-        env.should have_variable :test
-        env.find(:test).should == 1
-        result.should == 1
-      end
-    end
-    
-    describe "#find" do
-      context "without a parent" do
-        before :each do
-          @environment = Environment.new
-          @environment.define(:test, 1)
-        end
-        
-        it "should find a variable in the current environment" do
-          @environment.find(:test).should == 1
-        end
-        
-        it "should return nil when variable is not set" do
-          @environment.find(:fake).should be_nil
-        end
-      end
-      
-      context "with a parent" do
-        before :each do
-          @parent_environment = Environment.new
-          @environment = Environment.new(@parent_environment)
-          @parent_environment.define(:test, 1)
-        end
-        
-        it "should find a variable in the parent environment" do
-          @environment.find(:test).should == 1
-        end
-        
-        it "should return a variable from the current environment if it is set in both current and parent" do
-          @environment.define(:test, 5)
-          @environment.find(:test).should == 5
-        end
-        
-        it "should return nil when variable is not set in the current or parent environment" do
-          @environment.find(:fake).should be_nil
-        end
-      end
-    end
-  end
-end

data/spec/flea/interpreter_spec.rb

@@ -1,85 +0,0 @@
-require File.dirname(__FILE__) + '/../spec_helper'
-
-describe "Flea" do
-  describe "::Interpreter" do
-    
-    include Flea
-   
-    describe "#new" do
-      it "should return an Interpreter" do
-        Interpreter.new.should be_an Interpreter
-      end
-      
-      it "should allow setting the base environment to use" do
-        environment = mock("Environment")
-        interpreter = Interpreter.new(
-          :base_environment => environment,
-          :load_standard_library => false
-        )
-        interpreter.base_environment.should be environment
-      end
-    end
-    
-    describe ".run" do
-      it "should run a program and return the last output from the program" do
-        interpreter = Interpreter.new
-        result = interpreter.run("(define test 1)")
-        result.should == 1
-        interpreter.base_environment.should have_variable :test
-      end
-    end
-    
-    describe ".parse" do
-      it "should return an abstract syntax tree representing the supplied program" do
-        ast = Interpreter.new.parse("(define test 1)")
-        ast.should == [[:define, :test, 1]]
-      end
-    end
-    
-    describe ".evaluate" do
-      before :each do
-        @environment = mock("Environment")
-        @interpreter = Interpreter.new(
-          :base_environment => @environment, 
-          :load_standard_library => false
-        )
-      end
-      
-      it "should return the value of a variable" do
-        @environment.should_receive(:find).with(:test).and_return(1)
-        result = @interpreter.evaluate(:test)
-        result.should == 1
-      end
-      
-      it "should define a variable in the current environment" do
-        @environment.should_receive(:define).with(:test, 1).and_return(1)
-        result = @interpreter.evaluate([:define, :test, 1])
-        result.should == 1
-      end
-      
-      it "should create a native function" do
-        result = @interpreter.evaluate([:native_function, "
-          Proc.new() do |arguments, interpreter|
-            1
-          end
-        "])
-        result.should be_a Proc
-        result.call.should == 1        
-      end
-      
-      it "should call a native function" do
-        @environment.should_receive(:find).with(:foo).and_return(Proc.new {|a,b| "bar"})
-        result = @interpreter.evaluate([:foo, 1, 2, 3])
-        result.should == "bar"
-      end
-      
-      [1, 1.0, "string"].each do |literal|
-        it "should return literal '#{literal}' as is" do
-          result = @interpreter.evaluate(literal)
-          result.should be literal
-        end
-      end
-    end
-    
-  end
-end

data/spec/flea/standard_library/addition_operator_spec.rb

@@ -1,23 +0,0 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
-
-describe "Standard Library" do
-  describe "addition operator" do
-    before :each do
-      @interpreter = Flea::Interpreter.new
-    end
-    
-    it "should add several numbers" do
-      result = @interpreter.run('(+ 1 2 3)')
-      result.should == 6
-    end
-    
-    it "should evaluate its arguments before adding them" do
-      result = @interpreter.run('
-        (define a 2)
-        (+ a a a)
-      ')
-      result.should == 6
-    end
-    
-  end
-end

data/spec/flea/standard_library/append_spec.rb

@@ -1,17 +0,0 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
-
-describe "Standard Library" do
-  describe "append" do
-    before :each do
-      @interpreter = Flea::Interpreter.new
-    end
-    
-    it "union of two lists" do
-      result = @interpreter.run('
-        (append (quote (1 2 3)) (quote (1 2 3)))
-      ')
-      result.should == [1, 2, 3, 1, 2, 3]
-    end
-    
-  end
-end

data/spec/flea/standard_library/begin_spec.rb

@@ -1,20 +0,0 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
-
-describe "Standard Library" do
-  describe "begin" do
-    before :each do
-      @interpreter = Flea::Interpreter.new
-    end
-  
-    it "should execute each expression after the begin call and return final value" do
-      result = @interpreter.run('
-        (begin
-          (define test 1)
-          (set! test 2))
-      ')
-      result.should == 2
-      @interpreter.base_environment.find(:test).should == 2
-    end
-    
-  end
-end

data/spec/flea/standard_library/car_spec.rb

@@ -1,17 +0,0 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
-
-describe "Standard Library" do
-  describe "car" do
-    before :each do
-      @interpreter = Flea::Interpreter.new
-    end
-    
-    it "should return first item of list" do
-      result = @interpreter.run('
-        (car (quote (10 2 2)))
-      ')
-      result.should == 10
-    end
-    
-  end
-end

data/spec/flea/standard_library/cdr_spec.rb

@@ -1,17 +0,0 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
-
-describe "Standard Library" do
-  describe "cdr" do
-    before :each do
-      @interpreter = Flea::Interpreter.new
-    end
-    
-    it "should return remainder of list" do
-      result = @interpreter.run('
-        (cdr (quote (10 2 2)))
-      ')
-      result.should == [2, 2]
-    end
-    
-  end
-end

data/spec/flea/standard_library/cons_spec.rb

@@ -1,25 +0,0 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
-
-describe "Standard Library" do
-  describe "cons" do
-    before :each do
-      @interpreter = Flea::Interpreter.new
-    end
-    
-    it "should create a list from an atom and an empty list" do
-      result = @interpreter.run("(cons 'a '())")
-      result.should == [:a]
-    end
-    
-    it "should create a list from a pair of lists" do
-      result = @interpreter.run("(cons '(a) '(b c d))")
-      result.should == [[:a], :b, :c, :d]
-    end
-    
-    it "should push an atom on an existing list" do
-      result = @interpreter.run('(cons "a" \'(b c ))')
-      result.should == ["a", :b, :c]
-    end
-    
-  end
-end

data/spec/flea/standard_library/display_spec.rb

@@ -1,36 +0,0 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
-
-describe "Standard Library" do
-  describe "display" do
-    before :each do
-      @interpreter = Flea::Interpreter.new
-      @old_stdout = $stdout
-      @buffer = StringIO.new
-      $stdout = @buffer
-    end
-    
-    it "should output simple literal" do
-      @interpreter.run('(display 1)')
-      @buffer.string.should == "1"
-    end
-    
-    it "should output a list" do
-      @interpreter.run('(display (quote (1 2 3)))')
-      @buffer.string.should == "(1 2 3)"
-    end
-    
-    it "should output true and false using Scheme external representation" do
-      @interpreter.run('(display #t)(display #f)')
-      @buffer.string.should == "#t#f"
-    end
-    
-    it "should return the same value that it displayed" do
-      result = @interpreter.run('(display "abc")')
-      result.should == "abc"
-    end
-    
-    after :each do
-      $stdout = @old_stdout
-    end
-  end
-end