view release on metacpan or  search on metacpan

Ace.pm  view on Meta::CPAN

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