NAME

Text::ZPL::Stream - Streaming ZPL decoder

SYNOPSIS

use Text::ZPL::Stream;

my $stream = Text::ZPL::Stream->new;

if ( $stream->push($zpl_chrs) ) {
  # Parsed at least one complete line:
  my $ref = $stream->get;
  # ...
}

# Or in a loop:
while ( defined(my $zpl_chrs = magically_get_some_zpl) ) {
  $stream->push($zpl_chrs);
}
my $ref = $stream->get;
# ...

DESCRIPTION

A streaming decoder for ZeroMQ Property Language files using Text::ZPL.

See the Text::ZPL documentation for more on ZPL and parsing-related details.

new

my $stream = Text::ZPL::Stream->new(
  # Optional:
  max_buffer_size => 512,
);

Constructs an object representing a new ZPL stream.

Accepts the following options:

max_buffer_size

The maximum line length allowed in buffers before an exception is thrown.

Defaults to 0 (unlimited).

push

$stream->push(@chars);
$stream->push($string);

Takes characters (individually or as strings) and collects until an end-of-line marker (\r, \n, or \r\n) is encountered, at which point a parse is called and the reference returned by "get" is altered appropriately.

An exception is thrown if parsing fails, or if "max_buffer_size" is reached -- if you're unsure of your incoming data, you may want to wrap push calls with Try::Tiny or similar.

Returns the number of complete lines parsed, which can be useful as an indicator that "get" ought be called:

if ( $stream->push($zpl) ) {
  # Parsed at least one complete line:
  my $ref = $stream->get;
  ...
}

get

my $ref = $stream->get;

Returns the HASH reference to the decoded structure.

This is the actual reference in use by the decoder, not a copy! Altering the structure of the HASH may have unintended consequences, in which case you may want to make use of "dclone" in Storable to create a safe copy.

get_buffer

Returns a string containing the current character buffer (that is, any incomplete line).

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>