ohm_util 0.1

data/examples/one-to-many.rb

@@ -0,0 +1,118 @@
+### 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_equal video.comments.size, 1
+
+  assert audio.comments.include?(audio_comment)
+  assert_equal 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_equal %w(C1 C2 C3 C4 C5),  video.comments.range(0, 4).map(&:body)
+  assert_equal %w(C6 C7 C8 C9 C10), video.comments.range(5, 9).map(&: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://redis.io/commands/zrem) 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).

data/examples/slug.rb

@@ -0,0 +1,149 @@
+### All Kinds of Slugs
+
+# The problem of making semantic URLs have definitely been a prevalent one.
+# There has been quite a lot of solutions around this theme, so we'll discuss
+# a few simple ways to handle slug generation.
+
+#### ID Prefixed slugs
+
+# This is by far the simplest (and most cost-effective way) of generating
+# slugs. Implementing this is pretty simple too.
+
+# Let's first require `Ohm`.
+require "ohm"
+
+# Now let's define our `Post` model, with just a single
+# `attribute` *title*.
+class Post < Ohm::Model
+  attribute :title
+
+  # To make it more convenient, we override the finder syntax,
+  # so doing a `Post["1-my-post-title"]` will in effect just call
+  # `Post[1]`.
+  def self.[](id)
+    super(id.to_i)
+  end
+
+  # This pattern was mostly borrowed from Rails' style of generating
+  # URLs. Here we just concatenate the `id` and a sanitized form
+  # of our title.
+  def to_param
+    "#{id}-#{title.to_s.gsub(/\p{^Alnum}/u, " ").gsub(/\s+/, "-").downcase}"
+  end
+end
+
+# Let's verify our code using the
+# [Cutest](http://github.com/djanowski/cutest)
+# testing framework.
+require "cutest"
+
+# Also we ensure every test run is guaranteed to have a clean
+# *Redis* instance.
+prepare { Ohm.flush }
+
+# For each and every test, we create a post with
+# the title "ID Prefixed Slugs". Since it's the last
+# line of our `setup`, it will also be yielded to
+# each of our test blocks.
+setup do
+  Post.create(:title => "ID Prefixed Slugs")
+end
+
+# Now let's verify the behavior of our `to_param` method.
+# Note that we make it dash-separated and lowercased.
+test "to_param" do |post|
+  assert "1-id-prefixed-slugs" == post.to_param
+end
+
+# We also check that our easier finder syntax works.
+test "finding the post" do |post|
+  assert post == Post[post.to_param]
+end
+
+#### We don't have to code it everytime
+
+# Because of the prevalence, ease of use, and efficiency of this style of slug
+# generation, it has been extracted to a module in
+# [Ohm::Contrib](http://github.com/cyx/ohm-contrib/) called `Ohm::Slug`.
+
+# Let's create a different model to demonstrate how to use it.
+# (Run `[sudo] gem install ohm-contrib` to install ohm-contrib).
+
+# When using `ohm-contrib`, we simply require it, and then
+# directly reference the specific module. In this case, we
+# use `Ohm::Slug`.
+require "ohm/contrib"
+
+class Video < Ohm::Model
+  include Ohm::Slug
+
+  attribute :title
+
+  # `Ohm::Slug` just uses the value of the object's `to_s`.
+  def to_s
+    title.to_s
+  end
+end
+
+# Now to quickly verify that everything works similar to our
+# example above!
+test "video slugging" do
+  video = Video.create(:title => "A video about ohm")
+
+  assert "1-a-video-about-ohm" == video.to_param
+  assert video == Video[video.id]
+end
+
+# That's it, and it works similarly to the example above.
+
+#### What if I want a slug without an ID prefix?
+
+# For this case, we can still make use of `Ohm::Slug`'s ability to
+# make a clean string.
+
+# Let's create an `Article` class which has a single attribute `title`.
+class Article < Ohm::Model
+  include Ohm::Callbacks
+
+  attribute :title
+
+# Now before creating this object, we just call `Ohm::Slug.slug` directly.
+# We also check if the generated slug exists, and repeatedly try
+# appending numbers.
+protected
+  def before_create
+    temp = Ohm::Slug.slug(title)
+    self.id = temp
+
+    counter = 0
+    while Article.exists?(id)
+      self.id = "%s-%d" % [temp, counter += 1]
+    end
+  end
+end
+
+# We now verify the behavior of our `Article` class
+# by creating an article with the same title 3 times.
+test "create an article with the same title" do
+  a1 = Article.create(:title => "All kinds of slugs")
+  a2 = Article.create(:title => "All kinds of slugs")
+  a3 = Article.create(:title => "All kinds of slugs")
+
+  assert a1.id == "all-kinds-of-slugs"
+  assert a2.id == "all-kinds-of-slugs-1"
+  assert a3.id == "all-kinds-of-slugs-2"
+end
+
+#### Conclusion
+
+# Slug generation comes in all different flavors.
+#
+# 1. The first solution is good enough for most cases. The primary advantage
+#    of this solution is that we don't have to check for ID clashes.
+#
+# 2. The second solution may be needed for cases where you must make
+#    the URLs absolutely clean and readable, and you hate having those
+#    number prefixes.
+#
+#    *NOTE:* The example we used for the second solution has potential
+#    race conditions. I'll leave fixing it as an exercise to you.