entrez 0.5.5 → 0.5.6

data/README.rdoc

@@ -17,7 +17,21 @@ See 'Email & Tool' section below for setup.
 
 == Usage
 
-(You can copy/paste the resulting following request URLs into a browser to see what the response would be.)
+Supported Utilities
+
+* EFetch
+* EInfo
+* ESearch
+* ESummary
+
+Not yet implemented
+
+* EPost
+* ELink
+* EGQuery
+* ESpell
+
+You can copy/paste the resulting following request URLs into a browser to see what the response would be.
 
 === EFetch, ESummary
 
@@ -39,10 +53,17 @@ args:
 * params hash (optional)
 
   Entrez.ESearch('genomeprj', {WORD: 'hapmap', SEQS: 'inprogress'}, retmode: :xml)
-  #=> makes request to http://http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=genomeprj&term=hapmap[WORD]+AND+inprogress[SEQS]&retmode=xml.
+  #=> makes request to http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=genomeprj&term=hapmap[WORD]+AND+inprogress[SEQS]&retmode=xml.
   #=> returns XML document with list of Ids of genome projects that match the searc term criteria.
   #=> i.e. genome projects that have 'hapmap' in the description and whose sequencing status is 'inprogress'.
 
+==== Customized Queries
+
+You can build your own customized queries if you have something more complex with ANDs and ORs.
+Use Entrez.convert_search_term_hash() to help you.
+It converts a hash into a valid Entrez search string properly joined with the operator of your choosing.
+If you pass in the OR operator, the returned search string will be wrapped in a set of parentheses.
+
 === EInfo
 
 args:
@@ -67,14 +88,6 @@ NCBI recommends no more than 3 URL requests per second: http://www.ncbi.nlm.nih.
 This gem respects this limit. It will delay the next request if the last 3 have been made within 1 second.
 The amount of delay time is no more than what is necessary to make the next request "respectful".
 
-== Supported Utilities
-
-* EFetch
-* ESummary
-* ESearch
-
-Not yet implemented: EPost, ELink, EGQuery, ESpell.
-
 == Compatibility
 
 http://test.rubygems.org/gems/entrez

data/lib/entrez.rb

@@ -41,6 +41,21 @@ class Entrez
       get utility_path, :query => {db: db}.merge(params)
     end
 
+    # Take a ruby hash and convert it to an ENTREZ search term.
+    # E.g. convert_search_term_hash {WORD: 'low coverage', SEQS: 'inprogress'}
+    # #=> 'low coverage[WORD]+AND+inprogress[SEQS]'
+    def convert_search_term_hash(hash, operator = 'AND')
+      raise UnknownOperator.new(operator) unless ['AND', 'OR'].include?(operator)
+      str = hash.map do |field, value|
+        value = value.join(',') if value.is_a?(Array)
+        "#{value}[#{field}]"
+      end.join("+#{operator}+")
+      if operator == 'OR'
+        str = "(#{str})"
+      end
+      str
+    end
+
     private
 
     def respect_query_limit
@@ -59,16 +74,6 @@ class Entrez
       @request_times ||= []
     end
 
-    # Take a ruby hash and convert it to an ENTREZ search term.
-    # E.g. convert_search_term_hash {WORD: 'low coverage', SEQS: 'inprogress'}
-    # #=> 'low coverage[WORD]+AND+inprogress[SEQS]'
-    def convert_search_term_hash(hash)
-      hash.map do |field, value|
-        value = value.join(',') if value.is_a?(Array)
-        "#{value}[#{field}]"
-      end.join('+AND+')
-    end
-
     # Define ids() method which will parse and return the IDs from the XML response.
     def parse_ids_and_extend(response)
       response.instance_eval do
@@ -87,4 +92,10 @@ class Entrez
 
   end
 
+  class UnknownOperator < StandardError
+    def initialize(operator)
+      super "Unknown operator: #{operator}"
+    end
+  end
+
 end

data/lib/entrez/version.rb

@@ -1,3 +1,3 @@
 module Entrez
-  VERSION = "0.5.5"
+  VERSION = "0.5.6"
 end

data/spec/entrez_spec.rb

@@ -62,4 +62,14 @@ describe Entrez do
     requests.should take_longer_than(1.0)
   end
 
+  it 'should convert search term hash into query string with AND operator by default' do
+    query_string = {TITL: 'BRCA1', ORGN: 'human'}
+    Entrez.convert_search_term_hash(query_string).should == 'BRCA1[TITL]+AND+human[ORGN]'
+  end
+
+  it 'should convert search term hash into query string with OR operator with parentheses' do
+    query_string = {TITL: 'BRCA1', ORGN: 'human'}
+    Entrez.convert_search_term_hash(query_string, 'OR').should == '(BRCA1[TITL]+OR+human[ORGN])'
+  end
+
 end

metadata

@@ -2,7 +2,7 @@
 name: entrez
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.5.5
+  version: 0.5.6
 platform: ruby
 authors: 
 - Jared Ning
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-31 00:00:00 -05:00
+date: 2011-07-20 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency