sphinx 0.9.10.2094 → 0.9.10.2122

data/README.rdoc

@@ -1,4 +1,4 @@
-= Sphinx Client API 0.9.10
+= 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, 
@@ -138,10 +138,10 @@ will be finally executed successfully.
 Most Sphinx API methods expecting for special constants will be passed.
 For example:
 
-  sphinx.set_match_mode(Sphinx::Client::SPH_MATCH_ANY)
+  sphinx.set_match_mode(Sphinx::SPH_MATCH_ANY)
 
-Please note that these constants defined in a <tt>Sphinx::Client</tt>
-namespace. You can use symbols or strings instead of these awful
+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)
@@ -195,6 +195,26 @@ save the order of records established by Sphinx.
   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:

data/VERSION.yml

@@ -2,4 +2,4 @@
 :major: 0
 :minor: 9
 :patch: 10
-:build: 2094
+:build: 2122

data/lib/sphinx.rb

@@ -3,7 +3,7 @@
 # Author::    Dmytro Shteflyuk <mailto:kpumuk@kpumuk.info>.
 # Copyright:: Copyright (c) 2006 — 2009 Dmytro Shteflyuk
 # License::   Distributes under the same terms as Ruby
-# Version::   0.9.10-r2091
+# Version::   0.9.10-r2122
 # Website::   http://kpumuk.info/projects/ror-plugins/sphinx
 # Sources::   http://github.com/kpumuk/sphinx
 #
@@ -15,15 +15,36 @@ module Sphinx
     config = YAML.load(File.read(File.dirname(__FILE__) + '/../VERSION.yml'))
     "#{config[:major]}.#{config[:minor]}.#{config[:patch]}.#{config[:build]}"
   end
+
+  # Base class for all Sphinx errors
+  class SphinxError < StandardError; end
+
+  # Connect error occurred on the API side.
+  class SphinxConnectError < SphinxError; end
+
+  # Request error occurred on the API side.
+  class SphinxResponseError < SphinxError; end
+
+  # Internal error occurred inside searchd.
+  class SphinxInternalError < SphinxError; end
+
+  # Temporary error occurred inside searchd.
+  class SphinxTemporaryError < SphinxError; end
+
+  # Unknown error occurred inside searchd.
+  class SphinxUnknownError < SphinxError; end
 end
 
 require 'net/protocol'
 require 'socket'
 require 'zlib'
 
-require File.dirname(__FILE__) + '/sphinx/request'
-require File.dirname(__FILE__) + '/sphinx/response'
-require File.dirname(__FILE__) + '/sphinx/timeout'
-require File.dirname(__FILE__) + '/sphinx/buffered_io'
-require File.dirname(__FILE__) + '/sphinx/server'
-require File.dirname(__FILE__) + '/sphinx/client'
+path = File.dirname(__FILE__)
+require "#{path}/sphinx/constants"
+require "#{path}/sphinx/indifferent_access"
+require "#{path}/sphinx/request"
+require "#{path}/sphinx/response"
+require "#{path}/sphinx/timeout"
+require "#{path}/sphinx/buffered_io"
+require "#{path}/sphinx/server"
+require "#{path}/sphinx/client"

data/lib/sphinx/client.rb

@@ -1,17 +1,4 @@
 module Sphinx
-  # Base class for all Sphinx errors
-  class SphinxError < StandardError; end
-  # Connect error occurred on the API side.
-  class SphinxConnectError < SphinxError; end
-  # Request error occurred on the API side.
-  class SphinxResponseError < SphinxError; end
-  # Internal error occurred inside searchd.
-  class SphinxInternalError < SphinxError; end
-  # Temporary error occurred inside searchd.
-  class SphinxTemporaryError < SphinxError; end
-  # Unknown error occurred inside searchd.
-  class SphinxUnknownError < SphinxError; end
-
   # The Sphinx Client API is used to communicate with <tt>searchd</tt>
   # daemon and perform requests.
   #
@@ -26,81 +13,8 @@ module Sphinx
   #   excerpts = sphinx.build_excerpts(docs, 'index', 'test')
   #
   class Client
-    #=================================================================
-    # Known searchd commands
-    #=================================================================
-
-    # search command
-    # @private
-    SEARCHD_COMMAND_SEARCH     = 0
-    # excerpt command
-    # @private
-    SEARCHD_COMMAND_EXCERPT    = 1
-    # update command
-    # @private
-    SEARCHD_COMMAND_UPDATE     = 2
-    # keywords command
-    # @private
-    SEARCHD_COMMAND_KEYWORDS   = 3
-    # persist command
-    # @private
-    SEARCHD_COMMAND_PERSIST    = 4
-    # status command
-    # @private
-    SEARCHD_COMMAND_STATUS     = 5
-    # query command
-    # @private
-    SEARCHD_COMMAND_QUERY      = 6
-    # flushattrs command
-    # @private
-    SEARCHD_COMMAND_FLUSHATTRS = 7
-
-    #=================================================================
-    # Current client-side command implementation versions
-    #=================================================================
-
-    # search command version
-    # @private
-    VER_COMMAND_SEARCH     = 0x117
-    # excerpt command version
-    # @private
-    VER_COMMAND_EXCERPT    = 0x100
-    # update command version
-    # @private
-    VER_COMMAND_UPDATE     = 0x102
-    # keywords command version
-    # @private
-    VER_COMMAND_KEYWORDS   = 0x100
-    # persist command version
-    # @private
-    VER_COMMAND_PERSIST    = 0x000
-    # status command version
-    # @private
-    VER_COMMAND_STATUS     = 0x100
-    # query command version
-    # @private
-    VER_COMMAND_QUERY      = 0x100
-    # flushattrs command version
-    # @private
-    VER_COMMAND_FLUSHATTRS = 0x100
-
-    #=================================================================
-    # Known searchd status codes
-    #=================================================================
-
-    # general success, command-specific reply follows
-    # @private
-    SEARCHD_OK      = 0
-    # general failure, command-specific reply may follow
-    # @private
-    SEARCHD_ERROR   = 1
-    # temporaty failure, client should retry later
-    # @private
-    SEARCHD_RETRY   = 2
-    # general success, warning message and command-specific reply follow
-    # @private
-    SEARCHD_WARNING = 3
-
+    include Sphinx::Constants
+    
     #=================================================================
     # Some internal attributes to use inside client API
     #=================================================================
@@ -120,118 +34,16 @@ module Sphinx
     # Number of request retries.
     # @private
     attr_reader :reqretries
-    # Log debug/info/warn/error to the given Logger, defaults to nil.
+    # Log debug/info/warn to the given Logger, defaults to nil.
     # @private
     attr_reader :logger
 
-    #=================================================================
-    # Known match modes
-    #=================================================================
-
-    # match all query words
-    SPH_MATCH_ALL       = 0
-    # match any query word
-    SPH_MATCH_ANY       = 1
-    # match this exact phrase
-    SPH_MATCH_PHRASE    = 2
-    # match this boolean query
-    SPH_MATCH_BOOLEAN   = 3
-    # match this extended query
-    SPH_MATCH_EXTENDED  = 4
-    # match all document IDs w/o fulltext query, apply filters
-    SPH_MATCH_FULLSCAN  = 5
-    # extended engine V2 (TEMPORARY, WILL BE REMOVED IN 0.9.8-RELEASE)
-    SPH_MATCH_EXTENDED2 = 6
-
-    #=================================================================
-    # Known ranking modes (ext2 only)
-    #=================================================================
-
-    # default mode, phrase proximity major factor and BM25 minor one
-    SPH_RANK_PROXIMITY_BM25 = 0
-    # statistical mode, BM25 ranking only (faster but worse quality)
-    SPH_RANK_BM25           = 1
-    # no ranking, all matches get a weight of 1
-    SPH_RANK_NONE           = 2
-    # simple word-count weighting, rank is a weighted sum of per-field keyword occurence counts
-    SPH_RANK_WORDCOUNT      = 3
-    # phrase proximity
-    SPH_RANK_PROXIMITY      = 4
-    # emulate old match-any weighting
-    SPH_RANK_MATCHANY       = 5
-    # sets bits where there were matches
-    SPH_RANK_FIELDMASK      = 6
-    # codename SPH04, phrase proximity + bm25 + head/exact boost
-    SPH_RANK_SPH04          = 7
-
-    #=================================================================
-    # Known sort modes
-    #=================================================================
-
-    # sort by document relevance desc, then by date
-    SPH_SORT_RELEVANCE     = 0
-    # sort by document date desc, then by relevance desc
-    SPH_SORT_ATTR_DESC     = 1
-    # sort by document date asc, then by relevance desc
-    SPH_SORT_ATTR_ASC      = 2
-    # sort by time segments (hour/day/week/etc) desc, then by relevance desc
-    SPH_SORT_TIME_SEGMENTS = 3
-    # sort by SQL-like expression (eg. "@relevance DESC, price ASC, @id DESC")
-    SPH_SORT_EXTENDED      = 4
-    # sort by arithmetic expression in descending order (eg. "@id + max(@weight,1000)*boost + log(price)")
-    SPH_SORT_EXPR          = 5
-
-    #=================================================================
-    # Known filter types
-    #=================================================================
-
-    # filter by integer values set
-    SPH_FILTER_VALUES      = 0
-    # filter by integer range
-    SPH_FILTER_RANGE       = 1
-    # filter by float range
-    SPH_FILTER_FLOATRANGE  = 2
-
-    #=================================================================
-    # Known attribute types
-    #=================================================================
-
-    # this attr is just an integer
-    SPH_ATTR_INTEGER   = 1
-    # this attr is a timestamp
-    SPH_ATTR_TIMESTAMP = 2
-    # this attr is an ordinal string number (integer at search time,
-    # specially handled at indexing time)
-    SPH_ATTR_ORDINAL   = 3
-    # this attr is a boolean bit field
-    SPH_ATTR_BOOL      = 4
-    # this attr is a float
-    SPH_ATTR_FLOAT     = 5
-    # signed 64-bit integer
-    SPH_ATTR_BIGINT    = 6
-    # string (binary; in-memory)
-    SPH_ATTR_STRING    = 7
-    # this attr has multiple values (0 or more)
-    SPH_ATTR_MULTI     = 0x40000000
-
-    #=================================================================
-    # Known grouping functions
-    #=================================================================
-
-    # group by day
-    SPH_GROUPBY_DAY      = 0
-    # group by week
-    SPH_GROUPBY_WEEK     = 1
-    # group by month
-    SPH_GROUPBY_MONTH    = 2
-    # group by year
-    SPH_GROUPBY_YEAR     = 3
-    # group by attribute value
-    SPH_GROUPBY_ATTR     = 4
-    # group by sequential attrs pair
-    SPH_GROUPBY_ATTRPAIR = 5
-
-    # Constructs the <tt>Sphinx::Client</tt> object and sets options to their default values.
+    # Constructs the <tt>Sphinx::Client</tt> object and sets options
+    # to their default values.
+    #
+    # @param [Logger] logger a logger object to put logs to. No logging
+    #   will be performed when not set.
+    #
     def initialize(logger = nil)
       # per-query settings
       @offset        = 0                       # how many records to seek from result-set start (default is 0)
@@ -458,8 +270,10 @@ module Sphinx
       @servers = servers.map do |server|
         raise ArgumentError, '"servers" argument must be Array of Hashes' unless server.kind_of?(Hash)
 
-        host = server[:path] || server['path'] || server[:host] || server['host']
-        port = server[:port] || server['port'] || 9312
+        server = server.with_indifferent_access
+
+        host = server[:path] || server[:host]
+        port = server[:port] || 9312
         path = nil
         raise ArgumentError, '"host" argument must be String' unless host.kind_of?(String)
 
@@ -809,7 +623,7 @@ module Sphinx
     # @return [Sphinx::Client] self.
     #
     # @example
-    #   sphinx.set_match_mode(Sphinx::Client::SPH_MATCH_ALL)
+    #   sphinx.set_match_mode(Sphinx::SPH_MATCH_ALL)
     #   sphinx.set_match_mode(:all)
     #   sphinx.set_match_mode('all')
     #
@@ -849,7 +663,7 @@ module Sphinx
     # @return [Sphinx::Client] self.
     #
     # @example
-    #   sphinx.set_ranking_mode(Sphinx::Client::SPH_RANK_BM25)
+    #   sphinx.set_ranking_mode(Sphinx::SPH_RANK_BM25)
     #   sphinx.set_ranking_mode(:bm25)
     #   sphinx.set_ranking_mode('bm25')
     #
@@ -891,7 +705,7 @@ module Sphinx
     # @return [Sphinx::Client] self.
     #
     # @example
-    #   sphinx.set_sort_mode(Sphinx::Client::SPH_SORT_ATTR_ASC, 'attr')
+    #   sphinx.set_sort_mode(Sphinx::SPH_SORT_ATTR_ASC, 'attr')
     #   sphinx.set_sort_mode(:attr_asc, 'attr')
     #   sphinx.set_sort_mode('attr_asc', 'attr')
     #
@@ -1087,7 +901,8 @@ module Sphinx
     # be matched (or rejected, if +exclude+ is +true+).
     #
     # @param [String, Symbol] attribute an attribute name to filter by.
-    # @param [Array<Integer>] values an +Array+ of integers with given attribute values.
+    # @param [Array<Integer>, Integer] values an +Array+ of integers or
+    #   single Integer with given attribute values.
     # @param [Boolean] exclude indicating whether documents with given attribute
     #   matching specified values should be excluded from search results.
     # @return [Sphinx::Client] self.
@@ -1104,15 +919,14 @@ module Sphinx
     #
     def set_filter(attribute, values, exclude = false)
       raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String) or attribute.kind_of?(Symbol)
+      values = [values] if values.kind_of?(Integer)
       raise ArgumentError, '"values" argument must be Array'               unless values.kind_of?(Array)
-      raise ArgumentError, '"values" argument must not be empty'           if values.empty?
-      raise ArgumentError, '"exclude" argument must be Boolean'            unless exclude.kind_of?(TrueClass) or exclude.kind_of?(FalseClass)
+      raise ArgumentError, '"values" argument must be Array of Integers'   unless values.all? { |v| v.kind_of?(Integer) }
+      raise ArgumentError, '"exclude" argument must be Boolean'            unless [TrueClass, FalseClass].include?(exclude.class)
 
-      values.each do |value|
-        raise ArgumentError, '"values" argument must be Array of Integer' unless value.kind_of?(Integer)
+      if values.any?
+        @filters << { 'type' => SPH_FILTER_VALUES, 'attr' => attribute.to_s, 'exclude' => exclude, 'values' => values }
       end
-
-      @filters << { 'type' => SPH_FILTER_VALUES, 'attr' => attribute.to_s, 'exclude' => exclude, 'values' => values }
       self
     end
     alias :SetFilter :set_filter
@@ -1502,6 +1316,8 @@ module Sphinx
     #   Query warning message reported by searchd (string, human readable).
     #   Empty if there were no warnings.
     #
+    # Please note: you can use both strings and symbols as <tt>Hash</tt> keys.
+    #
     # It should be noted that {#query} carries out the same actions as
     # {#add_query} and {#run_queries} without the intermediate steps; it
     # is analoguous to a single {#add_query} call, followed by a
@@ -1799,7 +1615,7 @@ module Sphinx
 
       # parse response
       (1..nreqs).map do
-        result = { 'error' => '', 'warning' => '' }
+        result = HashWithIndifferentAccess.new('error' => '', 'warning' => '')
 
         # extract status
         status = result['status'] = response.get_int
@@ -1944,16 +1760,18 @@ module Sphinx
       end
 
       # fixup options
-      opts['before_match']    ||= opts[:before_match]    || '<b>';
-      opts['after_match']     ||= opts[:after_match]     || '</b>';
-      opts['chunk_separator'] ||= opts[:chunk_separator] || ' ... ';
-      opts['limit']           ||= opts[:limit]           || 256;
-      opts['around']          ||= opts[:around]          || 5;
-      opts['exact_phrase']    ||= opts[:exact_phrase]    || false
-      opts['single_passage']  ||= opts[:single_passage]  || false
-      opts['use_boundaries']  ||= opts[:use_boundaries]  || false
-      opts['weight_order']    ||= opts[:weight_order]    || false
-      opts['query_mode']      ||= opts[:query_mode]      || false
+      opts = HashWithIndifferentAccess.new(
+        'before_match'    => '<b>',
+        'after_match'     => '</b>',
+        'chunk_separator' => ' ... ',
+        'limit'           => 256,
+        'around'          => 5,
+        'exact_phrase'    => false,
+        'single_passage'  => false,
+        'use_boundaries'  => false,
+        'weight_order'    => false,
+        'query_mode'      => false
+      ).update(opts)
 
       # build request
 
@@ -2044,7 +1862,7 @@ module Sphinx
         tokenized = response.get_string
         normalized = response.get_string
 
-        entry = { 'tokenized' => tokenized, 'normalized' => normalized }
+        entry = HashWithIndifferentAccess.new('tokenized' => tokenized, 'normalized' => normalized)
         entry['docs'], entry['hits'] = response.get_ints(2) if hits
 
         entry
@@ -2154,6 +1972,26 @@ module Sphinx
     end
     alias :UpdateAttributes :update_attributes
 
+    # Escapes characters that are treated as special operators by the
+    # query language parser.
+    #
+    # This function might seem redundant because it's trivial to
+    # implement in any calling application. However, as the set of
+    # special characters might change over time, it makes sense to
+    # have an API call that is guaranteed to escape all such
+    # characters at all times.
+    #
+    # @param [String] string is a string to escape.
+    # @return [String] an escaped string.
+    #
+    # @example:
+    #   escaped = sphinx.escape_string "escaping-sample@query/string"
+    #
+    def escape_string(string)
+      string.to_s.gsub(/([\\()|\-!@~"&\/\^\$=])/, '\\\\\\1')
+    end
+    alias :EscapeString :escape_string
+
     # Queries searchd status, and returns an array of status variable name
     # and value pairs.
     #
@@ -2194,11 +2032,11 @@ module Sphinx
           status = (0...rows).map do
             (0...cols).map { response.get_string }
           end
-          { :server => server.to_s, :status => status }
+          HashWithIndifferentAccess.new(:server => server.to_s, :status => status)
         rescue SphinxError
           # Re-raise error when a single server configured
           raise if @servers.size == 1
-          { :server => server.to_s, :error => self.last_error}
+          HashWithIndifferentAccess.new(:server => server.to_s, :error => self.last_error)
         end
       end
 

data/lib/sphinx/constants.rb

@@ -0,0 +1,189 @@
+module Sphinx
+  # Contains all constants need by Sphinx API.
+  #
+  module Constants
+    #=================================================================
+    # Known searchd commands
+    #=================================================================
+
+    # search command
+    # @private
+    SEARCHD_COMMAND_SEARCH     = 0
+    # excerpt command
+    # @private
+    SEARCHD_COMMAND_EXCERPT    = 1
+    # update command
+    # @private
+    SEARCHD_COMMAND_UPDATE     = 2
+    # keywords command
+    # @private
+    SEARCHD_COMMAND_KEYWORDS   = 3
+    # persist command
+    # @private
+    SEARCHD_COMMAND_PERSIST    = 4
+    # status command
+    # @private
+    SEARCHD_COMMAND_STATUS     = 5
+    # query command
+    # @private
+    SEARCHD_COMMAND_QUERY      = 6
+    # flushattrs command
+    # @private
+    SEARCHD_COMMAND_FLUSHATTRS = 7
+
+    #=================================================================
+    # Current client-side command implementation versions
+    #=================================================================
+
+    # search command version
+    # @private
+    VER_COMMAND_SEARCH     = 0x117
+    # excerpt command version
+    # @private
+    VER_COMMAND_EXCERPT    = 0x100
+    # update command version
+    # @private
+    VER_COMMAND_UPDATE     = 0x102
+    # keywords command version
+    # @private
+    VER_COMMAND_KEYWORDS   = 0x100
+    # persist command version
+    # @private
+    VER_COMMAND_PERSIST    = 0x000
+    # status command version
+    # @private
+    VER_COMMAND_STATUS     = 0x100
+    # query command version
+    # @private
+    VER_COMMAND_QUERY      = 0x100
+    # flushattrs command version
+    # @private
+    VER_COMMAND_FLUSHATTRS = 0x100
+
+    #=================================================================
+    # Known searchd status codes
+    #=================================================================
+
+    # general success, command-specific reply follows
+    # @private
+    SEARCHD_OK      = 0
+    # general failure, command-specific reply may follow
+    # @private
+    SEARCHD_ERROR   = 1
+    # temporaty failure, client should retry later
+    # @private
+    SEARCHD_RETRY   = 2
+    # general success, warning message and command-specific reply follow
+    # @private
+    SEARCHD_WARNING = 3
+
+    #=================================================================
+    # Known match modes
+    #=================================================================
+
+    # match all query words
+    SPH_MATCH_ALL       = 0
+    # match any query word
+    SPH_MATCH_ANY       = 1
+    # match this exact phrase
+    SPH_MATCH_PHRASE    = 2
+    # match this boolean query
+    SPH_MATCH_BOOLEAN   = 3
+    # match this extended query
+    SPH_MATCH_EXTENDED  = 4
+    # match all document IDs w/o fulltext query, apply filters
+    SPH_MATCH_FULLSCAN  = 5
+    # extended engine V2 (TEMPORARY, WILL BE REMOVED IN 0.9.8-RELEASE)
+    SPH_MATCH_EXTENDED2 = 6
+
+    #=================================================================
+    # Known ranking modes (ext2 only)
+    #=================================================================
+
+    # default mode, phrase proximity major factor and BM25 minor one
+    SPH_RANK_PROXIMITY_BM25 = 0
+    # statistical mode, BM25 ranking only (faster but worse quality)
+    SPH_RANK_BM25           = 1
+    # no ranking, all matches get a weight of 1
+    SPH_RANK_NONE           = 2
+    # simple word-count weighting, rank is a weighted sum of per-field keyword occurence counts
+    SPH_RANK_WORDCOUNT      = 3
+    # phrase proximity
+    SPH_RANK_PROXIMITY      = 4
+    # emulate old match-any weighting
+    SPH_RANK_MATCHANY       = 5
+    # sets bits where there were matches
+    SPH_RANK_FIELDMASK      = 6
+    # codename SPH04, phrase proximity + bm25 + head/exact boost
+    SPH_RANK_SPH04          = 7
+
+    #=================================================================
+    # Known sort modes
+    #=================================================================
+
+    # sort by document relevance desc, then by date
+    SPH_SORT_RELEVANCE     = 0
+    # sort by document date desc, then by relevance desc
+    SPH_SORT_ATTR_DESC     = 1
+    # sort by document date asc, then by relevance desc
+    SPH_SORT_ATTR_ASC      = 2
+    # sort by time segments (hour/day/week/etc) desc, then by relevance desc
+    SPH_SORT_TIME_SEGMENTS = 3
+    # sort by SQL-like expression (eg. "@relevance DESC, price ASC, @id DESC")
+    SPH_SORT_EXTENDED      = 4
+    # sort by arithmetic expression in descending order (eg. "@id + max(@weight,1000)*boost + log(price)")
+    SPH_SORT_EXPR          = 5
+
+    #=================================================================
+    # Known filter types
+    #=================================================================
+
+    # filter by integer values set
+    SPH_FILTER_VALUES      = 0
+    # filter by integer range
+    SPH_FILTER_RANGE       = 1
+    # filter by float range
+    SPH_FILTER_FLOATRANGE  = 2
+
+    #=================================================================
+    # Known attribute types
+    #=================================================================
+
+    # this attr is just an integer
+    SPH_ATTR_INTEGER   = 1
+    # this attr is a timestamp
+    SPH_ATTR_TIMESTAMP = 2
+    # this attr is an ordinal string number (integer at search time,
+    # specially handled at indexing time)
+    SPH_ATTR_ORDINAL   = 3
+    # this attr is a boolean bit field
+    SPH_ATTR_BOOL      = 4
+    # this attr is a float
+    SPH_ATTR_FLOAT     = 5
+    # signed 64-bit integer
+    SPH_ATTR_BIGINT    = 6
+    # string (binary; in-memory)
+    SPH_ATTR_STRING    = 7
+    # this attr has multiple values (0 or more)
+    SPH_ATTR_MULTI     = 0x40000000
+
+    #=================================================================
+    # Known grouping functions
+    #=================================================================
+
+    # group by day
+    SPH_GROUPBY_DAY      = 0
+    # group by week
+    SPH_GROUPBY_WEEK     = 1
+    # group by month
+    SPH_GROUPBY_MONTH    = 2
+    # group by year
+    SPH_GROUPBY_YEAR     = 3
+    # group by attribute value
+    SPH_GROUPBY_ATTR     = 4
+    # group by sequential attrs pair
+    SPH_GROUPBY_ATTRPAIR = 5
+  end
+
+  include Constants
+end

data/lib/sphinx/indifferent_access.rb

@@ -0,0 +1,152 @@
+module Sphinx
+  begin
+    HashWithIndifferentAccess = ::HashWithIndifferentAccess
+  rescue NameError
+    # This class has dubious semantics and we only have it so that
+    # people can write params[:key] instead of params['key']
+    # and they get the same value for both keys.
+    #
+    # This is part of Rails' ActiveSupport project. If you are
+    # using Rails, this class will not be used.
+    #
+    class HashWithIndifferentAccess < Hash
+      def initialize(constructor = {})
+        if constructor.is_a?(Hash)
+          super()
+          update(constructor)
+        else
+          super(constructor)
+        end
+      end
+
+      def default(key = nil)
+        if key.is_a?(Symbol) && include?(key = key.to_s)
+          self[key]
+        else
+          super
+        end
+      end
+
+      alias_method :regular_writer, :[]= unless method_defined?(:regular_writer)
+      alias_method :regular_update, :update unless method_defined?(:regular_update)
+
+      # Assigns a new value to the hash:
+      #
+      #   hash = HashWithIndifferentAccess.new
+      #   hash[:key] = "value"
+      #
+      def []=(key, value)
+        regular_writer(convert_key(key), convert_value(value))
+      end
+
+      # Updates the instantized hash with values from the second:
+      # 
+      #   hash_1 = HashWithIndifferentAccess.new
+      #   hash_1[:key] = "value"
+      # 
+      #   hash_2 = HashWithIndifferentAccess.new
+      #   hash_2[:key] = "New Value!"
+      # 
+      #   hash_1.update(hash_2) # => {"key"=>"New Value!"}
+      # 
+      def update(other_hash)
+        other_hash.each_pair { |key, value| regular_writer(convert_key(key), convert_value(value)) }
+        self
+      end
+
+      alias_method :merge!, :update
+
+      # Checks the hash for a key matching the argument passed in:
+      #
+      #   hash = HashWithIndifferentAccess.new
+      #   hash["key"] = "value"
+      #   hash.key? :key  # => true
+      #   hash.key? "key" # => true
+      #
+      def key?(key)
+        super(convert_key(key))
+      end
+
+      alias_method :include?, :key?
+      alias_method :has_key?, :key?
+      alias_method :member?, :key?
+
+      # Fetches the value for the specified key, same as doing hash[key]
+      def fetch(key, *extras)
+        super(convert_key(key), *extras)
+      end
+
+      # Returns an array of the values at the specified indices:
+      #
+      #   hash = HashWithIndifferentAccess.new
+      #   hash[:a] = "x"
+      #   hash[:b] = "y"
+      #   hash.values_at("a", "b") # => ["x", "y"]
+      #
+      def values_at(*indices)
+        indices.collect {|key| self[convert_key(key)]}
+      end
+
+      # Returns an exact copy of the hash.
+      def dup
+        HashWithIndifferentAccess.new(self)
+      end
+
+      # Merges the instantized and the specified hashes together, giving precedence to the values from the second hash
+      # Does not overwrite the existing hash.
+      def merge(hash)
+        self.dup.update(hash)
+      end
+
+      # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second.
+      # This overloaded definition prevents returning a regular hash, if reverse_merge is called on a HashWithDifferentAccess.
+      def reverse_merge(other_hash)
+        super other_hash.with_indifferent_access
+      end
+
+      # Removes a specified key from the hash.
+      def delete(key)
+        super(convert_key(key))
+      end
+
+      def stringify_keys!; self end
+      def symbolize_keys!; self end
+      def to_options!; self end
+
+      # Convert to a Hash with String keys.
+      def to_hash
+        Hash.new(default).merge(self)
+      end
+
+      protected
+        def convert_key(key)
+          key.kind_of?(Symbol) ? key.to_s : key
+        end
+
+        def convert_value(value)
+          case value
+          when Hash
+            value.with_indifferent_access
+          when Array
+            value.collect { |e| e.is_a?(Hash) ? e.with_indifferent_access : e }
+          else
+            value
+          end
+        end
+    end
+
+    module HashIndifferentAccess #:nodoc:
+      def with_indifferent_access
+        hash = HashWithIndifferentAccess.new(self)
+        hash.default = self.default
+        hash
+      end
+    end
+
+    class ::Hash #:nodoc:
+      unless respond_to?(:with_indifferent_access)
+        include Sphinx::HashIndifferentAccess
+      end
+    end
+  end
+end

data/spec/client_response_spec.rb

@@ -143,10 +143,10 @@ describe Sphinx::Client, 'connected' do
     result['matches'].length.should == 3
     result['time'].should_not be_nil
     result['attrs'].should == {
-      'group_id' => Sphinx::Client::SPH_ATTR_INTEGER,
-      'created_at' => Sphinx::Client::SPH_ATTR_TIMESTAMP,
-      'rating' => Sphinx::Client::SPH_ATTR_FLOAT,
-      'tags' => Sphinx::Client::SPH_ATTR_MULTI | Sphinx::Client::SPH_ATTR_INTEGER
+      'group_id' => Sphinx::SPH_ATTR_INTEGER,
+      'created_at' => Sphinx::SPH_ATTR_TIMESTAMP,
+      'rating' => Sphinx::SPH_ATTR_FLOAT,
+      'tags' => Sphinx::SPH_ATTR_MULTI | Sphinx::SPH_ATTR_INTEGER
     }
     result['fields'].should == [ 'name', 'description' ]
     result['total'].should == 3

data/spec/client_spec.rb

@@ -15,7 +15,7 @@ describe Sphinx::Client, 'disconnected' do
           cnt.should == 1
         end
       end
-      
+
       it 'should raise an exception on error' do
         2.times do
           cnt = 0
@@ -91,20 +91,20 @@ describe Sphinx::Client, 'disconnected' do
       end
     end
   end
-  
+
   context 'in with_socket method' do
     before :each do
       @sphinx = Sphinx::Client.new
       @socket = mock('TCPSocket')
     end
-    
+
     context 'without retries' do
       before :each do
         @server = mock('Server')
         @server.should_receive(:get_socket).and_yield(@socket).and_return(@socket)
         @server.should_receive(:free_socket).with(@socket).at_least(1)
       end
-      
+
       it 'should initialize session' do
         @socket.should_receive(:write).with([1].pack('N'))
         @socket.should_receive(:read).with(4).and_return([1].pack('N'))
@@ -159,7 +159,7 @@ describe Sphinx::Client, 'disconnected' do
         @server.should_receive(:get_socket).at_least(1).times.and_yield(@socket).and_return(@socket)
         @server.should_receive(:free_socket).with(@socket).at_least(1)
       end
-      
+
       it 'should raise an exception on error' do
         @socket.should_receive(:write).exactly(3).times.with([1].pack('N'))
         @socket.should_receive(:read).exactly(3).times.with(4).and_return([1].pack('N'))
@@ -174,7 +174,7 @@ describe Sphinx::Client, 'disconnected' do
       end
     end
   end
-    
+
   context 'in parse_response method' do
     before :each do
       @sphinx = Sphinx::Client.new
@@ -182,20 +182,20 @@ describe Sphinx::Client, 'disconnected' do
     end
 
     it 'should receive response' do
-      @socket.should_receive(:read).with(8).and_return([Sphinx::Client::SEARCHD_OK, 1, 4].pack('n2N'))
+      @socket.should_receive(:read).with(8).and_return([Sphinx::SEARCHD_OK, 1, 4].pack('n2N'))
       @socket.should_receive(:read).with(4).and_return([0].pack('N'))
       @sphinx.send(:parse_response, @socket, 1)
     end
 
     it 'should raise exception on zero-sized response' do
-      @socket.should_receive(:read).with(8).and_return([Sphinx::Client::SEARCHD_OK, 1, 0].pack('n2N'))
+      @socket.should_receive(:read).with(8).and_return([Sphinx::SEARCHD_OK, 1, 0].pack('n2N'))
       expect {
         @sphinx.send(:parse_response, @socket, 1)
       }.to raise_error(Sphinx::SphinxResponseError, 'received zero-sized searchd response')
     end
 
     it 'should raise exception when response is incomplete' do
-      @socket.should_receive(:read).with(8).and_return([Sphinx::Client::SEARCHD_OK, 1, 4].pack('n2N'))
+      @socket.should_receive(:read).with(8).and_return([Sphinx::SEARCHD_OK, 1, 4].pack('n2N'))
       @socket.should_receive(:read).with(4).and_return('')
       expect {
         @sphinx.send(:parse_response, @socket, 1)
@@ -203,14 +203,14 @@ describe Sphinx::Client, 'disconnected' do
     end
 
     it 'should set warning message when SEARCHD_WARNING received' do
-      @socket.should_receive(:read).with(8).and_return([Sphinx::Client::SEARCHD_WARNING, 1, 14].pack('n2N'))
+      @socket.should_receive(:read).with(8).and_return([Sphinx::SEARCHD_WARNING, 1, 14].pack('n2N'))
       @socket.should_receive(:read).with(14).and_return([5].pack('N') + 'helloworld')
       @sphinx.send(:parse_response, @socket, 1).should == 'world'
       @sphinx.GetLastWarning.should == 'hello'
     end
 
     it 'should raise exception when SEARCHD_ERROR received' do
-      @socket.should_receive(:read).with(8).and_return([Sphinx::Client::SEARCHD_ERROR, 1, 9].pack('n2N'))
+      @socket.should_receive(:read).with(8).and_return([Sphinx::SEARCHD_ERROR, 1, 9].pack('n2N'))
       @socket.should_receive(:read).with(9).and_return([1].pack('N') + 'hello')
       expect {
         @sphinx.send(:parse_response, @socket, 1)
@@ -218,7 +218,7 @@ describe Sphinx::Client, 'disconnected' do
     end
 
     it 'should raise exception when SEARCHD_RETRY received' do
-      @socket.should_receive(:read).with(8).and_return([Sphinx::Client::SEARCHD_RETRY, 1, 9].pack('n2N'))
+      @socket.should_receive(:read).with(8).and_return([Sphinx::SEARCHD_RETRY, 1, 9].pack('n2N'))
       @socket.should_receive(:read).with(9).and_return([1].pack('N') + 'hello')
       expect {
         @sphinx.send(:parse_response, @socket, 1)
@@ -234,7 +234,7 @@ describe Sphinx::Client, 'disconnected' do
     end
 
     it 'should set warning when server is older than client' do
-      @socket.should_receive(:read).with(8).and_return([Sphinx::Client::SEARCHD_OK, 1, 9].pack('n2N'))
+      @socket.should_receive(:read).with(8).and_return([Sphinx::SEARCHD_OK, 1, 9].pack('n2N'))
       @socket.should_receive(:read).with(9).and_return([1].pack('N') + 'hello')
       @sphinx.send(:parse_response, @socket, 5)
       @sphinx.GetLastWarning.should == 'searchd command v.0.1 older than client\'s v.0.5, some options might not work'
@@ -291,7 +291,7 @@ describe Sphinx::Client, 'disconnected' do
         it "should generate valid request for SPH_MATCH_#{match.to_s.upcase}" do
           expected = sphinx_fixture("match_#{match}")
           @sock.should_receive(:write).with(expected)
-          @sphinx.SetMatchMode(Sphinx::Client::const_get("SPH_MATCH_#{match.to_s.upcase}"))
+          @sphinx.SetMatchMode(Sphinx::const_get("SPH_MATCH_#{match.to_s.upcase}"))
           sphinx_safe_call { @sphinx.Query('query') }
         end
 
@@ -485,7 +485,7 @@ describe Sphinx::Client, 'disconnected' do
         it "should generate valid request for SPH_GROUPBY_#{groupby.to_s.upcase}" do
           expected = sphinx_fixture("group_by_#{groupby}")
           @sock.should_receive(:write).with(expected)
-          @sphinx.SetGroupBy('attr', Sphinx::Client::const_get("SPH_GROUPBY_#{groupby.to_s.upcase}"))
+          @sphinx.SetGroupBy('attr', Sphinx::const_get("SPH_GROUPBY_#{groupby.to_s.upcase}"))
           sphinx_safe_call { @sphinx.Query('query') }
         end
 
@@ -507,14 +507,14 @@ describe Sphinx::Client, 'disconnected' do
       it 'should generate valid request for SPH_GROUPBY_DAY with sort' do
         expected = sphinx_fixture('group_by_day_sort')
         @sock.should_receive(:write).with(expected)
-        @sphinx.SetGroupBy('attr', Sphinx::Client::SPH_GROUPBY_DAY, 'somesort')
+        @sphinx.SetGroupBy('attr', Sphinx::SPH_GROUPBY_DAY, 'somesort')
         sphinx_safe_call { @sphinx.Query('query') }
       end
 
       it 'should generate valid request with count-distinct attribute' do
         expected = sphinx_fixture('group_distinct')
         @sock.should_receive(:write).with(expected)
-        @sphinx.SetGroupBy('attr', Sphinx::Client::SPH_GROUPBY_DAY)
+        @sphinx.SetGroupBy('attr', Sphinx::SPH_GROUPBY_DAY)
         @sphinx.SetGroupDistinct('attr')
         sphinx_safe_call { @sphinx.Query('query') }
       end
@@ -537,9 +537,9 @@ describe Sphinx::Client, 'disconnected' do
     it 'should generate valid request for SetOverride' do
       expected = sphinx_fixture('set_override')
       @sock.should_receive(:write).with(expected)
-      @sphinx.SetOverride('attr1', Sphinx::Client::SPH_ATTR_INTEGER, { 10 => 20 })
-      @sphinx.SetOverride('attr2', Sphinx::Client::SPH_ATTR_FLOAT, { 11 => 30.3 })
-      @sphinx.SetOverride('attr3', Sphinx::Client::SPH_ATTR_BIGINT, { 12 => 1099511627780 })
+      @sphinx.SetOverride('attr1', Sphinx::SPH_ATTR_INTEGER, { 10 => 20 })
+      @sphinx.SetOverride('attr2', Sphinx::SPH_ATTR_FLOAT, { 11 => 30.3 })
+      @sphinx.SetOverride('attr3', Sphinx::SPH_ATTR_BIGINT, { 12 => 1099511627780 })
       sphinx_safe_call { @sphinx.Query('query') }
     end
 
@@ -562,7 +562,7 @@ describe Sphinx::Client, 'disconnected' do
 
       @sphinx.SetRetries(10, 20)
       @sphinx.AddQuery('test1')
-      @sphinx.SetGroupBy('attr', Sphinx::Client::SPH_GROUPBY_DAY)
+      @sphinx.SetGroupBy('attr', Sphinx::SPH_GROUPBY_DAY)
       @sphinx.AddQuery('test2')
 
       sphinx_safe_call { @sphinx.RunQueries }
@@ -656,4 +656,14 @@ describe Sphinx::Client, 'disconnected' do
       sphinx_safe_call { @sphinx.UpdateAttributes('index', ['group', 'category'], { 123 => [ [456, 789], [1, 2, 3] ] }, true) }
     end
   end
+
+  context 'in EscapeString method' do
+    before :each do
+      @sphinx = Sphinx::Client.new
+    end
+
+    it 'should escape special characters' do
+      @sphinx.escape_string("escaping-sample@query/string").should == "escaping\\-sample\\@query\\/string"
+    end
+  end
 end

data/spec/client_validations_spec.rb

@@ -327,10 +327,18 @@ describe Sphinx::Client, 'disconnected' do
       }.to_not raise_error(ArgumentError)
     end
 
-    it 'should raise an error when values is not Array' do
+    it 'should raise an error when values is not Array or Integer' do
       expect {
         @sphinx.SetFilter(:attr, {})
       }.to raise_error(ArgumentError)
+
+      expect {
+        @sphinx.SetFilter(:attr, 1)
+      }.to_not raise_error(ArgumentError)
+
+      expect {
+        @sphinx.SetFilter(:attr, [1])
+      }.to_not raise_error(ArgumentError)
     end
 
     it 'should raise an error when values is not Array of Integers' do
@@ -339,10 +347,11 @@ describe Sphinx::Client, 'disconnected' do
       }.to raise_error(ArgumentError)
     end
 
-    it 'should raise an error when values is empty Array' do
+    it 'should not raise an error when values is empty Array' do
       expect {
         @sphinx.SetFilter(:attr, [])
-      }.to raise_error(ArgumentError)
+      }.to_not raise_error(ArgumentError)
+      @sphinx.instance_variable_get(:@filters).should be_empty
     end
 
     it 'should raise an error when exclude is not Boolean' do

data/sphinx.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sphinx}
-  s.version = "0.9.10.2094"
+  s.version = "0.9.10.2122"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Dmytro Shteflyuk"]
-  s.date = %q{2009-11-23}
+  s.date = %q{2009-12-04}
   s.description = %q{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.}
   s.email = %q{kpumuk@kpumuk.info}
   s.extra_rdoc_files = [
@@ -24,6 +24,8 @@ Gem::Specification.new do |s|
      "lib/sphinx.rb",
      "lib/sphinx/buffered_io.rb",
      "lib/sphinx/client.rb",
+     "lib/sphinx/constants.rb",
+     "lib/sphinx/indifferent_access.rb",
      "lib/sphinx/request.rb",
      "lib/sphinx/response.rb",
      "lib/sphinx/server.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sphinx
 version: !ruby/object:Gem::Version 
-  version: 0.9.10.2094
+  version: 0.9.10.2122
 platform: ruby
 authors: 
 - Dmytro Shteflyuk
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-23 00:00:00 +02:00
+date: 2009-12-04 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -30,6 +30,8 @@ files:
 - lib/sphinx.rb
 - lib/sphinx/buffered_io.rb
 - lib/sphinx/client.rb
+- lib/sphinx/constants.rb
+- lib/sphinx/indifferent_access.rb
 - lib/sphinx/request.rb
 - lib/sphinx/response.rb
 - lib/sphinx/server.rb