sphinx 0.9.9.2117

data/.gitignore

@@ -0,0 +1,4 @@
+rdoc
+doc
+.yardoc
+pkg

data/README.rdoc

@@ -0,0 +1,243 @@
+= Sphinx Client API
+
+This document gives an overview of what is Sphinx itself and how to use it 
+from your Ruby on Rails application. For more information or documentation, 
+please go to http://www.sphinxsearch.com
+
+== Sphinx
+
+Sphinx is a standalone full-text search engine, meant to provide fast, 
+size-efficient and relevant fulltext search functions to other applications. 
+Sphinx was specially designed to integrate well with SQL databases and 
+scripting languages. Currently built-in data sources support fetching data 
+either via direct connection to MySQL, or from an XML pipe.
+ 
+Simplest way to communicate with Sphinx is to use <tt>searchd</tt> —
+a daemon to search through full text indexes from external software.
+
+== Installation
+
+There are two options when approaching sphinx plugin installation:
+
+* using the gem (recommended)
+* install as a Rails plugin
+
+To install as a gem, add this to your environment.rb:
+
+  config.gem 'sphinx', :source => 'http://gemcutter.org'
+
+And then run the command:
+
+  sudo rake gems:install
+
+To install Sphinx as a Rails plugin use this:
+
+  script/plugin install git://github.com/kpumuk/sphinx.git
+
+== Documentation
+
+Complete Sphinx plugin documentation could be found here:
+http://kpumuk.github.com/sphinx
+
+Also you can find documentation on rdoc.info:
+http://rdoc.info/projects/kpumuk/sphinx
+
+You can build the documentation locally by running:
+
+  rake yard
+
+Please note: you should have yard gem installed on your system:
+
+  sudo gem install yard --source http://gemcutter.org
+
+Complete Sphinx API documentation could be found on Sphinx Search Engine
+site: http://www.sphinxsearch.com/docs/current.html
+This plugin is fully compatible with original PHP API implementation.
+
+== Ruby naming conventions
+
+Sphinx Client API supports Ruby naming conventions, so every API
+method name is in underscored, lowercase form:
+
+  SetServer    -> set_server
+  RunQueries   -> run_queries
+  SetMatchMode -> set_match_mode
+
+Every method is aliased to a corresponding one from standard Sphinx
+API, so you can use both <tt>SetServer</tt> and <tt>set_server</tt>
+with no differrence.
+
+There are three exceptions to this naming rule:
+
+  GetLastError   -> last_error
+  GetLastWarning -> last_warning
+  IsConnectError -> connect_error?
+
+Of course, all of them are aliased to the original method names.
+
+== Using multiple Sphinx servers
+
+Since we actively use this plugin in our Scribd development workflow,
+there are several methods have been added to accommodate our needs.
+You can find documentation on Ruby-specific methods in documentation:
+http://rdoc.info/projects/kpumuk/sphinx
+
+First of all, we added support of multiple Sphinx servers to balance
+load between them. Also it means that in case of any problems with one
+of servers, library will try to fetch the results from another one.
+Every consequence request will be executed on the next server in list
+(round-robin technique).
+
+  sphinx.set_servers([
+    { :host => 'browse01.local', :port => 3312 },
+    { :host => 'browse02.local', :port => 3312 },
+    { :host => 'browse03.local', :port => 3312 }
+  ])
+
+By default library will try to fetch results from a single server, and
+fail if it does not respond. To setup number of retries being performed,
+you can use second (additional) parameter of the <tt>set_connect_timeout</tt>
+and <tt>set_request_timeout</tt> methods:
+
+  sphinx.set_connect_timeout(1, 3)
+  sphinx.set_request_timeout(1, 3)
+
+There is a big difference between these two methods. First will affect
+only on requests experiencing problems with connection (socket error,
+pipe error, etc), second will be used when request is broken somehow
+(temporary searchd error, incomplete reply, etc). The workflow looks like
+this:
+
+1. Increase retries number. If is less or equal to configured value,
+   try to connect to the next server. Otherwise, raise an error.
+2. In case of connection problem go to 1.
+3. Increase request retries number. If it less or equal to configured
+   value, try to perform request. Otherwise, raise an error.
+4. In case of connection problem go to 1.
+5. In case of request problem, go to 3.
+6. Parse and return response.
+
+Withdrawals:
+
+1. Request could be performed <tt>connect_retries</tt> * <tt>request_retries</tt>
+   times. E.g., it could be tried <tt>request_retries</tt> times on each
+   of <tt>connect_retries</tt> servers (when you have 1 server configured,
+   but <tt>connect_retries</tt> is 5, library will try to connect to this
+   server 5 times).
+2. Request could be tried to execute on each server <tt>1..request_retries</tt>
+   times. In case of connection problem, request will be moved to another
+   server immediately.
+
+Usually you will set <tt>connect_retries</tt> equal to servers number,
+so you will be sure each failing request will be performed on all servers.
+This means that if one of servers is live, but others are dead, you request
+will be finally executed successfully.
+
+== Sphinx constants
+
+Most Sphinx API methods expecting for special constants will be passed.
+For example:
+
+  sphinx.set_match_mode(Sphinx::SPH_MATCH_ANY)
+
+Please note that these constants defined in a <tt>Sphinx</tt>
+module. You can use symbols or strings instead of these awful
+constants:
+
+  sphinx.set_match_mode(:any)
+  sphinx.set_match_mode('any')
+
+== Setting query filters
+
+Every <tt>set_</tt> method returns <tt>Sphinx::Client</tt> object itself.
+It means that you can chain filtering methods:
+
+  results = Sphinx::Client.new.
+              set_match_mode(:any).
+              set_ranking_mode(:bm25).
+              set_id_range(10, 1000).
+              query('test')
+
+There is a handful ability to set query parameters directly in <tt>query</tt>
+call. If block does not accept any parameters, it will be eval'ed inside
+Sphinx::Client instance:
+
+  results = Sphinx::Client.new.query('test') do
+    match_mode :any
+    ranking_mode :bm25
+    id_range 10, 1000
+  end
+
+As you can see, in this case you can omit the <tt>set_</tt> prefix for
+this methods. If block accepts a parameter, sphinx instance will be
+passed into the block. In this case you should you full method names
+including the <tt>set_</tt> prefix:
+
+  results = Sphinx::Client.new.query('test') do |sphinx|
+    sphinx.set_match_mode :any
+    sphinx.set_ranking_mode :bm25
+    sphinx.set_id_range 10, 1000
+  end
+
+== Example
+
+This simple example illustrates base connection establishing,
+search results retrieving, and excerpts building. Please note
+how does it perform database select using ActiveRecord to
+save the order of records established by Sphinx.
+
+  sphinx = Sphinx::Client.new
+  result = sphinx.query('test')
+  ids = result['matches'].map { |match| match['id'] }
+  posts = Post.all :conditions => { :id => ids },
+                   :order => "FIELD(id,#{ids.join(',')})"
+
+  docs = posts.map(&:body)
+  excerpts = sphinx.build_excerpts(docs, 'index', 'test')
+
+== Logging
+
+You can ask Sphinx client API to log it's activity to some log. In
+order to do that you can pass a logger object into the <tt>Sphinx::Client</tt>
+constructor:
+
+  require 'logger'
+  Sphinx::Client.new(Logger.new(STDOUT)).query('test')
+
+Logger object should respond to methods :debug, :info, and :warn, and
+accept blocks (this is what standard Ruby <tt>Logger</tt> class does).
+Here is what you will see in your log:
+
+* <tt>DEBUG</tt> -- <tt>query</tt>, <tt>add_query</tt>, <tt>run_queries</tt>
+  method calls with configured filters.
+* <tt>INFO</tt> -- initialization with Sphinx version, servers change,
+  attempts to re-connect, and all attempts to do an API call with server
+  where request being performed.
+* <tt>WARN</tt> -- various connection and socket errors.
+
+== Support
+
+Source code:
+http://github.com/kpumuk/sphinx
+
+To suggest a feature or report a bug:
+http://github.com/kpumuk/sphinx/issues
+
+Project home page:
+http://kpumuk.info/projects/ror-plugins/sphinx
+
+== Credits
+
+Dmytro Shteflyuk <kpumuk@kpumuk.info> http://kpumuk.info
+
+Andrew Aksyonoff http://sphinxsearch.com
+
+Special thanks to Alexey Kovyrin <alexey@kovyrin.net> http://blog.kovyrin.net
+
+Special thanks to Mike Perham http://www.mikeperham.com for his awesome
+memcache-client gem, where latest Sphinx gem got new sockets handling from.
+
+==License
+
+This library is distributed under the terms of the Ruby license.
+You can freely distribute/modify this library.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name        = 'sphinx'
+    gemspec.summary     = 'Sphinx Client API for Ruby'
+    gemspec.description = 'An easy interface to Sphinx standalone full-text search engine. It is implemented as plugin for Ruby on Rails, but can be easily used as standalone library.'
+    gemspec.email       = 'kpumuk@kpumuk.info'
+    gemspec.homepage    = 'http://github.com/kpumuk/sphinx'
+    gemspec.authors     = ['Dmytro Shteflyuk']
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts 'Jeweler not available. Install it with: sudo gem install jeweler'
+end
+
+begin
+  require 'spec/rake/spectask'
+
+  desc 'Default: run specs'
+  task :default => :spec
+
+  desc 'Test the sphinx plugin'
+  Spec::Rake::SpecTask.new do |t|
+    t.libs << 'lib'
+    t.pattern = 'spec/*_spec.rb'
+  end
+rescue LoadError
+  puts 'RSpec not available. Install it with: sudo gem install rspec'
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    t.options = ['--title', 'Sphinx Client API Documentation']
+    if ENV['PRIVATE']
+      t.options.concat ['--protected', '--private']
+    else
+      t.options << '--no-private' 
+    end
+  end
+rescue LoadError
+  puts 'Yard not available. Install it with: sudo gem install yard'
+end

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:major: 0
+:minor: 9
+:patch: 9
+:build: 2117

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/lib/sphinx'

data/lib/sphinx/buffered_io.rb

@@ -0,0 +1,26 @@
+# A simple wrapper around <tt>Net::BufferedIO</tt> performing
+# non-blocking select.
+#
+# @private
+class Sphinx::BufferedIO < Net::BufferedIO # :nodoc:
+  BUFSIZE = 1024 * 16
+
+  if RUBY_VERSION < '1.9.1'
+    def rbuf_fill
+      begin
+        @rbuf << @io.read_nonblock(BUFSIZE)
+      rescue Errno::EWOULDBLOCK
+        retry unless @read_timeout
+        if IO.select([@io], nil, nil, @read_timeout)
+          retry
+        else
+          raise Timeout::Error, 'IO timeout'
+        end
+      end
+    end
+  end
+
+  def setsockopt(*args)
+    @io.setsockopt(*args)
+  end
+end