NAME

Iterator::Flex::Manual::Internals - How Things Work

VERSION

version 0.12

DESCRIPTION

Object

An iterator is an object. It is composed from a base class (Iterator::Flex::Base) and a number of roles. (Some iterators use a subclass of Iterator::Flex::Base, but they should be rewritten as roles.)

The object is a blessed code reference (not a hash). This allows the iterator to be called without method lookup overhead:

  $iter = iterator { ... };
  $value = $iter->();

The roles incorporate optional capabilities or different ways of implementing a behavior (e.g., signaling exhaustion via throwing an exception versus returning a sentinel). They are also used to implement interfaces to alien iterators.

Object Attributes

Storage for object attributes is done via the "inside-out" object model. Attributes are stored in the %Iterator::Flex::Utils::Registry hash, keyed off of the internal memory address of the object obtained via "refaddr" in Scalar::Util. The entry in the registry is deleted upon object destruction.

Each registry entry is a hash, with the following structure (constants for the keys are available from Iterator::Flex::Utils):

  $Registry{ref address}
    + -- { +ITERATOR }
         + -- { +CURRENT }
         + -- { +METHODS }
         + -- { +NEXT }
         + -- { +PREV }
         + -- { +RESET }
         + -- { +REWIND }
         + -- { +STATE }
         + -- { +_DEPENDS }
         + -- { +_NAME }
         + -- { +_ROLES }
    + -- { +GENERAL }
         + -- { +INPUT_EXHAUSTION }
         + -- { +EXHAUSTION }
         + -- { +ERROR }

Object Construction

There are two steps to object construction:

1. Class construction

2. Object iteration

Class Construction

Classes can be constructed using the factory or via Iterator::Flex::Base or a subclass thereof.

The fundamental constructor is Iterator::Flex::Base::new_from_attrs. Everything else calls it. It accepts two hash arguments, one for parameters specific to the particular iterator, the other for specifying general behaviors, such as how the iterator should signal exhaustion or error.

Roles

• Iterator::Flex::Role::Freeze

• Iterator::Flex::Role::Current::Method

• Iterator::Flex::Role::Current::Closure

• Iterator::Flex::Role::Next::Closure

• Iterator::Flex::Role::Next::ClosedSelf

• Iterator::Flex::Role::Reset::Method

• Iterator::Flex::Role::Reset::Closure

• Iterator::Flex::Role::Exhaustion::Return

• Iterator::Flex::Role::Exhaustion::PassthroughThrow

• Iterator::Flex::Role::Exhaustion::Throw

• Iterator::Flex::Role::Exhaustion::ImportedReturn

• Iterator::Flex::Role::Exhaustion::ImportedThrow

• Iterator::Flex::Role::Rewind::Method

• Iterator::Flex::Role::Rewind::Closure

• Iterator::Flex::Role::State::Registry

• Iterator::Flex::Role::State::Closure

• Iterator::Flex::Role::Utils

• Iterator::Flex::Role::Wrap::Return

• Iterator::Flex::Role::Wrap::Self

• Iterator::Flex::Role::Wrap::Throw

• Iterator::Flex::Role::Prev::Method

• Iterator::Flex::Role::Prev::Closure

• Iterator::Flex::Role::Error::Throw

SUPPORT

Bugs

Please report any bugs or feature requests to bug-iterator-flex@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Iterator-Flex

Source

Source is available at

  https://gitlab.com/djerius/iterator-flex

and may be cloned from

  https://gitlab.com/djerius/iterator-flex.git

SEE ALSO

Please see those modules/websites for more information related to this module.

• Iterator::Flex

• Iterator::Flex::Manual

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007

cpanm Iterator::Flex

perl -MCPAN -e shell
install Iterator::Flex