Cogs are generic, yet arbitrarily complex, data structures.
The name comes from an acronym - Configurable Object Graph. Each Cog object is a node, and they can be hooked together in various ways to form mathematical graph networks. The types are configurable rather than hard-coded. Thus, the name.
Cogs are designed to store the many types of “payload” data encountered in a system. This data is typically just a record-like structure (named values), but may also consist of lists or nested hierarchies. The primitive data stored within is often of indeterminate type, so conversions between e.g. string and numeric types need to be easy.
Cogs are also designed to be simple and natural to use from a script, and to remove a lot of the bulk code required to build complex objects. They are designed to be flexible and forgiving, rather than strict and rigid.
Cogs can be used in two major ways. The first is “untyped”, where there is no schema or assigned type for the cog’s nodes. Untyped cogs can be used for temporary or casual data storage, or for cases when (e.g. loading old files for backwards compatibility) you don’t want to apply validation rules to the data.
“Typed” cogs, on the other hand, have a CogSchema and a data type associated with them. This data type describes the cog’s organization and metadata, such as the defined fields for a structure, the allowed contents for a list, etc. It contains user-oriented items such as field labels and descriptions, and also contains validation rules that can be run on the data.
Cogs consist of nodes, connected together in a hierarchy, doubly-linked so that you can traverse both up and down the structure. Cogs can be treated as primitives (leaf nodes), as lists or associations, or as structures, depending on need and upon the data type.
An optional CogHeader is defined only for the root Cog in a structure; this contains pointers to the schema and maintains event listeners and dispatch.
Cogs fit very naturally into XML format, since the nodes form hierarchical documents. CogXmlLib provides simple reading and writing methods for this format.
Cogs intentionally form a separate, language- and platform-independent typing and data modeling system from Java. Cogs are readable from other platforms, and the type and metadata associated with them are expressed in generic terms. However, it is also useful to use Cog as a serialization method for Java, and direct support for this is provided via the Coggable interface.
Cogs are designed to be flexible and easy to use rather than high-performance. Other data structures are more appropriate if performance is a priority.
All of this sounds very complicated, but they are in fact quite easy to use.