heist 0.1.0

data/History.txt

@@ -0,0 +1,21 @@
+=== Version 0.1.0 (2009-02-25)
+
+First public release
+* Data: booleans, numbers, strings, symbols, proper lists
+* Most of R5RS syntax (chapter 4)
+* Quoting, quasiquoting
+* Binding constructs, conditionals
+* Boolean logic
+* Delayed evaluation
+* Macros
+* Tail recursion
+* Continuations
+* Optional transparent lazy evaluation
+* Decent chunk of R5RS numeric library
+
+
+=== Version 0 (2009-01-12)
+
+Initial draft. Supports (define), (lambda), lexical scoping,
+closures, arithmetic and (display).
+

data/Manifest.txt

@@ -0,0 +1,53 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/heist
+lib/heist.rb
+lib/bin_spec.rb
+lib/repl.rb
+lib/builtin/primitives.rb
+lib/builtin/syntax.rb
+lib/builtin/syntax.scm
+lib/builtin/library.scm
+lib/parser/scheme.tt
+lib/parser/scheme.rb
+lib/parser/nodes.rb
+lib/runtime/runtime.rb
+lib/runtime/data/expression.rb
+lib/runtime/data/identifier.rb
+lib/runtime/data/list.rb
+lib/runtime/callable/function.rb
+lib/runtime/callable/macro.rb
+lib/runtime/callable/macro/matches.rb
+lib/runtime/callable/macro/splice.rb
+lib/runtime/callable/macro/expansion.rb
+lib/runtime/callable/continuation.rb
+lib/runtime/stack.rb
+lib/runtime/stackless.rb
+lib/runtime/frame.rb
+lib/runtime/scope.rb
+lib/runtime/binding.rb
+lib/stdlib/benchmark.scm
+lib/stdlib/birdhouse.scm
+test/test_heist.rb
+test/arithmetic.scm
+test/benchmarks.scm
+test/booleans.scm
+test/closures.scm
+test/conditionals.scm
+test/continuations.scm
+test/define_functions.scm
+test/define_values.scm
+test/delay.scm
+test/file_loading.scm
+test/let.scm
+test/lib.scm
+test/macro-helpers.scm
+test/macros.scm
+test/hygienic.scm
+test/unhygienic.scm
+test/plt-macros.txt
+test/numbers.scm
+test/vars.scm
+

data/README.txt

@@ -0,0 +1,274 @@
+= Heist
+
+Heist is a Scheme interpreter written in Ruby. It provides an executable
+for running Scheme code directly, and also allows the interpreter to be
+easily embedded in, and extended using, Ruby applications. It nominally
+targets R5RS, though is likely to be more liberal than other implementations.
+
+
+== What is Scheme?
+
+Scheme is a dialect of Lisp, one of the oldest programming languages still
+in use today. Lisp was the first language to implement conditionals, first
+class functions (lambdas), closures and recursion. Some Lisp features, such
+as closures and macros, have yet to penetrate mainstream languages and it
+has been observed that mainstream languages are slowly converging on the
+feature set of Lisp.
+
+Scheme in particular is important for its influence on current languages,
+in particular JavaScript and Ruby (JavaScript is remarkably similar to
+Scheme if you ignore the syntactic differences). It is also used in the
+much-praised book "Structure and Interpretation of Computer Programs",
+wherein it is used to explore some of the theory surrounding interpreters.
+
+It is a functional language, in that it supports first-class functions
+and many constructs that would be syntax in other languages resemble
+function calls in Scheme. However it is not purely functional as it
+allows side effects, and is more procedural in nature than, say, a
+declarative language such as Haskell. Like other Lisps, its lack of
+predefined syntax and its support for macros (functions that rewrite
+source code) make it ideal for creating new syntactic forms and embedded
+languages.
+
+
+== Features
+
+Heist nominally targets R5RS and is still in the early stages of development
+(at time of writing it is about a month old). The priority at this stage
+is runtime support for features that cannot be directly expressed as
+Scheme functions. The library is therefore rather small but the runtime
+is more advanced than some other toy Schemes I've seen.
+
+Currently implemented R5RS features include:
+
+* Boolean literals: #t and #f
+* Numeric literals for integers, reals and rationals (though rationals
+  are currently converted to floating point)
+* String and symbol literals
+* Proper lists and full (quasi)quoting with <tt>'</tt>, <tt>`</tt>,
+  <tt>,</tt>, <tt>,@</tt>
+* Macros: <tt>(syntax-rules)</tt>, <tt>(define-syntax)</tt>,
+  <tt>(let-syntax)</tt>, <tt>(letrec-syntax)</tt>. Supports keywords,
+  lists, pattern variables and ellipses down to arbitrary depth
+* Continuations: <tt>(call-with-current-continuation)</tt>, aliased
+  as <tt>(call/cc)</tt>
+* Proper tail recursion
+* Variable assignment: <tt>(define)</tt> and <tt>(set!)</tt>
+* Lambda expressions: <tt>(lambda (x) body)</tt>, including lexical
+  scoping and closures (varargs are currently not supported)
+* Control flow: <tt>(begin)</tt>, <tt>(if)</tt>, <tt>(cond)</tt>,
+  <tt>(case)</tt>
+* Binding constructs: <tt>(let)</tt>, <tt>(let*)</tt>, <tt>(letrec)</tt>
+* Iteration: named <tt>(let)</tt>, <tt>(do)</tt>
+* Delayed evaluation: <tt>(delay)</tt> and <tt>(force)</tt>
+* Logical connectives: <tt>(and)</tt>, <tt>(or)</tt>, <tt>(not)</tt>
+* Type checking: <tt>(boolean?)</tt>, <tt>(number?)</tt>, <tt>(complex?)</tt>,
+  <tt>(real?)</tt>, <tt>(rational?)</tt>, <tt>(integer?)</tt>
+* Comparators: <tt>(eqv?)</tt>, <tt>(=)</tt>, <tt>(<)</tt>, <tt>(<=)</tt>,
+  <tt>(>)</tt>, <tt>(>=)</tt>
+* Numeric library: <tt>(max)</tt>, <tt>(min)</tt>, <tt>(+)</tt>,
+  <tt>(-)</tt>, <tt>(*)</tt>, <tt>(/)</tt>, <tt>(quotient)</tt>,
+  <tt>(remainder)</tt>, <tt>(modulo)</tt>, <tt>(floor)</tt>,
+  <tt>(ceiling)</tt>, <tt>(truncate)</tt>, <tt>(round)</tt>,
+  <tt>(exp)</tt>, <tt>(log)</tt>, <tt>(sin)</tt>, <tt>(cos)</tt>,
+  <tt>(tan)</tt>, <tt>(asin)</tt>, <tt>(acos)</tt>, <tt>(atan)</tt>,
+  <tt>(expt)</tt>, <tt>(sqrt)</tt>, <tt>(zero?)</tt>, <tt>(positive?)</tt>,
+  <tt>(negative?)</tt>, <tt>(odd?)</tt>, <tt>(even?)</tt>, <tt>(abs)</tt>,
+  <tt>(gcd)</tt>, <tt>(lcm)</tt>, <tt>(factorial)</tt>,
+  <tt>(number->string)</tt>
+* String library: <tt>(display)</tt>, <tt>(newline)</tt>,
+  <tt>(string->number)</tt>
+* File loading: <tt>(load "foo.scm")</tt>, paths are relative to the
+  current file
+
+In addition to the above R5RS features, the following are provided. Heist
+allows the behaviour of some of these features to be configured on a
+per-runtime-environment basis.
+
+* <b>More-helpful-than-usual REPL</b>. Heist's REPL does not clutter
+  your display with prompts and other such cruft. It indents your
+  code automatically, supports tab completion, and output is printed
+  as comments so it's simple to copy code out of a REPL session into
+  a file without modification.
+* <b>Transparent lazy evaluation (call by need)</b>. Expressions are not
+  evaluated before being passed as arguments, instead they are
+  evaluated as and when the called function requires their values.
+* <b>Unhygienic macros</b>. Scheme mandates hygienic macros that
+  preserve lexical scoping, but other Lisps use a simpler system that
+  does not impose this restriction. Heist allows hygiene to be
+  disabled, its author not having the requisite experience to decide
+  which system he prefers yet.
+* <b>Optional continuations</b>. Supporting continuations incurs a
+  constant performance overhead, so if you don't need them you can
+  switch them off.
+
+
+== Installation and Usage
+
+  sudo gem install hoe
+  sudo gem install heist
+
+Heist can be run from the command line or embedded in Ruby applications. To
+run a Scheme file:
+
+  heist path/to/file.scm
+
+To start an REPL session:
+
+  heist -i
+
+Both these commands accept a number of runtime configuration options;
+run <tt>heist -h</tt> for more information.
+
+To embed Heist in a Ruby application, you need to create an instance of
+the runtime:
+
+  require 'rubygems'
+  require 'heist'
+  scheme = Heist::Runtime.new(options)
+
+<tt>options</tt> is an optional argument and is a hash that specifies
+the behaviour of optional parts of the runtime. For example, to enable
+lazy evaluation:
+
+  scheme = Heist::Runtime.new(:lazy => true)
+
+The full list of options is:
+
+* <tt>:continuations</tt> - sets whether continuations and <tt>(call/cc)</tt>
+  are enabled. Default is <tt>false</tt>.
+* <tt>:lazy</tt> - sets whether evaluation is lazy. By default this option
+  is <tt>false</tt> and evaluation is eager.
+* <tt>:unhygienic</tt> - set this to <tt>true</tt> to disable macro hygiene.
+
+Bear in mind that continuations and lazy evaluation are not currently
+compatible; enabling continuations forces eager evaluation. Also
+note that lazy evaluation has a slightly unpredictable effect on the
+use of macros.
+
+Every runtime gets its own copy of all the built-in functions. You can add
+your own functions written in Ruby and Heist will make them available as
+Scheme procedures. For example, for running tests I do this in my +setup+
+method:
+
+  @@env = Heist::Runtime.new
+  @@env.define('assert-equal') do |expected, actual|
+    assert_equal(expected, actual)
+  end
+
+This lets me write, for example, <tt>(assert-equal 7 (+ 3 4))</tt> in my
+tests. You can place arbitrary Ruby code in your functions, so this is
+an easy way to expose Ruby functionality to the Scheme environment.
+
+To run a Scheme file using the runtime, just call:
+
+  scheme.run("path/to/file.scm")
+
+
+== Notes
+
+This is alpha-quality software. While every attempt has been made to run
+valid Scheme code, error handling is at present very weak. Anything
+explicitly documented in this file can be assumed to work according to
+the Scheme standard, or according to the information presented here,
+and can be assumed to be reasonably stable.
+
+I have not documented how to write your own syntax using Ruby because
+it requires far too much knowledge of Heist's plumbing at present (I
+suspect this may be unavoidable). Besides, we have macros so if you
+want new syntax we've got you covered.
+
+Heist is extremely liberal as regards symbols. Any sequence of
+characters that does not contain any spaces or parentheses and that
+is not a boolean literal, a number or a string is considered a valid
+symbol. This means that syntax that should be used for chars and
+vectors will currently parse as symbols.
+
+There are currently no list operations. This may seem like a
+staggering omission but my goal initially was to work through the
+early stages of SICP, for which Heist in its current form is
+adequate. Being something of a simpleton, I wrote the list representation
+using arrays and it will need gutting and converting to linked lists
+before list operations are implemented.
+
+Macros are slightly more liberal than R5RS, in that this is a valid
+macro:
+
+  (define-syntax my-let (syntax-rules ()
+    [(my-let (name value) ... body ...)
+      (let [(name value) ...]
+        body ...)]))
+
+You are allowed to use ellipses in infix positions, as long as the
+pattern that follows the ellipsis matches input that the preceeding
+pattern would fail to match. This is, the ellipsis acts as a greedy
+star operator in regular expressions. In the above, <tt>(name value) ...</tt>
+captures input until a non-list expression is met, at which point
+<tt>body ...</tt> takes over. The following expression evaluates
+to <tt>3</tt> using this macro:
+
+  (my-let (x 2) (y 3) y)
+
+Speaking of macros, there is no distinct macro expansion stage in
+Heist. Macros are expanded as they are encountered at runtime, and
+their expansions are inlined into the AST to improve performance:
+the same macro use is never expanded more than once. Macros (and
+native syntactic forms) are first-class, so they can be easily
+aliased and used anonymously:
+
+  (define when if)
+  
+  ((syntax-rules () [(_ expr) expr])
+    (+ 3 4)) ; => 7
+
+It's not clear whether it would be useful to choose syntactic forms
+conditionally, certainly this will not work with macros as the
+inlining process will overwrite conditional code using the first
+expansion generated.
+
+Lazy evaluation mode is mainly useful for doing lambda calculus
+without being concerned about the difference between normal and
+applicative order, which for example affects the expression for
+the Y combinator. It displays some interesting properties, such
+as the fact that this is a perfectly reasonable definition for
+<tt>Y</tt>:
+
+  (define (Y f)
+    (f (Y f)))
+  ; => #<procedure:Y>
+  
+  (define fact (Y (lambda (rec)
+                    (lambda (x)
+                      (if (zero? x)
+                          1
+                          (* x (rec (- x 1))))))))
+  ; => #<procedure:fact>
+  
+  (fact 6)
+  ; => 720
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2009 James Coglan
+
+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/Rakefile

@@ -0,0 +1,12 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/heist.rb'
+
+Hoe.new('heist', Heist::VERSION) do |p|
+  p.developer('James Coglan', 'jcoglan@googlemail.com')
+  p.extra_deps = %w(oyster treetop)
+end
+
+# vim: syntax=Ruby

data/bin/heist

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+require File.dirname(__FILE__) + '/../lib/heist'
+require File.dirname(__FILE__) + '/../lib/bin_spec'
+
+begin
+options = Heist::BIN_SPEC.parse
+rescue Oyster::HelpRendered; exit
+end
+
+if options[:interactive] or options[:unclaimed].empty?
+  Heist::REPL.new(options).run
+else
+  env = Heist::Runtime.new(options)
+  env.run(File.expand_path(options[:unclaimed].first))
+end
+

data/lib/bin_spec.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'oyster'
+
+Heist::BIN_SPEC = Oyster.spec do
+  name "heist -- Ruby-powered Scheme interpreter, v. #{Heist::VERSION}"
+  author 'James Coglan <jcoglan@googlemail.com>'
+  
+  synopsis <<-EOS
+    heist -i [OPTIONS]
+    heist FILE_NAME [OPTIONS]
+  EOS
+  
+  flag :interactive, :desc =>
+        'Start an interactive Scheme session'
+  
+  flag :lazy, :default => false, :desc =>
+        'Use lazy evaluation order'
+  
+  flag :continuations, :default => false, :desc =>
+        'Enable first-class continuations and (call/cc)'
+  
+  flag :unhygienic, :default => false, :desc =>
+        'Use Common Lisp-style unhygienic macros'
+end
+

data/lib/builtin/library.scm

@@ -0,0 +1,95 @@
+; Any built-in functions that we can implement directly
+; in Scheme should go here. If at all possible, write
+; builtins in Scheme rather than Ruby.
+
+; (not x)
+; Boolean inverse of x
+(define (not x)
+  (if x #f #t))
+
+; Longhand aliases for boolean constants
+(define true #t)
+(define false #f)
+
+; (boolean? x)
+; Returns true iff x is a boolean value
+(define (boolean? x)
+  (or (eqv? x #t) (eqv? x #f)))
+
+; (number? x)
+; Returns true iff x is any type of number
+(define number? complex?)
+
+; (zero? x)
+; Returns true iff x is zero
+(define (zero? x)
+  (eqv? x 0))
+
+; (positive? x)
+; Returns true iff x > 0
+(define (positive? x)
+  (> x 0))
+
+; (negative? x)
+; Returns true iff x < 0
+(define (negative? x)
+  (< x 0))
+
+; (odd? x)
+; Returns true iff x is odd
+(define (odd? x)
+  (= 1 (remainder x 2)))
+
+; (even? x)
+; Returns true iff x is even
+(define (even? x)
+  (zero? (remainder x 2)))
+
+; (abs x)
+; Returns the absolute value of a number
+(define (abs x)
+  (if (negative? x)
+      (- x)
+      x))
+
+; (gcd x y)
+; Returns the greatest common divisor of two numbers
+; http://en.wikipedia.org/wiki/Euclidean_algorithm
+; TODO take >2 arguments
+(define (gcd x y)
+  (if (zero? y)
+      (abs x)
+      (gcd y (remainder x y))))
+
+; (lcm x y)
+; Returns the lowest common multiple of two numbers
+; http://en.wikipedia.org/wiki/Least_common_multiple
+; TODO take >2 arguments
+(define (lcm x y)
+  (/ (abs (* x y))
+     (gcd x y)))
+
+(define ceiling ceil)
+
+; (factorial x)
+; Returns factorial of x
+(define (factorial x)
+  (define (iter y acc)
+    (if (zero? y)
+        acc
+        (iter (- y 1) (* y acc))))
+  (iter x 1))
+
+; (newline)
+; prints a new-line character
+(define (newline)
+  (display "\n"))
+
+; (force)
+; Extracts the value of a promise created using (delay)
+(define (force promise) (promise))
+
+; (call/cc)
+; Alias for (call-with-current-continuation)
+(define call/cc call-with-current-continuation)
+