view release on metacpan or  search on metacpan

lib/Data/Transform.pm  view on Meta::CPAN

get() is the greedy form of get_one().  It accepts an array reference
containing unprocessed stream chunks, and it adds that data to the
filter's internal buffer.  It then parses as many full items as
possible from the buffer and returns them in another array reference.
Any unprocessed data remains in the filter's buffer for the next call.

This should only be used if you don't care how long the processing takes.
Unless responsiveness doesn't matter for your application, you should
really be using get_one_start() and get_one().

=cut

sub get {
  my ($self, $stream) = @_;
  my @return;

  $self->get_one_start($stream);
  while (1) {
    my $next = $self->get_one();
    last unless @$next;
    push @return, @$next;
  }

  return \@return;
}

=head2 put ARRAYREF

put() serializes items into a stream of octets that may be written to
a file or sent across a socket.  It accepts a reference to a list of
items, and it returns a reference to a list of marshalled stream
chunks.  The number of output chunks is not necessarily related to the
number of input items.

=cut

sub put {
  my ($self, $packets) = @_;
  my @raw;

  foreach my $packet (@$packets) {
    if (blessed $packet and $packet->isa('Data::Transform::Meta')) {
      if (my @ret = $self->_handle_put_meta($packet)) {
        push @raw, @ret;
      }
      next;
    } elsif (my @data = $self->_handle_put_data($packet)) {
      push @raw, @data;
    }
  }

  return \@raw;
}

=head2 meta

A flag method that always returns 1. This can be used in e.g. POE to check
if the class supports L<Data::Transform::Meta>, which all Data::Transform
subclasses should, but L<POE::Filter> classes don't. Doing it this way
instead of checking if a filter is a Data::Transform subclass allows for
yet another filters implementation that is meant to transparently replace
this to be used by POE without changes to POE.

=cut

sub meta {
  return 1;
}

=head2 clone

clone() creates and initializes a new filter based on the constructor
parameters of the existing one.  The new filter is a near-identical
copy, except that its buffers are empty.

=cut

sub clone {
  my $self = shift;
  my $type = ref $self;
  croak "$type has to implement a clone method";
}

=head2 get_pending

get_pending() returns any data remaining in a filter's input buffer.
The filter's input buffer is not cleared, however.  get_pending()
returns a list reference if there's any data, or undef if the filter
was empty.

Full items are serialized whole, so there is no corresponding "put"
buffer or accessor.

=cut

sub get_pending {
  my $self = shift;

  return [ @{$self->[0]} ] if @{$self->[0]};
  return undef;
}

=head1 IMPLEMENTORS NOTES

L<Data::Transform> implements most of the public API above to help
ensure uniform behaviour across all subclasses. This implementation
expects your object to be an array ref. Data::Transform provides
a default implementation for the following methods:

=over 2

=item get(), get_one_start(), get_one()

get() is implemented in terms of get_one_start() and get_one(). Since
having to handle L<Data::Transform::Meta> packets means that you have
to keep a list of incoming packets, it is highly unlikely that you
will ever need to override get_one_start(), since all it does is add
to the list. It assumes the list is kept as an array ref in the first
entry of your object's list.

get_one is in turn implemented in terms of the following two methods: