   Copyright (C) 2007 Mooneer Salem.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.2 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover Texts
     being "A GNU Manual," and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     "GNU Free Documentation License."

Kite
****

This manual is for Kite (version 1.0.4, 16 December 2008).

1 About Kite
************

Kite is a programming language designed with lightweight systems in
mind. On OS X Leopard, the main Kite library is only 88KB, with each
package in the standard library weighing in at 13-30KB. Besides size
considerations, the design philosophy is that of minimalism-only
include the minimum necessary, while giving developers the power to
write anything that they can write in any other language. With that in
mind, we aim to put up the fewest roadblocks to development out of most
other languages.

2 Invoking Kite
***************

2.1 Normal invocation
=====================

To see what command line arguments are available, use the -h flag. It
will produce something similar to the following:

     harry:trunk mooneer$ kite -h
     This is kite, version 1.0a1 (built on i386-apple-darwin9.1.0)
     Copyright (C) 2007 Mooneer Salem

     Usage: kite [-h|-v] [file]
           -v: Print version information
           -h: This message
       [file]: File to execute or run (optional). If not specified, defaults to
               standard input.

   To run a Kite application, simply include the filename as an
argument:

     harry:trunk mooneer$ kite test.kt
     Hello, world!
     harry:trunk mooneer$

   Not including a filename will cause Kite to take the program from
standard input:

     harry:trunk mooneer$ kite
     "Hello, world!"|print()
     ^D
     Hello, world!
     harry:trunk mooneer$

2.2 The Kite Debugger (`kdb')
=============================

Kite has a built-in debugger for user-written code, called `kdb'. To
execute it, pass `kdb' the name of your program:

     harry:trunk mooneer$ kdb test.kt
     Break at file test.kt
     1: "Hello, world!"|print;
     >

2.2.1 Available commands
------------------------

While in `kdb', the following commands are available:

`eval [code]'
     Compiles the given code and evaluates it in the current context.
     The return value is output to standard output.

`exit'
     Exits the application.

`clear [file]:[line]'
     Clears breakpoint at the file `[file]' line `[line]'.

`break [file]:[line]'
     Sets breakpoint at the file `[file]' line `[line]'.

`step'
     Steps through one line of code.

`next'
     Steps through one line of code, executing any methods called by
     the current line.

`cont'
     Continues execution until the next breakpoint.

`ev [code]'
     Synonym for `eval'.

`ex'
     Synonym for `exit'.

`cl [file]:[line]'
     Synonym for `clear'.

`b [file]:[line]'
     Synonym for `break'.

`s'
     Synonym for `step'.

`n'
     Synonym for `next'.

`co'
     Synonym for `cont'.

3 Kite Language Specification
*****************************

3.1 Syntax
==========

Kite has a simple, functional syntax, similar to other object-oriented
languages.

3.1.1 Basics
------------

3.1.1.1 General
...............

All statements in Kite end with a semicolon. For instance:

     "Hello world"|print;

   Whitespace also does not matter, for the most part. `"hello world" |
print ;' is equivalent to the first line above. Brackets are used to
delineate blocks.

3.1.1.2 Representation of Built-In Types
........................................

Numbers are represented as in other languages (integers have no
periods, while floating-point numbers have one). Strings are surrounded
by double quotes, and have the normal escapes:

`\n'
     Newline

`\r'
     Carriage return

`\\'
     Literal "\"

`\"'
     Literal "

`\t'
     Tab

`\b'
     Backspace

`\f'
     Form feed

`\[0-7][0-7]?[0-7]?'
     ASCII character, represented in octal

`\x[0-F][0-F]?'
     ASCII character, represented in hexadecimal

   Strings can also span multiple lines without the need for any escape
character.  Lists are surrounded by `[' and `]' characters, with each
element separated by commas: `[1,2,3]'. All built-in types are
immutable, except for lists. Boolean values are `true' and `false' (for
true and false, respectively).

   As of 1.0b8, it's also possible to specify a range of integers by
using the following construct: `from:to(:step)'. This will instantiate a
System.math.range object (see kdoc documentation) that represents all
the numbers from one integer to another (possibly skipping numbers
along the way).

   Regular expressions are also built-into the language syntax as of
1.0.1. Regular expressions begin with "r/" and end with either "/"
(case-sensitive) or "/i" (case-insensitive). This is equivalent to
creating a new System.regex object with the appropriate parameters.

3.1.2 Declarations
------------------

3.1.2.1 Required Version
........................

A module can specify the minimum required version in order to run. This
can be done by using the `version' keyword, as shown below:

     version "1.2.0";
     "hello world"|print;

   If a user attempts to run the above code on a version of Kite lower
than 1.2.0, an exception will be thrown. The minimum supported version
that can be specified here is 1.0.0. Only two of the version components
are required-the third one will default to being 0 if not specified:

     version "1.2";
     "hello world"|print;

3.1.2.2 Classes
...............

The class is the fundamental unit in Kite. All objects, whether
built-in or user-created, are instances of classes. To declare a class,
use the `class' keyword:

     class Hello from System.object [
        ...
     ];

   The `from System.object' is optional, as all classes inherit from
System.object by default. If specified, your class will inherit from
the class specified. This allows for single inheritance:

     class Greetings [
         ...
     ];

     class Hello from Greetings [
         ...
     ];

   All declarations inside of a class are delimited by commas, instead
of semicolons.

3.1.2.3 Properties/variables
............................

Properties and variables are the same in Kite. To declare, use the
`property' keyword:

     class Greeting [
         property text,
         global property number_given
     ];

     property desired;

   `global' is an optional keyword that goes before `property' that
indicates that the property is to be shared amongst all instances of
the class. This is equivalent to static members in C++ and similar
languages.

   Properties can also have a value assigned to them on first creation,
as seen here:

     class Greeting [
         property text = "Hello!",
         global property number_given = 1
     ];

3.1.2.4 Methods
...............

Methods work in a similar way as in other languages, and are declared
using the `method' keyword:

     class Hello from Greeting [
         method sendGreeting(string) [
             string|print;
         ];
     ];

     method greetings() [
         (make Hello())|sendGreeting("hello");
     ];

   Unlike in other languages, there is no concept of static vs.
instance methods; however, `this' will be set to the class object
inside of methods called without an instance and not called inside of a
class. Methods can take any number of parameters, and method
overloading is possible:

     class Hello from Greeting [
         method sendGreeting() [
             this|sendGreeting("hello");
         ],
         method sendGreeting(greeting) [
             greeting|print;
         ]
     ];

   The return value of any method is the return value of the last
executed statement in the method. In the example above, sendGreeting()
will return whatever print returns.

   Anonymous methods are also possible, by removing the method name from
the declaration. Example:

     x = method(a) [
         (a + 1);
     ];
     (x(1))|print;

   Any references to variables/properties inside a method call will
search for the property down the call stack. That is, `x' inside the
method will change the declaration outside the method unless a
`property' declaration is included:

     property x;
     method y() [
         x = 3;
     ];

     x = 2;
     x|print;
     y();
     x|print;

   To exit out of a method early, simply use the `return' keyword:

     method x(y)
     [
         return;
         "should not reach here"|print;
     ];
     x(1);

3.1.2.5 Operators
.................

Kite also supports operator overloading using the `operator' keyword.
Overloadable operators are below:

`plus'
     Addition (+)

`minus'
     Subtraction (-)

`multiply'
     Multiplication (*)

`divide'
     Division (/)

`mod'
     Modulus (%)

`unplus'
     Unary plus (+)

`unminus'
     Unary minus (-)

`map'
     Map (<-)

`reduce'
     Reduce (<|)

`array'
     Array dereference ([])

`array_set'
     Array set ([]=)

`lt'
     Less than (<)

`gt'
     Greater than (>)

`leq'
     Less than or equal to (<=)

`geq'
     Greater than or equal to (>=)

`and'
     Logical/bitwise AND (and)

`or'
     Logical/bitwise OR (or)

`not'
     Logical/bitwise NOT (not)

`xor'
     Logical/bitwise XOR (xor)

`lshift'
     Left shift (<<)

`rshift'
     Right shift (>>)

`call'
     Method call. *Caution:* the array passed in as the argument
     contains the method name for the first element (as a string) and a
     list containing the arguments as the second element. This operator
     is also called only if said method does not exist.

   All operator methods above only take a single argument, the right
hand side of the operation (if any). For the unary operators, this
argument will be `null'. The left hand side is always `this'. Example:

     class Widget [
         property number,
         operator add(rhs) [
             property ret;
             ret = make Widget;
             ret.number = this.number + rhs.number;
             ret;
         ]
     ];

3.1.2.6 Constructors and Destructors
....................................

Constructors and destructors are created using the `construct' and
`destruct' keywords:

     construct (param1, param2, ...) [
         ...
     ];
     destruct [
         ...
     ];

   Constructors can also be overloaded, as appropriate. To call a base
class's constructor, use `base|__construct__(...)' (base also works in
any class method to call parent's version of said method). Any return
value from the constructor is ignored.

3.1.2.7 Package importation
...........................

Packages are imported using the `import' keyword, with the name of the
package in quotes:

     import "System.vm.thread";

   Each component of the package is separated by a period and
corresponds to an element of the path (see Extending Kite for more
information).

   *Caution:* `import' instructions are executed before any other code
is run.  This can interfere with proper operation if the package you're
looking for is not in the standard Kite lookup path. Use `eval' (see
Dynamic code evaluation) as a workaround.

3.1.3 Object creation
---------------------

3.1.3.1 Explicit creation
.........................

Objects are created using the `make' keyword:

     var = make Class(param1, param2, ...);

   `make' returns the object itself, which can be used in method calls.
The parameters passed into `make' will be passed to the constructor.

   *Please note:* As of 1.0a2, parent class constructors are not called
(but any constructors in the given class matching the number of
parameters are). Constructors that need to call parent constructors can
use `parent|__construct__(...)', where `parent' is the name of one of
the parent classes.

3.1.3.2 Implicit creation
.........................

Objects are implicitly created when operators are run upon them (for
instance, adding two numbers). The supported operators are listed under
the Operators section above.

3.1.3.3 Map/Reduce
..................

Kite has built-in support for the map and reduce operators (`<-' and
`<|', respectively). Map applies a method to each element of an object
(by default, any object that implements the iterator methods), while
reduce constructs a single new object from another object using a
method. For example:

     method mapping(a) [
         (a + 1);
     ];
     method reducing(a, b) [
         (a + b);
     ];

     ([1,2,3]<-mapping)|print;
     ([1,2,3]<|reducing)|print;

   which outputs:

     [2,3,4]
     6

3.1.4 Method calls and dereferencing
------------------------------------

Unlike in other languages, there is a syntactic difference between
dereferencing an object and calling a method on an object. The dot
(`.') operator dereferences a class and returns the contents:

     x = class.property;

   The pipe (`|'), on the other hand, dereferences the method and then
calls it with the arguments and object given:

     x|doWork();

   Any arguments passed to the method are within the parenthesis (which
are optional if no arguments are being passed). For methods not defined
in a class, the parenthesis *are* required for Kite to determine
whether you want the method object or to call the method.

   Inside of a class, if you wish to call the version of a function
that is inside a parent class, you may do so by prepending the parent
class's name. For example:

     class a [
         method x() [ ... ]
     ];

     class b from a [
         method x() [ ...; a|x(); ... ]
     ];

     y = make b();
     y|x;

   The special `__construct__' method can also be used to reference
parent (or your own) constructors.

3.1.5 Documentation strings
---------------------------

Kite has built-in support for documentation strings.

3.1.5.1 How to write
....................

Documentation strings begin with /[ and end with /]. The string can
span multiple lines. Example:

     /[Top of file]/

     class Test /[A class.]/ [
         property prop /[A property.]/,

         construct() /[A constructor.]/ [
             ...
         ],

         destruct() /[A destructor.]/ [
             ...
         ],

         operator plus(rhs)
         [
             ...
         ],

         method x(
             arg /[A method argument.]/
         ) /[A method.]/
         [
             ...
         ]
     ];

3.1.5.2 Generating documentation
................................

To generate documentation, use `System.doc|generate_doc()':

     import "System.doc";
     import "your.package";

     out = make System.doc.outputters.html_outputter();
     doc = System.doc|generate_doc(your.package);
     doc|output(out);

   An example of kdoc documentation (generated from System.doc) can be
found at http://www.kite-language.org/kdoc-test/System.doc.html.

3.1.5.3 Supported constructs
............................

The following constructs can have documentation strings:

   * Beginning of files

   * `class'

   * `property'

   * `method'

   * `construct'

   * `destruct'

   * method arguments

   * `operator'

3.1.6 Object type determination
-------------------------------

The type of an object can be surmised in several ways:

   * `object|type'

   * `is'/`isof' operators

3.1.6.1 `object|type'
.....................

Every object contains a method called `type'. This method returns the
name of the class as a string. This example will return `System.string'
as the output:

     x = "string";
     x|type|print;

3.1.6.2 `is'/`isof' operators
.............................

The other method is through the use of the `is'/`isof' operators. The
difference between the two is how far they search. `is' only determines
if the current instance is of type `x', while `isof' determines whether
the current instance is of type `x', or any child class of `x'. Example:

     import System.string;
     class x from System.string [
     ];

     ((make x) is x)|print;
     ((make x) is System.string)|print;
     ((make x) isof x)|print;
     ((make x) isof System.string)|print;

   returns the following:

     true
     false
     true
     true

3.1.7 Decisions
---------------

Kite uses the `decide' construct (analogous to C/C++'s `switch'
statement) to allow developers to conditionally execute code. Example:

     decide [
         condition1 [ ... ],
         condition2 [ ... ],
         ...
         true       [ ... ]
     ];

   Each condition is separated by a comma, where condition is any
statement that evaluates to a Boolean value. `true' is used to denote
code that should be executed when none of the other conditions match.
Each condition is evaluated one-by-one, with the rest short-circuited
once the first matching condition is found (no falling through like in
C/C++).

3.1.8 Loops
-----------

Kite has two types of loops: `while' and `until'. `while' loops execute
code _while_ the condition evaluates to `true', while `until' loops
execute code _until_ the condition evaluates to `true':

     i = 0;
     while (i < 10) [
         i = i + 1;
     ];
     until (i == 0) [
         i = i - 1;
     ];

   To break out of the loop early, use the `break' statement. To jump
back to the top of the loop, use `continue'.

3.1.9 Exceptions
----------------

Kite supports exceptions through run/catch:

     run [
         ...
     ] catch [
         ...
     ];

   When Kite throws an exception, control passes to the first statement
within the catch block. The exception itself is placed in the `__exc'
variable. To throw an exception, the
`System.exceptions.exception|throw' method is used. This method is
implemented by all exceptions.

3.1.10 Dynamic code evaluation
------------------------------

Kite supports the `eval' construct, which allows one to dynamically
execute code:

     eval "\"Hello, human.\"|print";

   The parameter after `eval' can be any valid Kite construct that
evaluates into a string. Of course, an exception will be thrown if the
string cannot be parsed.

3.2 Standard Library
====================

The Kite standard library consists of several important libraries. All
of these libraries should be part of an implementation of Kite.

   The documentation for these can be generated by executing:

     import "System.doc";
     out = make System.doc.outputters.html_outputter();
     doc = System.doc|generate_doc(__root);
     doc|output(out);

   You can also view the documentation online by going to
http://www.kite-language.org/docs/kdoc-[version]/__root.html, where
[version] is the version of your copy of the interpreter (starting from
1.0b4 on).

4 Extending Kite
****************

There are two ways to extend Kite: write your own classes/packages and
writing your own compiled extensions.

4.1 Kite Packages
=================

To write a package, it is a simple matter of saving your classes and
other code in a file with the `.kt' extension. For example, here is a
simple package:

     #!/usr/bin/kite

     class Greeting [
         property text,
         method sayGreeting() [
             text|print;
         ]
     ];

     class Hello from Greeting [
         construct [
             this.text = "Hello!";
         ]
     ];

     class Hola from Greeting [
         construct [
             this.text = "¡Hola!";
         ]
     ];

   We shall call this Greetings.kt. Now, where should this be placed?
We know that greetings fall under common sayings, so let's place this
in the CommonSayings folder. Now, the package can be referenced by
using `import CommonSayings.Greetings' in any Kite application. Let's
try it:

     #!/usr/bin/kite

     import "CommonSayings.Greetings";
     greetings = CommonSayings.Greetings;

     english = make greetings.Hello;
     spanish = make greetings.Hola;

     english|sayGreeting;
     spanish|sayGreeting;

   Assuming that your folder structure looks like this:

     ./CommonSayings/
     ./CommonSayings/Greetings.kt
     ./test.kt

   Running `kite test.kt' will produce:

     Hello!
     ¡Hola!

   Easy enough, but what if your package isn't in the current Kite
search path? You'll have to use something like this to fix that:

     #!/usr/bin/kite

     import "System.vm.loader";
     System.vm.loader.searchPath = System.vm.loader.searchPath + ":/path/to/package";
     greetings = System.vm.loader|loadClass("CommonSayings.Greetings");

     english = make greetings.Hello;
     spanish = make greetings.Hola;

     english|sayGreeting;
     spanish|sayGreeting;

   Now, it'll work as intended.

   *Caution:* `import' will only load a class once during runtime. If
you need to reload the package for any reason, you'll currently need to
restart Kite. (This is on the TODO for future releases.)

4.2 Compiled Extensions
=======================

Compiled extensions are the second route to extending Kite. There are
two routes to doing this: native extensions and using the
`interface.language.c' class.

4.2.1 Native Kite extensions
----------------------------

Native Kite extensions allow a user to write a Kite module in the C
programming language (or any language that can export a C interface).
This is useful for those that require extra speed, or to add support
for libraries and modules that were originally written in C or other
programming languages.

4.2.1.1 A Simple Example: Greeting in C
.......................................

Here is a simple example of a Kite module in C. We want to have a
method called "write" that outputs a greeting to the user on standard
output. Let's create a file called "greeting.c" with the following
lines:

     #include <stdio.h>
     #include <stdlib.h>
     #include <kite_object.h>

   kite_object.h is mandatory in order to use Kite language features.
Now, we need to write the method. We'll call it Greeting_write,
although it can be called anything:

     KITE_CLASS_METHOD(Greeting_write)
     {
         KITE_NO_ARGS;
         KITE_THIS_NOT_USED;
         printf("Hello, world!\n");
         kite_vm_return(thd, kite_new_null(thd));
     }

   `KITE_NO_ARGS' and `KITE_THIS_NOT_USED' are helper macros designed
to remove spurious compile warnings. `kite_vm_return' is how we return
values to the user; all code generally returns some value, even if it's
simply null. As you can see, this method simply writes a message to
standard output.

   Now we need to let Kite know of this method and the object. We'll
set up an initializer function, as shown here:

     KITE_MODULE_INITIALIZER(greeting)
     {
         kite_object_t *inherits =
             kite_dereference_and_load(thread, "System.object");
         kite_object_t *newclass =
             kite_new_class(thread, inherits, "greeting");
         kite_set_docstring(newclass, "Output greeting to user.");

         kite_add_method(thread, newclass, "write",
             kite_new_method_compiled_with_docs(thread, Greeting_write,
                                       "Write greeting to user.", 0));

         /* Add to parent to complete loading. */
         kite_add_property(thread, parent, "greeting", 1, NULL);
         kite_set_property(thread, parent, "greeting", newclass);
     }

   The code above creates a new class that inherits `System.object' and
contains one method called "write" that takes no arguments. It then
adds the class to the parent class, which in this case, is the root
class.

   Now that we've written our object, we need to compile it. On Linux,
we can do the following:

     gcc -shared -I/usr/local/include -fPIC -g -o greeting.so greeting.c

   and write some Kite code to test:

     import "greeting";
     greeting|write;

   Now, when we run Kite on the test code, we'll get:

     $ kite test.kt
     Hello, world!
     $

4.2.1.2 For Further Information
...............................

If you have Doxygen (http://www.stack.nl/~dimitri/doxygen/), you can
generate documentation for all of the Kite internals by running
`doxygen Doxyfile' from the top of the distribution.  It should place
HTML and LaTeX files in `docs/html' and `docs/latex', respectively. A
version of the Doxygen documentation can also be found here
(http://www.kite-language.org/docs/).

4.2.2 Using `interface.language.c'
----------------------------------

*Please note:* This method only works on platforms supported by
C/Invoke (http://www.nongnu.org/cinvoke/).  At this writing (July
2008), the supported platforms are Windows (32-bit Intel), OS X (PPC
and Intel) and Linux/*BSD (32 and 64-bit Intel).

   `interface.language.c' is a module that allows one to interface with
compiled modules on his or her system. No experience with C/C++ or Kite
internals is necessary.

   Here is a simple example of using `interface.language.c':

     import "interface.language.c";

     libr = make interface.language.c("libm.dylib");
     libr|add_method(
     	"cos",
     	interface.language.c.param_types.double,
     	[interface.language.c.param_types.double]
     );
     libr|cos(0.0)|print;

   (the example prints "1.00000")

   Structures and callback functions are also supported. Here is a
longer example that implements both.  First, we'll create a quick and
simple dynamic library called libtest. Here are the contents of
libtest.c:

     #include <stdio.h>

     struct xyz
     {
         char *name;
         int val;
     };

     void print(struct xyz *ptr, int x, void(*ptr)(int))
     {
         printf("name = %s, value = %d\n", ptr->name, ptr->val);
         (*ptr)(x);
     }

   To compile on Linux: `gcc -shared -fPIC -g -o libtest.so libtest.c'.
Now here is the Kite code necessary to access our new module:

     import "interface.language.c";

     lib = make interface.language.c("/tmp/libtest.so");

     st = make interface.language.c.c_struct(
     	lib,
     	[
     		["name", interface.language.c.param_types.string],
     		["val", interface.language.c.param_types.int]
     	]
     );

     inst = st|make_instance;
     inst|name("test");
     inst|val(123);

     cb = make interface.language.c.c_callback(
         lib,
         interface.language.c.param_types.void,
         [interface.language.c.param_types.int],
         method(extra, x) [
             x|print;
         ],
         null
     );

     lib|add_method(
     	"print",
     	interface.language.c.param_types.void,
     	[
     	    interface.language.c.param_types.pointer,
     	    interface.language.c.param_types.int,
     	    interface.language.c.param_types.pointer
     	]
     );

     lib|print(inst|pointer, 31415, cb|pointer);

   This results in:

     name = test, value = 123
     31415

   More information on interface.language.c can be found in the kdoc
documentation (http://www.kite-language.org/docs/) for the current
version.

4.3 Embedding Kite In An Application
====================================

Kite can also be embedded into a compiled application. As with creating
a compiled module, you'll first need to include kite_object.h:

     #include <kite_object.h>

   In order to access Kite, you'll need to create a new virtual
machine. Virtual machines are the fundamental unit that represents a
single instance of the Kite interpreter. These can be created using the
`kite_new_vm' function. Let's do that now inside of our main():

     int main(int argc, char **argv)
     {
         kite_vm_t *vm;

         kite_app_init();
         vm = kite_new_vm(argv);
         ...
         kite_free_vm(&vm);
         return 0;
     }

   Also note that you'll need to call `kite_app_init()' before using
any Kite functions.  This is necessary to initialize the garbage
collector, for those versions of Kite compiled with Boehm GC support.

   `kite_new_vm' requires a single argument, a pointer to an array of
strings. This represents the command-line arguments passed into Kite at
the command prompt; passing argv should work fine.  You'll also notice
that we delete the virtual machine after we've finished using it by
using the `kite_free_vm' function. This function sets the VM object to
NULL on completion.

   At this point, we have a virtual machine object, but it's not
currently doing any useful work.  We'd like it to run some code for us.
To do that, we'll need to compile some code:

     kite_thread_t *thd = kite_vm_creator_thread(vm);
     kite_object_t *obj = kite_vm_compile_from_string(thd, "42|print;", 1);

     if (thd->exception)
     {
         /* Uh oh. */
         exit(-1);
     }

   `kite_vm_creator_thread' above returns the very first thread created
by the virtual machine.  This will usually be the thread that initially
runs any code you write. `kite_vm_compile_from_string' is one of the
functions that can be used to compile code. This compiles a snippet of
code into a Kite object and returns the object. Errors start from line
1. Other compile methods exist as well, including ones that compile
from a file.

   To ensure there are no errors, we check for the existence of an
exception object in `thd->exception'.  If this property is NULL, code
we've run did not throw an exception. Also, most functions will return
FALSE or NULL on error.

   Since we now have a compiled form of the Kite code we've entered
above, we can run it. To do that, we can call `kite_start_bytecode':

     kite_start_bytecode(thd, obj);
     if (thd->exception) ...

   The return value from executed Kite code, if any, is on the top of
the running stack. This can be retrieved by using `kite_vm_pop()', but
we'll ignore it for our example. To make sure everything's cleaned up,
we should wait for our thread to terminate:

     kite_dereference_object(obj);
     kite_join_thread(vm, thd);

   `kite_dereference_object()' is an important function when it comes
to Kite memory management. It decrements the reference count of a given
object, and when the reference count reaches zero, it is scheduled for
deletion. The destructor is generally called when this occurs. If you
need to pass references to Kite objects around, you should always
increment the reference count by using the analogous
`kite_reference_object()' function.

   Your file should now look like this:

     #include <kite_object.h>

     int main(int argc, char **argv)
     {
         kite_vm_t *vm;
         kite_thread_t *thd;
         kite_object_t *obj;

         kite_app_init();

         vm = kite_new_vm(argv);
         thd = kite_vm_creator_thread(vm);
         obj = kite_vm_compile_from_string(thd, "42|print;", 1);

         if (thd->exception)
         {
             /* Uh oh. */
             exit(-1);
         }

         kite_start_bytecode(thd, obj);
         if (thd->exception) exit(-1);

         kite_dereference_object(obj);
         kite_join_thread(vm, thd);

         kite_free_vm(&vm);
         return 0;
     }

   Compile in Linux using something like this:

     gcc -g -L/usr/local/lib -I/usr/local/include -lkite -fPIC -o example example.c

   and run like this:

     $ ./example
     42
     $

   And there you have it!

4.4 Distributing Packages
=========================

As of 1.0.2, there is now an automated method of building Kite packages
called kpkg. A kpkg package is a gzipped tar file containing a file
called kpkg.kt and one or more source files.  Here is an example of
what a typical kpkg.kt could look like:

     #!/usr/bin/kite

     import "System.package.builder";
     from System.package.builder;

     this.options = make System.package.builder.builder_options();
     this.options.package_name = "greeting";
     this.options.package_version = "1.0.0";
     this.options.module_depends|set("greeting", ["interface.http"]);

     this.options.libraries_built << "greeting";
     this.options.library_files|set("greeting", ["greeting.c"]);

     this.options.libraries_built << "greeting.foreign";
     this.options.library_files|set("greeting.foreign", ["foreign.kt", "spanish.kt", "german.kt"]);

     this.options.libraries_built << "greeting.domestic";
     this.options.library_files|set("greeting.domestic", ["domestic.kt", "midwest.kt", "south.kt", "northeast.kt"]);

     this.options.custom_pre_build_rules << method(options) [ "A pre-build example."|print; true; ];
     this.options.custom_post_build_rules << method(options) [ "A post-build example."|print; true; ];

     System.package.builder|process_builder(this.options);

   The important thing to remember about kpkg.kt is that it is a
derived class of System.package.builder, which is what actually does
the package build. It handles all command-line options and builds
compiled or native Kite modules based on what options are written into
the file. For packages that need specific configuration (such as shared
library locations), it is also possible to specify compile flags and
linker flags for each file and module, as well as custom build and
install rules. The full list of possible configuration properties can
be found in the kdoc documentation for
System.package.builder.builder_options.

   To build such a package, simply uncompress and untar the tarball and
run "kite kpkg.kt build". If successful, a "sudo kpkg.kt install" will
install the package into Kite's default package directory.  If for some
reason you need to install the package in a different directory, then
defining the KPKG_DESTDIR environment variable before running kpkg.kt
install will copy the package to the directory given instead of the
Kite default.

   kpkg.kt also specifies other options. To find out what those are,
simply run kpkg.kt with no arguments.

4.5 Additional Information
==========================

For more information on the kinds of functions available to you, see
the documentation for the Kite API
(http://www.kite-language.org/docs/), especially kite_object.h and
kite_vm.h.

5 Additional help
*****************

There are several ways to get help with Kite.

5.1 By IRC
==========

Kite developers and users alike are on the Freenode IRC network
(irc.freenode.net) in channel #kite. This is the preferred place to get
help with issues related to development in the language. Note that it
may take anywhere from a few minutes to a few hours to get a response,
depending on the time of day of the inquiry.

5.2 By email
============

Email is the preferred contact method for bug reports and questions
that cannot be answered on IRC. The email address to use is
`bugs@kite-language.org'.

Appendix A GNU Free Documentation License
*****************************************

                      Version 1.2, November 2002

     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it
     can be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You
     accept the license if you copy, modify or distribute the work in a
     way requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.  If a section does not fit the above definition of
     Secondary then it is not allowed to be designated as Invariant.
     The Document may contain zero Invariant Sections.  If the Document
     does not identify any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup, or absence of
     markup, has been arranged to thwart or discourage subsequent
     modification by readers is not Transparent.  An image format is
     not Transparent if used for any substantial amount of text.  A
     copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML, PostScript or PDF designed for
     human modification.  Examples of transparent image formats include
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
     can be read and edited only by proprietary word processors, SGML or
     XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML, PostScript or PDF
     produced by some word processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a computer-network location from
     which the general network-using public has access to download
     using public-standard network protocols a complete Transparent
     copy of the Document, free of added material.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section Entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the
          section all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.2
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.