/ 
Gideon-0.0.3
River stage zero No dependents
/ Gideon::Manual::Finding

NAME

Gideon::Manual::Finding - Finding objects

VERSION

version 0.0.3

DESCRIPTION

The Gideon API defines two methods for finding records: find and find_one

find( [%opts] )

Find is used for finding one or more records within your data store, the query DSL may vary from different providers. In the case of the DBI driver it uses the SQL::Abstract interface, for example

# Search all
Class->find;

# Search object with id = 1
Class->find( id => 1 )

# Search object using like
Class->find( name => { like => 'Doe' } );

# Complex search
Class->find( name => [ { like => 'Doe' }, { 'not like' => 'John' } ] );

You can additionally request a particular sorting criteria, or limit. To do that you need to add -order and -limit in your options

# Search all order by id descending
Class->find( -order => { -desc => 'id' } )

# Search first 10 elements
Class->find( -limit => 10 )

# Next page
Class->find( -limit => 10, -offset => 10);

Another particular aspect of Gideon is that find behaves differently depending on the calling context.

find( [%opts] ) in Scalar Context

When called in scalar context it returns a Gideon::ResultSet object and does not retrieve object from the data store deferring the operation to when results are really needed. This allows you to, for instance, combine different searches together.

# Find in scalar context
my $grown_ups = Poeple->find( age => { '>' => 16 } );
my $us_grown_ups = $grown_ups->find( country => 'US' );

# This has the same effect as
# my $usa_grown_ups = Poeple->find( age => { '>' => 16 }, country => 'US' );

say $_->name for $usa_grown_ups;

find in Array Context

When find is called in Array Context it queries the data store immediately and returns an array with the results.

# Same results as previous example
say $_->name for Poeple->find( age => { '>' => 16 }, country => 'US' );

find_one( [%opts] )

find_one is a shortcut to search one record only, in case there are multiple results it will only return the first object, if -order is not provided it will return the first result using data store's natural ordering

my $first_grown_up = People->find_one( age => { '>' => 16 } );
say $first_grown_up->name;

The you can use the same %opts as with the find method with one exception: limit is not used as it is forced to 1

NAME

Finding objects with Gideon

VERSION

version 0.0.3

AUTHOR

Mariano Wahlmann, Gines Razanov

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Mariano Wahlmann, Gines Razanov.

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