sohm 0.0.1

data/examples/chaining.rb

@@ -0,0 +1,162 @@
+### Chaining Ohm Sets
+
+#### Doing the straight forward approach
+
+# Let's design our example around the following requirements:
+#
+# 1. a `User` has many orders.
+# 2. an  `Order` can be pending, authorized or captured.
+# 3. a `Product` is referenced by an `Order`.
+
+#### Doing it the normal way
+
+# Let's first require `Ohm`.
+require "ohm"
+
+# A `User` has a `collection` of *orders*. Note that a collection
+# is actually just a convenience, which implemented simply will look like:
+#
+#   def orders
+#     Order.find(user_id: self.id)
+#   end
+#
+class User < Ohm::Model
+  collection :orders, :Order
+end
+
+# The product for our purposes will only contain a name.
+class Product < Ohm::Model
+  attribute :name
+end
+
+# We define an `Order` with just a single `attribute` called `state`, and
+# also add an `index` so we can search an order given its state.
+#
+# The `reference` to the `User` is actually required for the `collection`
+# of *orders* in the `User` declared above, because the `reference` defines
+# an index called `:user_id`.
+#
+# We also define a `reference` to a `Product`.
+class Order < Ohm::Model
+  attribute :state
+  index :state
+
+  reference :user, User
+  reference :product, Product
+end
+
+##### Testing what we have so far.
+
+# For the purposes of this tutorial, we'll use cutest for our test framework.
+require "cutest"
+
+# Make sure that every run of our test suite has a clean Redis instance.
+prepare { Ohm.flush }
+
+# Let's create a *user*, a *pending*, *authorized* and a captured order.
+# We also create two products named *iPod* and *iPad*.
+setup do
+  @user = User.create
+
+  @ipod = Product.create(name: "iPod")
+  @ipad = Product.create(name: "iPad")
+
+  @pending =    Order.create(user: @user, state: "pending",
+                             product: @ipod)
+  @authorized = Order.create(user: @user, state: "authorized",
+                             product: @ipad)
+  @captured =   Order.create(user: @user, state: "captured",
+                             product: @ipad)
+end
+
+# Now let's try and grab all pending orders, and also pending
+# *iPad* and *iPod* ones.
+test "finding pending orders" do
+  assert @user.orders.find(state: "pending").include?(@pending)
+
+  assert @user.orders.find(state: "pending",
+                           product_id: @ipod.id).include?(@pending)
+
+  assert @user.orders.find(state: "pending",
+                           product_id: @ipad.id).empty?
+end
+
+# Now we try and find captured and/or authorized orders.
+test "finding authorized and/or captured orders" do
+  assert @user.orders.find(state: "authorized").include?(@authorized)
+  assert @user.orders.find(state: "captured").include?(@captured)
+
+  results = @user.orders.find(state: "authorized").union(state: "captured")
+
+  assert results.include?(@authorized)
+  assert results.include?(@captured)
+end
+
+#### Creating shortcuts
+
+# You can of course define methods to make that code more readable.
+class User < Ohm::Model
+  def authorized_orders
+    orders.find(state: "authorized")
+  end
+
+  def captured_orders
+    orders.find(state: "captured")
+  end
+end
+
+# And we can now test these new methods.
+test "finding authorized and/or captured orders" do
+  assert @user.authorized_orders.include?(@authorized)
+  assert @user.captured_orders.include?(@captured)
+end
+
+# In most cases this is fine, but if you want to have a little fun,
+# then we can play around with some chainability using scopes.
+
+# Let's require `ohm-contrib`, which we will be using for scopes.
+require "ohm/contrib"
+
+# Include `Ohm::Scope` module and desired scopes.
+class Order
+  include Ohm::Scope
+
+  scope do
+    def pending
+      find(state: "pending")
+    end
+
+    def authorized
+      find(state: "authorized")
+    end
+
+    def captured
+      find(state: "captured")
+    end
+
+    def accepted
+      find(state: "authorized").union(state: "captured")
+    end
+  end
+end
+
+# Ok! Let's put all of that chaining code to good use.
+test "finding pending orders using a chainable style" do
+  assert @user.orders.pending.include?(@pending)
+  assert @user.orders.pending.find(product_id: @ipod.id).include?(@pending)
+
+  assert @user.orders.pending.find(product_id: @ipad.id).empty?
+end
+
+test "finding authorized and/or captured orders using a chainable style" do
+  assert @user.orders.authorized.include?(@authorized)
+  assert @user.orders.captured.include?(@captured)
+
+  assert @user.orders.accepted.include?(@authorized)
+  assert @user.orders.accepted.include?(@captured)
+
+  accepted = @user.orders.accepted
+
+  assert accepted.find(product_id: @ipad.id).include?(@authorized)
+  assert accepted.find(product_id: @ipad.id).include?(@captured)
+end

data/examples/json-hash.rb

@@ -0,0 +1,75 @@
+### Make Peace wih JSON and Hash
+
+#### Why do I care?
+
+# If you've ever needed to build an AJAX route handler, you may have noticed
+# the prevalence of the design pattern where you return a JSON response.
+#
+#     on get, "comments" do
+#       res.write Comment.all.to_json
+#     end
+#
+# `Ohm` helps you here by providing sensible defaults. It's not very popular,
+# but `Ohm` actually has a `to_hash` method.
+
+# Let's start by requiring `ohm` and `ohm/json`.
+require "ohm"
+require "ohm/json"
+
+# Here we define our `Post` model with just a single `attribute` called `title`.
+class Post < Ohm::Model
+  attribute :title
+end
+
+# Now let's load the test framework `cutest` to test our code.
+require "cutest"
+
+# We also call `Ohm.flush` for each test run.
+prepare { Ohm.flush }
+
+# When we successfully create a `Post`, we can see that it returns
+# only the *id* and its value in the hash.
+test "hash representation when created" do
+  post = Post.create(title: "my post")
+
+  assert_equal Hash[id: post.id], post.to_hash
+end
+
+# The JSON representation is actually just `post.to_hash.to_json`, so the
+# same result, only in JSON, is returned.
+test "json representation when created" do
+  post = Post.create(title: "my post")
+
+  assert_equal "{\"id\":\"#{post.id}\"}", post.to_json
+end
+
+#### Whitelisted approach
+
+# Unlike other frameworks which dumps out all attributes by default,
+# `Ohm` favors a whitelisted approach where you have to explicitly
+# declare which attributes you want.
+#
+# By default, only `:id` will be available if the model is persisted.
+
+# Let's re-open our Post class, and add a `to_hash` method.
+class Post
+  def to_hash
+    super.merge(title: title)
+  end
+end
+
+# Now, let's test that the title is in fact part of `to_hash`.
+test "customized to_hash" do
+  post = Post.create(title: "Override FTW?")
+
+  assert_equal Hash[id: post.id, title: post.title], post.to_hash
+end
+
+#### Conclusion
+
+# Ohm has a lot of neat intricacies like this. Some of the things to keep
+# in mind from this tutorial would be:
+#
+# 1. `Ohm` doesn't assume too much about your needs.
+# 2. If you need a customized version, you can always define it yourself.
+# 3. Customization is easy using basic OOP principles.

data/examples/one-to-many.rb

@@ -0,0 +1,124 @@
+### One to Many Ohm style
+
+#### Problem
+
+# Let's say you want to implement a commenting system, and you need to have
+# comments on different models. In order to do this using an RDBMS you have
+# one of two options:
+#
+# 1. Have multiple comment tables per type i.e. VideoComments, AudioComments,
+#    etc.
+# 2. Use a polymorphic schema.
+#
+# The problem with option 1 is that you'll may possibly run into an explosion
+# of tables.
+#
+# The problem with option 2 is that if you have many comments across the whole
+# site, you'll quickly hit the limit on a table, and eventually need to shard.
+
+#### Solution
+
+# In *Redis*, possibly the best data structure to model a comment would be to
+# use a *List*, mainly because comments are always presented within the
+# context of the parent entity, and are typically ordered in a predefined way
+# (i.e. latest at the top, or latest at the bottom).
+#
+
+# Let's start by requiring `Ohm`.
+require "ohm"
+
+# We define both a `Video` and `Audio` model, with a `list` of *comments*.
+class Video < Ohm::Model
+  list :comments, Comment
+end
+
+class Audio < Ohm::Model
+  list :comments, Comment
+end
+
+# The `Comment` model for this example will just contain one attribute called
+# `body`.
+class Comment < Ohm::Model
+  attribute :body
+end
+
+# Now let's require the test framework we're going to use called
+# [cutest](http://github.com/djanowski/cutest)
+require "cutest"
+
+# And make sure that every run of our test suite has a clean Redis instance.
+prepare { Ohm.flush }
+
+# Let's begin testing. The important thing to verify is that
+# video comments and audio comments don't munge with each other.
+#
+# We can see that they don't since each of the `comments` list only has
+# one element.
+test "adding all sorts of comments" do
+  video = Video.create
+
+  video_comment = Comment.create(:body => "First Video Comment")
+  video.comments.push(video_comment)
+
+  audio = Audio.create
+  audio_comment = Comment.create(:body => "First Audio Comment")
+  audio.comments.push(audio_comment)
+
+  assert video.comments.include?(video_comment)
+  assert video.comments.size == 1
+
+  assert audio.comments.include?(audio_comment)
+  assert audio.comments.size == 1
+end
+
+
+#### Discussion
+#
+# As you can see above, the design is very simple, and leaves little to be
+# desired.
+
+# Latest first ordering can simply be achieved by using `unshift` instead of
+# `push`.
+test "latest first ordering" do
+  video = Video.create
+
+  first = Comment.create(:body => "First")
+  second = Comment.create(:body => "Second")
+
+  video.comments.unshift(first)
+  video.comments.unshift(second)
+
+  assert [second, first] == video.comments.to_a
+end
+
+# In addition, since Lists are optimized for doing `LRANGE` operations,
+# pagination of Comments would be very fast compared to doing a LIMIT / OFFSET
+# query in SQL (some sites also use `WHERE id > ? LIMIT N` and pass the
+# previous last ID in the set).
+test "getting paged chunks of comments" do
+  video = Video.create
+
+  20.times { |i| video.comments.push(Comment.create(:body => "C#{i + 1}")) }
+
+  assert %w(C1 C2 C3 C4 C5)      ==  video.comments[0, 4].map(&:body)
+  assert %w(C6 C7 C8 C9 C10)     ==  video.comments[5, 9].map(&:body)
+
+  # ** Range style is also supported.
+  assert %w(C11 C12 C13 C14 C15) ==  video.comments[10..14].map(&:body)
+
+  # ** Also you can just pass in a single number.
+  assert "C16" == video.comments[15].body
+end
+
+#### Caveats
+
+# Sometimes you need to be able to delete comments. For these cases, you might
+# possibly need to store a reference back to the parent entity. Also, if you
+# expect to store millions of comments for a single entity, it might be tricky
+# to delete comments, as you need to manually loop through the entire LIST.
+#
+# Luckily, there is a clean alternative solution, which would be to use a
+# `SORTED SET`, and to use the timestamp (or the negative of the timestamp) as
+# the score to maintain the desired order. Deleting a comment from a
+# `SORTED SET` would be a simple
+# [ZREM](http://code.google.com/p/redis/wiki/ZremCommand) call.

data/examples/philosophy.rb

@@ -0,0 +1,137 @@
+### Internals: Nest and the Ohm Philosophy
+
+#### Ohm does not want to hide Redis from you
+
+# In contrast to the usual philosophy of ORMs in the wild, Ohm actually
+# just provides a basic object mapping where you can safely tuck away
+# attributes and declare grouping of data.
+#
+# Beyond that, Ohm doesn't try to hide Redis, but rather exposes it in
+# a simple way, through key hierarchies provided by the library
+# [Nido](http://github.com/soveran/nido).
+
+# Let's require `Ohm`. We also require `Ohm::Contrib` so we can make
+# use of its module `Ohm::Callbacks`.
+require "ohm"
+require "ohm/contrib"
+
+# Let's quickly declare our `Post` model and include `Ohm::Callbacks`.
+# We define an *attribute* `title` and also *index* it.
+#
+# In addition we specify our `Post` to have a list of *comments*.
+class Post < Ohm::Model
+  include Ohm::Callbacks
+
+  attribute :title
+  index :title
+
+  list :comments, :Comment
+
+  # This is one example of using Redic simple API and
+  # the underlying library `Nido`.
+  def self.latest
+    fetch(redis.call("ZRANGE", key[:latest], 0, -1))
+  end
+
+  protected
+
+  # Here we just quickly push this instance of `Post` to our `latest`
+  # *SORTED SET*. We use the current time as the score.
+  def after_save
+    redis.call("ZADD", model.key[:latest], Time.now.to_i, id)
+  end
+
+  # Since we add every `Post` to our *SORTED SET*, we have to make sure that
+  # we removed it from our `latest` *SORTED SET* as soon as we delete a
+  # `Post`.
+  def after_delete
+    redis.call("ZREM", model.key[:latest], id)
+  end
+end
+
+# Now let's quickly define our `Comment` model.
+class Comment < Ohm::Model
+end
+
+#### Test it out
+
+# For this example, we'll use [Cutest](http://github.com/djanowski/cutest)
+# for our testing framework.
+require "cutest"
+
+# To make it simple, we also ensure that every test run has a clean
+# *Redis* instance.
+prepare do
+  Ohm.flush
+end
+
+# Now let's create a post. `Cutest` by default yields the return value of the
+# block to each and every one of the test blocks.
+setup do
+  Post.create
+end
+
+# We then verify the behavior for our `Post:latest` ZSET. Our created
+# post should automatically be part of `Post:latest`.
+test "created post is inserted into latest" do |post|
+  assert [post.id] == Post.latest.map(&:id)
+end
+
+# And it should automatically be removed from it as soon as we delete our
+# `Post`.
+test "deleting the created post removes it from latest" do |post|
+  post.delete
+
+  assert Post.latest.empty?
+end
+
+# You might be curious what happens when we do `Post.all`. The test here
+# demonstrates more or less what's happening when you do that.
+test "querying Post:all using raw Redis commands" do |post|
+  assert [post.id] == Post.all.ids
+  assert [post] == Post.all.to_a
+end
+
+#### Understanding `post.comments`.
+
+# Let's pop the hood and see how we can do *LIST* operations on our
+# `post.comments` object.
+
+# Getting the current size of our comments is just a wrapper for
+# [LLEN](http://redis.io/commands/LLEN).
+test "checking the number of comments for a given post" do |post|
+  assert_equal 0, post.comments.size
+  assert_equal 0, Post.redis.call("LLEN", post.comments.key)
+end
+
+# Also, pushing a comment to our `post.comments` object is equivalent
+# to doing an [RPUSH](http://redis.io/commands/RPUSH) of its `id`.
+test "pushing a comment manually and checking for its presence" do |post|
+  comment = Comment.create
+
+  Post.redis.call("RPUSH", post.comments.key, comment.id)
+  assert_equal comment, post.comments.last
+
+  post.comments.push(comment)
+  assert_equal comment, post.comments.last
+end
+
+# Now for some interesting judo.
+test "now what if we want to find all Ohm or Redis posts" do
+  ohm = Post.create(title: "Ohm")
+  redis = Post.create(title: "Redis")
+
+  # Finding all *Ohm* or *Redis* posts now will just be a call to
+  # [SUNIONSTORE](http://redis.io/commands/UNIONSTORE).
+  result = Post.find(title: "Ohm").union(title: "Redis")
+
+  # And voila, they have been found!
+  assert_equal [ohm, redis], result.to_a
+end
+
+#### The command reference is your friend
+
+# If you invest a little time reading through all the different
+# [Redis commands](http://redis.io/commands).
+# I'm pretty sure you will enjoy your experience hacking with Ohm, Nido,
+# Redic and Redis a lot more.

data/examples/redis-logging.txt

@@ -0,0 +1,179 @@
+### Understanding Ohm Internals through Logging
+
+#### Benefits
+
+# Ohm is actually a very thin wrapper for Redis, and most of the design
+# patterns implemented in Ohm are based on the prescribed patterns for using
+# Redis.
+#
+# If you take a little time to grok the internals of Ohm and Redis, the more
+# effective you will be in weilding it efficiently.
+
+#### Keys
+#
+# Most key-value stores have standardized on a structured design pattern for
+# organizing data. Let's fire up a console:
+#
+#     >> irb -r ohm -r logger
+#
+#     Ohm.redis.client.logger = Logger.new(STDOUT)
+#
+#     class Post < Ohm::Model
+#       attribute :title
+#     end
+#
+#     Post.create(:title => "Grokking Ohm")
+#
+# After executing `Post.create(...)`, you'll see a lot of output from the
+# logger. Let's go through every line in detail.
+
+#### Post.create
+
+# *Generate a new `Post:id`.*
+INCR Post:id
+
+# *Lock `Post:2`
+# (see [SETNX](http://code.google.com/p/redis/wiki/SetnxCommand)
+# for an explanation of the locking design pattern).
+SETNX Post:2:_lock 1285060009.409451
+
+# *Add the newly generated ID 2 to the `Post:all` SET.*
+SADD Post:all 2
+
+# *Start transaction.*
+MULTI
+
+# *Delete HASH `Post:2`.*
+DEL Post:2
+
+# *Set the attributes.*
+HMSET Post:2 title "Grokking Ohm"
+
+# *End transaction.*
+EXEC
+
+# *Release the lock.*
+DEL Post:2:_lock
+
+#### Sets and Lists
+
+# Let's do a little `SET` and `LIST` manipulation and see what Ohm does.
+# Here's the code for this section:
+#
+#     class User < Ohm::Model
+#       collection :posts, Post
+#     end
+#
+#     class Post < Ohm::Model
+#       attribute :title
+#       reference :user, User
+#
+#       list :comments, Comment
+#     end
+#
+#     class Comment < Ohm::Model
+#     end
+
+#### User.create
+
+# *Generate a new ID for the `User`.*
+INCR User:id
+
+# *Lock User:9.*
+SETNX User:9:_lock 1285061032.174834
+
+# *Add this new user to the SET User:all.*
+SADD User:all 9
+
+# *Release the lock.*
+DEL User:9:_lock
+
+#### Post.create(:title => "Foo", :user => User.create)
+
+# *Generate an ID for this Post*
+INCR Post:id
+
+# *Lock Post:3*
+SETNX Post:3:_lock 1285061032.180314
+
+# *Add the ID 3 to the SET Post:all*
+SADD Post:all 3
+
+# *Start transaction*
+MULTI
+
+# *Remove existing Post:3 HASH*
+DEL Post:3
+
+# *Assign the attributes to Post:3*
+HMSET Post:3 title Foo user_id 9
+
+# *End transaction*
+EXEC
+
+# *Add the ID of this post to the SET index (more on this below)*
+SADD Post:user_id:OQ== 3
+
+# *Book keeping for Post:3 indices*
+SADD Post:3:_indices Post:user_id:OQ==
+
+# *Release lock*
+DEL Post:3:_lock
+
+#### post.comments << Comment.create
+
+# *Generate an ID for this comment*
+INCR Comment:id
+
+# *Lock Comment:1*
+SETNX Comment:1:_lock 1285061034.335855
+
+# *Add this comment to the SET Comment:all*
+SADD Comment:all 1
+
+# *Release lock*
+DEL Comment:1:_lock
+
+# *Append the comment to the LIST Post:3:comments*
+RPUSH Post:3:comments 1
+
+#### Understanding indexes
+
+#     reference :user, User
+#
+# is actually more or less the same as:
+#
+#     attribute :user_id
+#     index :user_id
+#
+#     def user
+#       User[user_id]
+#     end
+#
+#     def user_id=(user_id)
+#       self.user_id = user_id
+#     end
+#
+# To further explain the [example above](#section-29), let's
+# run through the commands that was issued. Remember that
+# we had a *user_id* of *9* and a *post_id* of *3*.
+
+# *OQ== is Base64 of *9*, with newlines removed. The post_id 3 is added
+# effectively to Post:user_id:9, if we ignore the encoding.*
+SADD Post:user_id:OQ== 3
+
+# *Just keep track that Post:user_id:OQ== was created*
+SADD Post:3:_indices Post:user_id:OQ==
+
+# *Get all *posts* with user_id *9**
+SMEMBERS Post:user_id:OQ==
+
+#### What's next?
+
+# We tackled a fair bit amount regarding Ohm internals. More or less this is
+# the foundation of everything else found in Ohm, and other code are just
+# built around the same fundamental concepts.
+#
+# If there's anything else you want to know, you can hang out on #ohm at
+# irc.freenode.net, or you can visit the
+# [Ohm google group](http://groups.google.com/group/ohm-ruby).