Name

Object::Relation::Iterator - Object::Relation iterator class

Synopsis

  use Object::Relation::Iterator;

  my $iter = Object::Relation::Iterator->new(\&closure);
  while (my $thing = $iter->next) {
      # Do something with $thing.
  }

Description

This class provides an iterator interface for accessing a list of items, generally Object::Relation objects. Users generally won't create iterator objects directly, but will get them back from calls to the search() method of Object::Relation::Handle.

The basic interface for iterator objects is the next() instance method. This method will return each item in turn, and will return undef when there are no more items. Therefore, no item can actually be undef.

Class Interface

Constructors

new

  my $iter = Object::Relation::Iterator->new(\&code_ref);
  my $iter = Object::Relation::Iterator->new(\&code_ref, \&destroy_code_ref);

Constructs and returns a new iterator object. The code reference passed as the first argument is required and must return the next item to iterate over each time it is called, and undef when there are no more items. undef cannot itself be an item. The optional second argument must also be a code reference, and will only be executed when the iterator object is destroyed (that is, it will be called in the DESTROY() method).

Throws:

Fatal::Invalid

Instance Interface

Instance Methods

next

  while (my $thing = $iter->next) {
      # Do something with $thing.
  }

Returns the next item in the iterator. Returns undef when there are no more items to iterate.

current

  my $current = $iter->current;

Returns the current item in the iterator--that is, the same item returned by the last call to next().

peek

  while ($iter->peek == 1) {
      $iter->next;
  }

Returns the next item to be returned by next() without actually removing it from the list of items to be returned. The item returned by peek() will be returned by the next call to next(). After that, it will not be available from peek() but the next item will be.

all

  for my $item ($iter->all) {
      print "Item: $item\n";
  }

Returns a list or array reference of all of the items to be returned by the iterator. If next() has been called prior to the call to all(), then only the remaining items in the iterator will be returned. Use this method with caution, as it could cause a large number of Object::Relation objects to be loaded into memory at once.

do

  $iter->do( sub { print "$_[0]\n"; return $_[0]; } );
  $iter->do( sub { print "$_\n"; return $_; } );

Pass a code reference to this method to execute it for each item in the iterator. Each item will be set to $_ before executing the code reference, and will also be passed as the sole argument to the code reference. If next() has been called prior to the call to do(), then only the remaining items in the iterator will passed to the code reference. Iteration terminates when the code reference returns false, so be sure to have it return a true value if you want it to iterate over every item.

request

  my $request = $iter->request;
  $iter->request($intermediate_representation);

In the event that the iterator was created by a Object::Relation::search request, this method will return the intermediate representation (IR) generated by the Object::Relation::Parser. This IR is an array reference of Object::Relation::Search objects. This is useful if you have an iterator but need to know how the results were generated.

The returned request will be a hash reference with the keys being the query parameter keys and the values being the search object which corresponds to the given column.

Due to the extremely complicated nature of some searches, this request at the present time only stores simple searches. Simple searches are those which implicitly AND their search terms via the comma operator.

 name => 'foo', age => GE 21

Searches with AND or OR compounds are considered complex searches and are not stored completely:

 name => 'foo', OR(age => GE 21)

Copyright and License

Copyright (c) 2004-2006 Kineticode, Inc. <info@obj_relode.com>

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

cpanm Object::Relation

perl -MCPAN -e shell
install Object::Relation