NAME

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

VERSION

version 1.03

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 is a role for mapper classes. Mappers can be attached to other streams to filter, expand and transform their data.

Mapper API is 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 the context, mappers can map input or output streams, or be attached to other mappers to construct more complex mappers.

The common way to create a new mapper is to use mapper(&) function from Flux::Simple. Alternatively, you can consume Flux::Mapper role in your class and implement write, write_chunk and commit methods.

| 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 sure that your mapper 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::Role::Easy instead of this role.

SEE ALSO

mapper() function from Flux::Simple.

Flux::Mapper::Role::Easy.

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.