# Generalized Agile Transport System (GATS)

GATS is a data encoding format, as well as a set of libraries for reading and
writing data in that format.  It's a structured format reminiscent of a binary
json, but with some extra cool features.

 * All numbers (integers and floating point) are stored in an arbitrary
   precision format which takes up the least amount of space it can.
 * Unlike textual formats (like json, xml, etc.) floating point numbers are
   stored exactly, the exact number you write in is the exact number you read
   out.
 * All formats stored are machine independent, you can read and write them on
   any architecture, any endianness and they will always be the same.  No more
   encoding worries.
 * There are a number of data types you can use to make up data structures:
   * Dictionaries
   * Lists
   * Integers
   * Floats
   * Strings (binary 8-bit strings, perfect for UTF-8)
   * Booleans
   * Nulls

# License

GATS is distributed under a new-BSD type license.  This is fairly permissive,
but if you require other licensing options feel free to contact us.

# Uses

GATS was originally intended for use in internet protocols, and is great for
that purpose.  Used correctly it allows you to create efficient yet highly
malleable protocols with very little extra effort.

However, you can certainly use it for other purposes such as serializing data
for storage, and inter-process communication.  In fact, with the different
language bindings available, sometimes GATS may be one of the easier ways to
allow, say, a PHP web service to communicate with a custom C++ executable or
python program.

# Languages/Libraries Supported

At the moment we actively maintain libraries for C++, java, php, and python.
Other languages and libraries are welcomed.  Here's a little info on each
target directory:

 * ''c++-libbu++'' - The original libgats implementation.  Works using libbu++
   data types and streams.  You need to have libbu++ and Xagasoft build in
   order to build this version.
 * ''c++-qt'' - A version written using Qt data types.  This version builds using
   qmake, so if you're using Qt you already have everything you need.  Also
   features handy signals & slots to make event driven networking even easier!
 * ''java'' - A library using the Java native interfaces, everything looks and
   works exactly how you would expect it should.  There is a Xagasoft Build
   script to build a jar file, but it's simple enough that a single javac
   command can build it all, or just import the code into your project directly.
   This java version has been used on desktops and android devices.
 * ''php'' - There are two libraries for working with php, the first defines a
   set of classes for fine control over the format, sometimes this is necessary
   as php's types are a little loose.  The second simply uses php native types
   like array() as data transport.  The second option is usually the much easier
   to use, but doesn't always get the encoding correct for all inputs.
 * ''python'' - These work like other serialization mechanisms in Python like
   pickle, json, shelve, and marshal.  It exposes the functions load, dump,
   loads, dumps, and also the handy helpers recv and send for working with
   sockets.  The Python implementation returns and transmits native Python
   data types, which makes life pretty easy.  To use this version simply copy
   gats.py to your project.

# Basic Operation

The way GATS works is dictated by the format, so it works similarly in every
implementation, although they each have slightly different mechanics.  When
encoding GATS you always encode each object in it's own "GATS packet."  A GATS
packet has a very simple header which includes the size of the packet to make
parsing fast and efficient.

Each packet can contain a single root object.  It can be any type, but for most
protocols a dictionary is a great choice for the root object.

The format is designed to make it very easy to work with various encoding,
packing, and encryption systems.  The reader, by default, will skip all leading
zero bytes that come before a valid GATS packet, and will stop processing
precisely at the end of a valid GATS packet.

Skipping leading zeros makes it easy to work in environments where padding may
be required.  You can use the simplest of all padding schemes (pad with zeros)
and it will work seamlessly with GATS.

Since the reader always reads exactly the number of bytes it needs, it's very
easy to embed GATS packets in other streams, or read them sequentially as fast
as you can from a socket.

## A Note About Strings

All strings in GATS are simply sequences of 8-bit bytes.  There is no
overarching encoding that is dictated by the format.  When using GATS it is
good to specify how you are encoding your text data, we recommend Unicode.
There is a possibility that a future version of GATS will include a separate
Unicode String data type, but for now it's important to remember this.

For this reason, we also recommend making the keys in all dictionaries 7-bit
UTF-8 compatible ASCII/Latin1.  This isn't required of course, but it makes
things a bit easier.

# Speed vs Size

GATS objects are, on average, smaller than storing in other binary formats, and
can be much smaller than textual formats by virtue of storing only as many
bytes as necessary for integers and floats.  This also means that GATS requires
more processing than fixed field binary formats, but interestingly not quite as
much as text formats like json.  The processing we do on floats is actually
roughly comparable in many ways to text processing, although with fewer steps.