Rose::DBx::Bouquet - Use a database schema to generate Rose-based source code
Rose::DBx::Bouquet
Step 1: Unpack the distros: shell> tar xvzf Rose-DBx-Bouquet-1.00.tgz (from CPAN) shell> tar xvzf Local-Wine-1.06.tgz (see FAQ) Step 2: Check for (and install) the pre-requisites: shell> cd Rose-DBx-Bouquet-1.00 shell> perl Build.PL shell> cd ../Local-Wine-1.06 shell> perl Build.PL Note: You /must/ now be in Local-Wine-1.06/. Step 3: Create and optionally populate the database: Edit lib/Local/Wine/.htwine.conf and then shell> scripts/create.tables.pl shell> scripts/populate.tables.pl Step 4: Edit: o lib/Rose/DBx/Bouquet/.htrose.bouquet.conf o lib/Local/Wine/.htwine.conf Step 5: Run the first code generator (see scripts/rosy for an overview): shell> scripts/run.rose.app.gen.pl > scripts/run.rose.pl Step 6: This is the log from run.rose.app.gen.pl: exclude: ^(?:pg_|sql_) module: Local::Wine output_dir: ./lib remove: 0 tmpl_path: /home/ron/perl.modules/Rose-DBx-Bouquet-1.00/templates verbose: 1 Working dir: lib/Local/Wine/Rose Rose::DB module: Local::Wine::Base::DB Processing tables: grape vineyard wine wine_maker Processing modules: Grape Vineyard Wine WineMaker Processing template generator.pl.tmpl Success Step 7: Run the second code generator: shell> perl -Ilib scripts/run.rose.pl Step 8: This is the log from run.rose.pl: Processing Rose::DB-based modules: Generated lib/Local/Wine/Rose/Grape.pm Generated lib/Local/Wine/Rose/Vineyard.pm Generated lib/Local/Wine/Rose/Wine.pm Generated lib/Local/Wine/Rose/WineMaker.pm Processing */Manager.pm modules: Generated lib/Local/Wine/Rose/Grape/Manager.pm Generated lib/Local/Wine/Rose/Vineyard/Manager.pm Generated lib/Local/Wine/Rose/Wine/Manager.pm Generated lib/Local/Wine/Rose/WineMaker/Manager.pm Processing */Form.pm modules: Module: Grape. Columns: id, name Generated lib/Local/Wine/Rose/Grape/Form.pm Module: Vineyard. Columns: id, name Generated lib/Local/Wine/Rose/Vineyard/Form.pm Module: Wine. Columns: grape_id, id, rating, review_date, vineyard_id, vintage, wine_maker_id Generated lib/Local/Wine/Rose/Wine/Form.pm Module: WineMaker. Columns: id, name Generated lib/Local/Wine/Rose/WineMaker/Form.pm Success You can see this generated 12 files. These files are used by CGI::Application::Bouquet::Rose (on CPAN), and by test.rose.pl. Step 9: Test the generated code: shell> scripts/test.rose.pl Step 10: This is the log (12 lines) from test.rose.pl: Total grape record count: 63. Page: 1 of 'name like S%'. 1: Sangiovese,Shiraz. 2: Sauvignon,Semillon. 3: Sav Blanc. 4: Sav Blanc,Semillon. Page: 2 of 'name like S%'. 1: Sav Blanc,Verdelho. 2: Semillon. 3: Shiraz. 4: Sparkling Shiraz. Page: 3 of 'name like S%'. Step 11: Switch to the instructions for CGI::Application::Bouquet::Rose.
Rose::DBx::Bouquet is a pure Perl module.
It uses a database schema to generate Rose-based source code.
This documentation uses Local::Wine as the basis for all discussions. See the FAQ for the availability of the Local::Wine distro.
The generated code can be used as-is, or it can be used by CGI::Application::Bouquet::Rose.
CGI::Application::Bouquet::Rose
This module is actually a very simple version of Rose::DBx::Garden, and was inspired by the latter.
Rose::DBx::Garden
The main difference, apart from its lack of sophistication of course, is that Rose::DBx::Bouquet uses HTML::Template-style templates to control the format of all generated code.
HTML::Template
Rose::DBx::Bouquet contains just enough code to be usable by CGI::Application::Bouquet::Rose.
If you wish to use Rose::DBx::Garden instead of Rose::DBx::Bouquet, there are a couple of places in the templates which have to be changed.
This module is available as a Unix-style distro (*.tgz).
See http://savage.net.au/Perl-modules.html for details.
See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing.
new(...) returns an object of type Rose::DBx::Bouquet.
This is the class's contructor.
Usage: Rose::DBx::Bouquet -> new().
Rose::DBx::Bouquet -> new()
This method takes a hashref of options.
Call new() as new({option_1 => value_1, option_2 => value_2, ...}).
new()
new({option_1 => value_1, option_2 => value_2, ...})
Available options:
This takes a regexp (without the //) of table names to exclude.
Code is generated for each table which is not excluded.
If not specified, the value defaults to the value in lib/Rose/DBx/Bouquet/.htrose.bouquet.conf.
The default value is ^(?:information_schema|pg_|sql_), which suits users of Postgres.
Postgres
This takes the name of a module to be used in the prefix of the namespace of the generated modules.
Generate a set of modules under this name. So, Local::Wine would result in:
Local::Wine
These examples assume -output_dir is defaulting to ./lib.
The default value for 'module' is Local::Wine, because this document uses Local::Wine for all examples, and because you can download the Local::Wine distro from my website, as explained in the FAQ, for testing.
This takes the path where the output modules are to be written.
See the discussion of the 'module' option above for more information.
The default value is ./lib.
This takes either a 0 or a 1.
Removes files generated by an earlier run of this program.
For instance, given the output listed under the 'module' option above, it removes the directory ./lib/Local/Wine/Rose/.
The default value is 0, meaning do not remove files.
This is the path to Rose::DBx::Bouquet's template directory.
Rose::DBx::Bouquet's
These templates are input to the code generation process.
The default value is ../Rose-DBx-Bouquet-1.00/templates.
Note: The point of the '../' is because I assume you have done 'cd Local-Wine-1.06' or the equivalent for whatever module you are working with.
Write more or less progress messages to STDERR, during code generation.
The default value is 0.
Download Local::Wine from http://savage.net.au/Perl-modules/Local-Wine-1.06.tgz
The schema is at: http://savage.net.au/Perl-modules/wine.png
Rose::DBx::Bouquet ships with rose.app.gen.pl in the bin/ directory, whereas Local::Wine ships with various programs in the scripts/ directory.
rose.app.gen.pl
Files in the /bin directory get installed via 'make install'. Files in the scripts/ directory are not intended to be installed; they are only used during the code-generation process.
Note also that 'make install' installs lib/Rose/DBx/Bouquet/.htrose.bouquet.conf, and - depending on your OS - you may need to change its permissions in order to edit it.
Short answer:
You can implement this module any way you want. It just has to provide the same methods.
Note specifically that even if you re-write Local::Wine::Config, rather than just copying all the code into your new module, I believe you should still provide to the end user a config file of options equivalent to those in .htwine.conf.
Local::Wine::Config
This module will use the default type and domain, where 'type' and 'domain' are Rose concepts.
Long answer:
See the docs for Local::Wine.
To avoid the problem of people assuming it can be downloaded and used just like any other module.
I did not try, but I assume it would be easy to do.
All columns are processed.
Future versions of either or both of Rose::DBx::Bouquet and CGI::Application::Bouquet::Rose will support a 'little language' (http://en.wikipedia.org/wiki/Little_language) which will allow you to specify the columns to be displayed from the current table.
When CGI::Application::Bouquet::Rose displays a HTML form containing a foreign key input field, you must enter a value (optionally with SQL wild cards) for the foreign key, if you wish to use that field as a search key.
Future versions of either or both of Rose::DBx::Bouquet and CGI::Application::Bouquet::Rose will support a 'little language' which will allow you to specify the columns to be displayed from the foreign table via the value of the foreign key.
You'll see a list of option names and default values near the top of this file, in the hash %_attr_data.
Some default values are undef, and some are scalars.
My policy is this:
Then the real default comes from a config file, and is obtained via the *::Config module.
Then that scalar is the default, and cannot be over-ridden by a value from a conf file.
Because I believe it makes sense for the end user (you, dear reader), to have the power to change configuration values without patching the source code. Hence the conf file.
However, for some values, I don't think it makes sense to do that. So, for those options, the default value is a scalar in the source code of this module.
No. Options whose defaults are already in the config file will never be deleted from that file.
However, options not currently in the config file may be made available via the config file, depending on feedback.
Also, the config file is an easy way of preparing for more user-editable options.
If new() was called as new({verbose => 1}), write the message to STDERR.
new({verbose => 1})
If new() was called as new({verbose => 0}) (the default), do nothing.
new({verbose => 0})
Do everything.
See bin/rose.app.gen.pl for an example of how to call run().
bin/rose.app.gen.pl
run()
Rose::DBx::Garden.
Rose::DBx::Bouquet was written by Ron Savage <ron@savage.net.au> in 2008.
Home page: http://savage.net.au/index.html
Australian copyright (c) 2008, Ron Savage.
All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Artistic License, a copy of which is available at: http://www.opensource.org/licenses/index.html
To install Rose::DBx::Bouquet, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Rose::DBx::Bouquet
CPAN shell
perl -MCPAN -e shell install Rose::DBx::Bouquet
For more information on module installation, please visit the detailed CPAN module installation guide.