use Perl

My ORLite ORM system (which seems to be turning into one of those projects that I'm in love with but nobody else quite seems to get) has made my life so much better.

But since I started using it as the data storage layer for Padre I've confirmed my suspicion that I made a massive mistake in the design.

My original goal was to produce an ORM that would compliment and imitate the best features of SQLite. It would be simple, fast, very very small, self-contained, and easy to use.

It's certainly met most of those goals.

Creating an light, simple and fast ORM class tree in one line of code with very little memory load works perfectly. It can handle SQLite databases living at arbitrary remote URLs, and it supports schema versioning so that you can automate the schema migration and upgrade processes.

The problem with all this wonderful automation is that because there's no actual code created anywhere nobody (and some days that also includes me) has any idea how to use the ORM classes that ORLite creates.

Most of the generated classes don't get their own .pm files, the set of methods that get generated varies subtly based on read-only vs read-write access to the SQLite database, and writing documentation in the ORLite module itself can confuse things even more, because you end up with a mix of "How to use ORLite docs" and "How to use the classes it creates" documentation.

As far as I can tell, none of the 25 or so committers on the Padre project have ever actually written code to use the Padre::DB layer beyond cut and pasting from stuff I had written already.

If code is generated in a forest and it doesn't come documented, does anybody care?

  should finally fix this last big problem with using ORLite in the real world.

The distribution contains a command line tool orlite2pod which you run from the root directory of a distribution, passing it the class name for the ORLite database class.

The tool will load the database class, connect to the underlying SQLite database, and then use a mix of database-level introspection and Perl-level introspection to generate a complete tree of .pod files containing the documentation for the data model (as it exists at the time you run the orlite2pod tool).

Running it looks something like this

D:\padre\Padre>orlite2pod Padre::DB
Creating ORLite::Pod instance...
Starting POD generation run...
Analyzing dbi:SQLite:D:\Documents and Settings\adam.kennedy\Local Settings\Application Data\.padre\config.db...
Generating lib\Padre\DB.pod...
Generating lib\Padre\DB\Modules.pod...
Generating lib\Padre\DB\History.pod...
Generating lib\Padre\DB\Hostconf.pod...
Generating lib\Padre\DB\Snippets.pod...
Generating lib\Padre\DB\Plugin.pod...

D:\padre\Padre>


That example snippit is about the only end-user documentation there is right now, the uploaded 0.01 release is mainly there to see if the POD template fragments in the code are going to be treated as module documentation by search.cpan.

Once orlite2pod can generate documentation for all the basic methods, I plan to also start adding support (somehow) for options such as merging the generated POD into the matching .pm file (for the root class at least) so that you can effectively mix POD documentation of additional methods you add to the stuff that is generated for you.

And the ability to generate all the documentation like this brings forwards an interesting idea I had previous had for taking a remote published SQLite database, and auto-generating an entire distribution from scratch to provide a documented ORM that pulls from it.