ohm 0.0.15 → 0.0.16

data/README.markdown

@@ -3,6 +3,7 @@ Ohm ॐ
 
 Object-hash mapping library for Redis.
 
+
 Description
 -----------
 
@@ -11,17 +12,48 @@ Ohm is a library that allows to store an object in
 database. It includes an extensible list of validations and has very
 good performance.
 
-Usage
------
 
-    require 'ohm'
+Getting started
+---------------
+
+Install [Redis](http://code.google.com/p/redis/). On most platforms
+it's as easy as grabbing the sources, running make and then putting the
+`redis-server` binary in the PATH.
+
+Once you have it installed, you can execute `redis-server` and it will
+run on `localhost:6379` by default. Check the `redis.conf` file that comes
+with the sources if you want to change some settings.
+
+If you don't have Ohm, try this:
+
+    $ sudo gem install ohm
+
+Now, in an irb session you can test the Redis adapter directly:
+
+    >> require "ohm"
+    => true
+    >> Ohm.connect
+    => []
+    >> Ohm.redis.set "Foo", "Bar"
+    => "OK"
+    >> Ohm.redis.get "Foo"
+    => "Bar"
+
+
+Models
+------
 
-    Ohm.connect
+Ohm's purpose in life is to map objects to a key value datastore. It
+doesn't need migrations or external schema definitions. Take a look at
+the example below:
+
+### Example
 
     class Event < Ohm::Model
       attribute :name
       set :participants
       list :comments
+      counter :votes
 
       index :name
 
@@ -30,53 +62,183 @@ Usage
       end
     end
 
-    event = Event.create(:name => "Ruby Tuesday")
-    event.participants << "Michel Martens"
-    event.participants << "Damian Janowski"
-    event.participants.all #=> ["Damian Janowski", "Michel Martens"]
+This example shows some basic features, like attribute declarations and
+validations. Keep reading to find out what you can do with models.
 
-    event.comments << "Very interesting event!"
-    event.comments << "Agree"
-    event.comments.all #=> ["Very interesting event!", "Agree"]
 
-    another_event = Event.new
-    another_event.valid?    #=> false
-    another_event.errors    #=> [[:name, :nil]]
+Attribute types
+---------------
 
-    another_event.name = ""
-    another_event.valid?    #=> false
-    another_event.errors    #=> [[:name, :empty]]
+Ohm::Model provides four attribute types: `attribute`, `set`, `list` and
+`counter`.
 
-    another_event.name = "Ruby Lunch"
-    another_event.create    #=> true
+### attribute
 
-Installation
-------------
+An `attribute` is just any value that can be stored as a string. In the
+example above, we used this field to store the Event's `name`. You can
+use it to store numbers, but be aware that Redis will return a string
+when you retrieve the value.
 
-    $ sudo gem install ohm
+### set
+
+A `set` in Redis is an unordered list, with an external behavior similar
+to that of Ruby arrays, but optimized for faster membership lookups.
+It's used internaly by Ohm to keep track of the instances of each model
+and for generating and maintaining indexes.
+
+### list
+
+A `list` is like an array in Ruby. It's perfectly suited for queues and
+for keeping elements in order.
 
-License
+### counter
+
+A `counter` is like a regular attribute, but the direct manipulation
+of the value is not allowed. You can retrieve, increase or decrease
+the value, but you can not assign it. In the example above, we used a
+counter attribute for tracking votes. As the incr and decr operations
+are atomic, you can rest assured a vote won't be counted twice.
+
+
+Indexes
 -------
 
-Copyright (c) 2009 Michel Martens and Damian Janowski
-
-Permission is hereby granted, free of charge, to any person
-obtaining a copy of this software and associated documentation
-files (the "Software"), to deal in the Software without
-restriction, including without limitation the rights to use,
-copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the
-Software is furnished to do so, subject to the following
-conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+An index is a set that's handled automatically by Ohm. For any index declared,
+Ohm maintains different sets of objects ids for quick lookups.
+
+For example, in the example above, the index on the name attribute will
+allow for searches like Event.find(:name, "some value").
+
+You can also declare an index on multiple colums, like this:
+
+    index [:name, :company]
+
+Note that the `find` method and the `assert_unique` validation need a
+corresponding index to exist.
+
+
+Validations
+-----------
+
+Before every save, the `validate` method is called by Ohm. In the method
+definition you can use assertions that will determine if the attributes
+are valid. Nesting assertions is a good practice, and you are also
+encouraged to create your own assertions. You can trigger validations at
+any point by calling `valid?` on a model instance.
+
+
+Assertions
+-----------
+
+Ohm ships with some basic assertions. Check Ohm::Validations to see
+the method definitions.
+
+### assert
+
+The `assert` method is used by all the other assertions. It pushes the
+second parameter to the list of errors if the first parameter evaluates
+to false.
+
+    def assert(value, error)
+      value or errors.push(error) && false
+    end
+
+### assert_present
+
+Checks that the given field is not nil or empty. The error code for this
+assertion is :not_present.
+
+    def assert_present(att, error = [att, :not_present])
+      assert(!send(att).to_s.empty?, error)
+    end
+
+### assert_format
+
+Checks that the given field matches the provided format. The error code
+for this assertion is :format.
+
+    def assert_format(att, format, error = [att, :format])
+      if assert_present(att, error)
+        assert(send(att).to_s.match(format), error)
+      end
+    end
+
+### assert_numeric
+
+Checks that the given field holds a number as a Fixnum or as a string
+representation. The error code for this assertion is :not_numeric.
+
+    def assert_numeric(att, error = [att, :not_numeric])
+      if assert_present(att, error)
+        assert_format(att, /^\d+$/, error)
+      end
+    end
+
+### assert_unique
+
+Validates that the attribute or array of attributes are unique.
+For this, an index of the same kind must exist. The error code is
+:not_unique.
+
+    def assert_unique(attrs)
+      index_key = index_key_for(Array(attrs), read_locals(Array(attrs)))
+      assert(db.scard(index_key).zero? || db.sismember(index_key, id), [Array(attrs), :not_unique])
+    end
+
+
+Errors
+------
+
+When an assertion fails, the error report is added to the errors array.
+Each error report contains two elements: the field where the assertion
+was issued and the error code.
+
+### Validation example
+
+Given the following example:
+
+    def validate
+      assert_present :foo
+      assert_numeric :bar
+      assert_format :baz, /^\d{2}$/
+      assert_unique :qux
+    end
+
+If all the assertions fail, the following errors will be present:
+
+    obj.errors #=> [[:foo, :not_present], [:bar, :not_numeric], [:baz, :format], [[:qux], :not_unique]]
+
+Note that the error for assert_unique wraps the field in an array.
+The purpose for this is to standardize the format for both single and
+multicolumn indexes.
+
+
+Presenting errors
+-----------------
+
+Unlike other ORMs, that define the full error messages in the model
+itself, Ohm encourages you to define the error messages outside. If
+you are using Ohm in the context of a web framework, the views are the
+proper place to write the error messages.
+
+Ohm provides a presenter that helps you in this quest. The basic usage
+is as follows:
+
+    error_messages = @model.errors.present do |e|
+      e.on [:name, :not_present], "Name must be present"
+      e.on [:account, :not_present], "You must supply an account"
+    end
+
+    error_messages #=> ["Name must be present", "You must supply an account"]
+
+Having the error message definitions in the views means you can use any
+sort of helpers. You can also use blocks instead of strings for the
+values. The result of the block is used as the error message:
+
+    error_messages = @model.errors.present do |e|
+      e.on [:email, :not_unique] do
+        "The email #{@model.email} is already registered."
+      end
+    end
+
+    error_messages #=> ["The email foo@example.com is already registered."]

data/Rakefile

@@ -1,9 +1,3 @@
-require "rake/testtask"
-
-task :default => :test
-
-desc 'Run all tests'
-Rake::TestTask.new(:test) do |t|
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
+task :default do
+  exec "thor ohm:test"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ohm
 version: !ruby/object:Gem::Version 
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors: 
 - Michel Martens
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-30 00:00:00 -03:00
+date: 2009-08-04 00:00:00 -03:00
 default_executable: 
 dependencies: []
 
@@ -34,15 +34,13 @@ files:
 - test/all_tests.rb
 - test/benchmarks.rb
 - test/connection_test.rb
-- test/db/dump.rdb
-- test/db/redis.pid
 - test/errors_test.rb
 - test/indices_test.rb
 - test/model_test.rb
 - test/redis_test.rb
-- test/test.conf
 - test/test_helper.rb
 - test/validations_test.rb
+- test/test.conf
 has_rdoc: true
 homepage: http://github.com/soveran/ohm
 licenses: []
@@ -67,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: ohm
-rubygems_version: 1.3.4
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: Object-hash mapping library for Redis.

data/test/db/redis.pid

@@ -1 +0,0 @@
-39163