NAME

Data::Focus::Lens - base class for lenses

DESCRIPTION

Data::Focus::Lens is the base class for all lenses in Data::Focus framework.

This class implements nothing except for operator overloads. See "OVERLOADS" for detail.

ABSTRACT OBJECT METHODS

This interface is experimental for now. You should not implement them by hand. Use Data::Focus::LensMaker instead.

All lens implementations must implement the following methods.

$f_whole_after = $lens->apply_lens($applicative_class, $part_mapper, $whole_before)

Apply the $lens and the $part_mapper to $whole_before, and obtain the result ($f_whole_after).

$applicative_class is the name of a Data::Focus::Applicative subclass. Generally speaking, it specifies the "context" in which this lens operation is performed.

$part_mapper is a code-ref with the following signature.

    $f_part_after = $part_mapper->($part_before)

where $part_before is a data part in $whole_before. The return value $f_part_after is an object of $applicative_class. Calling $part_mapper->($part_before) indicates that $lens focuses on the $part_before.

$whole_before is the target data for the $lens.

Return value $f_whole_after is the result of applying the $lens to $whole_before, wrapped in an object of $applicative_class.

A typical implementation of apply_lens() does the following.

1. Extract data parts from $whole_before. We call them as @parts here.

2. Apply $part_mapper to @parts.

       @f_parts_after = map { $part_mapper->($_) } @parts

3. Collect all @f_parts_after together to build the result. To unwrap Data::Focus::Applicative wrappers of @f_parts_after, we use build() method.

       $f_whole_after = $applicative_class->build(sub {
           my (@parts_after) = @_;
           my $whole_after = ...;
           return $whole_after;
       }, @f_parts_after)

   The callback passed to build() method is supposed to set @parts_after into the $whole_before (whether or not it's destructive), and return the $whole_after.

4. Return $f_whole_after obtained from build() method.

OVERLOADS

The "." operator is overloaded. It means lens composition.

    $composite_lens = $lens1 . $lens2

See Data::Focus::Lens::Composite for detail.

AUTHOR

Toshio Ito, <toshioito at cpan.org>