2004-03-08 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.26.
* This is primarily a "clean up" release where many relatively small or
medium sized changes were made to a large number of files. In other words,
the changes for this release were spread out widely rather than being
concentrated in just a few files. Some changes make this distribution
incompatible with previous ones; caveat early adopter.
* Updated the external dependency of this distribution on Locale::KeyedText
so that v0.03 of that module is now required. Corresponding to this, every
reference to Locale::KeyedText::_::[Message/Translator] is changed to refer
to Locale::KeyedText::[Message/Translator]; the classes were renamed.
* Updated SyntaxModel.pm (now v0.13), and Rosetta.pm (now v0.10), and both
ByTree.pm and SkipID.pm (each now v0.12), to reorganize and more properly
document each of their component class/package sets. The packages
[*]::_::[Container/Node] were each renamed to [*]::[Container/Node], and
[*]::_::[Interface/Engine] were each renamed to [*]::[Interface/Engine];
the packages [*]::_::Shared were merged into the module name-sake packages.
* Added new POD documentation section CLASSES IN THIS MODULE to each of the
above 4 modules which outlines the reality of the multiple package/classes
in each single module, and their relation. It also says that you should
never make your own modules with any of the same package or module names.
* Minor update to the DESCRIPTION of all *.pm files to replace "The ...
Perl 5 object class" with the more accurate "The [...] Perl 5 module".
* The multiple package declarations in the same 4 modules are no longer
obfuscated (split over 2 lines each) to prevent PAUSE from indexing them.
* SyntaxModel.pm no longer has separate actual "Container" and "Model"
classes, where the latter was a wrapper for the first and took care of the
first's automatic destruction. Instead, you must now explicitly call a
Container's new "destroy()" method (renamed from the private
"_destroy_properties" method) when you are done with it, so you don't leak
memory; see also the new POD section CAVEATS in that module, which explains
the change. The middle 3 BUGS paragraphs were removed from that module
also, as they described problems related to the now-removed wrapper. The
SYNOPSIS was updated to show destroy() in use. Related to these changes,
put_in_container() no longer checks for two class names.
* In all 3 SSM modules (as appropriate), the stateless new() and
create_empty_node() functions were respectively moved into the Container
and Node packages, and both have the name "new()"; each now uses its first
argument as the package name (or object) to bless into as is usual with
Perl classes, and unlike the hard-coded bless it had before. The
SQL::SyntaxModel package now has two new methods "new_container()" and
"new_node()" that exist in the place of the old functions, and these simply
call the moved functions; aside from the name changes, you can still invoke
them like you did before. Related to this change, the 3 private methods
"_get_static_const_[model/container/node]_class_name()" were removed. The
Container method "initialize()" was also removed. The private Container
method "_initialize_properties" was merged into its "new()" method.
* The code and property declarations in the SSM modules for Containers have
now been moved above those for Nodes; the module name-sake package code is
above both. The POD already had Container leading, so it wasn't changed.
* The SkipID.pm module is now developmentally severed from ByTree.pm. The
first now subclasses SyntaxModel.pm directly like the second does. All 4
ByTree.pm methods are now fully and independantly implemented in SkipID.pm,
so the latter is not dependant on the former. The two larger methods were
already separate code copies before, as that is where the modules differ,
but the two smaller ones were copied over to complete the separation. As
for POD, SkipID.pm used to have no method descriptions at all, but now it
has its own complete set for said 4 methods. These changes allow ByTree.pm
and SkipID.pm to diverge further from each other in all ways; SkipID.pm no
longer has to be backwards compatible with ByTree.pm, although in the short
term it still will be.
* Updated all 3 "en.pm" SSM localization files (each now v0.03) to account
for the above mentioned name changes and declaration orders.
* All of the test files received small updates to account for the package
name changes and constructor function name changes in the main modules and
their localization files. Also, all 3 of the SSM test files were updated
to explicitly destroy() the objects they create, and test that it worked.
* Changed the COPYRIGHT AND LICENSE for SyntaxModel.pm, its en.pm file,
Language.pod, and API_C.pod, as well as Rosetta.pm, Framework.pod,
SimilarModules.pod, and ReadMe. Mainly this was to make the text less
verbose. The license is essentially the same, still being the GPL v2 with
exceptions, but the exceptions have also been expanded; you may now link
with any independant modules without those having to be GPL, where
previously only independant modules that implemented or interfaced to
databases had that exception.
* Changed the COPYRIGHT AND LICENSE for ByTree.pm, SkipID.pm, and each of
their en.pm files. These 4 files are now licensed "under the same terms as
Perl 5.8 itself" instead of being licensed under the GPL with exceptions.
The 4 files also don't say they are "part of the SQL::SyntaxModel library".
* Added a new short documentation section named AN ALTERNATIVE SECOND
VERSION to both Framework.pod and API_C.pod, suggesting that my upcoming
second major versions of Rosetta and SQL::SyntaxModel may be implemented
using Parrot IMC rather than C. Inspired by dbdi-dev@perl.org.
* All 4 of the t/*.t files were renamed so that they no longer have the
numerical prefix (10_,11_,12_,20_); all references to those files by name
have been likewise updated, such as MANIFEST and INSTALL.
* Added new English Localization file lib/Rosetta/L/en.pm (v0.01) for
Rosetta, and refactored some error message generation code in Rosetta.pm.
* Added new file lib/Rosetta/Engine/Null.pm (v0.01) which is a mock Engine
whose only purpose in life is to help test the core Rosetta module.
* Added a large chunk of documentation to Rosetta.pm, mainly consisting of
a complete function/method list. Some other code and documentation changes
were made in Rosetta.pm.
2004-03-03 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.25.
* Implemented and altered large portions of Rosetta.pm, bringing it up to
version 0.09 from 0.08. Most code for this module was created, and any
previously existing property declarations were heavily edited. The new
version isn't yet functionally complete, but it should be about 70% of the
way there. The "Rosetta::_::[Interface/Engine]" classes were renamed to
"Rosetta::[Interface/Engine]" so that they would be easier for external
code to refer to, which should happen a lot. (We'll just have to ensure
that no one tries to make extension modules with those names.) As an
experiment, those two inner class declarations are no longer slightly
mangled to hide them from the PAUSE indexer. We'll see what serves the
community better. For documentation, a large chunk was added to STRUCTURE
and a couple dozen lines were changed in SYNOPSIS; the rest was practically
unchanged. One significant design change is that when you create the first
Interface with new(), you always pass an "application_instance" SSM Node.
* Minor update to SkipID.pm (now v0.112) that reverses a mistaken change
that was done as part of release 0.23; the two methods create_node_tree()
and create_child_node_tree() have been reverted and are now identical to
the versions in release 0.22. The "mistaken change" had been intended to
fix several "uninitialized value" warnings, which did not exist in release
0.22. A SyntaxModel.pm update for release 0.23 was what caused the
warnings to appear; the correct solution would have been to mirror the
SyntaxModel.pm change in SkipID.pm so they remained compatible, and said
change has been done now. The private _set_initial_container_props()
method was moved from the Model class to the Container class and renamed to
_initialize_properties(); this properly fixed the warnings.
* Aside from setting the test files to look for the newer module versions,
and updating the TODO and ChangeLog, no other files were changed.
2004-02-23 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.24.
* Made a design simplification in Language.pod (and SyntaxModel.pm, which
is now v0.12) that makes my short term development process easier, and
makes SQL::SyntaxModel / Rosetta easier to adapt. For the present,
"routines" may only do DML-type actions, whether implemented on the
database side or the application side. The pre-existing but poorly used
"commands" are now formally separate from "routines"; "commands" are
pseudo-routines that handle the DDL functions for now, plus database
"connect"/"disconnect", and they may only be run on the application side.
Other design improvements were made as well, such as adding "instance
options", and splitting 'database product' into 'data [storage/link]
product'. Other small fixes in SyntaxModel.pm included some method
documentation updates.
* Fleshed out the example code in t_SQL_SyntaxModel.pm so that it is now
correct/realistic and inline with the Language.pod improvements; the
SYNOPSIS POD in SyntaxModel.pm was correspondingly updated.
* The example Nodes lists in Language.pod that pertained to views, and the
corresponding test/example code in t_SQL_SyntaxModel_ByTree.pm, was
simplified in places so that fewer Nodes were necessary to express the same
concepts. Corresponding ByTree.pm (now v0.111) CONTRIVED EXAMPLE update.
* Minor data update in SkipID.pm (now v0.111).
* Some updates in Framework.pod. One of the most significant is that the
"module group" called "Engine" has been re-named to "Interface" and the
group named "Driver" has been re-named to "Engine". The Rosetta core now
has just 2 inner classes, which are "Rosetta::_::Interface" and
"Rosetta::_::Engine"; the first is all that applications talk to, and the
second is a mandatory super-class for all prospective Engine plug-in
modules. The SYNOPSIS section was moved to the end of the file and
renamed to OLDER EXAMPLE PROGRAM. Also renamed the EXPANDED MODULE LIST
docs to OLDER DOCUMENTATION. The module's NAME was changed, and a few other
changes were made.
* Began first major implementation of Rosetta.pm, bringing it up to version
0.08 from 0.073; both the code and documentation were almost entirely
re-written. The new version isn't functionally complete yet, but it does
have complete property declarations, a few functions, and a fully written
SYNOPSIS, a full DESCRIPTION, a partial SYNTAX and STRUCTURE. The NAME,
DEPENDENCIES, COPYRIGHT, SEE ALSO are unchanged or mostly unchanged from
before. It is not tested aside from that it compiles.
2004-02-12 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.23.
* Some reorganization of the constructor and destructor methods was done in
SQL::SyntaxModel. The new() method can now be invoked off of any object
type just like create_empty_node(); corresponding to this, a new private
method named _get_static_const_model_class_name() was added to all 3 SSM
modules (all 3 are now at v0.11 up from v0.10). These 3 methods were moved
from the Model class to the Container class: initialize(),
_set_initial_container_props(), _destroy_container_props(); you can now
invoke the first one from either a Model or Container object.
* Fixed a put_in_container() bug so it accepts both SQL::SyntaxModel and
SQL::SyntaxModel::_::Container objects as input, which users consider the
same thing. Simplified the code in remove_reciprocal_links().
* Fixed a bug concerning Nodes that are in "At Home" status. By definition
they are not supposed to be visible to any other Nodes and they should not
appear in any get_all_properties() output; however, any Nodes that had
pseudo-Node parents were always being output regardless of their status.
This was fixed by taking the code that added a Node to or removed a Node
from its pseudo-Node parent's child list and moving it from the 'container'
methods to the 'reciprocal' methods.
* Updated the move_before_sibling() method so that it also works with Nodes
that are siblings beneath pseudo-Node parents, rather than just under
normal Node parents. One related error message key/value was also altered,
with SQL::SyntaxModel::L::en (now v0.021) getting a minor update.
* Added new with_all_nodes_test_mandatory_attributes() method to the
Container class that tests all Nodes in it for test_mandatory_attributes().
* Fixed several "uninitialized value" warnings in SQL::SyntaxModel::SkipID.
* Made a large number of design changes and other documentation
improvements in Language.pod, with matching updates in all of the other
code, test, and documentation files. Several Node types and enumerated
types were created, or reorganized, or removed. LANGUAGE CONCEPT STRUCTURE
was mostly rewritten, and there are now 5 main Node groupings ('elements',
'blueprints', 'tools', 'sites', 'circumventions') instead of the previous
4; the last one is unchanged, the first was 'common-space', the second was
merged from most of 'database-space' and 'application-space'. One major
design advancement concerned the ability to recognize and act properly with
multiple instances of the same database schema or application blueprint, as
well as general communications between applications and catalogs, and
between catalogs, and concerning database users and multiple data links and
multiple implementing database products. Every Node type now has a list of
defined attributes, though some are incomplete; none don't have any. The
structure of view and routine components has been improved and matured;
issues regarding support for defining insert/update/delete operations have
matured (views take care of it), as have issues about views inside
routines. There is still a major outstanding concern in the design to work
out regarding routines, SQL::SyntaxModel 'commands', as well as 'standard
procedures'. Fixed a minor documentation mistake where LITERAL ATTRIBUTE
TYPES was a head2 rather than a head1.
* Added an actual SYNOPSIS documentation section to SQL::SyntaxModel that
demonstrates its use (by itself). Also added new test battery file
lib/t_SQL_SyntaxModel.pm which tests SQL::SyntaxModel by itself; all 3 of
the t/1*_SQL_SyntaxMode*.t main test scripts now use it. Several other
minor documentation updates were made in SQL::SyntaxModel.
* A block of older documentation was moved from Framework.pod (EXPANDED
MODULE LIST -> Schema Modules) to Language.pod (OLDER DOCUMENTATION).
* Multiple updates in Framework.pod, mainly concerning drivers. Also
chopped the DEPENDENCIES section from that file. Multiple updates in
Rosetta.pm (now v0.073), mainly to bring its declaration details in line
with SyntaxModel.pm; DEPENDENCIES are in the new format, and require Perl
5.006, and current versions of the other modules. Also chopped out the
single "function" which didn't actually do anything. Other minor updates
there and in SimilarModules.pod.
2004-02-04 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.22.
* Renamed the SQL::SyntaxModel Node object property (and accessor methods)
'node_attributes' to 'node_ref_attributes'; the corresponding attribute
type is now called 'node_ref' (to complement 'literal' and 'enumerated').
Practically every SSM code or doc file was updated to correspond. All SSM
code modules are now at version 0.10, and their locale files are at 0.02.
* Fixed a bug in the put_in_container() Node method of SQL::SyntaxModel so
that it now prevents you from adding a Node with the same Id as one already
in the Container. The set_node_id() method was already correct.
* Created new documentation file lib/SQL/SyntaxModel/Language.pod, which is
a heavily edited combination of the also-removed DataDictionary.pod and
XMLSchema.pod files. The documentation sections in SyntaxModel.pm named
BRIEF NODE RELATIONSHIP LIST and BRIEF NODE TYPE LIST were also removed in
favor of the new file. After these changes, Language.pod is now *the* main
documentation for SQL::SyntaxModel, besides the POD in that module itself.
* Corresponding to the above change, SyntaxModel.pm v0.10 now recognizes a
significantly different and very much incompatible list of Nodes, Node
attributes, enumerated types, and literal types than it did before. So do
ByTree.pm v0.10 and SkipID.pm v0.10. The test code was edited to work with
the new module and became a bit simpler in the process (and the CONTRIVED
EXAMPLE documentation is the same code that the tests use).
* Added new method move_before_sibling() to SyntaxModel.pm, which lets you
change the order of a child Node under its parent after they are linked.
* There are no longer any 'order' attributes for any Node type; the
sequence of a set of Nodes is now determined entirely by their order in the
model (under a common parent), just like XML nodes are. You will now have
to add a sequencing column yourself if saving Nodes as RDBMS records, which
is the only place where the old 'order' attributes would have been useful.
* Removed deprecated method collect_inherited_attributes() from ByTree.pm;
the paradigm it supports, where redundant attributes are stored in parent
and child Nodes, is no longer in use. Removed calls to it from SkipID.pm.
* Moved half of the functionality of ByTree.pm into SyntaxModel.pm,
specifically the generic attribute accessor methods and related information
function. All of these are wrappers around existing SyntaxModel.pm
methods, letting you access Node attributes without knowing what their
major types are. They are meant to be a convenience only, and you should
generally avoid them for performance reasons. After the change, ByTree.pm
only contains the 4 public methods which are its namesake.
* Consolidated all of the test_mandatory_*_attributes() methods into a
single test_mandatory_attributes() method.
* Updated the get_all_properties_as_*_str() methods so that they output
Node attributes in a different order than before. Attributes now appear in
the same order as they do in the Language.pod documentation, which is a
reasonable conceptual order. Previously, they were output in alphabetical
order by attribute name, except that 'id' was always first.
* Updated the 1*_SQL_SyntaxMode*.t test files so that they now trap any
exceptions thrown by the SSM modules and display their corresponding
localized error message. Of course, the current tests should never run
the exception handler if they pass, but the messages were very helpful
when I was *editing* the SSM modules (and they also serve as a practical
example of Locale::KeyedText in use).
* Made small documentation changes, largely related to the above changes,
in these files: Framework.pod, API_C.pod, MANIFEST.
2004-01-18 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.21.
* This release corresponds to the first releases of the independant
Locale-KeyedText distribution (0.01 and 0.02). The Rosetta distribution
now has an external dependency in the form of Locale::KeyedText v0.02.
* All 3 SQL::SyntaxModel/::* modules (now at version 0.09) have been
updated to throw their error exceptions as machine-readable
Locale::KeyedText Message objects rather than as strings. Aside from this
fact, the modules' API is identical to the 0.08 versions.
* One line of SkipID->set_node_attribute(), which caught a parent-thrown
exception and tried to gracefully recover from it, was updated to account
for the exception being an object rather than a string.
* Added 3 new user text localization data modules, one per existing
SQL::SyntaxModel/::* module; each is named "[code module name]::L::en", and
each has its own complete POD. The user text data that populates these,
aside from minor edits, originally existed in the 0.07 versions of the code
modules, in the form of comments beside the spots where the then-string
exceptions were thrown; these comments have been removed from the code
modules. A few of the exception keys had slight changes to their names.
* As a result of the above changes, Rosetta is now fully multi-lingual as
far as users of your programs are concerned; support for any number of new
languages can be added simply by adding a localization data file for each.
* Updated the debugging methods get_all_properties_as_perl_str() and
get_all_properties_as_xml_str() in SyntaxModel.pm to escape any literal
values that they output, so that the resulting Perl or XML string is well
formed. In the case of the Perl, if any Node literal attribute values
contained either an "'" or an "\" then the output Perl code used to have
syntax errors or was otherwise wrong, but now it doesn't. Likewise for the
XML, any ['&','"','<','>'] characters in literals are now escaped. This
makes the methods slower, but the output is now "correct".
* Made some minor POD updates in SyntaxModel.pm, ByTree.pm, SkipID.pm.
* Updated the 3 "...SyntaxModel..." test files to account for the version
changes and to also test the locale modules for each code module.
* Multiple updates to Framework.pod to that bring it up to date with
corresponding external changes in the last few Rosetta distributions.
Mainly it was the BRIEF MODULE LIST and EXPANDED MODULE LIST documentation
sections that were updated.
* These files saw small updates: Makefile.PL, ReadMe, and MANIFEST.
2003-12-21 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.20.
* Fixed minor POD bug in SyntaxModel.pm regarding '>' escaping.
* Removed these deprecated shim methods from SyntaxModel.pm: create_node(),
create_nodes(), get_root_node(). Also removed the deprecated code from
add_child_node() that made it a potential shim for create_child_node_tree().
Then updated the test scripts/modules to use the replacements for the above,
and likewise the CONTRIVED EXAMPLE documentation.
* Split SQL::SyntaxModel into two modules, itself and a new subclass named
SQL::SyntaxModel::ByTree. The split was clean, and consisted of moving the
following 14 methods out of the core SQL::SyntaxModel, with their POD:
major_type_of_node_type_attribute(), expected_attribute_major_type(),
get_attribute(), get_attributes(), clear_attribute(), clear_attributes(),
set_attribute(), set_attributes(), test_mandatory_attributes(),
collect_inherited_attributes(), create_child_node_tree(),
create_child_node_trees(), create_node_tree(), create_node_trees(). In
addition, the CONTRIVED EXAMPLE documentation was moved to the new module.
* Now there are 3 nested and closely related modules. SyntaxModel.pm is
the core; ByTree.pm is an optional subclass of that, and SkipID.pm is now
an optional subclass of ByTree.pm. All 3 of these modules are at version
0.08. Related to this, t_SQL_SyntaxModel.pm was renamed to
t_SQL_SyntaxModel_ByTree.pm, 1_SQL_SyntaxModel.t was split into
10_SQL_SyntaxModel.t and 11_SQL_SyntaxModel_ByTree.t, the other two test
files now have '12' and '20' prefixes; the test files were also updated
internally. Small updates to MANIFEST and INSTALL.
* Small updates to ByTree.pm and SkipID.pm so that they use the Node
property accessor methods provided by SyntaxModel.pm rather than accessing
properties defined by that class directly. I could not do this for the
Node and Model properties, however, as they have no appropriate methods.
2003-12-18 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.19.
* This is a major functionality update release, focused exclusively in 3
files: SQL::SyntaxModel, SQL::SyntaxModel::SkipID, SQL::SyntaxModel::API_C.
The first two of those each had their version numbers incremented from 0.06
to 0.07. No other files were changed at all, except that the module
version numbers looked for by the test scripts are incremented, and except
for the ChangeLog and TODO files, and except for the distro version number
in Makefile.PL.
* The modules now require Perl 5.006, up from 5.004, partly because the
newer version lets you throw objects as exceptions, and because it adds the
'use base' pragma, and possibly for other reasons. The modules also no
longer use Carp.
* SQL::SyntaxModel was almost entirely rewritten; it is still based on the
previous design, but more than 90% of the code and around 50% of the POD
documentation was changed. The most significant change is that the few
large and complicated methods of 0.06 (40; 21 pub + 19 priv) have been
replaced with many small and simple methods in 0.07 (89; 71 pub + 10 priv).
Related to this, some of the input constraints (such as mandatory
properties) which the module used to enforce up front are now deferred
until you ask. Both of these changes should make this module orders of
magnitude easier to use, giving you a much finer degree of control over how
it works, and in particular it is now practical to build its objects
piecemeal (such as if a user is editing them manually).
* The old "attributes" list Node property has been split into 4 different
properties: "literal attributes" (the usual numbers and strings and
booleans), "enumerated attributes" (allowed values are predefined by the
class), "node attributes" (references to one Node from another), and the
special "node id" (unique integer identifier for a Node in a Container). So
we now have 4 properties whose rules for dealing with them are each simpler
than the complex rules for dealing with the old combined property. Note
that while Node attributes are now physically separated, they all still
have unique names between the combined group. Ideally you should code your
program to use the separate accessor methods for each type of attribute,
for better performance and reliability, but for the moment I have also kept
wrapper methods that you can reach all attributes through regardless of
their major type. The wrappers are significantly slower, but they give a
semblence of backwards compatibility.
* The old "parent node" Node property has been replaced by a "primary
parent node attribute name" property. The property in 0.06 stored a
reference to the current Node's primary parent, and this duplicated one of
the Node attributes that had a reference to the same Node. In 0.07 the
duplication is gone and the attribute holds the only reference; the new
"primary parent" property now just holds the name of what attribute to go
to for the parent.
* Node objects can now exist apart from a Container; in fact, they are
initially created that way, and then putting them in a Container is a
separate step. This contributes towards their new ease of use, as you can
build them piecemeal and otherwise use them in your code far away from
where any Containers are. But Nodes still don't link together except
within the context of a Container. A side effect of this change is that it
is now a lot easier to duplicate Nodes or move Nodes from one Container to
another, should you want to do that.
* The reciprocation of references from a child Node to its parent Nodes,
which is what makes a parent aware that it even has children, can now be
deferred (and is by default). As a result, a Node that is under
construction within a Container will not have other Nodes trying to use it
before it is ready. This is another reliability and simplicity feature.
* The concept of "super-nodes" physically representable by Node objects no
longer exists. That concept, renamed to "pseudo-nodes", now only exists
within the context of get_all_properties[/*]() outputs.
* Each method is now arranged differently such that all preconditions are
tested prior to storing any input; this means that if a method throws an
exception (such as on bad input), you can now be confident that the objects
are unchanged at best, or consistant or recoverable at worst. By contrast,
0.06 made changes hot, so if a first change worked but a second didn't,
then the objects may not have been in a consistant state, and the program
would have been better to exit than to try using them afterwards.
* Each method now throws machine-readable exceptions on failure, so that
the calling code now can discern what the problem was (and where and how),
so it knows how to recover gracefully.
* SyntaxModel.pm is now physically reorganized for easier maintenance. Most
of the POD is now at the end of the file, rather than above or mixed in
with the code; this also means the Perl parser has less file to read
through to get all the code. Within the code, the methods for Node objects
now appear first, with Container methods afterwards; in 0.06 the Container
methods appeared first. Within the POD, that long and unweildy SYNOPSIS
code has been moved to the very end of the file, after everything else, and
renamed to CONTRIVED EXAMPLE, so you no longer have to wade through it to
get to the important stuff; the new SYNOPSIS at the top is currently empty
except for a comment to look below.
* Other changes within the POD are as follows: Added new FAULT TOLERANCE
AND MULTI-THREADING SUPPORT and NODE EVOLUTION STATES sections. Mostly
rewrote DEPENDENCIES, SYNTAX, BUGS, and all the method descriptions.
Slight changes to DESCRIPTION, STRUCTURE and BRIEF NODE TYPE LIST. The
remaining parts, NAME, COPYRIGHT AND LICENSE, BRIEF NODE RELATIONSHIP LIST
and SEE ALSO, were left completely unchanged.
* SQL::SyntaxModel::SkipID was updated to remain compatible with the
changes to its parent class. It can now override or extend its parent's
functionality in a clean way, without requiring the parent to have
unpleasant hacks or placeholders in it for the child class to work. SkipID
now has 11 distinct or overriding methods, down from 12 before; half of
them are largely unchanged, including the 2 bigger ones (that add new
functions), and the other half were rewritten or replaced. The POD and
code in SkipID was rearranged to mirror the new SQL::SyntaxModel
arrangement, such as Node methods above Container ones, and most POD at the
end of the file, and SYNOPSIS converted to CONTRIVED EXAMPLE at the end.
* SQL::SyntaxModel::API_C had its "code" portion mostly rewritten to bring
it up to date with the current SQL::SyntaxModel organizational structure;
in fact, some of the Perl module's design changes were done to make it work
more like the prospective C module would, so functionality and APIs are
easier to map between them. Now all of the C headers for libSQLSM will be
in one file, since there are sufficiently few of them.
* The 0.07 releases of SQL::SyntaxModel and SkipID intentionally have a few
extra, deprecated bits in them so that they are backwards compatible with
the 0.06 releases of both, or at least to the extent that all of my testing
scripts and SYNOPSIS / CONTRIVED EXAMPLE code worked against both when left
completely unchanged, producing the same output from the same input. This
is why the test code was left the same from the last release to this one.
* Some performance tests were run, to compare the speed of the 0.06 and 0.07
releases, and the results are below. For these tests, both versions got the
same input and received the same output. However, the newer module versions
were significantly slower, as the old-style inputs are no longer optimal for
them. The speed tests were run using the Perl v5.6.0 built for darwin, that
was bundled with Mac OS X 10.2.6. (The normal tests were run under both that
Perl and a Perl v5.8.1rc4 that I build myself from source under the same OS.)
Each pair of adjacent rows shows version 0.06 and 0.07 using the same input.
The 'INB6' means input that the core SQL::SyntaxModel would accept, and the
'INE6' means input that only SkipID would accept. 'MakeAndBreak' creates a
Container and populates it with Nodes, then lets it go out of scope and
auto-destroy itself. 'Output' calls get_all_properties_as_xml_str() on one
identical pre-populated Container. They are the same as the t/* code.
Benchmark: timing 1000 iterations of MakeAndBreak...
SSM 006 INB6: 54 wallclock secs ( 53.36 usr + 0.00 sys = 53.36 CPU) @ 18.74/s (n=1000)
SSM 007 INB6: 99 wallclock secs ( 97.95 usr + 0.00 sys = 97.95 CPU) @ 10.21/s (n=1000)
SSMSID 006 INB6: 72 wallclock secs ( 70.87 usr + 0.00 sys = 70.87 CPU) @ 14.11/s (n=1000)
SSMSID 007 INB6: 131 wallclock secs (129.59 usr + 0.00 sys = 129.59 CPU) @ 7.72/s (n=1000)
SSMSID 006 INE6: 94 wallclock secs ( 93.70 usr + 0.00 sys = 93.70 CPU) @ 10.67/s (n=1000)
SSMSID 007 INE6: 253 wallclock secs (251.48 usr + 0.00 sys = 251.48 CPU) @ 3.98/s (n=1000)
Benchmark: timing 1000 iterations of Output...
SSM 006 INB6: 35 wallclock secs (34.20 usr + 0.00 sys = 34.20 CPU) @ 29.24/s (n=1000)
SSM 007 INB6: 34 wallclock secs (32.33 usr + 0.00 sys = 32.33 CPU) @ 30.93/s (n=1000)
SSMSID 006 INB6: 35 wallclock secs (34.54 usr + 0.00 sys = 34.54 CPU) @ 28.95/s (n=1000)
SSMSID 007 INB6: 33 wallclock secs (32.81 usr + 0.00 sys = 32.81 CPU) @ 30.48/s (n=1000)
SSMSID 006 INE6: 35 wallclock secs (34.46 usr + 0.00 sys = 34.46 CPU) @ 29.02/s (n=1000)
SSMSID 007 INE6: 37 wallclock secs (35.85 usr + 0.00 sys = 35.85 CPU) @ 27.89/s (n=1000)
The memory usage figures for each test were constant and small, indicating
no memory leaks.
2003-09-26 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.18.
* This is a major functionality update release, focused mostly in the
SQL::* code files; few changes were made to the documentation-only files.
* SQL::ObjectModel has been renamed to SQL::SyntaxModel, and is now at
v0.06 (was v0.05); the proposed C library name was also changed from
"libSQLOM" to "libSQLSM". All files which made references to the old names
have been updated, and the corresponding test file is also renamed.
* Small updates to DataDictionary.pod. Every table column which was an
'int' data type is now a 'uint'. Also, each of these 4 tables had a column
added or moved: table_ind_col, view, view_col_def, block.
* Rewrote the STRUCTURE main documentation in SyntaxModel.pm so that it is
much easier to understand, and more accurately reflects how the module
works. Also, part of the old STRUCTURE was split into the new BRIEF NODE
RELATIONSHIP LIST main documentation section.
* SQL::SyntaxModel is now a lot more strict with its input constraints, to
help ensure that its objects are always in a consistant and useable state.
Any deviation from proper input will throw an exception; any code which
massaged input (such as numbers, booleans, enumerated values) into a proper
format is now gone; a benefit from this is that any data that you get out
is guaranteed to match what you put in. All Nodes are now required to have
a primary parent Node (except the single root); there are no longer any
detached nodes. Node ids are required to be integers >= 1, and other
numbers all have to be non-negative integers. Uniqueness of Node ids is
enforced; however, uniqueness of other attributes currently is not.
Mandatory Node attributes are enforced to be present (they mostly were in
0.04). No Node attributes can reference another Node that doesn't exist.
* SyntaxModel had some significant structural implementation details
changed. Node attributes now actually contain Perl references to other
Nodes instead of copies of their 'id' attributes. Related to this, each
Node can now have multiple 'parent' Nodes simultaneously; one of these is
more important than the others, and corresponds to the single parent XML
node. A Node's child list now contains all of the Nodes which refer to it
in an attribute. So parent-child relationships can now be many-to-many
rather than one-to-many. This is in some ways actually a simpler design
than before. One benefit gained from this is that you can now change a
Node's "id" property easily; before you couldn't. Another is that you can
easily and efficiently determine every other Node that links to the one you
hold, should you need to update them on certain changes to your Node.
Another is that you can crawl from one Node to another much easier, such as
when you want to generate SQL strings from them or otherwise use them.
* These SyntaxModel.pm methods were renamed: node_attribute() to
attribute(), add_node_attributes() to add_attributes(). The method
add_child_nodes() was split into itself and add_child_node().
* These SyntaxModel.pm methods were removed: clone(), unlink_parent_node(),
set_node_attributes(), set_child_nodes(). Their functionality was not
currently being used, and if any was going to be re-added, then
considerable thought will be needed in order to do it properly.
* These SyntaxModel.pm methods were added: initialize(), get_node(),
delete_node(). The latter replaces parts of the removed methods.
* Some extraneous SQL::SyntaxModel functionality has been removed from that
module and put into a new module named SQL::SyntaxModel::SkipID (v0.06),
which sub-classes the first module. The corresponding *.t file was also
split. The moved functionality is completely optional, and allows a
programmer to avoid explicit use of a Node's "id", and instead reference
Nodes using a different, more human-readable attribute, such as their
'name' (which is what actual SQL uses); it also sets default values for
more Node attributes, including auto-generation of an 'id' serial number;
it also can automatically assign a parent Node to a new Node, based on the
context of which Nodes were created previously. This can make the module
"easier to use" in some circumstances than the bare-bones SQL::SyntaxModel.
However, the moved 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; this added logic also makes the code slower and
use more memory. Note that the upcoming C library will probably supplant
only the core SQL::SyntaxModel module, with SkipID staying in the realm of
a pure-Perl add-on.
* The test (*.t) scripts were split up into a module, containing input and
output data, and a thin script that uses it. This was done so that the
separate test scripts for the split up module can use some of their test
data in common. However, 'make test' doesn't seem to work when said
modules are in the 't' subdirectory, so I put the new for-testing-only
modules in 'lib' instead: t_SQL_SyntaxModel.pm, t_SQL_SyntaxModel_SkipID.pm.
* All sorts of SyntaxModel implementation details were updated, and any
code which seemed hackish was removed. It is much easier now to look at
the code and know how it works or be confident that it works. Or, if any
dubious code still exists, most of it is in SkipID.
* Note that, for all intents and purposes, you should be able to use
SQL::SyntaxModel::SkipID v0.06 in the same way as you used SQL::ObjectModel
v0.05; it accepts the same input, and except for some minor tweaks,
produces the same output.
* Some performance tests were run, to compare the speed of the old module
to the two new ones, and the results are below; the test environment was
the same as that for release 0.17.
Time test results, as reported by the Benchmark module;
#1 shows SQL::ObjectModel v0.05;
#2 shows SQL::SyntaxModel v0.06;
#3 shows SQL::SyntaxModel::SkipID v0.06 with same input as SM 0.06;
#4 shows SQL::SyntaxModel::SkipID v0.06 with same input as OM 0.05:
Benchmark: timing 1000 iterations of MakeAndBreak, Output...
MakeAndBreak: 80 wallclock secs (78.66 usr + 0.00 sys = 78.66 CPU) @ 12.71/s (n=1000)
Output: 21 wallclock secs (21.04 usr + 0.00 sys = 21.04 CPU) @ 47.53/s (n=1000)
MakeAndBreak: 54 wallclock secs (53.55 usr + 0.00 sys = 53.55 CPU) @ 18.67/s (n=1000)
Output: 36 wallclock secs (34.33 usr + 0.00 sys = 34.33 CPU) @ 29.13/s (n=1000)
MakeAndBreak: 73 wallclock secs (71.55 usr + 0.00 sys = 71.55 CPU) @ 13.98/s (n=1000)
Output: 35 wallclock secs (34.14 usr + 0.00 sys = 34.14 CPU) @ 29.29/s (n=1000)
MakeAndBreak: 95 wallclock secs (93.25 usr + 0.00 sys = 93.25 CPU) @ 10.72/s (n=1000)
Output: 35 wallclock secs (33.91 usr + 0.00 sys = 33.91 CPU) @ 29.49/s (n=1000)
Memory usage (peak), as reported by 'top', for the above 4 items:
PID COMMAND %CPU TIME #TH #PRTS #MREGS RPRVT RSHRD RSIZE VSIZE
605 perl 99.3% 1:34.30 1 9 23 1.47M 308K 1.66M 2.59M
1222 perl 96.7% 1:04.05 1 9 23 1.48M 308K 1.67M 2.59M
1227 perl 98.4% 1:38.31 1 9 23 1.60M 308K 1.79M 2.59M
1231 perl 95.8% 1:40.83 1 9 23 1.55M 308K 1.74M 2.59M
* As before, time taken increases linearly with the number of repetitions,
and the RAM consumption is unchanged and low no matter how long the test
runs. Comparing the first two lines, which show input provided in the
'proper' format for each module version, we see v0.06 is one-third faster
for data input than v0.05, even though it is doing more validation tests,
because it is no longer "jumping through hoops" to recognize the data.
Whereas, v0.05 is two-fifths faster for outputting to XML, since v0.06 now
has to filter more Node meta-data (to convert many-to-many into a normal
tree). The last two lines take predictably longer because they are doing
both the extra input validation and the "jumping through hoops". Lines 1
and 4 have the same input and output data, while 2 and 3 have the same.
* Note: Where ObjectModel.pm was 93K in file size (46K POD + 47K code /
comments), SyntaxModel.pm is 93K (52K POD + 41K code), and SkipID.pm is 43K
(25K POD + 18K code). So the total code with '#' comments in v0.06 is 59K,
12K more than before; the total POD in v0.06 is 77K, 31K more.
2003-09-16 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.17.
* This update mostly deals with implementation details for ObjectModel.pm,
which is now at v0.05 (was v0.04); there were no interface changes.
* Updated ObjectModel.pm to assure proper destruction of its objects, by
breaking all of the circular references in their internal data structures,
and hence avoid causing memory leaks. The main SQL::ObjectModel class was
split into itself and a new Tree private class; the latter now contains all
of the internal cross-references with the Node private class, and the
former now never has any internal references to it. The change was
implemented this way so that users never have to explicitly call a
destructor method; the module will "do the right thing" and destroy itself
when external refs go out of scope.
* This is a speed and memory usage comparison between SQL::ObjectModel 0.04
and 0.05, based on running a SQL-ObjectModel.t that was slightly modified
to add Benchmark calls. The test is in 2 parts; the first, 'MakeAndBreak',
creates, populates, and destroys 1000 identical SQL::ObjectModel objects;
the second, 'Output', converts one identical object into a non-escaped XML
string 1000 times. The test script, which is almost entirely a
multi-dimensional Perl hash of input data, is about 17K in file size. The
output XML string is also about 17K in file size. It appears that each
in-memory SQL::ObjectModel object, thusly populated, takes about 160K of
RAM. The test machine had 768M of physical RAM, which was half unused.
Memory usage (peak), as reported by 'top', first 0.04 and second 0.05:
PID COMMAND %CPU TIME #TH #PRTS #MREGS RPRVT RSHRD RSIZE VSIZE
606 perl 98.7% 1:28.76 1 9 665 162M- 308K 162M 163M
605 perl 99.3% 1:34.30 1 9 23 1.47M 308K 1.66M 2.59M
Time test results, as reported by the Benchmark module, for 0.04 and 0.05:
Benchmark: timing 1000 iterations of MakeAndBreak, Output...
MakeAndBreak: 80 wallclock secs (78.59 usr + 0.00 sys = 78.59 CPU) @ 12.72/s (n=1000)
Output: 21 wallclock secs (21.11 usr + 0.00 sys = 21.11 CPU) @ 47.37/s (n=1000)
MakeAndBreak: 80 wallclock secs (78.66 usr + 0.00 sys = 78.66 CPU) @ 12.71/s (n=1000)
Output: 21 wallclock secs (21.04 usr + 0.00 sys = 21.04 CPU) @ 47.53/s (n=1000)
So, the performance difference was negligible, and the memory usage
improvement was phenominal, as expected. Note that testing with a
different number of iterations produced results that were linearly equal.
* Fixed small documentation bug in XMLSchema.pod - its NAME was wrong.
2003-09-11 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.16.
* This is a major design and functionality update release, although the
changes are all focused on the SQL::ObjectModel/::* files.
* The proposed C library name "libSOM" has been changed to "libSQLOM". The
NAME for SQL::ObjectModel was also rewritten, and it now looks like this:
SQL::
::ObjectModel adhOg An abstract syntax tree for all types of SQL DUNCAND
* Updated documentation in SQL::ObjectModel so each function and method
description now has an example line of code or two demonstrating its use.
* Updated cct_str_enc definition in DataDictionary.pod to account for UTF-8
and UTF-16 being variable-length encodings.
* Added new file lib/SQL/ObjectModel/XMLSchema.pod which explains
ObjectModels in terms of a suggested XML representation.
* Updated DataDictionary.pod and ObjectModel.pm so that every table and its
corresponding node now have a single-column integer primary key, whose name
is 'id'. This change was to make it much easier to convert ObjectModel
data between in-memory data structures linked by references and database
records and XML nodes. The other fields/attributes were also standardized
in their naming and structure, including the use of shorter field names,
single column foreign keys, and removal of some extra fields. ObjectModel
attributes now all have the same names whether they are in a database or
XML or in-memory structures, and all attributes are used in each place. As
a result, some attributes may appear redundant when in memory or XML, such
as those which say who the parent of a node is, or its order among its
siblings. But this is intentional and accounted for.
* A single model or data dictionary can now manage the commands for
multiple applications, which helps if they have databases in common.
* SQL::ObjectModel now enforces required-attribute constraints, and will
throw an exception if you try to create a node where said attributes are
not valued. At the same time, the logic for assigning default attribute
values has been improved so that it can generate serial numbers or copy
values from parent nodes, in addition to setting static literal values.
The 'id' attribute for all nodes is both mandatory and serially generated,
so it is technically possible (as shown by the example code) to use this
module without explicitly giving any 'id' values as input.
* Added feature to ObjectModel.pm where, if you simply create a node
without indicating a parent to attach it to, the module will make a logical
intuition as to where it should go and assign it there. Specifically, it
takes the last previously created node which is capable of being the new
one's parent. This feature is mainly intended for adding new databases or
namespaces or tables or views or blocks or applications or commands, but
not parts of those. See the updated SYNOPSIS for examples of the benefits.
* SQL::ObjectModel is now implemented internally as two classes, a
"container"/"model" and a "node" (which correspond to an XML DOM "document"
and "node"). All nodes now must exist within the context of a container,
and they currently can not be moved or copied between existing containers.
However, a container with full node complement can be cloned to make a
second container. Each container has a single root node that its other
nodes can descend from; however, nodes can still be detached from this and
be in other tree fragments (akin to an XML DOM "document fragment").
Working within a container context allows the module code to be a lot more
powerful or smarter, without being larger.
* Added a debugging method to spit out all of a node-tree's data as an XML
document, which is more compact and testing-reliable than the Perl-code
spitting function (which also still exists). Also, for all the debugging
methods, the option was removed to produce/hide extra data relating to Perl
variables; these are now superfluous, and were always troublesome.
* Updated the test code, and the partial copy of said code in the SYNOPSIS,
so it works with all the module changes. The code now uses the XML data
representation for testing, and this works without errors on both Perl
5.6.0 and 5.8.1rc4 (both under Mac OS X 10.2.6). Note that the test
failures on the Solaris testbed for release 0.15x appears to be from that
platform using Perl 5.8, and not simply because it was Solaris. So release
0.16 should test correctly on all platforms now.
* Updated the BUGS documentation in ObjectModel.pm to add/replace some
design flaw descriptions. They will be eliminated in near future releases.
* Added some items to supported database list in Framework.pod.
2003-07-11 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.152.
* The previous release failed to fix the test failure on CPAN's
"sun4-solaris 2.8" testbed (the test worked fine on 3 other platforms), and
so I have thought of another thing to change that might resolve it.
Several places in SQL::ObjectModel where a hash was being iterated through
are now sorting the hash elements by key before using them, so serialized
data that would be affected by this should now look the same on platforms
where Perl uses a different hashing algorithm. I should have thought of
this before (as I had on my other Perl distributions) but didn't. If this
doesn't fix the problem on Solaris then I am open to suggestions.
SQL::ObjectModel now is version 0.032; the test script now refers to that.
2003-07-10 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.151.
* This release is largely a minor bugfix update; it is an attempt to get
the test suite to run correctly on CPAN's "sun4-solaris 2.8" testbed, where
it had failed SQL-ObjectModel.t test 3 (note that the tests all passed in
both Perl 5.6.0 on Mac OS X 10.2.6 and a CPAN Win32 testbed). In suspician
that the problem may have to do with differences in newlines between
platforms, I made two changes. First, the get_all_properties_as_str()
method in SQL::ObjectModel received a minor update so it doesn't try to
substitute the trailing comma with a semicolon. Second, the test script
was updated so that the literal string which the result of the above
function is compared to now contains "\n" instead of literal (unix)
newlines (and there were a few other escapes done). If this doesn't fix
the problem on Solaris then I am open to suggestions.
* Also updated the version number in SQL::ObjectModel to 0.031. The number
should have been 0.03 in release 0.15, but I had forgotten to change it
then. The only change to this module since release 0.15, mentioned in the
above bullet point, accounts for the move from 0.03 to 0.031. Also updated
SQL-ObjectModel.t to refer to the new version number 0.031.
2003-07-07 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.15.
* The file lib/SQL/ObjectModel.pm was fully rewritten from scratch. All of
the old code and documentation was replaced by newer code and
documentation. This module is now in alpha development status (was
pre-alpha), which means that it is now fundamentally complete. This also
means that you can start actually using it in your code as if it were
released, except for the fact that I still reserve the right to make
incompatible changes to it (but any changes will still closely resemble the
current version).
* The file t/SQL-ObjectModel.t had actual tests put into it, which are basically
the same as the tested module's SYNOPSIS. While not every single feature
is tested exhaustively, most of the code and data is. The SYNOPSIS code
has been executed and works properly.
* No other modules were changed for this release.
2003-06-27 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.14.
* The file ObjectModel.pm was partly rewritten from scratch, with some of
the old documentation being shoved to the bottom and marked "depreciated".
All of the old code was replaced by newer code.
* The two test files [SQL-ObjectModel.t, Rosetta.t] were simplified so that
each only tests that its respective module compiles; also synchronized the
internal layout of each file. Any tests for code that was replaced in
ObjectModel.pm have been removed.
* Updated DataDictionary.pod to simplify "cct_basic_data_type" so that
there is only one base type for all numbers; updated "cct_standard_func"
and "data_type" to remain compatible with the changes. Also updated
"database" and "namespace" to complete their separation into two entities.
Also moved "trigger" to be under the TABLES main heading rather than under
BLOCKS.
* Updated BRIEF MODULE LIST in Framework.pod to more accurately reflect the
design details in DataDictionary.pod, and in the new ObjectModel.pm. Also
updated EXPANDED MODULE LIST in a similar fashion. Any modules whose names
were SQL::ObjectModel::* are now SQL::ObjectModel::_::* (with the exception
of the POD only files), and those whose names were Rosetta::Engine::* are
now Rosetta::_::* (Rosetta::Engine is now Rosetta::_::Engine). The '_'
signifies an inner class which isn't meant to be instantiated directly.
2003-06-14 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.132.
* This release is mainly a test to see how CPAN indexes handle a module
which contains inner classes that we are trying to hide. The module in
question is SQL::ObjectModel. I saw a certain trick employed in DBI 1.37
which I am now trying 3 variations on (each with a different inner class),
the first one being done the same way as DBI. After seeing the results,
all the inner classes will be standardized on one method, in the next
distribution release.
2003-06-11 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.131.
* This is primarily a bugfix release for the documentation, mainly for
replacing references to "Rosetta" with references to "SQL::ObjectModel", or
for updating SEE ALSO or DEPENDENCIES. Files updated include:
Framework.pod, ObjectModel.pm, DataDictionary.pod, API_C.pod, Rosetta.pm,
ObjectModel.t, Rosetta.t. Also removed mistaken Rosetta::Driver detail
reference from Framework.pod.
* Added new class SQL::ObjectModel::Command to Framework.pod reference.
While both Command objects describe an action to do, the SQL::ObjectModel
version is static and is what you would pass to DBI->prepare(); any code
using it needs to do their own prompting for bind vars specified within.
The Rosetta Command object encapsulates the other kind and also
encapsulates the resolved bind vars; code using the latter would call both
DBI->prepare() and DBI->execute().
2003-06-11 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.13.
* A few small fixes were made to DataDictionary.pod that were discovered
after release 0.12 went out.
* This release was mainly for reorganizaing and renaming the component
files of the Rosetta distribution in preparation for their being split into
3 distributions: Rosetta, SQL::ObjectModel, Locale::KeyedText. The files
that are ending up in each distribution are having their documentation
changed to reflect their new status, but for the moment they still share a
common ReadMe and related files. The file Framework.pod has also been
updated in its BRIEF MODULE LIST to reflect the changes.
* The new file lib/SQL/ObjectModel.pm replaces these previously existing 3
files: lib/Rosetta/Schema/[DataType,Table,View].pm. The new file
t/SQL-ObjectModel.t replaces these previously existing 3 files
t/Rosetta-Schema-[DataType,Table,View].t. The 2 files
lib/Rosetta/[DataDictionary,API_C].pod have been renamed to
lib/SQL/ObjectModel/[DataDictionary,API_C].pod. Any other preexisting
files were not renamed or replaced.
* Small updates were made to the copyright in all files, to remove the
reference to a "Driver" interface. In addition, the copyright in the
files that will be split off now refer to the SQL::ObjectModel library
(libSOM) in place of referring to the Rosetta framework. Small changes
were also made in ReadMe and INSTALL.
* This is the current file manifest following the renames and merges:
- ChangeLog
- INSTALL
- lib/Rosetta.pm
- lib/Rosetta/Framework.pod
- lib/Rosetta/SimilarModules.pod
- lib/SQL/ObjectModel.pm
- lib/SQL/ObjectModel/API_C.pod
- lib/SQL/ObjectModel/DataDictionary.pod
- LICENSE
- Makefile.PL
- MANIFEST
- ReadMe
- t/Rosetta.t
- t/SQL-ObjectModel.t
- TODO
2003-06-10 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.12.
* The DataDictionary.pod documentation file saw some more large changes,
increasing in size from 85K to 96K (added 11K). Mainly this saw the
entirety of the "BLOCKS" main section being written, and the corresponding
sub section of "STRUCTURE" was also written. The previously referenced
entities named [procedure, function, package] are now consolidated into
"block". Added two new main sections "SEQUENCES" and "USERS" (and
corresponding STRUCTURE parts), but they are currently placeholders. Made
several updates to CONSTANT CODE TABLES. "NAME SPACES AND SCHEMA OBJECTS"
was renamed to "DATABASES AND NAME SPACES". The "object" table no longer
exists, with details stored there moved into: "table", "view", "sequence",
"block". Other small fixes or changes were made. The most important
parts of this document are now complete (codes, tables, views, blocks).
* Small updates to BRIEF MODULE LIST in Framework.pod.
* This is the current file manifest; several of these are scheduled to be
renamed or merged in release 0.13, as a precursor for the distribution
being split up:
- ChangeLog
- INSTALL
- lib/Rosetta.pm
- lib/Rosetta/API_C.pod
- lib/Rosetta/DataDictionary.pod
- lib/Rosetta/Framework.pod
- lib/Rosetta/Schema/DataType.pm
- lib/Rosetta/Schema/Table.pm
- lib/Rosetta/Schema/View.pm
- lib/Rosetta/SimilarModules.pod
- LICENSE
- Makefile.PL
- MANIFEST
- ReadMe
- t/Rosetta.t
- t/Rosetta-Schema-DataType.t
- t/Rosetta-Schema-Table.t
- t/Rosetta-Schema-View.t
- TODO
2003-06-03 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.11.
* The DataDictionary.pod documentation file saw some more large changes,
increasing in size from 71K to 85K (added 14K). Mainly this saw the
completion of the "VIEWS" main section, with any undone table descriptions
being fleshed out and others updated; 2 tables added and 4 removed; 2
related tables were added to the CONSTANT CODE TABLES section as well.
Smaller updates were made to "STRUCTURE". Other bug fixes or small changes
were made. At this point all significant parts of the deprecated sections
that were removed in release 0.10 have been replaced. The main sections
"BLOCKS" and "COMMANDS AND RESULTS" still need to be written.
* Updated BRIEF MODULE LIST in Framework.pod to illustrate how the core
Rosetta distribution may get split up, with new modules having names like
"Locale::KeyedText" and "SQL::ObjectModel". Also updated formatting of
some level 2 headings in the document.
2003-05-28 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.10.
* The DataDictionary.pod pure documentation file saw large changes,
increasing in size from 38K to 71K (removed 14K, added 47K). The 3
deprecated sections named ["ROSETTA NATIVE DATA DICTIONARY STRUCTURE", "A
BASIC TABLE STRUCTURE FOR STORING ROSETTA SCHEMAS", "ANOTHER WAY OF SAYING
THAT"] were removed. Large updates were made to the "STRUCTURE" and
"CONSTANT CODE TABLES" main sections. These new main sections were added:
"DATA TYPES", "NAME SPACES AND SCHEMA OBJECTS", "TABLES", "VIEWS"; all
except "VIEWS" are complete, and the last is two-thirds complete. Also
added main sections "BLOCKS" and "COMMANDS AND RESULTS" as placeholders,
but they hardly contain anything yet. Technically a small amount of the
removed sections haven't been replaced yet, but they should be next time.
Note: the rest of DataDictionary.pod should be done for release 0.11.
* Small documentation changes in Framework.pod, mainly in BRIEF MODULE
LIST. Among other things, the possibility that the "Rosetta" distribution
may be split so that the "Schema" modules are distributed independently, as
well as other splits, is documented as being considered. This is meant
partly to help avoid the public perception that Rosetta has a strong "not
invented here" problem; the framework is in fact very separable and
extensible. Also, there is no longer a base class for driver modules;
rather, all Driver modules must simply have a certain documented interface.
* Updated DEPENDENCIES in the ReadMe file (and in Framework.pod) to clarify
that, while the Rosetta core doesn't have any dependencies in other
modules, the various Rosetta extensions (like Drivers) probably do. These
same notes were also added to the DEPENDENCIES section in Framework.pod.
* Added new section to the top of the TODO file, ONE DEVELOPMENT TRACK,
which shows my short term goals (allow tables to be created or changed,
allow records to be fetched or changed); things like stored procedures will
wait until later. The first several of these goals have been assigned to
specific release numbers. The previous content of the file is still there,
beneath the new stuff, under new title of ANOTHER DEVELOPMENT TRACK.
* Added DataDictionary.pod to the SEE ALSO section of several modules, and
also mentioned the file twice in Framework.pod, as the second main
documentation, to read after Framework.pod.
* Fixed a documentation bug in the SYNOPSIS of View.pm; version->0.12.
2003-05-11 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.09.
* Updated a few documentation details in file lib/Rosetta/API_C.pod, in the
"CONTENT OF rosetta_schema_datatype.h" section.
* Updated section SYNOPSIS of Framework.pod to make a few small corrections
or improvements.
* Updated section BRIEF MODULE LIST of Framework.pod, mainly for the Schema
modules (stored procedures et al are getting fleshed out; users are demoted
since they aren't really part of the schema).
* Added new file lib/Rosetta/DataDictionary.pod, which describes a database
that is suitable for storing all of the Rosetta Schema details, including
constant code tables, user data types, user tables, user views, and user
code blocks such as stored procedures, functions, and triggers. This may
be expanded later to also describe not only users and privileges but also a
means for storing any kind of Command or Response object for such things as
logging database activity. This new file is a rewritten replacement for
the last 3 main sections of Framework.pod, which were removed: "ROSETTA
NATIVE DATA DICTIONARY STRUCTURE", "A BASIC TABLE STRUCTURE FOR STORING
ROSETTA SCHEMAS", "ANOTHER WAY OF SAYING THAT". However, since the new
file isn't finished yet, copies of the 3 old sections have been moved to
the bottom of the new file in their original form. They will be removed
when they are fully redundant.
2003-04-27 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.08.
* Added new file lib/Rosetta/API_C.pod, which contains the start of my C
API documentation for Rosetta. It contains yet-incomplete contents for
these 3 C header files: rosetta.h, rosetta_types.h,
rosetta_schema_datatype.h. Also added the new filename to the SEE ALSO of
Framework.pod. No other changes were made in this release.
2003-04-15 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.07.
* The experimental changes made in release 0.062 were rolled back, meaning
that the files lib/Rosetta.pm and t/Rosetta.t were restored to the presence
they had in 0.061. Since those were the only changes, all change comments
below are relative to the state of release 0.061.
* This release was mainly a documentation and licensing update. The
distribution now has these extra files: INSTALL, LICENSE, TODO. No files
were removed. Framework.pod had the most changes, ReadMe the second most.
* The section ABSTRACT in Framework.pod was largely rewritten to bring it
up to date with my evolved plans, and also to greatly improve the
communication of what Rosetta does and does not do. For one thing, a lot
more emphasis is placed on its useability with both embedded and
client-server databases. There were a huge number of content changes.
* The Rosetta database abstraction framework is now distributed under the
terms of the GNU General Public License (GPL) rather than "under the same
terms as Perl itself" (meaning a choice of GPL or Artistic). The new
licensing should be a lot easier to understand. This applies to both code
and design documents; also, any code implemented from my design documents
will be considered a derivative work no matter who makes it, and be bound
by the same license. Note that while the GPL precludes linking to modules
for which the source code isn't freely available, my licensing terms have
an exception for the independent database drivers themselves. That said,
it is very likely that I will change to a dual-licensing arrangement some
time in the future, after Rosetta is actually able to do something useful,
where a GPL license is free, and getting an alternative license requires a
special arrangement with myself.
* A new file named LICENSE has been added to the distribution, which
contains the text of the GPL. All other distribution files, especially
Framework.pod, have been updated such that each AUTHOR documentation
section has been replaced with a COPYRIGHT AND LICENSE section (near the
top of each file); the AUTHOR section had talked about copyright and
licensing itself, and is now redundant. Correspondingly, all code modules
have had their version numbers increased by 0.001.
* The section SCHEDULE FOR DEVELOPMENT in lib/Rosetta/Framework.pod was
removed from there and put in the new file "TODO"; aside from a reformat to
move from POD to plain text, there were no changes. Upcoming plans for
this file is that it will be rewritten to include multiple parallel
development tracks, which more realistically portrays what will happen.
* A few terms were renamed globally in Framework.pod. Any references to
"connecting" or "disconnecting" a database were changed to say "opening"
and "closing" instead. Also, the module "Connection" was renamed to
"Database". This affected mainly the SYNOPSIS and the EXPANDED MODULE LIST.
Also, the DEPENDENCIES of all files were slightly updated.
* The STRUCTURE, BRIEF MODULE LIST, and EXPANDED MODULE LIST have been
expanded, and the diagram in STRUCTURE improved: 1. The list of Driver
modules has been rewritten to explicitly show several dozen databases, and
the expanded module descriptions for all drivers and driver utilities was
rewritten. 2. A new set of Validator modules has been added to be a common
test bed for all the drivers (akin to Sun's validation suite for JVMs). 3.
The Rosetta::Driver::Native driver is no longer intended for testing the
Rosetta core, but rather is to be useful in its own right; it will now be
in the Drivers distribution rather than the core distribution. 4. A new
set of modules named Rosetta::Proxy::* were added (along with a second
diagram in STRUCTURE), so that Rosetta could work as a client-server setup
ala ODBC. Comments on my plan to convert Rosetta into a C library
eventually (with a fully working pure-Perl version coming first) were added
to STRUCTURE.
* Removed one test from Rosetta-Schema-DataType.t which was generating a
warning; there was no point since it effectively tested just the Perl
runtime engine and not the module.
* The BUGS section was removed from SimilarModules.pod and put in ReadMe.
The INSTALLATION section was removed from ReadMe and put in a new file
named INSTALL. ReadMe was further updated to rename REQUIREMENTS to
DEPENDENCIES and to add a CREDITS section (currently empty). The PREFACE
was completely rewritten (and is now much shorter).
* A few more tiny whitespace formatting bits were fixed in several files,
and several parts were re-word-wrapped. Added "use warnings" to SYNOPSIS.
2003-03-29 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.062.
* This release is mainly a test to see how CPAN indexes handle a
distribution named after a registered module where that module doesn't
actually exist. The files lib/Rosetta.pm and t/Rosetta.t were removed from
the distribution to facilitate the test. The rationale is that these files
never actually did anything except serve as placeholders for the framework
on CPAN indexes, but they may not be needed. There were no other changes.
2003-03-09 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.061.
* This is a small bugfix release that mainly is for fixing documentation.
A lot of it was formatting issues that was easy to miss before; the other
bullet points below list the non-formatting issues. These files
had formatting fixes: Framework.pod, SimilarModules.pod, ChangeLog.
* Updated these sections in "ReadMe": PREFACE, INSTALLATION, TO DO.
* Updated BRIEF MODULE LIST in Framework.pod to add SimilarModules.pod.
* Updated SimilarModules.pod so that each module list shown for other
people's frameworks includes the framework release version and date for
which I was looking at them, so it is easier to validate my information.
* Updated Rosetta.pm (now at v0.061) replacing references to
"Rosetta::Framework.pod" with "lib/Rosetta/Framework.pod".
2003-03-08 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.06.
* Created new documentation-only file lib/Rosetta/SimilarModules.pod, which
is where all of the comparisons between Rosetta and other database-related
modules and frameworks will go. There are so many modules to compare with
that this documentation needs its own file.
* Updated the SEE ALSO lines of all the modules. Now Framework.pod is the
place where all of the other Rosetta modules are listed. SimilarModules.pod
has the list of other people's modules. All other modules simply list
Framework.pod and SimilarModules.pod in their SEE ALSO. DataType is now at
v0.02 and Rosetta.pm is at v0.06 because of this change.
* Added new modules lib/Rosetta/Schema/Table.pm and
lib/Rosetta/Schema/View.pm (both are v0.01), which complement the already
completed DataType.pm. There are also two new test files, one for each new
module. Given the greater complexity of the new modules relative to
DataType, and the desire to expedite this release, the two new modules will
only be partly done in this release, and their test files won't do
anything. Table.pm and View.pm should be finished probably by release 0.08
or 0.09.
* References in Framework.pod to a planned module Rosetta::Schema::DataSet
have been removed, as that module's functionality is now part of
Rosetta::Schema::View. Also added references to Rosetta::Schema::User and
Rosetta::Schema::Privilege (or PrivilegeType).
* Removed the entire MODULE DETAILS section from Framework.pod, and divided
its contents into the new Table.pm and View.pm.
* Updated STRUCTURE section in Framework.pod to move the Locale group in
the diagram so it is beside Schema; this signifies that both of these 2
named groups are used by the 4 other groups in more or less the same way.
2003-03-04 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.05.
* Created new file lib/Rosetta/Schema/DataType.pm which implements the
class Rosetta::Schema::DataType (v0.01); this is the first module to be
coded, and it is complete as of its first version. The already written POD
for this class that was in Rosetta::Framework under the section MODULE
DETAILS has been removed from that file and put in the new file instead,
with updates.
* Added new file t/Rosetta-Schema-DataType.t, to completely test the newly
coded module.
* Updated lib/Rosetta.pm (now at v0.05) and t/Rosetta.t to add the "use
warnings" pragma at the top of each file beside "use strict"; the
previously mentioned two new files also have the added pragma, which should
save users from having to put -w on the command line for these modules.
* Updated Rosetta::Framework further, in the STRUCTURE and BRIEF MODULE
LIST sections, to add references to a new set of core modules,
Rosetta::Locale::*. These are to function as constant data resources,
mainly holding user-readable text such as database error messages and so
forth, so that this text is separate from normal module code and easy to
edit. This is a set of files partly so that each file can have a different
localization; adding a new user language is as easy as adding another file.
The set of text strings being stored should be comprehensive enough that
any Driver module can use them, and therefore not need their own Locale
files for displaying error messages. All strings are mapped to short codes
(eg: 'R001372'); these codes are what the normal module code uses to
display a particular message.
2003-02-10 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.04.
* The file Documentation.pod was renamed to Framework.pod; that file's
internal name as declared in the POD is Rosetta::Framework; the file was
also moved into lib/Rosetta/; any references to this file in other files
were updated accordingly.
* In Framework.pod, updated BRIEF MODULE LIST to replace
Rosetta::Driver::Null with Rosetta::Driver::Native. The plan is that this
will be a fully-functional RDBMS implementation, and 100% Perl code; it
will implement all database features that the Rosetta core can interface
to, even if some real databases can't. This includes transactions,
locking, foreign keys, stored procedures, multiple 'users', and more. That
said, it is intended mainly for testing the Rosetta core, and will be
developed simultaneously with the latter. While Rosetta::Driver::Native is
fully functional, it is completely RAM-based for simplicity (nothing is
stored on disk, except perhaps by means of explicit freeze/thaw or the
like), and probably won't scale to more than a few thousand records
(namely, it will hold just whatever can all fit in RAM at once). It also
won't be designed with multi-threaded environments in mind, due to its
intent for testing (usually done by one person at a time); if you plan to
use it for more, you will need to serialize access yourself. Also, the
EXPANDED MODULE LIST :: DRIVER MODULES now describes the new module.
* In Framework.pod, moved section SCHEDULE FOR DEVELOPMENT down below BRIEF
MODULE LIST (leaving STRUCTURE right after DESCRIPTION). Some list items
in the moved section were also moved to be handled earlier.
2003-02-09 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.03.
* The most significant change in this release is that the file "Rosetta.pm"
has been split into itself and the new file "Documentation.pm". The latter
file now has all of the main Rosetta framework POD documentation. The
former now is very small and contains just module-specific documentation.
The new folders "lib" and "t" were also added to the distribution. As of
this release, Rosetta still consists entirely of documentation.
* Note that, as soon as module code starts being written, Rosetta will be
released as multiple distributions. This current distribution will contain
the framework core, mainly all of the Schema and Engine modules, and the
generic base class for Drivers, and continue under its existing name. A
new distribution named "Rosetta-Drivers" will contain most of the Driver
modules, and this is the only distribution that would have DBI and DBD::*
as prerequisites. Another distribution named "Rosetta-Emulators" will
contain the Emulator modules. Sample and utility applications will be in
yet another distribution, such as "Rosetta-Applications".
* Updated several parts of ReadMe file, particularly the Preface.
* Makefile.PL now hard-codes the distribution VERSION; this file now has
the authoritative VERSION for the distribution or framework itself.
* These were the main Documentation.pod sections with updates other than
from the file split (which removed PREFACE from both files):
- DEPENDENCIES - changed to "none" (from DBI) since core has no dependencies
- SCHEDULE FOR DEVELOPMENT - moved to later date stored Views and Pub Syn
- SYNTAX - removed section; content merged into STRUCTURE
- STRUCTURE - removed "Parser" from structure, made relationship graph complete
- BRIEF MODULE LIST - grouped modules by their distributions, added Driver::Null
- ROSETTA NATIVE DATA DICTIONARY STRUCTURE - separated Table, Select definitions
* Note that other POD sections are out of date and will need updating.
2003-01-27 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.02.
* This is the second release. The release and root-level module are now
called "Rosetta", which it was renamed to from "DBIx::Portable". It still
consists entirely of documentation in POD format, and all of that is in the
file Rosetta.pm.
* The documentation was significantly updated, with up to half of it being
rewritten. This release has a completed SYNOPSIS (the previous release
left out some significant parts due to time constraints), and several new
sections on framework design. In particular, the structure of the
internally used "schema" was fleshed out.
* These were the main sections with updates:
- ABSTRACT - new section
- SYNOPSIS - expanded to a complete Perl script with config file
- DESCRIPTION - several more paragraphs added
- SCHEDULE FOR DEVELOPMENT - rewritten from and replaces PROGRESS
- STRUCTURE - new section (not related to same-named old version section)
- BRIEF MODULE LIST - new section
- EXPANDED MODULE LIST - canibalized from the previous versions STRUCTURE
- ROSETTA NATIVE DATA DICTIONARY STRUCTURE - new section
- A BASIC TABLE STRUCTURE FOR STORING ROSETTA SCHEMAS - new section
- MODULE DETAILS
* These other sections had little or no updates:
- NAME
- PREFACE
- DEPENDENCIES
- SYNTAX
- MODULE DETAILS
- AUTHOR
- SEE ALSO
* Generally speaking, this release should be a lot better than the previous
one, although there are still large gaps or sections needing improving.
Subsequent releases will probably start including a code implementation,
with further documentation updates happening at the same time.
2003-01-21 Darren Duncan <perl@DarrenDuncan.net>
The next version of the Module List will list the following module:
modid: Rosetta
DSLIP: cdpOp
description: Framework for RDBMS-generic apps and schemas
userid: DUNCAND (Darren Duncan)
chapterid: 7 (Database_Interfaces)
enteredby: ANDK (Andreas J. Knig)
enteredon: Tue Jan 21 08:20:47 2003 GMT
The resulting entry will be:
Rosetta cdpOp Framework for RDBMS-generic apps and schemas DUNCAND
2003-01-05 thru 2003-01-19 Darren Duncan <perl@DarrenDuncan.net>
* On January 5th, a module registration request was sent to
modules@perl.org for "DBIx::Portable", which was to be the namespace root
for this distribution in release 0.01. But it was not registered. During
the following few days, both Tim Bunce and Brian D Foy replied (but no one
else), and alternate names were suggested instead, which I discussed
further with them. The general consensus was, being that I was making a
framework, my modules should have a unique root level namespace of their
own, which could be "brandable"; they should not be under the DBIx
namespace, or have the characters "DBI" in their root name. I came up with
some new ideas, and in doing so had rethought on part of the focus or
uniqueness of my framework. It was thought that using "Portable" or
"Abstract" were too generic sounding. My first new favorite, "Cipher", was
thought too easily confused with cryptography even though actually has a
wider meaning that was applicable. My other favourite suggestion of
"Rosetta" seemed to meet with Tim's approval.
* On January 9th, a module registration request was sent to
modules@perl.org for "Rosetta".
* On January 19th, a follow up to that request was sent which had a much
better description of what the framework would do, taken from its brand
new "ABSTRACT" POD, part of 0.02 in development.
2003-01-05 Darren Duncan <perl@DarrenDuncan.net>
* Release 0.01.
* This is the initial release. It contains only documentation, and all of
that is in the file Portable.pm. This documentation isn't complete, but it
should be enough for a first version, and I am keeping strictly to a Jan 5
release date regardless of completeness.
2002-12-14 Darren Duncan <perl@DarrenDuncan.net>
* Began creating this new Perl distribution package for CPAN, using an
initial title of DBIx-Portable-0.01, including ReadMe and ChangeLog files.
2002-11-12 Darren Duncan <perl@DarrenDuncan.net>
* Began development on these modules as their own entity that is separate
from the application, which will be distributed open-source on CPAN, using
initial titles of DBIx::Portable and DBIx::Portable::*. The modules are to
comprise an RDBMS-generic DB framework for any application to use. This
development effort was discussed with the victoria.pm Perl Mongers group.
* Modules based on a template created by h2xs 1.18.
2002-07-28
* Posted the first significant update to the second prototype, which added
an index or cache for data that was expensive to calculate for each page
request, and involved rewriting about a fourth of the perl code.
2002-06-07
* Posted to my website the second public prototype demo of the new
self-proprietary database driven application, whose database schema, user
interface, feature set, and Perl application code was almost completely
rewritten. The new version explicitly had separate modules for database
communication and the web interface logic, with MySQL-specific code and
database generic or data dictionary code in separate files, and separate
files for parts of the web interface. The program used the same generic
CPAN modules as in the first prototype, DBI/MySQL and CGI::Portable.
2001-11-24
* Posted the last update to the first prototype.
2001-07-12
* Posted to my website the first public prototype demo of a new
self-proprietary database driven application, which is like a cross between
a multimedia metadata catalogue and a repository for historical or
genealogical data. This application contained the first prototypes of code
that ended up in these modules. All of this application's code, for
database communication and web interface logic, was situated in a single
module, with the rest of the program being more generic CPAN modules like
DBI (and DBD for MySQL) and CGI::Portable.
2000-05-17
* Requested MySQL database privileges on my web host so I have something to
start developing, testing and deploying database driven applications on.