\documentclass[twoside,twocolumn,9pt]{extarticle}
\usepackage{hyperlatex}
%\T\usepackage{layout}
\T\usepackage{longtable}
\T\usepackage{myindex}
\T\usepackage{palatino}
\T\usepackage{fancybox}
% \W\usepackage{makeidx}
% \W\include{latex-index}

\T\addtolength{\topmargin}{-1.2in}
\T\addtolength{\evensidemargin}{-0.7in}
\T\addtolength{\oddsidemargin}{-0.2in}
%\T\oddsidemargin10pt\evensidemargin20pt

%\T\textwidth5.7in
\T\textwidth7.3in
%\T\textheight8.9in
\T\textheight9.6in
%\T\advance\textwidth by 4em

% \makeindex

\include{defs}
\T\include{texdefs}

\typeout{columnwidth  = \the\columnwidth}

% Make a few big HTML files, and not a lot of small ones.
\setcounter{htmldepth}{3}

% Put the html code in its own directory.
\htmldirectory{manual}

% Set the html base name.
\htmlname{goomanual}

% Add sections to main menu
% \setcounter{htmlautomenu}{2}

% White background
\htmlattributes{BODY}{BGCOLOR="#ffffff"}

\htmltitle{\goo\ Manual}

% Suppress navigation panel for first page.
% \htmlpanel{0}

%%% End preamble

\begin{document}
\label{top_node}

\T\sloppy    % Tells TeX not to worry too much about line breaks.

\T\title{{\Huge \goo\ Reference Manual v46 }}
\T\author{{\huge Jonathan Bachrach} \\ {\Large MIT AI Lab}}
\W\title{{\huge \goo\ Reference Manual v46 }}
\W\author{{\Large Jonathan Bachrach} \\ {\Large MIT AI Lab}}
\date{\today}
%\date{October 31, 1995}

%\T\cleardoublepage\pagenumbering{roman}

\maketitle

\section{Introduction}

\goo\ is a dynamic type-based object-oriented language.  It is
designed to be simple, productive, powerful, extensible, dynamic,
efficient and real-time.  It heavily leverages features from many
earlier languages.  In particular, it attempts to be a simpler,
more dynamic, lisp-syntaxed Dylan~\cite{Shalit:1996} and an object-oriented 
Scheme~\cite{Kelsey:Clinger:Rees:hosc:1998}.
% and a lispified Cecil~\cite{Chambers95}.
\goo's main goal is to offer the best of both scripting and
delivery languages while at the same time 
incorporating an extreme back-to-basics philosophy.
\goo\ is freely available from \kode{www.googoogaga.org} under GPL.
This manual is preliminary and relies on an understanding
of Scheme and Dylan.

\subsection{Notation}

Throughout this document \goo\ objects are described with definitions
of the following form:

\begin{defs}
\notation{\it Name}{\it Signature}
  \doc{\it Documentation}
\end{defs}

where the rightmost kind field has a one letter code as follows:

\begin{defs}
\notation{N}{Notation}
\notation{L}{Lexical}
\notation{S}{Syntax}
\notation{G}{Generic}
\notation{M}{Method}
\notation{F}{Function}
\notation{C}{Class}
\notation{P}{Property}
\notation{I}{Instance}
\notation{K}{Command}
\end{defs}

\subsection{Lexical Structure}

The lexical structure is mostly the same as 
Scheme~\cite{Kelsey:Clinger:Rees:hosc:1998} with
the notable exceptions being that identifiers can start with numeric digits
if they are clearly distinguishable from floating point numbers and
% \item {\bf keywords}: identifiers ending in ':', and
no syntax is provided for specifying improper lists.
Furthermore, vertical bars are tokenized immediately and separately and have
special meaning within lists, providing syntactic sugar for typed
variables.

The following is a very brief and incomplete description
of how characters are tokenized into s-expressions, where
s-expressions are either tokens or lists of s-expressions:

\begin{defs}
\notation{; ...}{Line comment}
\notation{\#/ ... /\#}{Nested comment}
\notation{.\ + - [0-9]+}{Number}
\notation{\#e \#i \#b \newline \#o \#d \#x}{Special number}
\notation{\#t \#f}{Logical}
\notation{\#$\backslash${\it name}}{Character}
\notation{[a-zA-Z0-9]+}{Identifier}
% \notation{{\it Identifier}:}{Keyword}
\notation{( ... )}{List}
\notation{\#( ... )}{Tuple}
\notation{\#[ ... ]}{Vector}
\notation{" ... "}{String}
\notation{$\backslash${\it c} }{Special character's within strings}
\notation{x|t}{Typed variable within list $\equiv$ \kode{(x t)}.}
\notation{\#|}{Escaped vertical bar.}
\notation{\{ ... \}}{Lightweight function syntax.}
\notation{'[' ... ']'}{Collection indexing and slicing.}
\end{defs}

\subsection{Meta Syntax}

\goo's syntax is described almost entirely as \goo\ patterns.  \goo\
patterns in turn are defined with a quasiquote metasyntax.  Pattern
variables are prefixed with a ``\kode{,}'' or ``\kode{,@}'' to
indicate the matching of one or many elements respectively.  The
default is for a pattern variable to match one or many s-expressions.  
Alternatively, a pattern variable's shape may be defined with another
pattern. 
The \kode{,name} shape is builtin and matches only identifiers.
The \kode{'['...']'} metasyntax is used to indicate optional
patterns, \kode{'...'} is used to indicate zero or more of the
preceding pattern element, and \kode{\#\#} is used to denote infix
string concatenation.
Finally, in this manual, uppercase indicates a special form or macro.

\subsection{Conventions}

The following naming conventions are used throughout this manual:

\begin{defs}
\notation{'<'...'>'}{Type variable}
\notation{'*'...'*'}{Global variable}
\notation{...'?'}{Predicate}
\notation{...'!'}{Destructive function}
\notation{...'-setter'}{Setter}
\end{defs}

\section{Expressions}

Once tokenized, \goo\ evaluates s-expressions in the usual lisp manner:

\begin{defs}
\form{{\it var}}{,name}
  \doc{returns the value of binding named \kode{,name} 
       in the current environment.}
\form{{\it lit}}{,lit}
  \doc{syntactic literals that are self-evaluating.}
\form{QUOTE}{(QUOTE ,form)} 
  \doc{with \kode{',form} $\equiv$ \kode{(QUOTE ,form)} (cf., Scheme's \kode{QUOTE})}
\form{{\it special}}{(,special ,@args)}
  \doc{\goo\ defines a number of identifiers as the names of special
       forms, which if seen in function call position cause special form
       specific evaluation.}
\form{{\it call}}{(,f ,@args)}
  \doc{otherwise lists represent function calls.}
\end{defs}

\section{Namespaces and Bindings}

\goo\ is a lexically scoped language.  Bindings contain values and are
looked up by name.  Lexical bindings are
visible from only particular textual ranges in a program.  Lexical
bindings shadow visible bindings of the same name.

At the topmost level, \goo\ provides simple modules that map from
names to bindings.  Each file introduces a new module with the same
name as the file.  Nested modules are supported by way of slashes in
module names.  Modules can import bindings exported by other modules,
but currently there is no way to selectively exclude or rename
imported bindings.  Furthermore, no cycles can occur in the module use
heterarchy.

\begin{defs}
\form{D.}{(D. ,var ,form)}
  \doc{defines a global constant named \kode{(var-name ,var)} with an 
  initial value \kode{,form} (cf. Dylan's \kode{DEFINE CONSTANT}).}
\form{DV}{(DV ,var ,form)}
  \doc{defines a global variable named \kode{(var-name ,var)} with an 
  initial value \kode{,form} (cf. Dylan's \kode{DEFINE VARIABLE}).}
\form{DEF}{(DEF ,var ,val)}
  \doc{locally binds \kode{,var} to \kode{,val} and evaluates
  remainder of current body in the context of that binding.}
\formcont{(DEF (TUP ,var ...) ,val)}
  \doc{parallel binding can also be specified using \kode{TUP} on the lhs of
       a \kode{DEF} binding. For example
        \kode{(DEF (TUP x y) (TUP 1 2))}}
\form{LET}{(LET ((,var ,val) ...) ,@body)}
  \doc{$\equiv$ \kode{(SEQ (DEF ,var ,val) ... ,@body)}}
\end{defs}

where

\begin{defs}
\syntax{,var}{,name | (,name ,type)}
  \doc{with \kode{,name | ,type} $\equiv$ \kode{(,name ,type)} within lists.}
\end{defs}

\begin{defs}
\form{SET}{(SET ,name ,form) }
  \doc{sets \kode{,name} binding to value of evaluating \kode{,form}
  (cf. Scheme's \kode{SET!})}
\formcont{(SET (,name ,@args) ,form)}
  \doc{$\equiv$ \kode{(,name \#\# -setter ,form ,@args)}}
\form{USE}{(USE ,name)}
  \doc{loads the module \kode{,name} (if it hasn't been loaded
  already) and aliases
  all the exported bindings into the current namespace.}
\form{EXPORT}{(EXPORT ,name)}
  \doc{makes the binding \kode{,name} available to code which uses 
       this module in the future.}
\form{USE/EXPORT}{(USE/EXPORT ,name)}
  \doc{same as \kode{USE} plus reexports all imported bindings.}
\end{defs}

\section{Program Control}

\goo\ provides a variety of program control constructs including
function calls, conditional execution, and nonlocal control flow.

\begin{defs}
\form{SEQ}{(SEQ ,@forms)}
  \doc{evaluates forms sequentially and returns values of evaluating last
  form (cf. Scheme's \kode{BEGIN})}
\formcont{(SEQ)}
  \doc{returns false}
\form{\{ ... \}}{\{ ,@body \}}
  \doc{\kode{SEQ} abbreviation $\equiv$ \kode{(SEQ ,@body)}.}
\form{IF}{(IF ,test ,then [ ,else ])}
  \doc{evaluates either \kode{,then} if \kode{,test} is non-false
  otherwise evaluates \kode{,else} (cf. Scheme's \kode{IF}).  The
  \kode{,else} expression defaults to false.}
\form{AND}{(AND ,form ,@forms)}
  \doc{$\equiv$ \kode{(IF ,form (AND ,@FORMS))}}
\formcont{(AND ,form)}
  \doc{$\equiv$ \kode{,form}}
\form{OR}{(OR ,form ,@forms)}
   \doc{$\equiv$ \kode{(SEQ (DEF x ,form) (IF x x (OR ,@FORMS)))}}
\formcont{(OR ,form)}
  \doc{$\equiv$ \kode{,form}}
\form{UNLESS}{(UNLESS ,test ,@body)}
  \doc{$\equiv$ \kode{(IF (NOT ,test) (SEQ ,@body))}}
\form{WHEN}{(WHEN ,test ,@body)}
  \doc{$\equiv$ \kode{(IF ,test (SEQ ,@body))}}
\form{COND}{(COND (,test ,@body) ...)}
  \doc{evaluates \kode{(SEQ ,@body)} of first clause 
  whose \kode{,test} evaluates to
  non-false (cf. Dylan's \kode{CASE} and Scheme's \kode{COND}).}
\form{CASE[-BY]}{(CASE[-BY] ,value [ ,test ]\snl ((,@keys) ,@body) \snl ...)}
  \doc{evaluates \kode{,value} and then evaluates \kode{(SEQ ,@body)}
  of first clause for which \kode{(,test ,value ,key)} returns non-false
  (cf. Dylan's \kode{SELECT} and Scheme's \kode{CASE}).  N.B., each
  key is evaluated, thus symbols must be quoted.  The default
  \kode{,test} for the \kode{CASE} form is \kode{==}.}
\form{OPF}{(OPF ,place ,expr)}
  \doc{$\equiv$ \kode{(SEQ (DEF \_ ,place) (SET ,place ,expr))}, where
  \kode{,place} is evaluated only once.  For example, 
  \kode{(OPF x (+ \_ 1))} $\equiv$ \kode{(SET x (+ x 1))}.}
\form{SWAPF}{(SWAPF ,x ,y)}
  \doc{$\equiv$ \kode{(SEQ (DEF tmp ,x) (SET ,x ,y) (SET ,y tmp))},
  where \kode{,x} and \kode{,y} are evaluated only once.}
\form{ROTF}{(ROTF ,x ,y ,@places)}
  \doc{$\equiv$ \kode{(SET (TUP ,x ,y ,@places) (TUP ,y ,@places ,x))}
  where \kode{,x}, \kode{,y}, and \kode{,@places)} are evaluated only
  once and \kode{(SET (TUP ...) val)} stands for parallel assignment.}
\form{{\it call}}{(,f ,@args)}
  \doc{evaluates \kode{,f} and then \kode{,@args} in left to right
  order and then calls \kode{,f} with the evaluated arguments.}
\form{REP}{(REP ,name ((,var ,init) ...) ,@body) }
  \doc{defines a recursive loop (cf., Dylan's \kode{ITERATE} or Scheme's \kode{(LET ,var ...)}).}
\form{ESC}{(ESC ,name ,@body)}
  \doc{evaluates \kode{(SEQ ,@body)} with an exit
  function of a single parameter, \kode{x}, bound to
  \kode{,name} that if called, will cause \kode{ESC} to
  return the value of \kode{x}
  (cf. Dylan's \kode{BLOCK}/\kode{RETURN}).  It is illegal 
  to call the exit function
  after the execution of the creating \kode{ESC} form (i.e., no upward
  continuations).}
\form{FIN}{(FIN ,protected ,@cleanups)}
  \doc{ensures that \kode{(SEQ ,@cleanups)} is evaluated whether
  or not an \kode{ESC} upwards exit is taken
  during the dynamic-extent of \kode{,protected}
  (cf. Dylan's \kode{BLOCK/CLEANUP} form and CL's
  \kode{UNWIND-PROTECT}).  The result of a \kode{FIN} form is the
  result of evaluating its protected form.}
\form{ASSERT}{(ASSERT ,test ,message ,@args)}
  \doc{$\equiv$ \kode{(UNLESS ,test (ERROR ,message ,@args))}}
\end{defs}

\section{Types, Classes and Properties}

\goo\ types categorize objects.  Types are first class.  They are used
to annotate bindings.  Binding types restrict the type of objects
bindable to associated bindings.

\goo\ supports the following types in order of specificity 
(with the exact ordering defined in Appendix~\ref{subtyping}):
\begin{packeditemize}
\item {\it Singleton} types specify a unique instance,
\item {\it Classes} and {\it properties} specify the structure, 
inheritance, and
initialization of objects.  Every object is a direct instance of a
particular class,
\item {\it Product} types specify a cross product of types, 
\item {\it Subclass} types specify a lineage of classes, and
\item {\it Union} types specify a union of types.
\end{packeditemize}

The basic type protocol is:

\begin{defs}
\class{<type>}{<any>}
\generic{isa?}{x|<any> y|<type> => <log>}
\generic{subtype?}{x|<type> y|<type> => <log>}
  \doc{returns true iff \kode{x} is a subtype of \kode{y}.}
\generic{new}{type|<type> prop-inits|...}
  \doc{creation protocol taking type and creation options where
  \kode{prop-inits} contains getter / initial value pairs.}
% \generic{init}{x|<type> prop-inits|...}
%   \doc{provides user initialization opportunity.  Each \kode{init}
%        is responsible for calling \kode{next-method} to ensure inherited
%        initialization takes place.}
% \method{init}{x|<type> prop-inits|...}
%   \doc{default noop \kode{init} method.}
% \end{defs}
% 
% where
% 
% \begin{defs}
% \syntax{prop-init}{,getter ,value}
\end{defs}

\subsection{Singletons}

Singleton types match exactly one value using \kode{==}.  Singletons are 
the most specific types.

\begin{defs}
\class{<singleton>}{<type>}
\generic{t=}{x|<any> => <singleton>}
  \doc{returns singleton constrained to \kode{x}.}
\generic{type-object}{x|<singleton> => <any>}
  \doc{object that singleton type matches.}
\end{defs}

\subsection{Subclasses}

Subclass types match classes and their subclasses.  
They are quite useful in
situations that involve class arguments that need to be further constrained.

\begin{defs}
\class{<subclass>}{<type>}
\generic{t<}{x|<class> => <subclass>}
  \doc{returns subclass type constrained to subclasses of \kode{x}.}
\generic{type-class}{x|<subclass> => <class>}
  \doc{object that subclass type matches.}
\end{defs}

\subsection{Unions}

Union types represent the disjunction of types.  In conjunction with
singleton types, they can be used to represent C-style \kode{enum}'s.

\begin{defs}
\class{<union>}{<type>}
\generic{t+}{types|... => <union>}
  \doc{returns union type representing disjunction of \kode{types}.}
\generic{union-elts}{x|<union> => <seq>}
  \doc{types that union type matches.}
\function{t?}{type|<type> => <union>}
  \doc{$\equiv$ \kode{(t+ (t= \#f) type)} (cf., Dylan's
  \kode{false-or}).  This is often used to widen a type to include the
  convenient false null.}
\end{defs}

\subsection{Product}

Product types represent tuples formed as the cartesian product of
types.  They are often used to describe multiple value return types.

\begin{defs}
\class{<product>}{<type>}
\generic{t*}{types|... => <product>}
  \doc{returns product type specifying the cross product of \kode{types}.}
\generic{product-elts}{x|<product> => <seq>}
  \doc{types that product type matches.}
\end{defs}

\subsection{Classes}

Classes are types that specify an inheritance relationship and can
have associated structured data through properties.

\begin{defs}
\class{<class>}{<type>}
\generic{class-name}{x|<class> => (t?\ <sym>)}
  \doc{returns class name or false otherwise.}
\generic{class-parents}{x|<class> => <seq>}
  \doc{direct superclasses.}
\generic{class-ancestors}{x|<class> => <seq>}
  \doc{class precedence list including this class.  See
  Appendix~\ref{cpl} for details.}
\generic{class-direct-props}{x|<class> => <seq>}
  \doc{properties defined directly on this class.}
\generic{class-props}{x|<class> => <seq>}
  \doc{properties defined on this class or any superclass.}
\generic{class-children}{x|<class> => <seq>}
  \doc{direct subclasses.}
\form{DC}{(DC ,name (,@parents))}
  \doc{defines a class named \kode{,name} with direct parents \kode{,@parents}}
% \method{new}{type|<class> prop-inits|...}
%   \doc{default \kode{new} method creates uninitialized object \kode{x} of type
%   \kode{type} and then calls \kode{init} with \kode{x} and \kode{prop-inits}.}
\method{new}{type|<class> prop-inits|...}
  \doc{creates an instance of type \kode{type} and prop 
  initialized as specified by \kode{prop-inits}.  
  For example, \kode{(new <point> point-x 1 point-y 2)}
  creates a point with \kode{x=1} and \kode{y=2}.}
\end{defs}

\subsubsection{Properties}

Properties are named data associated with classes.  Their values are
accessed exclusively through generic functions, called getters and
setters.  Descriptions of properties are instances of \kode{<prop>}.
Property values can either be specified at creation time with keyword
arguments, by calling a property setter, or through a property
initialization function called lazily the first time a getter is called if
the property is otherwise uninitialized.  Property initialization
functions are called with a single argument, the object under construction.

\begin{defs}
\class{<prop>}{<any>}
\property{prop-owner}{x|<prop> => <any>}
  \doc{class on which property was directly defined.}
\property{prop-getter}{x|<prop> => <gen>}
  \doc{reader accessor generic.}
\property{prop-setter}{x|<prop> => <gen>}
  \doc{writer accessor generic.}
\property{prop-type}{x|<prop> => <type>}
  \doc{type constraining property value.}
\property{prop-init}{x|<prop> => <fun>}
  \doc{lazy initialization function.}
\generic{find-getter}{c|<class> getter|<gen> => <met>} % TODO: T?
  \doc{finds getter method defined on given class.}
\generic{find-setter}{c|<class> setter|<gen> => <met>} % TODO: T?
  \doc{finds setter method defined on given class.}
\property{prop-bound?}{x g|<gen> => <log>}
  \doc{returns true if property with getter \kode{g} is bound in
  instance \kode{x}.}
\method{add-prop}{owner getter|<gen> setter|<gen> \snl type|<type> init|<fun>} % TODO: T?
  \doc{where \kode{init} is a one parameter function that returns the initial
  value for the prop and gets called lazily with the new instance as
  the argument.}
\form{DP}{(DP ,name (,oname|,owner => ,type) [,@init])}
  \doc{add's an immutable property to \kode{,owner} with getter named
       \kode{,name},
       type \kode{,type}, and optionally initial 
  value \kode{,init}.  The initial value function is evaluated 
  lazily when prop's value is first requested.}
\form{DP!}{(DP! ,name (,oname|,owner => ,type) [,@init])}
  \doc{same as \kode{DP} but mutable 
       with setter named \kode{,name \#\# "-setter"}} 
\end{defs}

\section{Functions}

All operations in \goo\ are functions.

Functions accept zero or more arguments, and return one value. The
parameter list of the function describes the number and types of the
arguments that the function accepts, and the type of the value it returns.

There are two kinds of functions, methods and generic functions. Both
are invoked in the same way. The caller does not need to know whether
the function it is calling is a method or a generic function.

A method is the basic unit of executable code.  A method accepts a
number of arguments, creates local bindings for them, executes an
implicit body in the scope of these bindings, and then returns a
value.

A generic function contains a number of methods. When a generic
function is called, it compares the arguments it received with the
parameter lists of the methods it contains. It selects the most
appropriate method and invokes it on the arguments. This technique of
method dispatch is the basic mechanism of polymorphism in \goo.

All \goo\ functions are objects, instances of \kode{<fun>}. Generic
functions are instances of \kode{<gen>} and methods are instances of
\kode{<met>}.

\begin{defs}
\class{<fun>}{<any>}
\property{fun-name}{x|<fun> => (t?\ <sym>)}
  \doc{returns the name of function or false if unavailable.}
\property{fun-names}{x|<fun> => <lst>}
  \doc{returns the names of parameters of \kode{x} or \kode{()} if unavailable.}
\property{fun-specs}{x|<fun> => <lst>}
  \doc{returns the specializers of \kode{x}.}
\property{fun-nary?}{x|<fun> => <log>}
  \doc{returns true iff the function takes optional arguments.}
\property{fun-arity}{x|<fun> => <int>}
  \doc{returns \kode{x}'s number of required arguments.}
\property{fun-val}{x|<fun> => <type>}
  \doc{returns the return type of \kode{x}.}
% \generic{identity}{=> <fun>}
%   \doc{returns a function \kode{(fun (x) x)}.}
% \generic{compose}{x|<fun> y|<fun> => <fun>}
%   \doc{returns a function that composes function's \kode{x} and \kode{y}.}
% \generic{curry}{x|<fun> curried|... => <fun>}
%   \doc{$\equiv$ \kode{(fun (args|...) (app f (cat curried args)))}}
% \generic{rcurry}{x|<fun> curried|... => <fun>}
%   \doc{$\equiv$ \kode{(fun (args|...) (app f (cat args curried)))}}
% \generic{always}{x|<any> => <fun>}
%   \doc{creates a function that always returns \kode{x}.}
\form{FUN}{(FUN ,sig ,@body)}
  \doc{creates an anonymous method with signature \kode{,sig} and when called
       evaluates \kode{,@body} as \kode{(SEQ ,@body)} (cf. Scheme's
  \kode{LAMBDA}).  The following a few example functions and their application:

{\scriptsize
\begin{ex}
((fun (x) x) 1) ==> 1 \newline
((fun (x|<int> => <int>) x) 2) ==> 2 \newline
((fun (x|...) x) 1 2 3) ==> (1 2 3) \newline
((fun (x y|...) y) 1 2 3) ==> (2 3) \newline
((fun (x => (tup <int>))) (tup x)) 1) \inl $\equiv$ (tup 1)
\end{ex}
}
}
\form{\{ ... \}}{\{ [ ,@sig '$\backslash$' ] ,@body \}}
  \doc{\kode{FUN} abbreviation $\equiv$ \kode{(fun (,@sig) ,@body)}.  
  This is particularly useful for lightweight thunks
  (e.g., \kode{\{(+ x 1)\}} $\equiv$ \kode{(fun () (+ x 1))}).  N.B. this
  is an experimental syntax and might change in the future.}
\end{defs}

where

\begin{defs}
\syntax{,sig}{(,@params) | (,@params => ,ret)}
\syntax{,params}{(,@vars [(,name '...')])}
  \doc{where parameter lists can include an optional nary parameter which
  binds to all arguments beyond required arguments.}
\syntax{,ret}{,var | (TUP ,@ret-vars)}
  \doc{with \kode{TUP} turning into corresponding \kode{t*} 
  function return type.}
\syntax{,ret-var}{(,name ,type)}
\end{defs}
\begin{defs}
\form{LOC}{(LOC ((,name ,sig ,@fbody)) ,@body)}
  \doc{$\equiv$\begin{ex}
       (LET ((,name \#f) ...) \snl
       (SET ,name (fun ,sig ,@fbody)) ... \snl
       ,@body)
       \end{ex}
   \kode{LOC} introduces local functions that can recursively call each other
  (cf. Scheme's \kode{LETREC}).  
}
\form{DF}{(DF ,name ,sig ,@body)}
  \doc{$\equiv$ \kode{(DV ,name (FUN ,sig ,@body))} followed by
       setting the function's name.}
\generic{zipped}{x|<fun> => <fun>}
  \doc{$\equiv$ \kode{(fun (y|...) (app x y))}.  This is useful when
  mapping over zipped multiple sequences (e.g., \kode{(map (zipped +)
  (zip '(1 2) '(2 3)))}.}
\form{OP}{(OP ,op-arg ...)}
  \doc{creates an anonymous function with implicitly defined
  arguments, where \kode{,op-arg} is either an implicit required parameter
  ``\kode{\_}'' or rest parameter ``\kode{...}'' or an s-expression 
  potentially containing further op-args.  The required parameters are found
  ordered according to a depth-first walk of the op-args.  
  The following are typical examples:
\begin{ex}
((op \_) 1) ==> 1 \newline
((op 2) 1) ==> 2 \newline
((op + \_ 1) 3) ==> 4 \newline
((op lst ...\ 1) 3 2) ==> (3 2 1) \newline
((op tail (tail \_)) '(1 2 3)) ==> (3) 
\end{ex}
}
\generic{app}{f|<fun> args|... => <any>}
%  \doc{$\equiv$ \kode{(f [args 0] [args 1] ... [[args n]])}}
  \doc{calls \kode{f} with arguments 
       \kode{(cat (sub args 0 (- (len args) 2)) (elt args (- (len args) 1)))}.}
\end{defs}


\subsection{Generics}

Generic functions provide a form of polymorphism allowing many
implementation methods with varying parameter types, called
{\it specializers}.  Methods on a given generic function are chosen
according to applicability and are then ordered by specificity.
A method is applicable if each argument is an instance of each
corresponding specializer.
A method A is more specific than method B
if all of A's specializers are subtypes of B's.  
During method dispatch three cases can occur:
\begin{packeditemize}
\item if no methods are applicable then a no-applicable-method error
is signaled,
\item if methods are applicable but are not orderable then an
ambiguous-method error is signaled,
\item if methods are applicable and are orderable then the most
specific method is called and the next methods are established.
\end{packeditemize}

\begin{defs}
\class{<gen>}{<fun>}
\property{fun-mets}{x|<gen> => <lst>}
  \doc{returns \kode{x}'s methods.}
\generic{gen-add-met}{x|<gen> y|<met> => <gen>}
  \doc{adds method \kode{y} to generic \kode{x}.}
\generic{ord-app-mets}{x|<gen> args|... \snl => (tup ord|<lst> amb|<lst>)}
  \doc{returns both the list of sorted applicable methods and any ambiguous
  methods when generic \kode{x} is called with arguments args.}
\form{DG}{(DG ,name ,sig)}
  \doc{defines a binding with name \kode{,name} bound to a generic with signature \kode{,sig}.}
\end{defs}

\subsection{Methods}

Methods are \goo's code objects.  Methods can optionally be added to
generics. 

\begin{defs}
\class{<met>}{<fun>}
\generic{met-app?}{x|<met> args|<lst> => <log>}
  \doc{determines whether \kode{x} is applicable when called with \kode{args}.}
\form{DM}{(DM ,name ,sig ,@body)}
  \doc{first ensures that a generic exists named ,name and with a minimally
  congruent to signature \kode{,sig} and then adds  a method with signature
  \kode{,sig} and body \kode{,@body} (cf., Dylan's \kode{DEFINE METHOD}).}
\form{SUP}{(SUP ,@args)}
  \doc{calls next most applicable method.  N.B., all
  arguments must be supplied.}
\formcont{(APP-SUP ,@args)}
  \doc{applies next most applicable method.  N.B., all
  arguments must be supplied.}
\end{defs}

\section{Macros}

Macros provide a facility for extending the base syntax of \goo.  The
design is based on quasiquote code templates and a simple list pattern
matching facility.  Macros are currently unhygienic, and users are
required to use \kode{gensym} to avoid name collisions.

\begin{defs}
\form{QUASIQUOTE}{(QUASIQUOTE ,@qq-forms)}
  \doc{\kode{QUOTE} with selective evaluation using \kode{UNQUOTE} and
  \kode{SPLICING-UNQUOTE} (cf. Lisp and Scheme's \kode{QUASIQUOTE}),
  abbreviated ``\kode{`}''.}
\form{UNQUOTE}{(UNQUOTE ,form)}
  \doc{evaluates \kode{,form} in the midst of a \kode{QUASIQUOTE}
  expression, abbreviated ``\kode{,}''.}
\form{SPLICING-UNQUOTE}{(SPLICING-UNQUOTE ,form)}
  \doc{evaluates \kode{,form} in the midst of a \kode{QUASIQUOTE}
       expression and splices it in, abbreviated ``\kode{,@}''.}
% \form{MIF}{(MIF (,pat ,val) ,then [ ,else ])}
%   \doc{is the ``matching if'', evaluating \kode{,then} with pattern 
%     variables bound to matched 
%     parts of value if matching succeeds and otherwise evaluates
%     \kode{,else}.  The pattern is much the same as \kode{QUASIQUOTE} 
%     and can contain either \kode{UNQUOTE}'d variables
%     or \kode{UNQUOTE-SPLICING} variables.  For example,
% \begin{ex}
% (MIF ((,a ,b) '(1 2)) (lst a b)) $\rightarrow$ (1 2) \newline
% (MIF ((,a ,@b) '(1 2)) (lst a b)) $\rightarrow$ (1 (2))
% \end{ex}}
\form{MATCH}{(MATCH ,exp (,pat ,val) ...)}
  \doc{evaluates \kode{,val} corresponding to first \kode{,pat}
  matching \kode{,exp}.  The pattern is much the same as \kode{QUASIQUOTE} 
  and can contain either \kode{UNQUOTE}'d variables
  or \kode{UNQUOTE-SPLICING} variables.  For example,
\begin{ex}
(MATCH '(1 2) ((,a ,b) (lst a b))) $\rightarrow$ (1 2) \newline
(MATCH '(1 2) ((,a ,@b) (lst a b))) $\rightarrow$ (1 (2))
\end{ex}}
\form{DS}{(DS ,name (,pattern) ,@body)}
  \doc{defines a macro matching pattern ,pattern and expanding according to
  \kode{,@body}. The pattern matching occurs as in \kode{MIF} and
  makes available pattern variables during the evaluation 
  of \kode{(SEQ ,@body)}.  For example,
\begin{ex}
(DS unless (,test ,@body)\snl 
  `(if (not ,test) (seq ,@body)))
\end{ex}
  defines the \kode{when} macro in \goo.}
\end{defs}
where

\begin{defs}
\syntax{pattern}{(,@qq-forms)}
\end{defs}

\begin{defs}
\form{CT}{(CT ,@body)}
  \doc{evaluates \kode{(SEQ ,@body)} at compile-time allowing a user to make
  available computations for the purpose of macro-expansion.}
\form{CT-ALSO}{(CT-ALSO ,@body)}
  \doc{equivalent to \kode{CT}, but also includes a copy of
  \kode{,@body} in compiled
  images.  Similar to \kode{(eval-when (:compile-toplevel :execute) ...)}
  in Common LISP.  The return value of \kode{CT-ALSO} is undefined.}
\form{MACRO-EXPAND}{(MACRO-EXPAND ,form)}
  \doc{recursively expands macros in expression \kode{,form}.}
\end{defs}

\section{Scalars}

\goo\ provide a rich set of simple objects.

\subsection{Any}

All objects are derived from \kode{<any>}.

\begin{defs}
\class{<any>}{<any>}
\generic{as}{x|<any> y|<any> => <any>}
  \doc{coerces y to an instance of x.}
% \generic{parents-of}{x|<any> => <lst>}
\generic{class-of}{x|<any> => <class>}
  \doc{returns concrete class of \kode{x}.}
\generic{==}{x|<any> y|<any> => <log>}
  \doc{returns true iff \kode{x} and \kode{y} are computationally
  equivalent.}
\generic{=}{x|<any> y|<any> => <log>}
  \doc{returns true iff \kode{x} and \kode{y} are equal, where
  equality is user defined and defaults to \kode{==}.}
\generic{\~{}=}{x|<any> y|<any> => <log>}
  \doc{$\equiv$ \kode{(not (= x y))}.}
\generic{\~{}==}{x|<any> y|<any> => <log>}
  \doc{$\equiv$ \kode{(not (== x y))}.}
\generic{to-str}{x|<any> => <str>}
  \doc{returns string representation of object.}
\end{defs}

\subsection{Booleans}

In \goo, for convenience sake, true is often represented by anything
that is not false, but \kode{\#t} is reserved for the canonical true
value.  False is often used to represent null.

\begin{defs}
\class{<log>}{<any>}
\instance{\#f}{<log>}
\instance{\#t}{<log>}
\method{not}{x|<any> => <log>}
  \doc{$\equiv$ \kode{(if x \#f x)}}
\end{defs}

\subsection{Magnitudes}

Magnitudes are totally orderable objects.  Users are only required to
implement \kode{<} and \kode{=}.

\begin{defs}
\class{<mag>}{<any>}
\generic{<}{x|<mag> y|<mag> => <log>}
  \doc{returns iff \kode{x} is less than \kode{y}.}
\generic{>}{x|<mag> y|<mag> => <log>}
  \doc{$\equiv$ \kode{(not (or (< x y) (= x y)))}.}
\generic{<=}{x|<mag> y|<mag> => <log>}
  \doc{$\equiv$ \kode{(or (< x y) (= x y))}.}
\generic{>=}{x|<mag> y|<mag> => <log>}
  \doc{$\equiv$ \kode{(not (< x y))}.}
\generic{min}{x|<mag> y|<mag> => <mag>}
  \doc{returns the smallest of \kode{x} and \kode{y}.} 
\generic{max}{x|<mag> y|<mag> => <mag>}
  \doc{returns the largest of \kode{x} and \kode{y}.} 
\end{defs}

% \subsection{Null}
% 
% \begin{defs}
% \instance{nul}{<any>}
% \function{nul?}{x => <log>}
% \end{defs}

\subsection{Locatives}

Locatives are word aligned pointers to memory.  They are meant to be
used to represent pointers to foreign data and not to point to
interior \goo\ object data.

\begin{defs}
\class{<loc>}{<mag>}
\generic{loc-val}{x|<loc> => <any>}
  \doc{returns the object pointed to by \kode{x}.}
% \generic{loc-val-setter}{address|<loc> x|<loc>}
%   \doc{returns the object pointed to by \kode{x}.}
\generic{address-of}{x|<any> => <loc>}
  \doc{returns address of particular object.}
\end{defs}

\subsection{Characters}

\goo\ currently supports 8 bit ASCII characters.

\begin{defs}
\class{<chr>}{<mag>}
\generic{alpha?}{x|<chr> => <log>}
  \doc{returns true iff \kode{x} is one of the ASCII upper or
  lowercase characters.}
\generic{digit?}{x|<chr> => <log>}
  \doc{returns true iff \kode{x} is one of the ten ASCII numeric characters.}
\generic{lower?}{x|<chr> => <log>}
  \doc{returns true iff \kode{x} is one of the ASCII lowercase characters.}
\generic{upper?}{x|<chr> => <log>}
  \doc{returns true iff \kode{x} is one of the ASCII uppercase characters.}
\generic{to-digit}{x|<chr> => <int>}
  \doc{converts ascii representation of digit to an integer one.}
\generic{to-lower}{x|<chr> => <chr>}
  \doc{returns lowercase version of uppercase alphabetic 
  characters otherwise returns \kode{x}.}
\generic{to-upper}{x|<chr> => <chr>}
  \doc{returns uppercase version of lowercase alphabetic 
  characters otherwise returns \kode{x}.}
\end{defs}

\subsection{Numbers} 

\begin{defs}
\class{<num>}{<mag>}
\generic{+}{x|<num> y|<num> => <num>}
  \doc{returns the sum of its arguments.}
% \generic{1+}{x|<num> => <num>}
%   \doc{$\equiv$ \kode{(+ x 1)}.}
\generic{-}{x|<num> y|<num> => <num>}
  \doc{returns the difference of its arguments.}
% \generic{1-}{x|<num> => <num>}
%   \doc{$\equiv$ \kode{(- x 1)}.}
\generic{*}{x|<num> y|<num> => <num>}
  \doc{returns the product of its arguments.}
\generic{/}{x|<num> y|<num> => <num>}
  \doc{returns the quotient of its arguments.  
  %  Division by zero raises a divide by zero condition.
  }
% \generic{floor/}{x|<num> y|<num> \snl => (tup <int> rem|<num>)}
%   \doc{returns the floor of the quotient of two numbers and the
%   remainder, where floor truncates a number towards negative infinity.}
% \generic{ceiling/}{x|<num> y|<num> \snl => (tup <int> rem|<num>)}
%   \doc{returns the ceiling of the quotient of two numbers and the 
%   remainder, where ceiling truncates a number towards positive infinity.}
% \generic{round/}{x|<num> y|<num> \snl =>  (tup <int> rem|<num>)}
%   \doc{returns the nearest integer quotient of two numbers and the remainder.}
% \generic{truncate/}{x|<num> y|<num> \snl => (tup <int> rem|<num>)}
%   \doc{returns the towards zero truncated quotient of two numbers and the
%   remainder.}
\generic{round}{x|<num> => <int>}
  \doc{returns closest integer to \kode{x}.  If \kode{x} is exactly between
  two integers then the implementation is free to return either integer. }
\generic{round-to}{x|<num> n|<int> => <flo>}
  \doc{returns \kode{x} to closest flo \kode{n} digits precision.}
\generic{floor}{x|<num> => (tup <int> rem|<num>)}
  \doc{returns an integer by truncating \kode{x} towards negative infinity.}
\generic{ceil}{x|<num> => (tup <int> rem|<num>)}
  \doc{returns an integer by truncating \kode{x} towards positive infinity.}
\generic{trunc}{x|<num> => (tup <int> rem|<num>)}
  \doc{returns an integer by truncating \kode{x} towards zero.}
\generic{mod}{x|<num> y|<num> => <num>}
  \doc{returns the remainder after taking the floor of the quotient of
    \kode{x} and \kode{y}.}
\generic{div}{x|<num> y|<num> => <num>}
  \doc{returns the trunc of the quotient of \kode{x} and \kode{y}.}
\generic{rem}{x|<num> y|<num> => <num>}
  \doc{returns remainder after dividing \kode{x} by \kode{y}.}
\generic{pow}{x|<num> e|<num> => <num>}
  \doc{returns \kode{x} raised to the \kode{e} power.} 
\generic{exp}{x|<num> => <num>}
  \doc{$\equiv$ \kode{(pow \$e x)}}
\generic{sqrt}{x|<num> => <num>}
  \doc{returns the square root of \kode{x}.} 
\generic{pos?}{x|<num> => <log>}
  \doc{$\equiv$ \kode{(> x 0)}}
\generic{zero?}{x|<num> => <log>}
  \doc{$\equiv$ \kode{(= x 0)}}
\generic{neg?}{x|<num> => <log>}
  \doc{$\equiv$ \kode{(< x 0)}}
\generic{neg}{x|<num> => <num>}
  \doc{$\equiv$ \kode{(- 0 x)}}
\generic{abs}{x|<num> => <num>}
  \doc{$\equiv$ \kode{(if (neg? x) (neg x) x)}}
\generic{num-to-str-base}{x|<num> b|<int> => <str>}
  \doc{returns string representation of \kode{x} in base \kode{b}.}
\generic{num-to-str}{x|<num> => <str>}
  \doc{$equiv$ \kode{(num-to-str-base x 10)}}
\generic{str-to-num}{x|<str> => <num>}
  \doc{returns closest number corresponding to string \kode{x}.}
\form{INCF}{(INCF ,name)}
  \doc{$\equiv$ \kode{(SET ,name (+ ,name 1))}}
\formcont{(INCF (,name ,@rest))}
  \doc{$\equiv$ \kode{(SET (,name ,@rest) (+ (,name ,@rest) 1))}}
\form{DECF}{(DECF ,name) }
  \doc{$\equiv$ \kode{(SET ,name (+ ,name 1))}}
\formcont{(DECF (,name ,@rest))}
  \doc{$\equiv$ \kode{(SET (,name ,@rest) (+ (,name ,@rest) 1))}}
\instance{\$e}{<flo>}
\instance{\$pi}{<flo>}
\generic{sqrt}{x|<num> => <num>}
\generic{log}{x|<num> => <num>}
\generic{logn}{x|<num> b|<num> => <num>}
\generic{sin}{x|<num> => <num>}
\generic{cos}{x|<num> => <num>}
\generic{tan}{x|<num> => <num>}
\generic{asin}{x|<num> => <num>}
\generic{acos}{x|<num> => <num>}
\generic{atan}{x|<num> => <num>}
\generic{atan2}{y|<num> x|<num> => <num>}
\generic{sinh}{x|<num> => <num>}
\generic{cosh}{x|<num> => <num>}
\generic{tanh}{x|<num> => <num>}
\end{defs}

\subsubsection{Integers} 

\goo\ currently represents integers as 30 bit fixnums.

\begin{defs}
\class{<int>}{<num>}
\generic{|}{x|<int> y|<int> => <int>}
  \doc{returns the logical inclusive or of its arguments.}
\generic{\&}{x|<int> y|<int> => <int>}
  \doc{returns the logical and or of its arguments.}
\generic{\^{}}{(x|<int> y|<int> => <int>)}
  \doc{$\equiv$ \kode{(| (\& x (\~{} y)) (\& (\~{} x) y))}}
\generic{\~{}}{x|<int> => <int>}
  \doc{returns the logical complement of its argument.}
\generic{bit?}{x|<int> n|<int> => <log>}
  \doc{returns true iff \kode{n}th bit is 1.}
\generic{even?}{x|<int> => <log>}
\generic{odd?}{x|<int> => <log>}
\generic{gcd}{x|<int> y|<int> => <int>}
  \doc{greatest common denominator.}
\generic{lcm}{x|<int> y|<int> => <int>}
  \doc{least common multiple.}
\generic{<<}{x|<int> n|<int> => <int>}
  \doc{returns \kode{n} bit shift left of \kode{x}.}
\generic{>>}{x|<int> n|<int> => <int>}
  \doc{returns signed \kode{n} bit shift right of \kode{x}.}
\generic{>>>}{x|<int> n|<int> => <int>}
  \doc{returns unsigned \kode{n} bit shift right of \kode{x}.}
\end{defs}

\subsubsection{Floats}

\goo\ currently only supports single-precision floating point numbers.

\begin{defs}
\class{<flo>}{<num>}
\generic{flo-bits}{x|<flo> => <int>}
  \doc{returns bit representation as an integer.}
\end{defs}

\section{Collections}

Collections are aggregate data structures mapping keys to values.
Collections can be almost entirely defined in terms of an enumeration class.

% Collections can be almost entirely defined in terms of an iteration protocol.
% The protocol is in turned defined in terms of an iteration state.
% 
% In defining a new collection class, a user must implemented at minimum
% the seven methods comprising the iteration protocol: \kode{1st-state},
% \kode{fin-state}, \kode{nxt-state}, \kode{now-elt},
% \kode{now-elt-setter}, \kode{now-key}, \kode{dup-state}.  For
% efficiency, users might choose to override more methods such as
% \kode{len}, \kode{elt}, \kode{elt-setter}, etc.

\begin{defs}
\class{<col>}{<any>}
\class{<col.>}{<col>}
  \doc{immutable collections.}
\generic{fab}{t|(t< <col>) n|<int> => <col>}
  \doc{returns a new instance of collection type \kode{t} of len
  \kode{n}.}
\generic{col}{t|(t< <col>) key-vals|... => <col>}
  \doc{returns new collection of type \kode{t} with initial key values
       \kode{key-vals}.}
\generic{fabs}{t|(t< <col>) elts|... => <col>}
  \doc{returns new collection of type \kode{t} with initial values
       \kode{elts} and keys \kode{(below (len elts))}.}
\generic{len}{x|<col> => <int>}
  \doc{returns number of collection elements.}
\generic{col-res-type}{x|<col> => <type>}
  \doc{appropriate instantiable type for creating collection results,
       where the default is \kode{(class-of x)}.}
\generic{nul?}{x|<col> => <log>}
  \doc{$\equiv$ \kode{(= (len x) 0)}}
\generic{nul}{x|(t< <col>) => <col>}
  \doc{returns collection specific unique empty value.}
% \generic{default}{x|<col> => <any>}
%   \doc{return default element value.}
\generic{key-test}{x|<col> => test|<fun>}
  \doc{returns collection's key equality function.}
\methodcont{x|<col> => (t= ==)}
  \doc{default key-test is identity function.}
\generic{key-type}{x|<col> => <type>}
  \doc{returns collection \kode{x}'s key type.}
\generic{elt-type}{x|<col> => <type>}
  \doc{returns collection \kode{x}'s element type.}
\generic{elt}{x|<col> k|<any> => <any>}
  \doc{returns collection \kode{x}'s element associated with key \kode{k}.}
\form{'[' ... ']'}{'[' ,x ,k ']'}
  \doc{$\equiv$ \kode{(elt ,x ,k)}} 
\generic{elt-or}{x|<col> k d => <any>}
  \doc{returns collection \kode{x}'s element associated with key
  \kode{k} or default \kode{d} if it doesn't exist.}
\generic{mem?}{x|<col> y|<any> => <log>}
  \doc{returns true iff \kode{y} is an element of \kode{x}.}
\generic{add}{x|<col> y|<any> => <col>}
  \doc{returns collection with \kode{y} added to \kode{x}.}
\generic{elts}{x|<col> keys|<seq> => <col>}
  \doc{subset of elements of \kode{x} corresponding to keys \kode{keys}.}
% \generic{elts-setter}{dst|<col> src|<col> keys|<col>}
%   \doc{replaces elements in \kode{dst} with ...}
\generic{dup}{x|<col> => <col>}
  \doc{returns shallow copy of \kode{x}.}
\generic{keys}{x|<col> => <seq>}
  \doc{returns \kode{x}'s keys.}
\generic{items}{x|<col> => <seq>}
  \doc{returns a sequence of \kode{x}'s key/val tuples.}
\generic{del}{x|<col> key|<any> => <col>}
  \doc{returns copy of \kode{x}'s without element corresponding to \kode{key}.}
\generic{zap}{x|<col> => <col>}
  \doc{returns empty copy of \kode{x}.}
\generic{fill}{x|<col> y|<any> => <col>}
  \doc{returns copy of \kode{x} with all values being \kode{y}.}
\generic{any?}{f|<fun> x|<col> => <log>}
  \doc{returns true iff any of \kode{x}'s element satisfies 
       given predicate \kode{f}.}
\generic{find}{f|<fun> x|<col> => <any>}
  \doc{returns key associated with first of \kode{x}'s values to
       satisfy predicate \kode{f}.}
\generic{find-or}{f|<fun> x|<col> default => <any>}
  \doc{returns key associated with first of \kode{x}'s values to
       satisfy predicate \kode{f} or \kode{default} if not found.}
\generic{all?}{f|<fun> x|<col> => <log>}
  \doc{returns true iff all of \kode{x}'s elements satisfies 
       given predicate \kode{f}.}
\generic{fold}{f|<fun> init|<any> x|<col> \snl => <col>}
  \doc{$\equiv$ \kode{(f (f ... (f init (elt x 0)) (elt x (- n 2)))
                         (elt x (- n 1)))}}
\generic{fold+}{f|<fun> x|<col> => <any>}
  \doc{$\equiv$ \kode{(f (f ... (f (elt x 0) (elt x 1)) (elt x (- n 2)))
  (elt x (- n 1)))}}
% TODO pass key if fun accepts >1 one arg
\generic{do}{f|<fun> x|<col>}
  \doc{iterates function \kode{f} over values of \kode{x} for side-effect.}
\generic{map}{f|<fun> x|<col> => <col>}
  \doc{iterates function \kode{f} over values of given 
       collections and collects the results.}
% \generic{do-keyed}{f|<fun> x|<col>}
%   \doc{iterates function \kode{f} over keys and values of \kode{x} 
%        for side-effect.}
% \generic{map-keyed}{f|<fun> x|<col> => <col>}
%   \doc{iterates function \kode{f} over keys and values of \kode{x}
%        and collects the results.}
\end{defs}

\subsection{Mutable Collections}

Mutation is seen as a necessary evil and is supported but segregated
in hopes of trying to isolate and optimize the nondestructive cases.
Mutation includes the notion of modifying values and adding/removing
keys.  The hope is that functional (nondestructive) programs will be
both more succinct, understandable, and efficient than equivalent
destructive programs.  Only core collection operators are given
destructive versions.  All others can be built out of nondestructive
operators followed by \kode{into}~\footnote{When optimization is in
place, the \kode{!} suffixed functions will be deprecated.}.

\begin{defs}
\class{<col!>}{<any>}
\generic{elt-setter}{v|<any> x|<col!> k|<any>}
  \doc{sets collection \kode{x}'s element associated with key
       \kode{k} to \kode{v}.}
\generic{into}{x|<col!> y|<col> => <col!>}
  \doc{replaces elements of \kode{x} with elements of \kode{y}.}
\generic{elt!}{x|<col!> y|<any default|<fun> => <any>}
  \doc{$\equiv$ \kode{(or (elt-or c k \#f) (set (elt c k) (default)))} but
  uses unique default key for \kode{elt-or} instead of false.}
\generic{fill!}{x|<col!> y|<any> => <col!>}
  \doc{fills \kode{x} with \kode{y}'s.}
\generic{add!}{x|<seq!> y|<any => <seq!>}
  \doc{adds \kode{y} to \kode{x}.}
\generic{del!}{x|<col!> key|<any> => <col!>}
  \doc{removes \kode{key} from \kode{x}.}
\generic{zap!}{x|<col!> => <col!>}
  \doc{removes all of \kode{x}'s elements.}
\end{defs} 

\subsection{Enumerators}

Enumerations are the foundation of collections and are designed to
provide the convenience of Lisp's list interface (e.g., \kode{null},
\kode{car}, \kode{cdr}) for all collections.
In defining a new collection class, a user must implement at minimum
an enumerator class and the enumeration protocol: \kode{enum},
\kode{fin?}, \kode{nxt}, and \kode{now}.
For efficiency, users might choose to override more methods such as
\kode{len}, \kode{elt}, \kode{elt-setter}, etc.
Enumeration behavior is undefined if an enumerator is modified during
enumeration.

\begin{defs}
\class{<enum>}{<any>}
\generic{enum}{x|<any> => <enum>}
  \doc{returns initial enum for iterating over \kode{x}.}
\generic{fin?}{x|<enum> => <log>}
  \doc{returns true iff no more elements exist from given enum \kode{x}.}
\generic{nxt}{x|<enum> => <enum>}
  \doc{returns enum pointing to next element in enum \kode{x}.}
\generic{now}{x|<enum> => <any>}
  \doc{returns current element given enum \kode{x}.}
\generic{now-setter}{v x|<enum>}
  \doc{sets current element given enum \kode{x} to \kode{v}.}
\generic{now-key}{x|<enum> => <any>}
  \doc{returns current key given enum \kode{x}.}
\method{enum}{x|<enum> => <enum>}
  \doc{returns x allowing enumerators to be enumerated.}
% \generic{1st-state}{x|<col> => <any>}
%   \doc{returns initial iteration state.}
% \generic{fin-state?}{x|<col> state|<any> => <log>}
%   \doc{returns true iff no more elements exist from given state.}
% \generic{nxt-state}{x|<col> state|<any> => <any>}
%   \doc{returns next state from collection and current state.}
% \generic{now-elt}{x|<col> state|<any> => <any>}
%   \doc{returns current element given collection and state.}
% \generic{now-elt-setter}{v|<any> x|<col> state|<any>}
%   \doc{sets current element of \kode{x} to \kode{v} given \kode{state}.}
% \generic{now-key}{x|<col> state|<any> => <any>}
%   \doc{returns current key of \kode{x} given \kode{state}.}
% \generic{dup-state}{x|<col> state|<any> => <any>}
%   \doc{returns copy of \kode{state} given \kode{x}.}
\form{FOR}{(FOR (,for-clause ...) ,@body)}
  \doc{parallel iteration over collections using enumerations.}
\end{defs}
where

\begin{defs}
\syntax{,for-clause}{(,var ,col) | ((tup ,keyvar ,var) ,col)}
  \doc{specifies one parallel iteration over a collection \kode{,col}
  binding successive values to \kode{,var} and optionally keys to
  \kode{,keyvar}.}
\end{defs}

\subsection{Packers}

Packers are the complement of enumerators and are the 
imperative version of \kode{fold}.  The default packer returns a
list of all accumulated values:
\begin{ex}
(packing (for ((e '(1 2 3 4 5))) 
           (when (odd? e) (pack e)))) \snl ==> (1 3 5)
\end{ex}
They can also be used for summing values etc:
\begin{ex}
(packing-in (x|<int>) 
  (for ((e '(1 2 3 4 5)))
    (when (odd? e) (pack-in x e)))
  (packed x)) \snl ==> 9
\end{ex}

\begin{defs}
\class{<packer>}{<any>}
\generic{packer-add}{p|<packer> x => <packer>}
  \doc{returns a copy packer \kode{p} augmented with element \kode{x}.}
\generic{packer-res}{p|<packer> => <any>}
  \doc{returns result of packings over \kode{p}.}
\generic{packer}{init add|<fun> res|<fun>}
  \doc{returns a simple packer that starts its value out
  with \kode{init}, is augmented with \kode{add}, and whose final value
  is computed with \kode{res}.}
\generic{packer-fab}{t|<type> => <packer>}
  \doc{returns a new type \kode{t} specific packer.}
\method{packer-fab}{t|(t< <seq>) => <packer>}
  \doc{$\equiv$ \kode{(packer '() pair (op as t (rev!\ \_)))}}
\method{packer-fab}{t|(t= <int>) => <packer>}
  \doc{$\equiv$ \kode{(packer 0 + (op \_))}}
\form{PACKING-WITH}{(PACKING-WITH ((,var ,pack) ...) ,@body)}
  \doc{mechanism for packing objects using given packer into \kode{,var}.}
\form{PACKING-IN}{(PACKING-IN (,name '|' ,type ...) ,@body)}
  \doc{$\equiv$ \kode{(PACKING-WITH (,name (packer-fab ,type)) ,@body)}.}
\formcont{(PACKING-IN (,name) ,@body)}
  \doc{$\equiv$ \kode{(PACKING-IN (,name '|' <lst>) ,@body)}.}
\form{PACKING}{(PACKING ,@body)}
  \doc{$\equiv$ \kode{(PACKING-IN (packer-) ,@body (packed packer-))}.}
\form{PACK-IN}{(PACK-IN ,pack ,x)}
  \doc{folds \kode{,x} into packer in \kode{,pack}.}
\form{PACK}{(PACK ,x)}
  \doc{$\equiv$ \kode{(PACK packer- ,name)}.}
\form{PACKED}{(PACKED ,name)}
  \doc{$\equiv$ \kode{(packer-res ,name)}.}
\end{defs}

\subsection{Maps}

Maps represent collections with explicit keys.  

\begin{defs}
\class{<map>}{<col>}
\class{<tab>}{<map> <col!>}
  \doc{Tables are near constant-time aggregate data structures.  
Users can define their own tables by subclassing and overriding the
\kode{key-test} and \kode{tab-hash} methods.}
\propertyinit{tab-growth-factor}{x|<tab> => <flo>}{2.0}
  \doc{factor by which to grow capacity.}
\propertyinit{tab-growth-threshold}{x|<tab> => <flo>}{0.8}
  \doc{when to grow based on proportion of total table capacity.}
\propertyinit{tab-shrink-threshold}{x|<tab> => <flo>}{0.5}
  \doc{when to shrink based on proportion of total table capacity.}
% TODO should this go away and be replaced with tab-hash and tab-test?
\generic{tab-hash}{x|<tab> => <fun>}
  \doc{returns hash function.}
% \generic{table-protocol}{x|<tab> \snl => (tup test|<fun> hash|<fun>)}
%   \doc{returns key equality and hash functions.}
% \instance{\$permanent-hash-state}{<any>}
%   \doc{GC specific.}
% \generic{tab-gc-state}{x|<tab> => <any>}
%   \doc{GC specific.}
% \generic{id-hash}{x|<tab> => (tup hash|<any> gc-state|<any>)}
%   \doc{hash function based on pointer.  Susceptible to rehash if
%        objects are moved.  The \kode{gc-state} reflects movement.}
\generic{id-hash}{x|<tab> => <int>}
  \doc{hash function based on identity.}
%TODO: CALL THIS SYM-TAB?
% \class{<str-tab>}{<tab>}
%   \doc{case insensitive string hash table used for symbol tables.}
\end{defs}

\subsection{Sequences}

Sequences are collections with nonnegative integer keys.

\begin{defs}
\class{<seq>}{<col>}
\class{<seq.>}{<seq> <col.>}
  \doc{immutable sequence.}
\generic{1st}{x|<seq> => <any>}
  \doc{$\equiv$ \kode{(elt x 0)}}
\generic{2nd}{x|<seq> => <any>}
  \doc{$\equiv$ \kode{(elt x 1)}}
\generic{3rd}{x|<seq> => <any>}
  \doc{$\equiv$ \kode{(elt x 2)}}
\generic{last}{x|<seq> => <any>}
  \doc{$\equiv$ \kode{(elt x (- (len x) 1))}}
\generic{pos}{x|<seq> v|<any> => (t?\ <int>)}
  \doc{finds position of \kode{v} in \kode{x} else returns false.}
\generic{finds}{x|<seq> y|<seq> => (t?\ <int>)}
  \doc{finds position of \kode{y} in \kode{x} else returns false.}
\method{add}{x|<seq> y|<any> => <seq>}
  \doc{returns sequence with \kode{y} added to the end of \kode{x}.}
\generic{push}{x|<seq> y|<any> => <seq>}
  \doc{returns sequence with \kode{y} added to \kode{x}.}
\generic{pop}{x|<seq> => (tup <any> <seq>)}
  \doc{returns last pushed element of \kode{x} and new sequence with that
       element removed from \kode{x}. }
\generic{rev}{x|<seq> => <seq>}
  \doc{returns reversed sequence.}
\generic{cat}{x|<seq> more|... => <seq>}
  \doc{returns concatenated sequences.}
\generic{sub}{x|<seq> from|<int> below|<int> => <seq>}
  \doc{subsequence of \kode{x} between \kode{from} and \kode{below}.}
\form{'[' ... ']'}{'[' ,x ,from ,below ']'}
  \doc{$\equiv$ \kode{(sub ,x ,from ,below)}} 
\generic{sub*}{x|<seq> from|<int> => <seq>}
  \doc{$\equiv$ \kode{(sub x from (len x))}}
\form{'[' ... ']'}{'[' ,x ,from * ']'}
  \doc{$\equiv$ \kode{(sub* ,x ,from)}} 
\generic{ins}{x|<seq> val i|<int> => <seq>}
  \doc{returns copy of \kode{x}'s with \kode{val} inserted before \kode{i}.}
\generic{del-dups}{x|<seq> => <seq>}
  \doc{returns sequence with all duplicates removed.}
\generic{del-vals}{s|<seq> val => <seq>}
  \doc{returns sequence with all copies of \kode{val} removed.}
\generic{sort-by}{s|<seq> f|<fun> => <seq>}
  \doc{returns a sorted copy of \kode{s} using \kode{f} as a comparator.}
\generic{sort}{s|<seq> => <seq>}
  \doc{$\equiv$ \kode{(sort-by s <)}}
% \generic{reject}{f|<fun> x|<seq>  => <seq>}
%   \doc{returns sequence without elements corresponding to
%   non-false results when calling predicate \kode{f}.}
\generic{pick}{f|<fun> x|<seq> => <seq>}
  \doc{returns new sequence with elements corresponding to 
  non-false results when calling predicate \kode{f}.}
\generic{prefix?}{x|<seq> prefix|<seq> => <log>}
  \doc{returns true iff sequence \kode{x} starts with sequence \kode{prefix}.}
\generic{suffix?}{x|<seq> suffix|<seq> => <log>}
  \doc{returns true iff sequence \kode{x} ends with sequence \kode{suffix}.}
\generic{repeat}{x|<seq> n|<int> => <seq>}
  \doc{returns sequence with \kode{n} concatenated copies of \kode{x}.}
\generic{split}{x|<seq> sep => <seq>}
  \doc{returns sequence of subsequences of \kode{x} separated by \kode{sep}.}
\generic{join}{xs|<seq> sep|<seq> => <seq>}
  \doc{returns sequence composed of sequences in \kode{xs} joined with
  \kode{sep}.}
\end{defs}

\subsubsection{Mutable Sequences}


\begin{defs}
\class{<seq!>}{<seq> <col!>}
\generic{rev!}{x|<seq!> => <seq!>}
  \doc{returns destructively reversed sequence.}
\generic{cat!}{x|<seq!> more|... => <seq!>}
  \doc{returns destructively concatenated sequences.}
\generic{add!}{x|<seq!> y|<any> => <seq!>}
  \doc{returns collection with \kode{y} added to the end of \kode{x}.}
\generic{push!}{x|<seq!> y|<any> => <seq!>}
  \doc{returns collection with \kode{y} added to the front of \kode{x}.}
\generic{pop!}{x|<seq!> => (tup val|<any> <seq!>)}
  \doc{pops element from front of sequence.}
\form{PUSHF}{(PUSHF ,place ,val)}
  \doc{pushes \kode{,val} onto the sequence stored in \kode{,place},
  updates \kode{,place} to contain the new sequence, and returns the new
  sequence.}
\form{POPF}{(POPF ,place)}
  \doc{pops a value from the sequence stored in 
  \kode{,place}, replaces
  the sequence with an updated sequence, and returns the value.}
\generic{ins!}{x|<seq!> v|<any> i|<int> => <seq!>}
  \doc{inserts \kode{v} before \kode{i} in \kode{x}.}
\generic{sub-setter}{dst|<seq!> src|<seq> from|<int> below|<int>}
  \doc{replaces subsequence in range between \kode{from} and
  \kode{below} of \kode{dst} with
  contents of \kode{src}.  Provides insertion, deletion, and
  replacement operations rolled into one. }
\generic{sub*-setter}{dst|<seq!> src|<seq> from|<int>}
  \doc{$\equiv$ \kode{(sub-setter dst src from (len dst))}}
\generic{del-vals!}{x|<seq!> v|<any>  => <seq!>}
  \doc{removes all \kode{v}'s from \kode{x}.}
\generic{del-dups!}{x|<seq!> => <seq!>}
  \doc{removes all duplicates from \kode{x}.}
\generic{sort-by!}{s|<seq> f|<fun> => <seq>}
  \doc{destructively sorts \kode{s} using \kode{f} as a comparator.}
\generic{sort!}{s|<seq> => <seq>}
  \doc{$\equiv$ \kode{(sort-by! s <)}}
\end{defs} 

\subsubsection{Lists}

Lists are always ``proper'' lists, that is, the tail of a list is always a
list.  Lists might be deprecated in future releases of \goo.

\begin{defs}
\class{<lst>}{<seq!>}
\alias{<list>}{<lst>} 
\property{head}{x|<lst> => <any>}
\propertyinit{tail}{x|<lst> => <lst>}{()}
\generic{lst}{elts|... => <lst>}
  \doc{returns list of arguments.}
\alias{list}{lst}
\generic{lst*}{elts|... => <lst>}
  \doc{returns list of arguments with last argument tacked onto end.}
\instance{nil}{<lst>}
  \doc{aka \kode{()}.}
\generic{pair}{x|<any> y|<lst> => <lst>}
  \doc{returns new list with \kode{x} as head and \kode{y} as tail.}
\end{defs}

\subsubsection{Zips}

A zip is a sequence of tuples of sucessive elements of sequences.  A
zip has the length of its shortest constituent sequence.

\begin{defs}
\class{<zip>}{<seq.>}
\generic{zip}{cs|(...\ <seq>) => <zip>}
  \doc{returns a zip over sequences \kode{cs}.}
\generic{unzip}{z|<zip> => <tup>}
  \doc{returns a tuple of \kode{z}'s constituent sequences.}
\end{defs}

\subsubsection{Flat Sequences}

Flats represents sequences with constant access time.  Flat enum provides
an enum implementation of all but \kode{now} and \kode{now-setter}.

\begin{defs}
\class{<flat>}{<seq>}
\class{<flat-enum>}{<enum>}
\class{<tup>}{<flat> <seq.>}
  \doc{Tuples are immutable flat sequences and represents multiple values in
  \goo.}
\generic{tup}{elts|... => <tup>}
  \doc{creates a tuple with elements being \kode{elts}.}
% \class{<opts>}{<flat>}
%   \doc{Optionals are used to hold n-ary arguments.  Optionals are immutable.}
% \class{<opts>}{<flat>}
%   \doc{Optionals are used to hold n-ary arguments.  Optionals are immutable.}
% \class{<vec>}{<flat> <seq.>}
%   \doc{Vectors are nonstretchy, mutable, one dimensional arrays of objects.}
% \generic{vec}{elts|... => <vec>}
%   \doc{returns new vector with elements \kode{elts}.}
\class{<vec>}{<flat> <seq!>}
  \doc{Stretchy vectors resize when needed.}
\generic{vec}{elts|... => <sec>}
  \doc{returns new vector with elements \kode{elts}.}
\end{defs}

\subsubsubsection{Strings}

\goo\ currently implements ASCII strings.

\begin{defs}
\class{<str>}{<flat> <mag> <seq.>}
\generic{str}{elts|... => <str>}
  \doc{returns new string with elements \kode{elts}.}
\generic{case-insensitive-string-hash}{x|<tab> => (tup hash|<any> gc-state|<any>)}
\generic{case-insensitive-string-equal}{x|<str> y|<str> => <log>}
\end{defs}

\subsection{Lazy Series'}

Represents an immutable sequence of numbers specified using a start number
\kode{from}, a step amount \kode{by} % defaulting to \kode{1}
, and an inclusive bound \kode{to}.
% which is either \kode{to}, \kode{below}, or \kode{above}.

\begin{defs}
\class{<range>}{<seq.>}
\generic{range-by}{from|<num> test|<fun> lim|<num> by|<fun>\snl => <range>}
  \doc{returns a range starting \kode{from}, updated with \kode{by},
  and continuing until \kode{(test x lim)} is false.}
\generic{range}{from|<num> test|<fun> lim|<fun> => <range>}
  \doc{$\equiv$ \kode{(range-by from test lim (op + \_ 1))}}
\generic{from}{from|<num> => <range>}
  \doc{$\equiv$ \kode{(range from (always \#t) 0)}}
\generic{below}{lim|<num> => <range>}
  \doc{$\equiv$ \kode{(range 0 < lim)}}
\class{<step>}{<seq.>}
  \doc{Steps represent step functions.}
\generic{first-then}{first|<fun> then|<fun> => <step>}
  \doc{returns a new step object, calling thunks \kode{first} to retrieve
initial value and \kode{then} to retrieve subsequent values.}
\generic{each}{f|<fun> => <each>}
  \doc{returns a new each object, calling \kode{f} thunk to retrieve
  each value.}
\class{<cycle>}{<seq.>}
  \doc{Cycles provide a mechanism to create infinite sequences repeating
  a certain sequence over and over again.}
\generic{cycle}{x|... => <cycle>}
  \doc{returns a cycles that repeats elements of \kode{x}.}
\end{defs}

\section{Symbols}

Symbols are uniquified (aka interned) strings.

\begin{defs}
\class{<sym>}{<any>}
\class{<sym-tab>}{<tab>}
  \doc{symbol table class.}
\method{as}{\_|(t= <sym>) x|<str> => <sym>}
  \doc{coerces a string to a symbol.}
\generic{cat-sym}{elts|... => <sym>}
  \doc{returns a symbol formed by concatenating the string
  representations of \kode{elts}.}
\generic{gensym}{=> <sym>}
  \doc{returns a system specific unique symbol.}
\generic{fab-setter-name}{x|<sym> => <sym>}
  \doc{$\equiv$ \kode{(as <sym> (cat (as <str> x) "-setter"))}.}
% \generic{var-name}{x|(t+ <sym> <lst>) => <sym>}
% \generic{var-type}{x|(t+ <sym> <lst>) => <sym>}
\end{defs}

\section{Conditions}

Conditions are objects representing exceptional situations.  
\goo\ provides restartable conditions as well as the more traditional stack
unwinding conditions.  A condition is an object used to provide
information to a handler.  A handler is an object with a handler
function used to take care
of conditions of a particular type.  Signalling is a mechanism for
finding the most appropriate handler for a given condition.
See DRM~\cite{Shalit:1996} for more information.

\begin{defs}
\class{<condition>}{<any>}
\generic{default-handler}{x|<condition> => <fun>}
  \doc{called if no appropriate handler is in force.}
\generic{default-handler-description}{c|<condition> => <str>}
  \doc{return a string describing an anonymous handler for this type of
  condition.}
\generic{build-condition-interactively}{type|<condition> in out
           => <condition>}
  \doc{construct a condition of the specified type and interactively prompt
  the user to fill in any important props.  Called by the debugger.
  Methods should call next-method to build the condition, then set the
  props for their own class.}
\generic{sig}{x|<condition> args|...}
  \doc{signals a condition with optional arguments args.}
\class{<simple-condition>}{<condition>}
  \doc{a condition consisting of a \kode{msg} message and arguments.}
\property{condition-message}{x|<simple-condition> => <str>}
  \doc{returns \kode{msg} string.}
\property{condition-arguments}{x|<simple-condition> => <lst>}
  \doc{returns \kode{msg} string arguments.}
\class{<serious-condition>}{<condition>}
  \doc{a condition that can not be safely ignored.}
\class{<error>}{<serious-condition>}
  \doc{a condition that indicates something is invalid about the program.}
\generic{error}{x|<any> args|...}
  \doc{signals an error.}
\method{error}{x|<str> args|...}
  \doc{signals a simple error.}
\class{<simple-error>}{<error> <simple-condition>}
  \doc{an error that consists of a \kode{msg} message and arguments.}
\class{<restart>}{<condition>}
  \doc{used for restarting a computation.}
\class{<handler>}{<any>}
  \doc{object used for handling a signaled condition.}
\generic{handler-function}{x|<handler> => <fun>}
\generic{fab-handler}{x|<fun> => <handler>}
  \doc{creates a handler from a handler function.}
\generic{handler-matches?}{x|<handler> y|<condition> => <log>}
  \doc{protocol for determining whether a handler handles a particular
  condition.}
\form{TRY}{(TRY ,try-options ,handler ,@body)}
  \doc{installs \kode{,handler} as a condition handler for the
  duration of \kode{(SEQ ,@body)}, using the instructions provided
  by \kode{,try-options}.
  \kode{,try-options} should either be the name of the condition type to
  \kode{handle}, or a \kode{,try-option-list} with zero or more of the
  following options: 
  \begin{packeditemize}
    \item \kode{(TYPE ,expr) =>}
      An expression returning the type of condition to handle.
    \item \kode{(TEST ,@body) => Code}
       which returns \kode{\#t} if the condition is applicable,
      and \kode{\#f} otherwise.  This may be called at arbitrary times 
      by the runtime, so it shouldn't do anything too alarming.
    \item \kode{(DESCRIPTION ,message ,@arguments) =>}
      A human-readable description of this handler.  Used by the debugger.
  \end{packeditemize}

  The handler function should take two arguments: the \kode{,condition} to be
  handled, and a \kode{,resume} function.  if a matching condition is signaled
  then the handler function is called with the signaled condition and a
  resume function to be called if the handler wants to return a value to be
  used as the result of the signaling \kode{SIG} call.  the handler has three
  possibilities: (1) it can handle the condition by taking an exit using
  \kode{ESC}, (2) it can resume to the original \kode{SIG} call using the
  resume function
  called with the value to be returned, or (3) it can do neither, that is,
  it can choose not to handle the condition by just falling through to the
  end of the handler (cf., Dylan's \kode{BLOCK}/\kode{EXCEPTION} 
  and \kode{LET HANDLER}) and the next available handler will be invoked.
  Note that \goo\ {\bf does not unwind the stack} before calling
  handlers!}
\end{defs}

where

\begin{defs}
\syntax{handler}{(fun (,condition ,resume) ,@body)}
\syntax{,try-options}{,condition-type-name | ,try-option-list}
\syntax{,try-option-list}{(,try-option* )}
\syntax{,try-option}{(,option-name ,@option-value)}
\end{defs}

\subsection{Conditions Hierarchy}

\goo\ has a builtin hierarchy of conditions.

\begin{defs}
\class{<arithmetic-error>}{<error>}
\class{<stack-overflow-error>}{<error>}
\class{<keyboard-interrupt>}{<error>}
  \doc{user hit interrupt key.}
\class{<internal-error>}{<simple-error>}
  \doc{a system fault was detected.}
\class{<assert-error>}{<simple-error>}
  \doc{an assertion failure occurred.}
\class{<unbound-error>}{<error>}
  \doc{an binding or property was found to be unbound.}
\class{<unbound-variable-error>}{<unbound-error>}
  \doc{a binding was found to be unbound.}
\property{unbound-variable-error-variable}{<unbound-variable-error> => <any>}
\class{<property-error>}{<error>}
\propertyinit{property-error-generic}{<property-error> => <any>}{\#f}
  \doc{property accessor if available.}
\propertyinit{property-error-owner}{<property-error> => <any>}{\#f}
  \doc{property owner if available.}
\class{<property-unbound-error>}{<property-error> <unbound-error>}
  \doc{unbound property was discovered.}
\class{<property-type-error>}{<property-error> <type-error>}
  \doc{attempt was made to store an invalid object in a property.}
\class{<property-not-found-error>}{<property-error>}
  \doc{attempt was made to find a missing property, most likely during
  a call to \kode{new}.}
\class{<as-error>}{<type-error>}
  \doc{no \kode{as} method was found.}
\class{<range-error>}{<error>}
  \doc{a key lookup on a collection failed.}
\property{range-error-collection}{<range-error> => <col>}
\property{range-error-key}{<range-error> => <any>}
\class{<type-error>}{<error>}
  \doc{a type check has failed.}
\property{type-error-value}{<type-error> => <any>}
  \doc{returns value on which type check failed.}
\property{type-error-type}{<type-error> => <any>}
  \doc{returns type on which type check failed.}
\class{<call-error>}{<error>}
  \doc{an function call failed.}
\property{call-error-function}{<call-error> => <fun>}
  \doc{returns function on which call failed.}
\property{call-error-arguments}{<call-error> => <fun>}
  \doc{returns arguments on which call failed.}
\class{<arity-error>}{<call-error>}
  \doc{wrong number of arguments supplied in function call.}
\class{<narity-error>}{<arity-error>}
  \doc{too few arguments supplied in nary function call.}
\class{<unknown-function-error>}{<call-error>}
  \doc{too few arguments supplied in nary function call.}
\class{<argument-type-error>}{<type-error> <call-error>}
  \doc{invalid argument used function call.}
\class{<return-type-error>}{<type-error> <call-error>}
  \doc{invalid result returned from function call.}
\class{<ambiguous-method-error>}{<call-error>}
  \doc{unable to sort applicable methods.}
\class{<no-applicable-methods-error>}{<call-error>}
  \doc{no methods were applicable.}
\class{<no-next-methods-error>}{<call-error>}
  \doc{no next-methods were found during a \kode{sup} or
  \kode{app-sup} call.}
\class{<incongruent-method-error>}{<error>}
  \doc{a method is incongruent with a generic.}
\property{incongruent-method-error-generic}{<incongruent-method-error> => <gen>}
\property{incongruent-method-error-method}{<incongruent-method-error> => <met>}
\class{<cpl-error>}{<error>}
  \doc{unable to find a consistent class precedence list.}
\class{<io-error>}{<error>}
  \doc{an input/output operation failure.}
\class{<file-opening-error>}{<io-error>}
  \doc{unable to open a file.}
\property{file-opening-error-filename}{<file-opening-error> => <str>}
\class{<directory-error>}{<file-opening-error>}
\class{<compiler-error>}{<error>}
\class{<syntax-error>}{<compiler-error>}
\class{<macro-error>}{<syntax-error>}
  \doc{a macro expansion failure.}
\class{<ast-error>}{<compiler-error> <simple-error>}
  \doc{an ast conversion failure.}
\class{<namespace-error>}{<compiler-error> <simple-error>}
  \doc{a namespace form failure.}
\end{defs}

\section{Input / Output}

This is a very preliminary I/O system and is mostly just enough with
which to write a compiler.

\subsection{Ports}

Ports represent character-oriented input/output devices.

\begin{defs}
\class{<port>}{<seq>}
\generic{open}{t|(t< <port>) x|<str> => <port>}
  \doc{creates port given port specific spec \kode{x}.}
\generic{close}{x|<port>}
  \doc{closes and cleanups port.}
\methodcont{x|<port>}
  \doc{noop default.}
\form{WITH-PORT}{(WITH-PORT (,name ,port) ,@body)}
  \doc{binds \kode{,name} to the value of \kode{,port} 
       during the evaluation of \kode{(seq ,@body)} and finally
       ensures that the port is closed at the end of evaluation.}
\generic{eof-object?}{x|<chr> => <log>}
\class{<in-port>}{<port>}
  \doc{input port.}
\instance{in}{<in-port>}
  \doc{standard input.} 
\generic{get}{x|<in-port> => <chr>}
  \doc{returns next available character or eof-object.}
\generic{gets}{x|<in-port> => <str>}
  \doc{returns a line until either reading a newline or eof-object.}
\generic{peek}{x|<in-port> => <chr>}
  \doc{returns next available character if any without advancing 
  pointer or eof-object.}
\generic{ready?}{x|<in-port> => <log>}
  \doc{returns true iff a character is available.}
\class{<out-port>}{<port>}
  \doc{output port.}
\instance{out}{<out-port>}
  \doc{standard output.}
\generic{force-out}{x|<out-port>}
  \doc{ensures that buffers are forced and pending output is completed.}
\generic{put}{x|<out-port> e|<chr>}
  \doc{outputs a single character.}
\generic{puts}{x|<out-port> e|<str>}
  \doc{outputs string.}
\generic{newline}{x|<out-port>}
  \doc{outputs a newline sequence.}
\generic{say}{x|<out-port> args|...}
  \doc{$\equiv$ \kode{(do (op puts x (to-str \_)) args)}}
\end{defs}

\subsubsection{File Ports}

File ports are ports which map to files.

\begin{defs}
\class{<file-port>}{<port>}
\method{close}{x|<file-port>}
  \doc{closes port and finishes pending output.}
\class{<file-in-port>}{<file-port> <in-port>}
\method{open}{t|(t= <file-in-port>) name|<str> \snl => <file-in-port>}
  \doc{creates file in port mapped to a file with filename \kode{name}.}
\class{<file-out-port>}{<file-port> <out-port>}
\method{open}{t|(t= <file-out-port>) name|<str> \snl => <file-out-port>}
  \doc{creates file out port mapped to a file with filename \kode{name}.}
\end{defs}

\subsubsection{String Ports}

String ports provide port interface mapped onto strings.

\begin{defs}
\class{<str-port>}{<any>}
\property{port-contents}{x|<str-port> => <str>}
  \doc{returns underlying string.}
\class{<str-in-port>}{<str-port> <out-port>}
\method{open}{t|(t= <str-in-port>) dat|<str> \snl => <str-in-port>}
  \doc{creates string in port mapped to string \kode{dat}.}
\property{port-index}{x|<str-port> => <int>}
  \doc{returns index from which next character will be read.}
\class{<str-out-port>}{<str-port> <in-port>}
\method{open}{t|(t= <str-out-port>) dat|<str> \snl => <str-out-port>}
  \doc{creates string out port mapped to string \kode{dat}.}
\form{PORT-TO-STR}{(PORT-TO-STR ,name ,@body)}
  \doc{$\equiv$ \kode{(let ((,name (open <str-out-port> ""))) ,@body (port-contents ,name))}}
\end{defs}

\subsection{Formatted I/O}

\goo\ provides convenient s-expression reading/writing facilities.

\begin{defs}
\generic{read}{x|<in-port> => <any>}
  \doc{returns sexpr result of parsing characters in a sequence.}
% \generic{read-from-str}{x|<str> => <any>}
%   \doc{$\equiv$ \kode{(read (new <str-in-port> port-contents x))}}
% \generic{read-file}{filename|<str> => <any>}
%   \doc{$\equiv$ \kode{(with-port (x (open-in-file filename)) (read x))}}
\generic{write}{x|<out-port> y|<any>}
  \doc{verbose printing.  prints strings with double quotes etc.}
\generic{writeln}{x|<out-port> y|<any>}
  \doc{$\equiv$ \kode{(seq (write x y) (newline x))}}
\generic{emit}{x|<out-port> y|<any>}
  \doc{concise printing (e.g., prints strings without double quotes).}
% \generic{write-to-str}{x|<any> => <str>}
\generic{msg}{x|<out-port> message|<seq> args|...}
  \doc{formatted output using special commands embedded in message.
  supported commands are:
  \begin{packeditemize}
  \item \kode{\%=  $\rightarrow$ (write x arg)}
  \item \kode{\%s  $\rightarrow$ (display x arg)}
  \item \kode{\%d  $\rightarrow$ (write x arg)}
  \item \kode{\%\% $\rightarrow$ (write-char x \#$\backslash$\%)}
  \end{packeditemize}
  which consume one argument at a time.  otherwise subsequent message
  characters are printed to port \kode{x} 
  (cf. Dylan's and CL's \kode{format}).}
\generic{post}{message|<seq> args|...}
  \doc{$\equiv$ \kode{(app msg out message args)}}
\end{defs}

\section{System}

This is a very rudimentary portable interface to an underlying
operating system.

\begin{defs}
\method{app-filename}{=> <str>}
  \doc{returns the filename of the application.}
\method{app-args}{=> <lst>}
  \doc{returns a list of argument strings with which the application 
       was called.}
\method{os-name}{=> <str>}
  \doc{returns name of current operating-system.}
\method{os-val}{s|<str> => <str>}
  \doc{returns OS environment variable value.}
\method{os-val-setter}{v|<str> s|<str> => <str>}
  \doc{sets OS environment variable value.}
\method{process-id}{=> <int>}
  \doc{returns the process id of the current \goo\ process.}
% \instance{*goo-root*}{=> <str>}
%   \doc{top of installation directory structure.}
% \instance{*module-search-path*}{=> <seq>}
%   \doc{path from which to find goo files.}
% \instance{*goo-build-root*}{=> <str>}
%   \doc{top of build directory structure.}
\end{defs}

\subsection{Files and Directories}

A preliminary set of file and directory facilities are provided.

\begin{defs}
\method{file-mtime}{filename|<str> => <flo>}
  \doc{return the last modification time of a file in seconds (relative to the
n       \goo epoch) as a floating point number.}
\method{file-exists?}{filename|<str> => <log>}
  \doc{return true if and only if a file (or a directory, etc.) exists with
       the given name.}
\method{file-type}{filename|<str> => <sym>}
  \doc{return \kode{'file}, \kode{'directory} or some other symbol, 
       depending on the type of the file.}
\method{create-directory}{filename|<str> => <sym>}
  \doc{create a directory with the given name.  The parent directory must
       already exist, and must contain no item with the given name.}
\method{parent-directory}{name|<str> => <str>}
  \doc{find the parent directory of the current filename.}
\method{probe-directory}{name|<str> => <str>}
  \doc{make sure that the named directory exists.}
\end{defs}

\subsection{Pathnames}

Pathnames allow you to work with hierarchical, structured pathnames in
a reasonably portable fashion.

\begin{defs}
\method{pathname-to-components}{pathname|<str> => <lst>}
  \doc{given a pathname, split it into a list of individual directories, etc.
       Three special values are returned as symbols:
       \begin{packeditemize}
       \item \kode{root} $\rightarrow$ This path starts in the root directory
       \item \kode{up} $\rightarrow$ Go up a directory
       \item \kode{current} $\rightarrow$ Remain in the current directory
       \end{packeditemize}
       Volume labels, drive letters, and other non-path information should
       be stored in a single tagged list at the head.  
%       For example:
%       \begin{exv}
%       C:\a\c.txt -> ((drive "C:") root "a" "c.txt")
%       \end{exv}
       Note that the hierarchical portion of this pathname (everything but the
       label) must be non-empty at all times.}
\method{components-to-pathname}{components|<lst> => <str>}
  \doc{reassemble components created by the above function.}
\method{label-components}{components|<lst> => <lst>}
  \doc{get any leading directory label.}
\method{hierarchical-components}{components|<lst> => <lst>}
  \doc{get rid of any leading directory label, etc.}
\method{components-last}{components|<lst> => <any>}
  \doc{return the last item in a list of components.}
\method{components-basename}{components|<lst> => <lst>}
  \doc{return all but the last item of a bunch of components.
       Do some magic to handle cases like \kode{'foo.txt' => './'}
       If you call this function enough times, you are eventually
       guaranteed to get components list ending in root, up or current.
       Requires the last item to be a string.}
\method{components-parent-directory}{components|<lst> => <lst>}
  \doc{calculate the parent directory of a pathname.}
\class{<pathname-error>}{<simple-error>}
\end{defs}

\section{Threads}

Threads allow for expressing concurrent programs.  The assumed model
is shared memory with explicit synchronization and symmetric
multiprocessing and is based heavily upon pthreads %~\cite{pthreads} .
This section is preliminary and might change in the future.  There are
several limitations in the current implementation.  It represents a
rudimentary but usable subset of typical thread operations.  Tables
and vectors require user locks to ensure thread safety and no out of
language crashes.  Finally, the compiler, interpreter, and
(re)definition machinery are thread unsafe and can only reliably be
run in one thread.

\begin{defs}
\class{<thread>}{<any>}
  \doc{Represents a thread of executation schedulable across 
  multiple processors.  Upon creation executes \code{thread-function}
  in separate thread.} 
\propertyinit{thread-name}{thread|<thread> => (t? <sym>)}{#f}
\propertyinit{thread-priority}{thread|<thread> => <int>}{0}
\propertyinit{thread-function}{thread|<thread> => <fun>}{(fun ())}
\method{new}{x|(t< <thread>) inits|... => <thread>}
  \doc{Creates thread and runs \code{thread-function} of created
  thread in separate OS thread.}
\form{SPAWN}{(SPAWN ,@body)}
  \doc{$\equiv$ \kode{(FAB <thread> thread-function (fun () ,@body))}}
\method{thread-yield}{}
  \doc{Surrenders processor to another thread.}
% \method{thread-detach}{}
\method{thread-join}{thread|<thread>}
  \doc{Causes current thread to wait for the termination of \code{thread}.}
\method{thread-current}{=> <thread>}
\method{all-threads}{=> <tup>}
\method{sleep}{secs|<flo>}
  \doc{Pauses current thread for \code{secs} seconds.}
\class{<lock>}{<any>}
  \doc{Represents a mutex.}
\property{lock-name}{lock|<lock> => (t? <sym>)}
\method{new}{x|(t< <lock>) inits|... => <lock>}
\method{lock-lock}{lock|<lock>}
  \doc{Obtain exclusive access to \kode{lock} waiting if necessary.}
\method{lock-unlock}{lock|<lock>}
  \doc{Free up exclusive access to \kode{lock} potentially allowing 
  another thread access.}
% \method{lock-destroy}{lock|<lock>}
\form{WITH-LOCK}{(WITH-LOCK ,lock ,@body)}
  \doc{$\equiv$ \kode{(FIN (SEQ (lock-lock ,lock) ,@body) (lock-unlock ,lock))}}
\class{<event>}{<any>}
  \doc{Represents a condition variable used for interthread notification.}
\propertyinit{event-name}{event|<event> => (t? <sym>)}{#f}
\method{new}{x|(t< <event>) inits|... => <event>}
\method{event-signal}{event|<event> lock|<lock>}
  \doc{Unblocks at least one thread waiting on \code{event}.}
\method{event-broadcast}{event|<event> lock|<lock>}
  \doc{Unblocks all threads waiting on \code{event}.}
% \method{event-destroy}{event|<event>}
% \method{event-reset}{event|<event>}
\method{event-wait}{event|<event> lock|<lock> => <log>}
  \doc{Unlocks \code{lock} and places thread in waiting state to be
  resumed when \code{event} is signaled or broadcasted upon which time
  \code{lock} is reacquired and thread resumed.}
\method{event-wait-timed}{event|<event> lock|<lock> secs|<flo> => <log>}
  \doc{Unlocks \code{lock} and places thread in waiting state to be
  resumed when \code{event} is signaled or broadcasted or timeout
  \code{secs} is reached upon which time \code{lock} is reacquired 
  and thread resumed.}
\form{DDV}{(DDV ,var ,form)}
  \doc{Defines a thread local variable named \kode{(var-name ,var)} with an 
  initial value \kode{,form}.}
\form{DLET}{(DLET ((,var ,val) ...) ,@body)}
  \doc{$\equiv$ \kode{(LET ((,old-var ,var) ...) (FIN (SEQ (SET ,var
  ,val) ... ,@body) (SET ,var ,old-var) ...))}}
\class{<pipe>}{<flat> <seq!>}
  \doc{Represents a synchronized FIFO queue allowing multiple readers
  and writers in separate threads.}
\method{enq!}{pipe|<pipe> x => <pipe>}
  \doc{Adds \code{x} to \code{pipe}.} 
\method{deq!}{pipe|<pipe> => <any>}
  \doc{Removes and returns element from \code{pipe} or waits for one
  to be available.} 
% \method{dequeue-or!}{pipe|<pipe> default => <any>}
%   \doc{Removes and returns element from \code{pipe} or returns
%   \code{default} if \kode{pipe} is empty.}
\end{defs}

\section{C Interface}

A simple mechanism (available through the \kode{goo/x} module) is
provided to inline C code directly into \goo, escaping back into \goo\
when necessary, and relying on C for its type system instead of having
to mirror it in \goo.  On the downside, there is no static checking,
and errors can occur during C compilation.

\begin{defs}
\form{\#" ... "\#}{Liberal String}
  \doc{Allows for the easy specification of strings (especially C code
  snippets) with special character escaping turned off.}
\form{C-MENT}{(C-MENT [,c-snippet ,goo-form]*)}
  \doc{Specifies a C statement formed as the
  concatenation of c-snippets (goo strings) and
  \goo\ forms~\footnote{Currently,
  embedded \goo\ loops are unsupported}.  
  The \goo\ forms are evaluated at runtime as embedded C expressions in the
  lexical context of the \kode{c-ment} expression.
  If specified at top level, then the \kode{c-ment} form 
  will be evaluated prior to the
  evaluation of non \kode{c-ment} top level forms.
}
\form{C-EXPR}{(C-EXPR [,c-snippet ,goo-form]*)}
  \doc{Same as \kode{c-ment} but specifies a value producing C
  expression instead.}
\generic{to-c}{x}
  \doc{user extensible protocol for converting a \goo\ object to a C
  value.  Methods are provided for \kode{<int>}, \kode{<flo>},
  \kode{<str>}, \kode{<chr>}, \kode{<log>}, and \kode{<loc>}.}
\form{\#\{ ... \}}{Inlined C Statement}
  \doc{Shorthand for \kode{c-ment} allowing \goo\ forms to be
  specified with a \kode{\$} prefix and the conversion of \goo\
  objects into C values specified with an
  \kode{@} prefix, with \kode{@x} $\equiv$ \kode{\$(to-c x)}.
For example,
\begin{ex}
(df f (x) \#\{ printf("Got \%lx", \$x); \})
\end{ex}
prints out the \goo\ value \kode{x}.  
A callback can be defined at top level as follows:
\begin{ex}
\#\{ int gl\_idle(int x) \{ \$(gl-idle); \} \}
\end{ex}
C headers can be included similarly:
\begin{ex}
\#\{ \#include "GL.h" \}
\end{ex}
C expressions can be nested within embedded \goo\ expressions as follows:
\begin{ex}
\#\{ int gl\_idle(int x) \{ \$(gl-idle \#ei\{ x \}); \} \}
\end{ex}
in order to access lexical apparent C variables etc.
}
\form{\#ec\{ ... \}}{Inlined C Expression}
  \doc{Similar shorthand for \kode{c-expr} also allowing a single
  character code \kode{c} for specifying the conversion of C values back to
  \goo\ objects.  The valid codes are \kode{i} for \kode{<int>}, 
  \kode{f} for \kode{<flo>}, \kode{s} for \kode{<str>}, 
  \kode{c} for \kode{<chr>}, \kode{b} for \kode{<log>}, 
  \kode{l} for \kode{<loc>}, \kode{g} for none.
For example, 
\begin{ex}
(d.\ \$gl-line-loop \#ei\{ GL\_LINE\_LOOP \})
\end{ex}
defines a top-level OpenGL constant.
}
\form{USE/LIBRARY}{(USE/LIBRARY ,name)}
  \doc{adds \kode{,name} to list of libraries to be linked against.}
\form{USE/INCLUDE}{(USE/INCLUDE ,name)}
  \doc{adds \kode{,name} to include directory search path.}
\end{defs}

\section{Compiler}

\goo's compiler, {\em g2c}, compiles \goo\ source code to C.  It lives
within the \kode{eval} module.  During a given session, \kode{g2c} recompiles
only used modules that are either modified or use modified modules.

\begin{defs}
\class{<g2c-module-loader>}{<module-loader>}
  \doc{a g2c module loader used in g2c builds.}
\method{g2c-def-app}{appname|<str> modname|<str> \snl => <g2c-module-loader>}
  \doc{constructs a g2c module loader to be used in future g2c builds.}
\method{g2c-build-app}{loader|<g2c-module-loader>}
  \doc{translates \goo\ app into C in subdirectory of \goo's toplevel C
       directory named after loader's top modname.}
\method{g2c-goo}{}
  \doc{builds entire goo world.}
\method{g2c-test}{name}
  \doc{changes destination directory to be \kode{(cat "g2c-" (to-str
  name))}.  This is useful for bootstrapping.}
\end{defs}

\section{Top Level}

Functions which load code at runtime require a symbol specifying the
module name to use.

\begin{defs}
\generic{load}{filename|<str> modname|<sym> => <any>}
  \doc{returns the result of evaluating the result of reading file
  named \kode{filename} into module \kode{modname}.}
\generic{eval}{x|<any> modname|<sym> => <any>}
  \doc{return's result of evaluating \kode{x}.}
\generic{top}{modname|<sym>}
  \doc{runs top-level \kode{read-eval-print} loop which reads from 
  in and writes to out.}
% \generic{do-stack-frames}{f|<fun>}
%   \doc{evaluates \kode{(app f f args)} on all stack frames.}
\generic{save-image}{filename|<str>}
  \doc{saves an image of the current \goo\ process to a file 
       named \kode{filename}.}
\instance{\$ \$\$ \$\$\$}{<any>}
  \doc{refers respectively to last, second to last, and third to last
       values returned in top-level listener.}
\end{defs}

% \section{Series Protocol}
% 
% This section describes a proposed loopless programming protocol 
% based on Waters' series~\cite{Waters:1991:ATS}.
% 
% \begin{defs}
% \generic{until}{logs|<seq> x|<seq> => <seq>}
%   \doc{returns the first \kode{k} elements of \kode{x}, where \kode{k}
%   is the index of the first false in \kode{logs}.}
% \generic{expand}{logs|<seq> x|<seq> default \snl => <seq>}
%   \doc{is the quasi-inverse of \kode{pick} and returns a sequence
%   consisting of elements of \kode{x} in the non-false positions of
%   \kode{logs} and \kode{default} elsewhere.}
% \generic{split}{x|<seq> logs|<seq> \snl => (tup <seq> <seq>)}
%   \doc{returns two sequences corresponding to non-false and false
%   elements of \kode{logs} respectively.}
% \generic{indices}{logs|<seq> => <seq>}
%   \doc{returns a sequence with the indices of the non-false elements 
%   of \kode{logs}.}
% \generic{mask}{x|<seq> => <seq>}              %
%   \doc{is the quasi-inverse of \kode{indices} and returns a sequence
%   with true at all indices specified by the integer elements of \kode{x}
%   and falses elsewhere.}
% \generic{merge}{x|<seq> y|<seq> logs|<seq> \snl => <seq>}
%   \doc{returns a sequence consisting of all the elements of \kode{x} and
%   \kode{y} chosen based on logical sequence \kode{logs}.}
% %TODO: MORE DOC
% \generic{chunk}{m|<int> n|<int> x|<seq> \snl => <tup>}
%   \doc{returns \kode{m} sequences with starting positions differing 
%   by \kode{n}.}
% \generic{prev}{x|<seq> default amount|<int> \snl => <seq>}
%   \doc{returns a sequence same as \kode{x} except shifted to the right
%   by \kode{amount} inserting \kode{amount} copies of \kode{default} at
%   the beginning.}
% %TODO: MORE DOC
% \generic{latch}{x|<seq> after before pre post \snl => <seq>}
%   \doc{returns a sequence same as \kode{x} except some values are
%   replaced based on latching behavior ...}
% \end{defs}

\section{Installation}

Unpack a \goo\ development or platform specific binary tarball into an
appropriate staging directory.  In the case of a binary tarball, there
will be five directories: \kode{doc}, \kode{bin}, \kode{c},
\kode{src}, and \kode{emacs}.  You can just run \goo\ from the
\kode{bin} subdirectory.

In the case of a development tarball, you must install it.  After
unpacking, there will be five directories: \kode{doc}, \kode{bin},
\kode{c}, \kode{src}, and \kode{emacs}.  On windows, installation must
be conducted from within a cygwin shell.  \goo\ requires Boehm's GC to
be installed as a shared library on linux or under the source dir
\kode{GOO\_DIR/gc} downloadable from
\kode{http://www.hpl.hp.com/personal/Hans\_Boehm/gc/gc\_source/gc.tar.gz}.
\goo\ also requires gmp to be installed as a library downloadable from 
\kode{http://www.swox.com/gmp/}.

Generate makefiles by executing \kode{./configure}.  Configure takes a
\kode{--prefix} argument which sets the installation root,
\kode{GOO\_ROOT}.  Normally \kode{GOO\_ROOT} is set to \kode{/usr/local}
but can be set to staging directory for a personal installation.
Configure also takes a \kode{--with-threads} argument which enables
threads support on linux.  The rest of the configure arguments can be
found by executing \kode{./configure --help}.  Execute \kode{make} to
build \goo\ and \kode{make install} to install it.  Executing
\kode{make install} will build \goo\ with the proper roots, creating
\kode{lib} and \kode{mods} directories, and installing \goo\ in
\kode{bin} and setting up \kode{doc}.  On windows, it is necessary to
add \kode{GOO\_BIN} to your \kode{PATH}.

You can override the default \kode{GOO\_ROOT} by
setting up your \kode{OS} environment variable.  
For example, my \kode{GOO\_ROOT} on linux is: 
\kode{setenv GOO\_ROOT /home/ai/jrb/goo}.
Environment variable setting depends on the shell you're using.
In order to run \kode{g2c-goo} you need to
set \kode{GOO\_BUILD\_ROOT} to the directory which includes the \kode{src}
directory.  

During start up, \goo\ will load two patch files:

\begin{exv}
${GOO_ROOT}/init.goo
${HOME}/.goo/init.goo
\end{exv}

You can customize your \goo\ by adding forms to these files.

\section{Usage}

Typing \kode{goo} at your shell will start up a \goo\ read-eval-print
loop, which accepts sexpressions and top-level commands commencing
with a comma.  The following is a list of available commands:

\begin{defs}
\command{,quit}{\emptybox}
  \doc{exits from \goo.}
\command{C-c}{\emptybox}
  \doc{invokes a recursive read-eval-print loop.}
\command{,g2c-eval}{\emptybox}
  \doc{to change to dynamic compilation evaluation.}
\command{,ast-eval}{\emptybox}
  \doc{to change to ast evaluation.}
\instance{GOO\_EVAL\_MODE}{<str>}
  \doc{environment variable for setting goo's evaluation mode.  Valid
  settings are ``ast'' or ``g2c''.}
\command{,in}{,name}
  \doc{changes to module \kode{,name}.}
\syntax{mod:name}{\emptybox}
  \doc{accesses an unexported binding from another module.}
% \generic{frame-var}{n|<int> name|<sym>}
%   \doc{returns \kode{n}{\it th} called function argument named
%   \kode{name}.  Can also be called at top-level as a function.}
\end{defs}

\subsection{Development}

To batch compile \goo\ to C:

\begin{exv}
goo/user 0<= (use eval/g2c)
goo/user 0=> #f
goo/user 0<= (g2c-goo)
\end{exv}

To then compile the C:

\begin{exv}
cd ${GOO_ROOT}/c
make
\end{exv}

To run the test suites:

\begin{exv}
goo/user 0<= (use tests)
goo/user 0=> #f
goo/user 0<= (run-all-tests)
\end{exv}

\subsection{Debugger}

A keyboard interrupt or any error enters the user into the debugger
which provides a superset of the commands available at top-level.
The following are debugger specific commands:

\begin{defs}
\command{,up}{\emptybox}
  \doc{goes up one level.}
\command{,top}{\emptybox}
  \doc{goes to top level.}
\command{,restarts}{\emptybox}
  \doc{lists available restarts}
\command{,restart}{,n}
  \doc{chooses available restart.}
\command{,handlers}{,n}
  \doc{shows available handlers.}
\command{,backtrace}{\emptybox}
  \doc{prints out called functions and their arguments.}
\command{,bt}{\emptybox}
  \doc{prints out called functions.}
\command{,frame}{,n}
  \doc{prints out \kode{n}{\it th} called function and its arguments.}
\command{,frame-var}{,n ,name}
  \doc{prints out \kode{n}{\it th} called function's parameter \kode{name}.}
\function{frame-var}{n|<int> name|<sym>}
  \doc{returns \kode{n}{\it th} called function's parameter \kode{name}.}
\end{defs}

% \subsection{Loading Code}
% 
% Use the load function to load a file of source into goo:
% 
% % \begin{exv}
% %   (load "\\jrb\\ai\\goo\\interpreters\\basic.goo")
% % \end{exv}
% 
% \begin{exv}
% (load "/usr/jrb/goo/src/demo.goo")
% \end{exv}
% 
% Make sure to use double backslashes on windows in pathnames.  Also you
% probably need to use an absolute pathname for your file include the
% \kode{".goo"} suffix if appropriate.

\subsection{Emacs Support}

A rudimentary emacs-based development system is provided.

\subsubsection{Emacs Mode}

Put \kode{emacs/goo.el} in your emacs lisp directory.  Add the following to
your \kode{.emacs} file:

\begin{exv}
(autoload 'goo-mode "goo" "Major mode for editing Goo source." t)
(setq auto-mode-alist
      (cons '("\\.goo\\'" . goo-mode) auto-mode-alist))
\end{exv}

Useful features include the following.
You can add ``font-lock'' mode by adding 
\kode{(global-font-lock-mode t)} to your \kode{.emacs}:
In a given buffer, you can toggle font-lock with \kode{M-x font-lock-mode}.
Finally, check out the ``Index'' menu item in a \goo\ buffer for other
options.

For even more fun, load \kode{emacs/goo-font-lock.el} for a color
coded parenthesis nesting aid~\footnote{The original idea was dreamed
up and first implemented by Andrew Sutherland and then improved by
James Knight.}.

\subsubsection{Emacs Shell}

Put \kode{emacs/goo-shell.el} in your emacs lisp directory.  Add the
following to your \kode{.emacs}:

\begin{exv}
(autoload 'run-goo  "goo-shell" "Run an inferior Goo process." t)
(setq auto-mode-alist
      (cons '("\\.goo\\'" . goo-mode) auto-mode-alist))
(setq goo-program-name "/home/ai/jrb/goo/goo") 
\end{exv}

make sure to set up the goo-program-name to correspond to your
installation area.

Useful command / key-bindings are:

\begin{exv}
M-C-x   goo-send-definition
C-c C-e goo-send-definition
C-c M-e goo-send-definition-and-go
C-c C-r goo-send-region
C-c M-r goo-send-region-and-go
C-c C-z switch-to-goo
\end{exv}

Check out \kode{goo-shell.el} for the complete list of command /
key-bindings. I doubt the compile commands do anything useful cause
there isn't a compiler.

\subsubsection{TAGS}

Emacs TAGS files can be generated by typing \kode{make all-tags} in
the \kode{src} directory.  Useful tags commands / key-bindings are:

\begin{exv}
M-.     find-tag
M-,     tags-loop-continue
        tags-search
        tags-query-replace
\end{exv}

\section{Caveats} 

This is the first release of \goo.
\goo\ is relatively slow at this point.  There are no compiler
optimizations in place.  The error reporting is minimal and no source
locations are tracked.  Also hygiene is not implemented and there are
some potential hygiene leaks.  Dynamic compilation and image saving
work only on Linux.

This manual is preliminary.  Please consult the runtime
libraries in the \kode{src} directory.  Also check out Scheme and Dylan's
manuals for information on their lexical structure and special form
behavior respectively.

Please, please, please send bug reports to \kode{jrb@googoogaga.org}.  I
will fix your bugs asap.  The \goo\ website \kode{www.googoogaga.org}
will have papers, releases, FAQS, etc.

\section{Future}

The plan is for \goo\ to evolve in a number of dimensions.  First of
all, \goo's design is incomplete.  Parameter lists and dispatch will
be improved to allow methods of differing numbers of required
parameters and named parameters.  Lisp lists will most likely be
deprecated and program fragments will be represented by a richer data
structure which can capture source locations and hygiene information.
This will be accomplished with minimal impact on macro definitions and
WYSIWYG program construction and destructuring facilities.  The module
system will be improved to include in the very least renaming and selective
imports. Finally, \goo\ will support a more complete loopless
programming protocol inspired by Waters'
series~\cite{Waters:1991:ATS}.

Secondly, the overall mission is to crank the implementation until its
performance is competitive with Java while at the same time
maintaining low-latency interactivity.  The basic approach involves
incremental whole program optimization using simple dynamic
compilation combined with partial evaluation.  One important
optimization will be side effect analysis combined with a generalized
box/unbox optimization to remove unnecessary creation of immutable
enumerators and packers for instance.  Similar analyses and
optimizations will be employed to optimize loopless programming
patterns involving \kode{map} and \kode{fold}.

\section{History and Acknowledgements} 

\goo\ has greatly benefitted from the help of others.  During the
winter of 2001, I briefly discussed the early design of Proto, a
Prototype-based precursor to \goo, with Paul Graham and his feedback
was very useful.  From there, I bootstrapped the first version of
Proto for a seminar, called Advanced Topics in Dynamic Object-Oriented
Language Design and Compilation ($6.894$), that I cotaught with Greg
Sullivan and Kostas Arkoudas.  The $6.894$ students were very patient
and gave me many helpful suggestions that greatly improved Proto.
During and after the seminar, Greg Sullivan reviewed many ideas and
helped tremendously, including by writing the Emacs \kode{goo-mode}.  
James Knight was one of the $6.894$ students and
became my MEng student after the course.  He has helped in many many
ways including the writing of the \kode{save-image} facility, the
speeding up of the runtime, and the improving of the non local exit
facility.  Eric Kidd worked with me during the summer of 2001
implementing the module system, restarts, and the dependency tracking
system.  During that summer I decided that a Prototype-based object
system was inadequate for the type system I was interested in
supporting and changed over to the present type-based system.  I
presented my ideas on Proto at LL1 in the Fall of 2001.  Many
stimulating conversations on the follow on LL1 discussion list inpired
me.  In fact, during the course of defending Proto's form of
object-orientation on that list I came up with its current name, \goo,
and it stuck.  Andrew Sutherland became my MEng student in the winter
of 2002, wrote a \goo\ SWIG~\cite{Beaz96a} backend, and has provided
useful feedback on \goo's design.  I also wish to thank Boehm, Demers,
and Weiser for writing the conservative GC upon which this initial
version of \goo\ is based.  Finally, I would like to thank
Keith Playford for his continued guidance in language design and
implementation and for his ever present and rare sense of good taste.
% Most recently, \goo\ has benefitted from the parallel design effort of
% Paul Graham's Arc language~\cite{graham01}.  

% \texonly{
% \begin{myindex}
% \section{Index}
% % \addtocounter{chapter}{1}
% % \addcontentsline{toc}{chapter}{\protect\numberline{\thechapter}{Index}}
% 
% The principal entry for each term, procedure, or keyword is listed
% first, separated from the other entries by a semicolon.
% 
% \bigskip
% 
% \input{index}
% \end{myindex}
% }

\W\section*{Index}
\W\htmlprintindex
% \T\input{hyperlatex.ind}

\bibliographystyle{plain}
\bibliography{goo}

\texonly{
\appendix
}

\section{Class Precedence List}
\label{cpl}

This section defines the algorithm for computing a class's linearized
ancesters from its parents, its parent's parents, etc.  \goo\ uses
the C3 class linearization rule~\cite{dylan-cpl}.  The following is
the \goo\ implementation of this algorithm:

\begin{exv}
(dm class-ordered-ancestors (c|<class> => <lst>)
  (def parents (class-parents c))
  (rep merge-lists
      ((partial-cpl|<lst>     
         (lst c)) 
       (remaining-lists|<lst> 
         (add (map class-ancestors parents) parents)))
    (if (all? nul? remaining-lists)
        (rev! partial-cpl)
        (loc ((candidate (c) 
                (loc ((tail? (l|<lst>) (mem? (tail l) c)))
                  (and (not (any? tail? remaining-lists)) c)))
              (candidate-at-head (l|<lst>)
                (and (not (nul? l)) (candidate (head l)))))
          (def next (any? candidate-at-head remaining-lists))
          (if next
              (loc ((del-next (l|<lst>)
                      (if (== (head l) next) (tail l) l)))
                (merge-lists
                 (pair next partial-cpl) 
                 (map del-next remaining-lists)))
              (error "inconsistent precedence graph"))))))
\end{exv}

\section{Subtyping Rules}
\label{subtyping}

This section defines the subtyping rules for \goo\ in terms of subtype
methods.  

\begin{exv}
(dm subtype? (t1|<union> t2|<type> => <log>)
  (all? (op subtype? _ t2) (type-elts t1)))
(dm subtype? (t1|<type> t2|<union> => <log>)
  (any? (op subtype? t1 _)) (type-elts t2)))
(dm subtype? (t1|<union> t2|<union> => <log>)
  (all? (op subtype? _ t2)) (type-elts t1)))
(dm subtype? (t1|<class> t2|<class> => <log>)
  (subclass? t1 t2))
(dm subtype? (t1|<singleton> t2|<class> => <log>)
  (isa? (type-object t1) t2))
(dm subtype? (t1|<subclass> t2|<class> => <log>)
  (subclass? <class> t2))
(dm subtype? (t1|<class> t2|<singleton> => <log>) #f)
(dm subtype? (t1|<singleton> t2|<singleton> => <log>)
  (== (type-object t1) t2))
(dm subtype? (t1|<subclass> t2|<singleton> => <log>) #f)
(dm subtype? (t1|<class> t2|<subclass> => <log>)
  (and (== t1 <class>) (== (type-class t2) <class>)))
(dm subtype? (t1|<subclass> t2|<subclass> => <log>)
  (subclass? (type-class t1) (type-class t2)))
(dm subtype? (t1|<singleton> t2|<subclass> => <log>)
  (and (isa? (type-object t1) <class>)
       (subclass? (type-object t1) (type-class t2))))
(dm subtype? (t1|<product> t2|<type> => <log>) #f)
(dm subtype? (t1|<type> t2|<product> => <log>) #f)
(dm subtype? (t1|<product> t2|<product> => <log>)
  (and (== (len (type-elts t1)) (len (type-elts t2)))
       (all? (zipped subtype?) (zip (type-elts t1) (type-elts t2)))))
(dm subtype? (t1|<product> t2|<class> => <log>)
  (subtype? <tup> t2))
\end{exv}

\end{document}

