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>