pyzpl 0.1.8

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:

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:

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

• Implement Serialization of Streams

• Add travis CI

• Implement Cython based Parsing/Serialization

Changelog

todo (add based on git commit message parsing)