NAME

Text::ZPL - Encode and decode ZeroMQ Property Language

SYNOPSIS

# Decode ZPL to a HASH:
my $data = decode_zpl( $zpl_text );

# Encode a HASH to ZPL text:
my $zpl = encode_zpl( $data );

# From a shell; examine the Perl representation of a ZPL document:
sh$ zpl_to_pl my_config.zpl

DESCRIPTION

An implementation of the ZeroMQ Property Language, a simple ASCII configuration file format; see http://rfc.zeromq.org/spec:4 for details.

Exports two functions by default: "decode_zpl" and "encode_zpl". This module uses Exporter::Tiny to export functions, which allows for flexible import options; see the Exporter::Tiny documentation for details.

As a simple example, a ZPL file as such:

# This is my conf.
# There are many like it, but this one is mine.
confname = "My Config"

context
    iothreads = 1

main
    publisher
        bind = tcp://eth0:5550
        bind = tcp://eth0:5551
    subscriber
        connect = tcp://192.168.0.10:5555

... results in a structure like:

{
  confname => "My Config",
  context => { iothreads => '1' },
  main => {
    subscriber => {
      connect => 'tcp://192.168.0.10:5555'
    },
    publisher => {
      bind => [ 'tcp://eth0:5550', 'tcp://eth0:5551' ]
    }
  }
}

decode_zpl

Given a string of ZPL-encoded text, returns an appropriate Perl HASH; an exception is thrown if invalid input is encountered.

(See Text::ZPL::Stream for a streaming interface.)

encode_zpl

Given a Perl HASH, returns an appropriate ZPL-encoded text string; an exception is thrown if the data given cannot be represented in ZPL (see "CAVEATS").

TO_ZPL

A blessed object can provide a TO_ZPL method that will supply a plain HASH or ARRAY (but see "CAVEATS") to the encoder:

# Shallow-clone this object's backing hash, for example:
sub TO_ZPL {
  my $self = shift;
  +{ %$self }
}

CAVEATS

Not all Perl data structures can be represented in ZPL; specifically, deeply-nested structures in an ARRAY will throw an exception:

# Simple list is OK:
encode_zpl(+{ list => [ 1 .. 3 ] });
#  -> list: 1
#     list: 2
#     list: 3
# Deeply nested is not representable:
encode_zpl(+{
  list => [
    'abc',
    list2 => [1 .. 3]
  ],
});
#  -> dies

Encoding skips empty lists (ARRAY references).

(The spec is unclear on all this; issues welcome via RT or GitHub!)

SEE ALSO

The Text::ZPL::Stream module for processing ZPL piecemeal.

The bundled zpl_to_pl script for examining parsed ZPL.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>