| Internal documentation for the aif library. |
| |
| AIF stands for "architecture-independent form". Any data structure in any |
| language should be convertable to an AIF. The AIF may be safely shipped from |
| machine to machine and converted back to an equivalent data structure. |
| |
| An AIF is a struct with fields for the format-descriptor string (fds) and the |
| data (with explicit length). The fds uses characters to indicate the type. |
| All bytes are represented in the data by two hex characters, representing upper |
| nibble then lower nibble. The characters and formats have changed over time. |
| This is the currently operative list: |
| |
| address: aN |
| - Represents an address value |
| - N is a single digit specifying the number of bytes of data |
| |
| aggregate: {ID|N1=T1,...; N2=T2,...; N3=T3,...; N4=T4,...} |
| - Used for struct and class types |
| - ID is an optional name for the aggregate |
| - Nn is the name of the field |
| - Tn is a format string representing the type of the field |
| - The type specifier is divided into four sections separated by ";" |
| - The first section is used to store public access fields (eg: N1) |
| - The second section is used to store protected access fields (eg: N2) |
| - The third section is used to store private access fields (eg: N3) |
| - The fourth section is used to store package access fields (eg: N4) |
| - Structures only supply fields in the public section |
| |
| array: [R]T |
| - R is a range indicating low and high bounds. If R is empty then |
| this is a 0 element array. |
| - T is a format string representing the base type |
| - Multi-dimension arrays are represented as an array of base type array |
| - Itself uses 0 bytes of data, but the components may use data |
| |
| boolean: bN |
| - Represents a true/false value |
| - N is a single digit specifying the number of bytes of data |
| - The data for a true value is non-zero |
| - The data for a false value is 0 |
| |
| character: c |
| - Represents a single character |
| - The data size is a single byte |
| - Characters are always unsigned |
| |
| C-style string: paN |
| - aN is an address type |
| - The first N bytes of data are the address value |
| - The next 2 bytes of the data indicate the length (more significant |
| byte first) of the string in bytes. These bytes follow immediately. |
| - There is no null included in the string |
| |
| enumeration: <ID|S1=V1,S2=V2,...>isN |
| - ID is an optional name for the type |
| - Sn=Vn are name/value tuples where Sn is the name of the |
| enumerated value and Vn is the value of the enumeration. |
| - The value of the enumeration is an integer whose type |
| is "isN" (signed integer of length N bytes) |
| |
| floating: fN |
| - Represents a floating point value of arbitrary length |
| - N is a single digit specifying the number of bytes of data |
| |
| function: &A1,A2,.../T |
| - Represents a function that returns type T |
| - A1, A2, ... are the types of each formal parameter |
| - Data consists of a null-terminated string containing |
| the name of the function |
| |
| integer: i(s|u)N |
| - Represents a signed or unsigned integer value of arbitrary length |
| - s means signed; u means unsigned |
| - N is a single digit specifying the number of bytes of data |
| |
| named component: %N/T |
| - N is a number |
| - T is a format string representing the component |
| - Uses 0 bytes of data |
| |
| pointer: ^aNT |
| - aN is an address type |
| - T is the type of the pointer target (possibly of > form) |
| - The first byte in the data is a type, with value: |
| 0 to indicate a null pointer |
| 1 to indicate a normal value |
| 2 to indicate a normal value that will be referred to later. |
| 3 to indicate that the value is a circular reference |
| 4 to indicate an invalid pointer value |
| - A null pointer (type 0) has no data. |
| - Data for a normal pointer (type 1) comprises N bytes of the |
| address value, followed by the target. |
| - Data for a named pointer (type 2) comprises a name, N bytes of the |
| address value, then the target data. |
| - Data for a reference pointer (type 3) comprises a name followed by |
| N bytes of the address value. |
| - Data for an invalid pointer (type 4) comprises N bytes of |
| the address value. |
| - Names are 4 byte unsigned integers |
| |
| range: rL,NT |
| - IF N>0, represents a range from L to L+N-1, inclusive |
| - If N==0 the range is empty |
| - L and N are integer types specified by T |
| |
| reference to named component: >N/ |
| - Used in circular linked types to make representation finite |
| - N is a number |
| - Uses 0 bytes of data |
| |
| string: s |
| - Represents an arbitrary length character string |
| - The first 2 bytes of the data indicate the length (more significant |
| byte first) of the string in bytes. These bytes follow immediately |
| |
| union: (ID|N1=F1,N2=F2,...) |
| - Similar to a structure, but all fields start at the same address |
| - ID is the identifier for the union, it is optional |
| - Nn is the name of the field |
| - Fn is a format string representing the field |
| - The size of the union will be max(sizeof(F1),...sizeof(FN)) |
| |
| void: vN |
| - Represents a void type |
| - N is the number of bytes of data |
| |
| ZPL region: zNT |
| - Represents a ZPL region of rank N. |
| - Type T is the type of the data describing |
| the bounds of each rank and must be an integer type. The data |
| consists of pairs of integers describing the lower and upper |
| bounds of each rank respectively |
| |
| invalid: ?n? |
| - n is an integer code (currently only 0) |
| - 0 bytes of data |
| |
| The construction routines allow a client to build most reasonable AIFs, but in |
| building data-circular AIFs requires using lower-level access. For arrays, it |
| is necessary to generate the data portion of the array using low-level |
| mechanisms before using our constructors to make the final AIF. |