oedipus 0.0.1.pre1

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+spec/data/index/*
+spec/data/binlog/*
+spec/data/searchd.*
+spec/data/sphinx.*

data/.rspec

@@ -0,0 +1 @@
+--colour

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in oedipus.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright © 2011 Chris Corbyn
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# Oedipus: Sphinx 2 Search Client for Ruby
+
+Oedipus is a client for the Sphinx search engine (>= 2.0.2), with support for
+real-time indexes and multi and/or faceted searches.
+
+It is not a clone of the PHP API, rather it is written from the ground up,
+wrapping the SphinxQL API offered by searchd.  Nor is it a plugin for
+ActiveRecord or DataMapper... though this is planned in separate gems.
+
+It will provide some higher level of abstraction in terms of the ease with
+which faceted search may be implemented, though it will remain light and simple.
+
+## Current Status
+
+This gem is in development.  It is not ready for production use.  I work for
+a company called Flippa.com, which currently implements faceted search in a PHP
+part of the website, using a slightly older version of Sphinx with lesser
+support for SphinxQL.  Once a month the developers at Flippa are given three days
+to work on a project of their own choice.  This is my 'Triple Time' project.
+
+I anticipate another week or two of development before I can consider this project
+production-ready.
+
+## Usage
+
+Not all of the following features are currently implemented, but the interface
+style is as follows.
+
+``` ruby
+require "oedipus"
+
+sphinx = Oedipus.connect('localhost:9306') # sphinxql host
+
+# insert a record into the 'articles' real-time index
+record = sphinx[:articles].insert(
+  7,
+  title:     "Badgers in the wild",
+  body:      "A big long wodge of text",
+  author_id: 4,
+  views:     102
+)
+# The attributes (but not the indexed fields) are returned
+# => { id: 7,  author_id: 4, views: 102 }
+
+# updating a record
+record = sphinx[:articles].update(7, views: 103)
+# The new attributes (but not the indexed fields) are returned
+# => { id: 7,  author_id: 4, views: 103 }
+
+# deleting a record
+sphinx[:articles].delete(7)
+# => true
+
+# searching the index
+results = sphinx[:articles].search("badgers", limit: 2)
+
+# Meta deta indicates the overall number of matched records, while the ':records'
+# array contains the actual data returned.
+# 
+# => {
+#   total_found: 987,
+#   time:        0.000,
+#   keyword[0]:  "badgers",
+#   docs[0]:     987,
+#   records:     [
+#     { id: 7,  author_id: 4, views: 102 },
+#     { id: 11, author_id: 6, views: 23 }
+#   ]
+# }
+
+# using attribute filters
+results = sphinx[:articles].search(
+  "example",
+  author_id: 7
+)
+# => (the same results, filtered by author)
+
+# performing a faceted search
+results = sphinx[:articles].facted_search(
+  "badgers",
+  facets: {
+    popular:         { views: 100..10000 },
+    farming:         "farming",
+    popular_farming: ["farming", { views: 100..10000 } ]
+  }
+)
+# The main results are returned in the ':records' array, and all the facets in
+# the ':facets' Hash.
+# => {
+#   total_found: 987,
+#   time: 0.000,
+#   records: [ ... ],
+#   facets: {
+#     popular: {
+#       total_found: 25,
+#       time: 0.000,
+#       records: [ ... ]
+#     },
+#     farming: {
+#       total_found: 123,
+#       time: 0.000,
+#       records: [ ... ]
+#     },
+#     popular_farming: {
+#       total_found: 2,
+#       time: 0.000,
+#       records: [ ... ]
+#     }
+#   }
+# }
+# 
+# When performing a faceted search, the primary search is used as the basis for
+# each facet, so they can be considered refinements.
+
+# performing a mutli-search
+results = sphinx[:articles].multi_search(
+  badgers: ["badgers", { limit: 30 }],
+  frogs:   "frogs AND wetlands",
+  rabbits: ["rabbits OR burrows", { view_count: 20..100 }]
+)
+# The results are returned in a 2-dimensional Hash, keyed as sent in the query
+# => {
+#   badgers: {
+#     ...
+#   },
+#   frogs: {
+#     ...
+#   },
+#   rabbits: {
+#     ...
+#   }
+# }
+# 
+# Unlike with a faceted search, the queries in a multi-search do not have to be
+# related to one another.
+```
+
+## Future Plans
+
+I plan to release gems for integration with DataMapper and ActiveRecord.  DataMapper
+first, since that's what we use.
+
+I also intend to remove ruby-mysql from the dependencies, as it doesn't perfectly fit
+the needs of SphinxQL.  I will be implementing the limited subset of the MySQL protocol
+by hand (which is not as big a deal as it sounds).
+
+## Copyright and Licensing
+
+Refer to the LICENSE file for details.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/oedipus/connection.rb

@@ -0,0 +1,50 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "mysql"
+
+# SphinxQL greets with charset number 0
+Mysql::Charset::NUMBER_TO_CHARSET[0] = Mysql::Charset::COLLATION_TO_CHARSET["utf8_general_ci"]
+
+module Oedipus
+  # Provides an interface for talking to SphinxQL.
+  class Connection
+    # Instantiate a new Connection to a SphinxQL host.
+    #
+    # @param [Hash]
+    #   a Hash containing :host and :port
+    #
+    # The connection will be established on initialization.
+    def initialize(options)
+      @conn = ::Mysql.new(options[:host], nil, nil, nil, options[:port], nil, ::Mysql::CLIENT_MULTI_STATEMENTS | ::Mysql::CLIENT_MULTI_RESULTS)
+    end
+
+    # Acess a specific index for querying.
+    #
+    # @param [String] index_name
+    #   the name of an existing index in Sphinx
+    #
+    # @return [Index]
+    #   an index that can be queried
+    def [](index_name)
+      Index.new(index_name, self)
+    end
+
+    def execute(sql)
+      @conn.query(sql)
+    end
+
+    def quote(v)
+      case v
+      when Numeric then v
+      else "'#{::Mysql.quote(v.to_s)}'"
+      end
+    end
+  end
+end

data/lib/oedipus/index.rb

@@ -0,0 +1,103 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module Oedipus
+  # Representation of a search index for querying.
+  class Index
+    attr_reader :name
+    attr_reader :attributes
+
+    # Initialize the index named +name+ on the connection +conn+.
+    #
+    # @param [Symbol] name
+    #   the name of an existing index in sphinx
+    #
+    # @param [Connection] conn
+    #   an instance of Oedipus::Connection for querying
+    def initialize(name, conn)
+      @name       = name.to_sym
+      @conn       = conn
+      @attributes = reflect_attributes
+      @builder    = QueryBuilder.new(name, conn)
+    end
+
+    # Insert the record with the ID +id+.
+    #
+    # @example
+    #   index.insert(42, :title => "example", :views => 22)
+    #
+    # @param [Integer] id
+    #   the unique ID of the document in the index
+    #
+    # @param [Hash] hash
+    #   a symbol-keyed hash of data to insert
+    #
+    # @return [Hash]
+    #   a copy of the inserted record
+    def insert(id, hash)
+      data = Hash[
+        [:id, *hash.keys.map(&:to_sym)].zip \
+        [id,  *hash.values.map { |v| String === v ? @conn.quote(v) : v }]
+      ]
+      @conn.execute("INSERT INTO #{name} (#{data.keys.join(', ')}) VALUES (#{data.values.join(', ')})")
+      attributes.merge(data.select { |k, _| attributes.key?(k) })
+    end
+
+    def search(*args)
+      raise ArgumentError, "Wrong number of arguments (#{args.size} for 1..2)" unless (1..2) === args.size
+
+      query, attrs = case args.first
+        when String then [args[0], args[1] || {}]
+        when Hash   then ["", args[0]]
+        else raise ArgumentError, "Invalid argument type #{args.first.class} for argument 0"
+      end
+
+      results = @conn.execute(@builder.sql(query, attrs))
+      meta    = @conn.execute("SHOW META")
+
+      # FIXME: This needs optimizing
+      {}.tap do |r|
+        meta.each do |k, v|
+          r[k.to_sym] = case k
+            when 'total', 'total_found' then Integer(v)
+            when 'time'                 then Float(v)
+            else v
+          end
+        end
+
+        r[:records] = []
+
+        results.each_hash do |hash|
+          r[:records] << Hash[hash.keys.map(&:to_sym).zip(hash.map { |k, v| cast(k, v) })]
+        end
+      end
+    end
+
+    private
+
+    def cast(key, value)
+      case attributes[key.to_sym]
+      when Fixnum then Integer(value)
+      else value
+      end
+    end
+
+    def reflect_attributes
+      rs = @conn.execute("DESC #{name}")
+      {}.tap do |attrs|
+        rs.each_hash do |row|
+          case row['Type']
+          when 'uint', 'integer' then attrs[row['Field'].to_sym] = 0
+          when 'string'          then attrs[row['Field'].to_sym] = ""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/oedipus/mysql/client.rb

@@ -0,0 +1,136 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "socket"
+require "net/protocol"
+
+module Oedipus
+  module Mysql
+    # Limited subset of MySQL protocol for communication with SphinxQL.
+    #
+    # This needs to exist since other ruby MySQL clients do not provide the relevant features.
+    class Client
+      # Connect to the SphinxQL server.
+      #
+      # @param [Hash]
+      #   a Hash containing :host and :port
+      def initialize(options)
+        @sock = TCPSocket.new(options[:host], options[:port])
+        @seq  = 0
+        perform_handshake
+      end
+
+      def execute(sql)
+        p send_packet(query_packet(sql))
+      end
+
+      private
+
+      def perform_handshake
+        auth_pkt = clnt_authentication_packet(serv_initialization_packet)
+        raise "Some sort of error" unless send_packet(auth_pkt)[:type] == :ok
+      end
+
+      def incr_seq(seq)
+        raise ProtocolError, "Invalid packet sequence value #{seq} != #{@seq}" unless seq == @seq
+        @seq = (seq + 1) % 256
+      end
+
+      def recv_packet
+        a, b, seq = @sock.read(4).unpack("CvC")
+        incr_seq(seq)
+        @sock.read(a | (b << 8))
+      end
+
+      def send_packet(pkt)
+        while chunk = pkt.read(2**24 - 1)
+          @sock.write([chunk.length % 256, chunk.length / 256, @seq, chunk].pack("CvCZ*"))
+          incr_seq(@seq)
+        end
+
+        serv_result_packet
+      end
+
+      def serv_result_packet
+        pkt = recv_packet
+        case pkt[0]
+        when "\x00" then ok_packet(pkt)
+        else raise ProtocolError, "Unknown packet type #{pkt[0]}"
+        end
+      end
+
+      def scan_lcb(str)
+        case v = str.slice!(0)
+        when "\xFB" then nil
+        when "\xFC" then str.slice!(0, 2).unpack("v").first
+        when "\xFD"
+          a, b = str.slice!(0, 3).unpack("Cv")
+          a | (b << 8)
+        when "\xFE"
+          a, b = str.slice!(0, 8).unpack("VV")
+          a | (b << 32)
+        else v.ord
+        end
+      end
+
+      def ok_packet(str)
+        Hash[
+          [
+            :field_count,
+            :affected_rows,
+            :insert_id,
+            :serv_stat,
+            :warning_count,
+            :message
+          ].zip([scan_lcb(str), scan_lcb(str), scan_lcb(str)] + str.unpack("vva*"))
+        ].tap { |pkt| pkt[:type] = :ok }
+      end
+
+      def serv_initialization_packet
+        Hash[
+          [
+            :prot_ver,
+            :serv_ver,
+            :thread_id,
+            :scramble_buf_a,
+            :filler_a,
+            :serv_cap_a,
+            :serv_enc,
+            :serv_stat,
+            :serv_cap_b,
+            :scramble_len,
+            :filler_b,
+            :scramble_buf_b
+          ].zip(recv_packet.unpack("CZ*Va8CvCvvCa10Z*"))
+        ].tap do |pkt|
+          raise ProtocolError, "Unsupported MySQL protocol version #{pkt[:prot_ver]}" unless pkt[:prot_ver] == 0x0A
+        end
+      end
+
+      def clnt_authentication_packet(init_pkt)
+        StringIO.new [
+          197120,  # clnt_cap (prot 4.1, multi-stmt, multi-rs)
+          1024**3, # max pkt size
+          0,       # charset not used
+          '',      # filler 23 bytes
+          '',      # username not used
+          '',      # scramble buf (no password)
+          ''       # dbname not used
+        ].pack("VVCa23Z*A*Z*")
+      end
+
+      def query_packet(sql)
+        StringIO.new [
+          0x03,  # COM_QUERY type
+          sql
+        ].pack("Ca*")
+      end
+    end
+  end
+end

data/lib/oedipus/query_builder.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module Oedipus
+  class QueryBuilder
+    def initialize(index_name, conn)
+      @index_name = index_name
+      @conn       = conn
+    end
+
+    def sql(query, filters)
+      [
+        from,
+        conditions(query, filters),
+        limits(filters)
+      ].join(" ")
+    end
+
+    private
+
+    def from
+      "SELECT * FROM #{@index_name}"
+    end
+
+    def conditions(query, filters)
+      exprs = []
+      exprs << "MATCH(#{@conn.quote(query)})" unless query.empty?
+      "WHERE " << exprs.join(" AND ") if exprs.any?
+    end
+
+    def limits(filters)
+      "LIMIT #{filters[:offset].to_i}, #{filters[:limit].to_i}" if filters.key?(:limit)
+    end
+  end
+end

data/lib/oedipus/version.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module Oedipus
+  VERSION = "0.0.1.pre1"
+end

data/lib/oedipus.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "oedipus/version"
+require "oedipus/query_builder"
+require "oedipus/connection"
+require "oedipus/index"
+require "oedipus/mysql/client"
+
+module Oedipus
+  class << self
+    # Connect to Sphinx running SphinxQL.
+    #
+    # @example
+    #   c = Oedipus.connect("localhost:9306")
+    #   c = Oedipus.connect(:host => "localhost", :port => 9306)
+    #
+    # @param [String] server
+    #   a 'hostname:port' string
+    #
+    # @param [Hash] options
+    #   a Hash with :host and :port keys
+    #
+    # @return [Connection]
+    #   a client connected to SphinxQL
+    def connect(options)
+      # TODO: Add pooling
+      Connection.new(
+        options.kind_of?(String) ?
+          Hash[ [:host, :port].zip(options.split(":")) ] :
+          options
+      )
+    end
+  end
+end

data/oedipus.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "oedipus/version"
+
+Gem::Specification.new do |s|
+  s.name        = "oedipus"
+  s.version     = Oedipus::VERSION
+  s.authors     = ["d11wtq"]
+  s.email       = ["chris@w3style.co.uk"]
+  s.homepage    = "https://github.com/d11wtq/oedipus"
+  s.summary     = "Sphinx 2 Search Client for Ruby"
+  s.description = <<-DESC.strip
+    Oedipus brings full support for Sphinx 2 to Ruby:
+
+      * real-time indexes
+      * faceted search
+      * multi-queries
+      * full attribute support
+      * optional model-style interaction
+
+    It works with 'stable' versions of Sphinx 2 (>= 2.0.2). All
+    features are implemented entirely through the SphinxQL interface.
+  DESC
+
+  s.rubyforge_project = "oedipus"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "ruby-mysql"
+
+  s.add_development_dependency "rspec"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "rspec"
+require "bundler/setup"
+require "oedipus"
+
+Dir[File.expand_path("../support/**/*rb", __FILE__)].each { |f| require f }
+
+RSpec.configure do |config|
+  include Oedipus::TestHarness
+
+  config.before(:suite) do
+    unless ENV.key?("SEARCHD")
+      raise "You must specify a path to the Sphinx 'searchd' executable (>= 2.0.2)"
+    end
+
+    set_data_dir File.expand_path("../data", __FILE__)
+    set_searchd  ENV["SEARCHD"]
+
+    prepare_data_dirs
+    write_sphinx_conf
+    start_searchd
+  end
+
+  config.before(:each) do
+    empty_indexes
+  end
+
+  config.after(:suite) do
+    stop_searchd
+  end
+end

data/spec/support/test_harness.rb

@@ -0,0 +1,143 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module Oedipus
+  # Mixed into RSpec suites to manage starting/stopping Sphinx.
+  module TestHarness
+    # Set the path to the searchd executable.
+    #
+    # The version of Sphinx must be >= 2.0.2.
+    #
+    # @param [String] path
+    #   the absolute path to searchd
+    def set_searchd(path)
+      @searchd = path
+    end
+
+    # Set the path to a temporary directory for writing test data to.
+    #
+    # @param [String] path
+    #   the path to a writable directory whose contents may be completely deleted
+    def set_data_dir(path)
+      @data_dir = path
+    end
+
+    # Ensure that the temporary data directories exist and are clean.
+    def prepare_data_dirs
+      Dir.mkdir("#{data_dir}/index")  unless Dir.exist?("#{data_dir}/index")
+      Dir.mkdir("#{data_dir}/binlog") unless Dir.exist?("#{data_dir}/binlog")
+
+      clean_data_dirs
+    end
+
+    def empty_indexes
+      require "mysql"
+      @conn ||= ::Mysql.new(searchd_host[:host], nil, nil, nil, searchd_host[:port])
+
+      idxs = @conn.query("SHOW TABLES")
+
+      while idx = idxs.fetch_hash
+        docs = @conn.query("SELECT id FROM #{idx['Index']}")
+        while hash = docs.fetch_hash
+          @conn.query("DELETE FROM #{idx['Index']} WHERE id = #{hash['id']}")
+        end
+      end
+    end
+
+    # Write the sphinx.conf file, using #index_definiton.
+    #
+    # Sphinx will listen on localhost port 9399.
+    #
+    # Any string returned from #index_definition will be used to define one or more indexes.
+    def write_sphinx_conf
+      File.open(searchd_config, "wb") do |f|
+        f <<
+        <<-CONF.gsub(/^ {10}/m, "")
+          ##
+          # This file is automatically generated during tests
+          ##
+
+          index posts_rt
+          {
+            type = rt
+            path = #{data_dir}/index/posts_rt
+
+            rt_field       = title
+            rt_field       = body
+
+            rt_attr_uint   = user_id
+            rt_attr_uint   = views
+            rt_attr_string = status
+          }
+
+          searchd
+          {
+            compat_sphinxql_magics = 0
+
+            max_matches  = 2000
+            pid_file     = #{data_dir}/searchd.pid
+            listen       = #{searchd_host[:host]}:#{searchd_host[:port]}:mysql41
+            workers      = threads
+            log          = #{data_dir}/searchd.log
+            query_log    = #{data_dir}/searchd.log
+            binlog_path  = #{data_dir}/binlog
+          }
+        CONF
+      end
+    end
+
+    # Start the sphinx daemon in a child process and return the PID.
+    #
+    # Output is redirected to searchd.out and searchd.err in the data dir.
+    def start_searchd
+      @searchd_pid = Process.spawn(
+        searchd, "--console", "-c", searchd_config,
+        out: "#{data_dir}/searchd.out",
+        err: "#{data_dir}/searchd.err"
+      )
+      sleep 1
+    end
+
+    # Stop an already running sphinx daemon and wait for it to shutdown.
+    def stop_searchd
+      Process.kill("TERM", @searchd_pid) && Process.wait
+    end
+
+    private
+
+    def clean_data_dirs
+      clean_files("#{data_dir}/index/**/*")
+      clean_files("#{data_dir}/binlog/**/*")
+      clean_files("#{data_dir}/searchd.pid")
+      clean_files("#{data_dir}/searchd.out")
+      clean_files("#{data_dir}/searchd.err")
+      clean_files("#{data_dir}/sphinx.conf")
+    end
+
+    def searchd_host
+      { host: "127.0.0.1", port: 9399 }
+    end
+
+    def searchd
+      @searchd ||= "searchd"
+    end
+
+    def searchd_config
+      "#{data_dir}/sphinx.conf"
+    end
+
+    def clean_files(path)
+      Dir[path].each { |f| File.delete(f) unless File.directory?(f) }
+    end
+
+    def data_dir
+      @data_dir ||= "./data"
+    end
+  end
+end

data/spec/unit/connection_spec.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "spec_helper"
+
+describe Oedipus::Connection do
+  let(:conn) { Oedipus::Connection.new(searchd_host) }
+
+  describe "#initialize" do
+    context "on successful connection" do
+      it "returns the connection" do
+        Oedipus::Connection.new(searchd_host).should be_a_kind_of(Oedipus::Connection)
+      end
+    end
+
+    context "on failed connection" do
+      it "raises an error" do
+        expect {
+          Oedipus::Connection.new(:host => "127.0.0.1", :port => 45346138)
+        }.to raise_error
+      end
+    end
+  end
+
+  describe "#[]" do
+    it "returns an index" do
+      conn[:posts_rt].should be_a_kind_of(Oedipus::Index)
+    end
+  end
+end

data/spec/unit/index_spec.rb

@@ -0,0 +1,85 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "spec_helper"
+
+describe Oedipus::Index do
+  let(:conn)  { Oedipus::Connection.new(searchd_host) }
+  let(:index) { Oedipus::Index.new(:posts_rt, conn) }
+
+  describe "#insert" do
+    context "with valid data" do
+      it "returns the inserted attributes as a Hash" do
+        index.insert(
+          10,
+          title:   "Badgers",
+          body:    "They live in setts, do badgers.",
+          views:   721,
+          user_id: 7
+        ).should == { id: 10, views: 721, user_id: 7, status: "" }
+      end
+    end
+
+    context "with invalid data" do
+      it "raises an error" do
+        expect {
+          index.insert(
+            10,
+            bad_field: "Invalid",
+            body:      "They live in setts, do badgers.",
+            views:     721,
+            user_id:   7
+          )
+        }.to raise_error
+      end
+    end
+  end
+
+  describe "#search" do
+    before(:each) do
+      index.insert(1, title: "Badgers and foxes",   views: 150)
+      index.insert(2, title: "Rabbits and hares",   views: 87)
+      index.insert(3, title: "Badgers in the wild", views: 41)
+      index.insert(4, title: "Badgers for all!",    views: 3003)
+    end
+
+    context "by fulltext matching" do
+      it "indicates the number of records found" do
+        index.search("badgers")[:total_found].should == 3
+      end
+
+      it "includes the matches records" do
+        index.search("badgers")[:records].should == [
+          { id: 1, views: 150,  user_id: 0, status: "" },
+          { id: 3, views: 41,   user_id: 0, status: "" },
+          { id: 4, views: 3003, user_id: 0, status: "" }
+        ]
+      end
+    end
+
+    context "with limits" do
+      it "still indicates the number of records found" do
+        index.search("badgers", limit: 2)[:total_found].should == 3
+      end
+
+      it "returns the limited subset of the results" do
+        index.search("badgers", limit: 2)[:records].should == [
+          { id: 1, views: 150,  user_id: 0, status: "" },
+          { id: 3, views: 41,   user_id: 0, status: "" }
+        ]
+      end
+
+      it "can use an offset" do
+        index.search("badgers", limit: 1, offset: 1)[:records].should == [
+          { id: 3, views: 41,   user_id: 0, status: "" }
+        ]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: oedipus
+version: !ruby/object:Gem::Version
+  version: 0.0.1.pre1
+  prerelease: 6
+platform: ruby
+authors:
+- d11wtq
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-mysql
+  requirement: &20332040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *20332040
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &20331620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *20331620
+description: ! "Oedipus brings full support for Sphinx 2 to Ruby:\n\n      * real-time
+  indexes\n      * faceted search\n      * multi-queries\n      * full attribute support\n
+  \     * optional model-style interaction\n\n    It works with 'stable' versions
+  of Sphinx 2 (>= 2.0.2). All\n    features are implemented entirely through the SphinxQL
+  interface."
+email:
+- chris@w3style.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/oedipus.rb
+- lib/oedipus/connection.rb
+- lib/oedipus/index.rb
+- lib/oedipus/mysql/client.rb
+- lib/oedipus/query_builder.rb
+- lib/oedipus/version.rb
+- oedipus.gemspec
+- spec/data/.gitkeep
+- spec/spec_helper.rb
+- spec/support/test_harness.rb
+- spec/unit/connection_spec.rb
+- spec/unit/index_spec.rb
+homepage: https://github.com/d11wtq/oedipus
+licenses: []
+post_install_message: 
+rdoc_options: []
+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.3.1
+requirements: []
+rubyforge_project: oedipus
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Sphinx 2 Search Client for Ruby
+test_files: []