rubylisp 0.2.1 → 1.0.2

data/lib/rubylisp/{special_forms.rb → prim_special_forms.rb}

@@ -1,128 +1,140 @@
 # -*- coding: utf-8 -*-
 module Lisp
 
-  class SpecialForms
+  class PrimSpecialForms
 
     def self.register
-      Primitive.register("cond", 
+      Primitive.register("cond", "*",
                          "(cond (predicate sexpr...)... [(else sexpr...)])\n\nEach predicate is evaluated in order until one results in true value. The expressions associated with this predicate are then evaluated in order, and the result of the `cond` is the result of the last evaluation. If all predicates evaluate to false values, the value of `cond` in indeterminate. If, however, the final predicate is the symbol `else` the expressions associated with it are evaluated, and the value of `cond` is the value of the last evaluation.",
                          true) do |args, env|
-                           Lisp::SpecialForms::cond_impl(args, env)
+                           Lisp::PrimSpecialForms::cond_impl(args, env)
                          end
 
-      Primitive.register("case", 
+      Primitive.register("case", ">=1",
                          "(case target-sexpr ((value...) sexpr...)... [(else sexpr...)])\n\n`case` chooses code to evaluate based on the value of the target `sexpr`. Each condition clause is a list of possible values. A clause is selected if the target value is in it’s list of possible values. Any number of expressions can be associated with each target value.",
                          true) do |args, env| 
-                           Lisp::SpecialForms::case_impl(args, env)
+                           Lisp::PrimSpecialForms::case_impl(args, env)
                          end
                          
-      Primitive.register("if", 
+      Primitive.register("if", "2|3",
                          "(if condition true-clause)\n(if condition true-clause false-clause)\n\n`if` has two forms, one that conditionally evaluates a single `sexpr` (see `begin` which provides a way to use multiple `sexprs` in this context) and one that chooses an `sexpr` to evaluate based on the value of the condition.\n\nIn the single action version, `nil` is the value of the form when the conditions evaluates to `false`. Note that it is preferable to use `when` (see below) instead of this form of `if`.",
                          true) do |args, env|
-                           Lisp::SpecialForms::if_impl(args, env)
+                           Lisp::PrimSpecialForms::if_impl(args, env)
                          end
                          
-      Primitive.register("when", 
+      Primitive.register("when", ">=2",
                          "(when condition sexpr...)\n\nIff the condition evaluates to logically true, the `sexprs` are evaluated and the result of the last one is the result of the form, otherwise nil is the result.",
                          true) do |args, env|
-                           Lisp::SpecialForms::when_impl(args, env)
+                           Lisp::PrimSpecialForms::when_impl(args, env)
                          end
                          
-      Primitive.register("unless", 
+      Primitive.register("unless", ">=2",
                          "(unless condition sexpr...)\n\nIff the condition evaluates to logically false, the `sexprs` are evaluated and the result of the last one is the result of the form, otherwise nil is the result. This is the same functionally as `(when (not condition) sexpr...)` but is simpler and can be clearer.", 
                          true) do |args, env| 
-                           Lisp::SpecialForms::unless_impl(args, env)
+                           Lisp::PrimSpecialForms::unless_impl(args, env)
                          end
                          
-      Primitive.register("lambda", 
-                         "(lambda (param...) sexpr...)\n\nCreates an anonymous function. This can then be used in a function call.\n\n    ((lambda (x)\n      (+ x x))\n    5) ⇒ 10\n\nFunctions can be named (i.e. bound to a symbol) and later referred to by using define (but using `defun` is preferred):\n\n    (define foo (lambda (x)\n                  (+ x x)))\n    (foo 5) ⇒ 10\n\n`lambda` creates a local environment at the point of it’s evaluation. This environment is attached to the resulting function, and any binding or symbol lookup starts in this local environment.", 
+      Primitive.register("lambda", ">=1",
+                         "(lambda ([param...]) sexpr...)\n\nCreates an anonymous function. This can then be used in a function call.\n\n    ((lambda (x)\n      (+ x x))\n    5) ⇒ 10\n\nFunctions can be named (i.e. bound to a symbol) and later referred to by using define:\n\n    (define foo (lambda (x)\n                  (+ x x)))\n    (foo 5) ⇒ 10\n\n`lambda` creates a local environment at the point of it’s evaluation. This environment is attached to the resulting function, and any binding or symbol lookup starts in this local environment.", 
                         true) do |args, env|
-                          Lisp::SpecialForms::lambda_impl(args, env)
+                          Lisp::PrimSpecialForms::lambda_impl(args, env)
                         end
                         
-      Primitive.register("define",
+      Primitive.register("define", ">=2",
                          "(define symbol value)\n\nEvaluates the value expression and binds it to the symbol, returning the value.",
                          true) do |args, env| 
-                           Lisp::SpecialForms::define_impl(args, env)
+                           Lisp::PrimSpecialForms::define_impl(args, env)
                          end
                          
-      Primitive.register("defun",
-                         "(defun (symbol param...) doc-string sexpr...)\n\nCreate a named function:\n\n`symbol` specifies the name (how you reference the function)\n\n`param...` parameters of the function, these are bound to the respective arguments when the function is called.\n\n`doc-string` is an optional documentation string.\n\n`sexpr...` the sequence of expressions that are evaluated in order when the function is called. The final evaluation result becomes the value of evaluation of the function.",
-                         true) do |args, env| 
-                           Lisp::SpecialForms::defun_impl(args, env)
-                         end
-                         
-      Primitive.register("defmacro",
+      Primitive.register("defmacro", "2|3",
                          "(defmacro (symbol param...) sexpr)\n\nCreate a named macro:\n\n`symbol` specifies the name (how you reference the macro)\n\n`param...` parameters of the macro, these are bound to the respective arguments when the macro is invoked. **NOTE** that the arguments to a macro invokation are **not** evaluated, but are passed as is to the macro to do with as it wishes.\n\n`sexpr` the template expression that is processed when the macro is invoked. The result of evaluating the processed template expression becomes the value of the macro's invocation.", 
                          true) do |args, env|
-                           Lisp::SpecialForms::defmacro_impl(args, env)
+                           Lisp::PrimSpecialForms::defmacro_impl(args, env)
                          end
       
-      Primitive.register("let", 
+      Primitive.register("let", "*",
                          "(let ((name value)...) sexpr...)\n\nCreate a local scope and bindings for evaluating a body of code. The first argument is a list of bindings. Each binding is a raw symbol (doesn’t get evaluated) that is the name to be bound, and a value (which is evaluated). These bindings are added to a scope that is local to the let. The body is evaluated in this local scope. The value of the `let` is the last evaluation result. Bindings values are evaluated in the environment where the `let` is defined, and so are independant.", 
                          true) do |args, env|
-                           Lisp::SpecialForms::let_impl(args, env)
+                           Lisp::PrimSpecialForms::let_impl(args, env)
                          end
                          
-      Primitive.register("let*", 
+      Primitive.register("let*", "*",
                          "(let* ((name value)...) sexpr...)\n\nCreate a local scope and bindings for evaluating a body of code. The first argument is a list of bindings. Each binding is a raw symbol (doesn’t get evaluated) that is the name to be bound, and a value (which is evaluated). Each binding’s value is evaluated in the context of the local scope. I.e. bindings cascade. The body is evaluated in this local scope. The value of the `let*` is the last evaluation result.",
                          true) do |args, env|
-                           Lisp::SpecialForms::letstar_impl(args, env)
+                           Lisp::PrimSpecialForms::letstar_impl(args, env)
                          end
                          
-      Primitive.register("begin",
+      Primitive.register("begin", ">=1",
                          "(begin sexpr...)\n\nEvaluates the each `sexpr` in order, returning the result of the last one evaluated. Used in a context that allows a single `sexpr` but you need multiple.",
                          true) do |args, env|
-                           Lisp::SpecialForms::begin_impl(args, env)
+                           Lisp::PrimSpecialForms::begin_impl(args, env)
                          end
                          
-      Primitive.register("do",
+      Primitive.register("do", ">=2",
                          "(do ((name initial next)...) ((test sexpr...)) sexpr...)\n\nThis is a general purpose iteration construct. There are three sections:\n\nbindings\nThis is similar to `let` in that it defines names that can be used in the remainder of the scope of the `do`. Like `let` it is a list of lists, each starting with the binding name followed by the initial value of the binding. The difference is that this is followed by an expression that is evaluated at the beginning of each subsequent pass through the loop, and whose result is used as a new binding of the name.\n\ntermination\nThis is a list whose first element is an expression which is evaluated before each pass through the loop (after rebinding the variables). If it evaluates to a truthy value, the remaining expressions are evaluated in turn. The result of the final one is used as the value of the `do`.\n\nbody\nThis is a sequence of expressions that are evaluated in order each time though the loop. This section can be empty.",
                          true) do |args, env|
-                           Lisp::SpecialForms::do_impl(args, env)
+                           Lisp::PrimSpecialForms::do_impl(args, env)
                          end
                          
-      Primitive.register("eval",
+      Primitive.register("eval", "1",
                          "(eval sexpr)\n\nEvaluate `sexpr`.",
                          true) do |args, env|
-                           Lisp::SpecialForms::eval_impl(args, env)
+                           Lisp::PrimSpecialForms::eval_impl(args, env)
                          end
                          
-      Primitive.register("apply",
+      Primitive.register("apply", ">=2",
                          "(apply function sexpr...)\n\nApply the function that results from evaluating `function` to the argument list resulting from evaluating each `sexpr`. Each initial `sexpr` can evaluate to any type of object, but the final one (and there must be at least one `sexpr`) must evaluate to a list.",
                          true) do |args, env|
-                           Lisp::SpecialForms::apply_impl(args, env)
+                           Lisp::PrimSpecialForms::apply_impl(args, env)
                          end
                          
-      Primitive.register("=>",
+      Primitive.register("=>", ">=2",
                          "(=> value sexpr|symbol...)\n\nThis creates a cascade.\n\n`value` (evaluated once at the beginning) is used as the initial argument to **each** function, and they are independent and do not pass results one to another. `value` is the result of the form.\n\nSince this is implemented by syntactic modification, a `lambda` form **cannot** be used here as an `sexpr`.",
                          true) do |args, env|
-                           Lisp::SpecialForms::tap_impl(args, env)
+                           Lisp::PrimSpecialForms::tap_impl(args, env)
                          end
                          
-      Primitive.register("->",
+      Primitive.register("->", ">=2",
                          "(-> value sexpr|symbol...)\n\nThis creates a function chain. `value` (evaluated first) is used as the first argument to the first `sexpr`. The result of each `sexpr` is used as the first argument of the next, and the result of the final `sexpr` is the value of the `->` form. If a `sexpr` would take a single argument (which would be provided by the `value` or the result of the previous `sexpr`, just the function name can be used. Since this is implemented by syntactic modification, a `lambda` form cannot be used here as an `sexpr`.\n\nThe form `(-> 0 a b c)` is equivalent to `(c (b (a 0)))`.",
                          true) do |args, env|
-                           Lisp::SpecialForms::chain_impl(args, env)
+                           Lisp::PrimSpecialForms::chain_impl(args, env)
                          end
                          
-      Primitive.register("quote", "(quote _expr_)\n\nSurpresses evaluation of the expression.\n\n         (quote (+ 1 2)) ⇒ (+ 1 2)\n\nThere is a shortcut for quote that uses the single quote:\n\n        '(+ 1 2) ⇒ (+ 1 2)") do |args, env|
-        Lisp::SpecialForms::quote_impl(args, env)
-      end
+      Primitive.register("quote", "1",
+                         "(quote _expr_)\n\nSurpresses evaluation of the expression.\n\n         (quote (+ 1 2)) ⇒ (+ 1 2)\n\nThere is a shortcut for quote that uses the single quote:\n\n        '(+ 1 2) ⇒ (+ 1 2)",
+                         true) do |args, env|
+                           Lisp::PrimSpecialForms::quote_impl(args, env)
+                         end
       
-      Primitive.register("quasiquote", "(quasiquote _sexpr_)\n\nThis defines a template expression that can be filled in by unquote and unquote-splicing. The backquote character can be used as a shorthand for quasiquote: `sexpr.") do |args, env|
-        Lisp::SpecialForms::quasiquote_impl(args, env)
-      end
+      Primitive.register("quasiquote", "1",
+                         "(quasiquote _sexpr_)\n\nThis defines a template expression that can be filled in by unquote and unquote-splicing. The backquote character can be used as a shorthand for quasiquote: `sexpr.",
+                         true) do |args, env|
+                           Lisp::PrimSpecialForms::quasiquote_impl(args, env)
+                         end
       
-      Primitive.register("gensym", "(gensym)\n(gensym _prefix_)\n\nThis creates a unique symbol. If you provide the optional prefix string it is
-used as the initial part of the symbol, otherwise GENSYM is used. gensym is
-useful in macros when you need a unique name for something.") do |args, env|
-        Lisp::SpecialForms::gensym_impl(args, env)
-      end
+      Primitive.register("gensym", "0|1",
+                         "(gensym)\n(gensym _prefix_)\n\nThis creates a unique symbol. If you provide the optional prefix string it is used as the initial part of the symbol, otherwise GENSYM is used. gensym is useful in macros when you need a unique name for something.",
+                         true) do |args, env|
+                           Lisp::PrimSpecialForms::gensym_impl(args, env)
+                         end
       
-      Primitive.register("expand", "(expand _symbol_ _sexpr_...)\n\nExpands the macro named by symbol, passing the evaluated sequence of sexpr as arguments.\n\nNOTE: whereas invoking the macro (in the same way you invoke a function) expands and evaluates, expand (as you would expect) only expands the macro, resulting in the expanded template sexpr. This can then be evaluated as desired.") do |args, env|
-        Lisp::SpecialForms::expand_impl(args, env)
-      end
+      Primitive.register("expand", ">=1",
+                         "(expand _symbol_ _sexpr_...)\n\nExpands the macro named by symbol, passing the evaluated sequence of sexpr as arguments.\n\nNOTE: whereas invoking the macro (in the same way you invoke a function) expands and evaluates, expand (as you would expect) only expands the macro, resulting in the expanded template sexpr. This can then be evaluated as desired.",
+                         true) do |args, env|
+                           Lisp::PrimSpecialForms::expand_impl(args, env)
+                         end
+      
+      Primitive.register("doc-string", "1",
+                         "(doc-string _symbol_)\n\Prints the documentation associated with the form, function, or macro named by symbol.",
+                         true) do |args, env|
+                           Lisp::PrimSpecialForms::doc_string_impl(args, env)
+                         end
+      
+      Primitive.register("definition", "1",
+                         "(definition _symbol_)\n\Prints the code associated with the function or macro named by symbol.",
+                         true) do |args, env|
+                           Lisp::PrimSpecialForms::definition_impl(args, env)
+                         end
       
       @@SYMBOL_COUNT = 0
     end
@@ -164,12 +176,11 @@ useful in macros when you need a unique name for something.") do |args, env|
           return Lisp::Debug.process_error("Case requires non-atomic clauses", env)
         end
       end
-      return nil
+      nil
     end
 
 
     def self.if_impl(args, env)
-      return Lisp::Debug.process_error("IF requires a condition, true action, and possibly an else action", env) unless args.length == 2 || args.length == 3
       condition = args.car.evaluate(env)
       if condition.true?
         args.cadr.evaluate(env)
@@ -182,7 +193,6 @@ useful in macros when you need a unique name for something.") do |args, env|
 
 
     def self.when_impl(args, env)
-      return Lisp::Debug.process_error("WHEN requires a condition and sexprs to evaluate.", env) unless args.length >= 2
       condition = args.car.evaluate(env)
       return args.cdr.evaluate_each(env) if condition.true?
       nil
@@ -190,7 +200,6 @@ useful in macros when you need a unique name for something.") do |args, env|
 
 
     def self.unless_impl(args, env)
-      return Lisp::Debug.process_error("UNLESS requires a condition and sexprs to evaluate.", env) unless args.length >= 2
       condition = args.car.evaluate(env)
       return args.cdr.evaluate_each(env) unless condition.true?
       nil
@@ -200,7 +209,7 @@ useful in macros when you need a unique name for something.") do |args, env|
     def self.lambda_impl(args, env)
       arguments = args.car
       body = args.cdr
-      Lisp::Function.new("lambda", arguments, "", body, env)
+      Lisp::Function.new("anonymous_function", arguments.empty? ? nil : arguments, "", body, env)
     end
 
 
@@ -208,7 +217,7 @@ useful in macros when you need a unique name for something.") do |args, env|
       return Lisp::Debug.process_error("Variable names must be literal symbols.", env) unless definition.symbol?
 
       ev = value.evaluate(env)
-      Lisp::EnvironmentFrame.global.bind(definition, ev)
+      env.bind_locally(definition, ev)
       ev
     end
 
@@ -228,13 +237,6 @@ useful in macros when you need a unique name for something.") do |args, env|
     end
 
 
-    def self.defun_impl(args, env)
-      definition = args.car
-      return Lisp::Debug.process_error("Function definition must specify name and parameters in a list", env) unless definition.list?
-      define_function(definition, args.cdr, env)
-    end
-    
-    
     def self.define_impl(args, env)
       definition = args.car
       if definition.list?
@@ -247,12 +249,11 @@ useful in macros when you need a unique name for something.") do |args, env|
 
 
     def self.defmacro_impl(args, env)
-      return Lisp::Debug.process_error("defmacro requires 2 or 3 arguments: a name and argument list, and a template expression.", env) unless args.length == 2 || args.length == 3
       definition = args.car
       return Lisp::Debug.process_error("defmacro requires macro name and args in a list as it's first argument.", env) if definition.nil? || !definition.list?
       name = definition.car
       arguments = definition.cdr
-      doc = nil
+      doc = ""
       if args.cadr.string?
         doc = args.cadr
         body = args.caddr
@@ -275,13 +276,27 @@ useful in macros when you need a unique name for something.") do |args, env|
                  "GENSYM"
                else
                  return Lisp::Debug.process_error("gensym's argument must be a string", env) unless args.car.string?
-                 args.car.to_s
+                 args.car.evaluate(env).to_s
                end
       sym = Lisp::Symbol.named("#{prefix}-#{@@SYMBOL_COUNT}")
       @@SYMBOL_COUNT += 1
       sym
     end
 
+
+    def self.doc_string_impl(args, env)
+      thing = args.car.evaluate(env)
+      return Lisp::Debug.process_error("doc-string expects a form, macro, or function as its argument", env) unless thing.macro? || thing.function? || thing.primitive?
+      puts thing.doc
+    end
+
+    
+    def self.definition_impl(args, env)
+      thing = args.car.evaluate(env)
+      return Lisp::Debug.process_error("definition expects a macro or function as its argument", env) unless thing.macro? || thing.function?
+      puts thing.body.print_string
+    end
+
     
     def self.expand_impl(args, env)
       macro = args.car.evaluate(env)
@@ -291,7 +306,9 @@ useful in macros when you need a unique name for something.") do |args, env|
     
 
     def self.process_quasiquoted(sexpr, level, env)
-      if !sexpr.list?
+      if sexpr.nil?
+        ConsCell.new
+      elsif !sexpr.list?
         ConsCell.cons(sexpr)
       elsif sexpr.car.symbol? && sexpr.car.name == "quasiquote"
         ConsCell.cons(ConsCell.cons(Symbol.named("quasiquote"), process_quasiquoted(sexpr.cadr, level + 1, env)))
@@ -308,7 +325,8 @@ useful in macros when you need a unique name for something.") do |args, env|
           ConsCell.cons(ConsCell.cons(Symbol.named("unquote-splicing"), process_quasiquoted(sexpr.cadr, level - 1, env)))
         end
       else
-        l = ConsCell.array_to_list(sexpr.to_a.map {|e| process_quasiquoted(e, level, env)}).flatten
+        processed_sexpr = sexpr.to_a.map {|e| process_quasiquoted(e, level, env)}
+        l = ConsCell.array_to_list(processed_sexpr).flatten
         ConsCell.cons(l)
       end
     end
@@ -333,7 +351,7 @@ useful in macros when you need a unique name for something.") do |args, env|
     def self.let_impl(args, env)
       bindings = args.car || Lisp::ConsCell.new
       return Lisp::Debug.process_error("let requires a list of bindings as it's firest argument", env) unless bindings.list?
-      local_frame = EnvironmentFrame.extending(env)
+      local_frame = EnvironmentFrame.extending(env, "let")
       local_frame.previous = env
       do_let_bindings(bindings, env, local_frame)
       args.cdr.evaluate_each(local_frame)
@@ -343,7 +361,7 @@ useful in macros when you need a unique name for something.") do |args, env|
     def self.letstar_impl(args, env)
       bindings = args.car || Lisp::ConsCell.new
       return Lisp::Debug.process_error("let requires a list of bindings as it's firest argument", env) unless bindings.list?
-      local_frame = EnvironmentFrame.extending(env)
+      local_frame = EnvironmentFrame.extending(env, "let*")
       do_let_bindings(bindings, local_frame, local_frame)
       args.cdr.evaluate_each(local_frame)
     end
@@ -355,14 +373,13 @@ useful in macros when you need a unique name for something.") do |args, env|
 
 
     def self.do_impl(args, env)
-      return Lisp::Debug.process_error("Do requires at least a list of bindings and a test clause", env) if args.length < 2
       bindings = args.car
       return Lisp::Debug.process_error("Do requires a list of bindings as it's first argument", env) unless bindings.list?
       test_clause = args.cadr
       return Lisp::Debug.process_error("Do requires a list of termination condition and result expressions as it's second argument", env) unless test_clause.list?
       body = args.cddr
 
-      local_frame = EnvironmentFrame.extending(env)
+      local_frame = EnvironmentFrame.extending(env, "do")
       local_frame.previous = env
 
       bindings.each do |binding|
@@ -393,7 +410,6 @@ useful in macros when you need a unique name for something.") do |args, env|
 
 
     def self.eval_impl(args, env)
-      return Lisp::Debug.process_error("eval expects a single argument, received #{args.length}.", env) if args.length != 1
       arg = args.car.evaluate(env)
       return Lisp::Debug.process_error("eval expect a list argument, received a #{arg.type}.", env) unless arg.list?
       arg.evaluate(env)
@@ -402,20 +418,18 @@ useful in macros when you need a unique name for something.") do |args, env|
 
     def self.apply_impl(args, env)
       func = args.car.evaluate(env)
-      return Lisp::Debug.process_error("Expected #{args.car} to evaluate to a function.", env) unless func.primitive? || func.function?
+      return Lisp::Debug.process_error("apply required the first qrgument to be a function but it was  #{args.car.to_s}.", env) unless func.primitive? || func.function?
 
       a = args.cdr.to_a.collect {|sexpr| sexpr.evaluate(env)}
-      arg_list = if a[-1].list?
-                   Lisp::ConsCell.array_to_list(a[0..-2], a[-1])
-                 else
-                   args.cdr
-                 end
+
+      return Lisp::Debug.process_error("Apply required the last argument to bea list but it was  #{a[-1].to_s}.", env) unless a[-1].list?
+      
+      arg_list = Lisp::ConsCell.array_to_list(a[0..-2], a[-1])
       func.apply_to(arg_list, env)
     end
 
 
     def self.chain_impl(args, env)
-      return Lisp::Debug.process_error("-> requires at the very least an initial value.", env) unless args.length > 0
       value = args.car.evaluate(env)
       cell = args.cdr
       while !cell.nil?
@@ -434,7 +448,6 @@ useful in macros when you need a unique name for something.") do |args, env|
 
 
     def self.tap_impl(args, env)
-      return Lisp::Debug.process_error("tap requires at the very least an initial value.", env) unless args.length > 0
       value = args.car.evaluate(env)
       cell = args.cdr
       while !cell.nil?