hobofields 0.7.5

data/test/hobofields.rdoctest

@@ -0,0 +1,57 @@
+# HoboFields
+
+## About Doctests
+
+HoboFields is documented and tested using *doctests*. This is an idea that comes from Python that we've been experimenting with for Hobo. Whenever you see code-blocks that start "`>>`", read them as IRB sessions. The `rdoctest` tool extracts these and runs them to verify they behave as advertised. 
+
+Doctests are a great way to get both documentation and tests from the same source. We're still experimenting with exactly how this all works though, so if the docs seem strange in places, please bear with us!
+
+## Introduction 
+
+HoboFields lives on GitHub: [http://github.com/tablatom/hobofields](http://github.com/tablatom/hobofields)
+
+You can install it with git:
+
+	git clone git://github.com/tablatom/hobofields.git vendor/plugins/hobofields
+
+Or subversion:
+
+	svn export svn://hobocentral.net/hobofields/tags/rel_0.7.4 vendor/plugins/hobofields
+	
+HoboFields provides two main features:
+
+ * An extension to ActiveRecord that provides rich field types such as "markdown text" or "email address"
+ * A generator that writes your migrations for you. Your migration writing days are over.
+ 
+This is all done using a declaration of your fields that you put in your models, for example
+
+    class BlogPost < ActiveRecord::Base
+      fields do
+        title :string
+        body  :text
+      end
+    end
+{: .ruby}
+
+**NOTE:** If you're going to use the migration generator outside of Hobo, do remember the `--skip-migration` option when generating your models:
+
+	./script/generate model post --skip-migration
+
+
+## [Migration Generator](/hobofields/migration_generator)
+
+Once you have declared your fields like this, you can run the following, at any time during the development of your project:
+
+	$ ./script/generate hobo_migration
+	
+The migration generator will create a migration to change from the schema that is currently in your database, to the schema that your models need. That's really all there is to it. Note that the migration generator is interactive -- it can't tell the difference between renaming something vs. adding one thing and removing another, so it has to ask you.
+
+The [migration generator doctests](/hobofields/migration_generator) provide a lot more detail. They're not really that great as documentation because doctests run in a single irb session, and that doesn't fit well with the concept of a generator. Skip these unless you're really keen to see the details of the migration generator in action
+
+## [HoboFields API](/hobofields/hobofields_api)
+
+As well as the migration generator, HoboFields provides a bunch of small extensions to ActiveRecord. The [HoboFields API doctests](/hobofields/hobofields_api) provide a useful reference to these.
+
+## [Rich Types](/hobofields/rich_types)
+
+Documentation for the full set of rich types bundled with HoboFields, and how to create your own, is [here](/hobofields/rich_types).

data/test/hobofields_api.rdoctest

@@ -0,0 +1,247 @@
+# HoboFields API
+
+## Connect to the Database
+
+In order for the API examples to run we need a connection to a database. You can ignore this if you're just looking for documentation.
+
+    >> require 'rubygems'
+    >> require 'activesupport'
+    >> Dependencies.load_paths << '.'
+    >> Dependencies.mechanism = :require
+    >> require 'activerecord'
+    >> require 'hobofields'
+    >> mysql_database = "hobofields_doctest"
+    >> system("mysqladmin create #{mysql_database}") or raise "could not create database"
+    >> ActiveRecord::Base.establish_connection(:adapter => "mysql",
+                                               :database => mysql_database,
+                                               :host => "localhost")
+
+## Example Models
+
+Let's define some example models that we can use to demonstrate the API. With HoboFields we define the model's fields, with their name and type, directly in the model like so:
+
+	>>
+	class Advert < ActiveRecord::Base
+	  fields do
+		title           :string
+		body            :text
+		contact_address :email_address
+	  end
+	end
+
+(Note: `:email_address` is an example of a "Rich Type" provided by HoboFields -- more on those later)
+
+The migration generator uses this information to create a migration. The following creates and runs the migration so we're ready to go.
+
+	>> up, down = HoboFields::MigrationGenerator.run
+	>> ActiveRecord::Migration.class_eval up
+	
+We're now ready to start demonstrating the API
+
+## The Basics
+
+The main feature of HoboFields, aside from the migration generator, is the ability to declare rich types for your fields. For example, you can declare that a field is an email address, and the field will be automatically validated for correct email address syntax.
+
+### Field Types
+
+Field values are returned as the type you specify.
+
+	>> a = Advert.new :body => "This is the body"
+	>> a.body.class
+	=> HoboFields::Text
+	
+This also works after a round-trip to the database
+
+	>> a.save
+	>> b = Advert.find(a.id)
+	>> b.body.class
+	=> HoboFields::Text
+
+HoboFields::Text is a simple subclass of string. It's a "wrapper type", by which we mean you pass the underlying value to the constructor. 
+
+	>> t = HoboFields::Text.new("hello")
+	=> "hello"
+	>> t.class
+	=> HoboFields::Text
+	
+If you define your own rich types, they need to support a one argument constructor in the same way.
+
+Although the body of our advert is really just a string, it's very useful that it has a different type. For example, the view layer in Hobo Rapid would use this information to render a `<textarea>` rather than an `<input type='text'>` in an Advert form.
+	
+
+## Names vs. Classes
+
+In the `fields do ... end` block you can give the field-type either as a name (symbol) or a class. For example, we could have said
+
+	body HoboFields::Text
+	
+Obviously the symbol form is a nicer:
+
+	body :text
+
+If you provide a class it must define the `COLUMN_TYPE` constant. This instructs the migration generator to create the appropriate underlying database column type. It should be a symbol that is a valid column type in a Rails migration. 
+
+	>> HoboFields::Text::COLUMN_TYPE
+	=> :text
+	
+The full set of available symbolic names is
+  
+ * `:integer`
+ * `:big_integer`
+ * `:float`
+ * `:string`
+ * `:text`
+ * `:boolean`
+ * `:date`
+ * `:datetime`
+ * `:html`
+ * `:textile`
+ * `:markdown`
+ * `:password`
+ * `:email_addresss`
+
+You can add your own types too. More on that later.
+
+
+## Model extensions
+	
+HoboFields adds a few features to your models.
+	
+### `Model.attr_type`
+
+Returns the type (i.e. class) declared for a given field or attribute
+
+	>> Advert.attr_type :title
+	=> String
+	>> Advert.attr_type :body
+	=> HoboFields::Text
+	
+### `Model.column`
+
+A shorthand for accessing column metadata
+
+	>> col = Advert.column :title
+	>> col.name
+	"title"
+	>> col.klass
+	>> String
+
+### `Model.attr_accessor` with types
+
+In your HoboFields models you can also give type information to "virtual fields" (i.e. regular Ruby attributes)
+
+	>>
+	class Advert
+	  attr_accessor :my_attr, :type => :text
+	end
+	>> a = Advert.new
+	>> a.my_attr = "hello"
+	>> a.my_attr.class 
+	=> HoboFields::Text
+	
+
+## Field validations
+
+HoboFields gives you some shorthands for declaring some common validations right in the field declaration
+
+### Required fields
+
+The `:required` argument to a field gives a `validates_presence_of`:
+
+	>> 
+	class Advert
+	  fields do
+	    title :string, :required
+	  end
+	end
+	>> a = Advert.new
+	>> a.valid?
+	=> false
+	>> a.errors.full_messages
+	=> ["Title can't be blank"]
+	>> a.title = "Jimbo"
+	>> a.save
+	=> true
+	
+
+### Unique fields
+
+The `:unique` argument in a field declaration gives `validates_uniqueness_of`:
+    
+	>> 
+	class Advert < ActiveRecord::Base
+	  fields do
+	    title :string, :unique
+	  end
+	end
+	>> a = Advert.new :title => "Jimbo"
+	>> a.valid?
+	=> false
+	>> a.errors.full_messages
+	=> ["Title has already been taken"]
+	>> a.title = "Sambo"
+	>> a.save
+	=> true
+	
+Let's get back to the basic Advert class with no validations before we continue:
+   
+	>> Dependencies.remove_constant "Advert"
+	>>
+	class Advert < ActiveRecord::Base
+	  fields do
+	    title           :string
+	    body            :text
+		contact_address :email_address
+	  end
+	end
+
+	
+### Type specific validations
+
+Rich types can define there own validations by a `#validate` method. It should return an error message if the value is invalid, otherwise nil. We can call that method directly to show how it works:
+
+	>> a = Advert.new :contact_address => "not really an email address"
+	>> a.contact_address.class
+	=> HoboFields::EmailAddress
+	>> a.contact_address.validate
+	=> "is not valid"
+	
+But normally that method would be called for us during validation:
+	
+	>> a.valid?
+	=> false
+	>> a.errors.full_messages
+	=> ["Contact address is not valid"]
+	>> a.contact_address = "me@me.com"
+	>> a.valid?
+	=> true
+	
+You can add this capability to your own rich types just by defining `#validate`
+	
+### Validating virtual fields
+
+You can set the type of a virtual field to a rich type, e.g.
+
+	>>
+	class Advert
+	  attr_accessor :alternative_email, :type => :email_address
+	end
+	
+By default, virtual fields are not subject to validation.
+
+	>> a = Advert.new :alternative_email => "woot!"
+	>> a.valid?
+	=> true
+
+To have them validated use `validate_virtual_field`:
+
+	>>
+	class Advert
+	  validate_virtual_field :alternative_email
+	end
+	>> a.valid?
+	=> false
+	
+## Cleanup
+
+    >> system  "mysqladmin --force drop #{mysql_database}"

data/test/migration_generator.rdoctest

@@ -0,0 +1,410 @@
+# HoboFields - Migration Generator
+
+Note that these doctests are good tests but not such good docs. The migration generator doesn't really fit well with the doctest concept of a single IRB session. As you'll see, there's a lot of jumping-through-hoops and doing stuff that no normal user of the migration generator would ever do.
+
+Firstly, in order to test the migration generator outside of a full Rails stack, there's a few things we need to do. First off we need to configure ActiveSupport for auto-loading
+
+    >> require 'rubygems'
+    >> require 'activesupport'
+    >> Dependencies.load_paths << '.'
+    >> Dependencies.mechanism = :require
+    
+And we'll require:
+
+    >> require 'activerecord'
+    >> require 'hobofields'
+
+We also need to get ActiveRecord set up with a database connection
+
+    >> mysql_database = "hobofields_doctest"
+    >> system("mysqladmin create #{mysql_database}") or raise "could not create database"
+    >> ActiveRecord::Base.establish_connection(:adapter => "mysql",
+                                               :database => mysql_database,
+                                               :host => "localhost")
+
+OK we're ready to get going.
+
+
+## The migration generator -- introduction
+
+The migration generator works by:
+
+ * Loading all of the models in your Rails app
+ * Using the Rails schema-dumper to extract information about the current state of the database.
+ * Calculating the changes that are required to bring the database into sync with your application.
+
+Normally you would run the migration generator as a regular Rails generator. You would type
+
+    $ script/generator hobo_migration
+    
+in your Rails app, and the migration file would be created in `db/migrate`. 
+
+In order to demonstrate the generator in this doctest script however, we'll be using the Ruby API instead. The method `HoboFields::MigrationGenerator.run` returns a pair of strings -- the up migration and the down migration. 
+
+At the moment the database is empty and no ActiveRecord models exist, so the generator is going to tell us there is nothing to do. 
+
+    >> HoboFields::MigrationGenerator.run
+    => ["", ""]
+
+
+### Models without `fields do` are ignored
+
+The migration generator only takes into account classes that use HoboFields, i.e. classes with a `fields do` declaration. Models without this are ignored:
+
+    >> class Advert < ActiveRecord::Base; end
+    >> HoboFields::MigrationGenerator.run
+    => ["", ""]
+
+
+### Create the table
+
+Here we see a simple `create_table` migration along with the `drop_table` down migration
+    
+    >> 
+    class Advert < ActiveRecord::Base
+      fields do
+        name :string
+      end
+    end
+    >> up, down = HoboFields::MigrationGenerator.run
+    >> up
+    =>""
+    create_table :adverts do |t|
+      t.string :name
+    end
+    >> down
+    => "drop_table :adverts"
+    
+Normally we would run the generated migration with `rake db:create`. We can achieve the same effect directly in Ruby like this:
+
+    >> ActiveRecord::Migration.class_eval up
+    >> Advert.columns.*.name
+    => ["id", "name"]
+    
+We'll define a method to make that easier next time
+
+    >>
+    def migrate(renames={})
+      up, down = HoboFields::MigrationGenerator.run(renames)
+      puts up
+      ActiveRecord::Migration.class_eval(up)  
+      ActiveRecord::Base.send(:subclasses).each { |model| model.reset_column_information }
+      [up, down]
+    end
+
+We'll have a look at the migration generator in more detail later, first we'll have a look at the extra features HoboFields has added to the model.
+
+
+### Add fields
+
+If we add a new field to the model, the migration generator will add it to the database.
+
+    >>
+    class Advert
+      fields do
+        name :string
+        body :text
+        published_at :datetime
+      end
+    end
+    >> up, down = migrate
+    >> up
+    =>""
+    add_column :adverts, :body, :text
+    add_column :adverts, :published_at, :datetime
+    >> down
+    =>""
+    remove_column :adverts, :body
+    remove_column :adverts, :published_at
+    >>
+
+### Remove fields
+
+If we remove a field from the model, the migration generator removes the database column. Note that we have to explicitly clear the known fields to achieve this in rdoctest -- in a Rails context you would simply edit the file
+
+    >> Advert.field_specs.clear # not normally needed
+    class Advert < ActiveRecord::Base
+      fields do
+        name :string
+        body :text
+      end
+    end
+    >> up, down = migrate
+    >> up
+    => "remove_column :adverts, :published_at"
+    >> down
+    => "add_column :adverts, :published_at, :datetime"
+    
+### Rename a field
+
+Here we rename the `name` field to `title`. By default the generator sees this as removing `name` and adding `title`.
+
+    >> Advert.field_specs.clear # not normally needed
+    class Advert < ActiveRecord::Base
+      fields do
+        title :string
+        body :text
+      end
+    end
+    >> # Just generate - don't run the migration:
+    >> up, down = HoboFields::MigrationGenerator.run
+    >> up
+    =>""
+    add_column :adverts, :title, :string
+    remove_column :adverts, :name
+    >> down
+    =>""
+    remove_column :adverts, :title
+    add_column :adverts, :name, :string
+    >>
+    
+When run as a generator, the migration-generator won't make this assumption. Instead it will prompt for user input to resolve the ambiguity. When using the Ruby API, we can ask for a rename instead of an add + drop by passing in a hash:
+
+    >> up, down = HoboFields::MigrationGenerator.run(:adverts => { :name => :title })
+    >> up
+    => "rename_column :adverts, :name, :title"
+    >> down
+    => "rename_column :adverts, :title, :name"
+    
+Let's apply that change to the database
+
+    >> migrate
+    
+    
+### Change a type
+
+    >> Advert.attr_type :title
+    => String
+    >>
+    class Advert
+      fields do
+        title :text
+        body :text
+      end
+    end
+    >> up, down = HoboFields::MigrationGenerator.run
+    >> up
+    => "change_column :adverts, :title, :text"
+    >> down
+    => "change_column :adverts, :title, :string"
+    
+    
+### Add a default
+    
+    >>
+    class Advert
+      fields do
+        title :string, :default => "Untitled"
+        body :text
+      end
+    end
+    >> up, down = migrate
+    >> up
+    => 'change_column :adverts, :title, :string, :default => "Untitled"'
+    >> down
+    => "change_column :adverts, :title, :string"
+
+
+### Foreign Keys
+
+HoboFields extends the `belongs_to` macro so that it also declares the foreign-key field.
+
+	>>
+	class Advert
+	  belongs_to :category
+	end
+	>> up, down = HoboFields::MigrationGenerator.run
+	>> up
+	=> 'add_column :adverts, :category_id, :integer'
+	>> down
+	=> 'remove_column :adverts, :category_id'
+	
+Cleanup:
+
+	>> Advert.field_specs.delete(:category_id)
+	
+If you specify a custom foreign key, the migration generator observes that:
+    
+	>>
+	class Advert
+	  belongs_to :category, :foreign_key => "c_id"
+	end
+	>> up, down = HoboFields::MigrationGenerator.run
+	>> up
+	=> 'add_column :adverts, :c_id, :integer'
+	>> down
+	=> 'remove_column :adverts, :c_id'
+	
+Cleanup:
+
+	>> Advert.field_specs.delete(:c_id)
+	
+	
+### Timestamps
+
+`updated_at` and `created_at` can be declared with the shorthand `timestamps`
+
+	>>
+	class Advert
+	  fields do
+	    timestamps
+	  end
+	end
+	>> up, down = HoboFields::MigrationGenerator.run
+	>> up
+	=>"" 
+	add_column :adverts, :created_at, :datetime
+	add_column :adverts, :updated_at, :datetime
+	>> down
+	=>""
+	remove_column :adverts, :created_at
+	remove_column :adverts, :updated_at
+	>>
+	
+Cleanup:
+
+	>> Advert.field_specs.delete(:updated_at)
+	>> Advert.field_specs.delete(:created_at)
+
+    
+### Rename a table
+
+The migration generator respects the `set_table_name` declaration, although as before, we need to explicitly tell the generator that we want a rename rather than a create and a drop.
+
+    >>
+    class Advert
+      set_table_name "ads"
+      fields do
+        title :string, :default => "Untitled"
+        body :text
+      end
+    end
+    >> up, down = HoboFields::MigrationGenerator.run(:adverts => :ads)
+    >> up
+    => "rename_table :adverts, :ads"
+    >> down
+    => "rename_table :ads, :adverts"
+    
+Set the table name back to what it should be and confirm we're in sync:
+
+    >> class Advert; set_table_name "adverts"; end
+    >> HoboFields::MigrationGenerator.run
+    => ["", ""]
+
+### Drop a table
+
+If you delete a model, the migration generator will create a `drop_table` migration. Unfortunately there's no way to fully remove the Advert class we've defined from the doctest session, but we can tell the migration generator to ignore it.
+
+    >> HoboFields::MigrationGenerator.ignore_models = [ :advert ]
+    
+Dropping tables is where the automatic down-migration really comes in handy:
+
+    >> up, down = HoboFields::MigrationGenerator.run
+    >> up
+    => "drop_table :adverts"
+    >> down
+    =>""
+    create_table "adverts", :force => true do |t|
+      t.text   "body"
+      t.string "title", :default => "Untitled"
+    end
+	>>
+    
+### Rename a table
+
+As with renaming columns, we have to tell the migration generator about the rename. Here we create a new class 'Advertisement'. Remember 'Advert' is being ignored so it's as if we renamed the definition in our models directory.
+
+    >>
+    class Advertisement < ActiveRecord::Base
+      fields do
+        title :string, :default => "Untitled"
+        body :text
+      end
+    end
+	>> up, down = HoboFields::MigrationGenerator.run(:adverts => :advertisements)
+    >> up
+    => "rename_table :adverts, :advertisements"
+    >> down
+    => "rename_table :advertisements, :adverts"
+    
+Now that we've seen the renaming we'll switch the 'ignore' setting to ignore that 'Advertisements' class.
+    
+    >> HoboFields::MigrationGenerator.ignore_models = [ :advertisement ]
+    
+## STI
+
+### Adding an STI subclass
+
+Adding a subclass should introduce the 'type' column and no other changes
+
+	>>
+	class FancyAdvert < Advert
+	end
+    >> up, down = HoboFields::MigrationGenerator.run
+    >> up
+	=> "add_column :adverts, :type, :string"
+	>> down
+	=> "remove_column :adverts, :type"
+	
+Cleanup
+
+	>> Advert.field_specs.delete(:type)
+
+
+## Coping with multiple changes
+    
+The migration generator is designed to create complete migrations even if many changes to the models have taken place.
+
+First let's confirm we're in a known state. One model, 'Advert', with a string 'title' and text 'body':
+
+    >> Advert.connection.tables
+    => ["adverts"]
+    >> Advert.columns.*.name
+    => ["id", "body", "title"]
+    >> HoboFields::MigrationGenerator.run
+    => ["", ""]
+    
+
+### Rename a column and change the default
+
+    >> Advert.field_specs.clear
+    >>
+    class Advert
+      fields do
+        name :string, :default => "No Name"
+        body :text
+      end
+    end
+    >> up, down = HoboFields::MigrationGenerator.run(:adverts => {:title => :name})
+    >> up
+    =>""
+    rename_column :adverts, :title, :name
+    change_column :adverts, :name, :string, :default => "No Name"
+    >> down
+    =>""
+    rename_column :adverts, :name, :title
+    change_column :adverts, :title, :string, :default => "Untitled"
+    >>
+    
+    
+### Rename a table and add a column
+    
+    >> HoboFields::MigrationGenerator.ignore_models << :advert
+    class Ad < ActiveRecord::Base
+      fields do
+        title      :string, :default => "Untitled"
+        body       :text
+        created_at :datetime
+      end
+    end
+    >> up, down = HoboFields::MigrationGenerator.run(:adverts => :ads)
+    >> up
+    =>""
+    rename_table :adverts, :ads
+    
+    add_column :ads, :created_at, :datetime
+    >>
+
+## Cleanup
+
+    >> system  "mysqladmin --force drop #{mysql_database}"