Where is detailed documentation on Class::DBI's sth_to_objects() method?

Question

How do I find detailed documentation on the behavior of the sth_to_objects() method in the Class::DBI module?

Answer 1

From what I can tell at the CPAN Page, they're using sth_to_objects as a sub defined by the user in their own class. I don't think it exists in any other manner.

Answer 2

My impression from http://search.cpan.org/~tmtm/Class-DBI-v3.0.17/lib/Class/DBI/Search/Basic.pm is that you implement it yourself.

However, http://search.cpan.org/src/TMTM/Class-DBI-v3.0.17/lib/Class/DBI.pm contains one, which may be a 'default' which is called in the event you don't overload it.

sub sth_to_objects {
    my ($class, $sth, $args) = @_;
    $class->_croak("sth_to_objects needs a statement handle") unless $sth;
    unless (UNIVERSAL::isa($sth => "DBI::st")) {
     my $meth = "sql_$sth";
     $sth = $class->$meth();
    }
    my (%data, @rows);
    eval {
     $sth->execute(@$args) unless $sth->{Active};
     $sth->bind_columns(\(@data{ @{ $sth->{NAME_lc} } }));
     push @rows, {%data} while $sth->fetch;
    };
    return $class->_croak("$class can't $sth->{Statement}: $@", err => $@)
     if $@;
    return $class->_ids_to_objects(\@rows);
}

This brings forth that you do

$someobject->sth_to_objects( $statement_handle, [ $args ] ) ;

And arges are whatever 'execute' takes.

Answer 3

sth_to_objects is supposed to be a public (actually protected) method. According to the changes file it was exposed and documented in 0.90, but no documentation exists other than mention in a couple examples. Lacking any API documentation, you can figure out what it does by looking at the implementation, as Kent pointed out, and some tests (which don't fully cover it's arguments) but use at your own risk. You have a bit more to go on seeing as how the Changes file and documentation intend that this is to be public, but in the immortal words of Tom Christensen, "you are wicked and wrong to have broken inside and peeked at the implementation and then relied upon it."