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 );
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
Text::ZPL::Stream
AUTHOR
Jon Portnoy <
[email protected]>
