A Person is either a NaturalPerson or a LegalPerson. 
Persons (in general) have a collection of addresses. 

An address consists in a type (a string) and a city (also a string). 

NaturalPerson - a subclass of Person - represents persons of flesh and blood. 
NaturalPersons have a name and a firstName (both strings) and an age (an integer). 
NaturalPersons sometimes have a partner (another NaturalPerson) and even children (a collection of NaturalPersons). 

LegalPerson - another subclass of Person - represents companies and other entities that the law regards as 'persons'. 
A LegalPerson has a name (a string) and a manager (a NaturalPerson). 

Note that Tangram does not create the corresponding Perl packages!.  That's up to the user.  However, to facilitate experimentation, Tangram comes with a module that implements the necessary classes.  For more information see Tangram::Springfield. 

The Schema lists all the classes that need persistence, along with their attributes and the inheritance relationships.  We must provide type information for the attributes, because SQL is more typed than Perl.  We also tell Tangram that Person is an abstract class, so it wastes no time attempting to retrieve objects of that exact class. 

Note that Tangram cannot deduce this information by itself.  While Perl makes it possible to extract the list of all the classes in an application, in general not all classes will need to persist.  A class may have both persistent and non-persistent bases.  As for attributes, Perl's most typical representation for objects - a hash - even allows two objects of the same class to have a different set of attributes. 

Tangram::Relational is the vanilla object-relational backend.  It assumes that the database understands standard SQL, and that both the database and the related DBI driver fully implements the DBI specification. 

Tangram also comes with vendor-specific backends for Mysql and Sybase.  When a vendor-specific backend exists, it should be used in place of the vanilla backend. 

In the process of saving Homer, Tangram detects that it contains references to objects that are not persistent yet (Marge, the addresses and the kids), and inserts them automatically.  Note that Tangram can handle cycles: Homer and Marge refer to each other. 

insert() returns an object id, or a list of object ids, that uniquely identify the object(s) that have been inserted. 

...is still up to you.  Tangram won't break in-memory cycles, it's a persistence tool, not a memory management tool.  Let's make sure we don't leak objects:

$homer->{partner} = undef; # do this before $homer goes out of scope

Also, when we're finished with a storage, we can explicitly disconnect it:

$storage->disconnect();

Whether it's important or not to disconnect the Storage depends on what version of Perl you use.  If it's prior to 5.6, you must disconnect the storage explicitly (or at least call unload()) otherwise the Storage will prevent the objects it controls from being reclaimed by Perl.  For more information see see Tangram::Storage. 

Actually, when Tangram loads an object that contains references to other persistent objects, it doesn't retrieve the referenced objects immediately.  Marge is retrieved only when Homer's 'partner' field is accessed.  This mechanism is almost totally transparent, we'd have to use tied to observe a non-present collection or reference. 

Usually we won't want to load all the NaturalPersons, only those objects that satisfy some condition.  Say, for example, that we want to load only the NaturalPersons whose name field is 'Simpson'.  Here's how this can be done:

This will bring in memory only the Simpsons; Burns or the Bouvier sisters won't turn up.  The filtering happens on the database server side, not in Perl space.  Internally, Tangram translates the $person-{name} eq 'Simpson'> clause into a piece of SQL code that is passed down to the database. 

The above example only begins to scratch the surface of Tangram's filtering capabilities.  The following examples are all legal and working code:

Note that Tangram uses a single ampersand (&) or vertical bar (|) to represent logical conjunction or disjunction, not the usual && or ||.  This is due to a limitation in Perl's operator overloading mechanism.  Make sure you never forget this, because, unfortunately, using && or || in place of & or | is not even a syntax error :(

Finally, Tangram make it possible to retrieve tuples of related objects:

Cursors provide a way of retrieving objects one at a time.  This is important is the result set is potentially large.  cursor() takes the same arguments as select() and returns a Cursor objects that can be used to iterate over the result set via methods current() and next():

The Cursor will be automatically closed when $cursor is garbage-collected, but Perl doesn't define just when that may happen :( Thus it's a good idea to explicitly close the cursor. 

Each Cursor uses a separate connection to the database.  Consequently you can have several cursors open at the same, all with pending results.  Of course, mixing reads and writes to the same tables can result in deadlocks. 

At this point, most people wonder what $person exactly is and how it all works.  This section attempts to give an idea of the mechanisms that are used. 

In Tangram terminology, $person a remote object.  Its Perl class is Tangram::Remote, but it's really a placeholder for an object of class NaturalPersonin the database, much like a table alias in SQL-speak. 

When you request a remote object of a given class, Tangram arranges that the remote object looks like an object of the said class.  It seems to have the same fields as a regular object, but don't be misled, it's not the real thing, it's just a way of providing a nice syntax. 

If you dig it, you'll find out that a Remote is just a hash of Tangram::Expr objects.  When you say $homer->{name}, an Expr is returned, which, most of the time, can be used like any ordinary Perl scalar.  However, an Expr represents a value in the database, it's the equivalent of Remote, only for expressions, not for objects. 

Expr objects that represent scalar values (e.g. ints, floats, strings) can be compared between them, or compared with straight Perl scalars.  Reference-like Exprs can be compared between themselves and with references

Expr objects that represent collections have an include methods that take a persistent object, a Remote object or an ID. 

The result of comparing Exprs (or calling include) is a Tangram::Expr::Filter that will translate into part of the SQL where-clause that will be passed to the RDBMS. 

Obviously Homer Simpson will be retrieved by both selects.  Are there two Homers in memory now?  Fortunately not.  There is only one copy of Homer in memory.  When Tangram load an object, it checks whether an object with the same ID is alredy present.  If yes, it keeps the old copy, which is desirable, since we may have changed it already. 

Incidentally, this explains why a Storage will hold objects in memory - until disconnected (again, this will change when Perl supports weak references). 

Tangram uses a single database transaction, but commits it only when the tx_commit()s exactly balance the tx_start()s.  Thanks to this feature any piece of code can open all the transactions it needs and still cooperate smoothly with the rest of the application.  If a DBI transaction is already active, it will be reused; otherwise a new one will be started. 

Tangram offer a more robust alternative to the start/commit code sandwich.  tx_do() calls CODEREF in a transaction.  If the CODEREF dies, the transaction is rolled back; otherwise it's committed.  The first example can be rewritten: