The goo spec
(c)1999 Robey Pointer

design influences, suggestions, and reality checks:
Scott James Remnant, Greg Brown

--

GOO stands for "Goo is Object Oriented".  This is a quick tutorial and
reference guide.  It assumes you know a lot about programming, and is
meant more as a reference for those of us writing and testing the goo
compiler.

 0. Miscellaneous
 1. Variable Declarations
 2. Expressions
 3. Statements
 4. Cheating
 5. Classes
 6. Class Variables
 7. Function Declarations
 8. Function Definitions and Calls
 9. Interfaces
10. Creating Objects (Constructor)
11. Exceptions

40. Persistent Objects
41. Redefining a Class
99. OO Weirdness
[more later?]



(0) Miscellaneous

Comments start at "//" and continue to the end of the line.  Or,
you can use C-style comments which are surrounded by "/*" and "*/".

Backslash substitutions in strings:
	\	ignore linefeed
	\n	LF
	\r	CR
	\\	\
	\"	"
	\xHH	char #HH, where HH is a hex number (ie, "\x3F")

All strings are implicitly UTF-8 and 8-bit clean.  This means they can
store any character from 0 to 255.  This also means that, unlike C, a
zero character (\x00) does NOT delimit the end of a string.


(1) Variable Declarations

[ <classname> ] <identifier> [ "[]" | "{}" ] [ "=" <expression> ] ";"

* without a classname, the identifier is a scalar (float, int, or string)
	numCans;		scalar
* "[]" marks arrays
	groceries[];		array of scalars
	Beer mybeers[];		array of objects of class Beer
* "{}" marks hashes (associative arrays)
	members{};		associative array

An array or hash may contain another array/hash as one of its members.
Example:
	bizarre{} = { "red": [ 3, 4 ], "blue": [ 1, 5, 6 ] };

Variables do not have to be explicitly declared -- they are implicitly
declared the first time you use them.  However, beware that your first
access of the variable defines its type.  If you access it as a scalar,
it becomes a scalar and cannot be used as an array later.  You may
explicitly declare variables before you use them, though, if you like.

A declaration is a valid expression, so it may be used anywhere in an
expression or block of code.  For example, to set two Turtle's to the
same new Turtle:
	Turtle t1 = Turtle t2 = new Turtle;

Note that goo would be just as happy with:
	t1 = t2 = new Turtle;
since they are clearly being assigned as type type Turtle.


(2) Expressions

OPERATORS: (highest to lowest precedence)
@			domain scope change
( ) [ ]			grouping, list creation
.			class member referencing
(...)			function call
[...] {...} [:]		array or hash reference, array slice
++ --			increment, decrement (pre and post)
! ~ # keys		logical not, string to-lower, length-of, keys list
- +			unary negative, positive
new			object creation
..			string concatenation
* / %			multiply, divide, modulo
+ -			add, subtract
>> <<			binary left-shift, right-shift
< > <= >=		logical comparisons
== != ~= in ~in		logical equality or inequality, case-insensitive
			    string equality, and substring matching
is                      object type checking
&			binary and
^			binary xor
|			binary or
as			object type casting
&& and			logical and
|| or			logical or
?:			expression "if"
= += -= *= /= %= ..=	assignment, the 5 math assignments, concat assign
,			separator

The precedence is largely based on C precedence, so there should be no
surprises.

COMPARISONS:
Tests for equivalence ("==", for example) compare scalars by trying to
guess what they're meant to be.  Goo remembers whether a scalar is holding
an integer, a float, or a string, even though it will treat them all equally.
For the purposes of comparison, if both sides are the same type of scalar,
they will be compared in the obvious way.  Otherwise, they will be compared
according to the type of the left operand.

Two objects compare equal only if they are pointing to the same underlying
object.  That is, if you create two objects with identical members, they
will still compare as non-equal.

VARIABLE EXPANSION:
Values in expressions are either method calls, variable names, or constants.
Obviously constants and method calls can only be rvalues.

Constant scalars:
3			int (scalar)
2.998			float (scalar)
"hello"			string (scalar)
undef			the "nil" or "null" (undefined) scalar value

Constant arrays:
"[" <rvalue> *( "," <rvalue> ) "]"
	[5, 3, 10]

Constant hashes:
"{" <scalar> ":" <rvalue> *( "," <scalar> ":" <rvalue> ) "}"
	{ "anchor": 5, "cherry wheat": 34 }

These may be combined -- it's all perfectly legal:
	{ "anchor": 5, "cherry wheat": [ 5, 3, { "x": 9, "y": 12 } ] }

Indexing an array:
<name> "[" <rvalue:int> "]"
(array indexes start at 1)
	myToys[2]

Indexing a hash:
<name> "{" <rvalue:string> "}"
	beerTally{"anchor"}

If the above combo-constant was stored in "beerTally", this expression would
evaluate to "12":
	beerTally{"cherry wheat"}[3]{"y"}
This is another perfectly valid way:
	x = "cherry wheat";
	g = 3;
	beerTally{x}[g]{"y"}

Method calls are distinguished by the "(" ... ")" following the identifier,
and can't be used after any "[" ... "]" or "{" ... "}" pairs.  It may be
used before, though:
	getGrades("scott"){"math"}
In this sense, you'll start to think, "Hey, so {} and [] are just operators
like + and .!"  You would be correct -- they are.  Some of the odder things
this allows are:
	x = getMagicNumber();
	y = [ 1.0, 1.1, 1.3, 1.5, 2.2, 3.9, 5.8, 9.0 ][x];
and:
	pn = getName();
	y = { "Robey": { "age": 24, "sex": "m" },
	      "Scott": { "age": 17, "sex": "yes" } }{pn};
	if (y{"age"} > 18) { ... }
That last one is an alternate way of doing an expr?a:b thing.

An array "slice" is a segment of an array.  This concept and syntax was
stolen directly from python.
	g[] = myToys[3:5];
will set g to be an array made up of elements 3, 4, and 5 of myToys.
Either parameter can be negative, which means to count from the end instead
of the beginning (-1 is the last entry in an array).  If the left parameter
of a slice is missing, it's assumed to be 1.  If the right parameter is
missing, it's assumed to be -1.  Thus
	g[] = myToys[:];
just makes a copy of myToys (from element 1, the first element, to element
-1, the last element).  Note that slices can't ever be assigned to (they
can't be the left side of an assignment).

Slices and array elements can be taken on a scalar.  In that case, the
scalar is treated as if it were an "array of characters".  Thus if 'name'
was a scalar, 'name[1]' would be the first character in that string.  When
used this way, the array element operator can't be assigned to (it can't
be the left side of an assignment).

To get the length of a string (scalar), use the # unary operator.


(3) Statements

For the purposes of goo, a block is equivalent to a statement.  A block is:
	"{" *( <statement> ) "}"

A statement can be an expression followed by a semicolon, a block, or one of
the following constructs:

"if" "(" <expr> ")" <block> [ "else" <block> ]
	Note that goo's "if" statement works like perl's (where braces are
	always required), and not like C's.  This avoids confusion (read the
        Perl book to find out why).  The expression is false only if it	
	evaluates to "undef", 0, 0.0, the empty string, or an empty array
	or hash.  All other values are true.

"while" "(" <expr> ")" <statement>
	Pretty typical.  Same values of "true" and "false" hold.

"foreach" "(" <var-name> { "," | "in" } <rvalue> ")" <statement>
	The <rvalue> is treated as a list of values.  The <statement> is
	executed once for each member of that list, with the <var-name>
	containing each value in turn.  If <rvalue> is a scalar, only one
	iteration is done.  If <rvalue> is an array, each member of the
	array is used, in order.  If <rvalue> is a hash, each hash key is
	used, in what is effectively a random order.

"for" "(" <expr> ";" <expr> ";" <expr> ")" <statement>
	This is equivalent to "for" in C.

"switch" [ "(" <expr> ")" ] "{" *( <expr> *( "," <expr> ) ":" <statement> )
	[ "else" ":" <statement> ] "}"
	There are two forms of the "switch" statement.  If an expression
	is included in parens, it behaves similar to a C "switch"
	statement -- each item is implicitly compared "==" to the
	expression in parens.  Unlike in C, the individual items do
	not have to be constants.

	Without an expression in parens, it behaves more like David Gries'
	"guard" statement.  It acts like multiple "if" statements.  All of
	the expressions that return true will have their statements executed,
	in order (unless/until a "done" is reached).

	[Note for C programmers:] C requires a "break" command at the end
	of each case in a switch to prevent it from executing the next case,
	even if the next case expression doesn't match.  Goo doesn't do that.
	Instead, each case expression is evaluated and ONLY those that match
	are executed.  So you don't need to put a "done" inside each case.

	If you want multiple expressions to execute the same piece of code,
	separate those expressions with commas in a single case.

"done" ";"
	Break out of the current "while", "foreach", "for", or "switch"
	statement.

"return" <expr> ";"
	Cause some value to be the value returned from a function.

"throw" <expr> ";"
	Cause some value to be thrown as an exception (see later section
	on exceptions).

"finally" <statement>
	Execute this statement before leaving the current block of code.
	Only one "finally" may be used per block.

"catch" "(" [class-name] <label> ")" <statement>
	If an exception object of type <class-name> is thrown within the
	surrounding block, execute this statement before leaving the block.
	If no class name is given, a scalar is caught.  (See the section
	below on exceptions.)


Example statements:

	5+7;

	x = "hello";

	if (answer == 5) { z = 5; } else { z = 6; }

	while (t < 500) t++;

	foreach (x, [ 2, 3, 9 ]) { z *= x; }

	for (c = 4; c < 16; c++) t += c;

	// guard-like switch
	switch {
	    t < 500 : {
		err = "Not enough tea.";
		done;
	    }
	    t < 1000 : {
		err = "Just enough tea.";
		done;
	    }
	    else : err = "Too much tea.";
	}

	// C-like switch
	switch (pies) {
	    0 : err = "There are no pies.";
	    1 : err = "There is one pie.";
	    2,3,4 : err = "There are between 2 and 4 pies.";
	    else : err = "There are more than 4 pies!";
	}

	finally {
	    self.setWidth(10);
	    self.setHeight(10);
	}

Note that using a guard-like "switch" as above (with a "done" after each
condition) is really just a convenient way to express what would be a bunch
of "if"/"else if" stuff in C.


(4) Cheating
[THIS WILL SOON GO AWAY -- REPLACE WITH EXPLANATION OF INS, DEL, KEYS.]

Arrays and hashes can sometimes act like objects, in that the "." operator
is used to access data members of the array or hash.  This is cheating, but
at least we're honest about it.

Arrays have the following members:
	size		number of elements in the array
	contains(x)	true if the scalar x is in the array
	search(x)	the first element number where x appears in the
			   array (0 if x is not in the array)
	rsearch(x)	the last element number where x appears in the
			   array (0 if x is not in the array)
	insert(n)	inserts a new member to the array, at index n (all
			   entries from n upward shift up one index)
	delete(n)	removes the array member at index n (all entries
			   from n upward shift down one index)

Hashes have the following members:
	getKeys()	array of key names
	getValues()	array of their corresponding values (the values will
			   always be in the same order as the keys)
	contains(x)	true if the key x has been stored in this hash
	search(x)	the name of one key that contains the value x (undef
			   if no keys contain the value x)

NOTE!  All array and hash functions operate on rvalues *only*.  This means
specifically that an array's insert(n) and delete(n) functions do not change
the state of an array variable -- they merely return new arrays that have
the intended effect.  Example:
	myArray.insert(1)		has no effect
	myArray = myArray.insert(1)	inserts new element to myArray at 1

Examples of cheating:
	x[] = [ "blue", "green", "white" ];
	if (x.contains("green")) {
	    x[x.size] = "cyan";		# an append operation!
	}
	x = x.delete(x.search("white"));

The array "size" member can be read or written to.  Changing the size of an
array may truncate or expand the array -- new entries are filled with undef.

The array member functions were chosen to make implementation of a simple
stack or queue trivial.
	x.push(i);	  ->	x[x.size] = i;
	i = x.pop();	  ->	i = x[x.size-1]; x.size--;
	x.enqueue(i);	  ->	x[x.size] = i;
	i = x.dequeue();  ->	i = x[0]; x = x.delete(0);
	x.undequeue(i);	  ->	x = x.insert(0); x[0] = i;


(5) Classes

"class" <name> [ "@" <domain> ] [ ":" <class> [ "@" <domain> ] ]
	[ "(" <class-attribute>	*( ";" <class-attribute> ) ")" ]
	"{" *( <class-member> ) "}"

Class attributes are:
	"is" <interface> *( "," <interface> )
	"from" <class> [ "@" <domain> ]
	"native"
	"exposed"

Statements (ie, code) can only be in functions (aka "methods"), and functions
can only be in classes.  (Function *declarations* can be in interfaces, but
full-fledged functions with code can only be in classes.)

Class names must be unique.  So to avoid namespace problems when you have
many clases, there are domains.  Class names only have to be unique within
a domain.  To change domains within a source file, the directive
	"domain" <name> ";"
is used.  A blank domain name ("domain;") returns you to the global domain.

Class name resolution first tries your current domain, then the global
domain.  You may specify a specific domain with "@", though, meaning that
a class name is composed of:
	<identifier> [ "@" <domain-name> ]

An exposed class is visible outside its domain; other classes are not.  The
engine behind the goo interpreter may place restrictions on a script's
ability to change domains or create classes inside some domains.  Typically
in a multi-user environment, there may be several "public access" domains,
and then one "private" domain per user.  Users may only instantiate or
subclass from the exposed classes in other users' domains.

A class may specify from zero to many interfaces in its class attributes.
Interfaces are explained later.

A class can be descended from another class (but only one class -- ie, 
single inheritance).  You can mark this descendancy using either the C++
style:
	class Child : Parent { ... }
or via the class attribute "from" (goo style):
	class Child (from Parent) { ... }

Here's sample code that creates a class "House" in domain Robey, then
subclasses it to "Condo" in the global domain:

	domain Robey;

	class House (exposed; is Dwelling) { ... }

	domain;

	class Condo (from House@Robey) { ... }

All classes in the global domain are exposed.  No ifs, ands, or buts.

A subclass contains all members of the original class, and automatically
contains any interface attributes that the previous class had.  (You may
re-state any of those interface attributes in the subclass, without
error -- however, they are already assumed.)

A class member is either a class variable, a function declaration, or a
function.

Within a single script, you may "import" classes from other domains.  For
example, if you are in domain "Robey" and you plan to make a lot of use of
class "Tree" from domain "Scott", you can import it.  The format of an
import directive is:
	"import" [<alias> ":"] <full-class-name> ";"
To import every exposed class from a domain, use:
	"import" <domain-name> ";"
After importing a class, for the length of that script, you may use just
the class name (without specifying domain) as a shortcut:

	domain Robey;
	import Tree@Scott;

	class Oak : Tree { ... }

Note that this does *not* create a class "Tree" in the Robey domain.  It's
more like an alias.  The goo parser will just mentally substitute
"Tree@Scott" whenever it sees "Tree" by itself.

If you would like to import a class from another domain, renaming it as you
import, you can do so:

	domain Robey;
	import Nut:Acorn@Scott;

	class MagicAcorn : Nut { ... }

That imports class "Acorn" from domain "Scott", but calls it "Nut".

You can declare a class before you define it, which in English means that
you can tell goo the class exists before you actually tell goo what's in
it.  For example:
	class Treehouse;
tells goo that you're going to define a class called "Treehouse" later.
This is useful when classes reference each other in a circle.  Compiler
nuts call this a "forward declaration".


(6) Class Variables

Class variables are declared just like local variables, but they can also
have special modifiers in front of them:

common		this var is shared between all objects of a class
		   (it's global across the class)
const		can't be changed once it's declared (implicitly common)
exposed		visible outside the class (the default is for all class
		   members to be invisible outside the class)
family		visible only to descendant classes
scrap		isn't part of an object's persistent state (doesn't
		   need to be written to disk)
obsolete	will soon be removed (see discussion below)

They can be combined any way you want.  You can also put modifiers in front
of a "block" of variables surrounded by "{" ... "}".  For example:
	exposed const {
	    PI = 3.14;
	    MAX = 50;
	}
The use of these modifier blocks is strongly encouraged for readability.

All class variables have to be declared in that class.  They can't be
created later on without reloading the class.  (Referencing an undefined
variable from within a function always creates a local variable -- never
a class variable.)

Note that class variables can't be defined ambiguously.  The definition
	x;
makes "x" a scalar -- not an array or hash.  The array "x" would be
defined in a class as:
	x[];
Thus, an initialization like
	x = [ 3, 4 ];
which is fine in code, is illegal in a class definition.  The actual class
definition would have to be
	x[] = [ 3, 4 ];
In other words, goo is very picky about variable types in class definitions.


(7) Function Declarations

Functions in goo can only exist as members of a class.  There is no "global"
class, and there are no "global" functions (though you can get pretty close
to "global functions" with common functions).

All of a class's functions must be declared inside that class.  The code
for the function may be placed there too (a coded function inside a class
counts as a declaration) but it doesn't have to be.

[ <modifier> ] "function" [ <classname> ] <identifier> [ "[]" | "{}" ]
	"(" [ <param-decl> ] *( "," <param-decl> ) ")" ";"

Valid modifiers are:
	common		this function may be called on the class as a
			   whole, and not just an instance of that class
	exposed		visible outside the class, to anyone
	family		visible only to descendant classes
	obsolete	can't be used by new code (see discussion below)

A parameter declaration is a variable declaration -- any valid variable
declaration is permitted as a function parameter.  These are all valid
function declarations:
	function foo(name);
	function foo(Tree t, weight);
	function foo(size=6);
	function foo(x=10, y=10, list[]=[3,4,5]);

Parameters may be initialized because it's possible to omit parameters
selectively (we'll get to that in a minute).  Parameters that are not
initialized will default to undef.

Unlike some languages like C++ and Java, only one function with a given
name may be declared -- regardless of what kind of parameters it has.
That is, you may not declare one function "foo" which takes a scalar
parameter, and another which takes a parameter of class Tree.  There
can only be one "foo" and it always has the same parameters.  This may
seem like a loss of flexibility, but named parameters end up giving
more flexibility in the end.

The return value from all functions is implicitly a scalar.  If a function
doesn't explicitly call "return" with some scalar value, it will return
undef.  You can specify that a function returns an array or hash instead
of a scalar:
	function foo[](name);
	function foo{}(weight);
You may also specify that it returns an object instead of a scalar:
	function Tree foo(name);
Or even an array or hash of objects:
	function Tree foo[](size);


(8) Function Definitions and Calls

A function's definition is complete once you associate code with it.  It's
an error to declare a function without ever giving code.  Defining a function
with its code is just a matter of giving a function declaration -- but
instead of ending it with a ";" you include a block of statements.

When calling a function, its parameters may be either positional or named.
Positional parameters behave just like C and most other languages.  For
example, if the function declaration is:
	function setCoke(calories, mL, flavor);
then a positional function call would look like this:
	setCoke(140, 355, "classic");
You may omit parameters, in which case the remaining parameters are set to
their default values when the function is called:
	setCoke(140);

Named parameters are not found in many languages.  This form of function
call allows you to switch the order of parameters or to selectively omit
certain parameters.  An example of a function call using named parameters
is:
	setCoke(calories:140, flavor:"classic");
Omitted parameters will be set to their default values.  Named parameters
can be extremely useful when a function declaration puts parameters in a
non-intuitive order, or when a function can take many different parameters
(with reasonable default values) and you only want to specify a few of them.

You may not use named parameters in combination with positional parameters
in the same function call.  Either all parameters must be named, or none
of them must be.  (Also, it's always an error to specify more parameters
than were listed in the function's declaration.)


(9) Interfaces

An interface is a class that can't be instantiated.  That is, you can't make
any objects out of an interface.  It's basically a class of function
declarations with no code, and no variable class members.  It provides an
"interface" of standard function declarations that a real class can
implement.

"interface" <name> [ "@" <domain> ] [ ":" <interface> [ "@" <domain> ] ]
	[ "(" <class-attribute>	*( ";" <class-attribute> ) ")" ]
	"{" *( <class-member> ) "}"

Interfaces can use all of the class attributes except "is".  Interfaces
may descend from other interfaces, but they may not implement them.

The advantage of interfaces is that they can be used to provide "masks" that
your class can wear to pretend to be other things.  For example:

class Toaster (is Appliance, Weapon) {
    ...
}

Any object of type Toaster can be passed to a function expecting a Weapon
or Appliance.  Since Weapon and Appliance are interfaces, they are only a
group of function declarations, so Toaster merely has to define each of
the functions listed in Weapon and Appliance.

You CAN declare an object as being an instantiation of an interface, but
you can't use "new" to create such an object.  It can be used to reference
an object that implements that interface.  For example, the following code
is valid:
	Toaster t = new Toaster;
	Appliance a = t;
But this code is not:
	Appliance a = new Appliance;

There are two cases where you may take a liberal interpretation of the
interface, listed below.  (Note that these restrictions and exceptions
also hold for a descendant class overriding a function defined in an
ancestor class.)

1. If an interface function defines a non-simple return type (ie. some kind
   of object is returned), you may implement the function by substituting
   a descendant class for the return type.  When your function is called,
   the return value will always be of the descendant class, not the original
   type.

   Example:
	interface Liquid {
	    function Object whatAmI();
	}

	class Coffee (is Liquid) {
	    function Coffee whatAmI();
	}

   Because you can transparently cast an object to one of its ancestor
   classes, this means that code that's unaware of the new "whatAmI"
   definition can still use the old definition without knowing it has
   changed:
	Liquid l = getCoffee();
	Object o = l.whatAmI();

2. You can add extra parameters to functions declared in an interface (but
   you can't omit any of the parameters that the interface declared).  When
   called from the interface, these parameters will have their default values
   (or undef, if you listed no default value).

   Example:
	interface Liquid {
	    function setHeat(tempC);
	}

	class Coffee (is Liquid) {
	    function setHeat(tempC, dissipationRate = 10);
	}

If you don't understand those two exceptions, you don't need to worry about
them.


(10) Creating Objects (Constructor)

A class's constructor is named after the class.  For example:

class Turtle {
    ...
    function Turtle(speed=15);
    ...
}

When an object is created with the "new" operator, the class's constructor
is called, if it exists.  (It's not an error for a class to have no
constructor.)  For example, to create a new object of class Turtle:

Turtle x = new Turtle;

This calls the constructor, using all default values.  If the constructor
has parameters, you can add them to the "new" operator just as if you
were calling the function directly:

Turtle x = new Turtle(20);

For readability, the use of named parameters is encouraged when using
constructors:

Turtle x = new Turtle(speed:20);

Unlike C++, goo does not allow multiple functions with the same name.  To
create a constructor that can have many possible initialization styles, then,
constructors tend to accept many possible parameters.  You can used named
parameters in the "new" operator to specify only the parameters you care
about.

By default, goo calls constructors in order from parent to child.  So if
you make a class Turtle descended from Reptile, the constructor for Reptile
is called before the constructor for Turtle.  This "hidden constructor call"
passes no parameters, so it behaves as if you called "new" on the parent
class with no paramters.  In order to pass parameters from the child's
constructor to the parent, you can use an explicit constructor call:

function Turtle(speed=15) : Reptile(legs: 4)
{
    ...
}

The explicit constructor (the part following the colon above) should look
just like a "new" call, without the "new".  It's treated somewhat as if
the first line of your constructor was a call to your parent's constructor,
except that you're both constructing the same object.  If this is confusing,
you probably don't have to worry about it.

A class is not required to have a constructor.  If no constructor exists,
goo will assume there's a constructor that does nothing but call the
parent's constructor (if there is a parent).

Because goo performs garbage collecting, no desctructor function exists.


(11) Exceptions

An exception is an error condition that causes a block of code to stop
executing prematurely.  You can cause an exception using "throw", which
can throw any value (object, scalar, etc).  The goo runtime can also cause
exceptions if things go wrong (like if memory runs out).  When an exception
has been thrown, each block of code is exited in reverse stack order, until
a block that "catches" the exception is found.  If no block catches the
exception, then the runtime will catch it after all the code blocks have
exited, and will print an ugly error message.

You catch an exception with a "catch" block.  For example:

{
    catch (BaseBall b) {
	x++;
    }

    x = 4;
    throw new BaseBall;
    x = 3;
}

The "catch" block acts like a "finally" block in that the code is set aside
for possible later use.  x is set to 4, and then a BaseBall is thrown.  The
"catch" block catches the BaseBall, incrementing x to 5, and then exiting
the block.  No statement after a "throw" is executed within a block, making
it similar to a "return" statement.  So for this example, x's final value
is 5.


(12) Overloading Operators

C++ style "operator overloading" is supported by goo, to a limited extent.
Operator overloading lets a class define how an operator works when an
object of that class is on the left side of the operator.  For example, if
you created a class ComplexNumber, you could define what happens when 
someone tries to add a scalar to a ComplexNumber.  Goo supports two ways
of doing this.  The C++ style is:

operator ComplexNumber +(x) { ... }

It looks a lot like a function, but the name of the function is "+".  It
takes one parameter, a scalar named "x", and returns a value of type
ComplexNumber.  The other way of defining an operator (goo style) is:

operator ComplexNumber (ComplexNumber + x) { ... }

This looks less like a function declaration, and more like what the operator
will look like when it's used.  Both styles are acceptable, and you can
intermix them -- C++ style is around for C++ hackers, because they're used
to it and they're set in their ways.  ;)

When you overload an operator like this, goo really just creates a function
for you.  Whenever anyone tries to use an operator on your class, goo checks
for a function that matches, and converts the operator into a function call.
So it's really just "syntactic sugar" to make code more readable.  An over-
loaded operator function can't have any modifiers, and is always exposed.

The following unary operators can be overloaded:
	#
The following binary operators can be overloaded:
	+ - * / % .. += -= *= /= %= ..= < > <= >= ~=
(This list may grow or shrink over time...)

An overloaded unary operator takes no arguments.  A binary operator takes
one argument: the right-hand side of the operator.  A C++ style of unary
operator overloading might look like this:

operator #() { ... }

(assuming it returns a scalar).  For unary operators, it is acceptable to
drop the parenthesis here, and just use:

operator # { ... }

The alternate (goo style) unary operator would look like this:

operator (#ComplexNumber) { ... }

(The goo style overload is always a representation of what the operator
would look like in an expression.)

You can create multiple functions that overload a single operator, but
take different types of arguments.  For example:

operator ComplexNumber (ComplexNumber + x) { ... }
operator ComplexNumber (ComplexNumber + ComplexNumber c) { ... }

When the operator is used, goo will choose the closest match.  Note that
the right-hand paramater must be 1-dimensional (can't be an array or hash),
and that the return value must also be 1-dimensional.


(30) Threads

There's some built-in support in goo for threads, though this can be
turned off by the engine.

(40) Persistent Objects

The goo interpreter stores all objects and class definitions on disk (or
possibly via some other method -- at the engine's discretion -- such as a
third-party database).  This is because goo is designed for a system that
will have a huge number of classes and objects, many more than could
possibly all fit into memory at once.

A certain amount of memory is allocated as a "memory cache" for the object
database.  If the memory cache is larger than the combined size of the
class definitions and objects, then everything can be stored in memory.
If not, ocassionally an object or class definition will be flushed to
disk.

All member variables of an object will be written out, except the ones
marked as "scrap".  Immediately prior to writing an object to disk, its
member function "_store()" will be called.  The base class has a default
_store() which doesn't do anything, but any class may override this function
if it wishes to do preparations before being written to disk.

When an object is referenced again, it will be loaded from disk if
necessary.  If the object is loaded from disk, the member function "_load()"
is called immediately after loading is finished.  This allows a chance to
re-create any scrap variables, or perform any other housecleaning that
needs to be done between loading the object and unleashing it into the
goo interpreter.


(41) Redefining a Class

You may redefine a class at any time (typically by loading a script which
redefines it).  If a class is redefined, all objects of that class are
converted to the new format.

Member variables which do not exist any more are erased, and any new
variables are set to undef.  (New arrays and hashes are set to the empty
array or the empty hash, respectively.)  Immediately after conversion,
the member function "_update()" will be called on any objects of that
class (or objects derived from that class).  This allows a class to
perform any conversions that may be necessary (typically, the initalizing
of new variables).

If an object is loaded from disk, and the class has been redefined since
the object was saved, the "_update()" function will be called first,
followed by "_load()".

However, goo will not let you load a class if non-hidden class members are
missing, and some other class uses it.  For example, if your class has a
function "setSize" which another class uses, you can't redefine your class
without including the function "setSize".  (The other class would get
confused if that function just vanished!)

You can avoid this problem by defining the function (or class variable) as
"obsolete".  Goo won't let any new code (including redefining of other
classes) use an obsolete class member.  In this way, you can leave a class
member around for older classes, but prevent new or redefined classes from
using it.  Eventually, no classes will be using your obsolete class member,
and goo will throw it away.  The next time you redefine the class, goo will
issue a warning message, telling you that the obsolete class member is no
longer used by anyone (so that you can remove the code).


(99) OO Weirdness

There are a couple of OO concepts that OO wizards know about (and sometimes
even care about!).  Here they are.

C++ VIRTUAL FUNCTIONS
All goo functions are what C++ would consider "virtual".  That means that
if you call a function of a descendant class which hasn't been overridden,
and the ancestor class makes another in-class function call, that function
call will be resolved with respect to the descendant class.

Gobbledy-gook!  Here's an example:

	class A {
	    function foo() { explode; }
	    function bar() { foo(); }
	}
	class B : A {
	    function foo() { implode; }
	}

If you call B.bar() it will resolve to the bar() in class A.  That bar()
calls foo().  Since the object belongs to class B, the foo() from B is
called, which causes an implosion.  In C++, you would have to declare foo()
as a virtual function to get that effect.  (C++'s default behavior is to
explode.)


INCOMPLETE FROM HERE ON
(to be continued)





(A) Reserved Words

undef, function, class, interface, is, domain, import, new, as
common, const, exposed, family, scrap, obsolete
if, else, while, foreach, for, switch, done, return
finally, throw, catch, in


(B) Goo Library Declarations

class Object {
    // called immediately after de-serializing from disk
    function _load();

    // called immediately prior to serializing to disk
    function _store();

    // called if the class has changed (if _load is appropriate too, this
    // is called first, then _load)
    function _update();

    // returns string name of this class
    common function getClassName();
}

class Stack {
    function push(Object o);
    function pop();
    function peek();
    function itemCount();
}

class Queue {
    function enqueue(Object o);
    function dequeue();
    function itemCount();
}

...also Iterator...