automatthew / filebase forked from dyoder/filebase

= Warning

This code is alpha quality. Do not use in production.

= Introduction

Filebase is a very file-based datastore. It comes with drivers for JSON, YAML, and Marshal, where each record is 
serialized to an individual file, but you can implement different storage classes if you like. It also provides a model 
class that allows you to treat your records like classes, including a very basic associations implementation.

= Example

Assuming we have the file 'joe@acme.com.yml' in the 'db/person' directory and it looks like this:

  --- 
  name: Joe Smith
  organization: acme.com
  key: joe@acme.com

Then the code for accessing this "database" looks like this:

  class Person
    include Filebase::Model[ :db / :person ]
    has_one :organization
  end
  class Organization
    include Filebase::Model[ :verify / :db / :organization ]
    has_many :members, :class => Person
  end

  joe = Person.find( 'joe@acme.com' )
  joe.name                                      # => 'Joe Smith'
  joe.organization.name                          # => 'Acme, Inc.'
  
You can create and delete records much like a normal database. You find an object using it's "key" which is actually the 
filename (typically with an extension like '.yml') and can be accessed using the "key" attribute. Note that changing an 
object's key will not remove the original value - you have to explicitly delete it. So, in effect, you can copy a value 
by changing the key and saving it.

Also, a note on the associations - they are not automatically bi-directional. Putting a has_one in one place and a 
complementary has_many in another does not mean that if you change one, the other will change. This will be fixed in a 
later version, but for now, remember, these are files, and the data is not synchronized between them in any way.

Another limitation is that there is no real query language. You can access all of the records for a given model using 
#all, and then filter them as you would any array. But obviously if you find yourself need complex queries spanning 
several different classes, you should probably use a relational database.