oedipus 0.0.13 → 0.0.14

data/README.md

@@ -1,11 +1,11 @@
 # 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 multi-dimensional faceted searches.
+real-time indexes and multi-dimensional 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 will follow in separate gems (see
+ActiveRecord or DataMapper... though this will be offered in separate gems (see
 [oedipus-dm](https://github.com/d11wtq/oedipus-dm)).
 
 Oedipus provides a level of abstraction in terms of the ease with which faceted
@@ -21,14 +21,17 @@ Oedipus does not (yet) provide wrappers for indexing that data via ruby [1].
 
 ## Dependencies
 
-  * ruby (>= 1.9)
-  * sphinx (>= 2.0.2)
-  * mysql client development libraries (>= 4.1)
+  * ruby >= 1.9
+  * sphinx >= 2.0.2
+  * mysql dev libs >= 4.1
 
-The gem builds a small (tiny) native extension for interfacing with mysql, as
-existing gems either did not support multi-queries, or were too flaky
-(i.e. ruby-mysql).  I will add a pure-ruby option in due course (it requires
-implementing a relatively small subset of the mysql 4.1 protocol).
+## Installation
+
+Via rubygems:
+
+```
+gem install oedipus
+```
 
 ## Usage
 
@@ -39,7 +42,30 @@ The following features are all currently implemented.
 ``` ruby
 require "oedipus"
 
-sphinx = Oedipus.connect('localhost:9306') # sphinxql host
+sphinx = Oedipus.connect('127.0.0.1:9306') # sphinxql host
+```
+
+**NOTE:** Don't connect to the named host 'localhost', since the MySQL library
+will try to use a UNIX socket instead of a TCP connection, which Sphinx doesn't
+currently support.
+
+Connections can be re-used by calling `Oedipus.connection` once connected.
+
+``` ruby
+sphinx = Oedipus.connection
+```
+
+If you're using Oedipus in a Rails application, you may wish to call `connect`
+inside an initializer and then obtain that connection in your application, by
+calling `connection`.
+
+If you need to manage multiple connections, you may specify names for each
+connection.
+
+``` ruby
+Oedipus.connect("other-host.tld:9306", :other)
+
+sphinx = Oedipus.connection(:other)
 ```
 
 ### Inserting (real-time indexes)
@@ -76,7 +102,6 @@ sphinx[:articles].update(7, views: 103)
 
 ``` ruby
 sphinx[:articles].delete(7)
-# => true
 ```
 
 ### Fetching a known document (by ID)
@@ -90,12 +115,6 @@ record = sphinx[:articles].fetch(7)
 
 You perform queries by invoking `#search` on the index.
 
-Oedipus makes no attempt to provide an abstraction layer for the fulltext
-query itself.  I believe this would not be flexible enough.  Sphinx fulltext
-queries are extremely featureful, very dense and concise; a ruby solution
-would only be lengthier and harder to understand, IMHO.  Perhaps such an
-abstraction could be provided by a separate gem.
-
 
 ``` ruby
 results = sphinx[:articles].search("badgers", limit: 2)
@@ -231,8 +250,8 @@ attribute differently.
 Note that Sphinx applies a limit of 20 by default, so you probably want to specify
 a limit yourself.  You are bound by your `max_matches` setting in sphinx.conf.
 
-Note that the meta data will still indicate the actual number of results that matched;
-you simply get a smaller collection of materialized records.
+The meta data will still indicate the actual number of results that matched; you simply
+get a smaller collection of materialized records.
 
 ``` ruby
 sphinx[:articles].search("bobcats", limit: 50)
@@ -245,8 +264,8 @@ A faceted search takes a base query and a set of additional queries that are
 variations on it.  Oedipus makes this simple by allowing your facets to inherit
 from the base query.
 
-Oedipus allows you to replace '%{query}' in your facets with whatever was in the
-original query.  This can be useful if you want to provide facets that only
+Oedipus allows you to replace `'%{query}'` in your facets with whatever was in
+the original query.  This can be useful if you want to provide facets that only
 perform the search in the title of the document (`"@title (%{query})"`) for
 example.
 
@@ -380,11 +399,6 @@ To run the unit tests alone, without the need for Sphinx:
 If you have made changes to the C extension, those changes will be compiled and installed
 (to the lib/ directory) before the specs are run.
 
-You may also compile the C extension and run the specs separately, if you prefer:
-
-    bundle exec rake compile
-    bundle exec rspec spec/unit/
-
 ### Footnotes
 
   [1]: In practice I find such an abstraction not to be very useful, as it assumes a single-server setup
@@ -399,10 +413,9 @@ You may also compile the C extension and run the specs separately, if you prefer
 
 ## Future Plans
 
-  * Integration ActiveRecord (DataMapper support has already been added)
+  * Integration ActiveRecord
   * Support for re-indexing non-realtime indexes from ruby code
   * Distributed index support (sharding writes between indexes)
-  * Make C extension optional and provide an implementation in pure-ruby
   * Query translation layer for Lucene-style AND/OR/NOT and attribute:value interpretation
   * Fulltext query sanitization for unsafe user input (e.g. @@missing field)
 

data/lib/oedipus/connection/registry.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module Oedipus
+  class Connection
+    module Registry
+      # Connect to Sphinx running SphinxQL.
+      #
+      # Connections are cached for re-use.
+      #
+      # @example
+      #   c = Oedipus.connect("127.0.0.1:9306")
+      #   c = Oedipus.connect(host: "127.0.0.1", port: 9306)
+      #   c = Oedipus.connect("127.0.0.1:9306", :dist_host)
+      #
+      # @param [String|Hash] server
+      #   a 'hostname:port' string, or
+      #   a Hash with :host and :port keys
+      #
+      # @param [Object] key
+      #   an optional name for the connection
+      #
+      # @return [Connection]
+      #   a client connected to SphinxQL
+      def connect(options, key = :default)
+        connections[key] = Connection.new(options)
+      end
+
+      # Lookup an already connected connection.
+      #
+      # @example
+      #   c = Oedipus.connection
+      #   c = Oedipus.connection(:dist_host)
+      #
+      # @param [Object] key
+      #   an optional name for the connection
+      #
+      # @return [Connection]
+      #   a client connected to SphinxQL
+      def connection(key = :default)
+        raise ArgumentError, "Connection #{key} is not defined" unless connections.key?(key)
+        connections[key]
+      end
+
+      def connections
+        @connections ||= {}
+      end
+    end
+  end
+end

data/lib/oedipus/connection.rb

@@ -49,6 +49,8 @@ module Oedipus
       Index.new(index_name, self)
     end
 
+    alias_method :index, :[]
+
     # Execute one or more queries in a batch.
     #
     # Queries should be separated by semicolons.

data/lib/oedipus/version.rb

@@ -8,5 +8,5 @@
 ##
 
 module Oedipus
-  VERSION = "0.0.13"
+  VERSION = "0.0.14"
 end

data/lib/oedipus.rb

@@ -30,30 +30,11 @@ require "oedipus/query_builder"
 require "oedipus/connection_error"
 require "oedipus/connection"
 require "oedipus/connection/pool"
+require "oedipus/connection/registry"
 
 require "oedipus/index"
 
 module Oedipus
   extend Comparison::Shortcuts
-
-  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)
-    end
-  end
+  extend Connection::Registry
 end

data/spec/integration/connection/registry_spec.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "spec_helper"
+require "oedipus/rspec/test_harness"
+
+describe Oedipus::Connection::Registry do
+  include Oedipus::RSpec::TestHarness
+
+  before(:all) do
+    set_data_dir File.expand_path("../../../data", __FILE__)
+    set_searchd  ENV["SEARCHD"]
+    start_searchd
+  end
+
+  after(:all) { stop_searchd }
+
+  before(:each) { empty_indexes }
+
+  let(:registry) do
+    Object.new.tap { |o| o.send(:extend, Oedipus::Connection::Registry) }
+  end
+
+  describe "#connect" do
+    it "makes a new connection to a SphinxQL host" do
+      registry.connect(searchd_host).should be_a_kind_of(Oedipus::Connection)
+    end
+  end
+
+  describe "#connection" do
+    context "without a name" do
+      let(:conn) { registry.connect(searchd_host) }
+
+      it "returns an existing connection" do
+        conn.should equal registry.connection
+      end
+    end
+
+    context "with a name" do
+      let(:conn) { registry.connect(searchd_host, :bob) }
+
+      it "returns the named connection" do
+        conn.should equal registry.connection(:bob)
+      end
+    end
+
+    context "with a bad name" do
+      it "raises an ArgumentError" do
+        expect { registry.connection(:wrong) }.to raise_error(ArgumentError)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oedipus
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-06 00:00:00.000000000 Z
+date: 2012-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &23194300 !ruby/object:Gem::Requirement
+  requirement: &12537160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *23194300
+  version_requirements: *12537160
 - !ruby/object:Gem::Dependency
   name: rake-compiler
-  requirement: &23193860 !ruby/object:Gem::Requirement
+  requirement: &12535680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *23193860
+  version_requirements: *12535680
 description: ! "== Sphinx 2 Comes to Ruby\n\nOedipus brings full support for Sphinx
   2 to Ruby:\n\n  - real-time indexes (insert, replace, update, delete)\n  - faceted
   search (variations on a base query)\n  - multi-queries (multiple queries executed
@@ -73,6 +73,7 @@ files:
 - lib/oedipus/comparison/shortcuts.rb
 - lib/oedipus/connection.rb
 - lib/oedipus/connection/pool.rb
+- lib/oedipus/connection/registry.rb
 - lib/oedipus/connection_error.rb
 - lib/oedipus/index.rb
 - lib/oedipus/query_builder.rb
@@ -80,6 +81,7 @@ files:
 - lib/oedipus/version.rb
 - oedipus.gemspec
 - spec/data/.gitkeep
+- spec/integration/connection/registry_spec.rb
 - spec/integration/connection_spec.rb
 - spec/integration/index_spec.rb
 - spec/spec_helper.rb
@@ -111,7 +113,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1539164909782359047
+      hash: -1945313164651030981
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -120,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1539164909782359047
+      hash: -1945313164651030981
 requirements: []
 rubyforge_project: oedipus
 rubygems_version: 1.8.11
@@ -129,6 +131,7 @@ specification_version: 3
 summary: Sphinx 2 Search Client for Ruby
 test_files:
 - spec/data/.gitkeep
+- spec/integration/connection/registry_spec.rb
 - spec/integration/connection_spec.rb
 - spec/integration/index_spec.rb
 - spec/spec_helper.rb