exlibris-primo 0.1.5 → 1.0.0

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2012 YOURNAME
+Copyright 2012 Scot Dalton
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,111 @@
+# Exlibris::Primo
+[![Build Status](https://secure.travis-ci.org/scotdalton/exlibris-primo.png)](https://secure.travis-ci.org/scotdalton/exlibris-primo)
+[![Dependency Status](https://gemnasium.com/scotdalton/exlibris-primo.png)](https://gemnasium.com/scotdalton/exlibris-primo)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/scotdalton/exlibris-primo)
+
+Exlibris::Primo offers a set of classes for interacting with the ExLibris Primo APIs.
+
+## Exlibris::Primo::Search
+The Exlibris::Primo::Search class performs a search against Primo for given parameters
+and exposes the set of holdings, fulltext links, table of contents links, and related links for each record retrieved.
+
+### Example of Exlibris::Primo::Search in action
+Search can search by a query
+
+    search = Exlibris::Primo::Search.new(:base_url => "http://primo.institution.edu",
+      :institution => "INSTITUTION", :page_size => "20")
+    search.add_query_term "0143039008", "isbn", "exact"
+    count = search.size #=> 20+ (assuming there are 20+ records with this isbn)
+    facets = search.facets #=> Array of Primo facets
+    records = search.records #=> Array of Primo records
+    records.size #=> 20 (assuming there are 20+ records with this isbn)
+    records.each do |record_id, record|
+      holdings = record.holdings #=> Array of Primo holdings
+      fulltexts = record.fulltexts #=> Array of Primo full texts
+      table_of_contents = record.table_of_contents #=> Array of Primo tables of contents
+      related_links = record.related_links #=> Array of Primo related links
+    end
+
+Or by a given record id
+
+    search = Exlibris::Primo::Search.new(:base_url => "http://primo.institution.edu",
+      :institution => "INSTITUTION")
+    search.record_id! "aleph0123456789"
+    count = search.size #=> 1
+    records = search.records #=> Array of Primo records
+    records.size #=> 1
+    record = records.first #=> Primo record
+    holdings = record.holdings #=> Array of Primo holdings
+    fulltexts = record.fulltexts #=> Array of Primo full texts
+    table_of_contents = record.table_of_contents #=> Array of Primo tables of contents
+    related_links = record.related_links #=> Array of Primo related links
+
+Search has some methods for setting search params
+
+    search = Exlibris::Primo::Search.new(:base_url => "http://primo.institution.edu",
+      :institution => "INSTITUTION")
+    search.isbn_is "0143039008" #=> Equivalent to search.add_query_term "0143039008", "isbn", "exact"
+    search.title_begins_with "Travels" #=> Equivalent to search.add_query_term "Travels", "title", "begins_with"
+    search.creator_contains "Greene" #=> Equivalent to search.add_query_term "Greene", "creator", "contains"
+
+Search can take a record id the initial hash
+
+    search = Exlibris::Primo::Search.new(:base_url => "http://primo.institution.edu",
+      :institution => "INSTITUTION", :record_id => "aleph0123456789")
+
+Search can also be chained using the ! version of the attribute writer
+
+    search = Exlibris::Primo::Search.new.base_url!("http://primo.institution.edu").
+      institution!("INSTITUTION").record_id!("aleph0123456789")
+
+Or
+
+    search = Exlibris::Primo::Search.new.base_url!("http://primo.institution.edu").
+      institution!("INSTITUTION").title_begins_with("Travels").
+        creator_contains("Greene").genre_is("Book")
+
+## Exlibris::Primo::Config
+Exlibris::Primo::Config allows you to specify global configuration parameter for Exlibris::Primo
+
+    Exlibris::Primo.configure do |config|
+      config.base_url = "http://primo.institution.edu"
+      config.institution = "INSTITUTION"
+      config.libraries = { "LIB_CODE1" => "Library Decoded 1", "LIB_CODE2" => "Library Decoded 2",
+        "LIB_CODE3" => "Library Decoded 3" }
+    end
+
+Exlibris::Primo::Config can also read in from a YAML file that specifies the various config elements
+
+    Exlibris::Primo.configure do |config|
+      config.load_yaml "./config/primo.yml"
+    end
+
+## Exlibris::Primo::EShelf
+The Exlibris::Primo::EShelf class provides methods for reading a given user's Primo eshelf 
+and eshelf structure as well as adding and removing records.
+
+## Example of Exlibris::Primo::EShelf in action
+    eshelf = Exlibris::Primo::EShelf.new(:user_id => "USER_ID",
+      :base_url => "http://primo.institution.edu", :insitution => "INSTITUTION")
+    records = eshelf.records
+    size = eshelf.size
+    basket_id = eshelf.basket_id
+    eshelf.add_records(["PrimoRecordId","PrimoRecordId2"], basket_id)
+
+## Exlibris::Primo::Reviews
+The Exlibris::Primo::Reviews class provides methods for reading a given user's Primo reviews 
+features.
+
+## Example of Exlibris::Primo::Reviews in action
+    reviews = Exlibris::Primo::Reviews.new(:record_id => "aleph0123456789", :user_id => "USER_ID",
+      :base_url => "http://primo.institution.edu", :insitution => "INSTITUTION")
+    user_record_reviews = reviews.reviews #=> Array of Primo reviews
+
+## Exlibris::Primo::Tags
+The Exlibris::Primo::Tags class provides methods for reading a given user's Primo tags 
+features.
+
+## Example of Exlibris::Primo::Tags in action
+    tags = Exlibris::Primo::Tags.new(:record_id => "aleph0123456789", :user_id => "USER_ID",
+      :base_url => "http://primo.institution.edu", :insitution => "INSTITUTION")
+    user_record_tags = tags.tags #=> Array of Primo tags

data/Rakefile

@@ -27,7 +27,8 @@ require 'rake/testtask'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
   t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.test_files = FileList['test/*_test.rb', 
+    'test/**/*_test.rb', 'test/**/**/*_test.rb']
   t.verbose = false
 end
 

data/lib/exlibris-primo.rb

@@ -1,14 +1,4 @@
-PRIMO_PATH = File.dirname(__FILE__) + "/exlibris/primo/"
-[ 
-  'record',
-  'eshelf',
-  'web_service',
-  'holding',
-  'related_link',
-  'rsrc',
-  'toc',
-  'searcher',
-  'source/aleph'
-].each do |library|
-  require PRIMO_PATH + library
-end
+# Leverage ActiveSupport core extensions
+require 'active_support/core_ext'
+require "require_all"
+require_all "#{File.dirname(__FILE__)}/exlibris/"

data/lib/exlibris/primo.rb

@@ -0,0 +1,13 @@
+module Exlibris
+  module Primo
+    class << self
+      def configure
+        yield config
+      end
+
+      def config
+        @config ||= Config
+      end
+    end
+  end
+end

data/lib/exlibris/primo/abstract.rb

@@ -0,0 +1,28 @@
+module Exlibris
+  module Primo
+    # 
+    # If a class is abstract, it can't be instantiated.
+    # 
+    module Abstract
+      def self.included(klass)
+        klass.class_eval do
+          extend ClassAttributes
+        end
+      end
+
+      module ClassAttributes
+        def abstract
+          @abstract ||= false
+        end
+        alias :abstract? :abstract
+
+        attr_writer :abstract
+        protected :abstract=
+      end
+
+      def initialize *args
+        raise NotImplementedError.new("Cannot instantiate #{self.class.name}.  It is abstract") if self.class.abstract?
+      end
+    end
+  end
+end

data/lib/exlibris/primo/chain_gang/README.md

@@ -0,0 +1,9 @@
+# ChainGang Modules
+ChainGang modules contain methods that are "chainable", i.e. they return `self`.
+
+## ! vs =
+ChainGang methods that take arguments are defined with a trailing `!` and aliased
+with a trailing `=`.  At the time of writing, the `=` version can't be chained because
+the Ruby virtual machine seems to compile the two methods slightly differently and the
+`=` version returns the arguments rather than `self`.  The `=` version is intended to
+be used as an `attr_writer`.

data/lib/exlibris/primo/chain_gang/base.rb

@@ -0,0 +1,121 @@
+module Exlibris
+  module Primo
+    module ChainGang
+      # = Primo ChainGang Base Attributes
+      # These base attributes are included in 
+      # Search, Eshelf, Tags and Reviews and allow 
+      # for chaining methods together.
+      # 
+      # == Examples
+      # 
+      #     search = Search.new.base_url!("http://primo.library.edu").
+      #       institution!("PRIMO").ip!("127.0.0.1") 
+      #       #=> #<Exlibris::Primo::Search @base_url="http://primo.library.edu", 
+      #             @institution="PRIMO", @request_attributes={:base_url => "http://primo.library.edu", 
+      #               :institution => "PRIMO", :ip => "127.0.0.1"}>
+      # 
+      #     eshelf = Eshelf.new.base_url!("http://primo.library.edu").
+      #       institution!("PRIMO").ip!("127.0.0.1")
+      #       #=> #<Exlibris::Primo::Eshelf @base_url="http://primo.library.edu", 
+      #             @institution="PRIMO", @request_attributes={:base_url => "http://primo.library.edu", 
+      #               :institution => "PRIMO", :ip => "127.0.0.1"}>
+      # 
+      #     reviews = Reviews.new.base_url!("http://primo.library.edu").
+      #       institution!("PRIMO").ip!("127.0.0.1")
+      #       #=> #<Exlibris::Primo::Reviews @base_url="http://primo.library.edu", 
+      #             @institution="PRIMO", @request_attributes={:base_url => "http://primo.library.edu", 
+      #               :institution => "PRIMO", :ip => "127.0.0.1"}>
+      # 
+      #     tags = Tags.new.base_url!("http://primo.library.edu").
+      #       institution!("PRIMO").ip!("127.0.0.1")
+      #       #=> #<Exlibris::Primo::Tags @base_url="http://primo.library.edu", 
+      #             @institution="PRIMO", @request_attributes={:base_url => "http://primo.library.edu", 
+      #               :institution => "PRIMO", :ip => "127.0.0.1"}>
+      # 
+      
+      module Base
+        # 
+        # Set base URL for the Primo request.
+        # 
+        def base_url!(base_url)
+          @base_url = base_url
+          request_attributes[:base_url] = "#{base_url}"
+          self
+        end
+        alias :base_url= :base_url!
+
+        # 
+        # Set institution for the Primo request.
+        # 
+        def institution!(institution)
+          @institution = institution
+          request_attributes[:institution] = "#{institution}"
+          self
+        end
+        alias :institution= :institution!
+
+        # 
+        # Set client IP for the Primo request.
+        # 
+        def ip!(ip)
+          request_attributes[:ip] = "#{ip}"
+          self
+        end
+        alias :ip= :ip!
+        alias :client_ip! :ip!
+        alias :client_ip= :ip!
+
+        # 
+        # Set the group for the Primo request.
+        # 
+        def group!(group)
+          request_attributes[:group] = "#{group}"
+          self
+        end
+        alias :group= :group!
+
+        # 
+        # Set the PDS handle for the Primo request.
+        # 
+        def pds_handle!(pds_handle)
+          request_attributes[:pds_handle] = "#{pds_handle}"
+          self
+        end
+        alias :pds_handle= :pds_handle!
+
+        # 
+        # Specifies that the Primo request is coming from on campus.
+        # 
+        def on_campus
+          request_attributes[:on_campus] = "true"
+          self
+        end
+
+        # 
+        # Specifies that the Primo request is coming from off campus.
+        # 
+        def off_campus
+          request_attributes[:on_campus] = "false"
+          self
+        end
+
+        # 
+        # Specifies that the Primo request user is logged in.
+        # 
+        def logged_in
+          request_attributes[:is_logged_in] = "true"
+          self
+        end
+
+        # 
+        # Specifies that the Primo request user is logged out.
+        # 
+        def logged_out
+          request_attributes[:is_logged_in] = "false"
+          self
+        end
+        alias :logged_off :logged_out
+      end
+    end
+  end
+end

data/lib/exlibris/primo/chain_gang/record.rb

@@ -0,0 +1,18 @@
+module Exlibris
+  module Primo
+    module ChainGang
+      module Record
+        attr_reader :record_id
+
+        # 
+        # Set the record_id
+        # 
+        def record_id!(record_id)
+          @record_id = record_id
+          self
+        end
+        alias :record_id= :record_id!
+      end
+    end
+  end
+end

data/lib/exlibris/primo/chain_gang/search.rb

@@ -0,0 +1,319 @@
+module Exlibris
+  module Primo
+    module ChainGang
+      # = Primo ChainGang Search
+      # These search attributes are included in
+      # Exlibris::Primo::Search and allow for chaining methods together.
+      #
+      # == Examples
+      #
+      #     Search.new.title("Travels", "title", "contains").
+      #           and.add_query_term("Greene", "creator", "contains").search
+      #
+      module Search
+        def self.included(klass)
+          klass.class_eval do
+            extend ClassAttributes
+          end
+        end
+
+        module ClassAttributes
+          def indexes
+            @indexes ||= [:any, :stitle, :title, :creator, :genre, :author, :isbn]
+          end
+
+          def indexes_map
+            @indexes_map ||= {:author => :creator}
+          end
+
+          def precisions
+            @precisions ||= [:is, :begins_with, :contains, :starts_with]
+          end
+
+          def precisions_map
+            @precisions_map ||= {:is => :exact, :starts_with => :begins_with}
+          end
+        end
+
+        #
+        # Set the boolean operator for the search
+        # to "AND".
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_query_term("Travels", "title", "contains").
+        #       and.add_query_term("Greene", "creator", "contains").search
+        #
+        def and
+          search_request.boolean_operator = "AND"
+          self
+        end
+
+        #
+        # Set the boolean operator for the search
+        # to "OR".
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_query_term("Travels", "title", "contains").
+        #       or.add_query_term("Greene", "creator", "contains").search
+        #
+        def or
+          search_request.boolean_operator = "OR"
+          self
+        end
+
+        #
+        # Adds a query term to the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_query_term("Travels", "title", "begins_with").
+        #       add_query_term("Greene", "creator", "contains").search
+        #
+        def add_query_term(*args)
+          search_request.add_query_term(*args)
+          self
+        end
+
+        # 
+        # Dynamically sets chainable accessor for indexes and 
+        # precisions
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.title_begins_with("Travels").
+        #       creator_contains("Greene").search
+        # 
+        def method_missing(method, *args, &block)
+          if matches? method
+            self.class.send(:define_method, method) { |value|
+              index = indexize(method)
+              index = (indexes_map[index] || index)
+              precision = precisionize(method)
+              precision = (precisions_map[precision] || precision)
+              add_query_term value, index, precision
+            }
+            send method, *args, &block
+          else
+            super
+          end
+        end
+
+        # Returns true if the method can be evaluated to a method name
+        # and parameter.
+        def respond_to? method, include_private=false
+          if(matches? method)
+            return true
+          else
+            super
+          end
+        end
+
+        # Supported indexes
+        def indexes
+          @indexes ||= self.class.indexes
+        end
+        private :indexes
+
+        # Alternative indexes mapping
+        def indexes_map
+          @indexes_map ||= self.class.indexes_map
+        end
+        private :indexes_map
+
+        # Supported precisions
+        def precisions
+          @precisions ||= self.class.precisions
+        end
+        private :precisions
+
+        # Alternative precisions mapping
+        def precisions_map
+          @precisions_map ||= self.class.precisions_map
+        end
+        private :precisions_map
+
+        # Get the index from the method.
+        def indexize(method)
+          parse_method(method).first.to_sym
+        end
+        private :indexize
+
+        # Get the precision from the method.
+        def precisionize(method)
+          parse_method(method).last.to_sym
+        end
+        private :precisionize
+
+        # Parse the method on the first occurence of delimiter.
+        def parse_method(method, delimiter="_")
+          method.to_s.split(delimiter, 2)
+        end
+        private :parse_method
+
+        # Does this match our indexes and precisions.
+        def matches? method
+          indexes.include? indexize(method) and precisions.include? precisionize(method)
+        end
+        private :matches?
+
+        #
+        # Set start index for the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.start_index!(11).
+        #       add_query_term("Digital divide", "any", "contains").
+        #         search.records.first => 11th record from the search
+        #
+        def start_index!(start_index)
+          request_attributes[:start_index] = "#{start_index}"
+          self
+        end
+        alias :start_index= :start_index!
+
+        #
+        # Set page size for the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.page_size!(10).
+        #       add_query_term("Digital divide", "any", "contains").
+        #         search.records.size => 10
+        #
+        def page_size!(page_size)
+          request_attributes[:bulk_size] = "#{page_size}"
+          self
+        end
+        alias :page_size= :page_size!
+
+        #
+        # Enable "Did U Mean" functionality for the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.enable_did_u_mean.add_query_term("Digital dvide", "any", "contains").
+        #       search.did_u_mean => "digital video"
+        #
+        def enable_did_u_mean
+          request_attributes[:did_u_mean_enabled] = "true"
+          self
+        end
+
+        #
+        # Disable "Did U Mean" functionality for the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.disable_did_u_mean.add_query_term("Digital dvide", "any", "contains").
+        #       search.did_u_mean => nil
+        #
+        def disable_did_u_mean
+          request_attributes[:did_u_mean_enabled] = "false"
+          self
+        end
+
+        #
+        # Enable highlighting functionality for the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.enable_highlighting.add_query_term("Digital dvide", "any", "contains").
+        #       search.did_u_mean => "digital d vide"
+        #
+        def enable_highlighting
+          request_attributes[:highlighting_enabled] = "true"
+          self
+        end
+
+        #
+        # Disable highlighting functionality for the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.disable_highlighting.add_query_term("Digital dvide", "any", "contains").
+        #       search.did_u_mean => nil
+        #
+        def disable_highlighting
+          request_attributes[:highlighting_enabled] = "false"
+          self
+        end
+
+        #
+        # Adds a language to the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_language("eng").
+        #       add_query_term("Greene", "creator", "contains").search
+        #
+        def add_language(*args)
+          search_request.add_language(*args)
+          self
+        end
+
+        #
+        # Adds a sort by to the search.
+        # Currently the Primo API only supports
+        # one sort by value. Add multiple
+        # sort bys at your own peril.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_sort_by("stitle").
+        #       add_query_term("Greene", "creator", "contains").search
+        #
+        def add_sort_by(*args)
+          search_request.add_sort_by(*args)
+          self
+        end
+
+        #
+        # Adds a display field (for highlighting) to the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_display_field("creator").
+        #       add_query_term("Greene", "creator", "contains").search
+        #
+        def add_display_field(*args)
+          search_request.add_display_field(*args)
+          self
+        end
+
+        #
+        # Adds a location to the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_location("local", "scope:(VOLCANO)").
+        #       add_query_term("Greene", "creator", "contains").search
+        #
+        def add_location(*args)
+          search_request.add_location(*args)
+          self
+        end
+
+        #
+        # Adds a local location to the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_local_location("scope:(VOLCANO)").
+        #       add_query_term("Greene", "creator", "contains").search
+        #
+        def add_local_location(location)
+          add_location("local", location)
+        end
+
+        #
+        # Adds an adaptor location to the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_adaptor_location("primo_central_multiple_fe").
+        #       add_query_term("Greene", "creator", "contains").search
+        #
+        def add_adaptor_location(location)
+          add_location("adaptor", location)
+        end
+
+        #
+        # Adds a remote location to the search.
+        # Suitable for chaining, e.g.
+        #
+        #     Search.new.add_remote_location("quickset_name").
+        #       add_query_term("Greene", "creator", "contains").search
+        #
+        def add_remote_location(location)
+          add_location("remote", location)
+        end
+      end
+    end
+  end
+end