isomorfeus-ferret 0.12.0

data/lib/isomorfeus/ferret/document.rb

@@ -0,0 +1,132 @@
+module Isomorfeus
+  module Ferret
+    # Instead of using documents to add data to an index you can use Hashes and
+    # Arrays. The only real benefits of using a Document over a Hash are pretty
+    # printing and the boost attribute. You can add the boost attribute to
+    # Hashes and arrays using the BoostMixin. For example;
+    #
+    #    class Hash
+    #      include BoostMixin
+    #    end
+    #
+    #    class Array
+    #      include BoostMixin
+    #    end
+    #
+    #    class String
+    #      include BoostMixin
+    #    end
+    module BoostMixin
+      attr_accessor :boost
+    end
+
+    # Documents are the unit of indexing and search.
+    #
+    # A Document is a set of fields.  Each field has a name and an array of
+    # textual values. If you are coming from a Lucene background you should note
+    # that Fields don't have any properties except for the boost property. You
+    # should use the Ferret::Index::FieldInfos class to set field properties
+    # across the whole index instead.
+    # 
+    # === Boost
+    #
+    # The boost attribute makes a Document more important in the index. That is,
+    # you can increase the score of a match for queries that match a particular
+    # document, making it more likely to appear at the top of search results.
+    # You may, for example, want to boost products that have a higher user
+    # rating so that they are more likely to appear in search results.
+    #
+    # Note: that fields which are _not_ stored (see Ferret::Index::FieldInfos)
+    # are _not_ available in documents retrieved from the index, e.g.
+    # Ferret::Search::Searcher#doc or Ferret::Index::IndexReader#doc.
+    #
+    # Note: that modifying a Document retrieved from the index will not modify
+    # the document contained within the index. You need to delete the old
+    # version of the document and add the new version of the document.
+    class Document < Hash
+      include BoostMixin
+
+      # Create a new Document object with a boost. The boost defaults to 1.0.
+      def initialize(boost = 1.0)
+        @boost = boost
+      end
+
+      # Return true if the documents are equal, ie they have the same fields
+      def eql?(o)
+        return (o.is_a? Document and (o.boost == @boost) and
+                (self.keys == o.keys) and (self.values == o.values))
+      end
+      alias :== :eql?
+
+      # Create a string representation of the document
+      def to_s
+        buf = ["Document {"]
+        self.keys.sort_by {|key| key.to_s}.each do |key|
+          val = self[key]
+          val_str = if val.instance_of? Array then %{["#{val.join('", "')}"]}
+                    elsif val.is_a? Field then val.to_s
+                    else %{"#{val.to_s}"}
+                    end
+          buf << "  :#{key} => #{val_str}"
+        end
+        buf << ["}#{@boost == 1.0 ? "" : "^" + @boost.to_s}"]
+        return buf.join("\n")
+      end
+    end
+
+    # A Field is a section of a Document. A Field is basically an array with a
+    # boost attribute. It also provides pretty printing of the field with the
+    # #to_s method.
+    #
+    # === Boost
+    #
+    # The boost attribute makes a field more important in the index. That is,
+    # you can increase the score of a match for queries that match terms in a
+    # boosted field. You may, for example, want to boost a title field so that
+    # matches that match in the :title field score more highly than matches that
+    # match in the :contents field. 
+    #
+    # Note: If you'd like to use boosted fields without having to use
+    # the Field class you can just include the BoostMixin in the Array class.
+    # See BoostMixin.
+    class Field < Array
+      include BoostMixin
+
+      # Create a new Field object. You can pass data to the field as either a
+      # string;
+      #
+      #    f = Field.new("This is the fields data")
+      #
+      # or as an array of strings;
+      #
+      #    f = Field.new(["this", "is", "an", "array", "of", "field", "data"])
+      #
+      # Of course Fields can also be boosted;
+      #
+      #    f = Field.new("field data", 1000.0)
+      def initialize(data = [], boost = 1.0)
+        @boost = boost
+        if data.is_a? Array
+          data.each {|v| self << v}
+        else
+          self << data.to_s
+        end
+      end
+
+      def eql?(o)
+        return (o.is_a? Field and (o.boost == @boost) and super(o))
+      end
+      alias :== :eql?
+
+      def +(o)
+        return Field.new(super(o), self.boost)
+      end
+
+      def to_s
+        buf = %{["#{self.join('", "')}"]}
+        buf << "^#@boost" if @boost != 1.0
+        return buf
+      end
+    end
+  end
+end

data/lib/isomorfeus/ferret/field_symbol.rb

@@ -0,0 +1,85 @@
+module Isomorfeus
+  module Ferret
+    FIELD_TYPES = %w(integer float string byte).map{|t| t.to_sym}
+
+    class BlankSlate < BasicObject
+    end
+
+    # The FieldSymbolMethods module contains the methods that are added to both
+    # the Symbol class and the FieldSymbol class. These methods allow you to
+    # easily set the type of a field by calling a method on a symbol.
+    #
+    # Right now this is only useful for Sorting and grouping, but some day Ferret
+    # may have typed fields, in which case these this methods will come in handy.
+    #
+    # The available types are specified in Ferret::FIELD_TYPES.
+    #
+    # == Examples
+    #
+    #   index.search(query, :sort => :title.string.desc)
+    #
+    #   index.search(query, :sort => [:price.float, :count.integer.desc])
+    #   
+    #   index.search(query, :group_by => :catalogue.string)
+    #
+    # == Note
+    #
+    # If you set the field type multiple times, the last type specified will be
+    # the type used. For example;
+    #
+    #   puts :title.integer.float.byte.string.type.inspect # => :string
+    #
+    # Calling #desc twice will set desc? to false
+    #
+    #   puts :title.desc?           # => false
+    #   puts :title.desc.desc?      # => true
+    #   puts :title.desc.desc.desc? # => false
+    module FieldSymbolMethods
+      FIELD_TYPES.each do |method|
+        define_method(method) do
+          fsym = FieldSymbol.new(self, respond_to?(:desc?) ? desc? : false)
+          fsym.type = method
+          fsym
+        end
+      end
+        
+      # Set a field to be a descending field. This only makes sense in sort
+      # specifications.
+      def desc
+        fsym = FieldSymbol.new(self, respond_to?(:desc?) ? !desc? : true)
+        fsym.type = respond_to?(:type) ? type : nil
+        fsym
+      end
+
+      # Return whether or not this field should be a descending field
+      def desc?
+        self.class == FieldSymbol and @desc == true
+      end
+
+      # Return the type of this field
+      def type
+        self.class == FieldSymbol ? @type : nil
+      end
+    end
+
+    # See FieldSymbolMethods
+    class FieldSymbol < BlankSlate
+      include FieldSymbolMethods
+      
+      def initialize(symbol, desc = false)
+        @symbol = symbol
+        @desc = desc
+      end
+
+      def method_missing(method, *args)
+        @symbol.__send__(method, *args)
+      end
+
+      def class
+        FieldSymbol
+      end
+
+      attr_writer :type, :desc
+    end
+  end
+end

data/lib/isomorfeus/ferret/index/field_infos.rb

@@ -0,0 +1,48 @@
+require 'yaml'
+
+module Isomorfeus
+  module Ferret
+    module Index
+      class FieldInfos
+        # Load FieldInfos from a YAML file. The YAML file should look something like
+        # this:
+        # default:
+        #   store: :yes
+        #   index: :yes
+        #   term_vector: :no
+        #
+        # fields:
+        #   id:
+        #     index: :untokenized
+        #     term_vector: :no
+        # 
+        #   title:
+        #     boost: 20.0
+        #     term_vector: :no
+        # 
+        #   content:
+        #     term_vector: :with_positions_offsets
+        #  
+        def self.load(yaml_str)
+          info = YAML.load(yaml_str)
+          convert_strings_to_symbols(info)
+          fis = FieldInfos.new(info[:default])
+          fields = info[:fields]
+          fields.keys.each {|key| fis.add_field(key, fields[key])} if fields
+          fis
+        end
+
+        private
+        def self.convert_strings_to_symbols(hash)
+          hash.keys.each do |key|
+            convert_strings_to_symbols(hash[key]) if hash[key].is_a?(Hash)
+            if key.is_a?(String)
+              hash[key.intern] = hash[key]
+              hash.delete(key)
+            end
+          end
+        end
+      end
+    end
+  end
+end