SearchBuilder(3p)     User Contributed Perl Documentation    SearchBuilder(3p)



NAME
       DBIx::SearchBuilder - Encapsulate SQL queries and rows in simple perl
       objects

SYNOPSIS
         use DBIx::SearchBuilder;

         package My::Things;
         use base qw/DBIx::SearchBuilder/;

         sub _Init {
             my $self = shift;
             $self->Table('Things');
             return $self->SUPER::_Init(@_);
         }

         sub NewItem {
             my $self = shift;
             # MyThing is a subclass of DBIx::SearchBuilder::Record
             return(MyThing->new);
         }

         package main;

         use DBIx::SearchBuilder::Handle;
         my $handle = DBIx::SearchBuilder::Handle->new();
         $handle->Connect( Driver => 'SQLite', Database => "my_test_db" );

         my $sb = My::Things->new( Handle => $handle );

         $sb->Limit( FIELD => "column_1", VALUE => "matchstring" );

         while ( my $record = $sb->Next ) {
             print $record->my_column_name();
         }

DESCRIPTION
       This module provides an object-oriented mechanism for retrieving and
       updating data in a DBI-accesible database.

       In order to use this module, you should create a subclass of
       "DBIx::SearchBuilder" and a subclass of "DBIx::SearchBuilder::Record"
       for each table that you wish to access.  (See the documentation of
       "DBIx::SearchBuilder::Record" for more information on subclassing it.)

       Your "DBIx::SearchBuilder" subclass must override "NewItem", and
       probably should override at least "_Init" also; at the very least,
       "_Init" should probably call "_Handle" and "_Table" to set the database
       handle (a "DBIx::SearchBuilder::Handle" object) and table name for the
       class.  You can try to override just about every other method here, as
       long as you think you know what you are doing.

METHOD NAMING
       Each method has a lower case alias; '_' is used to separate words.  For
       example, the method "RedoSearch" has the alias "redo_search".

METHODS
   new
       Creates a new SearchBuilder object and immediately calls "_Init" with
       the same parameters that were passed to "new".  If you haven't
       overridden "_Init" in your subclass, this means that you should pass in
       a "DBIx::SearchBuilder::Handle" (or one of its subclasses) like this:

          my $sb = My::DBIx::SearchBuilder::Subclass->new( Handle => $handle );

       However, if your subclass overrides _Init you do not need to take a
       Handle argument, as long as your subclass returns an appropriate handle
       object from the "_Handle" method.  This is useful if you want all of
       your SearchBuilder objects to use a shared global handle and don't want
       to have to explicitly pass it in each time, for example.

   _Init
       This method is called by "new" with whatever arguments were passed to
       "new".  By default, it takes a "DBIx::SearchBuilder::Handle" object as
       a "Handle" argument, although this is not necessary if your subclass
       overrides "_Handle".

   CleanSlate
       This completely erases all the data in the SearchBuilder object. It's
       useful if a subclass is doing funky stuff to keep track of a search and
       wants to reset the SearchBuilder data without losing its own data; it's
       probably cleaner to accomplish that in a different way, though.

   Clone
       Returns copy of the current object with all search restrictions.

   _ClonedAttributes
       Returns list of the object's fields that should be copied.

       If your subclass store references in the object that should be copied
       while clonning then you probably want override this method and add own
       values to the list.

   _Handle  [DBH]
       Get or set this object's DBIx::SearchBuilder::Handle object.

   _DoSearch
       This internal private method actually executes the search on the
       database; it is called automatically the first time that you actually
       need results (such as a call to "Next").

   AddRecord RECORD
       Adds a record object to this collection.

   _RecordCount
       This private internal method returns the number of Record objects saved
       as a result of the last query.

   _DoCount
       This internal private method actually executes a counting operation on
       the database; it is used by "Count" and "CountAll".

   _ApplyLimits STATEMENTREF
       This routine takes a reference to a scalar containing an SQL statement.
       It massages the statement to limit the returned rows to only
       "$self->RowsPerPage" rows, skipping "$self->FirstRow" rows.  (That is,
       if rows are numbered starting from 0, row number "$self->FirstRow" will
       be the first row returned.)  Note that it probably makes no sense to
       set these variables unless you are also enforcing an ordering on the
       rows (with "OrderByCols", say).

   _DistinctQuery STATEMENTREF
       This routine takes a reference to a scalar containing an SQL statement.
       It massages the statement to ensure a distinct result set is returned.

   _BuildJoins
       Build up all of the joins we need to perform this query.

   _isJoined
       Returns true if this SearchBuilder will be joining multiple tables
       together.

   _isLimited
       If we've limited down this search, return true. Otherwise, return
       false.

   BuildSelectQuery
       Builds a query string for a "SELECT rows from Tables" statement for
       this SearchBuilder object

   BuildSelectCountQuery
       Builds a SELECT statement to find the number of rows this SearchBuilder
       object would find.

   Next
       Returns the next row from the set as an object of the type defined by
       sub NewItem.  When the complete set has been iterated through, returns
       undef and resets the search such that the following call to Next will
       start over with the first item retrieved from the database.

   GotoFirstItem
       Starts the recordset counter over from the first item. The next time
       you call Next, you'll get the first item returned by the database, as
       if you'd just started iterating through the result set.

   GotoItem
       Takes an integer, n.  Sets the record counter to n. the next time you
       call Next, you'll get the nth item.

   First
       Returns the first item

   Last
       Returns the last item

   DistinctFieldValues
       Returns list with distinct values of field. Limits on collection are
       accounted, so collection should be "UnLimit"ed to get values from the
       whole table.

       Takes paramhash with the following keys:

       Field
           Field name. Can be first argument without key.

       Order
           'ASC', 'DESC' or undef. Defines whether results should be sorted or
           not. By default results are not sorted.

       Max Maximum number of elements to fetch.

   ItemsArrayRef
       Return a refernece to an array containing all objects found by this
       search.

   NewItem
       NewItem must be subclassed. It is used by DBIx::SearchBuilder to create
       record objects for each row returned from the database.

   RedoSearch
       Takes no arguments.  Tells DBIx::SearchBuilder that the next time it's
       asked for a record, it should requery the database

   UnLimit
       UnLimit clears all restrictions and causes this object to return all
       rows in the primary table.

   Limit
       Limit takes a hash of parameters with the following keys:

       TABLE
           Can be set to something different than this table if a join is
           wanted (that means we can't do recursive joins as for now).

       ALIAS
           Unless ALIAS is set, the join criterias will be taken from
           EXT_LINKFIELD and INT_LINKFIELD and added to the criterias.  If
           ALIAS is set, new criterias about the foreign table will be added.

       LEFTJOIN
           To apply the Limit inside the ON clause of a previously created
           left join, pass this option along with the alias returned from
           creating the left join. ( This is similar to using the EXPRESSION
           option when creating a left join but this allows you to refer to
           the join alias in the expression. )

       FIELD
           Column to be checked against.

       VALUE
           Should always be set and will always be quoted.

       OPERATOR
           OPERATOR is the SQL operator to use for this phrase.  Possible
           choices include:

           "="
           "!="
           "LIKE"
               In the case of LIKE, the string is surrounded in % signs.  Yes.
               this is a bug.

           "NOT LIKE"
           "STARTSWITH"
               STARTSWITH is like LIKE, except it only appends a % at the end
               of the string

           "ENDSWITH"
               ENDSWITH is like LIKE, except it prepends a % to the beginning
               of the string

           "MATCHES"
               MATCHES is equivalent to the database's LIKE -- that is, it's
               actually LIKE, but doesn't surround the string in % signs as
               LIKE does.

       ENTRYAGGREGATOR
           Can be "AND" or "OR" (or anything else valid to aggregate two
           clauses in SQL).  Special value is "none" which means that no entry
           aggregator should be used.  The default value is "OR".

       CASESENSITIVE
           on some databases, such as postgres, setting CASESENSITIVE to 1
           will make this search case sensitive

       SUBCLAUSE
           Subclause allows you to assign tags to Limit statements.
           Statements with matching SUBCLAUSE tags will be grouped together in
           the final SQL statement.

           Example:

           Suppose you want to create Limit statments which would produce
           results the same as the following SQL:

              SELECT * FROM Users WHERE EmailAddress OR Name OR RealName OR Email LIKE $query;

           You would use the following Limit statements:

               $folks->Limit( FIELD => 'EmailAddress', OPERATOR => 'LIKE', VALUE => "$query", SUBCLAUSE => 'groupsearch');
               $folks->Limit( FIELD => 'Name', OPERATOR => 'LIKE', VALUE => "$query", SUBCLAUSE => 'groupsearch');
               $folks->Limit( FIELD => 'RealName', OPERATOR => 'LIKE', VALUE => "$query", SUBCLAUSE => 'groupsearch');

   OrderBy PARAMHASH
       Orders the returned results by ALIAS.FIELD ORDER.

       Takes a paramhash of ALIAS, FIELD and ORDER.  ALIAS defaults to "main".
       FIELD has no default value.  ORDER defaults to ASC(ending).
       DESC(ending) is also a valid value for OrderBy.

       FIELD also accepts "FUNCTION(FIELD)" format.

   OrderByCols ARRAY
       OrderByCols takes an array of paramhashes of the form passed to
       OrderBy.  The result set is ordered by the items in the array.

   _OrderClause
       returns the ORDER BY clause for the search.

   GroupByCols ARRAY_OF_HASHES
       Each hash contains the keys ALIAS and FIELD. ALIAS defaults to 'main'
       if ignored.

   _GroupClause
       Private function to return the "GROUP BY" clause for this query.

   NewAlias
       Takes the name of a table.  Returns the string of a new Alias for that
       table, which can be used to Join tables or to Limit what gets found by
       a search.

   Join
       Join instructs DBIx::SearchBuilder to join two tables.

       The standard form takes a param hash with keys ALIAS1, FIELD1, ALIAS2
       and FIELD2. ALIAS1 and ALIAS2 are column aliases obtained from
       $self->NewAlias or a $self->Limit. FIELD1 and FIELD2 are the fields in
       ALIAS1 and ALIAS2 that should be linked, respectively.  For this type
       of join, this method has no return value.

       Supplying the parameter TYPE => 'left' causes Join to preform a left
       join.  in this case, it takes ALIAS1, FIELD1, TABLE2 and FIELD2.
       Because of the way that left joins work, this method needs a TABLE for
       the second field rather than merely an alias.  For this type of join,
       it will return the alias generated by the join.

       Instead of ALIAS1/FIELD1, it's possible to specify EXPRESSION, to join
       ALIAS2/TABLE2 on an arbitrary expression.

       It is also possible to join to a pre-existing, already-limited
       DBIx::SearchBuilder object, by passing it as COLLECTION2, instead of
       providing an ALIAS2 or TABLE2.

   Pages: size and changing
       Use "RowsPerPage" to set size of pages. "NextPage", "PrevPage",
       "FirstPage" or "GotoPage" to change pages. "FirstRow" to do tricky
       stuff.

       RowsPerPage

       Get or set the number of rows returned by the database.

       Takes an optional integer which restricts the # of rows returned in a
       result. Zero or undef argument flush back to "return all records
       matching current conditions".

       Returns the current page size.

       NextPage

       Turns one page forward.

       PrevPage

       Turns one page backwards.

       FirstPage

       Jumps to the first page.

       GotoPage

       Takes an integer number and jumps to that page or first page if number
       ommitted. Numbering starts from zero.

       FirstRow

       Get or set the first row of the result set the database should return.
       Takes an optional single integer argrument. Returns the currently set
       integer minus one (this is historical issue).

       Usually you don't need this method. Use "RowsPerPage", "NextPage" and
       other methods to walk pages. It only may be helpful to get 10 records
       starting from 5th.

   _ItemsCounter
       Returns the current position in the record set.

   Count
       Returns the number of records in the set.

   CountAll
       Returns the total number of potential records in the set, ignoring any
       "RowsPerPage" settings.

   IsLast
       Returns true if the current row is the last record in the set.

   Column { FIELD => undef }
       Specify that we want to load the column  FIELD.

       Other parameters are TABLE ALIAS AND FUNCTION.

       Autrijus and Ruslan owe docs.

   Columns LIST
       Specify that we want to load only the columns in LIST

   Fields TABLE
       Return a list of fields in TABLE, lowercased.

       TODO: Why are they lowercased?

   HasField  { TABLE => undef, FIELD => undef }
       Returns true if TABLE has field FIELD.  Return false otherwise

   Table [TABLE]
       If called with an argument, sets this collection's table.

       Always returns this collection's table.

DEPRECATED METHODS
   GroupBy
       DEPRECATED. Alias for the "GroupByCols" method.

   SetTable
       DEPRECATED. Alias for the "Table" method.

   ShowRestrictions
       DEPRECATED AND DOES NOTHING.

   ImportRestrictions
       DEPRECATED AND DOES NOTHING.

TESTING
       In order to test most of the features of "DBIx::SearchBuilder", you
       need to provide "make test" with a test database.  For each DBI driver
       that you would like to test, set the environment variables
       "SB_TEST_FOO", "SB_TEST_FOO_USER", and "SB_TEST_FOO_PASS" to a database
       name, database username, and database password, where "FOO" is the
       driver name in all uppercase.  You can test as many drivers as you
       like.  (The appropriate "DBD::" module needs to be installed in order
       for the test to work.)  Note that the "SQLite" driver will
       automatically be tested if "DBD::Sqlite" is installed, using a
       temporary file as the database.  For example:

         SB_TEST_MYSQL=test SB_TEST_MYSQL_USER=root SB_TEST_MYSQL_PASS=foo \
           SB_TEST_PG=test SB_TEST_PG_USER=postgres  make test

AUTHOR
       Copyright (c) 2001-2006 Jesse Vincent, jesse@bestpractical.com.

       All rights reserved.

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

SEE ALSO
       DBIx::SearchBuilder::Handle, DBIx::SearchBuilder::Record.



perl v5.12.2                      2010-11-19                 SearchBuilder(3p)
