easyredis 0.0.1

data/Manifest

@@ -0,0 +1,6 @@
+Manifest
+README.md
+Rakefile
+lib/easyredis.rb
+tests/benchmark.rb
+tests/test.rb

data/README.md

@@ -0,0 +1,73 @@
+# EasyRedis
+
+EasyRedis is a simple ruby framework designed to make using Redis as a database simpler.
+
+Redis is a very fast key-value store that supports data structures like lists, (sorted) sets, and hashes, but because of its simplicity, using Redis to store traditional database data can be somewhat tedious. EasyRedis streamlines this process.
+
+## Installation
+
+You can get the source with git:
+
+    $ git clone git://github.com/alecbenzer/easyredis.git
+
+or just download and extract a tar archive with the Downloads button.
+
+Once you have the source, run:
+
+    $ rake
+    $ gem install pkg/easyredis-x.x.x.gem
+
+Where x.x.x is the current version number.
+
+## Basics
+
+First, create a simple model:
+
+    require 'easyredis'
+
+    class Post < EasyRedis::Model
+      field :title
+      field :body
+    end
+
+    EasyRedis.connect
+
+This creates a Post model and connects to a redis server running on localhost on the default port (you can pass options to EasyRedis.connect like you would to Redis.new)
+
+We can now make post objects:
+
+    p = Post.new
+    p.title = "My First Post"
+    p.body = "This is my very first post!"
+
+Posts are automatically given ids that we can then use to retrive them:
+
+    id = p.id
+    p = Post[id]  # or Post.find(id)
+    p.title  # => "My First Post"
+
+We also get a created_at field for free that we can sort by.
+
+    p.created_at  # a ruby Time object
+    Post.all  # get all posts, ordered by creation time
+    Post.all :order => :desc  # specifying an order option
+    
+## Searching and Sorting
+
+We can also tell EasyRedis to optimize sorting and searching on certain fields. If we had defined Post as:
+
+    class Post < EasyRedis::Model
+      field :title
+      field :body
+
+      sort_on :title
+    end
+
+We can now sort our posts by title:
+
+    Post.sort_by :title, :order => :desc
+
+And also search:
+
+    Post.search_by(:title,"A common title")  # all posts with this title
+    Post.find_by(:title,"My First Post")  # just one post

data/Rakefile

@@ -0,0 +1,100 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+# spec = Gem::Specification.new do |s|
+#   s.platform = Gem::Platform::RUBY
+#   s.name = "easyredis"
+#   s.version = "0.0.1"
+#   s.author = "Alec Benzer"
+#   s.email = "alecbenzer@gmail.com"
+#   s.homepage = "https://github.com/alecbenzer/easyredis"
+#   s.summary = "simple framework designed to make using redis as a database simpler"
+#   s.files = FileList['lib/*.rb','test/*'].to_a
+#   s.require_path = "lib"
+#   s.test_files = Dir.glob('tests/*.rb')
+#   s.has_rdoc = true
+#   s.add_dependency("redis")
+#   s.add_dependency("activesupport")
+# end
+# 
+# Rake::GemPackageTask.new(spec) do |pkg|
+#   pkg.need_tar = true
+# end
+# 
+# task :default => "pkg/#{spec.name}-#{spec.version}.gem" do
+#   puts "generated latest version"
+# end
+
+Echoe.new('easyredis','0.0.1') do |p|
+  p.description = "simple framework designed to make using redis as a database simpler"
+  p.url = "https://github.com/alecbenzer/easyredis"
+  p.author = "Alec Benzer"
+  p.email = "alecbezer @nospam@ gmail.com"
+  p.ignore_pattern = ["*.rdb"]
+  p.development_dependencies = ["redis","activesupport"]
+end
+
+
+require 'benchmark'
+require './tests/test'
+
+$names = ["Bill","Bob","John","Jack","Alec","Mark","Nick","Evan","Eamon","Joe","Vikram"]
+
+def rand_name
+  $names[rand*$names.size]
+end
+
+namespace :bm do
+  task :clear do
+    count = Man.count
+
+    puts "destroying #{$count} previous entries"
+    Benchmark.bm do |bm|
+      bm.report { Man.destroy_all }
+    end
+  end
+
+  task :add do
+    count = ENV["count"] ? ENV["count"].to_i : 25000
+    puts "adding #{count} new entries"
+    Benchmark.bm do |bm|
+      bm.report { count.times { m = Man.new ; m.name = rand_name } }
+    end
+  end
+
+  task :populate => [:clear, :add]
+
+  task :sort do
+    puts "sorting #{Man.count} entries by name"
+    Benchmark.bm do |bm|
+      #bm.report("ruby:") { Man.all.sort_by { |m| m.name } }
+      #bm.report("redis:") { Man.sort_by(:name) }
+      bm.report { Man.sort_by(:name) }
+    end
+  end
+
+  task :search do
+    puts "searching #{Man.count} entries by a particular name"
+    Benchmark.bm do |bm|
+      name = rand_name
+      #bm.report("ruby:") { Man.all.select {|m| m.name == name} }
+      #bm.report("redis:") { Man.search_by(:name,name) }
+      bm.report { Man.search_by(:name,name) }
+    end
+  end
+
+  task :find do
+    puts "finding one of #{Man.count} entry by name"
+    Benchmark.bm do |bm|
+      name = rand_name
+      #bm.report("redis:") { Man.find_by(:name,name) }
+      bm.report { Man.find_by(:name,name) }
+    end
+  end
+
+end
+
+task :doc do
+  puts `rdoc lib/ --title "EasyRedis"`
+end

data/easyredis.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{easyredis}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Alec Benzer"]
+  s.date = %q{2011-02-05}
+  s.description = %q{simple framework designed to make using redis as a database simpler}
+  s.email = %q{alecbezer @nospam@ gmail.com}
+  s.extra_rdoc_files = ["README.md", "lib/easyredis.rb"]
+  s.files = ["Manifest", "README.md", "Rakefile", "lib/easyredis.rb", "tests/benchmark.rb", "tests/test.rb", "easyredis.gemspec"]
+  s.homepage = %q{https://github.com/alecbenzer/easyredis}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Easyredis", "--main", "README.md"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{easyredis}
+  s.rubygems_version = %q{1.5.0}
+  s.summary = %q{simple framework designed to make using redis as a database simpler}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<redis>, [">= 0"])
+      s.add_development_dependency(%q<activesupport>, [">= 0"])
+    else
+      s.add_dependency(%q<redis>, [">= 0"])
+      s.add_dependency(%q<activesupport>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<redis>, [">= 0"])
+    s.add_dependency(%q<activesupport>, [">= 0"])
+  end
+end

data/lib/easyredis.rb

@@ -0,0 +1,348 @@
+# EasyRedis is a simple ruby framework designed to make using Redis as a database simpler.
+#
+# Redis is a very fast key-value store that supports data structures like lists, (sorted) sets, and hashes, but because of its simplicity, using Redis to store traditional database data can be somewhat tedious. EasyRedis streamlines this process.
+#
+# Author:: Alec Benzer (mailto:alecbenzer@gmail.com)
+
+
+require 'redis'
+require 'set'
+require 'active_support/inflector'
+
+
+# main EasyRedis module which
+# holds all classes and helper methods
+module EasyRedis
+  
+  # generate a 'score' for a string
+  # used for storing it in a sorted set
+  def self.string_score(str)
+    str = str.downcase
+    mult = 1.0
+    scr = 0.0
+    str.each_byte do |b|
+      mult /= 27
+      scr += (b-'a'.ord+1)*mult
+    end
+    scr
+  end
+
+  # gets a score for a generic object
+  #
+  # Uses EasyRedis#string_score if the object is a string,
+  # and just returns the object otherwise (presumably its a number)
+  def self.score(obj)
+    if obj.is_a? String
+      string_score(obj)
+    else
+      obj
+    end
+  end
+
+  # access the redis object
+  def self.redis
+    @redis
+  end
+
+  # connect to a redis server
+  def self.connect(options = {})
+    @redis = Redis.new(options)
+  end
+
+  # exception that indicates that the given field has not been indexed for sorting/searching
+  class FieldNotSortable < RuntimeError
+    def initialize(field)
+      @message = "field '#{field.to_s}' not sortable"
+    end
+    
+    def to_s
+      @message
+    end
+  end
+
+  # exception that indicated an unknown ordering option was encountered
+  class UnknownOrderOption < RuntimeError
+    def initialize(opt)
+      @message = "unknown order option '#{opt}'"
+    end
+
+    def to_s
+      @message
+    end
+  end
+
+  # class representing a sort
+  class Sort
+    include Enumerable
+
+    # initialize the sort with a specific field, ordering option, and model
+    def initialize(field,order,klass)
+      raise EasyRedis::FieldNotSortable, field  unless klass.sortable?(field) 
+      raise EasyRedis::UnknownOrderOption, order  unless [:asc,:desc].member? order
+      @field = field
+      @order = order
+      @klass = klass
+    end
+
+    # access elements in this sort
+    #
+    # Work's like ruby's Array#[]. It can take a specific index, a range, or an offset, amount pair.
+    # Calling this method will actually query the redis server for ids
+    def [](index,limit=nil)
+      if limit
+        offset = index
+        self[offset...(offset+limit)]
+      elsif index.is_a? Range
+        a = index.begin
+        b = index.end
+        b -= 1 if index.exclude_end?
+        ids = []
+        if @order == :asc
+          ids = EasyRedis.redis.zrange(@klass.sort_prefix(@field),a,b)
+        elsif @order == :desc
+          ids = EasyRedis.redis.zrevrange(@klass.sort_prefix(@field),a,b)
+        end
+        ids.map{|i|@klass.new(i)}
+      elsif index.is_a? Integer
+        self[index..index].first
+      end
+    end
+
+    # iterate through all members of this sort
+    def each
+      self[0..-1].each { |o| yield o }
+    end
+
+    # return the number of elements in this sort
+    #
+    # As of now, idential to the Model's #count method.
+    # This method is explicility defined here to overwrite the default one in Enumerable, which iterates through all the entries to count them
+    def count
+      EasyRedis.zcard(@klass.sort_prefix(@field))
+    end
+
+    # return the fist element of this sort, or the first n elements, if n is given
+    def first(n = nil)
+      if n
+        self[0,n]
+      else
+        self[0]
+      end
+    end
+
+    def inspect
+      "#<EasyRedis::Sort model=#{@klass.name}, field=#{@field.to_s}, order=#{@order.to_s}>"
+    end
+
+  end
+
+
+  # class representing a data model
+  # you want to store in redis
+  class Model
+
+    # add a field to the model
+    def self.field(name)
+      name = name.to_s
+      getter = name
+      setter = name + "="
+      instance_var = '@' + name
+
+      define_method getter.to_sym do
+        prev = instance_variable_get(instance_var)
+        if prev
+          prev
+        else
+          instance_variable_set(instance_var,Marshal.load(EasyRedis.redis.hget(key_name,name)))
+        end
+      end
+
+      define_method setter.to_sym do |val|
+        EasyRedis.redis.hset(key_name,name,Marshal.dump(val))
+        instance_variable_set(instance_var,val)
+
+        if @@sorts.member? name.to_sym
+          # score = val.is_a?(String) ? EasyRedis.string_score(val) : val
+          EasyRedis.redis.zadd(sort_prefix(name),EasyRedis.score(val),@id)
+        end
+      end
+    end
+
+    # index a field to be sorted/searched
+    def self.sort_on(field)
+      @@sorts ||= []
+      @@sorts << field.to_sym
+    end
+
+    # returns number of instances of this model
+    def self.count
+      EasyRedis.redis.zcard(prefix.pluralize)
+    end
+
+    # get all instances of this model
+    # ordered by creation time
+    def self.all(options = {:order => :asc})
+      self.sort_by :created_at, options
+    end
+
+    # find an instance of this model based on its id
+    def self.find(id)
+      if EasyRedis.redis.zscore(prefix.pluralize,id)
+        new(id)
+      else
+        nil
+      end
+    end
+
+    # alias for Model#find
+    def self.[](id)
+      find(id)
+    end
+
+    # get all entries where field matches val
+    def self.search_by(field, val, options = {})
+      raise EasyRedis::FieldNotSortable, field unless @@sorts.member? field.to_sym
+      scr = EasyRedis.score(val)
+      # options[:limit] = [0,options[:limit]] if options[:limit]
+      ids = EasyRedis.redis.zrangebyscore(sort_prefix(field),scr,scr,proc_options(options))
+      ids.map{|i| new(i) }
+    end
+    
+    # get the first entry where field matches val
+    def self.find_by(field,val)
+      search_by(field,val,:limit => 1).first
+    end
+
+    # get all entries, sorted by the given field
+    def self.sort_by(field,options = {:order => :asc})
+      EasyRedis::Sort.new(field,options[:order],self)
+    end
+
+    # gives all values for the given field that begins with str
+    #
+    # This method is currently iterates through all existing entries. It is therefore very slow and should probably not be used at this time.
+    def self.matches(field,str)
+      scr = EasyRedis.score(str)
+      a,b = scr, scr+1/(27.0**str.size)
+      ids = EasyRedis.redis.zrangebyscore(sort_prefix(field), "#{a}", "(#{b}")
+      s = Set.new  
+      ids.each{|i| s << new(i).send(field.to_s) }
+      s.to_a
+    end
+
+    # searches for all entries where field begins with str
+    #
+    # works with string fields that have been indexed with sort_on
+    def self.match(field,str, options = {})
+      raise EasyRedis::FieldNotSortable, filename unless @@sorts.member? field
+      scr = EasyRedis.score(str)
+      a,b = scr, scr+1/(27.0**str.size)
+      ids = EasyRedis.redis.zrangebyscore(sort_prefix(field), "#{a}", "(#{b}", proc_options(options))
+      ids.map{|i| new(i)}
+    end
+
+    # indicates whether field has been indexed with sort_on
+    def self.sortable?(field)
+      @@sorts.member? field or field.to_sym == :created_at
+    end
+
+    # destroy all instances of this model
+    def self.destroy_all
+      all.each {|x| x.destroy}
+      @@sorts.each {|field| EasyRedis.redis.del(sort_prefix(field)) }
+      EasyRedis.redis.del(prefix.pluralize)
+      EasyRedis.redis.del(prefix + ":next_id")
+    end
+
+
+    # the id of this entry
+    attr_reader :id
+
+    # create a new instance of this model
+    #
+    # If no id is passed, one is generated for you.
+    # Otherwise, sets the id field to the passed id, but does not check to see if it is a valid id for this model.
+    # Users should use Model#find or Model#[] when retiving models by id, as these check for valid ids.
+    def initialize(id=nil)
+      if id
+        @id = id
+      else
+        @id = EasyRedis.redis.incr(prefix + ':next_id')
+        EasyRedis.redis.zadd(prefix.pluralize,Time.now.to_i,@id)
+        @id
+      end
+    end
+
+    # get the creation time of an entry
+    def created_at
+      Time.at(EasyRedis.redis.zscore(prefix.pluralize,@id).to_i)
+    end
+
+    # directly access a field of this entry's redis hash
+    #
+    # note that you cannot access created_at or id with these methods
+    def [](field)
+      EasyRedis.redis.hget(key_name,field)
+    end
+    
+    # directly change a field of this entry's redis hash
+    #
+    # note that you cannot access created_at or id with these methods
+    def []=(field,val)
+      if val
+        EasyRedis.redis.hset(key_name,field,val)
+      else
+        EasyRedis.redis.hdel(key_name,field)
+      end
+    end
+
+    # remove the entry
+    def destroy
+      EasyRedis.redis.zrem(prefix.pluralize,@id)
+      EasyRedis.redis.del(key_name)
+    end
+
+    # returns the key name of this entry's redis hash  
+    def key_name
+      prefix + ':' + @id.to_s
+    end
+
+    def inspect
+      "#<#{self.class.name}:#{@id}>"
+    end
+
+
+    private 
+
+    def self.get_temp_key
+      i = EasyRedis.redis.incr prefix.pluralize + ':next_tmp_id'
+      "#{name}:tmp_#{i}"
+    end
+
+    def self.proc_options(options)
+      opts = {}
+      opts[:limit] = [0,options[:limit]] if options[:limit]
+      opts
+    end
+
+    def self.prefix
+      self.name.downcase
+    end
+
+    def self.sort_prefix(field)
+      if field == :created_at
+        prefix.pluralize
+      else
+        prefix.pluralize + ':sort_' + field.to_s
+      end
+    end
+
+    def prefix
+      self.class.prefix
+    end
+
+    def sort_prefix(field)
+      self.class.sort_prefix(field)
+    end
+  end
+end

data/tests/benchmark.rb

@@ -0,0 +1,44 @@
+require './tests/test'
+require 'benchmark'
+
+$names = ["Bill","Bob","John","Jack","Alec","Mark","Nick","Evan","Eamon","Joe","Vikram"]
+
+def rand_name
+  $names[rand*$names.size]
+end
+
+$count = 0
+$num_add = ARGV[0] ? ARGV[0].to_i : 50000 
+
+puts "counting entries"
+Benchmark.bm(7) do |bm|
+  bm.report { $count = Man.count }
+end
+puts
+
+puts "destroying #{$count} previous entries"
+Benchmark.bm(7) do |bm|
+  bm.report { Man.destroy_all }
+end
+puts
+
+puts "adding #{$num_add} new entries"
+Benchmark.bm(7) do |bm|
+  bm.report { $num_add.times { m = Man.new ; m.name = rand_name } }
+end
+puts
+
+puts "sorting by name"
+Benchmark.bm(7) do |bm|
+  bm.report("ruby:") { Man.all.sort_by { |m| m.name } }
+  bm.report("redis:") { Man.sort_by(:name) }
+end
+puts
+
+puts "finding all entries by a particular name"
+Benchmark.bm(7) do |bm|
+  name = rand_name
+  bm.report("ruby:") { Man.all.select {|m| m.name == name} }
+  bm.report("redis:") { Man.search_by(:name,name) }
+end
+puts

data/tests/test.rb

@@ -0,0 +1,10 @@
+require './lib/easyredis'
+
+class Man < EasyRedis::Model
+  field :name
+  field :friend
+
+  sort_on :name
+end
+
+EasyRedis.connect

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: easyredis
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Alec Benzer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-05 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: redis
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: simple framework designed to make using redis as a database simpler
+email: alecbezer @nospam@ gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+- lib/easyredis.rb
+files: 
+- Manifest
+- README.md
+- Rakefile
+- lib/easyredis.rb
+- tests/benchmark.rb
+- tests/test.rb
+- easyredis.gemspec
+has_rdoc: true
+homepage: https://github.com/alecbenzer/easyredis
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Easyredis
+- --main
+- README.md
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+requirements: []
+
+rubyforge_project: easyredis
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: simple framework designed to make using redis as a database simpler
+test_files: []
+