comments and formatting

Author: reilandeubank

.gitignore

@@ -19,3 +19,4 @@ golox/pkg/scanner/errorHandler.txt
 golox/pkg/scanner/scanner.txt
 golox/pkg/scanner/token.txt
 golox/pkg/scanner/tokentype.txt
+/main

.idea/.gitignore

@@ -6,26 +6,31 @@ import (
 	"github.com/reilandeubank/golisp/pkg/parser"
 )
 
+// LispCallable  is the interface that LispFunction implements (unnecessary?)
 type LispCallable interface {
 	Arity() int
 	Call(i *Interpreter, arguments []interface{}) (interface{}, error)
 	String() string
 }
 
+// LispFunction is the struct that all functions in the language are stored as
 type LispFunction struct {
-	Declaration parser.FuncDefinition
-	Closure     *environment
+	Declaration   parser.FuncDefinition
+	Closure       *environment
 	IsInitializer bool
 }
 
+// String returns a string representation of the function for debugging purposes
 func (l LispFunction) String() string {
 	return "<fn " + l.Declaration.Name.Lexeme + ">"
 }
 
+// Arity is simply the number of parameters for a function (arity must match for function calls)
 func (l LispFunction) Arity() int {
 	return len(l.Declaration.Params)
 }
 
+// Call generates a new environment, defines each parameter as the passed arguments, then evaluates
 func (l LispFunction) Call(i *Interpreter, arguments []interface{}) (interface{}, error) {
 	env := NewEnvironmentWithEnclosing(*l.Closure)
 
@@ -34,4 +39,4 @@ func (l LispFunction) Call(i *Interpreter, arguments []interface{}) (interface{}
 	}
 
 	return i.evaluateFunction(l.Declaration.Body, env)
-}
+}

.idea/dictionaries/reilandeubank.xml

@@ -4,9 +4,10 @@ import (
 	"github.com/reilandeubank/golisp/pkg/scanner"
 )
 
+// environment allows for variable scope and closures. Less necessary in this implementation of Lisp
 type environment struct {
 	enclosing *environment
-	values map[string]interface{}
+	values    map[string]interface{}
 }
 
 func NewEnvironment() environment {
@@ -17,10 +18,12 @@ func NewEnvironmentWithEnclosing(Enclosing environment) environment {
 	return environment{enclosing: &Enclosing, values: make(map[string]interface{})}
 }
 
+// define a variable name as the passed value. only allowed in global scope
 func (e *environment) define(name string, value interface{}) {
-	e.values[name] = value	// this allows for variable redefinition. May be weird in normal code, but is useful for REPL
+	e.values[name] = value // this allows for variable redefinition. May be weird in normal code, but is useful for REPL
 }
 
+// get the value of a variable name. searches in enclosing environments, but throws if the variable is never found
 func (e *environment) get(name scanner.Token) (interface{}, error) {
 	value, ok := e.values[name.Lexeme]
 	if !ok && e.enclosing != nil {
@@ -30,14 +33,3 @@ func (e *environment) get(name scanner.Token) (interface{}, error) {
 	}
 	return value, nil
 }
-
-func (e *environment) assign(name scanner.Token, value interface{}) error {
-	_, ok := e.values[name.Lexeme]
-	if !ok && e.enclosing != nil {
-		return e.enclosing.assign(name, value)
-	} else if !ok {
-		return &RuntimeError{Token: name, Message: "Undefined variable '" + name.Lexeme}
-	}
-	e.values[name.Lexeme] = value
-	return nil
-}

.idea/lisp-interpreter.iml

@@ -6,16 +6,8 @@ import (
 	"github.com/reilandeubank/golisp/pkg/scanner"
 )
 
-var hadErrorFlag bool = false
-
-func HadError() bool {
-	return hadErrorFlag
-}
-
-func SetErrorFlag(val bool) {
-	hadErrorFlag = val
-}
-
+// RuntimeError defines a new Error type. Did not know this was possible until I started work on
+// the interpreter, so this would be the better way to implement my scanner and parser errors
 type RuntimeError struct {
 	Token   scanner.Token
 	Message string

.idea/modules.xml

@@ -8,8 +8,9 @@ import (
 	// "github.com/reilandeubank/golisp/pkg/parser"
 )
 
+// isTruthy shares a definition of truthiness with Go. 'nil', 0, and 'false' are false, all else are true
 func isTruthy(object interface{}) bool {
-	if object == nil || object == 0.0 || object == 0 { // only false, nil, and 0 are falsey
+	if object == nil || object == 0 { // only false, nil, and 0 are falsey
 		return false
 	}
 
@@ -41,4 +42,4 @@ func checkNumberOperands(operator scanner.Token, left interface{}, right interfa
 		return nil
 	}
 	return &RuntimeError{Token: operator, Message: "Operators must be numbers"}
-}
+}

.idea/vcs.xml

@@ -7,19 +7,22 @@ import (
 
 type Interpreter struct {
 	environment *environment
-	globals    *environment
+	globals     *environment
 }
 
+// NewInterpreter defines an interpreter instance where the environment and globals are the same environment
 func NewInterpreter() Interpreter {
 	global := NewEnvironment()
 	return Interpreter{environment: &global, globals: &global}
 }
 
+// evaluate calls the Accept method on a single expression
 func (i *Interpreter) evaluate(expr parser.Expression) (interface{}, error) {
 	return expr.Accept(i)
 }
 
-func (i *Interpreter) Interpret(exprs []parser.Expression) (error) {
+// Interpret will evaluate all expressions in the source code, printing out returned values
+func (i *Interpreter) Interpret(exprs []parser.Expression) error {
 	for _, expr := range exprs {
 		out, err := i.evaluate(expr)
 		if out != nil {
@@ -32,6 +35,8 @@ func (i *Interpreter) Interpret(exprs []parser.Expression) (error) {
 	return nil
 }
 
+// evaluateFunction will call evaluate the function's expression
+// and then return the current environment to normal after completion
 func (i *Interpreter) evaluateFunction(expression parser.Expression, environment environment) (interface{}, error) {
 	previous := i.environment
 
@@ -41,4 +46,4 @@ func (i *Interpreter) evaluateFunction(expression parser.Expression, environment
 
 	i.environment = &environment
 	return i.evaluate(expression)
-}
+}

pkg/interpreter/callable.go

@@ -8,8 +8,10 @@ import (
 	"github.com/reilandeubank/golisp/pkg/scanner"
 )
 
+// VisitListExpr evaluates a list which could be an operation, keyword and arguments, or a simple list of atoms
 func (i *Interpreter) VisitListExpr(l parser.ListExpr) (interface{}, error) {
 	switch head := l.Head.(type) {
+	// adds the tail as the operator's operands and evaluates the operator
 	case parser.Operator:
 		head.Operands = l.Tail
 		result, err := i.evaluate(head)
@@ -20,9 +22,11 @@ func (i *Interpreter) VisitListExpr(l parser.ListExpr) (interface{}, error) {
 			return nil, nil
 		}
 		return result, nil
+	// adds the tail as the keyword's arguments and evaluates it
 	case parser.Keyword:
 		head.Args = l.Tail
 		return i.evaluate(head)
+	// will simply return a list of atoms
 	case parser.Atom:
 		returnList := parser.ListExpr{Head: head, Tail: l.Tail}
 		return returnList, nil
@@ -31,15 +35,15 @@ func (i *Interpreter) VisitListExpr(l parser.ListExpr) (interface{}, error) {
 	return nil, fmt.Errorf("LISTEXPR not implemented")
 }
 
+// VisitKeywordExpr evaluates a syntax node where the keyword is of one of the
+// below types, and it contains a list of "arguments
 func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 	switch k.Keyword.Type {
-	case scanner.TRUE:
+	case scanner.TRUE: // TRUE keyword maps to Go's 'true' value
 		return true, nil
-	// case scanner.FALSE:
-	// 	return false, nil
-	case scanner.NIL:
+	case scanner.NIL: // NIL keyword maps to Go's 'nil' value (is also treated like a false value)
 		return nil, nil
-	case scanner.CAR:
+	case scanner.CAR: // car returns the first element of a list as an atom
 		car, err := i.evaluate(k.Args[0])
 		switch car.(type) {
 		case parser.ListExpr:
@@ -50,7 +54,7 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 			return nil, err
 		}
 		return car, nil
-	case scanner.CDR:
+	case scanner.CDR: // cdr returns the entire list other than the first element
 		output, err := i.evaluate(k.Args[0])
 		if err != nil {
 			return nil, err
@@ -65,7 +69,7 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 		} else {
 			return parser.ListExpr{Head: list.Tail[0]}, nil
 		}
-	case scanner.COND:
+	case scanner.COND: // cond is of the form (cond c1 r1 c2 r2...), where if c_n is true, r_n will be evaluated
 		for j := 0; j < len(k.Args); j += 2 {
 			condition, err := i.evaluate(k.Args[j])
 			if err != nil {
@@ -76,7 +80,7 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 			}
 		}
 		return nil, &RuntimeError{Token: k.Keyword, Message: "Lack of true condition"}
-	case scanner.NUMBERQ:
+	case scanner.NUMBERQ: // number? returns true if the argument is of type 'number', else nil
 		if len(k.Args) != 1 {
 			return nil, &RuntimeError{Token: k.Keyword, Message: "NUMBER? operation must have 1 operand"}
 		}
@@ -85,12 +89,12 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 			return nil, err
 		}
 		return checkNumberOperand(k.Keyword, expr)
-	case scanner.SYMBOLQ:
+	case scanner.SYMBOLQ: // symbol? returns true if the argument is a symbol, else nil
 		if len(k.Args) != 1 {
 			return nil, &RuntimeError{Token: k.Keyword, Message: "SYMBOL? operation must have 1 operand"}
 		}
 		return reflect.TypeOf(k.Args[0]) == reflect.TypeOf(parser.Symbol{}), nil
-	case scanner.LISTQ:
+	case scanner.LISTQ: // list? returns true if the argument is a list, else nil
 		if len(k.Args) != 1 {
 			return nil, &RuntimeError{Token: k.Keyword, Message: "LIST? operation must have 1 operand"}
 		}
@@ -99,7 +103,7 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 			return nil, err
 		}
 		return reflect.TypeOf(expr) == reflect.TypeOf(parser.ListExpr{}), nil
-	case scanner.NILQ:
+	case scanner.NILQ: // nil? returns true if the argument is nil, else nil
 		if len(k.Args) != 1 {
 			return nil, &RuntimeError{Token: k.Keyword, Message: "NIL? operation must have 1 operand"}
 		}
@@ -108,7 +112,7 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 			return nil, err
 		}
 		return expr == nil, nil
-	case scanner.ANDQ:
+	case scanner.ANDQ: // and? is the logical AND operation
 		if len(k.Args) != 2 {
 			return nil, &RuntimeError{Token: k.Keyword, Message: "AND? operation must have 2 operands"}
 		}
@@ -121,7 +125,7 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 			return nil, err
 		}
 		return isTruthy(left) && isTruthy(right), nil
-	case scanner.ORQ:
+	case scanner.ORQ: // or? is the logical OR operation
 		if len(k.Args) != 2 {
 			return nil, &RuntimeError{Token: k.Keyword, Message: "OR? operation must have 2 operands"}
 		}
@@ -138,7 +142,7 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 			return nil, nil
 		}
 		return result, nil
-	case scanner.NOTQ:
+	case scanner.NOTQ: // not? is the logical NOT operator
 		if len(k.Args) != 2 {
 			return nil, &RuntimeError{Token: k.Keyword, Message: "NOT? operation must have 1 operand"}
 		}
@@ -147,7 +151,7 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 			return nil, err
 		}
 		return !isTruthy(expr), nil
-	case scanner.SET:
+	case scanner.SET: // SET will declare and initialize a global variable with the first operand as the name and the second operand as the value
 		if len(k.Args) != 2 {
 			return nil, &RuntimeError{Token: k.Keyword, Message: "SET operation must have 2 operands"}
 		}
@@ -160,12 +164,13 @@ func (i *Interpreter) VisitKeywordExpr(k parser.Keyword) (interface{}, error) {
 		}
 		i.environment.define(k.Args[0].(parser.Symbol).Name.Lexeme, value)
 		return nil, nil
+	default:
+		return nil, fmt.Errorf("KEYWORDEXPR not implemented")
 	}
-	return nil, fmt.Errorf("KEYWORDEXPR not implemented")
 }
 
 func (i *Interpreter) VisitOperatorExpr(o parser.Operator) (interface{}, error) {
-	if len(o.Operands) != 2 {
+	if len(o.Operands) != 2 { // ensures that binary operators only receive 2 operands
 		return nil, &RuntimeError{Token: o.Operator, Message: "Binary operation must only have two operands"}
 	}
 	left, err := i.evaluate(o.Operands[0])
@@ -184,7 +189,7 @@ func (i *Interpreter) VisitOperatorExpr(o parser.Operator) (interface{}, error)
 			return nil, err
 		}
 		return left.(float64) - right.(float64), nil
-	case scanner.PLUS:
+	case scanner.PLUS: // + can be used with a pair of numbers or a pair of strings
 		if reflect.TypeOf(left) == reflect.TypeOf("") && reflect.TypeOf(right) == reflect.TypeOf("") {
 			return left.(string) + right.(string), nil
 		}
@@ -218,8 +223,9 @@ func (i *Interpreter) VisitOperatorExpr(o parser.Operator) (interface{}, error)
 		return left.(float64) < right.(float64), nil
 	case scanner.EQUAL:
 		return isEqual(left, right), nil
+	default:
+		return nil, &RuntimeError{Token: o.Operator, Message: "Invalid operator"}
 	}
-	return nil, &RuntimeError{Token: o.Operator, Message: "Invalid operator"}
 }
 
 func (i *Interpreter) VisitAtomExpr(a parser.Atom) (interface{}, error) {
@@ -230,7 +236,7 @@ func (i *Interpreter) VisitSymbolExpr(s parser.Symbol) (interface{}, error) {
 	return i.environment.get(s.Name)
 }
 
-func (i *Interpreter) VisitCallExpr (c parser.Call) (interface{}, error) {
+func (i *Interpreter) VisitCallExpr(c parser.Call) (interface{}, error) {
 	callee, err := i.evaluate(c.Callee)
 	if err != nil {
 		return nil, err