veneer

Veneer is an interface that sits above Data Sources. A data source may be an ORM like ActiveRecord or DataMapper, or it could be a document store like MongoMapper or even just an storage like Moneta.

Veneer aims to provide plugin authors with a consistant interface to any of these libraries so that plugins, engines, stacks and gems may be used across data store types. Reusable code FTW!

It differs from ActiveModel in that it doesn’t provide any validation support, serialization, callbacks, state machine or anything like that. Veneer is intended to work with ActiveModel to provide a data store independant interface to create reusable code.

Veneer instead aims to provide a simple interface for

  • querying
  • creating
  • saving
  • deleting

Creating and Saving an instance

To create an instance of an object wrap the class in a vaneer call and create or get a new instance.

obj = Veneer(MyModel).new(:some => "attribute")
obj.save

 # OR

obj = Veneer(MyModel).create(:some => "attribute")

There are also version that will raise an exception if it could not save

obj = Veneer(MyModel).new(:some => "attribute").save!

# OR

obj = Veneer(MyModel).create!(:some => "attribute")

Deleting

You can delete all the instances of a model or a single instance.

Veneer(MyModel).destroy_all # delete all instances

@some_veneer_model.destroy

Queries

Veneer lets you query models with a simple interface. Only simple queries are supported.

You can query a single object, or multiple objects.

Veneer(MyModel).first(:conditions => {:name => "foo"})

Veneer(MyModel).all(:conditions => {"age gte" => 18}, :limit => 5)

The supported options are:

  • :limit
  • :offset
  • :order
  • :conditions

Limit & Offset

The :limit option will limit the number of returned results.

The :offset option, when set to an integer x will begin the results at the xth result.

Order

Ordering should be set as a string. By default, the order is decending.

The format of the string is:

"<field> (<directon>), <field> (direction), ..."

# eg
  Veneer(MyModel).all(:order => "name, age desc")

Conditions

Conditions are a very simple set of conditions on the fields of the model. The for of the conditions are:

:conditions => {"field operator" => value}

The supported operators are

  • eql
  • not
  • lt (less than)
  • lte (less than or equal to)
  • gt (greater than)
  • gte (greater than or equal to)
  • in (in an array)

By default, the operator is set to eql


  Veneer(MyModel).all(:conditions => {"name in" => ["fred", "barney"], "age gte" => 18})
  Veneer(MyModel).first(:conditions => {:name => "fred"})

The results of a query are all wrapped as Veneer instances.

All Together

Veneer(MyModel).all(:order => "name, age asc", :limit => 5, :offset => 15, :conditions => {"name not" => "betty", "age lt" => 18})

Object methods

All methods that aren’t found on the adapter, are passed through to the instance. So to access any attributes on the actual model instance, just call the method on it.

Current Support

Veneer currently has built in support for ActiveRecord and DataMapper.

Veneer works on a VeneerInterface inner module though so you can easily impelment your adapter without requiring it to be in the veneer repo (although pull requests are welcome)

To use DataMapper or ActiveRecord


require 'veneer/adapters/activerecord'
require 'veneer/adapters/datamapper'

== Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don’t break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.

== Copyright

Copyright © 2009 Daniel Neighman. See LICENSE for details.