thinking-sphinx 2.1.0 → 3.0.0.pre

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+.rbx
+Gemfile.lock
+*.sublime-*
+pkg/*
+spec/internal/config/test.sphinx.conf
+spec/internal/db/sphinx

data/.travis.yml

@@ -0,0 +1,13 @@
+rvm:
+  - 1.9.2
+  - 1.9.3
+before_install: gem update --system
+before_script:
+  - "mysql -e 'create database thinking_sphinx;' > /dev/null"
+  - "psql -c 'create database thinking_sphinx;' -U postgres >/dev/null"
+env:
+  - DATABASE=mysql2
+  - DATABASE=postgresql
+gemfile:
+  - gemfiles/rails_3_1.gemfile
+  - gemfiles/rails_3_2.gemfile

data/Appraisals

@@ -0,0 +1,7 @@
+appraise 'rails_3_1' do
+  gem 'rails',  '~> 3.1.0'
+end
+
+appraise 'rails_3_2' do
+  gem 'rails',  '~> 3.2.0'
+end

data/Gemfile

@@ -0,0 +1,10 @@
+source :rubygems
+
+gemspec
+
+gem 'combustion',
+  :git => 'git://github.com/pat/combustion.git',
+  :ref => '45f50e64c3'
+
+gem 'pg', '~> 0.11.0', :platform => :ruby
+gem 'activerecord-jdbcpostgresql-adapter', '~> 1.1.3', :platform => :jruby

data/HISTORY

@@ -1,267 +1,2 @@
-2.1.0 - May 7th 2013
-* 1.5.0 changes.
-
-2.0.14 - January 2nd 2013
-* Fix model loading for Rails 3.2.9 when subdirectories exist (Kenn Ejima).
-* Use BasicObject instead of BlankSlate when running on 1.9 (Steve Purcell).
-* 1.4.14 changes.
-
-2.0.13 - August 10th 2012
-* 1.4.13 changes.
-
-2.0.12 - May 14th 2012
-* STI fix when generating WHERE clauses for sql_query.
-* 1.4.12 changes.
-
-2.0.11 - January 2nd 2012
-* Call #all on search results to force population of results, matching ActiveRecord::Relation#all in essence. (Adrian Macneil).
-* 1.4.11 changes.
-
-2.0.10 - November 4th 2011
-* 1.4.10 changes.
-
-2.0.9 - October 10th 2011
-* 1.4.9 changes (fixed invalid gemspec).
-
-2.0.8 - October 10th 2011
-* Actually looking at Rails engines paths for models (Eduardo Casanova).
-* Ensuring associations for acts-as-taggable-on are tweaked for Rails 3.1 (Anthony).
-* Bug fix for association collection proxies in Rails 3.1 (Pavel Forkert).
-* References all known Rails model paths - better for Rails 3 Engines.
-* Don't reload I18n anymore - the load order isn't an issue in Rails 3 or 3.1.
-* Fixing attribute source queries for Rails 3.1.
-* 1.4.8 changes
-
-2.0.7 - August 29th 2011
-* Making sure lib directory is actually a part of the gem. Oops.
-
-2.0.6 - August 28th 2011
-* Don't change superclass index definitions (otherwise sibling subclasses can end up with each others' index definitions).
-* Improved scope support (Andrew White).
-* Fixed association-filtered searches for Rails 3.1 (Andrew White).
-* Fixed polymorphic association support for Rails 3.1 (Jonathan Viney).
-* 1.4.7 changes.
-
-2.0.5 - May 25th 2011
-* Railtie equivalent for Sinatra.
-* Rails 3.1 support (Florent Piteau).
-* 1.4.6 changes.
-
-2.0.4 - May 12th 2011
-* Only determine Sphinx version when initializing Thinking Sphinx, instead of upon require.
-* Still execute logged blocks for searching even when logging isn't enabled.
-* 1.4.5 changes.
-
-2.0.3 - April 3rd 2011
-* 1.4.4 changes.
-
-2.0.2 - January 13th 2011
-* Improvement to loading the environment via Rake (Brenton Fletcher).
-* 1.4.2 changes.
-* 1.4.1 changes.
-
-2.0.1 - November 19th 2011
-* Intermittent as_json bug fix.
-* Using Rails 3 logging system (Stephen Celis).
-* Fixes for Rails 3.0.2 (Ivan Ukhov).
-
-2.0.0 - November 14th 2011
-* Handle has_many conditions defined as a hash (Artem Orlov).
-* Deprecation fixes for logging (Anton Sozontov).
-* Only load Thinking Sphinx if ActiveRecord is loaded (Matthew Higgins).
-* Rails 3 support.
-* 1.4.0 changes.
-
-1.5.0 - May 7th 2013
-* Removed plugin support - Thinking Sphinx is now gem-only across all branches.
-* ThinkingSphinx::Version and the thinking_sphinx:version task have been removed - it's a gem, it has a version number.
-* Updating Riddle to 1.5.6 or newer.
-* Requires ActiveRecord ~> 2.1 (earlier versions were considered unsupported a few releases ago).
-* Allow custom Riddle controllers - useful for Flying Sphinx to take over management of Sphinx daemon/indexing actions.
-* Rejigged delta support to be generic, with local job classes that provide a clean, simple interface for third-party libraries.
-* Add hooks for anything that needs to happen before indexing (such as clearing out existing delta jobs).
-* Connection pool for all Sphinx client communication, with new connections built if there's any connection-related (as opposed to syntax) issues.
-* Multiple-field search conditions can be done with arrays of field names as keys in the :conditions hash (Alex Dowad).
-* Removed named capture in regular expressions to maintain MRI 1.8 support (Michael Wintrant).
-* Support new JDBC configuration style (Kyle Stevens).
-
-1.4.14 - January 2nd 2013
-* Allow sql_query_pre values to come through from config/sphinx.yml (George Ogata).
-* ThinkingSphinx::Search#tap doesn't delegate through to the underlying array.
-* Use fire_delta? instance method in the model (if it exists) to decide whether indexing should happen.
-* Use full query in excerpts so double-stemming of terms is avoided (Jason Rust).
-* Fix thinking_sphinx:version rake task.
-* Directly compare non-string non-nil facet values for facet filters.
-* Don't bother checking with Sphinx whether documents exist when trying to update them. We're catching failures already (and Sphinx usually doesn't care anyway).
-
-1.4.13 - August 10th 2012
-* Sphinx 2.0.5 support.
-* Hard retries for Sphinx exceptions (Andrew Hunter).
-* Add support for association-filtered faceting (Andrew White).
-* Cast PostgreSQL timestamps to their floored integers (instead of rounding up).
-* Don't add array_accum to PostgreSQL v80311 (8.3.?) or newer.
-
-1.4.12 - May 14th 2012
-* Updating Riddle references to 1.5.2.
-* Can explicitly specify available types for STI tables instead of automatically discovering them with "SELECT DISTINCT type FROM <table>" (Cedric Maion).
-* Don't try to run rake tasks for Capistrano if there's no Rakefile - eg. on fresh deploys (Nathan Smith).
-* Populate search results before comparing with #==.
-* Can indicate whether Sphinx should use a socket for connections instead of TCP (Simon Hürlimann).
-* Can have just attribute values returned as search results using `:attributes_only => true` in a search call (Andrew Hunter).
-* Can specify additional local indices for the generated distributed index (usually one per model) (Andrew Hunter).
-* Supporting Sphinx 2.0.4 (Ilia Lobsanov).
-* Load MySQL SSL settings from database.yml (James Brooks).
-* Adding Sphinx 2.0.3 support (identical to 2.1.0).
-* Dropping Rails 1.2 and 2.0.x support.
-* Association keys now are the association stacks as arrays - more reliable in Rubinius.
-* Can now determine PostgreSQL versions with JRuby.
-* Many testing tweaks.
-* Allow for rank_expr option being passed through to Riddle.
-
-1.4.11 - January 2nd 2012
-* Handle no results for total_pages and total_entries with defaults of 0.
-* No longer shuffle Sphinx addresses by default.
-* Fix coalescing of non-char values in PostgreSQL (Matthew Barnett).
-* Default database user for Sphinx configuration is now ENV['USER'], not root.
-* Alias offset to offset_value for Kaminari.
-* Sphinx 2.1.0-dev support.
-
-1.4.10 - November 4th 2011
-* Updating Riddle references for impending 1.5.0 release of Riddle.
-* Handle out-of-date indexed_models references.
-* Fixing STI model handling during context index loading (Kenn Ejima).
-
-1.4.9 - October 10th 2011
-* Fixing invalid gemspec.
-
-1.4.8 - October 10th 2011
-* Adding smart default (id) for primary key column name.
-* Making error message when daemon fails to start a little more helpful (Tony Pitale).
-* Adding ThinkingSphinx::Search#last_page? for Kaminari (Pete Deffendol).
-* If ENV['NODETACH'] is set when calling ts:start, pass that flag through to Riddle to start Sphinx in the foreground (Aaron Gibralter).
-* Catch and report all errors when models are loaded (Martin Gordon).
-* Bringing in builder gem's BlankSlate for our Builder - better at keeping global Rake methods out of the way.
-* Use PostgreSQL's array_agg function if it exists, instead of array_accum (PG v8.4 or newer).
-* Shuffle multiple Sphinx addresses by default, but allow that to be turned off (Ngan Pham).
-* Fix string attributes when using Sphinx 2.0.1 and bin_path.
-
-1.4.7 - August 28th 2011
-* Don't search for objects when updating attributes on every save - if the object isn't there, then the error will be caught anyway.
-* Extra flexibility for association attribute references (Andrew White).
-* Setting up test suite for Travis, and fixing tests across many rubies.
-* Removing test for filtering on wordcount attribute - seems Sphinx doesn't like that.
-* If many indices are searched on, only use the first for excerpts.
-* Allow MVA facets from SQL strings that are all integers to skip object translation.
-* Adding total_count method for better Kaminari support (Dan Pickett).
-* Switching from Jeweler to Bundler for gem management.
-* Cleaning up Context - re-using camelized class names.
-* Simplified auto-star regex for 1.9 - no need to set the unicode flag.
-* Don't update sphinx_internal_id attribute when updating a record's attributes.
-* Ignore empty arrays for :without_ids (Jason Rust).
-* Now catching Riddle::ResponseError when we aren't fussed about the responses from Sphinx.
-* Distinguishing between Ruby 1.8 and 1.9 for auto-star regex (Andrew White).
-* Don't re-index at the end of suspended_delta calls if requested.
-* Adding stop_timeout setting to configure how long ts:stop should wait while checking whether Sphinx has stopped (Justin Tanner).
-* Speed improvement for types_to_crcs (Josh Goebel).
-* Adding a touched_reindex_file option, for a file that will be touched after indices are rotated (Rémi Prévost).
-* Better support for the Mysql2 adapter (Andrew White).
-* More pagination methods - next_page? and first_page?.
-* Adding use_64_bit option to ensure all timestamp attributes are treated as 64 bit integers (Andrey Deryabin).
-* Simpler, less brittle support for all Sphinx settings via Riddle (Clemens Kofler).
-* Optimised start/stop behaviour in Capistrano recipe (Lars Weiler).
-* Catch and ignore timeout errors for low priority requests.
-* Don't double up on de-polymorphised associations for generated Sphinx source SQL queries.
-
-1.4.6 - May 25th 2011
-* Require Riddle 1.3.3 or better.
-* Cast Sphinx document ids to 32bit integers to keep PostgreSQL happy when Sphinx is compiled for id64 support (Bruno Santschi).
-* Making sure suspended_delta always exists on indexed models, whether indices have been defined or not.
-* Workaround for ActsAsTaggableOn to ensure association joins work.
-* Use Sphinx string attributes instead of class_crc integers to determine which class each search result is from (Sphinx 2.x or newer).
-* String attribute support - and so, using this instead of str2ordinal for string sorting.
-* Support for fields with paired string attributes and wordcount attributes (Sphinx 1.10-beta or newer).
-* Support for file fields (Sphinx 1.10-beta or newer).
-* Wordcount attribute support (Sphinx 1.10-beta or newer).
-* Sinatra support is only used when Rails isn't loaded.
-* Sphinx 2.0.x (including 2.0.2-dev) support.
-* :without_any filtering option (the reverse of :with_all).
-
-1.4.5 - May 12th 2011
-* Require Riddle 1.3.2 or better.
-* Improved 1.9.2 support
-* Don't hack Array - make ThinkingSphinx::Search a subclass of Array instead.
-* Distinguishing between suspended deltas and disabled deltas.
-* Removing most Thread references, opting for Mutexes for better multi-threading support.
-* Added support for client_key to allow for authenticated Sphinx communication.
-* Sphinx 2.0.1 support.
-* Don't try to translate nil values (Alex Chee).
-* Performance fix for facets (Clemens Kofler).
-* Use Sphinx 0.9.9 in Capistrano recipe (Konstantin Shabanov).
-* Sinatra support (Patrick Tulskie).
-* Offer sanitize_sql method within define_index blocks (Matt Todd).
-* Performance fix: caching primary_key_for_sphinx value.
-
-1.4.4 - April 3 2011
-* Being consistent with === comparisons for Array monkeypatch.
-* Kaminari pagination support.
-* Ensure deltas are supported across multiple indices for a given model.
-* Use custom index names for excerpts calls if that's what exists (Javier Ramírez).
-* Allow for Sphinx versions compiled from source (Greg Weber).
-* Ensuring thread is being required to allow Mutexes to work.
-* Ensure primary_key_for_sphinx is inherited to subclasses (Robert Stern).
-* Don't complain if there's an error when checking for documents in a given index.
-
-1.4.3 - January 29th 2011
-* Don't memoize the database adapter.
-* Allow queries to just return specific attributes via the :only option, instead of ActiveRecord objects (Hans Hasselberg).
-* Performance fix: Only add sphinx scopes to has_many associations if there are scopes in play (Kirill Maximov).
-* Fixing CRC32 function for PostgreSQL to handle UTF characters that use more than one byte.
-
-1.4.2 - January 13th 2011
-* Ignore Sphinx errors when updating attributes (it's a low priority request).
-* Don't use the CRC32 function within the generated SQL queries for class types.
-* Direct facets to use a method to translate values using :value.
-* Ensure that if one sphinx_internal_id attribute is a bigint, they all are.
-* Ignore Sphinx errors when marking documents as deleted (it's a low priority request).
-* Don't select columns from polymorphic joins if they're not available.
-* Don't query Sphinx for a facet request if zero facets are requested.
-* Ensure we're only using local_options when it's available (Paul Schyska).
-* Don't presume the environment for Capistrano is production (Robert Glaser).
-* Allow for custom database adapters.
-* Fix for custom delta columns (Marcin Stecki).
-
-1.4.1 - December 21st 2010
-* No longer looking for attributes in :conditions option when searching.
-* Copy and then modify sort arguments.
-* Allow the generation of Sphinx configuration objects without necessarily writing to the configuration file.
-* Allow Sphinx 1.10-beta versions that have been compiled with id64 support.
-* Raise Sphinx errors when searching - which can be ignored using the :ignore_errors option (Matt Todd).
-* Handle complex :include arguments, including hashes within arrays (Paco Guzmán).
-* Handle hashes passed through to :include when searching.
-* Can now require either 'thinking_sphinx' or 'thinking-sphinx'.
-* Excerpts are less fussy about inputs.
-* No longer hard-coding RSpec colour setting - that's up to the developer.
-* Require Riddle 1.2.0 or better.
-* Use searchd to stop Sphinx (via --stop or --stopwait arguments) (Matt Todd).
-
-1.4.0 - November 14th 2010
-* No longer supporting attributes in :conditions option.
-* Case insensitive field sorting if :sortable is set to :insensitive.
-* Using Bundler for development
-* Can use make facet requests on existing searches and Sphinx scopes.
-* Don't star field markers in search queries.
-* Can use search_for_ids on Sphinx scopes.
-* Ensure the CRC32 function for PostgreSQL handles empty strings and NULLs.
-* Allow custom determination for database adapters.
-* :include search option now limits itself to the relevant classes when searching across more than one class.
-* Don't memoize primary_key_for_sphinx, which was causing trouble when objects are deleted or frozen.
-* Allow for excerpts options when searching (using :excerpt_options) (Lee Capps).
-* Wrap UTC in quotes when setting the timezone in PostgreSQL (Keith Pitt).
-* Don't colourize logs unless ActiveRecord allows for it.
-* Consistent contribution documentation (Sam Goldstein).
-* Allow the setting of Riddle's timeout value via sphinx.yml (Sam Goldstein).
-* 1.10-beta support.
-* Can set the riddle client for the search request using :client.
-* Fixing default sphinx scope support.
-* Make a reasonable attempt to check that Sphinx has stopped (Matt Todd).
-* Be more verbose if a model can't be loaded by Thinking Sphinx.
+2012-10-06: 3.0.0.pre
+* First pre-release. Not quite feature complete, but the important stuff is certainly covered. See the README for more the finer details.

data/LICENCE

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Pat Allan
+Copyright (c) 2011 Pat Allan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.textile

@@ -1,236 +1,204 @@
 h1. Thinking Sphinx
 
-Please note: this is the branch for Rails 3. At some point in the near future, it will be released as Thinking Sphinx 2.0. It does not work with versions of Rails before v3 - I'm not sure if that'll happen in the future, but was just too much hassle right now.
+Welcome to Thinking Sphinx version 3 - a complete rewrite from past versions. Right now it is a work-in-progress, though it does include most of the more popular features from TS 2 and earlier. It's also currently built for Rails 3.1 or newer only.
 
-If you want to give this a spin, clone the repo, check out the rails3 branch, and run @rake build@ to generate the gem.
+Still interested? Well, read on!
+
+h2. Installation
+
+There's only a pre-release gem available at this point - or you can use the git repository reference (the edge branch is what you're after). Also, you'll need to specify the Mysql2 gem as well (this is not an inbuilt dependency because JRuby, when supported, will need something different):
+
+<pre><code>gem 'mysql2',          '0.3.12b4'
+gem 'thinking-sphinx', '3.0.0.pre'</code></pre>
 
 h2. Usage
 
-First, if you haven't done so already, check out the main "usage":http://ts.freelancing-gods.com/usage.html page. Once you've done that, the next place to look for information is the specific method docs - ThinkingSphinx::Search and ThinkingSphinx::Index::Builder in particular.
+Indexes are no longer defined in models - they now live in `app/indices` (which you will need to create yourself). Each index should get its own file, and look something like this:
+
+<pre><code># app/indices/article_index.rb
+ThinkingSphinx::Index.define :article, :with => :active_record do
+  indexes title, content
+  indexes user.name, :as => :user
+  indexes user.articles.title, :as => :related_titles
+
+  has published
+end</code></pre>
+
+You'll notice the first argument is the model name downcased and as a symbol, and we are specifying the processor - @:active_record@. Everything inside the block is just like previous versions of Thinking Sphinx. Same goes for @config/thinking_sphinx.yml@ (formerly @config/sphinx.yml@).
+
+Other changes:
+* SphinxQL is now used instead of the old socket connections (hence the dependency on the @mysql2@ gem).
+* You'll need to include @ThinkingSphinx::Scopes@ into your models if you want to use Sphinx scopes.
+* The match mode is always extended - SphinxQL doesn't know any other way.
+* ActiveRecord::Base.set_sphinx_primary_key is now an option in the index definition (alongside @:with@ in the above example): @:primary_key@ - and therefore is no longer inheritable between models.
+* If you're explicitly setting a time attribute's type, instead of @:datetime@ it should now be @:timestamp@.
+* Delta arguments are passed in as an option of the @define@ call, not within the block:
+
+<pre><code>ThinkingSphinx::Index.define :article, :with => :active_record, :delta => true do
+  # ...
+end</code></pre>
+
+* Suspended deltas are no longer called from the model, but like so instead:
+
+<pre><code>ThinkingSphinx::Deltas.suspend :article do
+  article.update_attributes(:title => 'pancakes')
+end</code></pre>
+
+* Excerpts through search results behaves the same way, provided you add ExcerptsPane into the mix (read the section below on search results, glazes and panes). Excerpt options (like @:before_match@, @:after_match@ and @:chunk_separator@) can be passed through when searching under the @:excerpts@ option:
+
+<pre><code>ThinkingSphinx.search 'foo',
+  :excerpts => {:chunk_separator => ' -- '}</code></pre>
+
+* When indexing models on classes that are using single-table inheritance (STI), make sure you have a database index on the @type@ column. Thinking Sphinx will need to determine which subclasses are available, and we can't rely on Rails having loaded all models at any given point, so it queries the database. If you don't want this to happen, set :skip_sti to true in your search call, and ensure that the :classes option holds all classes that could be returned.
+
+<pre><code>ThinkingSphinx.search 'pancakes',
+  :skip_sti => true,
+  :classes => [User, AdminUser, SupportUser]</code></pre>
+
+* The option @:rank_mode@ has now become @:ranker@ - and the options (as strings or symbols) are as follows: proximity_bm25, bm25, none, wordcount, proximity, matchany, and fieldmask.
+* There are no explicit sorting modes - all sorting must be on attributes followed by ASC or DESC. For example: @:order => '@weight DESC, created_at ASC'@.
+* If you specify just an attribute name as a symbol for the @:order@ option, it will be given the ascending direction by default. So, @:order => :created_at@ is equivalent to @:order => 'created_at ASC'@.
+* If you want to use a calculated expression for sorting, you must specify the expression as a new attribute, then use that attribute in your @:order@ option. This is done using the @:select@ option to specify extra columns available in the underlying SphinxQL (_not_ ActiveRecord/SQL) query.
+
+<pre><code>ThinkingSphinx.search(
+  :select => '@weight * 10 + document_boost as custom_weight',
+  :order  => :custom_weight
+)</code></pre>
+
+* Support for latitude and longitude attributes named something other than 'lat' and 'lng' or 'latitude' and 'longitude' has been removed. May add it back in if requested, but would be surprised if it's a necessary feature.
+* Set INDEX_ONLY to true in your shell for the index task to re-index without regenerating the configuration file.
+* If you want to pass the old-style @:include@, @:joins@, @:select@ or @:order@ parameters through to the underlying ActiveRecord SQL queries for instantiating search results, they should go in a hash within the search option @:sql@:
+
+<pre><code>Article.search :sql => {:include => :user}</code></pre>
+
+* SphinxQL only supports grouping by single attributes - but these attributes may be generated on the fly within the select statement (see the @:select@ option above). A grouped search uses the @:group_by@ option, and you can pass in the attribute name as either a symbol or a string:
+
+<pre><code>Article.search :group_by => :user_id</code></pre>
+
+* If you want to change the order of which result appears for each group, that can be done via the @:order_group_by@ option - which behaves just like @:order@ does:
+
+<pre><code>Article.search(
+  :group_by       => :user_id,
+  :order_group_by => 'created_at DESC'
+)</code></pre>
+
+* The @each_with_group@, @each_with_count@ and @each_with_group_and_count@ enumerators are available when using the @:group_by@ option (but are otherwise not available to search objects). Please note the spelling - older versions of Thinking Sphinx allowed for groupby and group, this is no longer the case.
+* @each_with_weight@ (again, note that it's weight, not weighting) is available, but not by default. Here's an example of how to have it part of the search object:
+
+<pre><code>search = Article.search('pancakes', :select => '*, @weight')
+search.masks << ThinkingSphinx::Masks::WeightEnumeratorMask
+
+search.each_with_weight do |article, weight|
+  # ...
+end</code></pre>
+
+You'll also note here that I'm specifying the internal weight attribute. This is necessary for edge Sphinx post 2.0.5.
+
+* Batched/Bulk searches are done pretty similarly as in the past - here's a code sample that'll only hit Sphinx once:
+
+<pre><code>batch = ThinkingSphinx::BatchedSearch.new
+batch.searches << Article.search('foo')
+batch.searches << Article.search(:conditions => {:name => 'bar'})
+batch.searches << Article.search_for_ids('baz')
+
+# When you call batch#populate, the searches are all populated with a single
+# Sphinx call.
+batch.populate
+
+batch.searches #=> [[foo results], [bar results], [baz results]]</code></pre>
+
+* To search on specific indices, use the @:indices@ option, which expects an array of index names (including the @_core@ or @_delta@ suffixes).
+* @:without_any@ has become @:without_all@ - and is implemented, but Sphinx doesn't yet support the required logic.
+* If you're creating a multi-value attribute manually (using a SQL snippet), then in the definition pass in @:multi => true@, but @:type@ should be set as well, to one of the MVA types that Sphinx supports (@:integer@, @:timestamp@, or @:boolean@).
+* Automatic updates of non-string attributes are still limited to those from columns on the model in question, and is disabled by default. To enable it, just set attribute_updates to true in your @config/sphinx.yml@.
+* Search result helper methods are no longer injected into the actual result objects. Read the section below on search results, glazes and panes.
+* If you're using string facets, make sure they're defined as fields, not strings. There is currently no support for multi-value string facets.
 
-Keep in mind that while Thinking Sphinx works for ActiveRecord with Merb, it doesn't yet support DataMapper (although that is planned).
+h2. Search Middleware
+
+This section needs information - go hunting in the source for the moment if you're keen on adding a layer around querying/result population process.
+
+h2. Search results, Glazes and Panes
+
+In versions of Thinking Sphinx prior to v3, each search result object had many methods inserted into it - for direct access to the weight, distance, sphinx attributes and excerpts. This is no longer the case, but there is a more modular approach available.
+
+Search results may now have a glaze object placed around them, which can then delegate methods to any number of panes the glaze has available. By default, there are no panes added (and thus, no glazing), but this can be modified:
+
+<pre><code># For every search
+ThinkingSphinx::Configuration::Defaults::PANES << ThinkingSphinx::Panes::WeightPane
+
+# Or for specific searches:
+search = ThinkingSphinx.search('pancakes')
+search.context[:panes] << ThinkingSphinx::Panes::WeightPane</code></pre>
+
+The available panes are as follows:
+
+* @WeightPane@ (methods: @weight@)
+* @DistancePane@ (methods: @distance@, @geodist@)
+* @AttributesPane@ (methods: @sphinx_attributes@)
+* @ExcerptsPane@ (methods: @excerpts@)
+
+All panes namespaced to @ThinkingSphinx::Panes@, and the @DistancePane@ is automatically added when you provide latitude/longitude values via the @:geo@ option.
+
+If you wish to add your own panes, go ahead. The only requirement is that the initializer must accept three arguments: the search context, the underlying search result object, and a hash of the raw values from Sphinx.
+
+h2. Limitations
+
+Basic indexing and searching should be fine. There's currently only limited basic delta support. Some settings haven't yet been brought across. Many of the smaller features don't yet exist either. Some may actually not return... we'll see.
+
+Lists of what still needs to be implemented, in no particular order but in groups of vague importance:
+
+Required for Release Candidate:
+
+* Query and Ranged Query sources for Attributes and Fields
+* Using :though association shortcuts in index definitions
+* Overwritable toggle_delta? method on model
+* Query times for searches
+* Namespaced models support
+* Delayed Deltas
+* Infixing and Prefixing of specific fields
+* Default Sphinx scopes
+* sanitise_sql method in index definitions
+* Multiple sources for an index
+* JRuby support
+* Sinatra support
+* Wordcount fields and attributes
+
+May or may not be added:
+
+* Datetime Deltas
+* Bitmask weighting helper
+* Timezone support (for databases not using UTC)
+* Abstract Inheritance support (maybe - not sure this is something many of people want).
+* Capistrano Tasks
+* Facet support for arrays of strings.
+
+h3. Sphinx Versions
+
+TS 3 is built for Sphinx 2.x only. You cannot use 1.10-beta, 0.9.9 or anything earlier than that.
+
+h3. Rails Versions
+
+Currently TS 3 is built to support Rails/ActiveRecord 3.1 or newer. Sinatra is not yet supported, but it will be.
+
+TS 3 does not support Rails 3.0, Rails 2.x or earlier, or Merb - please refer to the TS 1.x and 2.x releases in those situations.
+
+h3. Ruby Versions
+
+Built on MRI 1.9.3 and tested against MRI 1.9.2 as well. No plans to support MRI 1.8, but would like to support Rubinius and JRuby (the one catch with the latter is the different MySQL interfaces).
+
+h3. Database Versions
+
+MySQL 5.x and Postgres 8.4 or better are supported.
 
 h2. Contributing
 
-Fork on GitHub and after you've committed tested patches, send a pull request.
-
-To quickly see if your system is ready to run the thinking sphinx specs, run the contribute.rb script found in the project root directory. Use the following instructions to install any missing requirements.
-
-To get the spec suite running, you will need to install the ginger gem:
-
-<pre><code>sudo gem install ginger --source http://gemcutter.org</code></pre>
-
-Then install the cucumber, yard, jeweler and rspec gems. Make sure you have a git install version 1.6.0.0 or higher, otherwise the jeweler gem won't install. Bluecloth is required for some of the yard documentation.
-
-<pre>
-  sudo gem install bluecloth cucumber yard jeweler rspec
-</pre>
-
-Then set up your database:
-
-<pre>
-  cp spec/fixtures/database.yml.default spec/fixtures/database.yml &&
-  mysqladmin -u root create thinking_sphinx
-</pre>
-
-This last step can be done automatically by the contribute.rb script if all dependencies are met.
-
-Make sure you don't have another Sphinx daemon (searchd) running. If you do, quit it with "rake ts:stop"
-in the app root.
-
-You should now have a passing test suite from which to build your patch on.
-
-<pre>
-  rake spec
-</pre>
-
-If you get the message "Failed to start searchd daemon", run the spec with sudo:
-
-<pre>
-  sudo rake spec
-</pre>
-
-If you quit the spec suite before it's completed, you may be left with data in the test
-database, causing the next run to have failures. Let that run complete and then try again.
-
-h2. Contributors
-
-Since I first released this library, there's been quite a few people who have submitted patches, to my immense gratitude. Others have suggested syntax changes and general improvements. So my thanks to the following people:
-
-* Joost Hietbrink
-* Jonathan Conway
-* Gregory Mirzayantz
-* Tung Nguyen
-* Sean Cribbs
-* Benoit Caccinolo
-* John Barton
-* Oliver Beddows
-* Arthur Zapparoli
-* Dusty Doris
-* Marcus Crafter
-* Patrick Lenz
-* Björn Andreasson
-* James Healy
-* Jae-Jun Hwang
-* Xavier Shay
-* Jason Rust
-* Gopal Patel
-* Chris Heald
-* Peter Vandenberk
-* Josh French
-* Andrew Bennett
-* Jordan Fowler
-* Seth Walker
-* Joe Noon
-* Wolfgang Postler
-* Rick Olson
-* Killian Murphy
-* Morten Primdahl
-* Ryan Bates
-* David Eisinger
-* Shay Arnett
-* Minh Tran
-* Jeremy Durham
-* Piotr Sarnacki
-* Matt Johnson
-* Nicolas Blanco
-* Max Lapshin
-* Josh Natanson
-* Philip Hallstrom
-* Christian Rishøj
-* Mike Flester
-* Jim Remsik
-* Kennon Ballou
-* Henrik Nyh
-* Emil Tin
-* Doug Cole
-* Ed Hickey
-* Evan Weaver
-* Thibaut Barrere
-* Kristopher Chambers
-* Dmitrij Smalko
-* Aleksey Yeschenko
-* Lachie Cox
-* Lourens Naude
-* Tom Davies
-* Dan Pickett
-* Alex Caudill
-* Jim Benton
-* John Aughey
-* Keith Pitty
-* Jeff Talbot
-* Dana Contreras
-* Menno van der Sman
-* Bill Harding
-* Isaac Feliu
-* Andrei Bocan
-* László Bácsi
-* Peter Wagenet
-* Martin Emde
-* David Wennergren
-* Mark Lane
-* Eric Lindvall
-* Lawrence Pit
-* Mike Bailey
-* Bill Leeper
-* Michael Reinsch
-* Anderson Dias
-* Jerome Riga
-* Tien Dung
-* Johannes Kaefer
-* Paul Campbell
-* Matthew Beale
-* Tom Simnett
-* Erik Ostrom
-* Ole Riesenberg
-* Josh Kalderimis
-* J.D. Hollis
-* Jeffrey Chupp
-* Rob Anderton
-* Zach Inglis
-* Ward Bekker
-* Brian Terlson
-* Christian Aust
-* Martin Sarasale
-* Édouard Brière
-* Steve Madsen
-* Justin DeWind
-* Chris Z
-* Chris Roos
-* Andrew Assarattanakul
-* Jonas von Andrian
-* Dimitri Krassovski
-* Sergey Kojin
-* Brad Sumersford
-* Amir Yalon
-* Edgars Beigarts
-* Ivan Ukhov
-* Tomáš Pospíšek
-* Jeffrey Hardy
-* David Heinemeier Hansson
-* Jimmy Hsu
-* Bruno Michel
-* Joren De Groof
-* Jan De Poorter
-* Tom Stuart
-* James Brooks
-* Andrew Coldham
-* Mark Dodwell
-* Frédéric Malamitsas
-* Jon Gubman
-* Michael Schuerig
-* Ben Hutton
-* Alfonso Jiménez
-* Szymon Nowak
-* Matthew Higgins
-* Anton Sozontov
-* Keith Pitt
-* Lee Capps
-* Sam Goldstein
-* Artem Orlov
-* Matt Todd
-* Ivan Ukhov
-* Stephen Celis
-* Paco Guzmán
-* Marcin Stecki
-* Robert Glaser
-* Brenton Fletcher
-* Paul Schyska
-* Kirill Maximov
-* Hans Hasselberg
-* Robert Stern
-* George Anderson
-* Greg Weber
-* Javier Ramírez
-* Patrick Tulskie
-* Konstantin Shabanov
-* Clemens Kofler
-* Ryan Mohr
-* Alex Chee
-* Florent Piteau
-* Bruno Santschi
-* Lars Weiler
-* Andrey Deryabin
-* Andrew White
-* Rémi Prévost
-* Justin Tanner
-* Josh Goebel
-* Jonathan Viney
-* Ngan Pham
-* Martin Gordon
-* Aaron Gibralter
-* Pavel Forkert
-* Anthony Byram
-* Pete Deffendol
-* Eduardo Casanova
-* Tony Pitale
-* Kenn Ejima
-* Matthew Barnett
-* Adrian Macneil
-* Ilia Lobsanov
-* Andrew Hunter
-* Simon Hürlimann
-* Nathan Smith
-* Cedric Maion
-* Steve Purcell
-* George Ogata
+You're brave! To contribute, clone this repository and have a good look through the specs - you'll notice the distinction between acceptance tests that actually use Sphinx and go through the full stack, and unit tests (everything else) which use liberal test doubles to ensure they're only testing the behaviour of the class in question. I've found this leads to far better code design.
+
+If you're still interested in helping evolve this, then write the tests and then the code to get them passing, and send through a pull request. No promises on merging anything, but we shall see!
+
+For some ideas behind my current approach, have a look through @sketchpad.rb@ in the root of this project. If you can make sense of that, you're doing very well indeed.
+
+h2. Licence
+
+Copyright (c) 2007-2012, Thinking Sphinx is developed and maintained by Pat Allan, and is released under the open MIT Licence. Many thanks to "all who have contributed patches":https://github.com/freelancing-god/thinking-sphinx/contributors.