Using the Simple ECMAScript Engine

# Using SEE, the Simple ECMAScript Engine

by David Leonard, 2006
for SEE version 3.0

The impatient may want to jump straight to the §4.1 code example.

## Table of contents

## Introduction

The Simple ECMAScript Engine ('SEE') is a parser and runtime library for the popular ECMAScript language. ECMAScript is the official name for what most people call JavaScript:

> [ECMAScript] is based on several originating technologies, the most well known being JavaScript (Netscape) and JScript (Microsoft). The language was invented by Brendan Eich at Netscape and first appeared in that company's Navigator 2.0 browser. It has appeared in all subsequent browsers from Netscape and in all browsers from Microsoft starting with Internet Explorer 3.0. (ECMA-262 standard, 1999)

SEE fully complies with ECMAScript Edition 3^,^, and to JavaScript 1.5^. It has compatibility modes that allow it to run scripts developed under earlier versions of JavaScript, Microsoft's JScript and LiveScript.

This documentation is intended for developers wishing to incorporate SEE into their applications. It explains how you can use SEE to:

- manage multiple, separate ECMAScript runtime environments,
- evaluate instances of user-supplied ECMAScript program text, and
- expose your application's objects to those programs.

This documentation does not explain the ECMAScript language, nor discuss how to build the library on your system.

SEE includes an example application, called see-shell which allows interactive use of the interpreter, and demonstrates how to write host function objects.

### Document conventions

I will use the phrase host application to mean your application, or any application that uses the SEE runtime environment auxillary to some primary purpose. Examples of a host application are web browsers and scriptable XML processors.

Throughout this documentation, references are made to the C functions and macros provided by the SEE library. To avoid definitional redundancy and to improve precision, the reader is encouraged to examine the SEE header files to find the precise definitions and arguments of each function or macro. Signatures for C macros are given, but you should understand that the compiler cannot normally typecheck your use of those macros.

Where literal C code is used, it is typeset in a monospace font, like this:

    if (failed) { abort(); } /* comment */

Similarly, ECMAScript code is typeset in a sans serif font, like this:

    window.location = "about:blank";

Important parts of exammple code are `highlighted`, and elided code is indicated with an elipsis, like this: `...`

Function definitions listed in the name index appear in green, like this: `SEE_example()`

⚠ Note: Notes of caution appear in boxes like this.

Short examples of usage appear in green boxes, like this:

Example: Demonstrating intended or expected usage through code snippets:

    cut() && paste(); /* as required */

The term ASCII in this document refers to character codes in the decimal range 0 through 127, inclusive.

## 1 Requirements

Compiling SEE requires an ANSI C compiler. Although the SEE library is essentially self-contained, it does depend on you (the host application developer) providing the following:

an IEEE 754 floating point type and a math library
  Most modern compilers have this, but if you are developing for some obscure architecture, you should check.
a garbage-collecting memory allocator
  The free Boehm gc is highly recommended (See also §3.2).

SEE uses scripts from GNU autoconf to determine if these are available, and also to determine other system-dependent properties. Host applications should `#include <see/see.h>` to access all the macros and functions prototypes.

(As a developer you may find the need to edit header files and configure scripts to make SEE compile on your system. I would be interested in hearing what changes were needed so that future releases can supply this automatically for other users. Please send mail to leonard@users.sourceforge.net.nospam.)

## 2 Creating interpreters

After having initialised the library with a call to `SEE_init()`, the first step in executing an ECMAScript program is to create an interpreter instance. Each interpreter instance represents an execution context and global variable space. When created, an interpreter is initialised with all the standard ECMAScript objects such as `Math` and `String`. Modules may add other objects (see §7).

First, the host application should allocate storage for a `struct SEE_interpreter` and then call `SEE_interpreter_init()` to initialise that structure.

    void SEE_interpreter_init(struct SEE_interpreter *interp);

A pointer to the initialised `SEE_interpreter` is required for almost every function that SEE provides. The pointer is conventionally named `interp`.

Example: Where storage has been allocated for the interpeter structure on the stack, and consequently the interpreter exists only until the function returns.

    void
    example()
    {
        struct SEE_interpreter interp_storage;

        SEE_interpreter_init(&interp_storage);
        /* Now the interpreter is ready for use */

        /* Because the interpreter storage is on the stack, it
         * will be garbage collected after this function returns.*/
    }

There is no mechanism for explicitly destroying an initialised interpreter; instead, SEE relies on the garbage collector to reclaim all unreferenced storage (see §3).

### 2.1 Multiple simultaneous interpreters

SEE supports multiple, simultaneous, independent interpreter instances. This is useful, for example, in an HTML web browser application, where each window may need its own interpreter instance because the variables and bindings to built-in objects must be different and separate in each one.

SEE's functions are not thread-safe within the same interpreter, but multiple different interpreters can be safely used by different threads without collision. This is because global data structures used by SEE are marked immutable when the first interpreter is initialised. Interpreters remain completely independent of each other only if the application:

- never passes an object or mutable string reference obtained from one interpreter to the other, and
- uses a thread-safe (or interpreter-dependent) memory allocator.

Strings generated from one interpreter, can be exported for use in another interpreter by using the `SEE_string_fix()` function (See §5.3).

If you need to allow multiple threads to call into the interpreter, but in a serialized manner (which you must enforce), then you can save and restore some of the interpreter state with the following functions.

    struct SEE_interpreter_state * SEE_interpreter_save_state(
            struct SEE_interpreter *interp);
    void SEE_interpreter_restore_state(
            struct SEE_interpreter *interp, struct SEE_interpreter_state *state);

Example: of a cfunction that allows a re-entrant call into the SEE library.

    void
    example_block(interp, self, thisobj, argc, argv, res)
    	struct SEE_interpreter *interp;
    	struct SEE_object *self, *thisobj;
    	int argc;
    	struct SEE_value **argv, *res;

    {
    	struct SEE_interpreter_state *saved_state;

    	/* Save the interpreter state */
    	saved_state = SEE_interpreter_save_state(interp);

    	/* The following three calls are not part of SEE */
    	RELEASE_MUTEX(interp);
    	BLOCK();
    	ACQUIRE_MUTEX(interp);

    	/* Restore the interpreter state */
    	SEE_interpreter_restore_state(interp, saved_state);
    	SEE_SET_UNDEFINED(res);
    }

Note that calls to `SEE_eval()` and `SEE_Global_eval()` are automatically re-entrant.

### 2.2 Fatal error handlers

If SEE encounters an internal error (such as memory exhaustion, memory corruption, or a bug), it calls the global function pointer `SEE_system.abort`, passing it a pointer to the interpreter in context (or `NULL`), and a short descriptive message. The `SEE_system.abort` hook initially points to a wapper function that simply calls the C library function `abort()`. You can set the hook early if you want to handle errors more gracefully. Its signature is:

    extern struct {
        ...
        extern void (*abort)(struct SEE_interpreter *interp, const char *msg) _SEE_dead;
        ...
    } SEE_system;

A convenience macro, `SEE_ABORT()` is provided for applications to call. It calls the hook function.

    extern void (*SEE_ABORT)(struct SEE_interpreter *interp, const char *msg);

## 3 Memory management

SEE uses a garbage collecting memory allocator. SEE has global function pointers for memory allocation that the host application can configure. These hooks must be set up before any interpreter instances are created.

SEE manages memory by calling through the following function pointers stored in the global structure `SEE_system`. Your host application can replace these pointers before it creates any interpreters.

    extern struct {
        ...
        void * (*malloc)(struct SEE_interpreter *interp, SEE_size_t size);
        void * (*malloc_finalize)(struct SEE_interpreter *interp, SEE_size_t size,
            void (*)(struct SEE_interpreter *, void *, void *), void *);
        void * (*malloc_string)(struct SEE_interpreter *interp, SEE_size_t size);

        void   (*free)(struct SEE_interpreter *interp, void *ptr);
        void   (*mem_exhausted)(struct SEE_interpreter *interp);
        void   (*gcollect)(struct SEE_interpreter *interp);
        ...
    } SEE_system;

These hooks are invoked through the following functions:

- `SEE_malloc()` - allocates storage that is scanned during garbage collection
- `SEE_malloc_finalize()` - allocates storage with a function that is called when it is unreachable
- `SEE_malloc_string()` - allocates storage for a string that will not contain pointers
- `SEE_free()` - releases storage that you can guarantee is unreferenced from anywhere
- `SEE_gcollect()` - detects and releases all unreachable objects

These functions should not be directly used by applications; instead use the macros below (for example, `SEE_NEW()`).

    void * SEE_malloc(struct SEE_interpreter *interp, SEE_size_t size);
    void * SEE_malloc_finalize(struct SEE_interpreter *interp, SEE_size_t size
            void (*finalizefn)(struct SEE_interpreter *i, void *p, void *closure),
    	void *closure);
    void * SEE_malloc_string(struct SEE_interpreter *interp, SEE_size_t size);
    void SEE_free(struct SEE_interpreter *interp, void **datap);
    void SEE_gcollect(struct SEE_interpreter *interp);

Notice that `SEE_free()` takes a pointer-to-a-pointer argument, unlike its counterpart in the `SEE_system` structure. The pointer will be set to `NULL` after freeing. Freeing an already-`NULL` pointer with `SEE_free()` has no effect.

If SEE was compiled with Boehm-gc support, `SEE_system.malloc` is initialised to point to a wrapper around the `GC_malloc()` function, `SEE_system.malloc_string` is initialised to point to a wrapper around `GC_malloc_atomic()`, `SEE_system.free` is initialised to point to a wrapper around `GC_free()`, and `SEE_system.malloc_finalize` is initialised to point to a wrapper around `GC_malloc()` and `GC_register_finalizer()`. Otherwise, the initial functions print a warning message and use the system `malloc()` without releasing any memory.

⚠ Note: If you are using Boehm-gc support (and therefore `GC_malloc()`), then you must call `GC_INIT()` early (usually from `main()`). Otherwise, your application may crash. The SEE library does not initialise the Boehm garbage collector (because on some systems, and when SEE is a shared library, the Boehm GC must be initialised from a non-static code segment.)

If you intend to hook in your own memory allocator, be aware that any of these hooks may be called with a `NULL` interpreter argument which indicates an unknown context. In case of errors or resource exhaustion, the malloc hooks must not throw an exception, but should return `NULL` on failure. SEE will detect this situation and act accordingly.

Instead of calling the `SEE_malloc` functions directly, application code should use these convenient type-cast macros to allocate storage:

- `SEE_NEW()` - allocate structure storage in the context of an interpreter, returning a pointer of given type
- `SEE_NEW_ARRAY()` - allocate storage for an array of elements of the given type
- `SEE_NEW_STRING_ARRAY()` - a gc-efficient form of `SEE_NEW_ARRAY()`, where you guarantee that the elements will not contain pointers
- `SEE_NEW_FINALIZE()` - same as `SEE_NEW()`, but associates a finalizer function
- `SEE_ALLOCA()` - allocate storage for an array on the stack (see `alloca()`)
- `SEE_STRING_ALLOCA()` - like `SEE_ALLOCA()`, except used to hint that the allocated elements will not contain pointers

    T * SEE_NEW(struct SEE_interpreter *interp, type T);
    T * SEE_NEW_ARRAY(struct SEE_interpreter *interp, type T, int length);
    T * SEE_NEW_STRING_ARRAY(struct SEE_interpreter *interp, type T, int length);
    T * SEE_NEW_FINALIZE(struct SEE_interpreter *interp, type T,
        void (*finalizefn)(struct SEE_interpreter *, void *, void *),
        void *closure);
    T * SEE_ALLOCA(struct SEE_interpreter *interp, type T, int length);
    T * SEE_STRING_ALLOCA(struct SEE_interpreter *interp, type T, int length);

Example: Allocating a buffer for 30 characters:

    char *buffer = SEE_NEW_STRING_ARRAY(interp, char, 30);

The allocator macros and functions check for memory allocation failures, and in that instance will automatically call `SEE_system.mem_exhausted()`. This hook defaults to a function that simply calls `SEE_ABORT()` with a short message. Your application may prefer to change the `mem_exhausted` hook to handle this situation more gracefully.

It is worth familiarizing yourself with the macro definitions in `<see/mem.h>` to see what they do.

### 3.1 Growable memory regions

SEE provides a convenience function `SEE_grow_to()` that exponentially enlarges an allocated region to handle resize requests. This makes it useful for implementing efficient, resizeable arrays.

- `SEE_GROW_INIT()` - initialises a `SEE_grow` structure, and zeros the pointer, length counter and allocated storage counter. It sets the `element_size` field to the size of an individual element in the `ptr` array.
- `SEE_grow_to()` - sets the length counter to the given value, ensuring that the array has sufficient storage, in a manner similar to realloc. Newly allocated elements are left uninitialised.

    void SEE_GROW_INIT(struct SEE_interpreter *interp, T *&ptr, unsigned int &len);
    void SEE_grow_to(struct SEE_interpreter *interp, struct SEE_growable *grow, unsigned int new_len);

    struct SEE_growable {
        void **data_ptr;            /* Reference to base pointer */
        unsigned int *length_ptr;   /* Reference to element use count */
        SEE_size_t element_size;    /* Size of an element */
        SEE_size_t allocated;       /* Valid storage addressed by *data_ptr */
        unsigned int is_string : 1; /* Use SEE_malloc_string */
    };

This facility is intended for when you have a separated array pointer and a length field. When you want to change the length, call `SEE_grow_to`: It will ensure that the array pointer points to sufficient storage, and set the length field automatically.

Example:

    #include <see/mem.h>

    void example()
    {
        int *numbers;
        unsigned int numbers_len;
        struct SEE_growable numbers_grow;

        /* Initialises numbers to NULL, numbers_len to 0,
         * and prepares the numbers_grow structure for growth. */
        SEE_GROW_INIT(interp, &numbers_grow, numbers, numbers_len);

        /* Because the array does not contain any GC'able pointers,
         * we will make SEE_grow_to use the 'string' allocators. This
         * gives a performance advantage when the numbers array gets large. */
        numbers_grow.is_string = 1;

        /* Set numbers_len = 2, growing the array as needed */
        SEE_grow_to(interp, &numbers_grow, 2);

        /* Now it is safe to access elements 0 and 1 of numbers */
        numbers[0] = 1234;
        numbers[1] = 5678;
    }

⚠ Note: The `SEE_growable` structure and related functions first appeared in API 2.0

### 3.2 On memory allocators

Why is SEE so dependent on a garbage collector? Why doesn't it use reference counting?

This subsection is a short diversion on answering this good question. I have asked myself the same thing about other applications that use garbage collectors. I'll justify SEE's reliance on a garbage collector with the following reasons:

- Using a strict memory allocator (like `malloc()` and `free()`) would have significantly increased the complexity, development time, run-time performance and code size of the library. This would in turn affect those properties of the host application. There are various convincing documents that explain why a garbage collector is a better general software engineering choice than (say) explicit reference counting. (See Advantages and Disadvantages of Conservative Garbage Collection.)
- Exceptions (§4.2) could not have been implemented easily with (fast) `longjmp()`, because references on the stack would become memory leaks or introduce too much fragile 'finally' code.
- The object-prototype model of ECMAScript results in plenty of circular references between constructor functions and instances, and with recursive function scope chains. A reference counting scheme would leak these [1] [2].
- A decent garbage collector for C is freely available (and some good commercial ones exist, too). They do nothing to impede development. They can often be tuned to meet your application's usage patterns.

### 3.3 Interacting with an external allocator

If you will be embedding SEE in a host application that uses non-GC `malloc()`, then any `struct SEE_...` pointers that you keep inside storage obtained by `malloc()` are likely to be unreliable. This is because garbage collectors do not normally look inside `malloc`ed memory.

To make the GC aware of your reference to the SEE object, you will either need to arrange for the GC to scan your malloc'd memory (e.g. by adding it to its root set) or by using a level of pointer indirection through uncollectable GC memory.

For example, you might create an indirect reference by allocating storage with Boehm's `GC_MALLOC_UNCOLLECTABLE()` function for a structure like this:

    struct myobjref {   /* Always allocate this as GC uncollectable */
        struct SEE_interpreter *interp;
        struct SEE_object *object;
    }

Then, you can safely keep a pointer to the `myobjref` in storage allocated by `malloc()`. It would still be your problem to eventually release the `myobjref` with a call to `GC_FREE()`.

You may also find it convenient for SEE to manage the lifetime of your `malloc`ed host data. This normally happens when you create wrapped SEE objects (see §6.3) and include pointers into storage allocated with with `malloc()`. To achieve this, use `SEE_NEW_FINALIZE()` to allocate the wrapped object structure, and write a finalizer function that calls `free()` on the right members.

Similar approaches can be used for external allocators that use reference counting.

### 3.4 Finalization

Host objects that acquire operating system resources should release those resources when their finalizer is called by the garbage collector. However, a major criticism of garbage collectors is that finalizers are not invoked early or often enough. What this means is that it is highly desirable to release system resources at the earliest time possible (i.e. immediately the referring object becomes unreachable), but garbage collectors deliberately don't do this because performing the reachability analysis on objects is expensive and often left only to when memory is low.

To address this problem, I recommend developers follow these guidelines when designing their host object finalizers:

1. Provide a host object method (conventionally called `dispose()`) that immediately releases all resources acquired by the object. The dispose method should cope with being called multiple times without error. The object will need to maintain state indicating whether it is valid or disposed, and its methods should check this state and generally throw an exception if it is invalid. You may also wish to provide the user with an accessor for this state, e.g. `isValid()`. The state can usually be combined with other normally occurring error states of the object.
2. Arrange to have the finalizer simply invoke the dispose method. You may even choose to allow users to hook the dispose method by having the finalizer call the method indirectly with `SEE_OBJECT_CALL`, and then once again, directly, in case the user's hook failed.
3. Detect/predict resource exhaustion at the point when host objects acquire new resources. In this case, force an immediate garbage collection by calling `SEE_gcollect()`, and then try just once more to acquire the resource before failing. An example of this technique is shown in the mod_File.c example module that comes with SEE.

The principal effects of these guidelines are to first shift the burden of optional, optimal reachability analysis onto the user, and secondly to couple memory exhaustion with resource exhaustion to exploit the benefits of late reachability analysis and avoid false resource loss when memory is plentiful.

## 4 Running programs

SEE's ultimate purpose is to execute user scripts. A full script, or a self-contained fragment of a script is referred to as program text. You should execute program text using the following general strategy:

1. initialise the SEE library once with a call to `SEE_init()`
2. obtain a reference to an (initialised) `SEE_interpreter` (§2);
3. construct a `SEE_input` unicode stream reader (§4.2) to transport the ECMAScript program text to SEE's parser;
4. establish a try-catch context (§4.3);
5. call the function `SEE_Global_eval()` to parse and evaluate the stream;
6. handle any exceptions caught in the try-catch context (§4.3);
7. examine the value result returned (§5) (optional)

The `SEE_init()` function initialises the SEE library, and need only be called once by the application. Subsequent calls to `SEE_init()` will have no effect. This function should be called before any customization of the `SEE_system`structure occurs.``

    void SEE_init(void);

⚠ Note: The `SEE_init()` function appeared in API 3.0.

The `SEE_Global_eval()` function is able to execute program text and then store the value associated with the last executed statement in a location given by a value pointer. In a non-interactive environment, this last statement's value is usually meaningless, and the value result return pointer ('`res`') given to `SEE_Global_eval()` may be safely given as `NULL`.

    void SEE_Global_eval(struct SEE_interpreter *interp,
                    struct SEE_input *input,
                    struct SEE_value *res);

The input program text is first parsed and then immediately executed, storing the output result. If the executed program text contains function definitions, the function objects created will contain a compiled equivalent. This means it is safe to destroy the input immediately after it has been passed to `SEE_Global_eval()`.

A more versatile execution function is `SEE_eval()`.

    void SEE_eval(struct SEE_interpreter *interp,
                    struct SEE_input *input, struct SEE_object *thisobj,
                    struct SEE_object *variable, struct SEE_scope *scope,
                    struct SEE_value *res);

The program text executed by `SEE_eval()` is run in an execution context with the specified `this` object, variables object (in which `var` statements create properties) and scope chain. This is useful for host applications that need fine control over the evaluation context of user scripts.

`SEE_Global_eval()` calls `SEE_eval()` with the [[Global]] object as both `this` and the variables object, and with a scope chain consisting of just the [[Global]] object.

⚠ Note: The `SEE_eval()` function appeared in API 3.0

### 4.1 Example

Although the rest of this document explains the library API in detail, a complete, but simple example of using the SEE interpreter follows:

    #include <see/see.h>

    /* Simple example of using the interpreter */
    int
    main()
    {
            struct SEE_interpreter interp_storage, *interp;
            struct SEE_input *input;
            SEE_try_context_t try_ctxt;
            struct SEE_value result;
            char *program_text = "Math.sqrt(3 + 4 * 7) + 9";

            /* Initialise the SEE library */
    	SEE_init();

            /* Initialise an interpreter */
            SEE_interpreter_init(&interp_storage);
            interp = &interp_storage;

            /* Create an input stream that provides program text */
            input = SEE_input_utf8(interp, program_text);

            /* Establish an exception context */
            SEE_TRY(interp, try_ctxt) {
                    /* Call the program evaluator */
                    SEE_Global_eval(interp, input, &result);

                    /* Print the result */
                    if (SEE_VALUE_GET_TYPE(&result) == SEE_NUMBER)
                            printf("The answer is %f\n", result.u.number);
                    else
                            printf("Unexpected answer\n");
            }

            /* Finally: */
            SEE_INPUT_CLOSE(input);

            /* Catch any exceptions */
            if (SEE_CAUGHT(try_ctxt))
                    printf("Unexpected exception\n");

            exit(0);
    }

When this program is compiled, linked against the SEE library and the garbage collector library, and run, it should respond with:

    The answer is 14.567764

This works because the value of the last executed statement in the `program_text` is stored in `result`. Calling `SEE_Global_eval()` is essentially the same as using ECMAScript's built-in `eval()` function.

If you are interested in developing a provider module for SEE, then you should look at the example module file mod_File.c. See also §7.

### 4.2 Inputs

SEE uses Unicode character stream sources known as 'inputs' to consume (scan and parse) ECMAScript program text. An input is a stream of 32-bit Unicode UCS-4 characters. The stream is read, one character at a time, through its 'get next character' callback function.

The SEE library provides some useful stream constructors. Each constructor create a new `SEE_input` structure, initialised for reading the source it is supplied.

- `SEE_input_file()` - streams from a stdio `FILE` pointer, and understands Unicode byte-order marks in that file
- `SEE_input_utf8()` - streams the contents of a null-terminated `char` array, and assumes 7-bit ASCII or UTF-8 encoding
- `SEE_input_string()` - streams the contents of a `SEE_string` value structure (which uses UTF-16 encoding, see §5.3)

    struct SEE_input *SEE_input_file(struct SEE_interpreter *interp,
                    FILE *f, const char *filename, const char *encoding);
    struct SEE_input *SEE_input_utf8(struct SEE_interpreter *interp,
                    const char *s);
    struct SEE_input *SEE_input_string(struct SEE_interpreter *interp,
                    struct SEE_string *s);

If these constructors do not adequately meet your needs, you are encouraged to develop your own. They're quite easy to do, if a bit fiddly. I recommend you find the source to one of the above and modify it to do what you want.

The rest of this section describes the input API in detail, with a view towards custom input streams.

#### 4.2.1 Input provider API

Why streams instead of strings? SEE uses a stream API for inputs rather than (say) a simple UCS-4 or UTF-8 string API, because Unicode-compliant applications will usually have a much better understanding of the encodings they are using than will SEE. With only a small amount of effort, streams provide this flexibility while avoiding unnecessary duplication or text storage.

Inputs are described by `SEE_input` structures. These are functionally similar to stdio's `FILE` type, or Java's `ByteReader` classes. Except they stream fully-decoded Unicode characters. The `SEE_input` structure is the focus of the API and maintains the input's stream state and provides a pointer to its access (callback) methods.

    struct SEE_input {
            struct SEE_inputclass *inputclass;
            SEE_boolean_t          eof;
            SEE_unicode_t          lookahead;
            ...
    };

    struct SEE_inputclass {
            SEE_unicode_t   (*next)(struct SEE_input *input);
            void            (*close)(struct SEE_input *input);
    };

The `inputclass` member indicates the access methods. It is a pointer to a `SEE_inputclass` structure. This class structure contains function pointers to the two methods `next()` and `close()`.

The `next()` method should advance the input pointer, update the `eof` and `lookahead` members of the `SEE_input` structure, and return the old value of `lookahead`. SEE's scanner calls `next()` repeatedly, until the `eof` member becomes true. When `eof` is true, the value of `lookahead` becomes meaningless (but should be set to `-1`). Generally, the stream's constructor will internally call its `next()` function once initially, to 'prime' the lookahead field.

If the `next()` method encounters an encoding error, it should set `lookahead` to `SEE_INPUT_BADCHAR` and try to recover. It can throw an exception if it wants to, but SEE does not attempt to handle that: the application or user program will receive it. If you don't particularly care about Unicode, it is helpful to know that 7-bit ASCII is a direct subset of Unicode, so you can just pass each of your ASCII `char`s as a 32-bit `SEE_unicode_t` masked with `0x7f`. (See the Unicode standards.)

The `close()` method should deallocate any operating system resources acquired during the input stream's construction. By convention, SEE will not call the `close()` method of any application-supplied input. The onus is on the caller to close the inputs supplied to SEE library functions. For this reason, you should use the 'finally' behaviour described in §4.3 to clean up a possibly failed stream.

The `SEE_input` structure represents the current state of the input stream. Most importantly, the `lookahead` field must always reflect the next character that a call to `next()` would return. Once initialised, the `filename`, `first_lineno` and `interpreter` members of the `SEE_input` structure should not be changed. The `lookahead` and `eof` members should also be initialised before the structure is given to SEE.

You are encouraged to read the source code to the three constructors listed at the beginning of this section.

#### 4.2.2 Input client API

Consumers, like SEE's lexical analyser, will use these convenience macros to call input methods on a constructed input stream, rather than calling through the class structure directly:

- `SEE_INPUT_NEXT()` - Consumes and returns the next Unicode character from the stream
- `SEE_INPUT_CLOSE()` - Releases any resources obtained by the stream

    SEE_unicode_t SEE_INPUT_NEXT(struct SEE_input *input);
    void SEE_INPUT_CLOSE(struct SEE_input *input);

### 4.3 Try-catch contexts

SEE's exceptions are implemented using C's `setjmp()`/`longjmp()` mechanism. SEE provides macros that establish a try-catch context, and test later if a try block terminated abnormally (i.e. due to an thrown exception). Typical code that uses try-catch looks like this:

    struct SEE_interpreter *interp;
    struct SEE_value *e;
    SEE_try_context_t c; /* storage for the try-catch context */

    ...

    SEE_TRY(interp, c) {

            /*
             * Now inside a protected "try block".
             * The following calls may throw exceptions if they want,
             * causing the try block to exit immediately.
             */
            do_something();
            do_something_else();

            /*
             * Because the SEE_TRY macro expands into a 'for' loop,
             * avoid using 'break', or 'return' statements.
             * If you must leave the try block, use SEE_TRY_BREAK
             * or throw an exception.
             */
    }

    /* Code placed here always runs. */
    do_cleanup();

    if ((e = SEE_CAUGHT(c))) {
            /* Handle the thrown exception 'e', somehow. */
            handle_exception(e);

            /* OR you can throw it up to the next try-catch like so: */
            SEE_RETHROW(interp, c);
    }

    ...

Do not `return`, `goto` or `break` out of a try block; the macro does not check for this, and the try-catch context may not be restored properly, causing all sorts of havoc. Currently, the `SEE_TRY_BREAK` macro expands into a `continue` statement, which terminates the `SEE_TRY` block correctly.

Exceptions thrown outside of any try-catch context will cause the interpreter to abort.

If you are not interested in catching exceptions, and only want the 'finally' behaviour, use the following idiom:

    SEE_TRY(interp, c) {
            do_something();
    }
    do_finally();    /* optional */
    SEE_DEFAULT_CATCH(interp, c);

If you need to re-throw an exception, use the `SEE_RETHROW()` macro. This macro must only be called when an exception has actually been caught; its behaviour when no exception has been caught is undefined. Note that you can still use `SEE_THROW()` to re-throw an exception, but the traceback information will be lost.

The signatures of these macros are:

    SEE_TRY(struct SEE_interpreter *interp, SEE_try_context_t ctxt) { stmt... }
    struct SEE_object *SEE_CAUGHT(SEE_try_context_t ctxt);
    void SEE_THROW(struct SEE_interpreter *interp, struct SEE_object *exception);
    void SEE_DEFAULT_CATCH(struct SEE_interpreter *interp, SEE_try_context_t ctxt);
    void SEE_RETHROW(struct SEE_interpreter *interp, SEE_try_context_t ctxt);

The `SEE_DEFAULT_CATCH(interp, c)` macro is equivalent to:

    if (SEE_CAUGHT(c))
    	SEE_RETHROW(interp, c);

### 4.4 Periodic callbacks

An application can use SEE's periodic callback mechanism to check for timeouts, interrupts or GUI events. The `periodic` field in the `SEE_system` structure, if set to something other than `NULL`, is called in the following situations:

- Before any statement in a script is executed
- Before any state branch processing during regular expression execution

    extern struct {
    	/* ... */
            void (*periodic)(struct SEE_interpreter *);
    	/* ... */
    } SEE_system;

It is possible for a cfunction to block the current thread and prevent the `periodic` hook from being called by SEE. Alternatives to the `periodic` hook are:

- Using threads
- Using signals or interrupts

⚠ Note: The `periodic` hook appeared in API 2.0

## 5 Values

Eventually, your host application will want to pass numbers, strings and complex value objects about, through the SEE interpreter, to and from the user code. This section describes the C interface to ECMAScript values.

The ECMAScript language has exactly six types of value. They are:

- undefined type - with exactly one value: `undefined`
- null type - with exactly one value: `null`
- boolean type - with exactly two values: `true` and `false`
- number type - IEEE 754 64-bit floating point numbers
- string type - UTF-16 character arrays of arbitrary length
- object type - a reference to a bag of named properties

The `SEE_value` structure can represent values of all of these types.

    struct SEE_value {
        enum { ... }            _type;
        union {
            SEE_boolean_t       boolean;
            SEE_number_t        number;
            struct SEE_string * string;
            struct SEE_object * object;
            ...
        } u;
    };

The first member, `_type`, is the discriminator, and must be one of the enumerated values `SEE_UNDEFINED`, `SEE_NULL`, `SEE_BOOLEAN`, `SEE_NUMBER`, `SEE_STRING` or `SEE_OBJECT`. You should access the `_type` member using the `SEE_VALUE_GET_TYPE()` macro.

    enum { ... } SEE_VALUE_GET_TYPE(struct SEE_value *value);

Depending on the type, you can directly access the corresponding value of a `SEE_value`. If the value variable is declared as:

    struct SEE_value v;

then the value that it holds is directly accessed through its union member, `v.u`. The following table shows when the union fields of `v.u` are valid:

`SEE_VALUE_GET_TYPE(&v)` | Valid member | Member's type
--- | --- | ---
`SEE_UNDEFINED` | n/a | n/a
`SEE_NULL` | n/a | n/a
`SEE_BOOLEAN` | `v.u.boolean` | `SEE_boolean_t`
`SEE_NUMBER` | `v.u.number` | `SEE_number_t`
`SEE_STRING` | `v.u.string` | `struct SEE_string *`
`SEE_OBJECT` | `v.u.object` | `struct SEE_object *`

Two other types (`SEE_COMPLETION` and `SEE_REFERENCE`) are only used internally to SEE and are not documented here.

To convert/coerce values into values of a different types, use the utility functions describe in §5.1.

To create new values in `struct SEE_value` structures, use the following initialisation macros. They first set the `_type` field and then copy the second parameter into the appropriate union field. It is fine to use a local variable for a `struct SEE_value`, because the garbage collector can see what is being used from the stack.

    void SEE_SET_UNDEFINED(struct SEE_value *val);
    void SEE_SET_NULL(struct SEE_value *val);
    void SEE_SET_OBJECT(struct SEE_value *val, struct SEE_object *obj);
    void SEE_SET_STRING(struct SEE_value *val, struct SEE_string *str);
    void SEE_SET_NUMBER(struct SEE_value *val, SEE_number_t num);
    void SEE_SET_BOOLEAN(struct SEE_value *val, SEE_boolean_t bool);

Most `SEE_value`s are passed about the SEE library functions using pointers. This is because the general contract is that the caller supplies storage for the return value (usually named `ret`), while other pointer arguments are treated as read-only. Conventionally, the result value pointer is provided as the last argument to these functions and is named `res`.

Avoid storing a `struct SEE_value` as a pointer. Instead, extract and copy values into storage using the following macro:

    void SEE_VALUE_COPY(struct SEE_value *dst, struct SEE_value *src);

⚠ Note: The `SEE_VALUE_COPY()` macro breaks the convention of putting the result pointer last by instead following the better-known idiom of `memcpy()`, which places the destination first.

A simple pitfall to avoid when passing values to SEE functions is to use a single value as both a parameter to the function and as the return result storage. Do not do this. It is possible that the function will initialise its return storage before it accesses its parameters.

### 5.1 Value conversion

The ECMAScript language specification provides for conversion functions that the host application developer may find useful. They convert arbitrary values into values of a known type:

- `SEE_ToPrimitive()` - Returns a non-object value. It calls the object's `DefaultValue()` method (see §6.3)
- `SEE_ToBoolean()` - Returns a value of type `SEE_BOOLEAN`
- `SEE_ToNumber()` - Returns a value of type `SEE_NUMBER`
- `SEE_ToInteger()` - Returns a value of type `SEE_NUMBER` that is also a finite integer
- `SEE_ToString()` - Returns a value of type `SEE_STRING`
- `SEE_ToObject()` - Returns a value of type `SEE_OBJECT` using the `String`, `Number` and `Boolean` constructors

    void SEE_ToPrimitive(struct SEE_interpreter *interp,
                    struct SEE_value *val, struct SEE_value *hint,
                    struct SEE_value *res);
    void SEE_ToBoolean(struct SEE_interpreter *interp,
                    struct SEE_value *val, struct SEE_value *res);
    void SEE_ToNumber(struct SEE_interpreter *interp,
                    struct SEE_value *val, struct SEE_value *res);
    void SEE_ToInteger(struct SEE_interpreter *interp,
                    struct SEE_value *val, struct SEE_value *res);
    void SEE_ToString(struct SEE_interpreter *interp,
                    struct SEE_value *val, struct SEE_value *res);
    void SEE_ToObject(struct SEE_interpreter *interp,
                    struct SEE_value *val, struct SEE_value *res);

See also the `SEE_parse_args()` function for a convenient way to extract C types from SEE values.

### 5.2 Undefined, null, boolean and number values

The undefined and null types have exactly one implied value each, namely `undefined` and `null`.

⚠ Note: ECMAScript's `null` is not an object type, and is not related to C's `NULL` constant.

Boolean types (`SEE_boolean_t`) have values of either true (non-zero) or false (zero).

Number values (`SEE_number_t`) are IEEE 754 signed floating point numbers, normally corresponding to the C compiler's built-in `double` type.

The following macros may be used to find information about a number value. (They assume that the `type` is `SEE_NUMBER`):

- `SEE_NUMBER_ISNAN()` - return true if the value represents an error condition (not a number)
- `SEE_NUMBER_ISPINF()` - return true if the value is +∞
- `SEE_NUMBER_ISNINF()` - return true if the value is -∞
- `SEE_NUMBER_ISFINITE()` - return true if the value is a finite number

    int SEE_NUMBER_ISNAN(struct SEE_value *val);
    int SEE_NUMBER_ISPINF(struct SEE_value *val);
    int SEE_NUMBER_ISNINF(struct SEE_value *val);
    int SEE_NUMBER_ISFINITE(struct SEE_value *val);

⚠ Note: The `SEE_NUMBER_ISINF()` and `SEE_ISINF()` macros of API 1.0 were deprecated in API 2.0. Previously, it returned true for values of ±∞

While the `SEE_NUMBER_xx()` macros work on values, the following macros are provided for operating on `SEE_number_t` types directly:

- `SEE_ISNAN()` - return true if the argument represents an error condition (not a number)
- `SEE_ISFINITE()` - return true if the argument is a finite number
- `SEE_ISPINF()` - return true if the argument is +∞
- `SEE_ISNINF()` - return true if the argument is -∞
- `SEE_COPYSIGN()` - returns the first argument converted to have the sign of the second

    int SEE_ISNAN(SEE_number_t);
    int SEE_ISFINITE(SEE_number_t);
    int SEE_ISPINF(SEE_number_t);
    int SEE_ISNINF(SEE_number_t);
    SEE_number_t SEE_COPYSIGN(SEE_number_t, SEE_number_t);

SEE also provides constants `SEE_Infinity` and `SEE_NaN` which may be stored in number values, but should not be used to compare number values with C's `==` operator. Use the macros mentioned previously, instead.

    const SEE_number_t SEE_Infinity;
    const SEE_number_t SEE_NaN;

Numbers (and other values) may be converted to integers using the functions `SEE_ToInt32()`, `SEE_ToUint32()` or `SEE_ToUint16()`.

    SEE_int32_t  SEE_ToInt32(struct SEE_interpreter *interp, struct SEE_value *val);
    SEE_uint32_t SEE_ToUint32(struct SEE_interpreter *interp, struct SEE_value *val);
    SEE_uint16_t SEE_ToUint16(struct SEE_interpreter *interp, struct SEE_value *val);

SEE provides three data types for integers:

- `SEE_uint16_t` - 16 bit unsigned integer
- `SEE_uint32_t` - 32 bit unsigned integer
- `SEE_int32_t` - 32 bit signed integer

### 5.3 String values

String values are pointers to `SEE_string` structures, that hold UTF-16 strings. Strings are stored as arrays of 16-bit unicode character codepoints. The `SEE_string` structure is defined something like this:

    struct SEE_string {
            unsigned int     length;
            SEE_char_t      *data;
            ...
    };

The useful members are:

- `length` - Length of string content
- `data` - Read-only storage for the string content (UTF-16 characters)

Be aware that other strings may come to share the string's data, such as by forming substrings. A string's content must not be modified after construction because of this risk. However, the `length` field of a string may be changed to a smaller value at any time without concern.

The `SEE_char_t` type represents a UTF-16 character in the string. It is equivalent to a 16-bit unsigned integer.

To manipulate a string, first create a new string using one of the following:

- `SEE_string_new()` - create a new, empty string
- `SEE_string_dup()` - create a new string with duplicate content
- `SEE_string_sprintf()` - create a new string using `printf`-like arguments
- `SEE_string_vsprintf()` - create a new string using `vprintf`-like arguments

    struct SEE_string *SEE_string_new(struct SEE_interpreter *interp,
                    unsigned int space);
    struct SEE_string *SEE_string_dup(struct SEE_interpreter *interp,
                    const struct SEE_string *s);
    struct SEE_string *SEE_string_sprintf(struct SEE_interpreter *interp,
                    const char *fmt, ...);
    struct SEE_string *SEE_string_vsprintf(struct SEE_interpreter *interp,
                    const char *fmt, va_list ap);

And then, before passing your new string to any other function, append characters to it using the following:

- `SEE_string_addch()` - append a UTF-16 character
- `SEE_string_append()` - append contents of another string
- `SEE_string_append_ascii()` - convert 7bit ASCII to Unicode and append to another string
- `SEE_string_append_int()` - append a signed integer's representation in base 10
- `SEE_string_append_unicode()` - append an unencoded Unicode character

    void SEE_string_addch(struct SEE_string *s, SEE_char_t ch);
    void SEE_string_append(struct SEE_string *s, const struct SEE_string *sffx);
    void SEE_string_append(struct SEE_string *s, const char *);
    void SEE_string_append_int(struct SEE_string *s, int i);
    void SEE_string_append_unicode(struct SEE_string *s, SEE_unicode_t c);

Once a new string has been passed to any other SEE function, it should not have its contents modified in any way. This is because string data can end up being shared between strings.

Strings themselves should not be passed between different interpreters, unless internalised with `SEE_intern_global()` (see §5.3.1) or 'fixed' with `SEE_string_fix()`. Fixing a string ensures that its content will not be modified or extended by another interpreter.

    struct SEE_string *SEE_string_fix(struct SEE_string *s);

All strings in SEE use UTF-16 encoding, meaning that in some cases you may need to be aware of Unicode 'surrogate' characters. If the host application really needs UCS-4 strings (which are subtly different to UTF-16), you will need to write your own converter function. Use the implementation of `SEE_input_string()` (§4.2) as the basis for such a converter because it understands UTF-16 combiner codes.

The functions `SEE_string_sprintf()` and `SEE_string_vsprintf()` do not exactly have the same formats as the standard `printf()` function, although they are substantially similar. Follows is a table of understood formats:

Format | Type | Comment
--- | --- | ---
`%[+][-][0][#]d` | `signed int` | decimal
`%[+][-][0][#]u` | `unsigned int``` | decimal
`%[+][-][0][#]x` | `unsigned int` | hexadecimal (base 16)
`%c` | `char` | ASCII only
`%C` | `SEE_char_t`
`%[-][#][.#]s` | `const char *` | ASCII only
`%[-][#][.#]S` | `struct SEE_string *`
`%[-][#]p` | `void *`
`%%` |  | single `%`
`%`other |  | literal `%`other

⚠ Note: Pror to API 2.0, the `SEE_string_sprintf()` and `SEE_string_vsprintf()` used the system `snprintf` forcing its output to 7-bit ASCII.

Where a hash (`#`) appears in the format column above, it means that either a positive integer in base 10 may be supplied to indicate padding or precision, (eg `%4d`) or an asterisk (`*`) can be used instead to indicate that the next `int` argument provides the padding or precision value. This follows the behaviour of `printf()`.

Other string functions provided are:

- `SEE_string_substr()` - create a read-only substring string
- `SEE_string_literal()` - create a copy of the string, escaping chars and enclosing it in double quotes (`"`)
- `SEE_string_fputs()` - write the string to the stdio file using UTF-8 encoding, returns `EOF` on error
- `SEE_string_toutf8()` - copy the string into a C string buffer, using UTF-8 encoding, throwing an error if the buffer is too small. Space is required for the trailing null character.
- `SEE_string_utf8_size()` - returns the size in bytes, excluding the trailing null character, of a UTF-8 conversion of the given string.
- `SEE_string_concat()` - efficiently concatenate two strings, creating a new string
- `SEE_string_cmp()` - compares two strings, like `strcmp()`

    struct SEE_string *SEE_string_substr(struct SEE_interpreter *interp,
                    struct SEE_string *s, int index, int length);
    struct SEE_string *SEE_string_literal(struct SEE_interpreter *interp,
                    const struct SEE_string *s);
    int SEE_string_fputs(const struct SEE_string *s, FILE *file);
    void SEE_string_toutf8(struct SEE_interpreter *interp,
                    char *buffer, SEE_size_t buffer_size,
                    const struct SEE_string *s);
    SEE_size_t SEE_string_utf8_size(struct SEE_interpreter *interp,
                    const struct SEE_string *s);
    struct SEE_string *SEE_string_concat(struct SEE_interpreter *interp,
                    struct SEE_string *s1, struct SEE_string *s2);
    int SEE_string_cmp(const struct SEE_string *s1,
                    const struct SEE_string *s2);

⚠ Note: The `SEE_string_toutf8()` function does not check for null characters in the output. Consider using `SEE_string_literal()` to make the string well-formed before converting to UTF-8.

#### 5.3.1 Internalised strings

If you find yourself comparing strings a lot, you may find it easier to compare internalised strings. These are strings that are kept in a fast hash table and may be compared equal using pointer equality. The `SEE_intern()` function returns an 'internalized' copy of the given string and is very fast on already-interned strings. It is worth using in lieu of `SEE_string_cmp()` if the strings are likely to be internalized already. (For example, all property names in the standard library are internalized.)

The function `SEE_intern_ascii()` is a convenience function that first converts the C string into a `SEE_string` before internalizing. The C string must be an ASCII string terminated by a null character.

    struct SEE_string *SEE_intern(struct SEE_interpreter *interp,
                    struct SEE_string *s);
    struct SEE_string *SEE_intern_ascii(struct SEE_interpreter *interp,
                    const char *s);

#### 5.3.2 Statically initialised strings

SEE supports statically initialised strings. If you have a large number of strings to create and use (e.g. properties and method names) over many interpreter instances, statically initialised strings can save space, and slightly improve performance.

Example:

    /* Example of a statically-initialised UTF-16 string */
    static SEE_char_t hello_world_chars[12] = {
        'H', 'e', 'l', 'l', 'o', ',', ' ', 'w', 'o', 'r', 'l', 'd'
    };
    static struct SEE_string hello_world = {
        12,                                                /* length */
        hello_world_chars                                  /* data */
    };

    ...
    struct SEE_string *text = &hello_world;

The main problem with static strings is finding an elegant way to initialise the strings' content. There is no simple way in ANSI C to have the compiler convert common ASCII strings into UTF-16 arrays. The internal approach taken by SEE in supporting all the standard ECMAScript object property names, is to generate C program text from a file of ASCII strings during the build process.

If an application wishes to internalise strings across interpreters, it can add all its global strings into the global intern table before creating any interpreters. This is done by calling `SEE_intern_global()` for each string. Doing this can save a moderate amount of overhead, and can improve performance if the internalized string needs to be used often.

    struct SEE_string * SEE_intern_global(const char *str);

⚠ Note: Prior to API 2.0, `SEE_intern_global()` had a very different signature. See §8.3.

## 6 Objects

ECMAScript uses a prototype-inheritance object model with simple named properties. More information on the object model can be found in the ECMA-262 standard, and in other JavaScript references.

This section describes how in-memory objects can be accessed and manipualated (the 'client interface'), and also how host applications can expose their own application objects and methods (the 'implementation interface').

Object instances are implemented as in-memory structures, with an `objectclass` pointer to a table of operational methods. Object references are held inside values with a type field of `SEE_OBJECT` (see §5).

If you want to create a plain object quickly from C, the convenience function `SEE_Object_new()` is the same as evaluating `new Object()`.

    struct SEE_object *SEE_Object_new(struct SEE_interpreter *interp);

### 6.1 Object values, and the object client interface

All object values are pointers to object instances. The pointers are of type `struct SEE_object *`. No object pointer in a `SEE_value` should ever point to `NULL`. I find working with `struct SEE_object *` pointer types directly, instead of using `struct SEE_value` to be convenient, when I know that I am dealing with objects.

To use an object instance, you should interact with it using the following internal method macros:

- `SEE_OBJECT_GET()` * - retrieve a named property or return `undefined` ('`o.prop`'); also known as the `[[Get]]` internal method
- `SEE_OBJECT_PUT()` * - create/update a named property ('`o.prop = val`'); also known as the `[[Put]]` internal method
- `SEE_OBJECT_CANPUT()` * - returns true if the property can be changed; also known as the `[[CanPut]]` internal method; assumes `prop` is an internalised string
- `SEE_OBJECT_HASPROPERTY()` * - tests for existence of a property ('`"prop" in o`'); also known as the `[[HasProperty]]` internal method; assumes `prop` is an internalised string
- `SEE_OBJECT_DELETE()` * - delete a property; returns true on success ('`delete o.prop`'); also known as the `[[Delete]]` internal method; assumes `prop` is an internalised string
- `SEE_OBJECT_DEFAULTVALUE()` - returns the string or number value associated with the object; also known as the `[[DefaultValue]]` internal method
- `SEE_OBJECT_CONSTRUCT()` † - call object as a constructor ('`new o(...)`'); also known as the `[[Construct]]` internal method (Note: the `thisobj` parameter of the construct macro is not used and should be set to `NULL`)
- `SEE_OBJECT_CALL()` † - call object as a function ('`o(...)`'); also known as the `[[Call]]` internal method
- `SEE_OBJECT_HASINSTANCE()` † - return true if the objects are related ('`x instanceof o`'); also known as the `[[HasInstance]]` internal method
- `SEE_OBJECT_ENUMERATOR()` † - create a property enumerator ('`for (i in o) ...`')
- `SEE_OBJECT_GET_SEC_DOMAIN()` † - returns the security domain associated with callable objects only (see §9)

    void SEE_OBJECT_GET(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_string *prop,
                    struct SEE_value *res);
    void SEE_OBJECT_PUT(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_string *prop,
                    struct SEE_value *res, int flags);
    int SEE_OBJECT_CANPUT(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_string *prop);
    int SEE_OBJECT_HASPROPERTY(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_string *prop);
    int SEE_OBJECT_DELETE(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_string *prop);
    void SEE_OBJECT_DEFAULTVALUE(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_value *hint,
                    struct SEE_value *res);
    void SEE_OBJECT_CONSTRUCT(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_object *thisobj,
                    int argc, struct SEE_value **argv,
                    struct SEE_value *res);
    void SEE_OBJECT_CALL(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_object *thisobj,
                    int argc, struct SEE_value **argv,
                    struct SEE_value *res);
    int SEE_OBJECT_HASINSTANCE(struct SEE_interpreter *interp,
                    struct SEE_object *obj, struct SEE_value *instance);
    struct SEE_enum *SEE_OBJECT_ENUMERATOR(struct SEE_interpreter *interp,
                    struct SEE_object *obj);
    void *SEE_OBJECT_GET_SEC_DOMAIN(struct SEE_interpreter *interp,
                    struct SEE_object *obj);

* The property `SEE_string` arguments to the property operation macros must have been internalised with `SEE_intern()`. This requirement appeared in API 3.0

† Five of the macros above (`CONSTRUCT`, `CALL`, `HASINSTANCE`, `ENUMERATOR` and `GET_SEC_DOMAIN`) call optional internal methods, and do not check if the object class has not provided them. This means the macros may try to call through a `NULL` function pointer, which will cause an error. You can determine if the object's class provides the optional methods by using the following macros before you use one of the four marked above. These check macros returns true if the method they check for is valid (i.e. they check the function pointer in the object class is non-`NULL`):

- `SEE_OBJECT_HAS_CALL()` - object can be called with `SEE_OBJECT_CALL()`
- `SEE_OBJECT_HAS_CONSTRUCT()` - object can be called with `SEE_OBJECT_CONSTRUCT()`
- `SEE_OBJECT_HAS_HASINSTANCE()` - object can be called with `SEE_OBJECT_HASINSTANCE()`
- `SEE_OBJECT_HAS_ENUMERATOR()` - object can be called with `SEE_OBJECT_ENUMERATOR()`
- `SEE_OBJECT_HAS_GET_SEC_DOMAIN()` - object can be called with `SEE_OBJECT_GET_SEC_DOMAIN()`

    int SEE_OBJECT_HAS_CALL(struct SEE_object *obj);
    int SEE_OBJECT_HAS_CONSTRUCT(struct SEE_object *obj);
    int SEE_OBJECT_HAS_HASINSTANCE(struct SEE_object *obj);
    int SEE_OBJECT_HAS_ENUMERATOR(struct SEE_object *obj);
    int SEE_OBJECT_HAS_GET_SEC_DOMAIN(struct SEE_object *obj);

Because it is frequently convenient to provide property names using ASCII C strings instead of with `struct SEE_string` pointers, the following convenience macros are provided. They are functionally identical to their counterparts, except that they convert their property name argument with `SEE_intern_ascii()`:

    void SEE_OBJECT_GETA(struct SEE_interpreter *interp,
                    struct SEE_object *obj, const char *ascii_prop,
                    struct SEE_value *res);
    void SEE_OBJECT_PUTA(struct SEE_interpreter *interp,
                    struct SEE_object *obj, const char *ascii_prop,
                    struct SEE_value *res, int flags);
    int SEE_OBJECT_CANPUTA(struct SEE_interpreter *interp,
                    struct SEE_object *obj, const char *ascii_prop);
    int SEE_OBJECT_HASPROPERTYA(struct SEE_interpreter *interp,
                    struct SEE_object *obj, const char *ascii_prop);
    int SEE_OBJECT_DELETEA(struct SEE_interpreter *interp,
                    struct SEE_object *obj, const char *ascii_prop);

⚠ Note: The convenience macros `SEE_OBJECT_*A` were introduced in API 2.0.

When storing properties in an object with `SEE_OBJECT_PUT()`, a `flags` parameter is required. In normal operation, this flag should be supplied as zero, but when populating an object with its properties for the first time, the following bit flags can be used:

Flag | Meaning
--- | ---
`SEE_ATTR_READONLY` | Future assignments (puts) on this property will fail
`SEE_ATTR_DONTENUM` | Enumerators will not list this property and will hide inherited prototype properties of the same name until this property is `delete`d. (see §6.2)
`SEE_ATTR_DONTDELETE` | Future `delete`s on this property will fail

### 6.2 Property enumerators

A property enumerator is a mechanism for discovering the properties that an object contains. The language exercises this with its `for (var v in ...)` construct. The results of the enumeration need not be sorted, nor even to be the same order each time.

Calling `SEE_OBJECT_ENUMERATOR()` returns a newly created enumerator which is a pointer to a `struct SEE_enum`. Once obtained, the following macros can be used to access the enumerator:

- `SEE_ENUM_NEXT()` - return a pointer to an internalized property name string, or `NULL` when the properties have been exhausted.

    struct SEE_string *SEE_ENUM_NEXT(struct SEE_interpreter *interp,
                    struct SEE_enum *e, int *flags_return);

Enumerators can assume that the underlying object does not change during enumeration. A suggested strategy for a caller that does need to remove or add an object's properties while enumerating them is to first create a private list of its property names, ensuring that it has exhausted the enumerator before attempting to modify the object.

Example: of enumerating properties on an object from C:

    void
    print_properties(struct SEE_interpreter *interp, struct SEE_object *obj)
    {
            struct SEE_enum *enumerator;
            struct SEE_string *prop;

            /* Ignore objects that don't provide an enumerator */
            if (!SEE_OBJECT_HAS_ENUMERATOR(obj))
                    return;

            enumerator = SEE_OBJECT_ENUMERATOR(interp, obj);
            while ((prop = SEE_ENUM_NEXT(interp, enumerator, NULL)) != NULL) {
                    SEE_PrintString(interp, prop, stdout);
                    printf("\n");
            }
    }

### 6.3 The object implementation interface

When a host application wishes to expose its own 'host objects' to ECMAScript programs, it must use the object implementation API described in this section.

All SEE objects are in-memory structures starting with a `struct SEE_object`:

    struct SEE_object {
            struct SEE_objectclass *objectclass;
            struct SEE_object *     Prototype;
    	void *                  host_data;
    };

The `host_data` field is for use by the host application. It is initialised to NULL in objects created by SEE.

⚠ Note: The `host_data` field was added in API 3.0.

Normally, the `SEE_object` structure is part of a larger structure that maintains the object's private state.

Example: Implementing native `Number` instance objects:

    struct number_object {             /* example implementation of Number */
            struct SEE_object object;
            SEE_number_t      number;
    };

Keeping the `object` part at the top of the `number_object` structure means that pointers of type `struct number_object *` can be cast to and from pointers of type `struct SEE_object *`. This is a general idiom: begin all host object structures with a field member of type `struct SEE_object` named `object`.

Although the ECMAScript language does not use classes per se, SEE's internal object implementation does use a class 'abstraction' to speed up execution and make implementation re-use easier. Each object has a field, `object.objectclass`, that must be initialised to point to a `struct SEE_objectclass` that provides the object's behaviour. The class structure looks like this:

    struct SEE_objectclass {
            const char *            Class;          /* mandatory */
            SEE_get_fn_t            Get;            /* mandatory */
            SEE_put_fn_t            Put;            /* mandatory */
            SEE_boolean_fn_t        CanPut;         /* mandatory */
            SEE_boolean_fn_t        HasProperty;    /* mandatory */
            SEE_boolean_fn_t        Delete;         /* mandatory */
            SEE_default_fn_t        DefaultValue;   /* mandatory */
            SEE_enumerator_fn_t     enumerator;     /* optional */
            SEE_call_fn_t           Construct;      /* optional */
            SEE_call_fn_t           Call;           /* optional */
            SEE_hasinstance_fn_t    HasInstance;    /* optional */
            SEE_get_sec_domain_fn_t get_sec_domain; /* optional (API 2.0) */
    };

⚠ Note: The type of the `Class` field changed from `struct SEE_string *` in API 1.0 to `const char *` in API 2.0.

The application generally provides this structure in static storage, as most of its members are function pointers or strings known at compile time. A member marked optional should be set to `NULL` if it is meaningless.

The object methods marked mandatory (`Get`, `Put`, etc.) are never `NULL`, and should provide the precise behaviours that SEE expects on native objects. These behaviours are fully described in the ECMA-262 standard, and are summarised in the following table:

Field | Behaviour
--- | ---
`Class` | name of the class as revealed by `toString()`
`Get` | retrieve a named property (or return `undefined`)
`Put` | create/update a named property
`Delete` | delete a property or return 0
`HasProperty` | returns 0 if the property doesn't exist
`CanPut` | returns 0 if the property cannot be changed
`DefaultValue` | turns the object into a string or number value
`enumerator` | allow enumeration of the properties (see above)
`Construct` | constructs a new object; as per the `new` keyword
`Call` | the object has been called as a function
`HasInstance` | returns 0 if the objects are unrelated
`get_sec_domain` | returns the security domain associated with functions

⚠ Note: The thisobj argument to the `Construct` method is unused and should be ignored by implementations.

It is up to the host application to provide storage for the properties, and so forth. The simplest strategy is to ignore property calls to `Put` and `Get` that are meaningless. To this end, if the host object does not want to expend effort supporting some of the mandatory operations, it can use the corresponding 'do-nothing' function(s) from this list:

- `SEE_no_get()`
- `SEE_no_put()`
- `SEE_no_canput()`
- `SEE_no_hasproperty()`
- `SEE_no_delete()`
- `SEE_no_defaultvalue()`

⚠ Note: `SEE_no_enumerator()` was deprecated in API 2.0. Use `NULL` instead.

⚠ Note: Property strings returned from an enumerator's `next()` method are required to have been internalised, e.g. with `SEE_intern()`. This requirement was added in API 3.0.

The `Prototype` field of an object instance can either be set to:

- the interpreter's `Object_prototype`,
- `NULL`, meaning no prototype, or
- some other object. (Be careful to avoid a prototype cycle!)

If you choose to use `NULL`, it is recommended you provide a `toString()` method (to help with debugging).

Once the host application has constructed its own objects that conform to the API, they can be inserted into the 'Global object' as object-valued properties.

The 'Global object' is an unnamed, top-level object whose sole purpose is to 'hold' all the built-in objects, such as `Object`, `Function`, `Math`, etc., as well as all user-declared global variables. The host application can access it through the `Global` member of the `SEE_interpreter` structure.

If you need to test an object's prototype chain, then the `instanceof` operator can be simulated with a call to `SEE_object_instanceof()`. This function tests if `val` is an instanceof `obj`:

    int SEE_object_instanceof(struct SEE_interpreter *,
                    struct SEE_value *val, struct SEE_object *obj);

### 6.4 Native objects

SEE provides support for a special kind of object class called native objects. Native objects maintain a hash table of properties, and implement the mandatory methods (plus `enumerator`), and correctly observe the `Prototype` field.

    struct SEE_native {
            struct SEE_object       object;
            struct SEE_property *   properties[SEE_NATIVE_HASHLEN];
    };

An application can create host objects based on native objects. First, place a `struct SEE_native` at the beginning of a structure:

    struct some_host_object {
            struct SEE_native       native;
            int                     host_specific_info;
    };

Then, use the following objects methods, either directly in the `SEE_objectclass` structure, or by calling them indirectly from method implementations:

- `SEE_native_get()`
- `SEE_native_put()`
- `SEE_native_canput()`
- `SEE_native_hasproperty()`
- `SEE_native_delete()`
- `SEE_native_defaultvalue()`
- `SEE_native_enumerator()`

It is very important that you initialize the `native` field when constructing your host object. Do this using the `SEE_native_init()` function.

    void SEE_native_init(struct SEE_native *obj, struct SEE_interpreter *i,
                    const struct SEE_objectclass *obj_class,
                    struct SEE_object *prototype);

### 6.5 C function objects

The host application will likely want a C function to be able to be called directly from a user script. SEE supports this by wrapping C function pointers in 'cfunction' objects.

The convenience function `SEE_cfunction_make()` constructs an object whose `Prototype` field points to `Function.prototype`, and whose `objectclass`'s `Call` method points to a given C function that contains the desired code.

The `SEE_cfunction_make()` takes a pointer to the C function, and an integer indicating the expected number of arguments. The integer becomes the function object's `length` property, which is advisory only.

Function objects are usually added as a property of another object. Remember that top level functions in ECMAScript (like `parseInt()` are actually properties of the unamed [[Global]] object.

    struct SEE_object *SEE_cfunction_make(struct SEE_interpreter *interp,
                    SEE_call_fn_t func, struct SEE_string *name, int argc);

⚠ Note: Objects returned by `SEE_cfunction_make()` should really only be used in the interpreter context in which they were created, but the current version of SEE does not check for this. (Because cfunction objects are essentially read-only after construction, and if memory allocation operates independently of the interpreters, sharing cfunction objects across interpreters will be OK, but it is not recommended for future portability.)

Example: This C function is the actual code behind the `Math.sqrt` object:

    /* Implementation of Math.sqrt() method */
    static void
    math_sqrt(interp, self, thisobj, argc, argv, res)
            struct SEE_interpreter *interp;
            struct SEE_object *self, *thisobj;
            int argc;
            struct SEE_value **argv, *res;
    {
            struct SEE_value v;

            if (argc == 0)
                    SEE_SET_NUMBER(res, SEE_NaN);
            else {
                    SEE_ToNumber(interp, argv[0], &v);
                    SEE_SET_NUMBER(res, sqrt(v.u.number));
            }
    }

When attaching cfunctions to an object, you may find the `SEE_CFUNCTION_PUTA()` macro useful. It performs both the `SEE_cfunction_make()` and `SEE_OBJECT_PUT()` operations in one step. Its signature is:

    void SEE_CFUNCTION_PUTA(struct SEE_interpreter *interp,
                    struct SEE_object *obj, const char *name,
                    SEE_call_fn_t func, int length, int attr);

The C function implementation must conform to the `SEE_call_fn_t` signature:

    typedef void (*SEE_call_fn_t)(struct SEE_interpreter *i,
                    struct SEE_object *obj, struct SEE_object *thisobj,
                    int argc, struct SEE_value **argv,
                    struct SEE_value *res);

Example: If you wanted to be able to call the C function `math_sqrt()` using the ECMAScript expression `sqrt()` from the [[Global]] name space, then use:

    SEE_CFUNCTION_PUTA(interp, interp->Global, "sqrt", math_sqrt, 1, 0);

The arguments to this function are described in the following table:

Argument | Purpose
--- | ---
`interp` | the current interpreter context
`self` | a pointer to the object called (`Math.sqrt` here)
`thisobj` | the `this` object (the `Math` object here) - may be `NULL`
`argc` | number of arguments
`argv` | array of value pointers, of length `argc`
`res` | uninitialised value location in which to store the result

A common convention in all ECMAScript functions is that unspecified arguments should be treated as `undefined`, and extraneous arguments should just be ignored. If the function uses `thisobj`, it should check any assumptions made about it, especially if it is expected to be a host object. This is because method functions can easily be attached to other objects by user code, and under other circumstances, the function can be called in a way that makes the `thisobj` pointer `NULL`.

When writing cfunctions, you can use the `SEE_parse_args()` convenience function to make argument processing easier. This function takes a format string and converts arguments according to the table below. It can throw a `TypeError` exception if a conversion error occurs.

    void SEE_parse_args(struct SEE_interpreter *interp,
            int argc, struct SEE_value **argv, const char *fmt, ...);
    void SEE_parse_args_va(struct SEE_interpreter *interp,
            int argc, struct SEE_value **argv, const char *fmt, va_list ap);

⚠ Note: The `SEE_parse_args()` function first appeared in API 2.0, and `SEE_parse_args_va()` in 3.0.

Format | Parameter type | Conversion applied | Result when `undefined`
--- | --- | --- | ---
`a` | `char **` | `SEE_ToString()`, then into an ASCII C string | `"undefined"`
`A` | `char **` | `NULL` if `undefined`, otherwise the same as format '`a`' | `NULL`
`b` | `int *` | `SEE_ToBoolean()`, then to `0` or `1` | `0`
`h` | `SEE_uint16_t *` | `SEE_ToUint16()` | `0`
`i` | `SEE_int32_t *` | `SEE_ToInt32()` | `0`
`n` | `SEE_number_t *` | `SEE_ToNumber()` | `SEE_NaN`
`o` | `struct SEE_object **` | `SEE_ToObject()` | `TypeError`
`O` | `struct SEE_object **` | `NULL` if `undefined` or `null`, otherwise the same as format '`o`' | `NULL`
`p` | `struct SEE_value *` | `SEE_ToPrimitive()` | `undefined`
`s` | `struct SEE_string **` | `SEE_ToString()` | `"undefined"`
`u` | `SEE_uint32_t *` | `SEE_ToUint32()` | `0`
`v` | `struct SEE_value *` | the argument is copied without conversion | `undefined`
`x` |  | the argument is ignored |
`z` | `char **` | `SEE_ToString()`, then into a UTF-8 C string | `"undefined"`
`Z` | `char **` | `NULL` if `undefined`, otherwise the same as format '`z`' | `NULL`
`|` |  | optional argument marker
`.` |  | throws a `TypeError` on further arguments
space |  | space character is ignored

The optional argument marker ('`|`') disables storing a result when the argument is `undefined` or not provided by the caller. This allows storage to be initialised to default values.

The '`a`' and '`A`' formats will throw a `TypeError` if the string contains non-ASCII characters. The '`a`', '`A`', '`z`' and '`Z`' formats will throw an error if the resulting string would contain a null character.

Example: Using `SEE_parse_args()` in an alternate implementation of `Math.sqrt()` method:

    static void
    math_sqrt_possible(interp, self, thisobj, argc, argv, res)
            struct SEE_interpreter *interp;
            struct SEE_object *self, *thisobj;
            int argc;
            struct SEE_value **argv, *res;
    {
            SEE_number_t n;

    	SEE_parse_args(interp, argc, argv, "n", &n);
    	SEE_SET_NUMBER(res, sqrt(n));
    }

A corresponding convenience function is provided for calling SEE function objects.

    void SEE_call_args(struct SEE_interpreter *interp,
            struct SEE_object *func, struct SEE_object *thisobj,
    	struct SEE_value *ret, const char *format, ...);
    void SEE_call_args_va(struct SEE_interpreter *interp,
            struct SEE_object *func, struct SEE_object *thisobj,
    	struct SEE_value *ret, const char *format, va_list ap);

⚠ Note: The `SEE_call_args()` and `SEE_call_args_va()` functions first appeared in API 3.0.

The `SEE_call_args()` function constructs a value argument array and then invokes `SEE_OBJECT_CALL()`. The format argument is explained in the following table.

Format | Parameter type | Conversion applied | Value generated
--- | --- | --- | ---
`a` | `char *` | ASCII C string | string
`A` | `char *` | ASCII C string, or NULL | string or `undefined`
`b` | `int` | none | boolean
`h` | `SEE_uint16_t` | none | number
`i` | `SEE_int32_t` | none | number
`l` |  | generates a `null` value | `null`
`n` | `SEE_number_t` | none | number
`o` | `struct SEE_object *` | none | object
`O` | `struct SEE_object *` | none, unless `NULL` | object or `undefined`
`p` | `struct SEE_value *` | `SEE_ToObject()` | object
`s` | `struct SEE_string *` | none, unless `NULL` | string or `undefined`
`u` | `SEE_uint32_t` | none | number
`v` | `struct SEE_value *` | the argument pointer is copied without conversion | same as input parameter type
`x` |  | generates an `undefined` value | `undefined`
`z` | `char *` | UTF-8 C string | string
`Z` | `char *` | UTF-8 C string or `NULL` | string or `undefined`
`*` | `unsigned char *, SEE_size_t` | 8-bit binary buffer copied byte-for-byte | string
space |  | space character is ignored

A cfunction may call 'back' into SEE using `SEE_Global_eval()`. In other words, cfunctions may be re-entrant. The traceback context is automatically maintained by SEE.

### 6.6 User function objects

Occasionally, a host application will wish to take some user text and create a callable function object from it. An example of this problem is in attaching the JavaScript code from HTML attributes onto form elements of a web page. One way to achieve this is to invoke the `Function` constructor object with the `SEE_OBJECT_CONSTRUCT()` macro, passing it the formal arguments text and body text as arguments. (See the ECMAScript standard for details on the `Function` constructor.)

Another way, that is more convenient if the user text is available as an input stream, is to use the `SEE_Function_new()` function:

    struct SEE_object *SEE_Function_new(struct SEE_interpreter *interp,
                    struct SEE_string *name, struct SEE_input *param_input,
                    struct SEE_input *body_input);

where any of the the `name`, `param_input` and `body_input` parameters may be `NULL` (indicating to use the empty string).

The returned function object may be called with the `SEE_OBJECT_CALL()` macro.

⚠ Note: Although the example above uses `SEE_Function_new()`, if you really are using SEE to build a web browser, this is probably not the best way to approach it. For implementing event handlers such as "onclick", you should instead look at using `SEE_eval()` on a string-valued attribute, and/or `SEE_OBJECT_CALL()` for when the attribute is exposed through a DOM.

### 6.7 Errors and Error objects

Host applications sometimes need to convey errors to ECMAScript programs. Errors in ECMAScript are typically indicated by throwing an exception with an object value. The thrown objects conventionally have `Error.prototype` somewhere in their prototype chain, and provide a `message` and `name` property which the `Error.prototype` reads to generate a human-readable error message.

Host applications can conveniently construct and throw error exceptions using the following macros:

    void SEE_error_throw(struct SEE_interpreter *interp,
                    struct SEE_object *error_constructor,
                    const char *fmt, ...);
    void SEE_error_throw_va(struct SEE_interpreter *interp,
                    struct SEE_object *error_constructor,
                    const char *fmt, va_list ap);
    void SEE_error_throw_string(struct SEE_interpreter *interp,
                    struct SEE_object *error_constructor,
                    struct SEE_string *string);
    void SEE_error_throw_sys(struct SEE_interpreter *interp,
                    struct SEE_object *error_constructor,
                    const char *fmt, ...);
    void SEE_error_throw_sys_va(struct SEE_interpreter *interp,
                    struct SEE_object *error_constructor,
                    const char *fmt, va_list ap);

These convenience macros construct a new error object, and throw it as an exception using `SEE_THROW()`. The object thrown is given a `message` string property that reflects the rest of the arguments provided to the called macro. The `SEE_error_throw_sys()` macro works like `SEE_error_throw()` but appends a textual description of `errno` using `strerror()`.

The `error_constructor` argument should be one of the error constructor objects found in the `SEE_interpreter` structure:

Member | Meaning
--- | ---
`Error` | runtime error
`EvalError` | error in `eval()`
`RangeError` | numeric argument has exceeded allowable range
`ReferenceError` | invalid reference was detected
`SyntaxError` | parsing error
`TypeError` | actual type of an operand different to that expected
`URIError` | error in a global URI handling function

Example: of how to throw a basic error:

    if (something_is_wrong)
            SEE_error_throw(interp, interp->Error, "something is wrong!");

Although `Error` is usually sufficient for most errors, host applications can create their own error constructor object with the `SEE_Error_make()` convenience function. Only one constructor of the same name should be created per interpreter.

    struct SEE_object *SEE_Error_make(struct SEE_interpreter *interp,
                    struct SEE_string *name);

## 7 Modules

SEE provides a module abstraction for host implementations that want a structured approach to adding their objects into a SEE interpreter.

⚠ Note: The module abstraction was introduced in API 2.0.

A `struct SEE_module` is a collection of functions that are automatically called by SEE at various stages of each intepreter initialisation. The module may initialise and insert its own objects into each interpreter before user scripts can be run.

    struct SEE_module {
            SEE_uint32_t      magic;
            const char       *name;
            const char       *version;
            unsigned int      index;        /* Set by SEE_module_add() */
            int             (*mod_init)(void);
            void            (*alloc)(struct SEE_interpreter *);
            void            (*init)(struct SEE_interpreter *);
    };

The `magic` field must be initialised to the constant value `SEE_MODULE_MAGIC`. The `name` field is currently unused, but should consist of a short, unique identifier corresponding to the name of the module. The `version` field is currently unused, and should be set to `NULL`. The `index` field is set by the `SEE_module_add()` function as the module is added to SEE. Each added module is given a unique index. Do not change the index.

The `mod_init` function pointer is called immediately the module is loaded (by `SEE_module_add()`). This is an opportunity for a module to obtain pointers to globally interned strings. (See `SEE_intern_global()` in §5.3.2.) The `mod_init` function is expected to return zero to indicate a successful initialisation. This pointer may be set to `NULL` if unneeded.

The `alloc` function is called after built-in objects have been allocated but before any other modules or built-in objects have been initialised. It is dangerous to make use of the interpreter at this stage. The main use of the `alloc` function pointer is to allow circular dependencies between modules. For most modules, the `alloc` pointer can be left as `NULL`.

The `init` function is called after all built-in objects and modules have been allocated, and after all built-in objects have been initialised. It is safe to make use of the interpreter built-ins at this stage, but not to make use of other modules. For most modules, the `init` function is the place to insert newly-created host objects into a pristine `interp->Global`.

A pointer to your module structure must be passed to `SEE_module_add()` before any interpreters are created. It is not possible to dynamically add modules once interpreters have been created because of the way the global intern table is managed. (If your module does not modify the global intern table, and your system is single-threaded, then you may be able to add the module dynamically.)

Finally, per-interpreter private storage for each module is provided through the `SEE_MODULE_PRIVATE()` macro. This macro evaluates to a `void *` lvalue that may be assigned dynamic storage during `alloc`.

    const SEE_uint32_t SEE_MODULE_MAGIC;
    int SEE_module_add(struct SEE_module *module);
    void *SEE_MODULE_PRIVATE(struct SEE_interpreter *, struct SEE_module *);

The `SEE_module_add()` function adds a module to the global list of modules initialised whenever a new interpreter is constructed. This function returns zero if the module was added successfully. It returns `-1` if an internal error occurred. Otherwise it returns the same non-zero value that the module's `mod_init` function hook returned. Once added, a module cannot be removed.

The interested reader is referred to the mod_File.c module example under the shell directory of the SEE source code.

## 8 Compatibility features

### 8.1 Compatibility with other JavaScript implementations

SEE provides backward-compatibility with earlier versions of JavaScript and JScript. These features ought never be used, since JavaScript program authors should be mindful of standards. Nevertheless, this section documents the compatibility modes that SEE supplies.

The behaviour of the SEE library is modified on a per-interpreter basis, by passing special flags to a variant of the interpreter's initialisation routine, `SEE_interpreter_init_compat()`. This function otherwise behaves just like `SEE_interpreter_init()` (see §2).

    void SEE_interpreter_init_compat(struct SEE_interpreter *interp,
                    int flags);

The `flags` parameter is a bitwise OR of the constants described in the following table.

⚠ Note: API 2.0 removed the `SEE_COMPAT_UNDEFDEF` and `SEE_COMPAT_EXT1` flags and introduced the `SEE_COMPAT_JSxx` flags.

Flag | Behaviour
--- | ---
`SEE_COMPAT_STRICT` | This is not really a flag. It is defined as zero, and can be used when no compatibility flags are wanted. SEE will operate in its default ECMA compliance mode.
`SEE_COMPAT_UTF_UNSAFE` | Treats overlong UTF-8 encodings as valid unicode characters. You should never need this.
`SEE_COMPAT_262_3B` | Enables optional features from Appendix B of ECMA-262 ed3, namely: defines `Date.prototype.toGMTString()`, equivalent to `toUTCString()` defines `Date.prototype.getYear()` and `Date.setYear()` defines `escape()` and `unescape()` in the global object defines `String.prototype.substr()`
`SEE_COMPAT_ERRATA` | Enables compatibility with Mozilla's ECMAScript Edition 3 Errata. (Added in API 3.0) `String.prototype.match()` returns `null` instead of an empty array when there are no matches.
`SEE_COMPAT_SGMLCOM` | This flag makes the lexical analyser stage treat the 4-character sequence '`<!--`' (at any place) and the 3-character sequence '`-->`' (when preceded by whitespace only) as if they were the '`//`' comment introducer. This is useful when parsing HTML SCRIPT elements.
`SEE_COMPAT_JS11` | Enables JavaScript 1.1 compatibility: The string representation of a bad date (e.g. `String(new Date(NaN))`) is returned as the string `"Invalid Date"`, instead of `"NaN"`. Calling `Date` as a constructor or function will recognise Netscape-style date strings of which one form is '`1/1/1999 12:30 AM`'. Conversions from a date to a string will include the timezone. Native objects synthesize a property called `__proto__` with the same value as the internal [[Prototype]] property (or `null`). Assignments to `__proto__` are accepted if they don't cause a cycle. [EXT:7 + EXT:8] Invalid `\u` or `\x` escapes will treat the leading `\u` or `\x` as a single-letter escape. This would be a lexical analyser error under ECMA. Regular expression instances have a [[Call]] property, which is essentially equivalent to `RegExp.prototype.exec()`. This has the side-effect of changing what the `typeof` operator returns when applied to regular expression instances. The `String.prototype` object is given the following methods that simply return the string, and ignore their arguments: `anchor`, `big`, `blink`, `bold`, `fixed`, `fontcolor`, `fontsize`, `italics`, `link`, `small`, `strike`, `sub` and `sup`. The `substr` method is also added. Enumerating over properties is done in a sorted fashion. During sort, property names are ordered arithmetically if they are suitable as array indicies, otherwise they are ordered lexicographically. [EXT:1] SEE's lexical analyser will recognise octal integers (i.e. integers starting with '0') and will fall back to decimal if the token contains a non-octal digit. Same with parseInt(). [EXT:4 + EXT:18] Coercing native values that do not have a [[DefaultValue]] internal property will return an object-unique string, instead of throwing a `TypeError`. [EXT:5 + EXT:6] `Function.prototype` will not have a `prototype` property of its own. [EXT:9] `Function.prototype.toString()` applied to built-in functions and constructors (which are not function instances) will return a bogus do-nothing FunctionDeclaration instead of throwing a `TypeError`. [EXT:13] The global object has its property [[Prototype]] property set to `Object.prototype`, effectively making all its properties available to the global scope, but having the good side effect of allowing `toString()` to work anywhere. [EXT:17] Calling `eval()` with a `this` different to the global object executes its contents with the scope and variable object always set to `this` (instead of inheriting the caller's context as per s10.2.2 of the standard). [EXT:23] Native functions assign themselves an `arguments` property when called, so that the old idiom of using `f.arguments` inside the function `f` will work. [EXT:2 + EXT:11 + EXT:12] The system-generated `arguments` object created inside a function has a default-value (a comma-separated string representing the arguments), instead of raising a `TypeError`. The upshot of this is that `arguments` can be coerced into a string. [EXT:14] Reserved words can be used as identifiers (with a warning message) [EXT:3] Invalid quantifiers in regular expressions (e.g. `/a{12x}/`) are treated as literals instead of raising a SyntaxError. [EXT:24] `RegExp` supports the [[HasInstance]] operator, meaning that `/x*/ instanceof RegExp` will work. [EXT:20] Change the token grammar to recognise simple character classes in literal regular expressions. This means the expression `/[/]/` will be parsed as if it were `/[\/]/`. [EXT:15] In regex character classes, three digit octal escape sequences beginning with `\0` are understood. [EXT:25] Regex execution leaves results in the `RegExp` object, in the properteis `$1` ... `$9`, `$_`, `$*`, `$+`, `$``, `$'`, `global`, `ignoreCase`, `input`, `lastIndex`, `lastMatch`, `lastParen`, `leftContext`, `multiline`, `rightContext`, and `source`. [EXT:21] The global function escape() returns uppercase hex digits, instead of lowercase. [EXT:19] `Array.join(undefined)` uses the string '`undefined`' as the join string instead of '`,`'. However when called without arguments will still use '`,`'. Also, `String.split(undefined)` will work in a corresponding reverse way. [EXT:16] String literals may contain LineTerminators only if escaped with backslash, in which case the escaped LineTerminator is ignored.
`SEE_COMPAT_JS12` | Enables JavaScript 1.2 compatibility: Includes all JavaScript 1.1 compatibility behaviour. The constructor `new Array()` when given a single numeric argument will return an array consisting of just that argument. e.g. `new Array(3)` is the same as `[3]`. This differs from the ECMA standard where an array of length 3 would be created, viz `[undefined,undefined,undefined]`. (JavaScript 1.2 only.) `Boolean` instance objects are converted to their logical value in expressions that are converted to boolean. This differs from the ECMA standard where all object instances are to be converted to `true`. For example, the condition in the statement `if (new Boolean(false))`statement, will be evaluated as `true` in ECMA, and `false` by JavaScript 1.2. (JavaScript 1.2 only.)`` `Array.prototype.toString()` and `Object.prototype.toString()` return string forms in literal notation, e.g. `"[1,2,3]"`, and `"{a:1, b:2}"`. (JavaScript 1.2 only.) `String.prototype.split()` when operating on the empty string `""` will return an empty array `[]` instead of an array consisting of the empty string, `[""]`. (JavaScript 1.2 only.) `String.prototype.split()`, when given a delimiter of exactly one space character (`" "`), will strip the leading whitespace from the string, and then split on `/\s+/`. (JavaScript 1.2 only.) The `Number()` function when applied to an array will return the array length, instead of `NaN`. (JavaScript 1.2 only.) The `Object.prototype.eval()` function is equivalent to the global `eval()` function and sets `this` to the object expected. (JavaScript 1.1 and 1.2 only.)
`SEE_COMPAT_JS13` | Enables JavaScript 1.3 compatibility: Includes JavaScript 1.1—1.2 compatibility behaviour.
`SEE_COMPAT_JS14` | Enables JavaScript 1.4 compatibility: Includes JavaScript 1.1—1.3 compatibility behaviour. The expression `v instanceof o` behaves differently when `o` has no [[HasInstance]] method. Instead of throwing an error, the [[Prototype]] chain of `v` is searched for `o.prototype`. If found, the expression results in true, otherwise false.
`SEE_COMPAT_JS15` | Enables JavaScript 1.5 compatibility: Includes JavaScript 1.1—1.4 compatibility behaviour. Permit conditional function declarations of the form `if (1) function foo (args) { body; }`. The statement becomes syntactically identical to `if (1) foo = function foo (args) { body; }`.

SEE now always optimises empty function calls by skipping the expensive process of extending the scope chain, creating an `arguments` property, etc. and just synthesizing `undefined` for the call, instead. This was an optional optimisation prior to SEE 2.0, but is now always in effect.

### 8.2 Compatibility with future versions of SEE

As distributed, SEE has two different version numbers:

1. the package, release and shared library version number (e.g. 2.0)
2. the API version number (e.g. 1.0)

The library version is available to programs to query through the `SEE_version()` function. This function returns a pointer to a static C string containing identifiers separated by a space character (`0x20`). The first identifier is the name of the library (e.g. `"see"`) and the second identifier is the package version number (e.g. `2.0`). Further identifiers indicate the features used when compiling the library. This string is useful for end users to determine what capabilities their library implementation has.

    const char *SEE_version(void);

The major and minor API version numbers indicate backward-compatible and backward-incompatible changes to the API, i.e the interface described in this documentation and the header files. The API version number is independent of the package and library version number.

Practically, developers should use the following code to signal the case of compiling against a future version of SEE with an API that isn't backward compatible with this document.

    #define DESIRED_SEE_API_MAJOR 2
    #if SEE_VERSION_API_MAJOR > DESIRED_SEE_API_MAJOR
     #warning "SEE API major version mismatch " #SEE_VERSION_API_MAJOR
    #endif

The rules I use for versioning future APIs are:

- If a function, type, extern or macro has been removed or changed since last release so that previous use is incompatible with future use, then the major version number is incremented and the minor version number is reset to zero.
- If a function, type, extern or macro has been added since last release such that its future use is incompatible with previous headers with the same API major version number, then the minor version number is incremented.

This document will indicate at what API version new API elements are added, defaulting to 1.0.

    const int SEE_VERSION_API_MAJOR;
    const int SEE_VERSION_API_MINOR;

### 8.3 Porting from API 1.0 to API 2.0

Applications previously written for SEE-1.3.1 (API 1.0) can be changed to compile against SEE-2.0 (API 2.0). If you want, both APIs can be supported by testing the macro `SEE_VERSION_API_MAJOR`. The following list indicates the differences and steps to take when porting API 1.0 code to API 2.0:

- The first field of a `struct SEE_objectclass`, has changed type from `struct SEE_string *Class` to `const char *Class`. You should use a simple C constant string to name the class.
- `void SEE_intern_global(struct SEE_string *)` has been replaced with `struct SEE_string *SEE_intern_global(const char *s)`. You can remove the static arrays of `SEE_char_t`, and use a simple C constant string. For example: `s_Foo = SEE_intern_global("Foo");`
- The interpreter `trace` callback function is called far less frequently and now takes an extra parameter of type `enum SEE_trace_event`. You may need to change the signature of functions you assign to the `trace` hook, and make use of the event information.
- The constants `SEE_COMPAT_UNDEFDEF` and `SEE_COMPAT_ARRAYJOIN1` has been removed. Replace them with zero.

### 8.4 Porting from API 2.0 to API 3.0

Applications previously written for SEE-2.0 (API 2.0) should be changed in order to compile against SEE-3.0 (API 3.0).

- Applications should call `SEE_init()` early in `main()`, and after any garbage collectors have been initialised. (This is currently optional, but will become mandatory in the next major version of SEE.)
- The most important change is that the property string argument of the following functions must have been internalised, usually with a call to `SEE_intern()`, or `SEE_global_intern()`.
  - `SEE_OBJECT_CANPUT()`
  - `SEE_OBJECT_DELETE()`
  - `SEE_OBJECT_GET()`
  - `SEE_OBJECT_HASPROPERTY()`
  - `SEE_OBJECT_PUT()`
  Similarly, if you have written a property enumerator, then the enumerator class's `next()` method must return property strings that are already internalised.
- The function `SEE_no_enumerator` has been deprecated. Please use `NULL` instead. This usually occurs when initialising the `Enumerator` field of a `SEE_objectclass` structure.
- The `SEE_STRING_FLAG_STATIC` flag for strings has been deprecated. Do not use it.

## 9 Security

The SEE library provides a simple framework for the host application to manage security contexts for scripts and host functions.

⚠ Note: The `SEE_interpreter.sec_domain`, `SEE_objectclass.get_sec_domain`, and `SEE_system.transit_sec_domain` fields were introduced in API 2.0.

The host application manages the 'current' security domain by setting the interpreter's `sec_domain` field. During execution, when callable objects are created, they inherit the value of the interpreter's `sec_domain` field. When an object is called, the host application is given the opportunity of changing the current security domain.

Just before an object is called (either through the `SEE_OBJECT_CALL()` or `SEE_OBJECT_CONSTRUCT()` macro), SEE takes the following steps:

1. If `SEE_system.transit_sec_domain` is `NULL`, then no security domain modification occurs, and execution continues; otherwise
2. If the object's class does not provide a `get_sec_domain()` method, then no modification occurs, and execution continues; otherwise
3. The `SEE_OBJECT_GET_SEC_DOMAIN()` macro is called to obtain the function's security domain.
4. If the function's security domain is identical to the current security domain (pointer comparison), then no modification occurs, and execution continues; otherwise
5. SEE calls the `SEE_system.transit_sec_domain()` function, which is expected to change the `sec_domain` field of the interpreter if needed.
6. Execution continues, but if an exception occurs during the call, or the object's call completes successfully, then the old value of `sec_domain` is restored to the interpreter before the return value or exeception is propagated.

The interpreter's `sec_domain` field is initially set to `NULL` by `SEE_interpreter_init()`. Consequently, all built-in SEE function objects constructed during initialisation will have a security domain of `NULL`. This also applies to modules, unless they explicitly change the current security context during their `init()` handler.

The following functions (amongst others) are sensitive to the interpreter's `sec_domain` field and will record it in any callable objects they produce:

- `SEE_Global_eval()`,
- `SEE_Function_new()`,
- `SEE_cfunction_make()`,

Apart from the `SEE_OBJECT_CALL()` and `SEE_OBJECT_CONSTRUCT()` macros, which only restore the `sec_domain`, no other function in the SEE library changes the interpreter's `sec_domain` value.

⚠ Note: If the interpreter's `sec_domain` field is somehow changed without restoration during an inner function, it will eventually be restored to its original value as the function returns. This is simply a consequence of a caller invoking `SEE_OBJECT_CALL()` or `SEE_OBJECT_CONSTRUCT()`. You should not rely on this side-effect.

### 9.1 Guidelines for using the security framework

If you plan to make use of SEE's security framework for foreign code, I recommend you follow the Java principals model used both by Java and Mozilla by following these guidelines:

1. Design a domain structure that represents a set of principals. A principal is a named entity which the user would recognise; e.g. another user, or a web site. You should provide functions for checking if a principal is in a set, and also to compute the intersection of two sets. You should also provide an 'empty' set constant which is not the `NULL` pointer.
2. Design a structure to hold authorization statements depening on the way your user will express them. These statements relate permisions to individual principals. These questions could be prompted dynamically, or might be read from an authorization file. For example, the user may want to express the authorization statement

   > all principals matching foo@bar.com are granted FileRead permission on resources matching /public/*

3. Write a function `checkPermission(interp, permission, resource)` that searches the authorization statements and throws an exception if the current domain (the principal set stored in `interp->sec_domain`) does not have the required permission. Call this function from the sensitive places of your code.
4. Implement the domain transition function `SEE_system.transit_sec_domain()` so that it efficiently computes the intersection of the current and the callee's security domain and sets it to be the current domain. Note that SEE's built-in functions will have a `NULL` domain and can be treated as completed trusted, that is `NULL` makes no change to the current security domain.
5. When your application receives source text from a trusted or untrusted source, then before calling `SEE_Global_eval()`, `SEE_Function_new()`, or even `SEE_cfunction_make()`, first set the interpreter's `sec_domain` field to reflect exactly the principal that controls the source. Be mindful to restore the security domain when you have finished, especially during exceptions, like so:

       void
       eval_in_domain(interp, input, input_sec_domain, result)
       	struct SEE_interpreter *interp;
       	struct SEE_input *input;
       	void *input_sec_domain;
       	struct SEE_value *result;
       {
       	SEE_try_context_t c;
       	void *saved_sec_domain;

       	saved_sec_domain = interp->sec_domain;
       	interp->sec_domain = input_sec_domain;
       	SEE_TRY(interp, c) {
                       SEE_Global_eval(interp, input, result);
       	}
       	interp->sec_domain = saved_sec_domain;
       	SEE_DEFAULT_CATCH(interp, c);
       }

## 10 Debugging facilities

### 10.1 Debugging the SEE library (for developers)

The SEE library contains various debugging facilities that are omitted if it is compiled with the `NDEBUG` preprocessor define.

These functions are intended for the developer to use while application debugging, and not for general use.

    void SEE_PrintValue(struct SEE_interpreter *interp,
                    struct SEE_value *val, FILE *file);
    void SEE_PrintObject(struct SEE_interpreter *interp,
                    struct SEE_object *obj, FILE *file);
    void SEE_PrintString(struct SEE_interpreter *interp,
                    struct SEE_string *str, FILE *file);
    void SEE_PrintContextTraceback(struct SEE_interpreter *interp,
                    SEE_try_context_t *context, FILE *file);
    void SEE_PrintTraceback(struct SEE_interpreter *interp,
                    FILE *file);

If debugging the library itself, it is worth reading the source code to find the debug flag variables that can be turned on by the host application to enable verbose traces during execution.

Defining the `NDEBUG` preprocessor symbol when building the library also disables (slow) internal assertions that would otherwise help show up application misuse of the API.

When using gdb on Unix, you can save a lot of heartache by using libtool to invoke it. Libtool knows what to do.

    $ ./libtool --mode=execute gdb shell/see-shell

### 10.2 Debugging scripts (for users)

The SEE library does not contain a script debugger, however it does provide an interpreter hook for external debuggers and the see-shell example tool contains an example of using it.

The interpreter structure provides a `trace` callback field, which is called on certain events during execution (function call, return, throw or statement). The callback is also passed a handle to the current execution context, (a `struct SEE_context *`) and an external debugger may examine it directly, or indirectly via the `SEE_context_eval()` utility function, which is otherwise functionally identical to `SEE_Global_eval()`. `SEE_context_eval()` is intended only for use by external debuggers attached to the `trace` callback.

⚠ Note: During a debugger's execution, the `trace` callback should be disabled by setting it to `NULL`, otherwise re-entrant tracing can occur.

⚠ Note: The signature and frequency of calling the `trace` hook changed between API 1.0 and API 2.0.

    void SEE_context_eval(struct SEE_context *context,
                    struct SEE_string *expr, struct SEE_value *res);

If see-shell is invoked with the -g option, then immediately before it executes the first script, it will prompt the user for debugging operations.

Commands available at the '`%`' prompt include:

`break` [filename`:`]lineno
  add a new breakpoint
`show`
  show current breakpoints
`delete` number
  delete existing breakpoint
`step`
  step to a new line
`cont`
  continue execution
`where`
  print traceback information
`info`
  print context information
`eval` expr
  evaluate and print an expression in the current context
`throw` expr
  throw an exception

## References

- ECMA-262, ECMAScript language specification, 3rd edition, December 1999.
- W Horwat, ECMAScript Edition 3 Errata
- The Boehm-Weiser garbage collection package for C and C++, accessed March 2004
- Hoffman et al., UTF-16, an encoding of ISO 10646 [RFC 2781], February 2000
- Boehm, Advantages and Disadvantages of Conservative Garbage Collection, accessed March 2004
- Unicode Inc., Unicode 2.1.9, April 1999
- Netscape Communications Corp., Client-Side JavaScript Reference 1.3, 1997
- Netscape Communications Corp., Client-Side JavaScript Reference 1.4, 1998
- Netscape Communications Corp., Client-Side JavaScript Reference 1.5, 2000

## Name index

SEE_ABORT SEE_ALLOCA SEE_CFUNCTION_PUTA (2.0) SEE_CAUGHT SEE_call_args (3.0) SEE_call_args_va (3.0) SEE_cfunction_make SEE_context_eval SEE_COPYSIGN (3.0) SEE_DEFAULT_CATCH SEE_ENUM_NEXT SEE_Error_make SEE_error_throw SEE_error_throw_string SEE_error_throw_sys SEE_error_throw_sys_va (3.0) SEE_error_throw_va (3.0) SEE_eval (3.0) SEE_Function_new SEE_gcollect (2.0) SEE_Global_eval SEE_growable struct (3.0) SEE_GROW_INIT (3.0) SEE_grow_to (3.0) SEE_Infinity SEE_init (3.0) SEE_input struct SEE_inputclass struct SEE_INPUT_CLOSE SEE_input_file SEE_INPUT_NEXT SEE_input_string SEE_input_utf8 SEE_intern SEE_intern_ascii (2.0) SEE_intern_global (2.0*) | SEE_interpreter_init SEE_interpreter_init_compat SEE_interpreter_restore_state (3.0) SEE_interpreter_save_state (3.0) SEE_ISFINITE SEE_ISNAN SEE_ISNINF (3.0) SEE_ISPINF (3.0) SEE_malloc SEE_malloc_string SEE_malloc_finalize (2.0) SEE_mem_exhausted_hook SEE_mem_free_hook SEE_mem_malloc_hook SEE_mem_malloc_string_hook SEE_module struct (2.0) SEE_module_add (2.0) SEE_MODULE_MAGIC (2.0) SEE_MODULE_PRIVATE (2.0) SEE_NaN SEE_native struct SEE_native_init SEE_NEW SEE_NEW_ARRAY SEE_NEW_FINALIZE (2.0) SEE_NEW_STRING_ARRAY SEE_NUMBER_ISFINITE SEE_NUMBER_ISNAN SEE_NUMBER_ISNINF SEE_NUMBER_ISPINF SEE_object struct SEE_objectclass struct SEE_OBJECT_CALL SEE_OBJECT_CANPUT SEE_OBJECT_CANPUTA (2.0) SEE_OBJECT_CONSTRUCT | SEE_OBJECT_DEFAULTVALUE SEE_OBJECT_DELETE SEE_OBJECT_DELETEA (2.0) SEE_OBJECT_ENUMERATOR SEE_OBJECT_GET SEE_OBJECT_GETA (2.0) SEE_OBJECT_GET_SEC_DOMAIN (2.0) SEE_OBJECT_HASINSTANCE SEE_OBJECT_HASPROPERTY SEE_OBJECT_HASPROPERTYA (2.0) SEE_OBJECT_HAS_CALL SEE_OBJECT_HAS_CONSTRUCT SEE_OBJECT_HAS_ENUMERATOR SEE_OBJECT_HAS_GET_SEC_DOMAIN (2.0) SEE_OBJECT_HAS_HASINSTANCE SEE_Object_new SEE_OBJECT_PUT SEE_OBJECT_PUTA (2.0) SEE_object_instanceof (3.0) SEE_parse_args (2.0) SEE_parse_args_va (3.0) SEE_PrintObject SEE_PrintString SEE_PrintContextTraceback (3.0) SEE_PrintTraceback SEE_PrintValue SEE_RETHROW (3.0) SEE_SET_BOOLEAN SEE_SET_NULL SEE_SET_NUMBER SEE_SET_OBJECT SEE_SET_STRING SEE_SET_UNDEFINED SEE_string struct SEE_string_addch SEE_STRING_ALLOCA | SEE_string_append SEE_string_append_ascii (2.0) SEE_string_append_int SEE_string_append_unicode (3.0) SEE_string_cmp SEE_string_concat SEE_string_dup (2.0*) SEE_string_fix (3.0) SEE_string_fputs SEE_string_literal SEE_string_new SEE_string_sprintf SEE_string_substr SEE_string_toutf8 (2.0) SEE_string_utf8_size (2.0) SEE_string_vsprintf SEE_THROW SEE_ToBoolean SEE_ToInt32 SEE_ToInteger SEE_ToNumber SEE_ToObject SEE_ToPrimitive SEE_ToString SEE_ToUint16 SEE_ToUint32 SEE_TRY SEE_TRY_BREAK (3.0) SEE_value struct SEE_VALUE_COPY SEE_VALUE_GET_TYPE SEE_version SEE_VERSION_API_MAJOR SEE_VERSION_API_MINOR

© David Leonard, 2008. This documentation may be entirely reproduced and freely distributed, as long as this copyright notice remains intact, and either the distributed reproduction or translation is a complete and bona fide copy, or the modified reproduction is subtantially the same and includes below this copyright statement a brief summary of the modifications made.

    $Id: USAGE.html 1369 2008-02-09 12:41:33Z d $