# NAME

# 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 <[email protected]>