[VPM] ANNOUNCE: SQL-Routine 0.60

[Darren Duncan]

2005-04-25   Darren Duncan <perl at DarrenDuncan.net>
--------------------------------------------------

Version 0.60 of SQL::Routine (SRT), a fully atomic and portable 
abstract syntax tree to define any database tasks, has been uploaded 
to CPAN; it should appear on your favorite mirror within the next few 
hours.

http://search.cpan.org/dist/SQL-Routine/

This release is primarily to remove a large and long-standing but 
dubious feature where a SQL::Routine Node is valid to exist outside 
of a Container, which is the context by which it associates with 
other Nodes to form trees.  So there was a fair amount of code that 
had to work under both conditions of 'alone' and 'well known', and 
there was a fair amount of documentation that had to differentiate 
between the two statuses.  As of this release 0.60, Nodes may only 
exist within a Container (aka 'well known').

As a result of this change, the main executable code is about 10% 
smaller, and executes about that much faster.  More importantly, the 
code (and the documentation too) should now be fully twice as easy 
for a novice to understand and debug and extend.  It will even be a 
fair bit easier for me to continue maintaining the module.

A small part of the low-level public API has changed; if you invoked 
any of the following 6 functions or methods directly, you will have 
to change your code: new_node(), Node.new(), clear_node_id(), 
put_in_container(), take_from_container(), build_lonely_node().  But 
the change should be simple, helped by search-n-replace.

Where you used to do this:

   my $model = SQL::Routine->new_container();
   my $node = SQL::Routine->new_node( 'table' );
   $node->set_node_id( 42 );
   # ... up to now, you can do use $node in its 'alone' state ...
   $node->put_in_container( $model );
   # ... now the $node is 'well known' ...
   $node->set_literal_attribute( 'si_name', 'persons' );

You now do this:

   my $model = SQL::Routine->new_container();
   my $node = SQL::Routine->new_node( $model, 'table', 42 );
   # ... the $node is akin to 'well known' ...
   $node->set_literal_attribute( 'si_name', 'persons' );

Of course, if you used the higher-level API that is shown in the 
SYNOPSIS, you may have done this all along instead and weren't 
affected by the change:

   my $model = SQL::Routine->new_container();
   my $node = $model->build_node( 'table', { 'id' => 42, 'si_name' => 
'persons' } );

Where you used to do this:

   $node->take_from_container();
   # ... the $node is 'alone' again but still useable
   # ... $node is garbage collected when it goes out of scope

You now do this:

   $node->delete_node();
   # ... $node has mostly been destroyed by now

Where you used to do this:

   $node->clear_node_id();

You now can't do that anymore; a Node always has an id set; you can 
still change its value to another defined value using set_node_id(), 
however, or just delete the Node.

Where you used to do this:

   my $model = SQL::Routine->new_container();
   my $node = SQL::Routine->build_lonely_node( 'table', 42 );
   $node->put_in_container( $model );

You now do this:

   my $model = SQL::Routine->new_container();
   my $node = $model->build_node( 'table', 42 );

There are no other API changes that would break external code.

The Changes files for this release contains a lot more details than 
are shown in this announcement email; the Changes does not contain 
any before/after code, however.

Any questions, feedback, requests, or offers of assistence with the 
module are welcome and appreciated.

Thank you and have a good day. -- Darren Duncan