A better example may help. Here is some actual pseudo code (that is, some actual code stripped down and with names changed to protect the innocent). Notice how different iterators can share the same lookup cache per database handle, and other iterators can be conditionally injected into the stream.

for my $dbh ( @db_handles) {
  my ( $crud_cache, $crud_stuff_cache, $stuff_name_cache) = ({},{},{})
+;

  my @filter_foo_name;
  if ($do_some_filtering) {
    @filter_foo_name = ( \&filter_foo_name, { FILTER => $this } );
  }

  my $f = mk_iterator(
    { DBH => $dbh, BIND => SQL_INTEGER },
    \&get_foo, { WHERE_CLAUSE => $where{$dbname} },
    \&get_wibble,
    \&get_stuff,
    \&get_crud,
    [
      \&get_more_important_stuff,
      \&get_foo_wibble_id,
      \&get_bar_wibble_id,
      \&get_foo_name,
      @filter_foo_name,
      \&get_bar_name,
      \&get_foo_wibble_thingy_id,
      \&get_bar_wibble_thingy_id,
      \&get_foo_crud_id,
      \&get_bar_crud_id,
      \&get_foo_crud_name, { CACHE => $crud_cache },
      \&get_bar_crud_name, { CACHE => $crud_cache },
      \&get_foo_crud_stuff, { CACHE => $crud_stuff_cache },
      \&get_bar_crud_stuff, { CACHE => $crud_stuff_cache },
    ],
    [
      \&get_stuff_name,
      \&get_stuff_type,
      \&get_stuff_this_and_that,
      \&get_stuff_this_name,
        { OUTER => 1, BIND => SQL_VARCHAR, CACHE => $stuff_name_cache 
+},
      \&get_stuff_that_name,
        { OUTER => 1, BIND => SQL_VARCHAR, CACHE => $stuff_name_cache 
+},
      \&get_foo_crud_stuff, { OUTER => 1, CACHE => $crud_stuff_cache }
+,
      \&get_bar_crud_stuff, { OUTER => 1, CACHE => $crud_stuff_cache }
+,
    ],
  );

  while ( my $row = $f->() ) {
    # do stuff w/$row which is a hashref 
    # w/all the keys from the SELECT array refs (see
    # sql_iterator() example below).
    #
    # Update: Actually, since there are array refs
    # in the iterator constructor, the actual href here
    # will contain all of the keys from the first
    # four iterators, and for each of those values,
    # it will iterate through values containing
    # keys from the first array ref, then through
    # values containing keys from the second array ref
    print join(",", $@row{qw(FOO_WIBBLE_ID FOO_NAME BAR_WIBBLE_ID BAR_
+NAME ETC ETC)}), "\n";
  }
}
[download]

And many of the iterator generator functions share the same code, with only the SELECT and ARG list differing, e.g.:

sub get_foo_wibble_id {
  sql_iterator(
    SQL =>
      "select WIBBLE_ID\n".
      "from WIBBLE_TABLE\n".
      "where STUFF_ID = ?\n".
      "and IMPORTANT_ID = ?\n",
    SELECT => ['FOO_WIBBLE_ID'],
    ARGS => [qw(STUFF_ID FOO_THINGY_ID)],
    @_,
  )
}

sub get_bar_wibble_id {
  get_foo_wibble_id(
    SELECT => ['BAR_WIBBLE_ID'],
    ARGS => [qw(STUFF_ID BAR_THINGY_ID)],
    @_,
  )
}
[download]

More update: Since the iterator is basically the same as a DBI fetchrow_hashref(), the "# do stuff" is whatever you would do after fetching a row from a database. But instead of doing one big SQL statement that joins many tables, I have many separate iterators each selecting from a (usually) single table with the iterators joined together.

Why do it this way? In my case, it was because I was working with a completely undocumented and confusing database schema. I was constantly commenting out some of the inner loops/joins and seeing if the outer loops were returning what I wanted. In one big SQL statement with joins, this would require commenting out columns in the SELECT clause, the tables in the FROM clause, and expressions in the WHERE clause. Using the above scheme, I could comment out just ONE LINE to eliminate an inner join...usually commenting out one line at a time from the bottom up in the mk_iterator call. Using the TRANSFORM option, I could do things that SQL alone wouldn't do, or would be hard to do. Though using this, you are limited in some ways, most notably in how useful any ORDER BY clause is. Hope that explains things :-)

I think this example would be clearer if you gave some details about what values $row transitions through here. That is, what might the code that replaces "# do stuff" look like?

- tye        

Just for fun, here is a completely runnable abstract example that doesn't use SQL at all, we are instead iterating over various lists that sort of simulate selecting a single column from several joined tables (No, you probably wouldn't really want to do this sort of hard coded list iterator this way, but it would be a good way to splice in hardcoded lists as sort of a Cartesian join on some SQL when combined with the SQL iterators):

use strict;
use warnings;

use DBIx::Iterator qw(mk_iterator list_iterator);

my $iter = mk_iterator(
  \&list_123,
  [
    \&list_abc,
    \&list_def,
  ],
  [
    \&list_456,
    \&list_789,
  ],
);

use Data::Dumper qw(Dumper);
while ( my $r = $iter->() ) {
  print Dumper($r);
}

sub list_ab {
  my $x = shift;
  my $y = shift;
  list_iterator(
    LIST => [ map {[$_]} $x..$y ],
    SELECT => [ "$x$y" ],
    @_,
 )
}

sub list_123 { list_ab(1,3,@_) }
sub list_456 { list_ab(4,6,@_) }
sub list_789 { list_ab(7,9,@_) }
sub list_abc { list_ab("a","c",@_) }
sub list_def { list_ab("d","f",@_) }
[download]

Why UNIVERSAL::isa? Do you expect people to pass in blessed references? Do you want to forbid tied variables?

Why UNIVERSAL:­:isa? Do you expect people to pass in blessed references? Do you want to forbid tied variables?

You confuse me. Some of the advantages of isa are that it doesn't forbid blessed references and it doesn't forbid tied variables.

One of the problems with using isa() as a function instead of as a method is that items that pretend to be some type of data structure via overloading are not detected by direct use of UNIVERSAL::isa() alone. One way to help isa() is for such classes to implement their own isa() method. Unfortunately, that work-around is often quite inconvenient for code like above to make use of (because $ref->isa("HASH") is most likely to just die, even though it works better for this one case).

A much better (IMHO) work around would be for such an overloading class to do push @ISA, "HASH"; so that UNIVERSAL::isa( $ref, "HASH" ) would be true.

Doing a tiny bit of testing, I see that UNIVERSAL::isa() is somewhat pickier than I assumed and to make this work one must also do something to create the "HASH" package, for example, { my $no_op= @HASH::ISA; }.

So I consider UNIVERSAL::isa() to be a "best practice" because it gets (as near as I can tell) all but the one rarest case right, it is very simple and easy to understand (doing *isa= \&UNIVERSAL::isa; makes it even nicer), and that one rarest case is nearly trivial to make work as well.

A patch to overload.pm do this push @ISA, "HASH" and create the HASH package (etc.) when appropriate would be well worthwhile, IMHO. I apologize that I won't be attempting such a patch any time soon for a number of reasons.

I hope I got that all correct. :)

Update: And let me address one potential complaint that I've seen before. One other aspect of UNIVERSAL::isa() is that you can use the technique I gave above to lie, intentionally making UNIVERSAL::isa() incorrectly return a true value for your objects. This aspect does not bother me because "Doctor, it hurts when I do this", that is, if you want to go out of your way to intentionally break my simple code, I just don't care. More importantly, such an ability can prove extremely useful for some of those edge cases you run into when writing unit tests and trying to get full code coverage. So I consider this aspect to be a feature. Note that you can also (probably) cheat in the other direction as simply as doing *UNIVERSAL::isa= sub { ... };.

I can certainly see the point in trying to prevent people from accidentally creating a class that breaks my simple code. I think it folly to try to prevent people from intentionally trying to break such code.

So it'd be really cool if overload.pm were "fixed" to co-operate with this technique. If I saw some other candidate for "best practice" here that was as close to "right" and as available yet didn't require this somewhat hackish trick, then I'd be pushing it instead. All of the alternatives have much worse draw-backs, I believe.

- tye        

So I consider UNIVERSAL::isa() to be a "best practice" because it gets (as near as I can tell) all but the one rarest case right...

Unfortunately, the function use of isa() and can() has been deprecated in bleadperl for at least a year. It doesn't answer the question appropriately. It's a hack. It relies on an accidental implementation detail of how method storage works in Perl.

In my mind, the right solution is to patch overload to answer DOES() appropriately, which has the benefits of being the right question, giving the right answer, and not breaking methods. (Life would be even more pleasant with autobox in the core at that point; then reftype() would be unnecessary before calling DOES().)

Why UNIVERSAL::isa?

Because nobody has suggested anything better yet or convinced me otherwise...I've seen some of the debates on UNIVERSAL::isa vs. ref() vs. Scalar::Util:reftype(), but not recently, and I don't recall what all the pros and cons are, and I'm not sure if there was any absolute best solution. Got any suggestions?

My best suggestion is to accept only one type of argument so you don't have to perform the check at all.

If that's not feasable, I suggest to dereference the reference appropriately inside an eval block. Otherwise you end up with a huge chain of tests just so that you don't miss all of the possibilities (non-reference, reference of the wrong type, reference of the right type, blessed reference, tied object, blessed reference of the wrong type with overloading, blessed reference of the right type with overloading).

Philosophically speaking, using UNIVERSAL::isa() to check for structural typing in Perl is perilous because Perl uses a nominal typing system (or behavioral, but no one ever talks about that). Sometimes the only way to know if you can do a thing is to do it and see if anything breaks.