view release on metacpan or  search on metacpan

Ace.pm  view on Meta::CPAN

   @objects = $db->fetch(-name    => 'D123*',
                         -class   => 'Sequence',
                         -filltag => 'Visible');

This will fetch all Sequences named D123* and fill in their Visible
trees in a single operation.

Other arguments in the named parameter calling form are B<-count>, to
retrieve a certain maximum number of objects, and B<-offset>, to
retrieve objects beginning at the indicated offset into the list.  If
you want to limit the number of objects returned, but wish to learn
how many objects might have been retrieved, pass a reference to a
scalar variable in the B<-total> argument.  This will return the
object count.  This example shows how to fetch 100 Sequence
objects, starting at Sequence number 500:

  @some_sequences = $db->fetch('Sequence','*',100,500);

The next example uses the named argument form to fetch 100 Sequence
objects starting at Sequence number 500, and leave the total number of
Sequences in $total:

  @some_sequences = $db->fetch(-class  => 'Sequence',
	                       -count  => 100,
	                       -offset => 500,
	                       -total  => \$total);

Notice that if you leave out the B<-name> argument the "*" wildcard is 
assumed.

You may also pass an arbitrary Ace query string with the B<-query>
argument.  This will supersede any name and class you provide.
Example: 

  @ready_dnas= $db->fetch(-query=>
      'find Annotation Ready_for_submission ; follow gene ; 
       follow derived_sequence ; >DNA');

If your request is likely to retrieve very many objects, fetch() many
consume a lot of memory, even if B<-fill> is false.  Consider using
B<fetch_many()> instead (see below).  Also see the get() method, which
is equivalent to the simple two-argument form of fetch().

=item get() method

   $object = $db->get($class,$name [,$fill]);

The get() method will return one and only one AceDB object
identified by its class and name.  The optional $fill argument can be
used to control how much data is retrieved from the database. If $fill
is absent or undefined, then the method will return a lightweight
"stub" object that is filled with information as requested in a lazy
fashion. If $fill is the number "1" then the retrieved object contains
all the relevant information contained within the database.  Any other
true value of $fill will be treated as a tag name: the returned object
will be prefilled with the subtree to the right of that tag.

Examples:

   # return lightweight stub for Author object "Sulston JE."
   $author = $db->get(Author=>'Sulston JE');

   # return heavyweight object
   $author = $db->get(Author=>'Sulston JE',1);

   # return object containing the Address subtree
   $author = $db->get(Author=>'Sulston JE','Address');

The get() method is equivalent to this form of the fetch()
method:

   $object = $db->fetch($class=>$name);

=head2 aql() method

    $count   = $db->aql($aql_query);
    @objects = $db->aql($aql_query);

Ace::aql() will perform an AQL query on the database.  In a scalar
context it returns the number of rows returned.  In an array context
it returns a list of rows.  Each row is an anonymous array containing
the columns returned by the query as an Ace::Object.

If an AQL error is encountered, will return undef or an empty list and
set Ace->error to the error message.

Note that this routine is not optimized -- there is no iterator
defined.  All results are returned synchronously, leading to large
memory consumption for certain queries.

=head2 put() method

   $cnt = $db->put($obj1,$obj2,$obj3);

This method will put the list of objects into the database,
overwriting like-named objects if they are already there.  This can
be used to copy an object from one database to another, provided that
the models are compatible.

The method returns the count of objects successfully written into the
database.  In case of an error, processing will stop at the last
object successfully written and an error message will be placed in
Ace->error();

=head2 parse() method

  $object = $db->parse('data to parse');

This will parse the Ace tags contained within the "data to parse"
string, convert it into an object in the databse, and return the
resulting Ace::Object.  In case of a parse error, the undefined value
will be returned and a (hopefully informative) description of the
error will be returned by Ace->error().

For example:

  $author = $db->parse(<<END);
  Author : "Glimitz JR"
  Full_name "Jonathan R. Glimitz"
  Mail	"128 Boylston Street"
  Mail	"Boston, MA"
  Mail	"USA"
  Laboratory GM
  END

This method can also be used to parse several objects, but only the
last object successfully parsed will be returned.

=head2 parse_longtext() method

  $object = $db->parse($title,$text);

This will parse the long text (which may contain carriage returns and
other funny characters) and place it into the database with the given
title.  In case of a parse error, the undefined value will be returned
and a (hopefully informative) description of the error will be
returned by Ace->error(); otherwise, a LongText object will be returned.

For example:

  $author = $db->parse_longtext('A Novel Inhibitory Domain',<<END);
  We have discovered a novel inhibitory domain that inhibits
  many classes of proteases, including metallothioproteins.
  This inhibitory domain appears in three different gene families studied
  to date...
  END

=head2 parse_file() method

  @objects = $db->parse_file('/path/to/file');
  @objects = $db->parse_file('/path/to/file',1);

This will call parse() to parse each of the objects found in the
indicated .ace file, returning the list of objects successfully loaded
into the database.

By default, parsing will stop at the first object that causes a parse
error.  If you wish to forge on after an error, pass a true value as
the second argument to this method.

Any parse error messages are accumulated in Ace->error().

=head2 new() method

  $object = $db->new($class => $name);

This method creates a new object in the database of type $class and
name $name.  If successful, it returns the newly-created object.
Otherwise it returns undef and sets $db->error().

$name may contain sprintf()-style patterns.  If one of the patterns is
%d (or a variant), Acedb uses a class-specific unique numbering to return
a unique name.  For example:

  $paper = $db->new(Paper => 'wgb%06d');

The object is created in the database atomically.  There is no chance to rollback as there is
in Ace::Object's object editing methods.

See also the Ace::Object->add() and replace() methods.

=head2 list() method

    @objects = $db->list(class,pattern,[count,offset]);
    @objects = $db->list(-class=>$class,
                         -name=>$name_pattern,
                         -count=>$count,
                         -offset=>$offset);

This is a deprecated method.  Use fetch() instead.

=head2 count() method

    $count = $db->count($class,$pattern);
    $count = $db->count(-query=>$query);

This function queries the database for a list of objects matching the
specified class and pattern, and returns the object count.  For large
sets of objects this is much more time and memory effective than
fetching the entire list.

The class and name pattern are the same as the list() method above.

You may also provide a B<-query> argument to instead specify an
arbitrary ACE query such as "find Author COUNT Paper > 80".  See
find() below.

=head2 find() method

    @objects = $db->find($query_string);
    @objects = $db->find(-query => $query_string,
                         -offset=> $offset,
                         -count => $count
                         -fill  => $fill);

This allows you to pass arbitrary Ace query strings to the server and
retrieve all objects that are returned as a result.  For example, this
code fragment retrieves all papers written by Jean and Danielle
Thierry-Mieg.

    @papers = $db->find('author IS "Thierry-Mieg *" ; >Paper');

You can find the full query syntax reference guide plus multiple
examples at http://probe.nalusda.gov:8000/acedocs/index.html#query.

In the named parameter calling form, B<-count>, B<-offset>, and
B<-fill> have the same meanings as in B<fetch()>.

=head2 fetch_many() method

    $obj = $db->fetch_many($class,$pattern);

    $obj = $db->fetch_many(-class=>$class,
                           -name =>$pattern,
                           -fill =>$filled,
                           -chunksize=>$chunksize);

    $obj = $db->fetch_many(-query=>$query);

If you expect to retrieve many objects, you can fetch an iterator
across the data set.  This is friendly both in terms of network
bandwidth and memory consumption.  It is simple to use:

    $i = $db->fetch_many(Sequence,'*');  # all sequences!!!!
    while ($obj = $i->next) {
       print $obj->asTable;
    }

The iterator will return undef when it has finished iterating, and
cannot be used again.  You can have multiple iterators open at once
and they will operate independently of each other.

Like B<fetch()>, B<fetch_many()> takes an optional B<-fill> (or
B<-filled>) argument which retrieves the entire object rather than
just its name.  This is efficient on a network with high latency if 
you expect to be touching many parts of the object (rather than
just retrieving the value of a few tags).

B<fetch_many()> retrieves objects from the database in groups of a
certain maximum size, 40 by default.  This can be tuned using the
optional B<-chunksize> argument.  Chunksize is only a hint to the
database.  It may return fewer objects per transaction, particularly
if the objects are large.

You may provide raw Ace query string with the B<-query> argument.  If
present the B<-name> and B<-class> arguments will be ignored.

=head2 find_many() method

This is an alias for fetch_many().  It is now deprecated.

=head2 keyset() method

    @objects = $db->keyset($keyset_name);

This method returns all objects in a named keyset.  Wildcard
characters are accepted, in which case all keysets that match the
pattern will be retrieved and merged into a single list of unique
objects.

=head2 grep() method