ZPL: ZeroMQ Property Language
=============================

The ZeroMQ Property Language (ZPL) defines a minimalistic
framing language for specifying property sets, expressed as a
hierarchy of name-value property pairs.

Goals
-----

ZPL is designed to represent a property set, where each property
has a name and a value. Properties are hierarchical, i.e.
properties can contain other properties. It aims to:

 - Be easy to read and edit, using visual clues for semantics.
 - Be minimalistic in terms of syntax.
 - Be trivial to parse in any programming language.
 - Be usable as a continuous stream of name/value updates.
 - Be able to represent hierarchical data structures.
 - Be neutral with respect to data typing.
 - Reduce the risk of human error to as close to zero as possible.

The use cases for ZPL include:

 - Configuration files edited by hand where readability is key.
 - Streamed data exchange.
 - Streamed logging.

Specification
-------------

ZPL is an ASCII text format that uses whitespace - line endings
and indentation - for framing and hierarchy. ZPL data consists
of a series of properties encoded as name/value pairs, one per
line, where the name may be structured, and where the value is
an untyped string.

Implementations should treat any of the following sequences as a
line-ending: newline (%x0A), carriage-return (%x0D), or
carriage-return followed by newline (%x0A %x0D).

Here is a typical example of a ZPL file:

.. code-block::

    1. ZPL configuration file example
    1. This format is designed to be trivial to write and parse
    #
    context
        iothreads = 1
        verbose = 1      #   Ask for a trace

    main
        type = zmq_queue
        frontend
            option
                hwm = 1000
                swap = 25000000
                subscribe = "#2"
            bind = tcp://eth0:5555
        backend
            bind = tcp://eth0:5556

Notes:
------

 - Whitespace is significant only before property names and
   inside values.
 - Text starting with '#' is discarded as a comment.
 - Each non-empty line defines a property consisting of a name
   and an optional value.
 - Values are untyped strings which the application may
   interpret in any way it wishes.
 - An entire value can be enclosed with single or double quotes,
   which do not form part of the value.
 - Any printable character except the closing quote is valid in
   a quoted string.
 - A value that starts with a quote and does not end in a
   matching quote is treated as unquoted.
 - There is no mechanism for escaping quotes or other characters
   in a quoted string.
 - The only special characters in ZPL are: whitespace, '#', '=',
   and single and double quotes.
 - Hierarchy is signaled by indentation, where a child is
   indented 4 spaces more than its parent.
 - The first non-whitespace character in a ZPL file is always
   either '#' or an alphanumeric character.
 - Whitespace following after a value is discarded unless within
   valid quotes.

Names SHALL match this grammar:

.. code-block::

    name = *name-char
    name-char = ALPHA | DIGIT | "$" | "-" | "_" | "@" | "." | "&" | "+" | "/"


Justification and Design
------------------------

ZPL exists because alternatives were inadequate:

 - XML cannot be read or written as a stream.
 - JSON cannot be read or written as a stream and is clumsy to
   edit due to delimiters between item lists.
 - YAML is relatively complex to parse.
 - UNIX-style configuration syntax does not support name
   hierarchies.

The use of significant whitespace may be controversial. It is
meant to be easier to create and verify manually than syntax
elements such as braces. It eliminates the need for separators.
The fixed 4-character indentation is meant to avoid confusion
and errors when fragments of ZPL files from different sources
are mixed together.

The lack of type awareness and other semantic validation is
deliberate. ZPL is not meant to be a formal grammar but a
simple-to-parse framing for name/value pairs. It emulates 0MQ
insofar as it frames data but does not attempt to inspect or
validate that data.


Backlog
-------

 - Add travis CI
 - Implement Serialization
 - Implement Cython based Parsing/Serialization
