endeca 1.3.7

data/lib/endeca/breadcrumb.rb

@@ -0,0 +1,42 @@
+module Endeca
+  
+  class Breadcrumb
+    include Readers
+
+    def self.create(raw)
+      name = raw['Type']
+      breadcrumb_class = self
+
+      if name    
+        unless Breadcrumbs.include?(name)
+          raise Breadcrumbs::TypeError, "Unknown breadcrumb type: #{name.inspect}" 
+        end
+        breadcrumb_class = Breadcrumbs[name]
+      end
+
+      breadcrumb_class.new(raw)
+    end
+    
+    def self.to_proc
+      proc(&method(:create))
+    end
+
+    attr_reader :raw
+    def initialize(raw={})
+      @raw = raw
+    end
+    alias_method :attributes, :raw
+    
+    reader 'Type' => :type    
+    def name; '' end
+
+    def ==(other)
+      name == other.name
+    end
+
+    def inspect
+      "#<#{self.class}=0x#{self.object_id.to_s(16)} name=#{name.inspect}>"
+    end
+
+  end
+end

data/lib/endeca/breadcrumbs.rb

@@ -0,0 +1,13 @@
+module Endeca
+  module Breadcrumbs
+    class TypeError < StandardError; end
+    
+    def self.include?(klass)
+      self.const_defined?(klass)
+    end
+    
+    def self.[](klass)
+      self.const_get(klass)
+    end
+  end
+end

data/lib/endeca/dimension.rb

@@ -0,0 +1,38 @@
+module Endeca
+  class Dimension
+    include Comparable
+    include Readers
+    extend ClassToProc
+
+    reader \
+      "DimValueName"  => :name,
+      "SelectionLink" => :selection_link,
+      "RemovalLink"   => :removal_link
+
+    integer_reader \
+      "DimValueID"      => :id,
+      "NumberofRecords" => :record_count
+
+    attr_reader :raw
+    def initialize(raw={})
+      @raw=raw
+    end
+    alias_method :attributes, :raw
+    
+    def to_endeca_params
+      selection_link || removal_link
+    end
+
+    def inspect
+      "#<#{self.class}=0x#{self.object_id.to_s(16)} id=#{id} name=#{name.inspect}>"
+    end
+
+    def ==(other)
+      id == other.id
+    end
+
+    def <=>(other)
+      name <=> other.name
+    end
+  end
+end

data/lib/endeca/document.rb

@@ -0,0 +1,146 @@
+module Endeca
+  # Endeca Documents provide accessors for document properties
+  # returned by an Endeca query. Interesting Document properties must be
+  # declared with reader to be accessible on the object.
+  #
+  # The +reader+ declaration provided by Readers can also handle basic data transformations (i.e.
+  # typecasting) and a few basic examples are provided (i.e. +integer_reader+).
+  class Document
+    include Readers
+    extend ClassToProc
+    extend Transformer
+
+    inherited_accessor :mappings, {}
+    inherited_property :path
+    inherited_property :default_params, {}
+    inherited_property :collection_class, DocumentCollection
+    
+    inherited_accessor :reader_names, []
+    def self.field_names; reader_names; end
+    
+    reader :id
+
+    attr_reader :raw, :properties
+    def initialize(record_raw=nil)
+      @raw        = record_raw || {}
+      @properties = @raw['Properties'] || {}
+    end
+
+    alias_method :attributes, :properties
+
+    def ==(other)
+      id == other.id
+    end
+
+    def self.inspect
+      return <<-INSPECT
+#<#{self}>
+Path: #{get_path.inspect}
+Collection Class: #{get_collection_class.inspect}"
+Mappings:\n\t#{mappings.collect{|k,v| "#{k}: #{v.inspect}\n\t"}.to_s} 
+DefaultParams:\n\t#{get_default_params.collect{|k,v| "#{k}: #{v.inspect}\n\t"}.to_s} 
+      INSPECT
+    end
+
+    def inspect
+      "#<#{self.class}:0x#{self.object_id.to_s(16)}>"
+    end
+
+    # Returns the collection of Endeca::Dimension for the given Document
+    def dimensions
+      return @dimensions if @dimensions
+      @dimensions = {}
+      (raw['Dimensions'] || {}).each do |name, values|
+        values = [values] unless Array === values
+        @dimensions[name] = values.map(&Dimension)
+      end
+      @dimensions
+    end
+
+    # Find operates with three distinct retrieval approaches:
+    #
+    # * Find by id - This is a specific id (1) or id string ("1")
+    # * Find first - This will return the first record matching the query options
+    #   used
+    # * Find all - This will return a collection of Documents matching the
+    #   query options. This is the default behavior of find if only query options
+    #   are passed.
+    #
+    # ==== Parameters
+    #
+    # Find accepts a query options hash. These options are either passed
+    # directly to Endeca or mapped (by use of +map+) to new parameters that are
+    # passed to Endeca.
+    #
+    # ==== Examples
+    #
+    #   # find by id
+    #   Listing.find(1)   # returns the Document for ID = 1
+    #   Listing.find('1') # returns the Document for ID = 1
+    #
+    #   # find all
+    #   Listing.find(:all) # returns a collection of Documents 
+    #   Listing.find(:all, :available => true)
+    #
+    #   # find first
+    #   Listing.find(:first) # Returns the first Document for the query
+    #   Listing.find(:first, :available => true)
+    def self.find(what, query_options={})
+      case what
+      when Integer, /^[A-Z\d]+$/
+        by_id(what, query_options)
+      when String
+        all(what)
+      when :first
+        first(query_options)
+      when :all
+        all(query_options)
+      else
+        all(what)
+      end
+    end
+
+
+    # Returns the first Document matching the query options.
+    def self.first(query_options={})
+      response = request(query_options)
+      record = if response['AggrRecords'] 
+        response['AggrRecords'].first['Records'].first
+      elsif response['Records']
+        response['Records'].first
+      else
+        nil
+      end
+
+      record && new(record)
+    end
+
+    # Returns all Documents matching the query options.
+    def self.all(query_options={})
+      get_collection_class.new(request(query_options), self)
+    end
+
+    # Returns a Document by id
+    def self.by_id(id, query_options={})
+      first(query_options.merge(:id => id, :skip_default_endeca_parameters => true))
+    end
+
+    private
+
+    def self.request(query_options)
+      Endeca::Request.perform(get_path, parse_query_options(query_options))
+    end
+
+    def self.parse_query_options(query_options)
+      if query_options.respond_to?(:merge)
+        unless query_options.delete(:skip_default_endeca_parameters)
+          query_options = get_default_params.merge(query_options)
+        end
+
+        transform_query_options(query_options)
+      else
+        URI.unescape(query_options)
+      end
+    end
+  end
+end

data/lib/endeca/document_collection.rb

@@ -0,0 +1,112 @@
+module Endeca
+  # Endeca DocumentCollections wrap a collection of Endeca Documents to provide
+  # access to metadata returned by the Endeca query. They behave like a simple
+  # Array in most cases (e.g. iteration) but also provide access to
+  # +refinements+.
+  #
+  # ==Attribute Readers
+  #
+  # DocumentCollection provides attribute readers for collection metadata in
+  # an interface that is compatible with WillPaginate::Collection for use in
+  # views.
+  #
+  # == Method Delegation
+  #
+  # DocumentCollections delegate array-like behavior to their embedded document
+  # collection, (+documents+). In most cases a DocumentCollection can be used
+  # as if it were an array of Document objects. (Array delegation pattern
+  # borrowed from Rake::FileList)
+  class DocumentCollection
+    include Readers
+    extend ClassToProc
+
+    attr_reader :raw
+    def initialize(raw, document_klass=Document)
+      @raw = raw
+      @document_klass = document_klass
+    end
+
+    def attributes
+      @raw['MetaInfo'] || {}
+    end
+
+    reader \
+      'NextPageLink' => :next_page_params
+
+    integer_reader \
+      'NumberofPages'           => :total_pages,
+      'NumberofRecordsperPage'  => :per_page,
+      'PageNumber'              => :current_page,
+      'TotalNumberofMatchingRecords' => :total_entries
+
+    # WillPaginate +offset+ correspondes to Endeca StartingRecordNumber - 1
+    reader('StartingRecordNumber' => :offset) {|i| Integer(i) - 1}
+
+    # The previous page number.
+    # Returns nil if there is no previous page.
+    # Borrowed from WillPaginate for compatibility.
+    def previous_page
+      current_page > 1 ? (current_page - 1) : nil
+    end
+
+    # The next page number.
+    # Returns nil if there is no next page.
+    # Borrowed from WillPaginate for compatibility
+    def next_page
+      current_page < total_pages ? (current_page + 1) : nil
+    end
+
+    # The internal collection of Document objects. Array methods are delegated here. 
+    def documents
+      if @raw['Records']
+        @documents ||= @raw['Records'].map(&@document_klass)
+      elsif aggregate?
+        @documents ||= @raw['AggrRecords'].map{|aggregate| aggregate['Records'].first}.map(&@document_klass)
+      else
+        []
+      end
+    end
+
+    def aggregate?
+      @raw['AggrRecords'] ? true : false
+    end
+
+    # The collection of Refinement objects for the collection.
+    def refinements
+      @refinements ||= (@raw['Refinements'] || []).map(&Refinement)
+    end
+
+    # The collection of Breadcrumb objects for the collection.
+    def breadcrumbs
+      @breadcrumbs ||= (@raw['Breadcrumbs'] || []).map(&Breadcrumb)
+    end
+
+    # Return the refinement by name
+    def refinement_by_name(name)
+      refinements.find{|ref| ref.name.downcase == name.downcase}
+    end
+
+    # List of array methods (that are not in +Object+) that need to be
+    # delegated to +documents+.
+    ARRAY_METHODS = (Array.instance_methods - Object.instance_methods).map { |n| n.to_s }
+
+    # List of additional methods that must be delegated to +documents+.
+    MUST_DEFINE = %w[to_a to_ary inspect]
+
+    (ARRAY_METHODS + MUST_DEFINE).uniq.each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(*args, &block)                 # def each(*args, &block)
+          documents.send(:#{method}, *args, &block)  #   documents.send(:each, *args, &block)
+        end                                          # end
+      RUBY
+    end
+
+    # Lie about our class. Borrowed from Rake::FileList
+    # Note: Does not work for case equality (<tt>===</tt>)
+    def is_a?(klass)
+      klass == Array || super(klass)
+    end
+    alias kind_of? is_a?
+
+  end
+end

data/lib/endeca/logging.rb

@@ -0,0 +1,9 @@
+module Endeca
+  module Logging
+    # Log and benchmark the workings of a single block. Will only be called if
+    # Endeca.benchmark is true
+    def log(message)
+      Endeca.logger.debug(message) if Endeca.debug && Endeca.logger
+    end
+  end
+end

data/lib/endeca/map.rb

@@ -0,0 +1,191 @@
+module Endeca
+  class Map
+    def initialize(old_key, new_key=nil)
+      @old_key = old_key
+      @new_key = new_key || @old_key
+      boolean
+    end
+
+    # Convert true and false into their Endeca equivalents
+    def boolean
+      @boolean = true
+      add_transformation { |value| value == true ? 1 : value }
+      add_transformation { |value| value == false ? 0 : value }
+      self
+    end
+
+    def boolean?; @boolean end
+
+    # Mapping actually resides in another key, value pair. Uses Endeca default
+    # join characters (can be overridden by specifying +with+ and/or +join+).
+    #
+    # Example:
+    #   map(:city => :propertycity).into(:ntk => :ntt)
+    #
+    #   Document.all(:city => 'Atlanta')   =>
+    #     ?ntk=propercity&ntt=>Atlanta
+    def into(hash)
+      hash = hash.intern if hash.respond_to?(:intern)
+      if hash.is_a?(Hash)
+        raise ArgumentError, "Only one key/value pair allowed" if hash.size > 1        
+        hash = hash.to_a.flatten
+        hash = {hash.first.to_sym => hash.last.to_sym}
+      end
+      @into = hash
+      with ':'
+      join '|'
+      self
+    end
+
+    def into?; @into end
+
+    # Mapping actually resides in another key, value pair. Uses Endeca default
+    # join characters (can be overridden by specifying +with+ and/or +join+).
+    #
+    # Example:
+    #   map(:city => :propertycity).split_into(:ntk => :ntt)
+    #
+    #   Document.all(:city => 'Atlanta, New York, Los Angeles')   =>
+    #     ?ntk=propercity|propertycity|propertycity&ntt=>Atlanta|New York|Los Angeles
+    def split_into(hash, split_value = ',')
+      into(hash)
+      @split_value = split_value
+    end
+
+    # When mapping multiple key/value pairs to a single parameter value (via
+    # +into+), use this character to join a key with a value.
+    def with(character)
+      @with = character
+      self
+    end
+
+    # When mapping multiple key/value pairs to one or two parameter values (via
+    # +into+), use this character to join each pair.
+    def join(character)
+      @join = character
+      self
+    end
+
+    def join?; @join end
+
+    # Code block to execute on the original data
+    def transform(&block)
+      add_transformation block
+      self
+    end
+
+    # When mapping multiple values, enclose the values in the string provided
+    # to +enclose+.
+    def enclose(str)
+      @enclose = str
+      self
+    end
+
+    def enclose?; @enclose end
+
+    # When mapping multiple key/value pairs, replace existing keys with the new
+    # keys rather than joining.
+    def replace!
+      @replace = true
+      self
+    end
+
+    def replace?; @replace end
+
+    # Perform the mapping as defined for the current_query
+    def perform(current_query)
+      @current_query = current_query.symbolize_keys
+      @current_value = @current_query[@old_key]
+
+      perform_transformation
+      perform_map
+      perform_into
+      perform_join
+
+      return @new_query
+    end
+
+    # Mapping object is equal to other mapping object if their attributes
+    # are equal
+    def ==(other)
+      equality_elements == other.equality_elements
+    end
+
+    def inspect
+      perform({ 'old_key' => "inspect_data" }).inspect
+    end
+
+    private
+
+    def transformations
+      @transformations ||= []
+    end
+
+    def transformations?
+      !transformations.empty?
+    end
+
+    def add_transformation(transformation = nil, &block)
+      transformations.push transformation if transformation
+      transformations.push block if block_given?
+    end
+
+    def perform_transformation
+      return unless transformations?
+      current_value = @current_value
+      transformations.each do |transformation|
+        current_value = transformation.call(current_value)
+      end
+      @current_value = current_value
+    end
+
+    def perform_map
+      @new_query = {@new_key => @current_value}.symbolize_keys
+    end
+
+    def perform_into
+      return unless into?
+      
+      old_key, old_value = Array(@new_query).flatten
+      new_key, new_value = Array(@into).flatten
+
+      if new_value
+        if @split_value
+          @new_query = perform_split(old_key, old_value, new_key, new_value)
+        else
+          @new_query = {new_key => old_key, new_value => old_value}
+        end
+      else
+        new_value = [old_key, old_value].compact.join(@with)
+        new_value = "#{@enclose}(#{new_value})" if enclose?
+        @new_query = {new_key => new_value}
+      end
+    end
+
+    def perform_join
+      return unless join?
+      return if replace?
+
+      @new_query.each do |key, value|
+        @new_query[key] = [@current_query[key], value].compact.join(@join)
+      end
+    end
+
+    protected
+
+    def perform_split(old_key, old_value, new_key, new_value)
+      key = []
+      value = [] 
+      old_value.split(@split_value).each do |val|
+        key << old_key
+        value << val
+      end
+
+      {new_key => key.join(@join), new_value => value.join(@join)}
+    end
+
+    def equality_elements # :nodoc:
+      [@old_key, @new_key, @join, @with, @join]
+    end
+  end
+end