Ace(3pm)

📦

version 1.92 · 8 versions

🎀 NAME 🎀

okay so this is Ace(3pm), from the User Contributed Perl Documentation, and the manual name is Ace. The whole vibe is Object-Oriented Access to ACEDB Databases. periodt. 💅

✨ SYNOPSIS ✨

bestie, here's the entire vibe in code. copy-paste exact, no changes. 💖

use Ace;
# open a remote database connection
$db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                   -port => 20000100);

# open a local database connection
$local = Ace->connect(-path=>'~acedb/my_ace');

# simple queries
$sequence  = $db->fetch(Sequence => 'D12345');
$count     = $db->count(Sequence => 'D*');
@sequences = $db->fetch(Sequence => 'D*');
$i         = $db->fetch_many(Sequence=>'*');  # fetch a cursor
while ($obj = $i->next) {
   print $obj->asTable;
}

# complex queries
$query = <<END;
find Annotation Ready_for_submission ; follow gene ;
follow derived_sequence ; >DNA
END
@ready_dnas= $db->fetch(-query=>$query);

$ready = $db->fetch_many(-query=>$query);
while ($obj = $ready->next) {
    # do something with obj
}

# database cut and paste
$sequence = $db->fetch(Sequence => 'D12345');
$local_db->put($sequence);
@sequences = $db->fetch(Sequence => 'D*');
$local_db->put(@sequences);

# Get errors
print Ace->error;
print $db->error;

💖 DESCRIPTION 💖

AcePerl is the whole interface to the ACEDB object-oriented database. You get both read and write access, and ACE objects come back as Perl objects with a similar structure. Multiple databases can be opened at the same time, no problem. ✨

okay so the Perl classes you'll be interacting with are Ace, Ace::Object, Ace::Iterator, and Ace::Model. Ace is the database accessor, and it can open both remote Ace databases — like ones running aceserver or gifaceserver — and local ones too. 🌈

Ace::Object is the superclass for all objects returned from the database. Ace and Ace::Object are linked: if you retrieve an Ace::Object from a particular database, it stores a reference to that database and uses it to fetch any subobjects contained within it. You can make changes to the Ace::Object and have those changes written into the database. You can also create Ace::Objects from scratch and store them in the database. main character energy. 🫶

Ace::Iterator is a utility class that acts as a database cursor for long-running ACEDB queries. Ace::Model gives you object-oriented access to ACEDB's schema. 🧚

Internally, Ace uses the Ace::Local class for access to local databases and Ace::AceDB for access to remote databases. Ordinarily you will not need to interact directly with either of these classes. iykyk. 💜

💖 CREATING NEW DATABASE CONNECTIONS 💖

okay so now we get to the actual socializing part — you're gonna make a connection, bestie, and the database is gonna be obsessed with you 🫶

🌸 connect() -- multiple argument form 🌸

# remote database
$db = Ace->connect(-host  =>  'beta.crbm.cnrs-mop.fr',
                   -port  =>  20000100);

# local (non-server) database
$db = Ace->connect(-path  =>  '/usr/local/acedb);

Use Ace::connect() to establish a connection to a networked or local AceDB database. Like, this is the move, no cap. If you wanna link up with an AceDB server, you pass the -host and/or -port arguments. For a local server, you use the -port argument. And heads up — the database has to already be up and running on the host and port you name before you try connecting to an AceDB server. The full syntax is as follows:

$db = Ace->connect(-host  =>  $host,
                   -port  =>  $port,
                   -path  =>  $database_path,
                   -program     => $local_connection_program
                   -classmapper =>  $object_class,
                   -timeout     => $timeout,
                   -query_timeout => $query_timeout
                   -cache        => {cache parameters},
                  );

The connect() method uses a named argument calling style, and recognizes the following arguments:

-host, -port — these arguments point to the host and port of an AceDB server. AcePerl will use its internal compiled code to establish a connection to the server unless explicitly overridden with the -program argument.
-path — this argument indicates the path of an AceDB directory on the local system. It should point to the directory that contains the wspec subdirectory. User name interpolations (~acedb) are OK.
-user — name of the user to log in as (when using a socket server only). If you don't provide it, it will attempt an anonymous login.
-pass — password to log in with (when using a socket server).
-url — an Acedb URL that combines the server type, host, port, user and password in a single string. See the connect() method's "single argument form" description.
-cache — AcePerl can use the Cache::SizeAwareFileCache module to cache objects to disk. This can result in dramatically increased performance in environments such as web servers in which the same Acedb objects are frequently reused. To activate this mechanism, the Cache::SizeAwareFileCache module must be installed, and you must pass the -cache argument during the connect() call.

The value of -cache is a hash reference containing the arguments to be passed to Cache::SizeAwareFileCache. For example:

-cache => {
           cache_root         => '/usr/tmp/acedb',
           cache_depth        => 4,
           default_expires_in => '1 hour'
           }

If not otherwise specified, the following cache parameters are assumed:

namespace — default value is the Server URL (e.g. sace://localhost:2005)
cache_root — default value is /tmp/FileCache (dependent on the system temp directory)
default_expires_in — default value is 1 day
auto_purge_interval — default value is 12 hours

By default, the cache is not size limited (the "max_size" property is set to $NO_MAX_SIZE). To adjust the size you may consider calling the Ace object's cache() method to retrieve the physical cache and then calling the cache object's limit_size($max_size) method from time to time. See Cache::SizeAwareFileCache for more details.

-program — by default AcePerl will use its internal compiled code calls to establish a connection to Ace servers, and will launch a tace subprocess to communicate with local Ace databases. The -program argument allows you to customize this behavior by forcing AcePerl to use a local program to communicate with the database. This argument should point to an executable on your system. You may use either a complete path or a bare command name, in which case the PATH environment variable will be consulted. For example, you could force AcePerl to use the aceclient program to connect to the remote host by connecting this way:

$db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                   -port => 20000100,
                   -program=>'aceclient');

-classmapper — the optional -classmapper argument (alias -class) points to the class you would like to return from database queries. It is provided for your use if you subclass Ace::Object. For example, if you have created a subclass of Ace::Object called Ace::Object::Graphics, you can have the database return this subclass by default by connecting this way:

$db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                   -port => 20000100,
                   -class=>'Ace::Object::Graphics');

The value of -class can be a hash reference consisting of AceDB class names as keys and Perl class names as values. If a class name does not exist in the hash, a key named _DEFAULT_ will be looked for. If that does not exist, then Ace will default to Ace::Object.

The value of -class can also be an object or a classname that implements a class_for() method. This method will receive three arguments containing the AceDB class name, object ID and database handle. It should return a string indicating the perl class to create.

-timeout — if no response from the server is received within $timeout seconds, the call will return an undefined value. Internally timeout sets an alarm and temporarily intercepts the ALRM signal. You should be aware of this if you use ALRM for your own purposes.

NOTE: this feature is temporarily disabled (as of version 1.40) because it is generating unpredictable results when used with Apache/mod_perl. 🫠

-query_timeout — if any query takes longer than $query_timeout seconds, will return an undefined value. This value can only be set at connect time, and cannot be changed once set.

If arguments are omitted, they will default to the following values:

-host          localhost
-port          200005;
-path          no default
-program       tace
-class         Ace::Object
-timeout       25
-query_timeout 120

If you prefer to use a more Smalltalk-like message-passing syntax, you can open a connection this way too:

$db = connect Ace -host=>'beta.crbm.cnrs-mop.fr',-port=>20000100;

The return value is an Ace handle to use to access the database, or undef if the connection fails. If the connection fails, an error message can be retrieved by calling Ace->error.

You may check the status of a connection at any time with ping(). It will return a true value if the database is still connected. Note that Ace will timeout clients that have been inactive for any length of time. Long-running clients should attempt to reestablish their connection if ping() returns false.

$db->ping() || die "not connected";

You may perform low-level calls using the Ace client C API by calling db(). This fetches an Ace::AceDB object. See THE LOW LEVEL C API for details on using this object.

$low_level = $db->db();

🦋 connect() -- single argument form 🦋

$db = Ace->connect('sace://stein.cshl.org:1880')

Ace->connect() also accepts a single argument form using a URL-type syntax. The general syntax is:

protocol://hostname:port/path

The :port and /path parts are protocol-dependent as described above.

Protocols, babe:

sace://hostname:port — connect to a socket server at the indicated hostname and port. Example:

sace://stein.cshl.org:1880

If not provided, the port defaults to 2005.

rpcace://hostname:port — connect to an RPC server at the indicated hostname and RPC service number. Example:

rpcace://stein.cshl.org:400000

If not provided, the port defaults to 200005

tace:/path/to/database — open up the local database at /path/to/database using tace. Example:

tace:/~acedb/elegans

/path/to/database — same as the previous. 💅

✨ close() Method ✨

You can explicitly close a database by calling its close() method:

$db->close();

This is not ordinarily necessary because the database will be automatically close when it — and all objects retrieved from it — go out of scope.

🎀 reopen() Method 🎀

The ACeDB socket server can time out. The reopen() method will ping the server and if it is not answering will reopen the connection. If the database is live (or could be resurrected), this method returns true. Iconic behavior honestly.

👑 RETRIEVING ACEDB OBJECTS 👑

Once you have established a connection and have an Ace database handle, several methods can be used to query the ACE database to retrieve objects. You can then explore the objects, retrieve specific fields from them, or update them using the Ace::Object methods. Please see Ace::Object.

🌈 fetch() method 🌈

$count   = $db->fetch($class,$name_pattern);
$object  = $db->fetch($class,$name);
@objects = $db->fetch($class,$name_pattern,[$count,$offset]);
@objects = $db->fetch(-name=>$name_pattern,
                      -class=>$class
                      -count=>$count,
                      -offset=>$offset,
                      -fill=>$fill,
                      -filltag=>$tag,
                      -total=>\$total);
@objects = $db->fetch(-query=>$query);

Ace::fetch() retrieves objects from the database based on their class and name. You may retrieve a single object by requesting its name, or a group of objects by fetching a name pattern. A pattern contains one or more wildcard characters, where "*" stands for zero or more characters, and "?" stands for any single character.

This method behaves differently depending on whether it is called in a scalar or a list context, and whether it is asked to search for a name pattern or a simple name. vibe check on your context, basically 💜

When called with a class and a simple name, it returns the object referenced by that time, or undef, if no such object exists. In an array context, it will return an empty list.

When called with a class and a name pattern in a list context, fetch() returns the list of objects that match the name. When called with a pattern in a scalar context, fetch() returns the number of objects that match without actually retrieving them from the database. Thus, it is similar to count().

and bestie, we are not done yet — there is more coming, so don't you dare close the tab 💖

So like, look at these three little lines and tell me they're not gorgeous:

$object =  $db->fetch(Sequence => 'D12345');
@objects = $db->fetch(Sequence => 'D1234*');
$cnt =     $db->fetch(Sequence =>'D1234*');

First line? Grabs the one Sequence object whose database ID is D12345. Second line? Gives you every single object matching the pattern D1234*. Third line? Returns the count of objects matching that exact same pattern. Chef's kiss, honestly. 💅

A whole buffet of communications and database errors can pop off while the request is being processed, and when that happens you get back undef or an empty list — no drama, no crash. The string describing what went wrong is sitting right there waiting for you in Ace->error. 🫶

✨ filled vs unfilled, the whole situation ✨

When you're retrieving database objects you get to pick: "filled" or "unfilled". Bestie, this matters.

A filled object contains the entire contents of the object, including all the tags and subtags. And for certain Sequence objects? That can be a significant amount of data. Like, a LOT a lot. 😭
An unfilled object consists just of the object name. It gets filled in from the database a little bit at a time as tags are requested. So chill, it's lazy and it's thriving.

By default, fetch() hands you the unfilled object. That's usually a straight-up performance win 🏆 — but if you already know for a fact that you're gonna need the full contents of the object you retrieved (say, you're displaying it in a tree browser), it can actually be more efficient to fetch in filled mode.

How do you do that? Call fetch() with the argument -fill set to a true value. That's it. Periodt.

The -filltag argument, if you provide it, asks the database to fill in the subtree anchored at the indicated tag. This will improve performance for subtrees you access a lot. Example time:

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

This fetches all Sequences named D123* and fills in their Visible trees in a single operation. One trip, all the goods. 🎀

Other arguments in the named parameter calling form:

-count — retrieve a certain maximum number of objects.
-offset — retrieve objects beginning at the indicated offset into the list.
-total — if you wanna limit how many objects come back but still learn how many objects might have been retrieved, pass a reference to a scalar variable here. It'll return the object count. Sneaky but iconic.

This example shows how to fetch 100 Sequence objects, starting at Sequence number 500:

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

And this next one uses the named argument form to fetch 100 Sequence objects starting at Sequence number 500, while leaving 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 -name argument, the "*" wildcard is assumed. The database just goes "say less" and gives you everything. 🙈

You can also just pass an arbitrary Ace query string with the -query argument. Heads up though: this one supersedes any name and class you provide. Like, it overrules them completely, no discussion. 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() may consume a lot of memory — even if -fill is false. Consider using fetch_many() instead (see below, it's down there, keep scrolling bestie). Also see the get() method, which is equivalent to the simple two-argument form of fetch().

💖 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 controls how much data gets pulled from the database:

If $fill is absent or undefined, you get back a lightweight "stub" object that gets filled with information as requested, in a lazy fashion. Very demure, very mindful.
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 is treated as a tag name: the returned object will be prefilled with the subtree to the right of that tag. Clever girl. 🦋

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

And for the record, get() is exactly equivalent to this form of the fetch() method:

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

🌈 aql() method 🌈

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

Ace::aql() performs an AQL query on the database. Behaviour depends on context, and honestly it's giving shapeshifter:

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 shows up, it'll return undef or an empty list and set Ace->error to the error message. Classic.

⚠️ Real talk: this routine is not optimized — there is no iterator defined. All results are returned synchronously, which leads to large memory consumption for certain queries. So like, be careful with the big ones. 😭

🎀 put() method 🎀

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

This method puts the list of objects into the database, overwriting like-named objects if they're already sitting there. You can use this to copy an object from one database to another — provided the models are compatible. Don't skip that part, okay?

It returns the count of objects successfully written into the database. If an error happens, processing stops at the last object successfully written and an error message gets placed in Ace->error();. So you know exactly where it gave up. 💀

✨ parse() method ✨

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

This parses the Ace tags contained within the "data to parse" string, converts it into an object in the database, and returns the resulting Ace::Object. If there's a parse error, the undefined value gets returned and a (hopefully informative) description of the error comes back from Ace->error(). Hopefully. 🙏

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

You can also use this method to parse several objects — but only the last object successfully parsed will be returned. The rest? Gone, bestie, they're in the database but they're not coming home with you.

🦋 parse_longtext() method 🦋

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

This parses the long text (which may contain carriage returns and other funny characters) and places it into the database with the given title. If there's a parse error, you get the undefined value back and a (hopefully informative) description of the error from Ace->error(). Otherwise? A LongText object is returned. Slay.

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

💜 parse_file() method 💜

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

This calls parse() on each of the objects found in the indicated .ace file, and returns the list of objects successfully loaded into the database. Bulk mode, we love to see it.

By default, parsing stops at the first object that causes a parse error. But if you wish to forge on after an error, just pass a true value as the second argument to this method. Living dangerously, I respect it.

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

👑 new() method 👑

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

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

Here's the fun part: $name may contain sprintf()-style patterns. And if one of those patterns is %d (or a variant), Acedb uses a class-specific unique numbering to return a unique name. Magic.

For example:

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

⚠️ The object is created in the database atomically. There is no chance to rollback like there is in Ace::Object's object editing methods. Once it's done, it's done. No take-backs. 💀

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

🌸 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. It's giving old money but the money's expired, okay?

⭐ 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. Like, don't fetch a million things just to count them, that's not the vibe.

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

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

💅 find() method 💅

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

This lets you pass arbitrary Ace query strings to the server and retrieve all objects 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, -count, -offset, and -fill have the same meanings as in fetch().

🧚 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 — the moment you've all been waiting for.

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 — important — it cannot be used again. One and done, bestie.

But here's the good news: you can have multiple iterators open at once and they will operate independently of each other. They don't gossip, they don't interfere. Iconic behaviour, honestly. 💖

Like fetch(), fetch_many() will happily take an optional -fill (or -filled) argument, and that bad boy pulls the entire object instead of just its name 🫶. This is lowkey a slay on a high-latency network, but only if you're gonna be poking at lots of parts of that object — not just grabbing a few tag values and dipping.

fetch_many() grabs objects in groups with a max size, 40 by default. Tune it with the optional -chunksize argument. Heads up bestie: chunksize is only a hint to the database 😌. It's fully allowed to hand you back fewer objects per transaction, especially when the objects are chonky.

You can also just yeet a raw Ace query string in with the -query argument. If you do, the -name and -class arguments get completely ignored, periodt.

find_many() method

It's just an alias for fetch_many(). It is now deprecated 💀 — so like, it still works, but don't be building new stuff on it, okay?

keyset() method

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

This returns every object sitting inside a named keyset. Wildcard characters are accepted, and when you use them, all the keysets matching that pattern get retrieved and merged into one single list of unique objects ✨.

grep() method

@objects = $db->grep($grep_string);
$count   = $db->grep($grep_string);
@objects = $db->grep(-pattern => $grep_string,
                     -offset=> $offset,
                     -count => $count,
                     -fill  => $fill,
                     -filltag => $filltag,
                     -total => \$total,
                     -long  => 1,
                    );

This runs a "grep" on the database and gives you back all object names or text that contain the grep pattern you asked for 🔍. In a scalar context, this call returns the number of matching objects. In an array context, you get the list of matching objects. There's also a named-parameter form of the call, which lets you specify how many objects to retrieve, the offset from the beginning of the list to start retrieving from, and whether the retrieved objects should be filled initially. You can use -total to discover the total number of objects that match while only retrieving a portion of the list — very clever, very iconic.

By default, grep uses a fast search that only examines class names and lexiques. Provide a true value to the -long parameter and it'll go digging inside LongText and other places that aren't usually touched — at the expense of much more CPU time 😭. So like, use it when you need it.

Due to "not listable" objects that may match during grep, the list of objects you can actually retrieve may not always match the count. Yes, that's real. No, it's not your fault.

model() method

$model = $db->model('Author');

This returns an Ace::Model object corresponding to the class you named 🎀.

new() method

$obj = $db->new($class,$name);
$obj = $db->new(-class=>$class,
                -name=>$name);

Creates a brand new object in the database with the class and name you gave it, and hands you back a pointer to it 🔥. It will return undef if the object already exists in the database. And listen — the object isn't actually written into the database until you call Ace::Object::commit(). So don't be out here thinking it saved itself, because it did not.

raw_query() method

$r = $db->raw_query('Model');

Sends a command straight to the database and returns its unprocessed output. This method is how you get at features that aren't implemented in this module yet — stuff like model browsing and complex queries 👑. Raw, unfiltered, direct. Fr fr.

classes() method

@classes = $db->classes();
@all_classes = $db->classes(1);

This returns a list of every object class the server knows about. In a list context you get an array of class names. In a scalar context, it gives you the number of classes defined in the database.

Ordinarily, classes() only returns the classes that are exposed to the user interface for browsing — the so-called "visible" classes 😇. Pass a true argument to the call to retrieve the non-visible classes as well.

class_count() method

%classes = $db->class_count()

This returns a hash where the keys are class names and the values are the total number of objects in that class. All classes come back, invisible ones included. Use this method if you need to count all the classes at once. If you only want to count one or two classes, it may be more efficient to call count($class_name) instead — work smarter, not harder 💅.

This method transiently uses a LOT of memory 😭. It should not be used with Ace 4.5 servers, because they contain a memory leak in the counting routine. Not our fault, but definitely our problem.

status() method

%status = $db->status;
$status = $db->status;

Returns various bits of status info from the server 🩺. In an array context, it returns a hash of hashes. In a scalar context, it returns a reference to a hash of hashes. The keys and subkeys are as follows:

code
        program     name of acedb binary
        version     version of acedb binary
        build       build date of acedb binary in format Jan 25 2003 16:21:24

database
        title       name of the database
        version     version of the database
        dbformat    database format version number
        directory   directory in which the database is stored
        session     session number
        user        user under which server is running
        write       whether the server has write access
        address     global address - not known if this is useful

resources
        classes     number of classes defined
        keys        number of keys defined
        memory      amount of memory used by acedb objects (bytes)

For example, to get the program version:

my $version = $db->status->{code}{version};

title() method

my $title = $db->title

Returns the version of the current database. Equivalent to $db->status->{database}{title}.

version() method

my $version = $db->version;

Returns the version of the current database. Equivalent to $db->status->{database}{version}.

date_style() method

$style = $db->date_style();
$style = $db->date_style('ace');
$style = $db->date_style('java');

For historical reasons, AceDB can display dates in either of two different formats 📅. The first one, which the docs call "ace" style, puts the year first, as in "1997-10-01". The second one, called "java" style, puts the day first, as in "01 Oct 1997 00:00:00" (this is also the style recommended for Internet dates). The default is to use the latter notation.

date_style() can be used to set or retrieve the current style. Call it with no arguments and it returns the current style, which will be one of "ace" or "java." Call it with an argument and it sets the style to one or the other.

timestamps() method

$timestamps_on = $db->timestamps();
$db->timestamps(1);

Whenever a data object gets updated, AceDB records the time and date of the update, plus the user ID it was running under ⏰. Ordinarily, retrieving that timestamp info is suppressed to conserve memory and bandwidth. To turn timestamps on, call the timestamps() method with a true value. You can grab the current value of the setting by calling the method with no arguments.

Ngl, activating timestamps disables some of the speed optimizations in AcePerl. So like, only turn them on if you really need that info 🔥.

auto_save()

Sets or queries the auto_save variable. If true, the "save" command will be issued automatically before the connection to the database is severed. The default is true ✨.

Examples:

$db->auto_save(1);
$flag = $db->auto_save;

error() method

Ace->error;

This returns the last error message 💀. Like UNIX errno, this variable is not reset between calls, so its contents are only valid after a method call has returned a result value indicating a failure. Don't trust stale errors, bestie.

For your convenience, you can call error() in any of several ways:

print Ace->error();
print $db->error();  # $db is an Ace database handle
print $obj->error(); # $object is an Ace::Object

There's also a global named $Ace::Error that you are free to use 💜.

datetime() and date()

$datetime = Ace->datetime($time);
$today    = Ace->datetime();
$date     = Ace->date($time);
$today    = Ace->date([$time]);

These convenience functions convert the UNIX timestamp given by $time (seconds since the epoch) into a datetime string in the format that ACEDB requires 🕰️. date() will truncate the time portion.

If you don't provide it, $time defaults to localtime().

✨ OTHER METHODS ✨

debug()

$debug_level = Ace->debug([$new_level])

This class method gets or sets the debug level. Higher integers increase verbosity 🗣️. 0 or undef turns debug messages off.

name2db()

$db = Ace->name2db($name [,$database])

This class method associates a database URL with an Ace database object. It's used internally by the Ace::Object class so it can figure out what database they "belong" to 🫶.

cache()

Get or set the Cache::SizeAwareFileCache object, if one has been created.

memory_cache_fetch()

$obj = $db->memory_cache_fetch($class,$name)

Given an object class and name, return a copy of the object from the in-memory cache. The object will only be cached if a copy of the object already exists in memory space. This is ordinarily called internally 🧠.

memory_cache_store($obj)

Store an object into the memory cache. This is ordinarily called internally.

memory_cache_delete($obj)

Delete an object from the memory cache. This is ordinarily called internally.

memory_cache_clear()

Completely clears the memory cache. Clean slate, no crumbs 🧹.

file_cache_fetch()

$obj = $db->file_cache_fetch($class,$name)

Given an object class and name, return a copy of the object from the file cache. This is ordinarily called internally 💾.

file_cache_store($obj)

Store an object into the file cache. This is ordinarily called internally.

file_cache_delete($obj)

Delete an object from the file cache. This is ordinarily called internally.

🧚 THE LOW LEVEL C API 🧚

Okay bestie, plot twist: under all the cute Perl vibes, Ace.pm is secretly doing C-language calls down to libace to yeet query strings at the server and pull the results back. The class that exports those low-level calls? Her name is Ace::AceDB. 💅

These are the methods hanging out in Ace::AceDB:

`new($host,$port,$query_timeout)`

Connects to $host at port $port, and queries will time out after $query_timeout seconds. If you don't specify a timeout, she defaults to 120 (two minutes) — clock's ticking, babe. ⏰

If it works, this call hands you back an Ace::AceDB connection object. If not? undef. That's it. Example, as promised:

$acedb = Ace::AceDB->new('localhost',200005,5)
         || die "Couldn't connect";

Also you can totally reach the Ace::AceDB object from the high-level Ace interface by calling the ACE::db() method:

$db = Ace->new(-host=>'localhost',-port=>200005);
$acedb = $db->db();

`query($request)`

Sends the query string $request to the server and returns a true value if it slayed. But heads up — you have to call read() over and over after this to actually fetch the query result. It's giving layered. 🎀

`read()`

Reads the result from the last query you sent to the server and returns it as a string. ACE may hand you the result in pieces, breaking between whole objects, so you might need to read repeatedly to collect the entire result. Canonical example, memorize her:

$acedb->query("find Sequence D*");
die "Got an error ",$acedb->error() if $acedb->status == STATUS_ERROR;
while ($acedb->status == STATUS_PENDING) {
   $result .= $acedb->read;
}

`status()`

Returns the status code from the last operation. These are exported by default when you use Ace.pm, so no extra work. Status codes you may see:

STATUS_WAITING    The server is waiting for a query.
STATUS_PENDING    A query has been sent and Ace is waiting for
                  you to read() the result.
STATUS_ERROR      A communications or syntax error has occurred

`error()`

Returns a more detailed error code supplied by the Ace server. Check this value when STATUS_ERROR has been returned. These constants are also exported by default. Possible values:

ACE_INVALID
ACE_OUTOFCONTEXT
ACE_SYNTAXERROR
ACE_UNRECOGNIZED

Please see the ace client library documentation for a full description of these error codes and their significance. 📖

`encore()`

This method may return true after you've done one or more read() operations, and it indicates there's more data to read. You won't ordinarily have to call this method. It's just there doing her little encore. ✨

💀 BUGS 💀

Not me listing all eight, because we keep every single one:

The ACE model should be consulted prior to updating the database.
There is no automatic recovery from connection errors.
Debugging has only one level of verbosity, despite the best of intentions.
Performance is poor when fetching big objects, because of many object references that must be created. This could be improved.
When called in an array context at("tag[0]") should return the current tag's entire column. It returns the current subtree instead.
There is no way to add comments to objects.
When timestamps are active, many optimizations are disabled.
Item number eight is still missing.

Number eight has been missing this whole time and honestly? Iconic. It stays missing. 🙈

🌈 SEE ALSO 🌈

Ace::Object, Ace::Local, Ace::Model, Ace::Sequence,Ace::Sequence::Multi.

👑 AUTHOR 👑

Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-Mieg <mieg@kaa.crbm.cnrs-mop.fr>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.

And that's a wrap on the whole page, bestie! 🫶 This was Ace(3pm), coming to you from perl v5.42.3, dated 2026-08-19. Go forth and query responsibly. 💖

📦 where this page comes from

ubuntu stonking: libace-perl 1.92-14build1 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms