| Path: | vendor/plugins/liftoff/README |
| Last Update: | Sun Nov 25 06:41:29 -0800 2007 |
Liftoff is a simple Rails plugin that gets your application off the ground by generating an initial set of model files from a single text file in which you specify only the names of the models and the types of the associations that pertain to them using an extremely simple DSL called "CAL". CAL stands for "Compact Association Language" and looks like this (of course, comments are optional).
#############################################################################
# CAL File for web store. #
#############################################################################
# A customer places one or more orders.
# An order may request more than one product, which may be requested by
# multiple orders.
# A line item references a single product.
customer < order <> product <= line_item # A line_item must specify
# a quantity for the product.
# For every order, exactly one invoice shall be generated.
# An invoice may contain multiple line items.
order => invoice < line_item
# A category describes many products and a product may be described by
# multiple categories.
category <> product
#############################################################################
Liftoff accepts as input a "CAL file" containing a sequence of declarations or "CAL chains" as illustrated above and generates a model file for each distinct table declared in the file. In addition, for each occurence of a CAL association symbol, Liftoff generates corresponding linkage declarations for the associated models pair. The interpretation of the association symbols is given below.
A > B A belongs_to B, B has_many A
A < B A has_many B, B belongs_to A
A <= B A belongs_to B, B has_one A
A => B A has_one B, B belongs to A
A <> B A has_and_belongs_to_many B,
B has_and_belongs_to_many A
It is important to note that every occurrence of an association symbol denotes a new relationship. Therefore, A<>B is not equivalent to A > B < A, and two occurrences of A > B will result in duplicate linkage declarations in your model files. The current implementation requires you to distinguish duplicate linkage declarations manually. One way of doing this is by adding a :foreign_key declaration. Note that Liftoff does not currently generate join tables.
1. Create a new rails application, and install the Liftoff plugin.
2. cd to the root of your application and type:
3. Observe that the model files for the sample database have been created in app/models.
4. Ensure that a development database has been configured.
5. To create the first migration file for each model, Type the following (See "Bash time saver" below first) once for each model file.
script/generate <model-name>
IMPORTANT: Do not allow the script to overwrite the models!
BASH time saver: Type the following incantation at the BASH prompt:
$ for f in `ls -1 app/models`; do script/generate model ${f%.*}; done
IMPORTANT: Keep typing 'n' until the generator stops prompting you.
6. To create an empty table in your database for each model, type:
rake db:migrate
7. Ensure that the database tables/schema.rb and migration files have been created.
8. Start adding column information to the migration files.
9. You are now officially "off the ground!"
The default location for the CAL file is the top-level directory for the Liftoff plugin. The default file name is "assoc.cal." Simply modify this file to meet your specifications, and repeat the above procedure.
To run the unit tests, type from the root directory of your rails application:
rake test:plugins
You can change the default path and file name of the CAL file by running liftoff.rb directly from the command line (not with rake) using the the command line option -c <path-to-CAL-file>.
You can change the default directory to which the model files are written by running liftoff.rb directly from the command line using the command line option -m <model-path>.
Liftoff/CAL is targeted at the initial stages of a Rails project in which the model is both open-ended and complicated enough to justify a back-to- front or "meet in the middle" design methodology. As such, it does not interfere with standard Rails workflows while adding functionality only where it is needed to fill the gap between the analysis and/or conceptual stage(s) and the implementation stage of the design of the database tier.
Generates Rails linkage declarations from a compact but intuitive and friendly notation called "CAL" that represents the direction, participants, and endpoint cardinalities of each relationship for arbitrarily large and complex schemas. CAL employs a semantically perspicuous symbolism in the sense that names unambiguously refer to model/table equivalences and association operators resemble their meanings. Therefore, a CAL file is a "logical picture" of the navigational structure of the Rails-managed subset of your database.
Supports multiple linkage declarations within a model class source file.
Generates any number of Rails model classes from a single text file.
Compact Association Language (CAL) uses chainable comparison operators to express transitive relationships in a natural and intuitive way.
Focuses developer attention on the high-level, navigational structure of the database during the early stages of the design process, prior to the creation of any physical artifacts other than the CAL file.
Increases agility by reducing or eliminating the need for distracting, idiosyncratic, and expensive GUI-driven database design software.
Facilitates human reasoning about the navigational properties of the database in an agile manner: instead of fighting with poorly designed diagramming algorithms, developers can simply rearrange CAL chains in a text editor.
CAL‘s nearly trivial, linear grammar can easily be adapted to multiple automation contexts that employ freely available command-line tools, e.g., SQL generators and graph-analysis software.
Liftoff/CAL has no significant learning curve.
"Rails standard" MIT License.
Generate models for join tables.
Replace ad-hoc table generation code with generators.
Generate "through" directives for applicable associations, but only if they are declared on the same line (i.e., as part of the same CAL chain).
Generate columns for implied foreign keys.
Disambiguate "duplicate" associations according to some simple convention, e.g., appending a number to the fk_id field.
Support models in subdirectories of app/models. Request for Feedback
Please do not hesitate to provide feedback. The evolution of Liftoff depends on you!
1. Create a new rails application and cd to the root directory of the new application.
2. Type:
svn co svn://rubyforge.org/var/svn/liftoff/vendor/
Same as above except for the URL:
svn co svn+ssh://username@rubyforge.org/var/svn/liftoff/vendor/
To install a gzipped or zipped package, uncompress it directly to your vendor/plugins subdirectory. Installing the RDoc
To install the RDoc for Liftoff, cd to the root of your rails application and type:
rake doc:plugins
To regenerate the RDoc, type:
rake doc:clobber_plugins
followed by the previous command. (Perhaps you should manually delete the Liftoff documentation if you have other plugins installed.)
There no bugs as far as I know, Liftoff works as advertised in the README, and I hope you find it useful. At the same time, this is a preliminary, alpha, release and should be regarded as such. There are several reasons for this:
It is absolutely the first public release in the weakest sense of "public," i.e., everybody except the author.
CAL may strike you as strange or silly, and I have no idea how it will be received, or how "original" it is. Simultaneously, CAL is the essence of Liftoff and if CAL dies, so does this project. See "Advantages of Liftoff/CAL."
The design is fairly ad-hoc.
I‘m not sure what the requirements should be regarding join tables, so I‘ve simply left them out of this release.
I am neither a Ruby nor a Rails expert and I need your help! Please do not hesitate to provide any combination of feedback, mentoring, and/or code regarding both technical and administrative (i.e. how to manage a project like this) issues.