view release on metacpan or  search on metacpan

Iterator_en.pod  view on Meta::CPAN

If a data path is provided, the referenced element may point to one of it's ancestors. It will be resolved anyway.

=item element()

- How it works

If element reaches the end of a data structure, element() called in a following loop will start again with the first element.

If you bail out of a structure-parsing loop, following calls to element() will resume parsing at the point it was interrupted.

If you don't want this, call reset(). This will reset (sic!) element() to the beginning of the structure.

This works for partial structures (data path provided) as well. You should pass the appropriate data path to reset().

Note: calling several element()-s with different data paths do I<not> interfere.

Same applies to keys() rsp. values(). These won't interfere with element()-s.


-Data

element() sets these data fields of its object:

@{$dobj}{'path','val','key','level','vref','ppath','parent'}

Ok. this feature is not very OO-ish, but it allows for getting the results of the last element() call.
This does I<not> apply if a value was set via element().

- Files

You cannot write to files/handles referenced via "-File:...", \*Glob or FileHandle-objects. See item "Pseudo arrays".

- Autovivification:

If you pass a data path to element(), pointing to an element with an inexisting ancestor(s), no ancestor(s) will be created automagically. This differs from Perl's standard lookup feature.

OTHO, if a value is I<set> via element(), ancestors will be generated as necessary.

=item Levels

element() returns the nesting level of the current element, relative to the current root. The level is counted from 0.

That is, level 0 of the root structure is not identical to level 0 of a substructure, which can reside on any level of the root structure.

Accordingly the option -DigLevel limits digging always to n levels deep from the current root


=back


=over 2

=item Data paths, format

You can pass data paths to element(), keys() and values() in different formats.

Standard is the Perl-like format for Hashes/Arrays:

 my $path = "{'key1'}{'key2'}[2][1]";

If you are too busy to write all the brackets and braces, this will do ok:

 my $path = 'key1.key2.2.1';

If you choose not to use brackets/braces, hash keys have to contain at least one non-numerical character. Otherwise they will be taken as an array index - and will cause a non-fatal error plus warning.

Additionally you can define an arbitrary delimiter to separate keys/indices - quite useful, if the . occurs within a hash key:

 my $path = "#key1#key2#2#1";

Note:

- If the first character of the path non-alphanumeric, it will be treated as separator. Except for [ and {.

- If the first character is alphanumeric, the . will be used as separator.

- You may combine bracket-/braceless keys/indices "normal" ones: "#key1{key2}[2]#[1]"

- Better avoid using the backslash \ as separator.

- Quoting of hash keys is not mandatory.

=item Handling of Coderefs

Coderefs will be resolved by executing the referenced code. This happens on initialization of the respective element.

Before execution, $SIG{__WARN__} and $SIG{__DIE__} are redirected locally to point to some replacement routine. So, errors generated by the referenced code won't let your script die().

Messages generated by the code's calls to warn() or die() get captured.

The return values of the referenced code are stuffed into a "pseudo array" and return by element() rsp. values() subsequently.

If the first element of the code's results array contains an array named {'__ERR__'}, the code has warn()ed or carp()ed or execution was cancelled by die() or croak().

You can check for the messages' prefix ('WARN : ' or 'FATAL: ') to see what happened.

=item Pseudo arrays

Results of parsing "-FILE:..."- or coderef-elements are retrieved as pseudo arrays.

Pseudo because these do not exist as real arrays - they just look alike. That is, you cannot read/write these "arrays'" elements directly by providing the respective data path.

The reason is, Iterator does not modify the original data structure in any way, and thus does not know/generate a handle/data path that would allow for "direct access".

=back


=head2 B<7. Version>

=over 2

=item 0.021 dated from: 30.12.2000

bugfix release:

 - Squashed a bug preventing iteration over array objects
   if data path is given
 - Cleaned up some "Use of uninitialized value..."-warnings
 - Example code corrected

=item 0.02 dated from: 10.12.2000