bento_search 0.0.1

data/app/models/bento_search/registrar.rb

@@ -0,0 +1,70 @@
+
+# Holds a list of registered search engines with configuration. 
+# There's one global one referened by BentoSearch module, but one
+# might want to create multiple. 
+class BentoSearch::Registrar
+  class ::BentoSearch::NoSuchEngine < Exception ; end
+  
+  def initialize    
+    @registered_engine_confs = {}
+  end
+  
+  # Register a configuration for a BentoSearch search engine. 
+  # While some parts of BentoSearch can be used without globally registering
+  # a configuration, it is neccesary for features like AJAX load, and
+  # convenient in other places. 
+  #
+  # BentoSearch.register_engine("gbs") do |conf|
+  #    conf.engine = "GoogleBooksSearch"
+  #    conf.api_key = "my_key"
+  # end
+  #
+  # BentoSearch.get_engine("gbs")
+  #    => a BentoSearch::GoogleBooksSearch, configured as specified. 
+  #
+  # The first parameter identifier, eg "gbs", may be used in some
+  # URLs, for AJAX etc. 
+  def register_engine(id, &block)
+    conf = Confstruct::Configuration.new(&block)
+    conf.id = id.to_s
+    
+    raise ArgumentError.new("Must supply an `engine` class name") unless conf.engine
+    
+    @registered_engine_confs[id] = conf    
+  end
+  
+  # Get a configured SearchEngine, using configuration and engine
+  # class previously registered for `id` with #register_engine. 
+  # Raises a BentoSearch::NoSuchEngine if is is not registered.
+  def get_engine(id)
+    conf = @registered_engine_confs[id.to_s]
+    
+    raise BentoSearch::NoSuchEngine.new("No registered engine for identifier '#{id}'") unless conf
+    
+    # Figure out which SearchEngine class to instantiate
+    klass = constantize(conf.engine)
+    
+    return klass.new( conf )
+  end
+  
+  # Mostly just used for testing
+  def reset_engine_registrations!
+    @@registered_engine_confs = {}
+  end
+  
+  protected
+  
+  # Turn a string into a constant/class object, lexical lookup
+  # within BentoSearch module. Can use whatever would be legal
+  # in ruby, "A", "A::B", "::A::B" (force top-level lookup), etc. 
+  def constantize(klass_string)        
+    unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ klass_string
+      raise NameError, "#{klass_string.inspect} is not a valid constant name!"
+    end
+
+    BentoSearch.module_eval(klass_string, __FILE__, __LINE__)
+  end
+  
+
+  
+end

data/app/models/bento_search/result_item.rb

@@ -0,0 +1,203 @@
+module BentoSearch
+  # Data object representing a single hit from a search, normalized
+  # with common data fields. Usually held in a BentoSearch::Results object.
+  #
+  # ANY field can be nil, clients should be aware.  
+  class ResultItem
+    include ERB::Util # for html_escape for our presentational stuff
+    include ActionView::Helpers::OutputSafetyHelper # for safe_join
+    
+    # Can initialize with a hash of key/values
+    def initialize(args = {})
+      args.each_pair do |key, value|
+        send("#{key}=", value)
+      end
+      
+      self.authors ||= []
+      self.other_links ||= []
+      
+      self.custom_data ||= {}
+    end
+    
+    # Array (possibly empty) of BentoSearch::Link objects
+    # representing additional links. Often SearchEngine's themselves
+    # won't include any of these, but Decorators will be used
+    # to add them in. 
+    attr_accessor :other_links
+    
+    # * dc.title 
+    # * schema.org CreativeWork: 'name'    
+    attr_accessor :title
+    
+    # When an individual seperate subtitle is available. 
+    # May also be nil with subtitle in "title" field after colon. 
+    # 
+    # * 
+    attr_accessor :subtitle
+    
+    # usually a direct link to the search provider's 'native' page. 
+    # Can be changed in actual presentation with a Decorator.
+    # * schema.org CreativeWork: 'url'
+    attr_accessor :link
+    
+    # normalized controlled vocab title, important this is supplied
+    # if possible for OpenURL generation and other features. 
+    #
+    # schema.org 'type' that's a sub-type of CreativeWork. 
+    # should hold a string that, when appended to "http://schema.org/"
+    # is a valid schema.org type uri, that sub-types CreativeWork. Eg.
+    # * Article
+    # * Book
+    # * Movie
+    # * MusicRecording
+    # * Photograph
+    # * SoftwareApplication
+    # * WebPage
+    # * VideoObject
+    # * AudioObject
+    # * SoftwareApplication
+    # 
+    # 
+    # 
+    # OR one of these symbols, sadly not covered by schema.org types:
+    # * :serial (magazine or journal)
+    # * :dissertation (dissertation or thesis)
+    # * :conference_paper  # individual paper
+    # * :conference_proceedings # collected proceedings
+    # * :report # white paper or other report.
+    # * :book_item # section or exceprt from book.
+    #
+    # Note: We're re-thinking this, might allow uncontrolled
+    # in here instead. 
+    attr_accessor :format    
+    
+    # uncontrolled presumably english-language format string.
+    # if supplied will be used in display in place of controlled
+    # format. 
+    attr_accessor :format_str
+    
+    # year published. a ruby int
+    # PART of:. 
+    # * schema.org CreativeWork "datePublished", year portion
+    # * dcterms.issued, year portion
+    # * prism:coverDate, year portion
+    attr_accessor :year
+    
+    attr_accessor :volume
+    attr_accessor :issue
+    attr_accessor :start_page
+    attr_accessor :end_page
+    
+    attr_accessor :journal_title
+    attr_accessor :issn
+    attr_accessor :isbn
+    
+    attr_accessor :doi
+    
+    # usually used for books rather than articles
+    attr_accessor :publisher
+    
+    # an openurl kev-encoded context object. optional,
+    # only if source provides one that may be better
+    # than can be constructed from individual elements above
+    attr_accessor :openurl_kev_co
+    
+    # Short summary of item. 
+    # Mark .html_safe if it includes html -- creator is responsible
+    # for making sure html is safely sanitizied and/or stripped,
+    # rails ActionView::Helpers::Sanistize #sanitize and #strip_tags
+    # may be helpful. 
+    attr_accessor :abstract
+    
+    # An array (order matters) of BentoSearch::Author objects
+    # add authors to it with results.authors << Author
+    attr_accessor :authors
+    
+    # engine-specific data not suitable for abstract API, usually
+    # for internal use. 
+    attr_accessor :custom_data
+    
+    
+    # Returns a ruby OpenURL::ContextObject (NISO Z39.88).     
+    def to_openurl
+      BentoSearch::OpenurlCreator.new(self).to_openurl
+    end
+    
+    ##################
+    # Presentation related methods. 
+    # yes, it really makes sense to include them here, they can be overridden
+    # by decorators. 
+    # May extract these to their own base decorator module at some point,
+    # but the OO hieararchy would be basically the same either way. 
+    #######################
+    
+    
+    # How to display a BentoSearch::Author object as a name
+    def author_display(author)
+      if (author.first && author.last)
+        "#{author.last}, #{author.first.slice(0,1)}"
+      elsif author.display
+        author.display
+      elsif author.last
+        author.last
+      else
+        nil
+      end
+    end
+    
+    # Put together title and subtitle if neccesary. 
+    def complete_title
+      t = self.title
+      if self.subtitle
+        t = safe_join([t, ": ", self.subtitle], "")        
+      end
+      
+      if t.blank?
+        t = I18n.translate("bento_search.missing_title")
+      end
+      
+      return t
+    end
+    
+    
+    
+    # A simple user-displayable citation, _without_ author/title.
+    # the journal, year, vol, iss, page; or publisher and year; etc. 
+    # Constructed from individual details. Not formal APA or MLA or anything,
+    # just a rough and ready display. 
+    #
+    # TODO: Should this be moved to a rails helper method? Not sure. 
+    def published_in
+      result_elements = []
+
+      unless year.blank?
+        # wrap year in a span so we can bold it. 
+        result_elements.push "<span class='year'>#{year}</span>"
+      end
+      
+      result_elements.push(journal_title) unless journal_title.blank?      
+      
+      if journal_title.blank? && ! publisher.blank?
+        result_elements.push html_escape publisher
+      end
+      
+      if (! volume.blank?) && (! issue.blank?)
+        result_elements.push html_escape "#{volume}(#{issue})"
+      else
+        result_elements.push html_escape volume unless volume.blank?
+        result_elements.push html_escape issue unless issue.blank?
+      end
+      
+      if (! start_page.blank?) && (! end_page.blank?)
+        result_elements.push html_escape "pp. #{start_page}-#{end_page}"
+      elsif ! start_page.blank?
+        result_elements.push html_escape "p. #{start_page}"
+      end
+      
+      return nil if result_elements.empty?
+      
+      return result_elements.join(", ").html_safe
+    end
+    
+  end
+end

data/app/models/bento_search/results.rb

@@ -0,0 +1,54 @@
+module BentoSearch
+  # An array-like object (in fact it-subclasses Array) that holds
+  # a page of search results. But also has some meta-data about the
+  # search itself (query, paging, etc). 
+  
+  # If #error is non-nil, object  may not have real results, but
+  # be an error. You can use failed? to see. 
+  class Results < ::Array
+    attr_accessor :total_items
+    # 0-based index into total results, used for pagination
+    attr_accessor :start
+    # per_page setting, can be used for pagination. 
+    attr_accessor :per_page
+
+    # If error is non-nil, it's an error condition with no real results.
+    # error should be a hash with these (and possibly other) keys, although
+    # none of these are required to be non-nil. 
+    # [:status] 
+    #     A (usually) non-succesful HTTP status code. May be nil. 
+    # [:message]
+    #     A short message explaining error, usually provided by external
+    #     service. NOT suitable for showing to end-users. May be nil. 
+    # [:end_user_message]
+    #     A message suitable for showing to end-users. May be nil. 
+    # [:error_info]
+    #     A service-specific way of reporting more error info, for developers,
+    #     not suitable for end-users. Might be a string, might be a hash,
+    #     depends on the service. may be nil. 
+    # [:exception]
+    #     Possibly a ruby exception object. may be nil. 
+    attr_accessor :error
+    
+    # time it took to do search, in seconds. 
+    attr_accessor :timing
+    
+    # search arguments as normalized by SearchEngine, not neccesarily
+    # directly as input. A hash. 
+    attr_accessor :search_args
+    # Registered id of engine used to create these results, 
+    # may be nil if used with an unregistered engine.
+    attr_accessor :engine_id
+    
+    # Returns a BentoSearch::Results::Pagination, that should be suitable
+    # for passing right to Kaminari (although Kaminari isn't good about doc/specing
+    # it's api, so might break), or convenient methods for your own custom UI. 
+    def pagination
+      Pagination.new( total_items, search_args)
+    end
+    
+    def failed?
+      ! error.nil?
+    end
+  end
+end

data/app/models/bento_search/results/pagination.rb

@@ -0,0 +1,67 @@
+
+# An object intended to be compatible with kaminari for pagination,
+# although kaminari doesn't doc/spec exactly what you need, so might
+# break in future. Could be useful for your own custom pagination too. 
+#
+# You don't normally create one of these yourself, you get one returned
+# from Results#pagination
+class BentoSearch::Results::Pagination
+  
+  # first arg is results.total_items, second is result
+  # of normalized_args from searchresults. 
+  #
+  # We don't do the page/start normalization calc here,
+  # we count on them both being passed in, already calculated
+  # by normalize_arguments in SearchResults. Expect :page, 0-based
+  # :start, and :per_page
+  def initialize(total, normalized_args)
+    @total_count = total || 0
+    @per_page = normalized_args[:per_page] || 10
+    @current_page = normalized_args[:page]  || 1
+    @start_record = (normalized_args[:start] || 0) + 1 
+  end
+    
+  def current_page
+    @current_page
+  end
+  
+  # 1-based start, suitable for showing to user
+  # Can be 0 for empty result set. 
+  def start_record
+    [@start_record, count_records].min
+  end
+  
+  # 1-based last record in window, suitable for showing to user.
+  # Can be 0 for empty result set.   
+  def end_record
+    [start_record + per_page - 1, count_records].min
+  end
+  
+  # If nil is passed in, will normalize to 0 so things doing math
+  # comparisons won't raise. 
+  def count_records
+    @total_count
+  end
+  
+  def total_pages
+    (@total_count.to_f / @per_page).ceil
+  end
+  # kaminari wants both, weird. 
+  alias num_pages total_pages
+
+  
+  def first_page?
+    current_page == 1
+  end
+  
+  def last_page?
+    current_page >= total_pages
+  end
+     
+  def per_page
+    @per_page
+  end
+  # kaminari wants it called this.
+  alias limit_value per_page
+  
+end

data/app/models/bento_search/search_engine.rb

@@ -0,0 +1,219 @@
+require 'active_support/concern'
+require 'active_support/core_ext/module/delegation'
+require 'confstruct'
+
+
+module BentoSearch
+  # Module mix-in for bento_search search engines. 
+  #
+  # ==Using a SearchEngine 
+  #
+  # * init/config
+  # * search
+  #   * pagination, with max per_page
+  #   * search fields, with semantics. ask for supported search fields. 
+  #
+  # == Standard config
+  #  * item_decorators : Array of Modules that will be decorated. See Decorators section. 
+  #
+  # == Implementing a SearchEngine
+  #
+  # `include BentoSearch::SearchEngine`
+  #
+  #  a SearchEngine's state should not be search-specific, but
+  #  is configuration specific. Don't store anything specific
+  #  to a specific search in iVars. 
+  #
+  #  Do implement `#search(*args)`
+  # 
+  #  Do use HTTPClient, if possible, for http searches, 
+  #  using a class-level HTTPClient to maintain persistent connections. 
+  #
+  #  Other options:
+  #  * implement a class-level `self.required_configuration' returning
+  #    an array of config keys or dot keypaths, and it'll raise on init
+  #    if those config's weren't supplied. 
+  #  * max per page
+  #  * search fields
+  #
+  #  Some engines support `:auth => true` for elevated access to affiliated
+  #  users. 
+  #
+  module SearchEngine
+    DefaultPerPage = 10
+    
+    extend ActiveSupport::Concern
+    
+    include Capabilities
+    
+    included do
+      attr_accessor :configuration      
+    end
+    
+    # If specific SearchEngine calls initialize, you want to call super
+    # handles configuration loading, mostly. Argument is a
+    # Confstruct::Configuration or Hash. 
+    def initialize(aConfiguration = Confstruct::Configuration.new)
+      # init, from copy of default, or new      
+      if self.class.default_configuration
+        self.configuration = Confstruct::Configuration.new(self.class.default_configuration)
+      else
+        self.configuration = Confstruct::Configuration.new
+      end
+      # merge in current instance config
+      self.configuration.configure ( aConfiguration )
+      
+      # global defaults?
+      self.configuration[:item_decorators] ||= []
+            
+      # check for required keys
+      if self.class.required_configuration
+        self.class.required_configuration.each do |required_key|          
+          if self.configuration.lookup!(required_key.to_s, "**NOT_FOUND**") == "**NOT_FOUND**"
+            raise ArgumentError.new("#{self.class.name} requires configuration key #{required_key}")
+          end
+        end
+      end
+      
+    end
+    
+    # Calls individual engine #search_implementation.
+    # first normalizes arguments, also adds on standard metadata
+    # to results. 
+    def search(*arguments)
+      start_t = Time.now
+      
+      arguments = normalized_search_arguments(*arguments)
+
+      results = search_implementation(arguments)
+      
+      decorate(results)      
+      
+      # standard result metadata
+      results.start = arguments[:start] || 0
+      results.per_page = arguments[:per_page]
+      
+      results.search_args   = arguments
+      results.engine_id     = configuration.id
+      
+      results.timing = (Time.now - start_t)
+        
+      return results
+    end
+        
+
+    
+    def normalized_search_arguments(*orig_arguments)
+      arguments = {}
+      
+      # Two-arg style to one hash, if present
+      if (orig_arguments.length > 1 ||
+          (orig_arguments.length == 1 && ! orig_arguments.first.kind_of?(Hash)))
+        arguments[:query] = orig_arguments.delete_at(0)      
+      end
+
+      arguments.merge!(orig_arguments.first)  if orig_arguments.length > 0
+      
+      
+      # allow strings for pagination (like from url query), change to
+      # int please. 
+      [:page, :per_page, :start].each do |key|
+        arguments.delete(key) if arguments[key].blank?
+        arguments[key] = arguments[key].to_i if arguments[key]
+      end   
+      arguments[:per_page] ||= DefaultPerPage
+      
+      # illegal arguments      
+      if (arguments[:start] && arguments[:page])
+        raise ArgumentError.new("Can't supply both :page and :start")
+      end
+      if ( arguments[:per_page] && 
+           self.max_per_page && 
+           arguments[:per_page] > self.max_per_page)
+        raise ArgumentError.new("#{arguments[:per_page]} is more than maximum :per_page of #{self.max_per_page} for #{self.class}")
+      end
+   
+      
+      # Normalize :page to :start, and vice versa
+      if arguments[:page]
+        arguments[:start] = (arguments[:page] - 1) * arguments[:per_page]
+      elsif arguments[:start]
+        arguments[:page] = (arguments[:start] / arguments[:per_page]) + 1
+      end
+      
+      # normalize :sort from possibly symbol to string
+      # TODO: raise if unrecognized sort key?
+      if arguments[:sort]
+        arguments[:sort] = arguments[:sort].to_s
+      end
+      
+      # translate semantic_search_field to search_field, or raise if
+      # can't. 
+      if (semantic = arguments.delete(:semantic_search_field)) && ! semantic.blank?
+        
+        mapped = self.semantic_search_map[semantic.to_s]
+        unless mapped
+          raise ArgumentError.new("#{self.class.name} does not know about :semantic_search_field #{semantic}")
+        end
+        arguments[:search_field] = mapped
+      end
+              
+      return arguments
+    end
+    alias_method :parse_search_arguments, :normalized_search_arguments
+    
+    
+
+   
+    
+    protected
+    
+    # Extend each result with each specified decorator module
+    def decorate(results)      
+      results.each do |result|
+        configuration.item_decorators.each do |decorator|
+          result.extend decorator
+        end
+      end
+    end
+    
+    
+    module ClassMethods
+      
+      # If support fielded search, over-ride to specify fields
+      # supported. Returns a hash, key is engine-specific internal
+      # search field, value is nil or a hash of metadata about
+      # the search field, including semantic mapping. 
+      #
+      # def search_field_definitions
+      #  { "intitle" => {:semantic => :title}}
+      # end
+      def search_field_definitions
+        {}
+      end
+      
+            
+      # Returns list of string internal search_field's that can
+      # be supplied to search(:search_field => x)
+      def search_keys        
+        return search_field_definitions.keys
+      end
+      
+      
+      
+      # Over-ride returning a hash or Confstruct with 
+      # any configuration values you want by default. 
+      # actual user-specified config values will be deep-merged
+      # into the defaults. 
+      def default_configuration
+      end
+      
+      # Over-ride returning an array of symbols for required
+      # configuration keys.
+      def required_configuration
+      end
+      
+    end
+    
+  end
+end