Adding some documentation in lisp.go, cleaning up some more. version now 1.0.3.0

Author: Jeff Aigner

CHANGELOG.md

@@ -1,4 +1,11 @@
 
+Version 1.0.3.0
+===============
+ *   Fixed lambda function environment copying to prevent shared env 
+ *   Adding quote built-in. Fixed car/cdr which now function properly. Added tests for car/cdr/quote
+ *   Adding print
+ *   Adding some documentation 
+
 Version 1.0.2.1
 ===============
  *   Fixing version numbering scheme

lisp.go

@@ -12,10 +12,12 @@ import (
 )
 
 const (
-	VERSION = "golisp v1.0.2.1"
-	VERBOSE = true
+	VERSION = "golisp v1.0.3.0"
 )
 
+// removeEmpty takes a list of strings
+// and removes any elements that are empty strings
+// returning a new array of string with no empty elements
 func removeEmpty(tokens []string) []string {
 	var result []string
 	for _, c := range tokens {
@@ -26,7 +28,10 @@ func removeEmpty(tokens []string) []string {
 	return result
 }
 
-func recover_error() {
+// recoverError is used to recover from panics
+// that are generated by parse / eval. It will
+// print the error and the stack trace
+func recoverError() {
 	if r := recover(); r != nil {
 		fmt.Println("Parse Error:", r)
 		buf := make([]byte, 1<<16)
@@ -36,7 +41,7 @@ func recover_error() {
 }
 
 func parse(program string) Object {
-	defer recover_error()
+	defer recoverError()
 
 	tokens := tokenize(program)
 	return build_ast(&tokens)
@@ -51,13 +56,18 @@ type Object interface{}
 
 type List []Object
 
+// String method for Number types
+// tries to print as an int, if not
+// then float
 func (n Number) String() string {
 	if float64(n) == float64(int64(n)) {
 		return fmt.Sprintf("%d", int64(n))
 	}
 	return fmt.Sprintf("%f", n)
 }
 
+// String method for List type, converts
+// into a LISP compatible list format
 func (l List) String() string {
 	var s []string
 	for _, v := range l {
@@ -76,6 +86,8 @@ type Lambda struct {
 	body  Object
 }
 
+// Build the abstract syntax tree from
+// a (pointer to a) list of tokens.
 func build_ast(tokens *[]string) Object {
 	token := pop(tokens)
 
@@ -94,6 +106,8 @@ func build_ast(tokens *[]string) Object {
 	}
 }
 
+// pop removes and return the head of a list of tokens
+// make changes in-place via pointer
 func pop(tokens *[]string) string {
 	if len(*tokens) == 0 {
 		panic("unexpected EOF while reading")
@@ -104,6 +118,8 @@ func pop(tokens *[]string) string {
 	return token
 }
 
+// atom converts a string to a primitive
+// either a Number or a Symbol
 func atom(token string) Object {
 	n, err := strconv.ParseFloat(token, 64)
 	if err == nil {
@@ -112,6 +128,7 @@ func atom(token string) Object {
 	return Symbol(token)
 }
 
+// tokenize turns a string into a list of tokens
 func tokenize(chars string) []string {
 	chars = strings.Replace(chars, "(", " ( ", -1)
 	chars = strings.Replace(chars, ")", " ) ", -1)
@@ -187,6 +204,8 @@ func print(args []Object) Object {
 	return args[0]
 }
 
+// getStandardEnv instantiates and populates
+// the standard environment used for evaluation
 func getStandardEnv() Env {
 	e := Env{
 		mapping: make(map[Symbol]Object),
@@ -207,8 +226,11 @@ func getStandardEnv() Env {
 	return e
 }
 
+// eval takes an object (from parse) and evaluates
+// it inside the environment
+// for example eval(parse("(* 2 2)"))
 func (e *Env) eval(x Object) Object {
-	defer recover_error()
+	defer recoverError()
 
 	if val, is_symbol := x.(Symbol); is_symbol {
 		return e.mapping[val]
@@ -267,6 +289,8 @@ func (e *Env) eval(x Object) Object {
 	}
 }
 
+// repl provides a REPL for the LISP machine
+// that the user can interact with
 func repl(e Env, profile_code bool) {
 	for {
 		reader := bufio.NewReader(os.Stdin)
@@ -287,6 +311,7 @@ func repl(e Env, profile_code bool) {
 	}
 }
 
+// main checks arguments and launches the REPL
 func main() {
 	profile_code := flag.Bool("profile", false, "profile code execution time")
 	show_version := flag.Bool("version", false, "show program version and exit")