primedia-endeca 0.9.0

data/lib/endeca/document_collection.rb

@@ -0,0 +1,93 @@
+require 'endeca/document'
+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
+    extend ClassToProc
+    extend Readers
+
+    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
+      @documents ||= (@raw['Records'] || []).map(&@document_klass)
+    end
+
+    # The collection of Refinement objects for the collection.
+    def refinements
+      @refinements ||= (@raw['Refinements'] || []).map(&Refinement)
+    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/map.rb

@@ -0,0 +1,119 @@
+module Endeca
+  class Map
+    def initialize(old_key=nil, new_key=nil)
+      @old_key = old_key
+      @new_key = new_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).in(:ntk => ntt)
+    #
+    #   Document.all(:city => 'Atlanta')   =>
+    #     ?ntk=propercity&ntt=>Atlanta
+    def into(hash)
+      @into = hash
+      @with ||= ':'
+      @join ||= '|'
+      self
+    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
+
+    # Code block to execute on the original data
+    def transform(&block)
+      add_transformation block
+      self
+    end
+
+    # Perform the mapping as defined for the current_query
+    def perform(current_query)
+      @current_query = current_query
+
+      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
+
+    private
+
+    def transformations
+      @transformations ||= []
+    end
+
+    def add_transformation(transformation = nil, &block)
+      transformations.push transformation if transformation
+      transformations.push block if block_given?
+    end
+
+    def perform_transformation
+      current_value = @current_query[@old_key]
+      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}
+    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
+        @new_query = {new_key => old_key, new_value => old_value}
+      else
+        @new_query = {new_key => [old_key, old_value].compact.join(@with)}
+      end
+    end
+
+    def perform_join
+      return unless @join
+      @new_query.each do |key, value|
+        @new_query[key] = [@current_query[key], value].compact.join(@join)
+      end
+    end
+
+    protected
+
+    def equality_elements # :nodoc:
+      [@old_key, @new_key, @join, @with, @join]
+    end
+  end
+end

data/lib/endeca/readers.rb

@@ -0,0 +1,95 @@
+module Endeca
+  class ReaderError < ::StandardError; end
+
+  module Readers
+    def add_reader(name, &block)
+      meta = (class << self; self; end)
+      meta.instance_eval do
+        define_method(name) { |*attrs| reader(*attrs, &block) }
+      end
+    end
+
+    # Maps key/value pairs from the data structure used to initialize a
+    # Endeca object. Allows attribute renaming. Use a block to perform data
+    # injunction on the value as it is set.
+    #
+    # ==== Examples
+    #
+    #   # Specify basic attributes
+    #   reader :title
+    #
+    #   # Attribute renaming
+    #   reader :long_desc => :description
+    #
+    #   # Data injunction
+    #   reader(:title => :upcased_title) { |title| title.upcase }
+    def reader(*attrs,&block)
+      hash = {}
+      block ||= lambda {|x| x}
+
+      hash.update(attrs.pop) if Hash === attrs.last
+
+      attrs.each{ |attr| hash[attr] = attr }
+
+      hash.each do |variable, method|
+        define_method(method) do
+          begin
+            block.call(attributes[variable.to_s])
+          rescue StandardError => e
+            raise Endeca::ReaderError, e.message
+          end
+        end
+      end
+    end
+
+    # Typecasts attributes as integers.
+    #
+    # ==== Examples
+    #   integer_reader :id, :rating
+    def integer_reader(*attrs)
+      reader(*attrs) { |value| Integer(value) }
+    end
+
+    # Typecasts attributes as BigDecimal
+    #
+    # ==== Examples
+    #   decimal_reader :price
+    def decimal_reader(*attrs)
+      require 'bigdecimal' unless defined?(BigDecimal)
+      reader(*attrs) { |value| BigDecimal(value.to_s) }
+    end
+
+    # Typecasts attributes as floats 
+    #
+    # ==== Examples
+    #   float_reader :latitude, :longitude
+    def float_reader(*attrs)
+      reader(*attrs) { |value| Float(value) }
+    end
+
+    # Typecasts attributes as a Perly boolean ("0" == false, "1" == true")
+    #
+    # ==== Examples
+    #   boolean_reader :price
+    def boolean_reader(*attrs)
+      reader(*attrs) { |value| value == "1" ? true : false }
+    end
+
+    def dim_reader(*attrs, &block)
+      hash = {}
+      block ||= lambda {|x| x}
+
+      hash.update(attrs.pop) if Hash === attrs.last
+
+      attrs.each{|attr| hash[attr] = attr}
+
+      hash.each do |variable, method|
+        define_method method do
+          dim = dimensions[variable.to_s]
+          name = dim && dim.name
+          block.call(name)
+        end
+      end
+    end
+  end
+end

data/lib/endeca/refinement.rb

@@ -0,0 +1,29 @@
+module Endeca
+  class Refinement
+    extend ClassToProc
+    extend Readers
+
+    attr_reader :raw
+    def initialize(raw={})
+      @raw = raw
+    end
+
+    def ==(other)
+      id == other.id
+    end
+
+    def inspect
+      "#<#{self.class}=0x#{self.object_id.to_s(16)} id=#{id} name=#{name.inspect}>"
+    end
+
+    def attributes
+      (@raw['Dimensions'] || []).first || {}
+    end
+
+    reader \
+      'DimensionName' => :name,
+      'ExpansionLink' => :to_params
+
+    integer_reader 'DimensionID' => :id
+  end
+end

data/lib/endeca/request.rb

@@ -0,0 +1,58 @@
+require 'uri'
+module Endeca
+  class RequestError < ::StandardError; end
+
+  class Request
+
+    def self.perform(path, query=nil)
+      new(path, query).perform
+    end
+
+    def initialize(path, query=nil)
+      @path  = path.strip
+      @query = query
+    end
+
+    def perform
+      handle_response(get_response)
+    end
+
+    def uri
+      return @uri if @uri
+
+      @uri = URI.parse(@path)
+      @uri.query = query_string
+      @uri
+    end
+
+    private
+
+    def get_response #:nodoc:
+      http = Net::HTTP.new(uri.host, uri.port)
+      request = Net::HTTP::Get.new(uri.request_uri)
+
+      Endeca.logger.debug "ENDECA REQUEST: uri=#{uri}" if Endeca.debug
+      http.request(request)
+    end
+
+    # Raises exception Net::XXX (http error code) if an http error occured
+    def handle_response(response) #:nodoc:
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(response.body)
+      else
+        response.error! # raises exception corresponding to http error Net::XXX
+      end
+
+    rescue => e
+      raise RequestError, e.message
+    end
+
+    def query_string
+      query_string_parts = [@uri.query, @query.to_params]
+      query_string_parts.reject!{ |s| s.nil? || s.empty? }
+
+      query_string_parts.empty? ? nil : query_string_parts.join('&')
+    end
+  end
+end

data/lib/endeca/transformer.rb

@@ -0,0 +1,40 @@
+module Endeca
+  module Transformer
+    # Requires existence of mappings accessor (Hash)
+    #
+    # ==== Examples
+    #   # Standard map call that returns an Endeca::Map object
+    #   map(:old_name => :new_name)
+    #
+    #   # Allows to to create a map object to perform other functionality such
+    #   # as transformations.
+    #   map(:new_name)
+    def map(mapping = {})
+      mapping = {mapping => mapping} if Symbol === mapping
+
+      if mapping.length > 1
+        raise ArgumentError, "map only accepts one key=>value pair" 
+      end
+
+      mapping.each do |key, transformed_key|
+        transformed_key = key unless transformed_key
+        return mappings[key] = Map.new(key, transformed_key)
+      end
+    end
+
+    # Use the mappings hash to replace domain level query query_options with
+    # their Endeca equivalent.
+    def transform_query_options(query_options)
+      query = query_options.dup
+      query.each do |key, value|
+        if mappings[key]
+          new_options = mappings[key].perform(query_options)
+          query_options.delete(key)
+          query_options.update(new_options)
+        end
+      end
+      query_options
+    end
+ 
+  end
+end

data/spec/core_ext_spec.rb

@@ -0,0 +1,52 @@
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Array do
+  describe "#to_params" do
+    it "should join the elements with ampersand" do
+      ["foo=1","bar=3"].to_params.should == "foo=1&bar=3"
+    end
+
+    it "should escape all elements" do
+      ['|=|','||=||'].to_params.should == '%7C=%7C&%7C%7C=%7C%7C'
+    end
+  end
+end
+
+describe Hash do
+  describe "#to_params" do
+    it "should join a key-value pair with equals" do
+      {:foo => :bar}.to_params.should == 'foo=bar'
+    end
+
+    it "should join two key-value pairs with ampersand" do
+      result = {:foo => :bar, :bizz => :bazz}.to_params
+      (result == 'foo=bar&bizz=bazz' || result == 'bizz=bazz&foo=bar').should be_true
+    end
+
+    it "should use brackets to indicate a nested hash" do
+      {:foo => {:foo => :bar}}.to_params.should == 'foo[foo]=bar'
+    end
+
+    it "should escape all elements" do
+      {'|' => '||'}.to_params.should == '%7C=%7C%7C'
+    end
+  end
+end
+
+describe NilClass do
+  describe "to_params" do
+    it "should return the empty string" do
+      nil.to_params.should == ''
+    end
+  end
+end
+
+describe String do
+  describe "#to_params" do
+    it "should URI escape the contents" do
+      '|'.to_params.should == '%7C'
+    end
+  end
+end
+
+# EOF