> ⚠️ **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/Specification.md](https://github.com/joeedh/STRUCT/blob/master/documentation/Specification.md).

# Terminology

# Grammar

    ID => [a-zA-Z_+][a-zA-Z0-9]*
          ID . ID

    header => ID {
              ID 'id' = NUMBER {

    type => int
            float
            bool
            byte
            double
            short
            string
            static_string [ NUMBER ]
            ID
            abstract(TYPE)
            abstract(TYPE, STRING)
            array(TYPE)
            array(ITERNAME, TYPE)
            iter(TYPE)
            iter(ITERNAME, TYPE)
            iterkeys(ITERNAME, TYPE)

    field => ID : TYPE
             ID : TYPE | JSCODE
    
    fieldlist => field ;
                 fieldlist field ;
               
    STRUCT => header fieldlist }

# Semantics

## Endianness

Data shall be written in network (big) byte order.

## Type definitions

### int

The 'int' type is defined to be a signed 32-bit integer

## byte

The 'byte' type is defined to be an unsigned 8-bit integer.

## bool

The 'bool' type is defined to be an unsigned 8-bit integer. Is cast to a boolean when read from file.

### float

The 'float' type is defined to be a signed 32-bit float

### double

The 'double' type is defined to be a signed 64-bit float

### short

The 'short' type is defined to be a signed 16-bit signed integer

### string

The string type is defined to be an unsigned array of 8-bit integers, encoded with UTF8.

#### Semantics

Strings shall be written in these steps:

1. Write size of final, encoded byte array as a signed 32-bit integer.
1. Write encoded byte array.

## static_string

The static_string type is a fixed-sized unsigned array of 8-bit integers. String data that is too long must be truncated
to fit within the array; data is too short must be padded with zeros.

## Object type

Object types declared without abstract() are written via their STRUCT definitions.

## Abstract object type

Object types saved with abstract() must save a signed integer ID referencing their struct definition within the STRUCT
manager that created them, then write the object as above.

If the client passes an additional string, it will be used in JSON mode as the property key to store the struct name;
otherwise "_structName" will be used.

## Array

Arrays may be variable length, of any valid STRUCT type, including abstract types.

### Semantics

To write an array:

1. Write a 32-bit signed integer representing array length
2. Write each array item according to STRUCT type rules.

## Iter

The Iter type is written identically to Array, but relaxes the requirement for direct, contiguous arrays for whatever
iterator protocol is appropriate for the language (which differs between ES5.1 and ES6).

## IterKeys

The IterKeys iterates over an object's own keys (using a for-in loop). Like array and iter it takes an optional iter key
argument.

Example:

    object : iterkeys(e, Something) | this.object[e].getSomething();