NAME

DustyDB::Collection - collections of records

VERSION

version 0.06

SYNOPSIS

  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...

DESCRIPTION

This class encapsulates a collection of records stored in DustyDB.

ATTRIBUTES

model

This is the model that the collection belongs to.

class_name

This is the class name of the record objects.

filter_subroutine

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

has_filter_subroutine

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

records

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

iterator_index

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

METHODS

filter

  $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.

count

  my $count = $collection->count;

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

first

  my $record = $collection->first;

Returns the first record matched or undef.

last

  my $record = $collection->last;

Returns the last record matched or undef.

next

  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.

reset

  $collection->reset;

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

contextual

  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.