# 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).