ohm 1.3.0 → 1.3.1

data/examples/json-hash.rb

@@ -0,0 +1,102 @@
+### 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.
+#
+#     post "/comments.json" do
+#       comment = Comment.create(params[:comment])
+#       comment.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 `json`. In ruby 1.9, `json` is
+# actually part of the standard library, so you don't have to install a gem
+# for it. For ruby 1.8.x, a simple `[sudo] gem install json` will do it.
+require "ohm"
+require "json"
+
+# Here we define our `Post` model with just a single `attribute` called
+# `title`.
+#
+# We also define a validation, asserting the presence of the `title`.
+class Post < Ohm::Model
+  attribute :title
+
+  def validate
+    assert_present :title
+  end
+end
+
+# Now let's load the test framework `cutest` to verify our code. We
+# also call `Ohm.flush` for each test run.
+require "cutest"
+
+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({ :id => "1" } == 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("{\"id\":\"1\"}" == post.to_json)
+end
+
+# Let's try and do the opposite now -- that is, purposely try and create
+# an invalid `Post`. We can see that it returns the `errors` of the
+# `Post`, because we added an `assert_present :title` in our code above.
+test "hash representation when validation failed" do
+  post = Post.create
+
+  assert({ :errors => [[:title, :not_present]]} == post.to_hash)
+end
+
+# As is the case for a valid record, the JSON representation is
+# still equivalent to `post.to_hash.to_json`.
+test "json representation when validation failed" do
+  post = Post.create
+
+  assert("{\"errors\":[[\"title\",\"not_present\"]]}" == post.to_json)
+end
+
+#### Whitelisted approach
+
+# Unlike in 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` and `:errors` will be available, depending if
+# it was successfully saved or if there were validation errors.
+
+# 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({ :id => "1", :title => "Override FTW?" } == 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,149 @@
+### 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
+# [Nest](http://github.com/soveran/nest).
+
+# 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 the underlying library `Nest` directly.
+  # As you can see, we can easily drop down to using raw *Redis* commands,
+  # in this case we use
+  # [ZREVRANGE](http://code.google.com/p/redis/wiki/ZrangeCommand).
+  #
+  # *Note:* Since `Ohm::Model` defines a `to_proc`, we can use the `&` syntax
+  # together with `map` to make our code a little more terse.
+  def self.latest
+    key[:latest].zrevrange(0, -1).map(&Post)
+  end
+
+  # Here we just quickly push this instance of `Post` to our `latest`
+  # *SORTED SET*. We use the current time as the score.
+protected
+  def after_save
+    self.class.key[:latest].zadd(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`.
+  #
+  # In this case we use the raw *Redis* command
+  # [ZREM](http://code.google.com/p/redis/wiki/ZremCommand).
+  def after_delete
+    self.class.key[:latest].zrem(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 { Ohm.flush }
+
+# Now let's create Post. `Cutest` by default yields the return value of the
+# block to each and every one of the test blocks.
+setup { Post.create }
+
+# 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 |p|
+  assert [p.id] == Post.key[:latest].zrange(0, -1)
+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 |p|
+  p.delete
+
+  assert Post.key[:latest].zrange(0, -1).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 |p|
+  assert [p.id] == Post.key[:all].smembers
+
+  assert [p] == Post.key[:all].smembers.map(&Post)
+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://code.google.com/p/redis/wiki/LlenCommand).
+test "checking the number of comments for a given post" do |p|
+  assert 0 == p.comments.key.llen
+  assert 0 == p.comments.size
+end
+
+# Also, pushing a comment to our `post.comments` object is equivalent
+# to doing an [RPUSH](http://code.google.com/p/redis/wiki/RpushCommand)
+# of its `id`.
+test "pushing a Comment manually and checking for its presence" do |p|
+  comment = Comment.create
+
+  p.comments.key.rpush(comment.id)
+  assert [comment.id] == p.comments.key.lrange(0, -1)
+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")
+
+  # Let's first choose an arbitrary key name to hold our `Set`.
+  ohm_redis = Post.key.volatile["ohm-redis"]
+
+  # A *volatile* key just simply means it will be prefixed with a `~`.
+  assert "~:Post:ohm-redis" == ohm_redis
+
+  # Finding all *Ohm* or *Redis* posts now will just be a call to
+  # [SUNIONSTORE](http://code.google.com/p/redis/wiki/SunionstoreCommand)
+  # on our *volatile* `ohm-redis` key.
+  ohm_redis.sunionstore(
+    Post.index_key_for(:title, "Ohm"),
+    Post.index_key_for(:title, "Redis")
+  )
+
+  # And voila, they have been found!
+  assert [ohm.id, redis.id] == ohm_redis.smembers.sort
+end
+
+#### The command reference is your friend
+
+# If you invest a little time reading through all the different
+# [Redis commands](http://code.google.com/p/redis/wiki/CommandReference),
+# I'm pretty sure you will enjoy your experience hacking with Ohm, Nest 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).