NAME

Flux::Mapper - objects for transforming input or output streams.

VERSION

version 1.02

SYNOPSIS

$new_item = $mapper->write($item);
# or when you know that mapper can generate multiple items from one:
@items = $mapper->write($item);

$new_chunk = $mapper->write_chunk(\@items);

@last_items = $mapper->commit; # some mappers keep items in internal buffer and process them at commit step

$mapped_in = $in | $mapper; # resulting object is a input stream
$double_mapper = $mapper1 | $mapper2; # resulting object is a mapper too
$mapped_out = $mapper | $out # resulting object is a output stream

DESCRIPTION

Flux::Mapper instances can be attached to other streams to filter, expand and transform their data.

It's API is currently identical to Flux::Out, consisting of write, write_chunk and commit methods, but unlike common output streams, values returned from these methods are always getting used.

Depending on context, mappers can map input or output streams, or be attached to other mappers to construct more complex mappers.

The easiest way to create a new mapper is to use mapper(&) function from Flux::Simple. Alternatively, you can inherit your class from Flux::Mapper and implement write and/or write_chunk methods (and optionally commit too).

| operator is overloaded by all mappers. It works differently depending on a second argument. Synopsis contains some examples which show the details.

Mappers don't have to return all results after each write call, and results don't have to match mapper's input in one-to-one fashion. On the other hand, there are some mapper clients which assume it to be so. In the future there'll probably emerge some specializations expressed in roles.

INTERFACE

write($item)

Process one item and return some "mapped" (rewritten) items.

Number of returned items can be any, from zero to several, so returned data should always be processed in the list context, unless you're absolutely sure that your filter is of one-to-one kind.

write_chunk($chunk)

Process one chunk and returns another, rewritten chunk.

Rewritten chunk can contain any number of items, independently from the original chunk, but it should be an arrayref, even if it's empty.

commit()

commit method can flush cached data and return remaining transformed items as plain list.

If you don't need flushing, just return (), or use Flux::Mapper::Easy instead of this role.

AUTHOR

Vyacheslav Matyukhin <me@berekuk.ru>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Yandex LLC.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.