Cheri builder–builder
The Cheri builder–builder is a tool for creating (or
extending) builder applications, or more simply, builders. Before I go any further,
let me stop and define what I mean by a builder:
A builder is a
domain-specific language
(DSL) for creating and/or representing hierarchies of related objects using a declarative syntax. By
declarative syntax, I mean one
that describes the (resultant) hierarchical structure, rather than the means by which it is created.
The Cheri builder–builder, then, is a meta-DSL for creating builder DSLs. (However, in light of the
above definition, the builder–builder is not, strictly speaking, a meta-builder, or a builder
at all, as its syntax is not strictly declarative.)
The builder–builder provides an easy way to create builders based on the Cheri builder
framework/engine (as are Cheri::Swing, Cheri::Xml and Cheri::Html). Before I bore you with
a BNF diagram of Cheri's
particular take on builder syntax (honestly, I was about to), let me move on to an example,
which should make things quite clear.
Example 1: A Really Simple Builder
Suppose we had a bookstore (unavoidable, it seems, in such examples), that represented a
number of authors, each of whom had written a number of books. Let's build a system that
captures and organizes certain information about the store, the authors, and the books.
We'll keep the model simple to begin with.
class Bookstore
attr :name, true
attr :address, true
attr :phone, true
attr :authors
def initialize(name=nil)
@name = name
@authors = []
end
def add(author)
@authors << author
end
end
|
class Author
attr :name, true
attr :hat_size, true
attr :shoe_size, true
attr :books
def initialize(name=nil)
@name = name
@books = []
end
def add(book)
@books << book
end
end
|
class Book
attr :title, true
attr :pages, true
attr :color, true
attr :mass, true
attr :density, true
def initialize(title=nil)
@title = title
end
end
|
Now that we've identified the truly relevant data, let's first look at populating our bookstore
in the usual (imperative) way.
@store = Bookstore.new 'Last Writes'
@store.address = '1313 Mockingbird Lane'
@store.phone = '867-5309'
author = Author.new 'Leo Tolstoy'
author.hat_size = 6.875 *
author.shoe_size = 8.0 *
@store.add author
book = Book.new 'War and Peace'
book.pages = 1424
book.color = 'gray'
book.mass = 973 †
book.density = 1.0/0.0 ‡
author.add book
book = Book.new 'Anna Karenina'
book.pages = 1024
book.color = 'scarlet'
book.mass = 582
book.density = 9301
author.add book
author = Author.new 'Terry Pratchett'
author.hat_size 7.5
author.shoe_size 11.75
@store.add author
book = Book.new 'Mort'
book.pages = 224
book.color = 'indigo'
book.mass = 148
book.density = 0.0/0.0
author.add book
# we could go on and on. but we won't.
* hat and shoe sizes in speculative US units
† mass in subjective units (SU)
‡ density in SU
Now let's look at how we'd populate the store using declarative syntax, if only we had a builder to help
us out. We'll assume it's a Cheri builder, because, of course, in a moment it will be.
@store = cheri.bookstore 'Last Writes' do
address '1313 Mockingbird Lane'
phone '867-5309'
author 'Leo Tolstoy' do
hat_size 6.875
shoe_size 8.0
book 'War and Peace' do
pages 1424
color 'gray'
mass 973
density 1.0/0.0
end
# or a litte more compactly:
book('Anna Karenina') {pages 1024; color 'scarlet'; mass 582; density 9301 }
end
# even more compactly
author('Terry Pratchett') { hat_size 7.5; shoe_size 11.75
book {title 'Mort'; pages 224; color 'indigo'; mass 148; density 0.0/0.0 }
# we'll do a couple more for fun
book {title 'Reaper Man'; pages 288; color 'green'; mass 218; density 42 }
book {title 'Soul Music'; pages 389; color 'yellow'; mass 486; density -13 }
}
end
That's a lot easier than using the imperative syntax. So, how do we create a Cheri
builder to enable this declarative syntax? Like this:
# creating a really simple builder
require 'cheri/builder'
BookstoreBuilder = Cheri::Builder.new_builder Bookstore, Book, Author
include BookstoreBuilder #=> remember Cheri builders are mixin modules
Of course, this example was a little contrived, in that both
the Bookstore and Author classes defined an add method,
which Cheri recognizes by default (for simple builders). The next example demonstrates
creating a builder for classes with 'add' methods other than add.
Example 2: A Slightly Less-Simple Builder
This example is almost the same as the previous one; the only difference is that
the add methods in classes Bookstore and Author have been
renamed:
class Bookstore
attr :name, true
attr :address, true
attr :phone, true
attr :authors
def initialize(name=nil)
@name = name
@authors = []
end
def add_author(author)
@authors << author
end
end
|
class Author
attr :name, true
attr :hat_size, true
attr :shoe_size, true
attr :books
def initialize(name=nil)
@name = name
@books = []
end
def add_book(book)
@books << book
end
end
|
class Book
attr :title, true
attr :pages, true
attr :color, true
attr :mass, true
attr :density, true
def initialize(title=nil)
@title = title
end
end
|
Cheri's default strategy of looking for an add method won't work here.
However, we can still use the builder–builder's "really simple" form, with just a slight
twist:
# creating an almost really simple builder
require 'cheri/builder'
BookstoreBuilder = Cheri::Builder.new_builder Book,
Author => :add_book,
Bookstore => :add_author
include BookstoreBuilder #=> remember Cheri builders are mixin modules
Beyond this point, we'll have to switch from the builder–builder's "really simple",
or parameter form, to its "still way easier than writing it yourself",
or block form, to take advantage of additional features of the Cheri builder platform/engine.
Example 3: Connections, part 1
The "really simple" builders we created in the first two examples work fine when used as intended.
However, it is also possible to use them incorrectly. For example, the following would be accepted:
@store = cheri.bookstore('Last Writes') {
bookstore 'Inner store?'
book 'Anonymous author?'
author('Fictional author?') {
author('Created by this one?') {
author('Or this one?') {
bookstore('Who owns a bookstore?')
}}}}
Now, for one-time use, or use only by yourself, that may be acceptable — you know
you'll use the builder correctly. But for regular use, or use by others, you'll probably want
something more robust. So let's look at how we can tighten things up.
As I hinted at earlier, the "really simple" (parameter) form of the builder–builder's
new_builder method is shorthand for a more detailed block form.
Here's what our bookstore builder looks like in block form, using the version from Example 2:
BookstoreBuilder = Cheri::Builder.new_builder do
# specify each class to be built
build Bookstore
build Author
build Book
# specify how objects of each type connect to other objects
type Bookstore do
connect Object, :add_author
end
type Author do
connect Object, :add_book
end
type Book do
connect Object, :add #=> :add is the default, may be omitted
end
end
Each build statement specifies a class to be built. By default,
the build method is the lower-case class name, with underscores inserted in place of any
camel-casing; so if our bookstore class name had been BookStore, the
method name would have been book_store. You can override the default
build method by following the class name with the symbol for the desired name:
build Bookstore, :store #=> override default build method 'bookstore'
The type statement defines how (and which) child objects may be connected to parent objects
of the specified type (class). As you will see in later examples, the type
(or types) statement is quite powerful; for example, superclasses or mixin
modules may be specified in place of the actual type. (Later examples will also show connecting
objects based on symbol [build method], rather than type.)
In this case, notice that the connect sub-statement for each type
specifies child class Object; that is the type inserted by the "really simple"
(parameter) form of the builder–builder, since it doesn't know anything about the
relationships among the classes you specified, or how you intend to use the builder. Class Object
will match just about any child object (we'll ignore 'orphan' classes here) —
as with the type statement itself, superclasses or mixins may be
specified in the connect statement.
(Also notice that the builder–builder created a type/connect pair for the Book class with the default
method add, even though Book doesn't define an add
method — I'll optimize this out in a later release.)
So all we really need to do to prevent illegal connections is change the
connect (child) types for Bookstore and Author:
type Bookstore do
connect Author, :add_author
end
type Author do
connect Book, :add_book
end
What happens now if we try to build an invalid hierarchy?
@store = cheri.bookstore('Last Writes') {
author 'Terry Pratchett'
bookstore 'Inner bookstore?'
}
Well… as you'd expect, the author will be added to the top bookstore. But the 'Inner bookstore'
just … sort of … vanishes. By default, Cheri does nothing if a child object can't be connected
to a parent object. But you'll probably want to know if that happens, as it will most likely be an
error of some sort. So let's issue a warning for any objects that don't get connected:
type Object do
connect Object do |parent, child, symbol|
warn "warning: can't connect #{child.class} (#{symbol}) to #{parent.class}"
end
end
Cheri's type matching logic works from most-specific class/module (nearest ancestor) to least, so
this code will only be invoked if a would-be child object can't be connected based on a more
specific ancestor than Object. [Note that an upcoming version of the builder–builder will
provide a shorthand method of specifying warnings/exceptions for unconnected objects.]
Here's our completed builder:
BookstoreBuilder = Cheri::Builder.new_builder do
# specify each class to be built
build Bookstore
build Author
build Book
# specify how objects of each type connect to other objects
type Bookstore do
connect Author, :add_author
end
type Author do
connect Book, :add_book
end
# issue warning for unconnected objects
type Object do
connect Object do |parent, child, symbol|
warn "warning: can't connect #{child.class} (#{symbol}) to #{parent.class}"
end
end
end
So far, we've been working with a very simple model: Bookstore => Author => Book. In the next
example, we'll look at creating a more complex builder.
Example 4: Connections, part 2
Coming soon! Check back a little later for the next example(s).
