> ⚠️ **DEPRECATED** — This wiki is no longer maintained. The current documentation lives in
> [`/documentation`](https://github.com/joeedh/STRUCT/tree/master/documentation).
> See the equivalent page: [documentation/Reading-And-Writing.md](https://github.com/joeedh/STRUCT/blob/master/documentation/Reading-And-Writing.md).

The API for serializing a STRUCT-registered class instance is straightforward enough:

    var data = [];
    nstructjs.manager.write_object(data, anObject);

The API for reading files is slightly different.  Let's have STRUCT read the data it just wrote:

    data = new DataView(new Uint8Array(data).buffer); 
    //STRUCT reads from DataViews, but writes to simple arrays
    var anObject2 = nstructjs.manager.read_object(data, anObject.constructor);

# Handling data structure changes

## Writing STRUCT scripts with file data

STRUCT has facilities to handle changes in data structures.  The basic idea is to save a copy of the STRUCT scripts used to generate a given file inside that file.  You generate this copy with `nstructjs.write_scripts()`, which you save before the file contents with nstructjs.binpack.write_string.  Note that **you must use `nstructjs.write_scripts()`,** or else the abstract keyword will not work.

To save space, the 'abstract' keyword does not store the full type of an object, instead it stores an integer ID reference to that object's type within the STRUCT system.  These IDs are assigned by a simple incrementer; thus, any changes to the _order_ of STRUCT registrations will change extant IDs.

This is where `nstructjs.write_scripts()` comes in: If you look at its output, you'll see stuff like this:

    mymodule.SomeClass id=1 {
    }

### File Writing Example
Here's a simple example of generating a file with embedded STRUCT scripts:

    var data = [];
    //generate id-enabled struct scripts.  note that helper JS code will be excluded.
    var scripts = nstructjs.write_scripts()
    
    //write utf8 representation of scripts.
    nstructjs.binpack.pack_string(data, scripts);

    //write object
    nstructjs.manager.write_object(anObject);
    
## Reading saved STRUCT scripts

Continuing the example above, we need to load a file with the STRUCT scripts saved in that file.  To do so,
we have to create our own instance of nstructjs.STRUCT (the class of nstructjs.manager):
    
    var load_manager = new nstructjs.STRUCT();

And then feed it the saved scripts buffer.  Assuming we have the output of the previous example, we have to first get a DataView:

`    data = new DataView(new Uint8Array(data).buffer);`

Then we have to create a "unpack context," which is basically an ArrayBuffer file pointer:

    //create unpack context
    var uctx = new nstructjs.binpack.unpack_ctx();

Next, we read the scripts definition string:

`    var scripts = nstructjs.binpack.unpack_string(data, uctx);`

And then we feed it to load_manager.

`    load_manager.parse_structs(scripts);`

We can now use load_manager to read the rest of our file:

`    var anObject2 = load_manager.read_object(data, anObject.constructor, uctx);`