view release on metacpan or  search on metacpan

Ace.pm  view on Meta::CPAN

  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);