NAME
SQL::Routine::SkipID - Use SQL::Routines without inputting Node IDs
DEPENDENCIES
Perl Version: 5.006
Standard Modules: none
Nonstandard Modules:
Locale::KeyedText 1.00 (for error messages)
SQL::Routine 0.47 (parent class)COPYRIGHT AND LICENSE
This file is part of the SQL::Routine::Castaways collection of archaic SQL::Routine functionality.
SQL::Routine::Castaways is Copyright (c) 1999-2004, Darren R. Duncan. All rights reserved. Address comments, suggestions, and bug reports to perl@DarrenDuncan.net, or visit "http://www.DarrenDuncan.net" for more information.
SQL::Routine::Castaways is free software; you can redistribute it and/or modify it under the same terms as Perl 5.8 itself.
Any versions of SQL::Routine::Castaways that you modify and distribute must carry prominent notices stating that you changed the files and the date of any changes, in addition to preserving this original copyright notice and other credits. SQL::Routine::Castaways is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SYNOPSIS
See the code inside the test script/module files that come with this module, 't/SQL_Routine_SkipID.t' and 't/lib/t_SQL_Routine_SkipID.pm'. That code demonstrates input that can be provided to SQL::Routine::SkipID, along with a way to debug the result; it is a contrived example since the class normally wouldn't get used this way. Such samples will not be shown in this POD to save on redundancy.
DESCRIPTION
The SQL::Routine::SkipID Perl 5 module is a completely optional extension to SQL::Routine, and is implemented as a sub-class of that module. The public interface to this module is essentially the same as its parent, with the difference being that SQL::Routine::SkipID will accept a wider variety of input data formats into its methods. Therefore, this module's documentation does not list or explain its methods (see the parent class for that), but it will mention any differences from the parent.
The extension is intended to be fully parent-compatible, meaning that if you provide it input which would be acceptable to the stricter bare parent class, then you will get the same behaviour. Where you will see the difference is when you provide certain kinds of input which would cause the parent class to return an error and/or throw an exception.
One significant added feature, which is part of this module's name-sake, is that it will automatically generate (by serial number) a new Node's "id" attribute when your input doesn't provide one. A related name-sake feature is that, when you want to refer to an earlier created Node by a later one, for purposes of linking them, you can refer to the earlier Node by a more human-readable attribute than the Node's "id" (or Node ref), such as its 'name' (which is also what actual SQL uses). Between these two name-sake features, it is possible to use SQL::Routine::SkipID without ever having to explicitly see a Node's "id" attribute.
Note that, for the sake of avoiding conflicts, you should not be explicitly setting ids for some Nodes of a type, and having others auto-generated, unless you take extra precautions. This is because while auto-generated Node ids will not conflict with prior explicit ones, later provided explicit ones may conflict with auto-generated ones. How you can resolve this is to use the parent class' get_node() method to see if the id you want is already in use. The same caveats apply as if the auto-generator was a second concurrent user editing the object. This said, you can mix references from one Node to another between id and non-id ref types without further consequence, because they don't change the id of a Node.
Another added feature is that this class can automatically assign a parent Node for a newly created Node that doesn't explicitly specify a parent in some way, such as in a create_node() argument or by the fact you are calling add_child_node(). This automatic assignment is context-sensitive, whereby the most recent previously-created Node which is capable of becoming the new one's parent will do so.
This module's added features can make it "easier to use" in some circumstances than the bare-bones SQL::Routine, including an appearance more like actual SQL strings, because matching descriptive terms can be used in multiple places.
However, the functionality has its added cost in code complexity and reliability; for example, since non-id attributes are not unique, the module can "guess wrong" about what you wanted to do, and it won't work at all in some circumstances. Additionally, since your code, by using this module, would use descriptive attributes to link Nodes together, you will have to update every place you use the attribute value when you change the original, so they continue to match; this is unlike the bare parent class, which always uses non-descriptive attributes for links, which you are unlikely to ever change. The added logic also makes the code slower and use more memory.
BUGS
See the BUGS main documentation section of SQL::Routine since everything said there applies to this module also.
The "use base ..." pragma doesn't seem to work properly (with Perl 5.6 at least) when I want to inherit from multiple classes, with some required parent class methods not being seen; I had to use the analagous "use vars @ISA; @ISA = ..." syntax instead.
The mechanisms for automatically linking nodes to each other, and particularly for resolving parent-child node relationships, are under-developed (somewhat hackish) at the moment and probably won't work properly in all situations. However, they do work for the test script/module code. This linking code may gradually be improved if there is a need.
CAVEATS
See the CAVEATS main documentation section of SQL::Routine since everything said there applies to this module also.
SEE ALSO
SQL::Routine::SkipID::L::en, SQL::Routine, and other items in its SEE ALSO documentation.