Stone: Dead-Simple Data Persistence

Get Version

0.1.2

→ ‘stone’

Sections

What

Installing

Getting Up and Running

Rails
Merb
Everywhere Else

Usage

Models
Get, Post, Put, and Delete

A Word About Finding Stuff

License

Contributing

Contact

What

For small applications, a database can be overkill for storing your data in a consistent and organized manner. Therefore, Stone was built to provide plug-and-play data persistence for any application or framework. It is fast, and it is easy… therefore it is good.

You can check out an application that uses Merb+Stone here.

The source for that blog is here.

Installing

sudo gem install stone

Up and Running

Rails

Create a new file in config/initializers called stone.rb

Add the following code to your new file:

  require 'stone'
  
  Stone.start(Dir.pwd, Dir.glob(File.join(Dir.pwd,"app/models/*")), :rails)

Open your environment.rb file and look for the following lines:

  # Skip frameworks you're not going to use (only works if using vendor/rails).
  # To use Rails without a database, you must remove the Active Record framework
  # config.frameworks -= [ :active_record, :active_resource, :action_mailer ]

Uncomment the last of those lines, and leave only active_record, so that it looks like this:

  # Skip frameworks you're not going to use (only works if using vendor/rails).
  # To use Rails without a database, you must remove the Active Record framework
  config.frameworks -= [ :active_record ]

Create some models! We’ll use an Author as an example:
```
  stone-gen model Author name:string
```

Merb

Add the following code to your init.rb file:

  dependency 'stone'
  
  # add this in the Merb::BootLoader.after_app_loads block
  # at the bottom of init.rb
  Stone.start(Dir.pwd, Dir.glob(File.join(Dir.pwd,"app/models/*")), :merb)

Create some models! We’ll use an Author as an example:
```
  stone-gen model Author name:string
```

Everywhere Else

Stone was designed to provide easy data storage management for any app, not just web ones.

Wherever you load your app, add the following:

  require 'stone'
  
  # replace path/to/models/ with wherever your models/resources may be
  Stone.start(Dir.pwd, Dir.glob(File.join(Dir.pwd,"path/to/models/*")))

Create some models! See Models.

That’s it! Remember, there are no databases to install with Stone. Instead, your data gets persisted to files within myapp/datastore/.

Usage

Model Files

Models are really easy to create. Here is an example:

  class Person
    include Stone::Resource   # gives you access to persistence methods
    
    # defines an attribute called "name" of type String
    field :name, String
    
    # defines an attribute called "email" of type String. 
    # Since :unique => true is set, "email" must be unique.
    field :email, String, :unique => true
    
    # Notifies Stone of a relationship between People and Jewels.
    # This allows for @person.jewels retrieval.
    has_many :jewels
    
    # both name and email must be present or errors will be added
    validates_presence_of :name, :email
  end

For more validation methods, see here.

Get, Post, Put, and Delete

Getting

  Author.get(some_id)             # gets Author with some_id
  Author[some_id]                 # same as get()
  
  # brings back first author whose name is "Nick DeMonner"
  Author.first(:name => "Nick DeMonner")
  
  # brings back first author whose name contains "Nick"
  Author.first(:name.includes => 'Nick')
  
  # brings back all authors whose email contains "gmail.com", and who 
  # were created before today
  Author.all(:email.includes => "gmail.com", :created_at.lt => DateTime.now)
  
  # brings back all Authors created before today, and orders them descending
  # from most recent to least
  Author.all(:created_at.lt => DateTime.now, :order => {:created_at => :desc})

Posting

  author = Author.new
  author.name = "Nick DeMonner"
  author.save                     # calls Author.post after validations

Putting

  author = Author[some_id]        # gets Author with id of some_id
  
  # updates name and calls Resource.save (which in turn calls Resource.put 
  # because this resource is being updated, not created)
  author.update_attributes(:name => "Bob Bobberson")

Deleting

  Author.delete(some_id)          # deletes Author at some_id

A Word About Finding Stuff

Stone uses a series of unique methods (à la DataMapper) to finding objects. You may use the following methods when searching:

Matches all objects whose field is greater than thing
```
  :field.gt => thing
```

Matches all objects whose field is greater than or equal to thing
```
  :field.gte => thing
```

Matches all objects whose field is less than thing
```
  :field.lt => thing
```

Matches all objects whose field is less than or equal to thing
```
  :field.lte => thing
```

Matches all objects whose field includes thing
```
  :field.includes => thing
```

Matches all objects whose field is equal to thing
```
  :field.equals => thing
```

Matches all objects whose field Regexp matches thing
```
  :field.matches => regexp
```

Matches all objects whose field does not equal thing
```
  :field.not => thing
```

License

This code is free to use under the terms of the MIT license.

Contributing

PLEASE. Stone is extremely immature at this point—“stable” is the watchword for the moment.

You can grab the source using Git:

  git clone git://github.com/ndemonner/stone.git

The code is pretty well specced out, so make sure you don’t break anything by running rake ok every once in a while.

Please add specs for any new functionality you might add, and hit me up to commit. =D

Contact

Comments are welcome. Join me in the IRC channel #stone on freenode.

Nick DeMonner, 17th April 2008
Theme extended from Paul Battley