DustyDB::Collection - collections of records


version 0.06


  package WhatsIt;
  use DustyDB::Object;

  has key bobble => ( is => 'rw', isa => 'Str' );
  has bits   => ( is => 'rw', isa => 'Str', predicate => 'has_bits' );

  package main;
  use DustyDB;

  my $db = DustyDB->new( path => 'foo.db' );
  my $model = DustyDB->model('WhatsIt');

  # All whatsits with a bobble containing fluff
  my $iter = $model->all( bobble => qr/fluff/ ); 
  while (my $whatsit = $iter->next) {
      print "Your fluff has bits of ", $whatsit->bits, " in it.\n";

  # Iterate through those that actually have bits
  $iter->filter( 'has_bits' );
  for my $whatsit ($iter->records) {
      print "Whatsit ", $whatsit->bobble, " has bits.\n";

  # and so on...


This class encapsulates a collection of records stored in DustyDB.



This is the model that the collection belongs to.


This is the class name of the record objects.


Do not use this directly. See "filter" instead. This contains a reference to the subroutine that is used to filter the records (if any).


This is a predicate that returns true if "filter_subroutine" is set.


This is the list of records that belong to this collection.


Do not use this directly. See "next" instead. This is the internal pointer into the "records" array.



  $collection->filter( %params );
  $collection->filter( $method_name );
  $collection->filter( $code_ref );

Given a description of a filter, this method will filter the records accordingly. There are three kinds of arguments that may be passed:

  1. %params. If you pass a hash of parameters, the keys are expected to be column names in the model object and the vlaues are expected to be values to match. These values may either be a scalar for an exact match or a regular expression to perform a pattern match.

  2. $method_name. If a string is given that matches a method defined on the model object, that method will be called (with no arguments) on every object. Any time a true value is returned by that method, it will be included in the collection.

  3. $code_ref. If a code reference is passed, this code reference is called for each object with $_ set to the object being evaluated. If the subroutine returns a true value, the object evaluated will be included in the collection.


  my $count = $collection->count;

Returns the number of records matched by the filter (or number of records total if there is no filter).


  my $record = $collection->first;

Returns the first record matched or undef.


  my $record = $collection->last;

Returns the last record matched or undef.


  my $record = $collection->next;

Returns the next record in the collection. On the first call, it returns the first record. On the second, it returns the second. This continues until it reaches the last record and then it returns undef. This sequence will repeat immediately after returning undef if called again.



Resets the record pointer used by "next" so that the next call to that method will return the first record.


  my @records = $collection->contextual;
  my $iter    = $collection->contextual;

You probably won't need to call this yourself. It basically makes the switch between the array and this collection class.