summon 1.0.0

data/.specification

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+name: summon
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: []
+
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-15 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: 
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib
+- lib/summon
+- lib/summon.rb
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- bin
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: 
+test_files: []
+

data/History.txt

@@ -0,0 +1,4 @@
+=== 1.0.0 2009-09-28
+
+* 1 major enhancement:
+  * Initial Release

data/Manifest.txt

@@ -0,0 +1,52 @@
+.specification
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+bin/summon
+bin/summonh
+ispec/integration_spec.rb
+lib/summon.rb
+lib/summon/cli.rb
+lib/summon/log.rb
+lib/summon/schema.rb
+lib/summon/schema/availability.rb
+lib/summon/schema/citation.rb
+lib/summon/schema/date.rb
+lib/summon/schema/document.rb
+lib/summon/schema/error.rb
+lib/summon/schema/facet.rb
+lib/summon/schema/query.rb
+lib/summon/schema/range.rb
+lib/summon/schema/search.rb
+lib/summon/schema/suggestion.rb
+lib/summon/service.rb
+lib/summon/transport.rb
+lib/summon/transport/canned.json
+lib/summon/transport/canned.rb
+lib/summon/transport/errors.rb
+lib/summon/transport/headers.rb
+lib/summon/transport/http.rb
+lib/summon/transport/qstring.rb
+script/console
+script/destroy
+script/generate
+spec/spec.opts
+spec/spec_helper.rb
+spec/summon/log_spec.rb
+spec/summon/schema/availability_spec.rb
+spec/summon/schema/citation_spec.rb
+spec/summon/schema/date_spec.rb
+spec/summon/schema/document_spec.rb
+spec/summon/schema/facet_spec.rb
+spec/summon/schema/query_spec.rb
+spec/summon/schema/range_spec.rb
+spec/summon/schema/search_spec.rb
+spec/summon/schema_spec.rb
+spec/summon/service_spec.rb
+spec/summon/transport/headers_spec.rb
+spec/summon/transport/http_spec.rb
+spec/summon/transport/qstring_spec.rb
+spec/summon_spec.rb
+summon.gemspec

data/PostInstall.txt

@@ -0,0 +1,4 @@
+
+For comprehensive documentation on Summon API options and usage visit:
+
+http://api.summon.serialssolutions.com

data/README.rdoc

@@ -0,0 +1,77 @@
+= summon
+
+* http://summon.rubyforge.org
+* http://www.serialssolutions.com/summon
+* http://api.summon.serialssolutions.com
+
+== DESCRIPTION:
+
+Ruby language bindings for Serials Solutions Summon Unified Discovery Service
+
+== FEATURES/PROBLEMS:
+
+* perform searches using the Summon public API from within ruby.
+
+== SYNOPSIS:
+
+=== From the Command Line
+
+ #help
+ summon --help
+ 
+ #simple text query
+ summon "Will Shakespeare"
+  
+ #books only please!
+ summon "Will Shakespeare" --s.cmd="addFacetValueFilters(ContentType, Book)"
+ 
+ #lots of results.
+ summon "Will Shakespeare" --s.cmd="addFacetValueFilters(ContentType, Book) setPageSize(100)"
+
+=== Inside Code
+
+  require 'summon'
+  @service = Summon::Service.new(:access_id => 'myaccessid', :secret_key => 'mysecretkey')
+
+  #search using parameters
+  search = @service.search("s.q" => "Elephants", "s.fvf" => "ContentType,Book")
+  puts search.record_count #=> 137
+  search.documents.each do |doc|
+  	puts doc.title
+  end
+
+  #search using commands
+  search = @service.search("s.cmd" => "addTextQuery(Elephants) addFacetValueFilters(ContentType,Book)")
+
+== REQUIREMENTS:
+
+* ruby >= 1.8.6
+
+== INSTALL:
+
+* sudo gem install summon
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Serials Solutions LLC
+
+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,25 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/summon'
+
+Hoe.plugin :newgem
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'summon' do
+  self.developer 'Charles Lowell', 'cowboyd@thefrontside.net'
+  self.post_install_message = File.read('PostInstall.txt')
+  self.rubyforge_name       = self.name
+  self.extra_deps           = [
+                                ['json_pure','>= 1.1.7']
+                              ]
+  self.extra_dev_deps       = [
+                                ['rspec', '>= 1.2.7']
+                            ]                          
+  self.version              = Summon::VERSION
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }

data/bin/summon

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+#
+#  Created on 2009-7-14.
+#  Copyright (c) 2009. All rights reserved.
+
+require 'rubygems'
+require File.expand_path(File.dirname(__FILE__) + "/../lib/summon")
+require "summon/cli"
+
+Summon::CLI.execute(STDOUT, ARGV)

data/bin/summonh

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require File.expand_path(File.dirname(__FILE__) + "/../lib/summon")
+require "summon/cli"
+
+raise "usage summonh <http query string>" unless ARGV.size == 1
+
+params = ARGV[0].split("&").inject({}) do |hash, term|
+  k,v = term.split("=")
+  hash[CGI.unescape(k)] = CGI.unescape(v)
+  hash
+end
+
+@config = Summon::CLI::Config.load
+@summon = Summon::Service.new(@config.options)
+@summon.send(:connect, "/search", params) do |result|
+  puts JSON.pretty_generate(result)
+end

data/ispec/integration_spec.rb

@@ -0,0 +1,61 @@
+require File.dirname(__FILE__) + '/../spec/spec_helper'
+require 'cgi'
+require 'summon/cli'
+
+describe "summon" do
+  attr_reader :summon
+  
+  before :all do 
+    @config = Summon::CLI::Config.load
+    @summon = Summon::Service.new(@config.options)
+  end
+
+  describe "search" do
+    it "should do an empty query" do
+      search = summon.search
+    
+      search.record_count.should > 0
+      search.should_not be_empty
+    end
+
+    it "should do a text query" do
+      search = summon.search "s.q" => "Probability models of recidivism\\\\\\: an exploration"
+      search.should_not be_empty
+      query(search).should == "s.q=Probability models of recidivism\\\\\\: an exploration"
+    end
+  
+    it "should do one command" do
+      search = summon.search "s.cmd" => "addTextFilter(Author\\:\\(Linster\\, Richard L\\))"    
+      query(search).should == "s.fq=Author:(Linster, Richard L)"
+      search.should_not be_empty
+    end
+  
+    it "should do an interesting search by pieces" do
+      text_query = "Probability models of recidivism\\: an exploration"
+      command = "addTextFilter(Author_t\\:\\(Linster\\, Richard L\\))"
+    
+      search = summon.search "s.q" => text_query, "s.cmd" => command
+    
+      query(search).should == "s.fq=Author:(Linster, Richard L)&" +
+                              "s.q=Probability models of recidivism\\: an exploration"
+    end
+    
+    it "should modify a search" do
+      search = summon.search "s.q" => "Probability models of recidivism\\: an exploration"
+      search = summon.modify_search search, "addTextFilter(Author\\:\\(Linster\\, Richard L\\))"
+      
+      query(search).should == "s.fq=Author:(Linster, Richard L)&" +
+                              "s.q=Probability models of recidivism\\: an exploration"
+    end
+  end
+    
+  def find(list, search_by, value)
+    item = list.find{|i| i.send(search_by) == value}
+    item.should_not be_nil
+    item
+  end
+  
+  def query(search)
+    CGI::unescape(search.query.query_string)
+  end
+end

data/lib/summon.rb

@@ -0,0 +1,41 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'rubygems'
+require 'cgi'
+require 'json'
+
+module Summon
+  VERSION = "1.0.0"
+  require 'summon/log'
+  require 'summon/service'
+  require 'summon/transport'
+  require 'summon/schema'
+  require 'summon/schema/query'
+  require 'summon/schema/search'
+  require 'summon/schema/facet'
+  require 'summon/schema/range'
+  require 'summon/schema/document'
+  require 'summon/schema/date'
+  require 'summon/schema/suggestion'
+  require 'summon/schema/availability'
+  require 'summon/schema/citation'
+  require 'summon/schema/error'
+  
+  def self.escape(value)
+    value.gsub(/(,|\(|\)|\{|\}|\$|\:)/, '\\\\\1').gsub("\\", '\\')
+  end
+
+  def self.unescape(value)
+    value.gsub(/\\(.)/, '\1')
+  end
+end
+
+unless Object.method_defined?(:tap)
+  class Object
+    def tap(&block)
+      yield self
+      return self
+    end
+  end
+end

data/lib/summon/cli.rb

@@ -0,0 +1,136 @@
+require 'optparse'
+require 'json'
+require 'fileutils'
+
+module Summon
+  class CLI
+    def self.execute(stdout, arguments=[])
+      config = Config.load
+      options = {
+        :log => {:level => :warn}
+      }
+      params = {
+        "s.pn" => 1,
+        "s.ps" => 10,
+        "s.q" => [],
+        "s.fq" => [],
+        "s.st" => [],
+        "s.cmd" => [],
+        "s.ff" => [],
+        "s.fvf" => [],
+        "s.fvgf" => [],
+        "s.rff" => [],
+        "s.hs" => "*",
+        "s.he" => "*"
+      }
+      raw = nil
+
+      mandatory_options = %w(  )
+
+      parser = OptionParser.new do |opts|
+        opts.banner = <<-BANNER.gsub(/^          /,'')
+          Summon Unified Discovery Service
+
+          Usage: #{File.basename($0)} [options] [text query]*
+          See: http://api.summon.serialssolutions.com/help for details
+
+        BANNER
+        opts.separator  "API query parameters"
+        opts.on("--s.cmd=COMMAND", String, "Command: pass a command to the API") {|cmd| params["s.cmd"] << cmd}       
+        opts.on("--s.q=QUERY", String, "Query Term: add an all-field text query to the search") {|q| params["s.q"] << q}
+        opts.on("--s.fq=QUERY", String, "Filter Query: add a filter query which does not affect document relevance") {|fq| params["s.fq"] << fq}
+        opts.on("--s.st=FIELD,VALUE", String, "Search Term: add a query term to a field") {|t| params["s.st"] << t}
+        opts.on("--s.ff=FIELD,MODE,PAGE", String, "Facet Field: request facet counts for the given Field") {|f| params['s.ff'] << f}
+        opts.on("--s.fvf=FIELD,VALUE,NEGATED", "Facet Value Filter: applies an exact-value filter for a facet value within a facetable field: e.g. ContentType,Book") {|fvf| params["s.fvf"] << fvf}
+        opts.on("--s.fvgf=FIELD,MODE,VALUES", "Facet Value Group Filter: advanced functionality. see official api docs. e.g. 'SubjectTerms,or,northern+america,u.s.,canada'")
+        opts.on("--s.rff=<facetField>, <minValue>:<maxValue>[:<inclusive>][, <minValue>:<maxValue>[:<inclusive>]]*", "Range Facet Field: e.g. PublicationDate,1971:1980,1981:1990,1991:2000,2001:2010") {|rff| params["s.rff"] << rff}
+        opts.on("--s.rf=<fieldName>, <minValue>:<maxValue>[:<inclusive>]", "Range Filter: filter the result list to values lying within the range. e.g. PublicationDate,1971:1980")
+        opts.on("--s.hl=BOOLEAN", "Highlight: turn highlighting on or off: e.g. --s.hl=false") {|hl| params["s.hl"] = hl}
+        opts.on("--s.hs=DELIMITER", String, "Highlight Start: demarcate the beginning of a term hit. default is *") {|d| params["s.hs"] = d}
+        opts.on("--s.he=DELIMITER", String, "Highlight End: demarcate the beginning of a term hit. default is *") {|d| params["s.he"] = d}
+        opts.on("--s.ps=INT", Integer, "Page Size: number of documents to return per page") {|n| params["s.ps"] = n}
+        opts.on("--s.pn=INT", Integer, "Page Number: start the results at this page, starting with 1") {|n| params["s.pn"] = n}
+        opts.on("--s.ho=BOOLEAN", "Holdings Only: restrict this search to my institution's holdings only ") {|n| params["s.ho"] = n}
+        opts.on("--s.sort=FIELD:DIRECTION", "Sort: specifiy sort order (e.g. PublicationDate:DESC)") {|s| params["s.sort"] = s}
+        opts.on("--s.dym=BOOLEAN", "Did You Mean?: enables or disables search suggestions.") {|dym| params["s.dym"] = dym}
+
+        opts.separator ""
+        opts.separator "Configuration Options"
+        opts.on("-u", "--url=KEY", String, "Summon API Base URL", "Default: http://api.summon.serialssolutions.com",
+                "Default: ~/.summonrc[url]") {|key| options[:url] = key}
+        opts.on("-i", "--access-id=ID", String,
+                "Summon API Access ID",
+                "Default: ~/.summonrc[access_id]") { |id| options[:access_id] = id }
+        opts.on("-k", "--secret-key=KEY", String, "Summon API Secret Key", "Default: ~/.summonrc[secret_key]") {|key| options[:secret_key] = key}
+        opts.on("-c --sersol-client-id=CLIENT_HASH", String, "Specific Serials Solutions Client ID to use when making this query", 
+          "Only useful when your access id is authorized to query multiple accounts") {|id| options[:client_key] = config.client_key(id)}
+          
+        opts.on("-g", "--get=URL", "Takes a raw summon url, and queries the api without first performing any encoding.") {|url| raw = url}
+        opts.on("--verbose", "output more request information") {options[:log].merge! :level => :info }
+        opts.on("--debug", "output very detailed information") {options[:log].merge! :level => :debug }
+        opts.on("-h", "--help",
+                "Show this help message.") { stdout.puts opts; exit }
+                      
+        begin
+          opts.parse!(arguments)
+        rescue OptionParser::ParseError => e
+          puts e.message; exit
+        end        
+        
+        params["s.q"] << ARGV.join(' ') unless ARGV.empty?
+
+        if mandatory_options && mandatory_options.find { |option| options[option.to_sym].nil? }
+          stdout.puts opts; exit
+        end
+      end
+      begin
+        service = Summon::Service.new(config.options.merge options)
+        puts JSON.pretty_generate(raw ? service.transport.urlget(raw) : service.transport.get("/search", params))
+      rescue Summon::Transport::TransportError => e
+        puts e.message
+      end
+
+    end
+    
+    
+    class Config
+      attr_reader :url, :access_id, :secret_key
+      
+      def initialize
+        @clients = {}
+      end
+      
+      def self.load
+        summonrc = "#{ENV['HOME']}/.summonrc"
+        FileUtils.touch summonrc unless File.exists?(summonrc)        
+        new.tap do |this|
+          this.instance_eval(File.read(summonrc), summonrc, 1)
+        end
+      end
+          
+      def url(url)
+        @url = url
+      end
+      
+      def access_id(access_id)
+        @access_id = access_id
+      end
+      
+      def secret_key(secret_key)
+        @secret_key = secret_key
+      end
+      
+      def clients(h)
+        @clients = h
+      end
+      
+      def client_key(name)              
+        @clients[name.to_sym] || name
+      end
+      
+      def options
+        {:url => @url, :access_id => @access_id, :secret_key => @secret_key}
+      end
+    end
+  end
+end