flea 0.1.0

data/.gitignore

@@ -0,0 +1 @@
+*.swp

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Aaron Gough (http://thingsaaronmade.com/)
+
+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.rdoc

@@ -0,0 +1,274 @@
+= 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

@@ -0,0 +1,36 @@
+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

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

data/bin/flea

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+
+require 'stringio'
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'flea.rb'))
+
+interpreter = Flea::Interpreter.new
+
+if ARGV.length > 0
+  interpreter.run(ARGF.read)
+  exit
+end
+
+loop do
+  program = []
+  indent = 0
+  loop do
+    print "> " + ("  " * indent)
+    program << gets
+    
+    tmp_program = program.join(" ")
+    open_p_count = tmp_program.count("(")
+    close_p_count = tmp_program.count(")")
+    
+    break if open_p_count == close_p_count
+    indent += 1 if program.last.count("(") > program.last.count(")")
+    indent -= 1 if program.last.count("(") < program.last.count(")")
+  end
+  program = program.join(" ")
+  exit if program.strip == "quit"
+  
+  old_stdout = $stdout
+  buffer = StringIO.new
+  $stdout = buffer
+  result = interpreter.run program
+  $stdout = old_stdout
+  print buffer.string
+  print "\n" unless buffer.string.empty?
+  puts " => #{result.inspect}"
+end

data/examples/guess-the-number.scm

@@ -0,0 +1,18 @@
+(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)

data/flea-language-spec/README.rdoc

@@ -0,0 +1,3 @@
+= Flea Language Specifcation
+
+This is a small executable language specification for Flea written using {AnySpec}[https://github.com/aarongough/any-spec]. It basically serves as an integration test-suite for the language, and provides an easy way of doing test-first development of new language features.

data/flea-language-spec/flea-language-spec.yaml

@@ -0,0 +1,2 @@
+specification_root: test-cases
+specification_extension: .scm

data/flea-language-spec/test-cases/01-display-and-basic-literals/01-display-string-literal.scm

@@ -0,0 +1,5 @@
+(display "Hello World!")
+
+----
+
+assert_output "Hello World!"

data/flea-language-spec/test-cases/01-display-and-basic-literals/02-display-integer-literal.scm

@@ -0,0 +1,5 @@
+(display 1)
+
+----
+
+assert_output "1"

data/flea-language-spec/test-cases/01-display-and-basic-literals/03-display-boolean-true-literal.scm

@@ -0,0 +1,5 @@
+(display #t)
+
+----
+
+assert_output "#t"

data/flea-language-spec/test-cases/01-display-and-basic-literals/04-display-boolean-false-literal.scm

@@ -0,0 +1,5 @@
+(display #f)
+
+----
+
+assert_output "#f"

data/flea-language-spec/test-cases/01-display-and-basic-literals/05-display-list-literal-using-quote.scm

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

data/flea-language-spec/test-cases/01-display-and-basic-literals/06-display-identifier-quoted.scm

@@ -0,0 +1,5 @@
+(display (quote test))
+
+----
+
+assert_output "test"