# 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](http://rfc.zeromq.org/spec:4) for details.

Exports two functions by default: ["decode\_zpl"](#decode_zpl) and ["encode\_zpl"](#encode_zpl). This
module uses [Exporter::Tiny](https://metacpan.org/pod/Exporter::Tiny) to export functions, which allows for flexible
import options; see the [Exporter::Tiny](https://metacpan.org/pod/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](https://metacpan.org/pod/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"](#caveats)).

### TO\_ZPL

A blessed object can provide a **TO\_ZPL** method that will supply a plain
`HASH` or `ARRAY` (but see ["CAVEATS"](#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](https://metacpan.org/pod/Text::ZPL::Stream) module for processing ZPL piecemeal.

The bundled [zpl\_to\_pl](https://metacpan.org/pod/zpl_to_pl) script for examining parsed ZPL.

# AUTHOR

Jon Portnoy <avenj@cobaltirc.org>