primedia-endeca 0.9.0

data/History.txt

@@ -0,0 +1,4 @@
+== 0.1.0 / 2009-01-20
+
+* 1 major enhancement
+  * Birthday!

data/Manifest.txt

@@ -0,0 +1,31 @@
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+endeca.gemspec
+example/benchmark.rb
+example/listing.rb
+lib/class_to_proc.rb
+lib/core_ext.rb
+lib/endeca.rb
+lib/endeca/dimension.rb
+lib/endeca/document.rb
+lib/endeca/document_collection.rb
+lib/endeca/map.rb
+lib/endeca/readers.rb
+lib/endeca/refinement.rb
+lib/endeca/request.rb
+lib/endeca/transformer.rb
+spec/core_ext_spec.rb
+spec/endeca/dimension_spec.rb
+spec/endeca/document_collection_spec.rb
+spec/endeca/document_spec.rb
+spec/endeca/map_spec.rb
+spec/endeca/readers_spec.rb
+spec/endeca/refinement_spec.rb
+spec/endeca/request_spec.rb
+spec/endeca/transformer_spec.rb
+spec/endeca_spec.rb
+spec/rcov.opts
+spec/spec.opts
+spec/spec_helper.rb

data/README.rdoc

@@ -0,0 +1,60 @@
+endeca
+  by Rein Henrichs and Andy Stone
+
+== DESCRIPTION:
+
+An Endeca client library for Ruby.
+
+== FEATURES/PROBLEMS:
+
+== SYNOPSIS:
+  class Listing < Endeca::Document
+    path 'http://endeca.example.com/api'
+ 
+    map :id => 'R'
+    map(:expand_refinements => :expand_all_dims).into(:M)
+ 
+    float_reader \
+      :latitude,
+      :longitude,
+ 
+    integer_reader :endeca_id
+ 
+    boolean_reader :isawesome => :awesome?
+  end
+
+  Listing.find(1234).awesome?              # => true
+  Listing.find(:all, :per_page => 10).size # => 10
+
+== REQUIREMENTS:
+
+* FakeWeb (for running tests)
+
+== INSTALL:
+
+  sudo gem install primedia-endeca --source=http://gems.github.com
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 PRIMEDIA Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,48 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'endeca'
+
+task :default => 'rcov'
+
+desc "Simple benchmarking"
+task :benchmark do
+  sh('ruby example/benchmark.rb')
+end
+task :bm => :benchmark
+
+desc "Flog your code for Justice!"
+task :flog do
+  sh('flog lib/**/*.rb')
+end
+
+desc "Run all specs and rcov in a non-sucky way"
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.spec_opts = IO.readlines("spec/spec.opts").map {|l| l.chomp.split " "}.flatten
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+  t.rcov_opts = IO.readlines("spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
+end
+
+PROJ.name = 'endeca'
+PROJ.authors = ['Rein Henrichs', 'Andy Stone']
+PROJ.email = ''
+PROJ.url = 'http://github.com/primedia/endeca-ruby'
+PROJ.version = Endeca::VERSION
+PROJ.rubyforge.name = 'endeca-ruby'
+PROJ.readme_file = "README.rdoc"
+
+# EOF

data/example/benchmark.rb

@@ -0,0 +1,13 @@
+require 'benchmark'
+
+$:.unshift(File.expand_path(File.dirname(__FILE__)))
+require 'lib/endeca'
+require 'listing'
+
+RUNS = 10
+Benchmark.bmbm do |results|
+  results.report('Full Request') {RUNS.times{Listing.all}}
+  results.report('Parse JSON') {RUNS.times{Endeca::Request.perform(Listing.get_path,'')}}
+  results.report('Get Net Response') {RUNS.times{Endeca::Request.new(Listing.get_path,'').send(:get_response)}}
+end
+

data/example/listing.rb

@@ -0,0 +1,36 @@
+require 'lib/endeca'
+class Listing < Endeca::Document
+  path 'http://192.168.3.218:8888/bridge/JSONControllerServlet.do'
+
+  reader \
+    :address,
+    :contact,
+    :description,
+    :header,
+    :phone
+
+  integer_reader \
+    'RecordSpec' => :listing_id
+
+  float_reader \
+    :longitude,
+    :latitude
+
+  decimal_reader :rent => :price
+
+  boolean_reader :showemail => :show_email?
+
+  reader(:rh_url => :details_url) {|url| "/{url}"}
+
+  add_reader(:caret_delimited_reader) {|string| string.split('^+^')}
+
+  caret_delimited_reader \
+    :thumbnails,
+    :graphicurl => :graphic_urls
+
+  def coordinates; [latitude, longitude] end
+  def image_url; (graphic_urls || thumbnails).first rescue nil end
+
+  dim_reader :zip, :bathrooms, :bedrooms
+
+end

data/lib/class_to_proc.rb

@@ -0,0 +1,5 @@
+module ClassToProc
+  def to_proc
+    proc(&method(:new))
+  end
+end

data/lib/core_ext.rb

@@ -0,0 +1,73 @@
+class Array
+  def to_params
+    join('&').to_params
+  end
+end
+
+class Class
+  def inherited_property(accessor, default = nil)
+    instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+      @#{accessor} = default
+
+      def set_#{accessor}(value)
+        @#{accessor} = value
+      end
+      alias #{accessor} set_#{accessor}
+
+      def get_#{accessor}
+        return @#{accessor} if instance_variable_defined?(:@#{accessor})
+        superclass.send(:#{accessor})
+      end
+    RUBY
+
+    # @path = default
+    #
+    # def set_path(value)
+    #   @path = value
+    # end
+    # alias_method path, set_path
+
+    # def get_path
+    #   return @path if instance_variable_defined?(:path)
+    #   superclass.send(:path)
+    # end
+  end
+
+  def inherited_accessor(accessor, default = nil)
+    instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+      class << self; attr_writer :#{accessor}; end
+      @#{accessor} = default
+
+      def #{accessor}
+        return @#{accessor} if instance_variable_defined?(:@#{accessor})
+        superclass.send(:#{accessor})
+      end
+    RUBY
+  end
+end
+
+class Hash
+  def to_params
+    map { |k, v|
+      if v.instance_of?(Hash)
+        v.map { |sk, sv|
+          "#{k}[#{sk}]=#{sv}"
+        }.join('&')
+      else
+        "#{k}=#{v}"
+      end
+    }.join('&').to_params
+  end
+end
+
+class NilClass
+  def to_params
+    ''
+  end
+end
+
+class String
+  def to_params
+    URI.escape(self)
+  end
+end

data/lib/endeca.rb

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'net/http'
+require 'json'
+require 'logger'
+
+$:.unshift(File.dirname(__FILE__))
+require 'core_ext'
+require 'class_to_proc'
+require 'endeca/readers'
+require 'endeca/map'
+require 'endeca/transformer'
+require 'endeca/dimension'
+require 'endeca/refinement'
+require 'endeca/request'
+require 'endeca/document_collection'
+require 'endeca/document'
+
+module Endeca
+
+  # :stopdoc:
+  VERSION = '0.9.0'
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Set Endeca.debug = true to turn on query logging
+  class << self
+    attr_accessor :debug
+    attr_accessor :logger
+  end
+
+  self.debug  = false
+  self.logger = Logger.new(STDOUT)
+end

data/lib/endeca/dimension.rb

@@ -0,0 +1,30 @@
+module Endeca
+  class Dimension
+    include Comparable
+    extend ClassToProc
+    extend Readers
+
+    attr_reader :raw
+    def initialize(raw={})
+      @raw=raw
+    end
+    alias_method :attributes, :raw
+
+    reader "DimValueName" => :name
+    reader "PivotLink"    => :to_params
+
+    integer_reader "DimValueID" => :id
+
+    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,109 @@
+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
+    extend ClassToProc
+    extend Readers
+    extend Transformer
+
+    inherited_accessor :mappings, {}
+    inherited_property :path
+    inherited_property :default_params, {}
+
+    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 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, value|
+        @dimensions[name] = Dimension.new(value)
+      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, /^\d+$/
+        by_id(what, query_options)
+      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={})
+      records = request(query_options)['Records']
+      records && new(records.first)
+    end
+
+    # Returns all Documents matching the query options.
+    def self.all(query_options={})
+      DocumentCollection.new(request(query_options), self)
+    end
+
+    # Returns a Document by id
+    def self.by_id(id, query_options={})
+      first(query_options.merge(:id => id))
+    end
+
+    private
+
+    def self.request(query_options)
+      query_options = transform_query_options(query_options.merge(get_default_params))
+      Endeca::Request.perform(get_path, query_options)
+    end
+  end
+end