view release on metacpan or  search on metacpan

lib/Text/ZPL.pm  view on Meta::CPAN

=head1 NAME

Text::ZPL - Encode and decode ZeroMQ Property Language

=head1 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

=head1 DESCRIPTION

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

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

As a simple example, a C<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' ]
      }
    }
  }

=head2 decode_zpl

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

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

=head2 encode_zpl

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

=head3 TO_ZPL

A blessed object can provide a B<TO_ZPL> method that will supply a plain
C<HASH> or C<ARRAY> (but see L</CAVEATS>) to the encoder:

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

=head2 CAVEATS

Not all Perl data structures can be represented in ZPL; specifically,
deeply-nested structures in an C<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 (C<ARRAY> references).

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

=head1 SEE ALSO

The L<Text::ZPL::Stream> module for processing ZPL piecemeal.

The bundled L<zpl_to_pl> script for examining parsed ZPL.

=head1 AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

=cut