README

This client has been written to interface with Sphinx[http://sphinxsearch.com/]. It is written by
{Pat Allan}[http://freelancing-gods.com], and has been influenced by both Dmytro Shteflyuk's Ruby
client and the original PHP client - credit where credit's due, after all.

It does not follow the same syntax as those two, though (not much point writing this otherwise) -
opting for a more Ruby-like structure.

The easiest way to install is to grab the gem from GitHub:

  sudo gem install freelancing-god-riddle --source http://gems.github.com/

However, if you're so inclined, you can grab sourcecode.

  git clone git://github.com/freelancing-god/thinking-sphinx.git

If you're looking for old versions - for older versions of Sphinx - you'll want to peruse the tagged versions in the old subversion repository

  svn co http://rails-oceania.googlecode.com/svn/patallan/riddle/tags riddle-tags

Please note that at the time of writing, the following versions are supported (if you get the appropriate tag):

* 0.9.8-r871
* 0.9.8-r909
* 0.9.8-r985
* 0.9.8-r1065
* 0.9.8-r1112
* 0.9.8-rc1 (gem version: 0.9.8.1198)
* 0.9.8-rc2 (gem version: 0.9.8.1231)
* 0.9.8 (gem version: 0.9.8.1371)

To get started, just instantiate a Client object:

  client = Riddle::Client.new # defaults to localhost and port 3312
  client = Riddle::Client.new "sphinxserver.domain.tld", 3333 # custom settings
  
And then set the parameters to what you want, before running a query:

  client.match_mode = :extended
  client.query "Pat Allan @state Victoria"
  
The results from a query are similar to the other clients - but here's the details. It's a hash with
the following keys:

* :matches
* :fields
* :attributes
* :attribute_names
* :words
* :total
* :total_found
* :time
* :status
* :warning (if appropriate)
* :error (if appropriate)

The key <tt>:matches</tt> returns an array of hashes - the actual search results. Each hash has the
document id (<tt>:doc</tt>), the result weighting (<tt>:weight</tt>), and a hash of the attributes for
the document (<tt>:attributes</tt>).

The <tt>:fields</tt> and <tt>:attribute_names</tt> keys return list of fields and attributes for the
documents. The key <tt>:attributes</tt> will return a hash of attribute name and type pairs, and
<tt>:words</tt> returns a hash of hashes representing the words from the search, with the number of
documents and hits for each, along the lines of:

  results[:words]["Pat"] #=> {:docs => 12, :hits => 15}
  
<tt>:total</tt>, <tt>:total_found</tt> and <tt>:time</tt> return the number of matches available, the
total number of matches (which may be greater than the maximum available), and the time in milliseconds
that the query took to run.

<tt>:status</tt> is the error code for the query - and if there was a related warning, it will be under
the <tt>:warning</tt> key. Fatal errors will be described under <tt>:error</tt>.

If you've installed the gem and wondering why there's no tests - check out the svn version. I've kept the specs out of the gem as I have a decent amount of test data in there, which really isn't needed unless you want to submit patches.

== Contributors

Thanks to the following people who have contributed to Riddle in some shape or form:

* Andrew Aksyonoff
* Brad Greenlee
* Lachie Cox
* Jeremy Seitz
* Mark Lane