This is a C library implementation of the FOA encoding, designed to be an alternative to XML for data exchange between i.e. web services. It can also be useful as a general encoding format similar to JSON.
The memory footprint of the library is small because it will never use more memory than required to hold the longest single line of data to decode.
The library can decode or encoded data using either a memory buffer (char *) or an file stream (FILE *). No validation is performed except for some rudimentary checks.
The library don't use any global variables or shared state, this makes it thread safe.
This section briefly describes the FOA encoding. Each encoded line contains either data (could be an array entry or an object member) or an special char. Each special char or data item must be followed by a newline (\n) character. The special chars are
'(' (begin object),
'[' (begin array),
']' (end array) and
')' (end object).
Each data, array or object (type) can also be named by
'name = type'. Arrays and objects can be unlimited nested in each other.
item := (name '=' data | data) + '\n' data := text | spec name := text - '=' text := any char spec := ()
Viewed from another angle: all encoded rows follows the pattern
'[name = ] data\n' (*), where the name is optional (the data is anonymous) and data is either one of '()' or another expression like (*).
This is an example of how an array (named arr) containing two structures (persons with named members) will be encoded:
arr = [ ( name = Albert Einstein born = March 14, 1879 ) ( name = Isaac Newton born = December 25, 1642 ) ]
See the encoding page for more examples.
If escaping is turned on (the default), then all special chars will be escaped when encoding and unescaped when decoding (they are replaced by HTTP encoded equivalents). This is all transparent to the library user. The escaping can be turned off thru foa_set_mode() to improve performance.