ion 0.0.1

data/README.md

@@ -0,0 +1,280 @@
+Ion
+===
+
+A search engine written in Ruby and uses Redis.
+
+Ion is under a state merciless refactoring until it reaches a
+useable feature set--use at your own risk :)
+
+Testing
+-------
+
+    rvm 1.9.2-p136@ion --rvmrc --create
+    redis-server
+    rvm gemset import  # or install gems in .gems
+
+    export REDIS_URL=redis://127.0.0.1:6379/0  # optional, this is the default
+    rake test
+
+Usage
+-----
+
+Ion needs Redis.
+
+    require 'ion'
+    Ion.connect url: 'redis://127.0.0.1:6379/0'
+
+Any ORM will do. As long as you can hook it to update Ion's indices, you'll be fine.
+
+    class Album < Ohm::Model
+      include Ion::Entity
+      include Ohm::Callbacks  # for `after` and `before`
+
+      # Say you have these fields
+      attribute :name
+      attribute :artist
+
+      # Set it up to be indexed
+      ion {
+        text :name
+        metaphone :artist
+      }
+
+      # Just call these after saving/deleting
+      after  :save,   :update_ion_indices
+      before :delete, :delete_ion_indices
+    end
+
+Searching is easy:
+
+    results = Album.ion.search {
+      text :name, "Dancing Galaxy"
+    }
+
+    results = Album.ion.search {
+      metaphone :artist, "Astral Projection"
+    }
+
+The results will be an `Enumerable` object. Go ahead and iterate as you normally would.
+
+    results.each do |album|
+      puts "Album '#{album.name}' (by #{album.artist})"
+    end
+
+You can also get the raw results easily.
+
+    results.to_a  #=> [<#Album>, <#Album>, ... ]
+    results.ids   #=> ["1", "2", "10", ... ]
+
+Features
+--------
+
+### Custom indexing functions
+
+    class Book < Ohm::Model
+      attribute :name
+      attribute :synopsis
+      reference :author, Person
+
+      ion {
+        text(:author) { author.name }              # Supply your own indexing function
+      }
+    end
+
+    Book.ion.search { text :author, "Patrick Suskind" }
+
+### Nested conditions
+
+By default, doing a `.search { ... }` does an `all_of` search (that is,
+it must match all the given rules). You can use `any_of` and `all_of`, and
+you may even nest them.
+
+    Book.ion.search {
+      all_of {
+        text :name,     "perfume the story of a murderer"
+        text :synopsis, "base note"
+        any_of {
+          text :tags, "fiction"
+          text :tags, "thriller"
+        }
+      }
+    }
+
+### Important rules
+
+You can make certain rules score higher than the rest. In this example,
+if the search string is found in the name, it'll rank higher than if it
+was found in the synopsis.
+
+    Book.ion.search {
+      any_of {
+        score(5.0) { text :name, "Darkly Dreaming Dexter" }
+        score(1.0) { text :synopsis, "Darkly Dreaming Dexter" }
+      }
+    }
+
+### Boosting
+
+You can define rules on what will rank higher.
+
+This is different from `score` (above) in such that it only boosts current
+results, and doesn't add any. For instance, below, it will not show all
+"sale" items, but will make any sale items in the current result set
+rank higher.
+
+    Book.ion.search {
+      text :name, "The Taking of Sleeping Beauty"
+      boost(2.0) { text :tags, "sale" }
+    }
+
+(Note: it will add +2.0, not multiply by 2.0. Also, the number is optional. This behavior may change in the future)
+
+### Metaphones
+
+Indexing via metaphones allows you to search by how something sounds like,
+rather than with exact spellings.
+
+    class Person < Ohm::Model
+      attribute :name
+
+      ion {
+        metaphone :name
+      }
+    end
+
+    Person.create name: "Stephane Michael Cook"
+
+    # Any of these will work
+    Person.ion.search { metaphone :name, 'stiefen michel cooke' }
+    Person.ion.search { metaphone :name, 'steven quoc' }
+
+### Ranges
+
+Limit your searches like so:
+
+    results = Book.ion.search {
+      text :author, "Anne Rice"
+    }
+
+    # Any of these will work.
+    results.range from: 54, limit: 10
+    results.range from: 3
+    results.range page: 1, limit: 30
+    results.range (0..3)
+    results.range (0..-1)
+    results.range from: 3, to: 9
+
+    results.size      # This will not change even if you change the range...
+    results.ids.size  # However, this will.
+
+    # Reset
+    results.range :all
+
+### Number indices
+
+    class Recipe < Ohm::Model
+      attribute :serving_size
+
+      ion {
+        number :serving_size         # Define a number index
+      }
+    end
+
+    Recipe.ion.search { number :serving_size, 1 }            # n == 1
+    Recipe.ion.search { number :serving_size, gt:1 }         # n > 1
+    Recipe.ion.search { number :serving_size, gt:2, lt:5 }   # 2 < n < 5
+    Recipe.ion.search { number :serving_size, min: 4 }       # n >= 4
+    Recipe.ion.search { number :serving_size, max: 10 }      # n <= 10
+
+### Sorting
+
+First, define a sort index in your model.
+
+    class Element < Ohm::Model
+      attribute :name
+      attribute :protons
+      attribute :electrons
+
+      ion {
+        sort   :name       # <-- like this
+        number :protons
+      }
+    end
+
+Now sort it like so. This will not take the search relevancy scores
+into account.
+
+    results = Element.ion.search { number :protons, gt: 3.5 }
+    results.sort_by :name
+
+Note that this sorting (unlike in Ohm, et al) is case insensitive,
+and takes English articles into account (eg, "The Beatles" will
+come before "Rolling Stones").
+
+Extending Ion
+-------------
+
+Override it with some fancy stuff.
+
+    class Ion::Search
+      def to_ohm
+        set_key = model.key['~']['mysearch']
+        ids.each { |id| set_key.sadd id }
+        Ohm::Set.new(set_key, model)
+      end
+    end
+
+    set = Album.ion.search { ... }.to_ohm
+
+Or extend the DSL
+
+    class Ion::Scope
+      def keywords(what)
+        any_of {
+          text :title, what
+          metaphone :artist, what
+        }
+      end
+    end
+
+    Album.ion.search { keywords "Foo" }
+
+Features in the works
+---------------------
+
+Stuff that's not implemented yet, but will be.
+
+    # TODO: search keyword blacklist
+    Ion.config.ignored_words += %w(at it the)
+
+    Item.ion.search {                  # TODO: Quoted searching
+      text :title, 'apple "MacBook Pro"'
+    }
+
+    results = Item.ion.search {
+      text :title, "Macbook"
+      exclude {                        # TODO: exclusions
+        text :title, "Case"
+      }
+    }
+
+    results.sort_by :name, order: :desc  # TODO: descending sort
+
+    results.facet_counts #=> { :name => { "Ape" => 2, "Banana" => 3 } } ??
+
+Quirks
+------
+
+### Searching with arity
+
+The search DSL may leave some things in accessible since the block will
+be ran through `instance_eval` in another context. You can get around it
+via:
+
+    Book.ion.search { text :name, @name }        # fail
+    Book.ion.search { |q| q.text :name, @name }  # good
+
+Or you may also take advantage of Ruby closures:
+
+    name = @name
+    Book.ion.search { text :name, name }         # good

data/Rakefile

@@ -0,0 +1,13 @@
+task :test do
+  $:.unshift File.expand_path(File.join(File.dirname(__FILE__), 'test'))
+
+  Dir['test/**/*_test.rb'].each do |file|
+    load file  unless file =~ /^-/
+  end
+end
+
+task :irb do
+  system 'irb -r./lib/ion.rb -r./test/irb_helpers'
+end
+
+task :default => :test

data/lib/ion.rb

@@ -0,0 +1,84 @@
+require 'redis'
+require 'nest'
+require 'text'
+require 'ostruct'
+
+module Ion
+  VERSION = "0.0.1"
+
+  PREFIX = File.join(File.dirname(__FILE__), 'ion')
+
+  # How long until search keys expire.
+  DEFAULT_TTL = 30
+
+  autoload :Stringer, "#{PREFIX}/stringer"
+  autoload :Config,   "#{PREFIX}/config"
+  autoload :Options,  "#{PREFIX}/options"
+  autoload :Search,   "#{PREFIX}/search"
+  autoload :Entity,   "#{PREFIX}/entity"
+  autoload :Index,    "#{PREFIX}/index"
+  autoload :Indices,  "#{PREFIX}/indices"
+  autoload :Scope,    "#{PREFIX}/scope"
+  autoload :Helpers,  "#{PREFIX}/helpers"
+
+  InvalidIndexType = Class.new(StandardError)
+  Error            = Class.new(StandardError)
+
+  # Returns the Redis instance that is being used by Ion.
+  def self.config
+    @config ||= Ion::Config.new
+  end
+
+  def self.version
+    VERSION
+  end
+
+  def self.redis
+    @redis || key.redis
+  end
+
+  # Connects to a certain Redis server.
+  def self.connect(to)
+    @redis = Redis.connect(to)
+  end
+
+  # Returns the root key.
+  def self.key
+    @key ||= if @redis
+      Nest.new('Ion', @redis)
+    else
+      Nest.new('Ion')
+    end
+  end
+
+  # Returns a new temporary key.
+  def self.volatile_key
+    key['~'][rand.to_s]
+  end
+
+  # Makes a certain volatile key expire.
+  def self.expire(*keys)
+    keys.each { |k| redis.expire(k, DEFAULT_TTL)  if k.include?('~') }
+  end
+
+  # Redis helper stuff
+  # Probably best to move this somewhere
+
+  # Combines multiple set keys.
+  def self.union(keys, options={})
+    return keys.first  if keys.size == 1
+
+    results = Ion.volatile_key
+    results.zunionstore keys, options
+    results
+  end
+
+  # Finds the intersection in multiple set keys.
+  def self.intersect(keys, options={})
+    return keys.first  if keys.size == 1
+
+    results = Ion.volatile_key
+    results.zinterstore keys, options
+    results
+  end
+end

data/lib/ion/config.rb

@@ -0,0 +1,16 @@
+class Ion::Config < OpenStruct
+  def initialize(args={})
+    super defaults.merge(args)
+  end
+
+  def defaults
+    @defaults ||= {
+      :ignored_words => %w(a it at the)
+    }
+  end
+
+  def method_missing(meth, *args, &blk)
+    return @table.keys.include?(meth[0...-1].to_sym)  if meth.to_s[-1] == '?'
+    super
+  end
+end

data/lib/ion/entity.rb

@@ -0,0 +1,48 @@
+module Ion::Entity
+  def self.included(to)
+    to.extend ClassMethods
+  end
+
+  # Call me after saving
+  def update_ion_indices
+    ion = self.class.ion
+
+    # Clear out previous indexes...
+    ion.index_types.each { |i_type| i_type.deindex(self) }
+
+    # And add new ones
+    ion.indices.each { |index| index.index(self) }
+  end
+
+  # Call me before deletion
+  def delete_ion_indices
+    ion = self.class.ion
+    ion.index_types.each { |i_type| i_type.del(self) }
+  end
+
+  module ClassMethods
+    # Sets up Ion indexing for a model.
+    #
+    # When no block is given, it returns the Ion::Options
+    # for the model.
+    #
+    # @example
+    #
+    #   class Artist < Model
+    #     include Ion::Entity
+    #     ion {
+    #       text :name
+    #       text :real_name
+    #     }
+    #   end
+    #
+    #   Artist.ion.indices
+    #   Artist.ion.search { ... }
+    #
+    def ion(&blk)
+      @ion_options ||= Ion::Options.new(self)
+      @ion_options.instance_eval(&blk)  if block_given?
+      @ion_options
+    end
+  end
+end

data/lib/ion/helpers.rb

@@ -0,0 +1,11 @@
+module Ion::Helpers
+  # Replacement for instance_eval for DSL stuff
+  # @example
+  #
+  #   yieldie(search) { |q| q.text :title, "hi" }
+  #   yieldie(search) { text :title, "hi" }
+  #
+  def yieldie(to=self, &blk)
+    (blk.arity > 0) ? yield(to) : to.instance_eval(&blk)
+  end
+end