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>