<commit_before>\documentclass[12pt]{article}
\usepackage{geometry} % see geometry.pdf on how to lay out the page. There's lots.
\geometry{a4paper} % or letter or a5paper or ... etc
\usepackage{graphicx}

% \geometry{landscape} % rotated page geometry

% See the ``Article customise'' template for come common customisations

\title{SteelSeries GoLisp 0.1}
\author{<NAME>}

\begin{document}

\maketitle

\section{Overview}

GoLisp is a simple Lisp implimented in Go for integrating into a Go
application to provide runtime extension and scripting. The core of a
basic Lisp in provided, but with limited special forms and primitive
functions. More of these will be added as required. 

GoLisp is a lexically scoped Lisp-1:

\begin{description}
\item[Lexically scoped:] The scope of definitions are determined by
  where they are made in the lexical structure of the code. Each
  function and let creates a new lexical scope. From~\cite{lisp}:

  \begin{quotation}
    A parameter has lexical scope if its binding is associated with
    the text interval bounded by the parentheses that delineate a
    parameter-binding form.
  \end{quotation}

\item[Lisp-1:] A Lisp where functions and variables share a single
  namespace. This differs from a Lisp-2 in which functions and
  variables have separate namespaces.
\end{description}

\section{Data types}

\begin{description}

\item[Cons Cells] are the central data type in classic Lisp used for
  both as dotted pairs \verb|(a .  b)| and general lists \verb|(a b)|.
  A cons cell is made up of two pointers, the \verb|car| and
  \verb|cdr|, as shown in Figure~\ref{fig:conscell}.

\begin{figure}[htbp] %  figure placement: here, top, bottom, or page
   \centering
   \includegraphics[width=5in]{conscell.png} 
\caption{Cons Cell.}
\label{fig:conscell}
\end{figure}

\item[Symbols] are simple identifiers, e.g. \verb|function-name|.
Symbols follow the follow simple rules: 

\begin{itemize}
\item starts with a letter, and
\item contains alphanumeric, \verb|-|, \verb|?|, and \verb|!|.
\end{itemize}

Typically, \verb|-| is used to seperate words in a symbol, \verb|?| is
used at the end of the name of a predicate function, and \verb|!| is
used at the end of the name of a function that changes some state as a
side effect (\verb|set!| is a canonical example).

Some builtin function names violate these rules (e.g. arithmetic and
relative functions). You can't create symbols like this without
adding support for them to the parser.

\item[Strings] are any sequence of characters other than \verb|"|
enclosed by a pair of \verb|"|, e.g. \verb|"string"|.

\item[Numbers] are non-negative integers internally represented as \verb|uint32| so
  their size reflects \verb|int| on the build of Go being used. E.g.
  \verb|5|, \verb|9845376|. 

\item[Booleans] represent true and false. \verb|nil|, \verb|()|, and
false are all logically false, everything else is logically true.
Boolean literals are \verb|#t| and \verb|#f| for true and false,
respectively. 

\item[Functions] are user defined procedures. They are covered in
detail later.

\item[Objects] allow you to encapsulate a Go object (struct) in a Lisp
  data object. There is no way to do this from Lisp itself, but is
  useful when writing primitive functions (see below). 

\item[Primitives] are just as they are in Lisp or Smalltalk: functions
  written in Go and exposed as functions in Lisp. The combination of
  primitives and objects allow you to integrate with the underlying Go
  program.
\end{description}

\section{Builtin functions}

\subsection{Arithmetic}

\noindent{\bf\large\verb|(+ <number>...)|}

Adds a series of numbers, e.g.

\begin{verbatim}
    (+ 4) ==> 4
    (+ 4 2) ==> 6
    (+ 4 2 7) ==> 13
\end{verbatim}

\noindent{\bf\large\verb|(- <number>...)|}

Sequentially subtracts a sequence of numbers. Negative results become
0. E.g. 

\begin{verbatim}
    (- 10 3) ==> 7
    (- 10 3 4) ==> 3
    (- 10 3 4 5) ==> 0
\end{verbatim}

\noindent{\bf\large\verb|(* <number>...)|}

Multiplies a series of numbers, e.g.

\begin{verbatim}
    (+ 4) ==> 4
    (+ 4 2) ==> 6
    (+ 4 2 7) ==> 13
\end{verbatim}

\noindent{\bf\large\verb|(/ <number>...)|}

Sequentially divides a sequence of numbers. E.g.

\begin{verbatim}
    (/ 30 2) ==> 15
    (/ 30 2 3 ) ==> 5
\end{verbatim}

\noindent{\bf\large\verb|(% <number> <number>)|}

Returns the remainder of dividion. E.g.

\begin{verbatim}
    (% 4 2) ==> 0
    (% 4 3) ==> 1 
\end{verbatim}

\subsection{Comparisons}

\noindent{\bf\large\verb|(< <number> <number>)|}

Returns whether the first argument is less than the second argument.

\begin{verbatim}
    (< 1 2) ==> #t
    (< 2 1) ==> #f
    (< 2 2) ==> #f
\end{verbatim}

\noindent{\bf\large\verb|(> <number> <number>)|}

Returns whether the first argument is greater than the second argument.

\begin{verbatim}
    (> 1 2) ==> #f
    (> 2 1) ==> #t
    (> 2 2) ==> #f
\end{verbatim}

\noindent{\bf\large\verb|(== <number> <number>)|}

Returns whether the first argument is equal to the second argument.

\begin{verbatim}
    (== 1 2) ==> #f
    (== 1 1) ==> #t
\end{verbatim}

\noindent{\bf\large\verb|(!= <number> <number>)|}

Returns whether the first argument is not equal to the second argument.

\begin{verbatim}
    (!= 1 2) ==> #t
    (!= 1 1) ==> #f
\end{verbatim}

\noindent{\bf\large\verb|(<= <number> <number>)|}

Returns whether the first argument is less than or equal to the second
argument. 

\begin{verbatim}
    (<= 1 2) ==> #t
    (<= 2 1) ==> #f
    (<= 2 2) ==> #t
\end{verbatim}

\noindent{\bf\large\verb|(>= <number> <number>)|}

Returns whether the first argument is greater than or equal to the
second argument. 

\begin{verbatim}
    (>= 1 2) ==> #f
    (>= 2 1) ==> #t
    (>= 2 2) ==> #t
\end{verbatim}

\subsection{Logical}

\noindent{\bf\large\verb|(! <arg>)|}
\noindent{\bf\large\verb|(not <arg>)|}

Returns whether the boolean negation of the argument.

\begin{verbatim}
    (! #t) ==> #f
    (! #f) ==> #t
\end{verbatim}

\noindent{\bf\large\verb|(and <arg>)|}

Computes a logical and of the arguments (which are evaluated first),
with shortcutting. I.e. each argument is evaluated in order until one
evaluates to false or the end of the list is reached. If all evaluate
to true the result of the \verb|and| is true, otherwise it is false.
If an argument evaluates to false, subsequent arguments are not
evaluated. \verb|and| with no arguments evaluates to true.

\begin{verbatim}
  
\end{verbatim}

\noindent{\bf\large\verb|(or <arg>)|}

Computes a logical or of the arguments (which are evaluated first),
with shortcutting. I.e. each argument is evaluated in order until one
evaluates to true or the end of the list is reached. If all evaluate
to false the result of the \verb|or| is false, otherwise it is true.
If an argument evaluates to true, subsequent arguments are not
evaluated. \verb|or| with no arguments evaluates to false.

\begin{verbatim}
  
\end{verbatim}

\subsection{Lists}

\noindent{\bf\large\verb|(list <arg>...)|}

Creates a list out of a sequence of values.

\begin{verbatim}
  (list 1 2 3) ==> (1 2 3)
  (list (+ 1 1) (+ 2 2) (+ 3 3)) ==> (2 4 6)
\end{verbatim}

\noindent{\bf\large\verb|(car <list>)|}

Returns the first item in the list, i.e. the car pointer of the first
conscell in the chain referenced by \verb|<list>|.

\begin{verbatim}
  (car nil) ==> nil
  (car '(a)) ==> a
  (car '(a b c)) ==> a
  (car (list (+ 1 1) (+ 2 2))) ==> 2
\end{verbatim}

\noindent{\bf\large\verb|(cdr <list>)|}

Returns the rest of the list, i.e. the cdr pointer of the first
conscell in the chain referenced by \verb|<list>|.

\begin{verbatim}
  (cdr nil) ==> nil
  (cdr '(a)) ==> nil
  (cdr '(a b c)) ==> (b c)  
  (cdr (list (+ 1 1) (+ 2 2))) ==> (2)
\end{verbatim}

The above \verb|car| and \verb|cdr| functions are the fundamental list
decomposition operations. There are more that are based on these two.
First there are a series of functions explicitly using \verb|car| and
\verb|cdr| such as \verb|caddr| which is equivalent to
\verb|(car (cdr (cdr <list>)))|. Up to \verb|cddddr| is supported.

\begin{verbatim}
  (caddr '(1 2 3 4 5)) ==> 3
  (cdddr '(1 2 3 4 5)) ==> (4 5)
\end{verbatim}

\noindent{\bf\large\verb|(first <list>)|}\\
\noindent{\bf\large\verb|(second <list>)|}\\
\noindent{\bf\large\verb|(third <list>)|}\\
\noindent{\bf\large\verb|(fourth <list>)|}\\
\noindent{\bf\large\verb|(fifth <list>)|}

These do exactly what you'd think: return the first, second, etc item
from the list.

\noindent{\bf\large\verb|(nth <list> n)|}

Returns the nth element, starting with 1.

\begin{verbatim}
  (nth '(1 2 3 4) 3) ==> 3
\end{verbatim}

\subsection{Association lists}

Association lists (aka a-lists) are a classic Lisp way to handle associating a value
with a key. Implimentation is a list of dotted pairs: the \verb|car|
is the key, and the \verb|cdr| is the value.

\noindent{\bf\large\verb|(acons <key> <value> [<a-list>])|}

This returns the result of adding a pair \verb|(<key> . <value>)| to
<a-list>. \verb|<key>|, \verb|<value>|, and \verb|<a-list>| are
evaluated. If \verb|<a-list>| is ommitted, it defaults to \verb|nil|.

\begin{verbatim}
  (acons 'a 1) ==> ((a . 1))
  (acons 'a 1 '((b . 2) (c . 3))) ==> ((a . 1) (b . 2) (c . 3)))
\end{verbatim}

\noindent{\bf\large\verb|(pairlis <keys> <values>)|}
\noindent{\bf\large\verb|(pairlis <keys> <values> <a-list>)|}

Creates an a-list from lists of keys and values. A third argument can
be provided which is an exicting a-list that the new pairs will be
added to.

\begin{verbatim}
  (pairlis '(a b) '(1 2)) ==> ((b.2) (a.1)))
  (pairlis '(a b) '(1 2) '((c.3) (d.4))) ==> ((b.2) (a.1) (c.3) (d.4))))
\end{verbatim}

Now that we have a way to create a-lists, we have a couple functions
to get data out of them.\\

\noindent{\bf\large\verb|(assoc <key> <a-list>)|}

Return the pair from \verb|<a-list>| whose \verb|car| is equal to
\verb|<key>|. The empty pair is returned is \verb|<key>| isn't found.

\begin{verbatim}
  (assoc 'a '((a.1) (b.2) (c.3))) ==> (a.1)
  (assoc 'c '((a.1) (b.2))) ==> ()
\end{verbatim}

\noindent{\bf\large\verb|(rassoc <value> <a-list>)|}

Return the pair from \verb|<a-list>| whose \verb|cdr| is equal to
\verb|<value>|. The empty pair is returned is \verb|<value>| isn't found.

\begin{verbatim}
  (rassoc '1 '((a.1) (b.2) (c.3))) ==> (a.1)
  (rassoc '3 '((a.1) (b.2))) ==> ()

\end{verbatim}

\section{Special forms}

\noindent{\bf\large\verb|(quote <expr>)|}

Surpresses evaluation of the expression.

\begin{verbatim}
     (quote (+ 1 2)) ==> (+ 1 2)
\end{verbatim}

There is a shortcut for quote that uses the single quote:

\begin{verbatim}
    '(+ 1 2) ==> (+ 1 2)
\end{verbatim}

\noindent{\bf\large\verb|(cond (<predicate> <sexpr>...)...)|}

Each 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 \verb|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
\verb|else| the expressions associated with it are evaluated, and the
value of \verb|cond| is the value of the last evaluation.

\begin{verbatim}
  (cond ((> 3 2) 'greater)
        ((< 3 2) 'less)) ==> greater

  (cond ((> 3 3) 'greater)
        ((< 3 3) 'less)
        (else 'equal)) ==> equal
\end{verbatim}

\noindent{\bf\large\verb|(case <variable> (<value> <sexpr...>) [<default sexpr>]|}

\begin{verbatim}
(define (test-func x)
  (case x
    (0 "zero")
    (1 "one")
    (2 "two")
    (3 "three")
    "unknown"))

(test-func 0) ==> "zero"
(test-func 1) ==> "one"
(test-func 2) ==> "two"
(test-func 3) ==> "three"
(test-func 5) ==> "unknown"
\end{verbatim}

\noindent{\bf\large\verb|(if <condition> <true clause>)|}

This is a special case of \verb|cond| that is more familiar to
programmers used to Algol style languages. \verb|if| has two forms,
one that conditionally evaluates a single sexpr (see below about
\verb|begin| which provides a way to use multiple sexprs in this context).

Iff the condition evaluates to logically true, the true clause is
evaluated and the result is the result of the if form, otherwise nil
is the result of the if form. 

\begin{verbatim}
    (if (< 1 2) 
        "less") ==> "less"
    (if (< 2 2) 
        "less") ==> nil
\end{verbatim}

\noindent{\bf\large\verb|(if <condition> <true clause> <else clause>)|}

If the condition evaluates to logically true, the true clause is
evaluated and the result is the result of the if form, otherwise the
else clause is evaluated and is the result of the if form. 

\begin{verbatim}
    (if (< 1 2) 
        "less" 
        "not less") ==> "less"
    (if (< 2 2) 
        "less" 
        "not less") ==> "not less"
\end{verbatim}

\noindent{\bf\large\verb|(lambda (<param>...) <expr>...)|}

Creates an anonymous function. This can then be used in a function call.

\begin{verbatim}
    ((lamdba (x) 
       (+ x x)) 
     5) ==> 10
\end{verbatim}

\verb|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. For
example, consider the following code (from~\cite{sicp}, \S~3.2.2):

\begin{verbatim}
  (define (square x)
     (* x x))

   (define (sum-of-squares x y)
     (+ (square x) (square y)))

   (define (f a)
     (sum-of-squares (+ a 1) (* a 2)))
\end{verbatim}

Each of the three functions have their own associated definition
environment pointer that points back to the global environment.

When a fucntion is executed, the implicit \verb|lambda| creates a new
envroment frame for the evaluation that (in this case) points back to
the global environment. This scoping approach is what is described in
\S~3 of \cite{sicp}.

\begin{figure}[htbp] %  figure placement: here, top, bottom, or page
   \centering
   \includegraphics[width=5in]{function_declarations.png} 
\caption{Procedure objects in the global frame.}
\label{fig:funcdefs}
\end{figure}

\begin{figure}[htbp] %  figure placement: here, top, bottom, or page
   \centering
   \includegraphics[width=5in]{function_invocations.png} 
\caption[Invocation Environments]{Environments created by evaluating
  {\tt (f 5)} using the procedures in Figure~\ref{fig:funcdefs}.}
\label{fig:funcinvocations}
\end{figure}


\noindent{\bf\large\verb|(define <symbol> <value>)|}

Evaluates the value expression and binds it to the symbol, returning
the value. 

\begin{verbatim}
    (define x (+ 2 3)) ==> 5
    x ==> 5
\end{verbatim}

Functions can be named (i.e. bound to a symbol) and later referred to
by using define:

\begin{verbatim}
  (define foo (lamdba (x) 
                (+ x x)))
  (foo 5) ==> 10  
\end{verbatim}


\noindent{\bf\large\verb|(define (<symbol> <param>...) <body>)|}

A syntacticly cleaner way to create a named function:

\verb|<symbol>| specifies the name (how you reference the function)

\verb|<param>...| parameters of the function, these are bound to the
respective arguments when the function is called. 

\verb|<body>| 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. 

\begin{verbatim}
    (define (double x)
       (+ x x))
    (double 5) ==> 10
\end{verbatim}

\noindent{\bf\large\verb|(set! <name> <new-value>)|}

The way to assign (i.e. rebind) a symbol. \verb|name| is the symbol to be rebound. The \verb|new-value| sexpr is
evaluated to arrive at the new value to be bound to. Use of
\verb|set!| is frowned upon, and should not be used without thought.
See Chapter 3 of Structure and Interpretation of Computer Programs (by
<NAME> and <NAME>) for a discussion of the pros
and cons of assignment.

\begin{verbatim}
  (define x 5)
  (set! x 10)
  x ==> 10
\end{verbatim}

Assigning takes action in the closest scope in which the symbol is
bound. In the following example, that's the global scope, so when the
let exits, \verb|x| still has the rebound value of \verb|10|.

\begin{verbatim}
  (define x 5)
  (let ()
    (set! x 10)
    x) ==> 10
  x ==> 10
\end{verbatim}

In this example, \verb|x| is bound by the let, i.e. in the local
context of the let, so the rebinding is done in the scope of the let
and doesn't extend beyond it.

\begin{verbatim}
  (define x 5)
  (let ((x 1))
    (set! x 10)
    x) ==> 10
  x ==> 5
\end{verbatim}

\noindent{\bf\large\verb|(map <function> <list>)|}

Applies \verb|function| (which has to be of a single argument) to each
element in \verb|list| in order, returning the list of the results. 

\begin{verbatim}
    (map - '(1 2 3 4))) ==> (-1 -2 -3 -4)

    (map (lambda (x)
                 (* x x))
         '(1 2 3 4)) ==> (1 4 9 16)
\end{verbatim}

\noindent{\bf\large\verb|(begin <sexpr>...)|}

Evaluates the each \verb|sexpr| in order, returning the result of the
last one evaluated. Used in a context that allows a single
\verb|sexpr| but you need multiple. E.g.

\begin{verbatim}
  (if (predicate)
      (begin
        (do-something)
        (do-something-else)))
\end{verbatim}

\noindent{\bf\large\verb|(let ((<name> <value>)...) <sexpr>...)|}

Create 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 \verb|let| is the last evaluation result. E.g.

\begin{verbatim}
  (let ((x 1)
        (y 2))
       (+ x y)) ==> 3
\end{verbatim}

Bindings cascade. I.e. each binding's value is evaluated in the
context of the local scope. E.g.

\begin{verbatim}
  (let ((x 1)
        (y (+ x 2)))
       (+ x y)) ==> 4
\end{verbatim}

As mentioned above, \verb|let| takes a sequence of sexprs as it's
body. In effect the body of the \verb|let| is an implicit
\verb|begin|.

\begin{verbatim}
  (let ((x 1)
        (y (+ x 2)))
       (do-something)
       (+ x y)) ==> 4
\end{verbatim}

\section{Testing}

Golisp has a simple builtin testing framwork.

The primary function is \verb|describe| which takes a name (as a raw
symbol) as it's first argument, followed by a sequence of expressions.
The expressions are of the form:

\begin{verbatim}
  (== <actual> <expected>)
\end{verbatim}

Generally you should create a test file for each feature you are
testing. The file is a plain lisp file and can contain any lisp code,
including global variable and function definitions.

For example, here is the test file for scoping:

\begin{verbatim}
(define a 5)

(define (foo a)
  (lambda (x) (+ a x)))

(describe global-env
          (== a 5))

(describe lambda-env
          (== ((foo 1) 5) 6)
          (== ((foo 2) 5) 7)
          (== ((foo 10) 7) 17))
\end{verbatim}

Running a test results in a stream of status output for each test,
followed at teh very end by a summary.  Running the above results in
the following:

\begin{verbatim}
Loading tests/scope_test.lsp
global-env
   (== a 5) - ok
lambda-env
   (== ((foo 1) 5) 6) - ok
   (== ((foo 2) 5) 7) - ok
   (== ((foo 10) 7) 17) - ok

Done.

4 Tests
4 Passes, 0 failures, 0 errors
\end{verbatim}

If we introduce a fialure, the output would be:

\begin{verbatim}
Loading tests/scope_test.lsp
global-env
   (== a 5) - ok
lambda-env
   (== ((foo 1) 5) 6) - ok
   (== ((foo 2) 5) 8) - failed: ((foo 2) 5) is 7
   (== ((foo 10) 7) 17) - ok

Done.
Failures:
  failed: ((foo 2) 5) is 7

4 Tests
3 Passes, 1 failures, 0 errors
\end{verbatim}
\section{Defining primitives}

The Go function \verb|MakePrimitiveFunction| allows you to create
primitive functions. This takes three arguments:

\begin{enumerate}
\item The function name. This is the name of a symbol which will be
  used to reference the function. 
\item The number of expected arguments. Using a -1 for this denotes
  any number of arguments. In the function definition you can enforce
  further constraints on argument counts and types. 
\item The Go function which impliments the primitive. This function
  {\bf must} have the signature
  \verb|func <Name>(*Data, *SymbolTableFrame) (*Data, error)| 
\end{enumerate}

\noindent The implimenting function takes two parameters as seen
above:

\begin{enumerate}
\item A Lisp list containing the arguments
\item The environment in which the primitive
  is being evaluated. This is used when calling \verb|Eval| or \verb|Apply|.
\end{enumerate}

\noindent An example:

\begin{verbatim}
    MakePrimitiveFunction("!", 1, BooleanNot)

    func BooleanNot(args *Data, env *SymbolTableFrame) 
                   (result *Data, err error) {
        if Length(args) != 1 {
            msg := fmt.Sprintf("! requires 1 argument. Received %d.", 
                               Length(args)
            err = errors.New(msg))
            return
        }

        arg, err := Eval(Car(args), env)
        if err != nil {
            return
        }

        val := BooleanValue(arg)
        return BooleanWithValue(!val), nil
     }
\end{verbatim}

\subsection{Data}

The core lisp data element is the data type which logically
contains a type tag and a value. The type tags are defined by the
constants: \verb|ConsCellType|, \verb|NumberType|, \verb|BooleanType|,
\verb|StringType|, \verb|SymbolType|, \verb|FunctionType|,
\verb|PrimitiveType|, \verb|ObjectType|.

\noindent The types are described earlier. If you need to check the
type of a piece of data you can fetch it's type using the
\verb|TypeOf(*Data) int| fuction and then compare it to a type tag
constant. Additionally there are predicate functions for the most
common types: 

\begin{description}
\item [{\tt StringP(*Data) bool}] returns whether the data is a string
\item [{\tt SymbolP(*Data) bool}] returns whether the data is a symbol
\item [{\tt NumberP(*Data) bool}] returns whether the data is a number
\item [{\tt PairP(*Data) bool}] returns whether the data is a cons cenn
  (aka pair)
\item [{\tt ObjectP(*Data) bool}] returns whether the data is an
  encapsulated Go object 
\item [{\tt FunctionP(*Data) bool}] returns whether the data is either
  a user defined or primitive function
\end{description}

\noindent Two other very handy functions are:

\begin{description}
\item [{\tt NilP(*Data) bool}] returns whether the data is nil
\item [{\tt NotNilP(*Data) bool}] returns whether the data is non-nil
\end{description}

\subsection{Creating and accessing data}

There are various convience functions that you can use to create data:

\begin{description}
\item [{\tt Cons(car *Data, cdr *Data) *Data}] creates a cons cell
  with the provided values for it's \verb|car| and \verb|cdr|.
\item [{\tt NumberWithValue(n int) *Data}] creates a number (integer)
  with the provided value
\item [{\tt BooleanWithValue(b bool) *Data}] creates a boolean with
  the provided value
\item [{\tt StringWithValue(s string) *Data}] creates a string with
  the provided value
\item [{\tt SymbolWithName(s string) *Data}] creates a symbol with the
  provided name
\item [{\tt ObjectWithTypeAndValue(thpeName string, o unsafe.Pointer) *Data}]
  creates an encapsulated Go object with the given type tag\footnote{a
    string eqivalent to the Go type of the value} and value 
\end{description}

\noindent Similarly there are functions for extracting information
from data elements: 

\begin{description}
\item [{\tt IntValue(*Data) int}] extracts the primitive integer value
\item [{\tt StringValue(*Data) string}] extracts the primitive
  string value
\item [{\tt BooleanValue(*Data) bool}] extracts the primitive
  boolean value
\item [{\tt TypeOfObject(*Data) string}] extracts the type tag of the
    encapsulated Go object
\item [{\tt ObjectValue(*Data) unsafe.Pointer}] extracts the
  primitive object value
\item [{\tt String(*Data) string}] returns a human readable string
  representation of the data 
\item [{\tt Length(*Data) int}] returns the length of a piece of Lisp 
  data. This will be 0 in all cases except lists, when it will be the
  number of elements in the list.
\item [{\tt IsEqual(*Data, o *Data) bool}] compares two expressions:
  \begin{itemize}
  \item if the two pointers point to the same thing, they are equal
  \item nil is never equal to anything
  \item data of different types are never equal
  \item if the data are lists, they are equal if corresponding pairs
    of elements are equal
  \item if values are the same (e.g. strings \& numbers) they are equal<commit_msg>Tweaked<commit_after>\documentclass[12pt]{article}
\usepackage{geometry} % see geometry.pdf on how to lay out the page. There's lots.
\geometry{a4paper} % or letter or a5paper or ... etc
\usepackage{graphicx}

% \geometry{landscape} % rotated page geometry

% See the ``Article customise'' template for come common customisations

\title{SteelSeries GoLisp 0.1}
\author{<NAME>}

\begin{document}

\maketitle

\section{Overview}

GoLisp is a simple Lisp implimented in Go for integrating into a Go
application to provide runtime extension and scripting. The core of a
basic Lisp in provided, but with limited special forms and primitive
functions. More of these will be added as required. 

GoLisp is a lexically scoped Lisp-1:

\begin{description}
\item[Lexically scoped:] The scope of definitions are determined by
  where they are made in the lexical structure of the code. Each
  function and let creates a new lexical scope. From~\cite{lisp}:

  \begin{quotation}
    A parameter has lexical scope if its binding is associated with
    the text interval bounded by the parentheses that delineate a
    parameter-binding form.
  \end{quotation}

\item[Lisp-1:] A Lisp where functions and variables share a single
  namespace. This differs from a Lisp-2 in which functions and
  variables have separate namespaces.
\end{description}

\section{Data types}

\begin{description}

\item[Cons Cells] are the central data type in classic Lisp used for
  both as dotted pairs \verb|(a .  b)| and general lists \verb|(a b)|.
  A cons cell is made up of two pointers, the \verb|car| and
  \verb|cdr|, as shown in Figure~\ref{fig:conscell}.

\begin{figure}[htbp] %  figure placement: here, top, bottom, or page
   \centering
   \includegraphics[width=5in]{conscell.png} 
\caption{Cons Cell.}
\label{fig:conscell}
\end{figure}

\item[Symbols] are simple identifiers, e.g. \verb|function-name|.
Symbols follow the follow simple rules: 

\begin{itemize}
\item starts with a letter, and
\item contains alphanumeric, \verb|-|, \verb|?|, and \verb|!|.
\end{itemize}

Typically, \verb|-| is used to seperate words in a symbol, \verb|?| is
used at the end of the name of a predicate function, and \verb|!| is
used at the end of the name of a function that changes some state as a
side effect (\verb|set!| is a canonical example).

Some builtin function names violate these rules (e.g. arithmetic and
relative functions). You can't create symbols like this without
adding support for them to the parser.

\item[Strings] are any sequence of characters other than \verb|"|
enclosed by a pair of \verb|"|, e.g. \verb|"string"|.

\item[Numbers] are non-negative integers internally represented as \verb|uint32| so
  their size reflects \verb|int| on the build of Go being used. E.g.
  \verb|5|, \verb|9845376|. 

\item[Booleans] represent true and false. \verb|nil|, \verb|()|, and
false are all logically false, everything else is logically true.
Boolean literals are \verb|#t| and \verb|#f| for true and false,
respectively. 

\item[Functions] are user defined procedures. They are covered in
detail later.

\item[Objects] allow you to encapsulate a Go object (struct) in a Lisp
  data object. There is no way to do this from Lisp itself, but is
  useful when writing primitive functions (see below). 

\item[Primitives] are just as they are in Lisp or Smalltalk: functions
  written in Go and exposed as functions in Lisp. The combination of
  primitives and objects allow you to integrate with the underlying Go
  program.
\end{description}

\section{Builtin functions}

\subsection{Arithmetic}

\noindent{\bf\large\verb|(+ <number>...)|}

Adds a series of numbers, e.g.

\begin{verbatim}
    (+ 4) ==> 4
    (+ 4 2) ==> 6
    (+ 4 2 7) ==> 13
\end{verbatim}

\noindent{\bf\large\verb|(- <number>...)|}

Sequentially subtracts a sequence of numbers. Negative results become
0. E.g. 

\begin{verbatim}
    (- 10 3) ==> 7
    (- 10 3 4) ==> 3
    (- 10 3 4 5) ==> 0
\end{verbatim}

\noindent{\bf\large\verb|(* <number>...)|}

Multiplies a series of numbers, e.g.

\begin{verbatim}
    (+ 4) ==> 4
    (+ 4 2) ==> 6
    (+ 4 2 7) ==> 13
\end{verbatim}

\noindent{\bf\large\verb|(/ <number>...)|}

Sequentially divides a sequence of numbers. E.g.

\begin{verbatim}
    (/ 30 2) ==> 15
    (/ 30 2 3 ) ==> 5
\end{verbatim}

\noindent{\bf\large\verb|(% <number> <number>)|}

Returns the remainder of dividion. E.g.

\begin{verbatim}
    (% 4 2) ==> 0
    (% 4 3) ==> 1 
\end{verbatim}

\subsection{Comparisons}

\noindent{\bf\large\verb|(< <number> <number>)|}

Returns whether the first argument is less than the second argument.

\begin{verbatim}
    (< 1 2) ==> #t
    (< 2 1) ==> #f
    (< 2 2) ==> #f
\end{verbatim}

\noindent{\bf\large\verb|(> <number> <number>)|}

Returns whether the first argument is greater than the second argument.

\begin{verbatim}
    (> 1 2) ==> #f
    (> 2 1) ==> #t
    (> 2 2) ==> #f
\end{verbatim}

\noindent{\bf\large\verb|(== <number> <number>)|}

Returns whether the first argument is equal to the second argument.

\begin{verbatim}
    (== 1 2) ==> #f
    (== 1 1) ==> #t
\end{verbatim}

\noindent{\bf\large\verb|(!= <number> <number>)|}

Returns whether the first argument is not equal to the second argument.

\begin{verbatim}
    (!= 1 2) ==> #t
    (!= 1 1) ==> #f
\end{verbatim}

\noindent{\bf\large\verb|(<= <number> <number>)|}

Returns whether the first argument is less than or equal to the second
argument. 

\begin{verbatim}
    (<= 1 2) ==> #t
    (<= 2 1) ==> #f
    (<= 2 2) ==> #t
\end{verbatim}

\noindent{\bf\large\verb|(>= <number> <number>)|}

Returns whether the first argument is greater than or equal to the
second argument. 

\begin{verbatim}
    (>= 1 2) ==> #f
    (>= 2 1) ==> #t
    (>= 2 2) ==> #t
\end{verbatim}

\subsection{Logical}

\noindent{\bf\large\verb|(! <arg>)|}
\noindent{\bf\large\verb|(not <arg>)|}

Returns whether the boolean negation of the argument.

\begin{verbatim}
    (! #t) ==> #f
    (! #f) ==> #t
\end{verbatim}

\noindent{\bf\large\verb|(and <arg>)|}

Computes a logical and of the arguments (which are evaluated first),
with shortcutting. I.e. each argument is evaluated in order until one
evaluates to false or the end of the list is reached. If all evaluate
to true the result of the \verb|and| is true, otherwise it is false.
If an argument evaluates to false, subsequent arguments are not
evaluated. \verb|and| with no arguments evaluates to true.

\begin{verbatim}
  
\end{verbatim}

\noindent{\bf\large\verb|(or <arg>)|}

Computes a logical or of the arguments (which are evaluated first),
with shortcutting. I.e. each argument is evaluated in order until one
evaluates to true or the end of the list is reached. If all evaluate
to false the result of the \verb|or| is false, otherwise it is true.
If an argument evaluates to true, subsequent arguments are not
evaluated. \verb|or| with no arguments evaluates to false.

\begin{verbatim}
  
\end{verbatim}

\subsection{Lists}

\noindent{\bf\large\verb|(list <arg>...)|}

Creates a list out of a sequence of values.

\begin{verbatim}
  (list 1 2 3) ==> (1 2 3)
  (list (+ 1 1) (+ 2 2) (+ 3 3)) ==> (2 4 6)
\end{verbatim}

\noindent{\bf\large\verb|(car <list>)|}

Returns the first item in the list, i.e. the car pointer of the first
conscell in the chain referenced by \verb|<list>|.

\begin{verbatim}
  (car nil) ==> nil
  (car '(a)) ==> a
  (car '(a b c)) ==> a
  (car (list (+ 1 1) (+ 2 2))) ==> 2
\end{verbatim}

\noindent{\bf\large\verb|(cdr <list>)|}

Returns the rest of the list, i.e. the cdr pointer of the first
conscell in the chain referenced by \verb|<list>|.

\begin{verbatim}
  (cdr nil) ==> nil
  (cdr '(a)) ==> nil
  (cdr '(a b c)) ==> (b c)  
  (cdr (list (+ 1 1) (+ 2 2))) ==> (2)
\end{verbatim}

The above \verb|car| and \verb|cdr| functions are the fundamental list
decomposition operations. There are more that are based on these two.
First there are a series of functions explicitly using \verb|car| and
\verb|cdr| such as \verb|caddr| which is equivalent to
\verb|(car (cdr (cdr <list>)))|. Up to \verb|cddddr| is supported.

\begin{verbatim}
  (caddr '(1 2 3 4 5)) ==> 3
  (cdddr '(1 2 3 4 5)) ==> (4 5)
\end{verbatim}

\noindent{\bf\large\verb|(first <list>)|}\\
\noindent{\bf\large\verb|(second <list>)|}\\
\noindent{\bf\large\verb|(third <list>)|}\\
\noindent{\bf\large\verb|(fourth <list>)|}\\
\noindent{\bf\large\verb|(fifth <list>)|}

These do exactly what you'd think: return the first, second, etc item
from the list.

\noindent{\bf\large\verb|(nth <list> n)|}

Returns the nth element, starting with 1.

\begin{verbatim}
  (nth '(1 2 3 4) 3) ==> 3
\end{verbatim}

\subsection{Association lists}

Association lists (aka a-lists) are a classic Lisp way to handle associating a value
with a key. Implimentation is a list of dotted pairs: the \verb|car|
is the key, and the \verb|cdr| is the value.

\noindent{\bf\large\verb|(acons <key> <value> [<a-list>])|}

This returns the result of adding a pair \verb|(<key> . <value>)| to
<a-list>. \verb|<key>|, \verb|<value>|, and \verb|<a-list>| are
evaluated. If \verb|<a-list>| is ommitted, it defaults to \verb|nil|.

\begin{verbatim}
  (acons 'a 1) ==> ((a . 1))
  (acons 'a 1 '((b . 2) (c . 3))) ==> ((a . 1) (b . 2) (c . 3)))
\end{verbatim}

\noindent{\bf\large\verb|(pairlis <keys> <values>)|}
\noindent{\bf\large\verb|(pairlis <keys> <values> <a-list>)|}

Creates an a-list from lists of keys and values. A third argument can
be provided which is an exicting a-list that the new pairs will be
added to.

\begin{verbatim}
  (pairlis '(a b) '(1 2)) ==> ((b.2) (a.1)))
  (pairlis '(a b) '(1 2) '((c.3) (d.4))) ==> ((b.2) (a.1) (c.3) (d.4))))
\end{verbatim}

Now that we have a way to create a-lists, we have a couple functions
to get data out of them.\\

\noindent{\bf\large\verb|(assoc <key> <a-list>)|}

Return the pair from \verb|<a-list>| whose \verb|car| is equal to
\verb|<key>|. The empty pair is returned is \verb|<key>| isn't found.

\begin{verbatim}
  (assoc 'a '((a.1) (b.2) (c.3))) ==> (a.1)
  (assoc 'c '((a.1) (b.2))) ==> ()
\end{verbatim}

\noindent{\bf\large\verb|(rassoc <value> <a-list>)|}

Return the pair from \verb|<a-list>| whose \verb|cdr| is equal to
\verb|<value>|. The empty pair is returned is \verb|<value>| isn't found.

\begin{verbatim}
  (rassoc '1 '((a.1) (b.2) (c.3))) ==> (a.1)
  (rassoc '3 '((a.1) (b.2))) ==> ()

\end{verbatim}

\section{Special forms}

\noindent{\bf\large\verb|(quote <expr>)|}

Surpresses evaluation of the expression.

\begin{verbatim}
     (quote (+ 1 2)) ==> (+ 1 2)
\end{verbatim}

There is a shortcut for quote that uses the single quote:

\begin{verbatim}
    '(+ 1 2) ==> (+ 1 2)
\end{verbatim}

\noindent{\bf\large\verb|(cond (<predicate> <sexpr>...)...)|}

Each 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 \verb|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
\verb|else| the expressions associated with it are evaluated, and the
value of \verb|cond| is the value of the last evaluation.

\begin{verbatim}
  (cond ((> 3 2) 'greater)
        ((< 3 2) 'less)) ==> greater

  (cond ((> 3 3) 'greater)
        ((< 3 3) 'less)
        (else 'equal)) ==> equal
\end{verbatim}

\noindent{\bf\large\verb|(case <variable> (<value> <sexpr...>) [<default sexpr>]|}

\begin{verbatim}
(define (test-func x)
  (case x
    (0 "zero")
    (1 "one")
    (2 "two")
    (3 "three")
    "unknown"))

(test-func 0) ==> "zero"
(test-func 1) ==> "one"
(test-func 2) ==> "two"
(test-func 3) ==> "three"
(test-func 5) ==> "unknown"
\end{verbatim}

\noindent{\bf\large\verb|(if <condition> <true clause>)|}

This is a special case of \verb|cond| that is more familiar to
programmers used to Algol style languages. \verb|if| has two forms,
one that conditionally evaluates a single sexpr (see below about
\verb|begin| which provides a way to use multiple sexprs in this context).

Iff the condition evaluates to logically true, the true clause is
evaluated and the result is the result of the if form, otherwise nil
is the result of the if form. 

\begin{verbatim}
    (if (< 1 2) 
        "less") ==> "less"
    (if (< 2 2) 
        "less") ==> nil
\end{verbatim}

\noindent{\bf\large\verb|(if <condition> <true clause> <else clause>)|}

If the condition evaluates to logically true, the true clause is
evaluated and the result is the result of the if form, otherwise the
else clause is evaluated and is the result of the if form. 

\begin{verbatim}
    (if (< 1 2) 
        "less" 
        "not less") ==> "less"
    (if (< 2 2) 
        "less" 
        "not less") ==> "not less"
\end{verbatim}

\noindent{\bf\large\verb|(lambda (<param>...) <expr>...)|}

Creates an anonymous function. This can then be used in a function call.

\begin{verbatim}
    ((lamdba (x) 
       (+ x x)) 
     5) ==> 10
\end{verbatim}

\verb|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. For
example, consider the following code (from~\cite{sicp}, \S~3.2.2):

\begin{verbatim}
  (define (square x)
     (* x x))

   (define (sum-of-squares x y)
     (+ (square x) (square y)))

   (define (f a)
     (sum-of-squares (+ a 1) (* a 2)))
\end{verbatim}

Each of the three functions have their own associated definition
environment pointer that points back to the global environment.

When a fucntion is executed, the implicit \verb|lambda| creates a new
envroment frame for the evaluation that (in this case) points back to
the global environment. This scoping approach is what is described in
\S~3 of \cite{sicp}.

\begin{figure}[htbp] %  figure placement: here, top, bottom, or page
   \centering
   \includegraphics[width=5in]{function_declarations.png} 
\caption{Procedure objects in the global frame.}
\label{fig:funcdefs}
\end{figure}

\begin{figure}[htbp] %  figure placement: here, top, bottom, or page
   \centering
   \includegraphics[width=5in]{function_invocations.png} 
\caption[Invocation Environments]{Environments created by evaluating
  {\tt (f 5)} using the procedures in Figure~\ref{fig:funcdefs}.}
\label{fig:funcinvocations}
\end{figure}


\noindent{\bf\large\verb|(define <symbol> <value>)|}

Evaluates the value expression and binds it to the symbol, returning
the value. 

\begin{verbatim}
    (define x (+ 2 3)) ==> 5
    x ==> 5
\end{verbatim}

Functions can be named (i.e. bound to a symbol) and later referred to
by using define:

\begin{verbatim}
  (define foo (lamdba (x) 
                (+ x x)))
  (foo 5) ==> 10  
\end{verbatim}


\noindent{\bf\large\verb|(define (<symbol> <param>...) <body>)|}

A syntacticly cleaner way to create a named function:

\verb|<symbol>| specifies the name (how you reference the function)

\verb|<param>...| parameters of the function, these are bound to the
respective arguments when the function is called. 

\verb|<body>| 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. 

\begin{verbatim}
    (define (double x)
       (+ x x))
    (double 5) ==> 10
\end{verbatim}

\noindent{\bf\large\verb|(set! <name> <new-value>)|}

The way to assign (i.e. rebind) a symbol. \verb|name| is the symbol to be rebound. The \verb|new-value| sexpr is
evaluated to arrive at the new value to be bound to. Use of
\verb|set!| is frowned upon, and should not be used without thought.
See Chapter 3 of Structure and Interpretation of Computer Programs (by
<NAME> and <NAME>) for a discussion of the pros
and cons of assignment.

\begin{verbatim}
  (define x 5)
  (set! x 10)
  x ==> 10
\end{verbatim}

Assigning takes action in the closest scope in which the symbol is
bound. In the following example, that's the global scope, so when the
let exits, \verb|x| still has the rebound value of \verb|10|.

\begin{verbatim}
  (define x 5)
  (let ()
    (set! x 10)
    x) ==> 10
  x ==> 10
\end{verbatim}

In this example, \verb|x| is bound by the let, i.e. in the local
context of the let, so the rebinding is done in the scope of the let
and doesn't extend beyond it.

\begin{verbatim}
  (define x 5)
  (let ((x 1))
    (set! x 10)
    x) ==> 10
  x ==> 5
\end{verbatim}

\noindent{\bf\large\verb|(map <function> <list>)|}

Applies \verb|function| (which has to be of a single argument) to each
element in \verb|list| in order, returning the list of the results. 

\begin{verbatim}
    (map - '(1 2 3 4))) ==> (-1 -2 -3 -4)

    (map (lambda (x)
                 (* x x))
         '(1 2 3 4)) ==> (1 4 9 16)
\end{verbatim}

\noindent{\bf\large\verb|(begin <sexpr>...)|}

Evaluates the each \verb|sexpr| in order, returning the result of the
last one evaluated. Used in a context that allows a single
\verb|sexpr| but you need multiple. E.g.

\begin{verbatim}
  (if (predicate)
      (begin
        (do-something)
        (do-something-else)))
\end{verbatim}

\noindent{\bf\large\verb|(let ((<name> <value>)...) <sexpr>...)|}

Create 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 \verb|let| is the last evaluation result. E.g.

\begin{verbatim}
  (let ((x 1)
        (y 2))
       (+ x y)) ==> 3
\end{verbatim}

Bindings cascade. I.e. each binding's value is evaluated in the
context of the local scope. E.g.

\begin{verbatim}
  (let ((x 1)
        (y (+ x 2)))
       (+ x y)) ==> 4
\end{verbatim}

As mentioned above, \verb|let| takes a sequence of sexprs as it's
body. In effect the body of the \verb|let| is an implicit
\verb|begin|.

\begin{verbatim}
  (let ((x 1)
        (y (+ x 2)))
       (do-something)
       (+ x y)) ==> 4
\end{verbatim}

\section{Testing}

Golisp has a simple builtin testing framwork.

The primary function is \verb|describe| which takes a name (as a raw
symbol) as it's first argument, followed by a sequence of expressions.
The expressions are of the form:

\begin{verbatim}
  (== <actual> <expected>)
\end{verbatim}

Generally you should create a test file for each feature you are
testing. The file is a plain lisp file and can contain any lisp code,
including global variable and function definitions.

For example, here is the test file for scoping:

\begin{verbatim}
(define a 5)

(define (foo a)
  (lambda (x) (+ a x)))

(describe global-env
          (== a 5))

(describe lambda-env
          (== ((foo 1) 5) 6)
          (== ((foo 2) 5) 7)
          (== ((foo 10) 7) 17))
\end{verbatim}

Running a test results in a stream of status output for each test,
followed at teh very end by a summary.  Running the above results in
the following:

\begin{verbatim}
Loading tests/scope_test.lsp
global-env
   (== a 5) - ok
lambda-env
   (== ((foo 1) 5) 6) - ok
   (== ((foo 2) 5) 7) - ok
   (== ((foo 10) 7) 17) - ok

Done.

4 Tests
4 Passes, 0 failures, 0 errors
\end{verbatim}

If we introduce a fialure, the output would be:

\begin{verbatim}
Loading tests/scope_test.lsp
global-env
   (== a 5) - ok
lambda-env
   (== ((foo 1) 5) 6) - ok
   (== ((foo 2) 5) 8) - failed: ((foo 2) 5) is 7
   (== ((foo 10) 7) 17) - ok

Done.
Failures:
  failed: ((foo 2) 5) is 7

4 Tests
3 Passes, 1 failures, 0 errors
\end{verbatim}
\section{Defining primitives}

The Go function \verb|MakePrimitiveFunction| allows you to create
primitive functions. This takes three arguments:

\begin{enumerate}
\item The function name. This is the name of a symbol which will be
  used to reference the function. 
\item The number of expected arguments. Using a -1 for this denotes
  any number of arguments. In the function definition you can enforce
  further constraints on argument counts and types. 
\item The Go function which impliments the primitive. This function
  {\bf must} have the signature
  \verb|func <Name>(*Data, *SymbolTableFrame) (*Data, error)| 
\end{enumerate}

\noindent The implimenting function takes two parameters as seen
above:

\begin{enumerate}
\item A Lisp list containing the arguments
\item The environment in which the primitive
  is being evaluated. This is used when calling \verb|Eval| or \verb|Apply|.
\end{enumerate}

\noindent An example:

\begin{verbatim}
    MakePrimitiveFunction("!", 1, BooleanNot)

    func BooleanNot(args *Data, env *SymbolTableFrame) 
                   (result *Data, err error) {
        if Length(args) != 1 {
            msg := fmt.Sprintf("! requires 1 argument. Received %d.", 
                               Length(args)
            err = errors.New(msg))
            return
        }

        arg, err := Eval(Car(args), env)
        if err != nil {
            return
        }

        val := BooleanValue(arg)
        return BooleanWithValue(!val), nil
     }
\end{verbatim}

\subsection{Data}

The core lisp data element is the data type which logically
contains a type tag and a value. The type tags are defined by the
constants: \verb|ConsCellType|, \verb|NumberType|, \verb|BooleanType|,
\verb|StringType|, \verb|SymbolType|, \verb|FunctionType|,
\verb|PrimitiveType|, \verb|ObjectType|.

\noindent The types are described earlier. If you need to check the
type of a piece of data you can fetch it's type using the
\verb|TypeOf(*Data) int| fuction and then compare it to a type tag
constant. Additionally there are predicate functions for the most
common types: 

\begin{description}
\item [{\tt StringP(*Data) bool}] returns whether the data is a string
\item [{\tt SymbolP(*Data) bool}] returns whether the data is a symbol
\item [{\tt NumberP(*Data) bool}] returns whether the data is a number
\item [{\tt PairP(*Data) bool}] returns whether the data is a cons cenn
  (aka pair)
\item [{\tt ObjectP(*Data) bool}] returns whether the data is an
  encapsulated Go object 
\item [{\tt FunctionP(*Data) bool}] returns whether the data is either
  a user defined or primitive function
\end{description}

\noindent Two other very handy functions are:

\begin{description}
\item [{\tt NilP(*Data) bool}] returns whether the data is nil
\item [{\tt NotNilP(*Data) bool}] returns whether the data is non-nil
\end{description}

\subsection{Creating and accessing data}

There are various convience functions that you can use to create data:

\begin{description}
\item [{\tt Cons(car *Data, cdr *Data) *Data}] creates a cons cell
  with the provided values for it's \verb|car| and \verb|cdr|.
\item [{\tt NumberWithValue(n int) *Data}] creates a number (integer)
  with the provided value
\item [{\tt BooleanWithValue(b bool) *Data}] creates a boolean with
  the provided value
\item [{\tt StringWithValue(s string) *Data}] creates a string with
  the provided value
\item [{\tt SymbolWithName(s string) *Data}] creates a symbol with the
  provided name
\item [{\tt ObjectWithTypeAndValue(thpeName string, o unsafe.Pointer) *Data}]
  creates an encapsulated Go object with the given type tag\footnote{a
    string eqivalent to the Go type of the value} and value 
\end{description}

\noindent Similarly there are functions for extracting information
from data elements: 

\begin{description}
\item [{\tt NumericValue(*Data) int}] extracts the primitive integer value
\item [{\tt StringValue(*Data) string}] extracts the primitive
  string value
\item [{\tt BooleanValue(*Data) bool}] extracts the primitive
  boolean value
\item [{\tt TypeOfObject(*Data) string}] extracts the type tag of the
    encapsulated Go object
\item [{\tt ObjectValue(*Data) unsafe.Pointer}] extracts the
  primitive object value
\item [{\tt String(*Data) string}] returns a human readable string
  representation of the data 
\item [{\tt Length(*Data) int}] returns the length of a piece of Lisp 
  data. This will be 0 in all cases except lists, when it will be the
  number of elements in the list.
\item [{\tt IsEqual(*Data, o *Data) bool}] compares two expressions:
  \begin{itemize}
  \item if the two pointers point to the same thing, they are equal
  \item nil is never equal to anything
  \item data of different types are never equal
  \item if the data are lists, they are equal if corresponding pairs
    of elements are equal
  \item if values are the same (e.g. strings \& numbers) they are equal
{'fraction_non_alphanumeric': 0.13353454604780163, 'fraction_numerical': 0.013948935475976833, 'mean_word_length': 3.490156579067851, 'pattern_counts': {'":': 0, '<': 221, '<?xml version=': 0, '>': 373, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2077510', 'n_tokens_mistral': 17058, 'n_tokens_neox': 16213, 'n_words': 6541}