AcePerl

AcePerl

Verson 1.91, November 1, 2006

AcePerl is an object-oriented Perl interface for the ACEDB database. It provides functionality for connecting to remote ACEDB databases, performing queries, fetching ACE objects, and updating databases. The programmer's API is compatible with the JADE Java API, and interoperable with the API used by BoulderIO.

1999 Winner of the Long Island Software Awards!

Downloads

The AcePerl package contains all you need to connect to remote ACEDB servers over the network. Unlike earlier versions, you do not need to compile and link in the ACEDB libraries.

If you wish to create your own local databases, you will need the full ACEDB package. AcePerl is designed to work with ACEDB version 4.7c, which you can download from the NCBI or from the Sanger Centre. AcePerl will function with earlier versions of ACEDB, but not all of the features described in the documentation will work.

In order to take advantage of the new Ace::Sequence class, which supports distributed sequence annotations, you will need ACEDB version 4.7l (that's an "ell" not a one),available at:

Please send bug reports to lstein@cshl.org.

The AcePerl API

Detailed information on this library can be found in the AcePerl manual pages, which are part of the package.

The following short script will give you a taste for the library. It fetches and displays some information about all the authors in an ACEDB database. Notice that the API automatically turns method calls like $object->Mail into a traversal of the object tree and a retrieval of the subtree at the indicated tag. The col() method, which is used several times in the example below, fetches the column of data beneath the indicated tag. Similarly, row() can be used to fetch a row of data. pick() follows an object reference back into the database and retrieves it. (If you don't know what I'm talking about, don't worry, it's explained in detail in the man page.)

#!/usr/local/bin/perl # This example will pull some information on various authors # from the C. Elegans ACEDB. use Ace; use strict vars; use constant HOST => $ENV{ACEDB_HOST} || 'beta.crbm.cnrs-mop.fr'; use constant PORT => $ENV{ACEDB_PORT} || 20000100; $|=1; print "Opening the database...."; my $db = Ace->connect(-host=>HOST,-port=>PORT) || die "Connection failure: ",Ace->error; print "done.\n\n"; my @authors = $db->fetch('Author','S*'); print "There are ",scalar(@authors)," Author objects starting with the letter \"S\".\n", "The first one's name is ",$authors[0],"\n", "His mailing address is ",join(',',$authors[0]->Mail),"\n\n"; my @papers = $authors[0]->Paper; print "He has published ",scalar(@papers)," papers.\n\n"; my $paper = $papers[$#papers]->fetch; print "The title of his most recent paper is ",$paper->Title,"\n", "The coauthors were ",join(", ",$paper->Author),"\n\n", "Here is all the information on the first coauthor:\n", (($paper->Author)[0]->fetch->asString);

Here's the output from this script:

Opening the database....done.

There are 543 Author objects starting with the letter "S".
The first one's name is Saari B
His mailing address is Department of Genetics,445 Henry Mall,Madison, WI  53706

He has published 8 papers.

The title of his most recent paper is TISSUE-SPECIFIC EXPRESSION AND
    SUB-CELLULAR LOCALIZATION OF RYANODINE RECEPTOR CHANNELS IN CAENORHABDITIS ELEGANS
The coauthors were Maryon EB, Saari B, Anderson P

Here is all the information on the first coauthor:
Maryon EB  Full_name  Ed Maryon
           Address    Mail          445 Henry Mall
                                    Laboratory of Genetics
                                    Madison, WI  53706
                      E_mail        maryon@ums2.macc.wisc.edu
                      Phone         (608)262-0203
                      Fax           (608)262-2976
           Paper      [wbg12.4p69]
                      [cgc1646]
                      [wbg13.4p74]
                      [wm93p304]
                      [wm95p77]
                      [wbg14.3p11]
                      [cgc2536]
                      [wm97ab390]
                      [wm97ab632]

Example Database

Here is a small example database of movies, directors, screenwriters and actors:22 June 2007: This is not currently working.

This example database may help get you started with AcePerl. Please see the ACEDB installation notes in the documentation directory for HOWTO files.

Changes

Here is the current change log:

1.90 Tue Apr 12 09:33:11 EDT 2005
1. The -fill=>1 argument now plays nicely with the caching code.
2. Cleaned debug infrastructure.
3. Fixes to make cache more robust in mod_perl environment (may not fix)
1.89 Wed Mar 9 18:25:45 EST 2005
1. Added caching code. If you fetch the same object multiple times from the database,
you will usually get the same in-memory object.
2. Now requires ace binaries 4_9s or later.
3. Requires CACHE::CACHE and WeakRef for caching.
1.87 10/3/03
1. Fixed unreadable GIF images produced by recent versions of GifAceServer.
2. Fixed Ace::Model to handle #tags properly.
1.86 5/11/03
1. Fixed Ace::Sequence, but requires Acedb server 4.9r or higher to work!
2. Changed location of regression tests.
3. Updated documentation.
1.84
1. Fixed auto_save() getting stuck on when using Ace::Local.
1.83 2/21/02
1. Added an Ace->reopen() call that will automatically freshen handles
that have timed out.
2. Added a facility to AceSubs that allows one to add fields to the
form tag generated by AceSearchTable().

1.82 Versioning confusion. Do not use.

1.81
1. Fixed bug in SiteDefs->displays() that was causing long delays
when fetching certain display lists.

1.80
1. Numerous small bug fixes.
1.77
1. AceBrowser is now part of AcePerl.
1.76
1. Changes to AceBrowser to improve AceRedirect() call and make more robust.
2. Can now redirect to other class.
3. Numerous enhancements to Ace::Graphics glyphs, including directional glyphs.
1.75
1. Added -coordinates and -getcoordinates arguments to asGif() to support scrolling
and zooming images.
1.74
1. Fixed a bad bug involving inability to index into portions of the subtree anchored by
numeric 0.
2. Added the -filled argument to autogenerated methods (big win).
1.70 3/5/2001
1. Folded AceBrowser functionality into package.
2. Added GD graphics.
1.69 10/17/2000
1. fixes to url processing
1.68 10/15/2000
1. Fixes for socket server.
2. Fixes to Ace::Sequence module to make it reliable.
1.67 9/6/2000
1. Many updates to support socket server.
2. find_many() will now be much faster for complex queries.
3. Single-argument shortcut form for connect()
4. The Ace->find_many() and Ace->models() methods, formerly deprecated,
are now no longer supported.
1.62 5/18/2000
1. **NOTE** Redid the automatic accessors. There is now always an implicit
move to the *right* of a tag when you fetch it as a method. Use
$object->Tag(0) to get the old default behavior. Be warned, you used to
have to do this to get to the object to the right of the Sequence tag
$sequence = $clone->Sequence->right
You now only have to do this:
$sequence = $clone->Sequence
2. Removed some uninitialized variable warnings from Ace::Sequence
1.60 11/01/99
1. Fixed suspended giface processes when using iterators.
2. Added explicit close() method.
1.59 9/8/99
1. Patches to Ace::Local & Ace::Object from Tim Cutts
to improve efficiency.
1.58 8/3/99
1. Tiny change in Model.pm to accomodate @tags.
1.57 7/22/99
1. 1.56 was contaminated with leftover rpc* files in the ace/ subdirectory,
this causes builds on several architectures to fail.
2. Fixed "ambiguous variable" warnings in the regression tests.
1.56 7/9/99
1. Added Ace::Sequence, Ace::Sequence::Feature and Ace::Sequence::Feature classes
2. Added Ace::Sequence::Multi class
3. Regression tests now point to stein.cshl.org
4. Added more documentation, including more acedb/aceserver hints
5. Added more makefiles
1.55 2/26/99
1. Patched nulls appearing in raw query strings. Was causing fetch() and list()
to return fewer than the correct number of objects (approximately 0.2% loss).
1.54 2/10/99
1. Fixed spin-loop (polling) bug in Ace::Local. Should no longer
consume 99% of CPU time while waiting for tace to answer a long query.
2. Fixed bug in get() and at() in which tags got duplicated because
of capitalization variations.
1.53 1/23/99
1. Bug fix in Ace::find function. Was causing a crash.
1.52 1/21/99
1. Fixed bad bug in the kill method which caused objects
to be removed from the database seemingly randomly.
2. Optimized tag searching to improve performance when
navigating objects.
3. Better error message reporting when objects do not contain
a desired tag.
1.51 12/14/98
1. Comparison between objects now is more sensible:
"eq" performs a string comparison on object names
"==" performs an object comparison. Two objects are
identical iff their names, classes and databases are identical
2. Fixed bugs involving names containing "*" and "?" characters.
3. Added the -long option to grep.
4. Added the -display option to asGIF()
5. The follow() method now follows a tag into the database.

1.50 1. THE SEMANTICS OF AUTOGENERATED FUNCTIONS HAS CHANGED. THEY NOW
ALWAYS DEREFERENCE THE TAG AND FETCH AN OBJECT FROM THE DATABASE.
2. Added the Ace::put() function to the Ace object, allowing you to move
objects from one database to another.
3. Added Ace::Object::add_row() and add_tree() functions, making it easier to build
up objects from scratch, or to mix and match objects from different databases.
4. Added Ace::parse() and parse_file() methods, for creating objects from .ace files.
5. Removed nulls from error strings.

1.47-49 Internal releases

1.46 1. Fixed nasty bug in which newlines appeared as "n" in text
fields.

1.45. 1. Fixed problems with autogeneration
2. Added the format() routine 3. Added the model() methods and
Ace::Model class

1.44 1. Added the auto_save() routine to the API
2. Fixed problem of hanging tace processes after quitting local sessions
3. Fixed problem with creation of new objects in local
sessions.

1.43 1. Moved the unescape routine into the C level for performance reasons.
2. Should now escape \? correctly and handle most protection issues.

1.42 1. Numerous small bug fixes

1.41 1. Fixed problem with truncation of trees at zero values
2. Fixed implementation of updating wrt new aceservers

1.46 1. Fixed nasty replacement of newlines by "n" characters in text fields.

1.45 Internal release only.

1.44 1. Added the auto_save() routine to the API
2. Fixed problem of hanging tace processes after quitting local sessions
3. Fixed problem with creation of new objects in local sessions.

1.43 1. Moved the unescape routine into the C level for performance reasons.
2. Should now escape \? correctly and handle most protection issues.

1.42 1. Numerous small bug fixes

1.41 1. Fixed problem with truncation of trees at zero values
2. Fixed implementation of updating wrt new aceservers

1.40 Internal version, never released

1.39 1. Workaround for problem with dropped date fields

1.38 1. list() is now deprecated. Use fetch() instead
2. grep() method added
3. -total parameter added to fetch() grep() and find()
4. ace.pl added to exampe directory
5. new patch file adds a few essential bug fixes to ace 4_5e.
6. asGIF() method is now documented
7. updated patchfile to include "phoenix effect" aceserver bug

1.37 1. Added timestamp and comment handling.
2. Added -filled and -chunksize arguments to fetch_many().
3. Quashed a bug in list(-filled).
4. More regression tests.

1.36 6/6/98 Substantial API changes:
1. row() now returns everything to the right of the current object INCLUSIVE
of the object. Calling row() in a scalar context returns the size of the
array, not the first member of the array.

2. col() now takes an optional numeric argument indicating how far to the
right in the tree to go. Specifically col(2) implements tag[2] semantics.

3. search() now takes an optional numeric argument indicating how
far to the right in the tree to go before retrieving the column.
Specifically, search($tag,2) implements tag[2] semantics.

4. automatically-generated methods (such as Homol) now take an optional
numeric argument that is passed to search. $obj->Homol(2) implements
tag[2] semantics.

5. fetch() now takes an optional tag argument which will be followed
prior to fetching from the database. $obj->fetch('Laboratory') will
return the Laboratory object.

6. tace can be used to access local databases, by passing a -path
argument to the Ace::connect() method.

7. dates are displayed in Java style (3 March 1998 hh:mm:ss) by
default. This can be altered with a call to Ace::date_style().

8. Default port has changed to 23456

1.34 5/20/98 Fixed bug in Ace.xs caused by 1.33 change! Only some objects
were retrieved by fetch().

1.33 5/19/98 Fixed bug in Ace.xs that caused client to crash on "quit" query.

1.01 3/20/98 Fixed bug in _appendToTable() routine that caused asHTML to hang.

1.00 2/25/98 First released version