og 0.12.0 → 0.13.0

data/CHANGELOG

@@ -0,0 +1,27 @@
+17-03-2005  George Moschovitis  <gm@navel.gr>
+
+	* Rakefile: updated.
+
+	* test/*: changes to make the tests pass again.
+
+15-03-2005  George Moschovitis  <gm@navel.gr>
+
+	* README: updated.
+
+12-03-2005  George Moschovitis  <gm@navel.gr>
+
+	* lib/og/validation.rb: introduced,
+	(#validate_unique): implemented,
+	(#validate_related): implemented.
+
+10-03-2005  George Moschovitis  <gm@navel.gr>
+
+	* lib/og.rb: removed Name.
+
+	* install.rb: updated for Og.
+
+	* INSTALL: updated for Og.
+
+	* Rakefile: updated, removed nitro dependencies.
+
+	* CHANGELOG: splitted from the Nitro ChangeLog.

data/INSTALL

@@ -0,0 +1,56 @@
+= Instalation with RubyGems
+
+1. Download and install RubyGems: 
+
+	http://rubygems.rubyforge.org
+
+2. Install the distribution:
+
+	gem install og
+
+	When asked about the dependencies to include, only accept
+	the dependencies for the RDBMS backends you are planning
+	to use.
+
+3. Set environment variable (required to load RubyGems):
+
+	export RUBYOPT=-rubygems
+
+	You can add this in you .bashrc in Unix.
+
+	Alternatively you can run your applications with the -rubygem 
+	option:
+
+  ruby -rubygem xxx.rb
+
+= Installation without RubyGems using script.
+
+Installation without RubyGems is *strongly* discouraged.
+However, as Og is all about freedom and possibilities,
+a standard installation script is provided.
+
+1. Switch to an administrator account 
+
+	For example in Unix:
+
+	$ su -
+
+2. Run the installation script.
+
+	$ ruby install.rb
+
+This installation script also installs some vendor libraries
+that you possibly have allready installed. Use with caution.
+
+= Manual installation.
+
+Uncompress your distribution (Unix example):
+
+$ cd my_dir
+$ tar xvfz og-x.x.x.tar.gz
+
+Put the libray dir in the Ruby path (Unix example):
+
+$ export RUBYOPT='-I path/to/og/lib'
+
+

data/{README.og → README}

@@ -1,6 +1,6 @@
-= Og 0.12.0
+= Og 0.13.0
 
-(ObjectGraph) is a powerfull object-relational mapping library. Og provides 
+Og (ObjectGraph) is a powerfull object-relational mapping library. Og provides 
 transparent serialization of object graphs to a RDBMS 
 backend. Unlike other similar libraries Og maps standard Ruby
 objects to SQL tables and not vice versa. Og provides a meta language
@@ -18,7 +18,7 @@ PostgreSQL, MySQL and SQLite are included.
 
 Og is part of the Nitro project, released as a stand-alone library
 due to popular demand. You can find the ChangeLog in the Nitro 
-distribution (http://www.rubyforge.com/projects/nitro).
+distribution (http://nitro.rubyforge.org).
 
 
 == Features

data/Rakefile

@@ -6,21 +6,11 @@ require 'rake/rdoctask'
 require 'rake/testtask'
 require 'rake/gempackagetask'
 
-og = true
-
 task :default => :package
 
 # Run the tests.
 
 Rake::TestTask.new do |t|
-	t.libs << 'test'
-	t.test_files = FileList['test/**/tc*.rb'].exclude('**/tc*og*.rb').exclude('test/og/**/*')
-	t.verbose = true
-end
-
-# Run all tests. (including expensive/depended tests)
-
-Rake::TestTask.new(:test_all) do |t|
 	t.libs << 'test'
 	t.test_files = FileList['test/**/tc*.rb']
 	t.verbose = true
@@ -31,14 +21,12 @@ end
 Rake::RDocTask.new do |rd|
 	rd.main = 'README'
 	rd.rdoc_dir = 'doc/rdoc'
-	rd.rdoc_files.include('README', 'INSTALL', 'doc/og_config.txt', 'doc/og_tutorial.txt', 'lib/**/*.rb')
+	rd.rdoc_files.include('README', 'INSTALL', 'doc/config.txt', 'doc/tutorial.txt', 'lib/**/*.rb')
 	rd.options << '--all --inline-source'
 end
 
 # Build gem.
 
-if og 
-
 spec = Gem::Specification.new do |s|
 	s.name = 'og'
 	if File.read('lib/og.rb') =~ /Version\s+=\s+'(\d+\.\d+\.\d+)'/
@@ -49,86 +37,32 @@ spec = Gem::Specification.new do |s|
 	s.summary = 'Og (ObjectGraph)'
 	s.description = 'An efficient and transparent Object-Relational mapping library'
 	
+	s.add_dependency 'glue', '= 0.13.0'
 	# s.add_dependency 'postgres-pr', '>= 0.3.0'
 	# s.add_dependency 'postgres', '>= 0.7.1'
-	s.add_dependency 'extensions', '>= 0.5'
 	# s.add_dependency 'sqlite3-ruby', '>= 1.0.0'
 	#s.add_dependency 'mysql', '>= 2.5.1'
-	s.add_dependency 'flexmock', '>= 0.0.3'
 
-	s.required_ruby_version = '>= 1.8.0'
+	s.required_ruby_version = '>= 1.8.1'
 
 	s.files = FileList[
-		'README.og', 'RELEASES.og', 'doc/LICENSE', 'doc/AUTHORS', 'Rakefile', 'ChangeLog*',
-		'install.rb',
-		'examples/og/*', 'lib/glue.rb', 'lib/glue/**/*', 'lib/og/**/*', 'lib/og.rb',
-		'test/*og*.rb', 'test/og/*', 'vendor/extensions/**/*'
+		'[A-Z]*', 'install.rb', '{bin,benchmark,examples,doc,lib,test,vendor}/**/*' 
 	].exclude('.svn/**/*').exclude('**/*.log').to_a
 
 	s.require_path = 'lib'
 	s.autorequire = 'og'
 	
 	s.has_rdoc = true
-	s.extra_rdoc_files = FileList['README.og', 'RELEASES.og', 'doc/LICENSE', 'doc/AUTHORS'].to_a
-	s.rdoc_options << '--main' << 'README.og' << '--title' << 'Og Documentation'
+	s.extra_rdoc_files = FileList['README', 'doc/RELEASES', 'doc/LICENSE', 'doc/AUTHORS'].to_a
+	s.rdoc_options << '--main' << 'README' << '--title' << 'Og Documentation'
 	s.rdoc_options << '--all' << '--inline-source'
 
 	s.author = 'George Moschovitis'
 	s.email = 'gm@navel.gr'
-	s.homepage = 'http://www.rubyforge.com/projects/nitro'
+	s.homepage = 'http://nitro.rubyforge.org'
 	s.rubyforge_project = 'nitro'
 end
 
-else
-	
-spec = Gem::Specification.new do |s|
-	s.name = 'nitro'
-	if File.read('lib/nitro.rb') =~ /Version\s+=\s+'(\d+\.\d+\.\d+)'/
-		s.version = $1 
-	else
-		raise 'No version found'
-	end
-	s.summary = 'Nitro Web Engine'
-	s.description = 
-		'An efficient, multiparadigm and flexible platform for rapid ' +
-		'web application development. Implements a full development stack.'
-
-	# s.add_dependency 'postgres-pr', '>= 0.3.0'
-	# s.add_dependency 'postgres', '>= 0.7.1'
-	# s.add_dependency 'ParseTree', '>= 1.3.3'
-	s.add_dependency 'extensions', '>= 0.5'
-	# s.add_dependency 'sqlite3-ruby', '>= 1.0.0'
-	# s.add_dependency 'mysql', '>= 2.5.1'
-	s.add_dependency 'flexmock', '>= 0.0.3'
-
-	s.required_ruby_version = '>= 1.8.0'
-
-	s.files = FileList[
-		'[A-Z]*', 'install.rb', '{bin,benchmark,examples,doc,lib,test,vendor}/**/*' 
-	].exclude('.svn/**/*').exclude('*.og').exclude('**/*.log').to_a
-
-	s.require_path = 'lib'
-	s.autorequire = 'nitro'
-	
-	s.has_rdoc = true
-	s.extra_rdoc_files = FileList['[A-Z]*'].exclude('*.og').to_a
-	s.rdoc_options << '--main' << 'README' << '--title' << 'Nitro Documentation'
-	s.rdoc_options << '--all' << '--inline-source'
-
-	s.test_files = []
-	
-	s.bindir = 'bin'
-	s.executables = ['nitro']
-	s.default_executable = 'nitro'
-
-	s.author = 'George Moschovitis'
-	s.email = 'gm@navel.gr'
-	s.homepage = 'http://www.rubyforge.com/projects/nitro'
-	s.rubyforge_project = 'nitro'
-end
-
-end
-
 Rake::GemPackageTask.new(spec) do |pkg|
   pkg.package_dir = 'dist'
   pkg.need_zip = true

data/benchmark/bench.rb

@@ -0,0 +1,75 @@
+# * George Moschovitis  <gm@navel.gr>
+# (c) 2004-2005 Navel, all rights reserved.
+# $Id: bench.rb 288 2005-03-10 12:47:03Z gmosx $
+
+require 'og'; include Og
+
+
+config = {
+	:adapter => 'sqlite',
+	:database => 'test',
+	:connection_count => 5 
+}
+
+class Article
+	prop_accessor :title, String
+	prop_accessor :body, String
+	prop_accessor :hits, Fixnum
+	prop_accessor :rate, Fixnum
+
+	def initialize(title = nil, body = nil)
+		@title = title
+		@body = body
+		@hits = rand(5)
+		@rate = rand(100)
+	end
+end
+
+Database.drop_db!(config)
+db = Database.new(config)
+
+# Benchmark the insert speed. Useful for finding
+# the improvement when using prepared statements.
+
+articles = []
+
+500.times do |i|
+	articles << Article.new("Title#{i}", "Body#{i}")
+end
+
+sum = 0
+min = 999999
+max = -min
+
+GC.disable
+
+10.times do |i|
+
+	db.exec "DELETE FROM #{Article::DBTABLE}"
+
+	for article in articles
+		article.oid = nil
+	end
+
+	Article.create("Dummy", "Dummy")
+	
+	t1 = Time.now
+	articles.each do |a|
+		a.save!
+	end
+	t2 = Time.now
+
+	d = t2 - t1
+	sum += d
+	min = d if d < min
+	max = d if d > max
+	
+	puts "Insert test #{i}: #{d} seconds"
+
+end
+
+puts %{
+Min: #{min}
+Max: #{max}
+Average: #{sum/10}
+}

data/benchmark/sqlite-no-prepare.1.txt

@@ -0,0 +1,13 @@
+Insert test 0: 3.53403 seconds
+Insert test 1: 4.222878 seconds
+Insert test 2: 3.84379 seconds
+Insert test 3: 3.877513 seconds
+Insert test 4: 3.793392 seconds
+Insert test 5: 3.725927 seconds
+Insert test 6: 3.814542 seconds
+Insert test 7: 3.760054 seconds
+Insert test 8: 3.936868 seconds
+Insert test 9: 4.061833 seconds
+Min: 3.53403
+Max: 4.222878
+Average: 3.8570827

data/benchmark/sqlite-no-prepare.2.txt

@@ -0,0 +1,13 @@
+Insert test 0: 4.050384 seconds
+Insert test 1: 4.098912 seconds
+Insert test 2: 3.739213 seconds
+Insert test 3: 4.030227 seconds
+Insert test 4: 4.061516 seconds
+Insert test 5: 3.963748 seconds
+Insert test 6: 4.088462 seconds
+Insert test 7: 4.047734 seconds
+Insert test 8: 3.966496 seconds
+Insert test 9: 3.948346 seconds
+Min: 3.739213
+Max: 4.098912
+Average: 3.9995038

data/benchmark/sqlite-prepare.1.txt

@@ -0,0 +1,13 @@
+Insert test 0: 3.578891 seconds
+Insert test 1: 4.257714 seconds
+Insert test 2: 3.535036 seconds
+Insert test 3: 3.742329 seconds
+Insert test 4: 3.874829 seconds
+Insert test 5: 3.608657 seconds
+Insert test 6: 3.843804 seconds
+Insert test 7: 3.688756 seconds
+Insert test 8: 3.858303 seconds
+Insert test 9: 3.739155 seconds
+Min: 3.535036
+Max: 4.257714
+Average: 3.7727474

data/benchmark/sqlite-prepare.2.txt

@@ -0,0 +1,13 @@
+Insert test 0: 3.859916 seconds
+Insert test 1: 4.321912 seconds
+Insert test 2: 3.836067 seconds
+Insert test 3: 4.077798 seconds
+Insert test 4: 4.171512 seconds
+Insert test 5: 4.148027 seconds
+Insert test 6: 3.841498 seconds
+Insert test 7: 3.94367 seconds
+Insert test 8: 3.758128 seconds
+Insert test 9: 4.25072 seconds
+Min: 3.758128
+Max: 4.321912
+Average: 4.0209248

data/doc/AUTHORS

@@ -18,14 +18,5 @@ IDEAS, ADDITIONAL CODING, SUPPORT:
 * Elias Athanasopoulos  <elathan@navel.gr>
 	Additional coding.
 
-* Gavin Sinclair <gsinclair@soyabean.com.au>
-	Logger#trace method.
-
 * Thomas Quas  <tquas@yahoo.com>
 	Ideas, bug reports, unit tests.
-
-* Kostas Nasis  <kostas@nasis.com>
-	Ideas and bug reports.
-
-* Elias Karakoulakis  <ekarak@navel.gr>
-	Additional design.

data/{RELEASES.og → doc/RELEASES}

@@ -1,3 +1,18 @@
+== Version 0.13.0 was released on 17/03/2005.
+
+A maintenance release. 
+
+Most notable additons:
+
+* Better separated from Nitro.
+
+* Database related validations (validate_unique) etc.
+
+* Emmit warnings on implicit graph changes.
+
+* Many bugfixes.
+
+
 == Version 0.12.0 was released on 07/03/2005.
 
 A careful blend of new features and subtle improvements

data/doc/config.txt

@@ -0,0 +1,35 @@
+= Og Configuration parameters
+
+This file presents a complete list of Og configuration 
+parameters.
+
+=== Og.table_prefix = nil
+
+Attach the given prefix to all generated SQL table names.
+Usefull on hosting scenarios where you have to run multiple
+applications/sites on a single database.
+
+=== Og.auto_manage_classes = true
+
+If true, use Ruby's advanced introspection capabilities to 
+automatically manage classes that define properties.
+	
+=== Og.enchant_managed_classes = true
+
+If true, the library automatically 'enchants' managed classes.
+In enchant mode, special db aware methods are added to 
+managed classes and instances. If false, Og enchants only classes 
+that define properties.
+	
+=== Og.create_schema = true
+
+If set to true, Og attempts to recreate the database schema
+to store the managed objects. If the table for an object class
+exists, Og does not recreate it. It is useful to get Og to
+automatically create the schema for your application on setup,
+or when you add a new managed class to your application. On 
+the downside, it inflicts a longer startup time on the 
+application, so it is better to set this to false in 
+production / live environments.
+
+This option is by default true to facilitate easy development.

data/doc/tutorial.txt

@@ -0,0 +1,595 @@
+= Og Tutorial
+
+=== Introduction
+
+Ruby is a wonderful object oriented language featuring a well
+designed syntax and advanced constructs to bring the joy back
+to programming. Creating the object model to describe your
+problem domain is easy, but making this model persistent is
+another story: you have to deal with relational databases
+and the SQL language.
+
+RDBMS systems are a proven and robust technology for storing
+and querying data, but after experiencing the wonders of Ruby,
+it is hard not to wish for a better way to integrate the OOP
+and Relational paradigms.
+
+Og makes your dream come true! Og stands for ObjectGraph and
+provides a transparent way to make your objects persistent
+while leveraging the full querying power of an RDBMS system.
+In fact, Og is designed to use an RDBMS system like MySQL or
+PostgreSQL to implement the actual data store where the
+objects are serialized.
+
+But, enough with the techno-babble, let's walk through a simple
+example to give you a better idea of what Og can do.
+
+
+=== Installing Og
+
+The best way to install Og is through RubyGems. For example:
+
+gem install og
+
+In order to use Og with a specific RDBMS, you have to install
+the corresponding Ruby binding. A list of supported RDBMS's
+and information about the Ruby bindings can be found in the
+README file.
+
+Alternatively, you can install a .tar.gz or .zip distribution.
+You can find these at the following URL:
+
+http://www.rubyforge.com/projects/nitro
+
+
+=== A Basic Blog Model
+
+Blogs are in vogue. It seems that almost everyone is running a blog, and
+many try to code one from scratch. We'll review the steps necessary
+to generate the persistence model for a blog application using Og.
+
+Let's start by designing the objects we'll use. Our simple Blog
+will use these three objects:
+
+# Blog category
+
+class Category
+    attr_accessor :name
+end
+
+# Blog posting
+
+class Post
+    attr_accessor :title
+    attr_accessor :body
+    attr_accessor :author
+end
+
+# Blog comment
+
+class Comment
+    attr_accessor :title
+    attr_accessor :body
+    attr_accessor :author
+end
+
+As you can see, this is pure Ruby code. One of the features of
+Ruby is dynamic typing. When defining the attributes of our
+objects, we don't declare the actual type. However, in order to
+persist the model in SQL, we need to provide some hints to Og.
+
+Og provides a replacement to the attr* family of methods to
+facilitate attaching metadata to the object's attributes. An
+attribute that contains metadata is called a property. For
+each attr* method, there is a corresponding prop* method. That is,
+
+    attr          => prop
+    attr_accessor => prop_accessor
+    attr_reader   => prop_reader
+    attr_writer   => prop_writer
+
+Here are the class definitions using the property mechanism:
+
+require 'og'
+
+class Category
+    prop_accessor :name, String
+end
+
+class Post
+    prop_accessor :title, String
+    prop_accessor :body, String
+    prop_accessor :author, String
+    prop_accessor :create_time, Time
+    prop_accessor :hits, Fixnum
+end
+
+class Comment
+    prop_accessor :title, String
+    prop_accessor :body, String
+    prop_accessor :author, String
+    prop_accessor :create_time, Time
+end
+
+Notice that the prop_accessor works similar to Ruby's attr_accessor. 
+Here are some examples:
+
+prop :title, true, String
+prop_reader :title, :body, :author, String
+
+To make the definitions look even cleaner, Og provides the property alias:
+
+class Category
+    property :name, String
+end
+
+class Post
+    property :title, String
+    property :body, String
+    property :author, String
+    property :create_time, Time
+    property :hits, Fixnum
+end
+
+class Comment
+    property :title, String
+    property :body, String
+    property :author, String
+    property :create_time, Time
+end
+
+This is most of the information that Og needs to manage these objects. Before we continue,
+we need to setup the actual RDBMS data store used by Og. Currently, Og has built-in adapters
+for PostgreSQL, MySQL, SQLite3, and Oracle. For this example, we'll use the PostgreSQL adapter,
+so add this code after the class definitions.
+
+db = Og::Database.new(
+    :database => 'test',
+    :adapter  => 'psql',
+    :user     => 'postgres',
+    :password => 'navelrulez'
+)
+
+Now you are ready to save your first object into Postgres. Add the following code:
+
+# create the object
+p = Post.new
+p.title = 'Hello'
+p.body = 'World'
+p.author = 'tml'
+
+# save the object in the database
+p.save
+
+That's it! Og works behind the scenes doing all the work for you.
+This simple command, p.save, does the following:
+
+1. Creates the database 'test' if it doesn't exist.
+2. Creates a table to store Post objects if it doesn't exist.
+   The table's columns map to the object properties.
+3. Creates SQL indices.
+4. Creates any needed sequences.
+5. Serializes the object into the table.
+
+Issue the following SQL to see the result:
+
+SELECT * FROM og_post
+
+This is nice, but where does the #save method come from?
+Og uses Ruby's advanced introspection features to automatically
+'enchant' class that define properties. An enchanted class
+provides several methods that will be discussed in the following
+text. These enchanted classes are called *managed* classes.
+
+Before going on, let's look at another Og macro that eases object creation:
+
+p = Post.create
+
+Create automatically calls the save method. Here is another way to save the object:
+
+db << p
+
+OR
+
+db.save(p)
+
+
+Let's create a Category object.
+
+cat = Category.new
+cat.name = 'Programming'
+cat.save
+
+If you investigate the generated og_category table, you will
+see an 'oid' column which serves as the primary key. This
+column is added automatically by Og. You can use the oid
+values to lookup objects:
+
+cat = Category[1] # loads the category object with oid = 1
+
+OR
+
+cat = db.load(1, Category)
+
+As a convenience, Og allows you to lookup the category
+using the special property 'name':
+
+cat = Category['Programming']
+
+You can lookup objects by name only if the name property is
+defined.
+
+If you want to view Og's SQL, you can enable debug mode by setting this global 
+debug (DBG) variable:
+
+$DBG = true
+
+
+=== Customizing the Schema and Defining Relations
+
+Og makes our blog model persistent through a simple interface. The next step is to
+refine the schema and define relations between the objects:
+
+class Post; end
+class Comment; end
+
+class Category
+    property :name, String
+
+    many_to_many :posts, Post
+
+    def initialize(title = nil)
+        @title = title
+    end
+end
+
+class Post
+    property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
+    property :body, String
+    property :author, String
+    property :create_time, Time
+    property :hits, Fixnum, :sql_index => true
+
+    has_many :comments, Comment
+
+    def initialize(title = nil, body = nil, author = nil)
+        @title, @body, @author = title, body, author
+        @create_time = Time.now
+        @hits = 0
+    end
+end
+
+class Comment
+    property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
+    property :body, String
+    property :author, String
+    property :create_time, Time
+
+    belongs_to :post, Post
+
+    def initialize(title = nil, body = nil, author = nil)
+        @title, @body, @author = title, body, author
+        @create_time = Time.now
+    end
+end
+
+Observe the :sql property option is used to refine
+the generated column type for the title property of Post,
+and how the :sql_index option is used to add an index to
+the generated table.
+
+Notice that the initialize methods provide default
+values to all parameters. This is required for all managed objects.
+
+Observe the many_to_many, has_many, and belongs_to macros.
+Og uses these macros to define the relations between
+standard Objects. In essence, Og defines a domain specific
+mini language. The following kinds of relations are
+supported:
+
+    * has_one: has one object of the given type.
+
+    * has_many: has many objects of the given type.
+
+    * belongs_to: belongs_to an object of the given type.
+
+    * many_to_many: defines a many-to-many relation. The corresponding
+      rows in the database are linked through a join table.
+
+    * refers_to: refers to another object.
+
+These macros generate the constructs needed to efficiently implement
+the corresponding relations. For example, the belongs_to macro generates
+the property that links to the parent. The many_to_many relation generates
+the join table that links the participating classes.
+
+Note that we have to use forward definitions of Post and Comment to satisfy
+Ruby's parser. Workarounds will be provided in a future version.
+
+After defining these relations, using and querying the object model is easy:
+
+cat = Category.create('Programming')
+
+cat.add_post { |p|
+     p.title = 'Title'
+     p.body = 'Body
+}
+
+cat.add_post { |p|
+    p.title = 'Another'
+    p.body = 'Hello'
+}
+
+cat.posts
+ => [Post(Title), Post(Another)]
+
+cat.posts[0].title
+ => Title
+
+cat.posts.size
+ => 2
+
+p = Post[1]
+p.title
+ => Title
+
+p.categories[0].title
+ => 'Programming'
+
+c = Comment.new('hello', 'world', 'tml')
+c.post = p
+c.save
+
+p.comments.size
+ => 1
+
+p.add_comment { |c|
+    c.title = 'Hi there'
+}
+
+p.comments[1].title
+  => 'Hi there'
+
+com = Comment.new('Hi there')
+p.add_comment(com)
+
+All the methods used in the above examples are generated automatically.
+These methods transparently modify the underlying SQL schema using efficient queries.
+
+Og provides full access to all features of the underlying RDBMS. Look at the following:
+
+post = Post.select("title='Title' and body='Body'")
+post.size
+ => 1
+post.hits
+ => 0
+
+Updating existing objects is easy too:
+
+p = Post[1]
+p.title = 'Changed'
+p.save
+
+p = Post[1]
+p.title
+ => 'Changed'
+
+You can also update specific properties, for example:
+
+p = Post[1]
+p.update_properties "body='Hello world'"
+
+p = Post[1]
+p.body
+ => 'Hello world'
+
+If you don't like a particular comment, you can easily delete it by doing the following:
+
+Comment.delete(comment)
+
+OR
+
+comment.delete!
+
+OR
+
+db.delete(comment)
+
+To delete all comments for a posting, enter the following:
+
+p.delete_all_comments
+
+When deleting an object that participates in relations, Og tries
+to delete all objects that belong to this object (ie, cascade deletes).
+
+All the generated methods take more parameters to customize their
+behaviour to suit your needs.
+
+
+=== Defining Callbacks
+
+Og provides a detailed callback facility allowing you to hook
+into a managed object's Lifecycle. This is a very useful
+feature that can improve your code considerably. To implement
+a callback, you have to define one or more of the following methods
+in your class:
+
+    * og_pre_insert
+    * og_post_insert
+    * og_pre_update
+    * og_post_update
+    * og_pre_insert_update
+    * og_post_insert_update
+    * self.og_pre_delete
+
+For example, the following code defines a callback for the Post class.
+
+class Post
+  ...
+
+  def og_post_insert(conn)
+        puts 'Hey, a new post was just posted!'
+    end
+end
+
+When post.save is called, you'll get this alert:
+
+p = Post.create('Hello')
+ => console: Hey, a new post was just posted!
+
+
+=== Using OOP techniques
+
+Og's managed objects are standard Ruby objects, so we can use class inheritance
+and module inclusion to minimize the code we have to write. Here's how we can
+improve the blog schema:
+
+class Category
+    property :name, String
+    many_to_many :posts, Post
+
+    def initialize(title = nil)
+        @title = title
+    end
+end
+
+class Common
+    property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
+    property :body, String
+    property :author, String
+    property :create_time, Time
+
+    def initialize(title = nil, body = nil, author = nil)
+        @title, @body, @author = title, body, author
+        @create_time = Time.now
+    end
+end
+
+class Post < Common
+    property :hits, Fixnum, :sql_index => true
+    has_many :comments, Comment
+
+    def initialize(title = nil, body = nil, author = nil)
+        super
+        @hits = 0
+    end
+end
+
+class Comment < Common
+    belongs_to :post, Post
+end
+
+In essence, this feature allows you to create SQL tables using inheritance,
+saving you lots of time when using objects with similar properties. It's also
+less error prone.
+
+
+=== Defining Validation Rules
+
+When managing large amounts of data, enforcing data integrity is
+important. Og provides another domain specific mini language that allows
+you to define validation rules in a simple manner. In the following code,
+the blog schema is enriched with hints that allows Og to automatically generate
+validation code:
+
+class Common
+    property :title, String, :sql => 'NOT NULL VARCHAR(32)'
+    property :body, String
+    property :author, String
+    property :create_time, String
+
+    validate_value :title
+    validate_length :body, :range => 2..100, :msg_long => 'argh'
+    validate_format :author, :format => /[a-z]/, :msg => 'wrong format'
+
+    def initialize(title = nil, body = nil, author = nil)
+        @title, @body, @author = title, body, author
+        @create_time = Time.now
+    end
+end
+
+This code demonstrates some validations facilities. Using the validate_value
+macro, we enforce that the 'title' property will have a value. Using the
+validate_length macro, we enforce the minimum and maximum lengths for the
+'body' property. Using the validate_format macro, we enforce a required
+format for values assigned to the 'author' field.
+
+Let's see this validation in practice:
+
+c = Comment.new
+c.valid?
+ => false
+c.errors.count
+ => 3
+
+c.title = 'Hello'
+c.valid?
+c.errors.count
+ => 2
+
+The errors array contains a list of Error objects that point to the offending
+field and contain a descriptive message.
+
+With Og, you can customize almost everything! More information can be found in the source code
+(lib/glue/validation.rb). To whet your appetite, here is a list of predefined validation macros:
+
+    * validate_value
+    * validate_format
+    * validate_length
+    * validate_inclusion
+    * validate_confirmation
+
+
+=== TypeMacros
+
+If you look at the common class definition, you will notice that the :sql
+option looks kind of ugly:
+
+:sql => 'VARCHAR2(32) NOT NULL'
+
+When building larger object models, this issue comes up frequently. Og
+provides a elegant solution in the form of type macros:
+
+def VarChar(size)
+    return String, :sql => "VARCHAR2(#{size}) NOT NULL"
+end
+
+property :title, VarChar(30)
+
+
+=== Switching To Another Database
+
+While Postgres is a great database, let's assume that the client wants to switch to
+MySQL at the last minute. Don't worry, Og can easily accomodate this by simply changing
+the db reference in the configuration file to look like this and then re-running the example:
+
+db = Og::Database.new(
+    :database => 'test',
+    :adapter  => 'mysql',
+    :user     => 'postgres',
+    :password => 'navelrulez'
+)
+
+A new MySQL database is automatically created along with all tables, indices, etc. You get all 
+this with changing only one line of code!
+
+
+=== Is There More?
+
+You betcha! You can to find more about Og by reading the available RDoc documentation and browsing the examples.
+
+For any questions regarding Og, feel free to ask on the ruby-talk 
+mailing list (which is mirrored to comp.lang.ruby) or contact 
+mailto:gm@navel.gr.
+
+A Nitro specific mailing list is also available. You can post questions about
+Og to this list. Please subscribe to nitro-general@rubyforge.com. The homepage 
+for this list is available here:
+
+http://rubyforge.org/mailman/listinfo/nitro-general
+
+Note that Og is still under heavy development, so new features are being added frequently. 
+Be sure to check back for updates.
+
+
+