Posted by & filed under Announcements, Scitools Labs.

We’ve made several changes to the Understand Perl API recently. The largest change was upgrading from Perl 5.6.0 to 5.10.0 in build 473.
In addition to several cool new features like the smart match operators and switch statements, Perl 5.10 runs faster and has a smaller memory footprint. For more details on what the changes are and how to use
them, see the Perl 5.10 Release Announcement.

We are also in the process of adding Snapshot support for the Perl API for build 476. Now you can access historical versions of the code through your scripts as well. For example you can compare versions of files or write a script to compare metrics between versions.

What does this mean to you as an Understand script user?
In addition to the new features, the main side effect might be that some scripts might no longer work.

If any of your scripts stop working, review this list of incompatabilities in the Perl delta document. You can also make sure the scripts are still valid syntax by running maintain_uperl -c

The new snapshot changes modify the API in a few different ways:

  • Db::snapshots() to get a list of snapshots for the db.
  • $snapshot->name() to get the name of a snapshot and
  • $snapshot->open() to open the snapshot and return a $db variable that represents the snapshot.
  • The $db object is now “live”. It never used to be and it was never important that a script pass around and use the correct object. It is now critical.
  • Entity objects carry with them knowledge of the database/snapshot they belong to. Multiple databases/snapshots can be open and you can have entities from them all at once.
  • Any scripts which used entity ids $ent->id() as keys in hashes must be updated – the $ent->id is no longer unique across snapshots and multiple databases
    • At the beginning of the script add:   use Tie::RefHash;
    • declare the hash with:  tie my %my_hash, ‘Tie::RefHash;
    • use the actual entity object as the key $my_hash{$ent}, not the dereference of the entity $my_hash{$ent->id}.
    • <Don’t use Understand::ent->new($id) to reconstruct an Ent object from the id.

If you run into any problems that you need help with, feel free to shoot us an email at

UPDATE- We found some issues with the above approach to $ent->id and changed it with build 477. Using a Tie::RefHash for entities does not work as intended and is no longer recommended. We added a new call $db->ent_from_id($id), to reconstruct entity objects from ids.  To use entities as hash keys without later retrieving the entities from keys, it is sufficient to simply use $ent for the key. To later retrieve an entity from a key, instead, use the entity id as the key ($ent->id()), and retrieve the entity from the key with $db->ent_from_id($key). Note, it is not possible to safely store entities from different db’s into the same hash using this technique, since id’s are not unique across multiple open db’s.