arx 1.0.0 → 1.3.0

data/lib/arx/inspector.rb

@@ -2,6 +2,7 @@ module Arx
 
   # Restricts +inspect+ to dump a whitelist of methods on an object.
   # It will always provide `object_id` at a minimum.
+  #
   # @private
   module Inspector
 
@@ -24,6 +25,7 @@ module Arx
       end
 
       # Defines helper +inspector_fields+ instance variable & method, and +inspector+ instance method on the target object.
+      #
       # @param [Object] source An arbitrary object (the object that +includes+ the +Inspector+ module).
       def included(source)
         inspected << source

data/lib/arx/query/query.rb

@@ -12,7 +12,9 @@ module Arx
       search_query: 'search_query',
       id_list: 'id_list',
       sort_by: 'sortBy',
-      sort_order: 'sortOrder'
+      sort_order: 'sortOrder',
+      start: 'start',
+      max_results: 'max_results',
     }
 
     # Logical connectives supported by the arXiv search API.
@@ -23,24 +25,27 @@ module Arx
     }
 
     # Supported fields for the search queries made to the arXiv search API.
+    #
     # @see https://arxiv.org/help/prep arXiv metadata fields
     # @see https://arxiv.org/help/api/user-manual#query_details arXiv user manual (query details)
     FIELDS = {
-      title: 'ti',     # Title
-      author: 'au',    # Author
-      abstract: 'abs', # Abstract
-      comment: 'co',   # Comment
-      journal: 'jr',   # Journal reference
-      category: 'cat', # Subject category
-      report: 'rn',    # Report number
-      all: 'all'       # All (of the above)
+      title: 'ti',                   # Title
+      author: 'au',                  # Author
+      abstract: 'abs',               # Abstract
+      comment: 'co',                 # Comment
+      journal: 'jr',                 # Journal reference
+      category: 'cat',               # Subject category
+      report: 'rn',                  # Report number
+      updated_at: 'lastUpdatedDate', # Last updated date
+      submitted_at: 'submittedDate', # Submission date
+      all: 'all'                     # All (of the above)
     }
 
     # Supported criteria for the +sortBy+ parameter.
     SORT_BY = {
       relevance: 'relevance',
-      last_updated: 'lastUpdated',
-      date_submitted: 'submittedDate'
+      updated_at: 'lastUpdatedDate',
+      submitted_at: 'submittedDate'
     }
 
     # Supported criteria for the +sortOrder+ parameter.
@@ -54,8 +59,10 @@ module Arx
     # @param ids [Array<String>] The IDs of the arXiv papers to restrict the query to.
     # @param sort_by [Symbol] The sorting criteria for the returned results (see {SORT_BY}).
     # @param sort_order [Symbol] The sorting order for the returned results (see {SORT_ORDER}).
+    # @param start [Integer] The index of the first returned result.
+    # @param max_results [Integer] The number of results returned by the query
     # @return [Query] The initialized query object.
-    def initialize(*ids, sort_by: :relevance, sort_order: :descending)
+    def initialize(*ids, sort_by: :relevance, sort_order: :descending, start: 0, max_results: 10)
       @query = String.new
 
       Validate.sort_by sort_by, permitted: SORT_BY.keys
@@ -64,9 +71,12 @@ module Arx
       Validate.sort_order sort_order, permitted: SORT_ORDER.keys
       @query << "&#{PARAMS[:sort_order]}=#{SORT_ORDER[sort_order]}"
 
+      Validate.paging start, max_results
+      @query << "&#{PARAMS[:start]}=#{start}&#{PARAMS[:max_results]}=#{max_results}"
+
       ids.flatten!
       unless ids.empty?
-        ids.map! &Cleaner.method(:extract_id)
+        ids.map! {|id| Cleaner.extract_id(id, version: true)}
         @query << "&#{PARAMS[:id_list]}=#{ids * ','}"
       end
 
@@ -75,16 +85,19 @@ module Arx
 
     # @!method and
     # Logical conjunction (+AND+) of subqueries.
+    #
     # @see https://arxiv.org/help/api/user-manual#query_details arXiv user manual
     # @return [self]
 
     # @!method and_not
     # Logical negated conjunction (+ANDNOT+) of subqueries.
+    #
     # @see https://arxiv.org/help/api/user-manual#query_details arXiv user manual
     # @return [self]
 
     # @!method or
     # Logical disjunction (+OR+) of subqueries.
+    #
     # @see https://arxiv.org/help/api/user-manual#query_details arXiv user manual
     # @return [self]
 
@@ -94,6 +107,7 @@ module Arx
 
     # @!method title(*values, exact: true, connective: :and)
     # Search for papers by {https://arxiv.org/help/prep#title title}.
+    #
     # @param values [Array<String>] Title(s) of papers to search for.
     # @param exact [Boolean] Whether to search for an exact match of the title(s).
     # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
@@ -101,6 +115,7 @@ module Arx
 
     # @!method author(*values, exact: true, connective: :and)
     # Search for papers by {https://arxiv.org/help/prep#author author}.
+    #
     # @param values [Array<String>] Author(s) of papers to search for.
     # @param exact [Boolean] Whether to search for an exact match of the author's name(s).
     # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
@@ -108,6 +123,7 @@ module Arx
 
     # @!method abstract(*values, exact: true, connective: :and)
     # Search for papers by {https://arxiv.org/help/prep#abstract abstract}.
+    #
     # @param values [Array<String>] Abstract(s) of papers to search for.
     # @param exact [Boolean] Whether to search for an exact match of the abstract(s).
     # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
@@ -115,6 +131,7 @@ module Arx
 
     # @!method comment(*values, exact: true, connective: :and)
     # Search for papers by {https://arxiv.org/help/prep#comments comment}.
+    #
     # @param values [Array<String>] Comment(s) of papers to search for.
     # @param exact [Boolean] Whether to search for an exact match of the comment(s).
     # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
@@ -122,6 +139,7 @@ module Arx
 
     # @!method journal(*values, exact: true, connective: :and)
     # Search for papers by {https://arxiv.org/help/prep#journal journal reference}.
+    #
     # @param values [Array<String>] Journal reference(s) of papers to search for.
     # @param exact [Boolean] Whether to search for an exact match of the journal refernece(s).
     # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
@@ -129,25 +147,43 @@ module Arx
 
     # @!method category(*values, connective: :and)
     # Search for papers by {https://arxiv.org/help/prep#category category}.
+    #
     # @param values [Array<String>] Category(s) of papers to search for.
     # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
     # @return [self]
 
     # @!method report(*values, connective: :and)
     # Search for papers by {https://arxiv.org/help/prep#report report number}.
+    #
     # @param values [Array<String>] Report number(s) of papers to search for.
     # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
     # @return [self]
 
+    # @!method updated_at(*values, connective: :and)
+    # Search for papers by lastUpdatedDate.
+    #
+    # @param values [Array<String>] lastUpdatedDate (string or range) of papers to search for.
+    # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
+    # @return [self]
+
+    # @!method submitted_at(*values, connective: :and)
+    # Search for papers by submittedDate.
+    #
+    # @param values [Array<String>] submittedDate (string or range) of papers to search for.
+    # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
+    # @return [self]
+
     # @!method all(*values, exact: true, connective: :and)
     # Search for papers by all fields (see {FIELDS}).
+    #
     # @param values [Array<String>] Field value(s) of papers to search for.
     # @param exact [Boolean] Whether to search for an exact match of the comment(s).
     # @param connective [Symbol] The logical connective to use (see {CONNECTIVES}). Only applies if there are multiple values.
     # @return [self]
 
     FIELDS.each do |name, field|
-      define_method(name) do |*values, exact: true, connective: :and|
+      _exact = ![:updated_at, :submitted_at].include?(name)
+      define_method(name) do |*values, exact: _exact, connective: :and|
         return if values.empty?
 
         values.flatten!
@@ -173,6 +209,20 @@ module Arx
       end
     end
 
+    # Creates a nested subquery (grouped statements with parentheses).
+    #
+    # @return [self]
+    def group
+      add_connective :and unless end_with_connective?
+      @query << (search_query? ? '+' : "&#{PARAMS[:search_query]}=")
+
+      @query << CGI.escape('(')
+      yield
+      @query << CGI.escape(')')
+
+      self
+    end
+
     # Returns the query string.
     #
     # @return [String]
@@ -189,7 +239,7 @@ module Arx
     # @return [self]
     def add_connective(connective)
       if search_query?
-        @query << "+#{CONNECTIVES[connective]}" unless ends_with_connective?
+        @query << "+#{CONNECTIVES[connective]}" unless end_with_connective? || start_of_group?
       end
       self
     end
@@ -198,9 +248,10 @@ module Arx
     #
     # @param subquery [String] The subquery to add.
     def add_subquery(subquery)
+      add_connective :and unless end_with_connective?
+
       if search_query?
-        add_connective :and unless ends_with_connective?
-        @query << "+#{subquery}"
+        @query << (start_of_group? ? "#{subquery}" : "+#{subquery}")
       else
         @query << "&#{PARAMS[:search_query]}=#{subquery}"
       end
@@ -218,10 +269,17 @@ module Arx
     #
     # @see CONNECTIVES
     # @return [Boolean]
-    def ends_with_connective?
+    def end_with_connective?
       CONNECTIVES.values.any? &@query.method(:end_with?)
     end
 
+    # Whether the query string ends in a start-of-group character '('.
+    #
+    # @return [Boolean]
+    def start_of_group?
+      @query.end_with? CGI.escape('(')
+    end
+
     # Parenthesizes a string with CGI-escaped parentheses.
     #
     # @param string [String] The string to parenthesize.

data/lib/arx/query/validate.rb

@@ -1,6 +1,7 @@
 module Arx
 
   # Validations for arXiv search query fields and identifier schemes.
+  #
   # @private
   module Validate
     class << self
@@ -28,6 +29,18 @@ module Arx
         raise ArgumentError.new("Expected `sort_order` to be one of #{permitted}, got: #{value}") unless permitted.include? value
       end
 
+      # Validates the paging fields of the query string: +start+ and +max_results+.
+      #
+      # @param start [Integer] The start value to validate.
+      # @param max_results [Integer] The max_results value to validate.
+      # @raise
+      #   [TypeError] If the value of +start+ is not an +Integer+.
+      #   [TypeError] If the value of +max_results+ is not an +Integer+.
+      def paging(start, max_results)
+        raise TypeError.new("Expected `start` to be an Integer, got: #{start.class}") unless start.is_a? Integer
+        raise TypeError.new("Expected `max_results` to be an Integer, got: #{max_results.class}") unless max_results.is_a? Integer
+      end
+
       # Validates a list of arXiv paper identifiers.
       #
       # @param ids [Array<String>] The identifiers to validate.

data/lib/arx/version.rb

@@ -5,7 +5,7 @@ module Arx
   # The current version of Arx.
   VERSION = {
     major: 1,
-    minor: 0,
+    minor: 3,
     patch: 0,
     meta: nil,
   }.compact.values.join('.').freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arx
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Edwin Onuonga
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-04-08 00:00:00.000000000 Z
+date: 2021-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -42,44 +42,44 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.20'
+        version: 0.20.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.20'
+        version: 0.20.3
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -94,9 +94,43 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.7'
-description: 
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.23
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.23
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.10
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.10
+description:
 email:
-- ed@mail.eonu.net
+- ed@eonu.net
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -128,13 +162,13 @@ metadata:
   documentation_uri: https://www.rubydoc.info/github/eonu/arx/master/toplevel
   bug_tracker_uri: https://github.com/eonu/arx/issues
   changelog_uri: https://github.com/eonu/arx/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -143,8 +177,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.1.2
+signing_key:
 specification_version: 4
 summary: A Ruby interface for querying academic papers on the arXiv search API.
 test_files: []