arx 0.1.0 → 1.1.0

data/lib/arx.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
+require 'cgi'
 require 'nokogiri'
 require 'open-uri'
+require 'happymapper'
 require 'arx/version'
+require 'arx/cleaner'
+require 'arx/inspector'
 require 'arx/categories'
-require 'arx/query/query'
+require 'arx/error'
 require 'arx/query/validate'
+require 'arx/query/query'
 require 'arx/entities/author'
 require 'arx/entities/category'
+require 'arx/entities/link'
 require 'arx/entities/paper'
 
 # A Ruby interface for querying academic papers on the arXiv search API.
@@ -16,38 +22,74 @@ module Arx
   # The arXiv search API endpoint.
   ENDPOINT = 'http://export.arxiv.org/api/query?'
 
-  # Performs a search query for papers on the arXiv search API.
+  # The current arxiv paper identifier scheme (1 April 2007 and onwards).
+  #   The last block of digits can either be five digits (if the paper was published after 1501 - January 2015),
+  #   or four digits (if the paper was published before 1501).
   #
-  # @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 {Query::SORT_BY}).
-  # @param sort_order [Symbol] The sorting order for the returned results (see {Query::SORT_ORDER}).
-  # @return [Array<Paper>, Paper] The {Paper}(s) found by the search query.
-  def self.search(*ids, sort_by: :relevance, sort_order: :descending)
-    query = Query.new(*ids, sort_by: sort_by, sort_order: sort_order)
+  # @see https://arxiv.org/help/arxiv_identifier#new arXiv identifier (new)
+  # @example
+  #   1501.00001
+  #   1705.01662v1
+  #   1412.0135
+  #   0706.0001v2
+  NEW_IDENTIFIER_FORMAT = /^\d{4}\.\d{4,5}(v\d+)?$/
+
+  # The legacy arXiv paper identifier scheme (before 1 April 2007).
+  #
+  # @see https://arxiv.org/help/arxiv_identifier#old arXiv identifier (old)
+  # @example
+  #   math/0309136v1
+  #   cond-mat/0211034
+  OLD_IDENTIFIER_FORMAT = /^[a-z]+(\-[a-z]+)?\/\d{7}(v\d+)?$/
+
+  class << self
 
-    yield query if block_given?
+    # Performs a search query for papers on the arXiv search API.
+    #
+    # @note The +sort_by+ and +sort_order+ arguments are ignored if passing in your own +query+.
+    # @param ids [Array<String>] The IDs of the arXiv papers to restrict the query to.
+    # @param query [Query, NilClass] Predefined search query object.
+    # @param sort_by [Symbol] The sorting criteria for the returned results (see {Query::SORT_BY}).
+    # @param sort_order [Symbol] The sorting order for the returned results (see {Query::SORT_ORDER}).
+    # @return [Array<Paper>, Paper] The {Paper}(s) found by the search query.
+    def search(*ids, query: nil, sort_by: :relevance, sort_order: :descending)
+      query ||= Query.new(*ids, sort_by: sort_by, sort_order: sort_order)
+      raise TypeError.new("Expected `query` to be an Arx::Query, got: #{query.class}") unless query.is_a? Query
 
-    document = Nokogiri::XML open(ENDPOINT + query.to_s + '&max_results=10000')
-    document.remove_namespaces!
+      yield query if block_given?
 
-    results = Paper.parse(document, single: false).reject {|paper| paper.id.empty?}
-    raise MissingPaper.new(ids.first) if results.empty? && ids.size == 1
-    ids.size == 1 && results.size == 1 ? results.first : results
+      document = Nokogiri::XML(open ENDPOINT + query.to_s + '&max_results=10000').remove_namespaces!
+      results = Paper.parse(document, single: ids.size == 1)
+
+      if results.is_a? Paper
+        raise Error::MissingPaper.new(ids.first) if results.title.empty?
+      elsif results.is_a? Array
+        results.reject! {|paper| paper.title.empty?}
+      elsif results.nil?
+        if ids.size == 1
+          raise Error::MissingPaper.new(ids.first)
+        else
+          results = []
+        end
+      end
+
+      results
+    end
+
+    alias_method :get, :search
   end
 end
 
 # Performs a search query for papers on the arXiv search API.
 #
 # @note This is an alias of the {Arx.search} method.
+# @note The +sort_by+ and +sort_order+ arguments are ignored if passing in your own +query+.
 # @see Arx.search
 # @param ids [Array<String>] The IDs of the arXiv papers to restrict the query to.
+# @param query [Query, NilClass] Predefined search query object.
 # @param sort_by [Symbol] The sorting criteria for the returned results (see {Arx::Query::SORT_BY}).
 # @param sort_order [Symbol] The sorting order for the returned results (see {Arx::Query::SORT_ORDER}).
 # @return [Array<Paper>, Paper] The {Arx::Paper}(s) found by the search query.
-def Arx(*ids, sort_by: :relevance, sort_order: :descending, &block)
-  if block_given?
-    Arx.search *ids, sort_by: sort_by, sort_order: sort_order, &block
-  else
-    Arx.search *ids, sort_by: sort_by, sort_order: sort_order
-  end
+def Arx(*ids, query: nil, sort_by: :relevance, sort_order: :descending, &block)
+  Arx.search *ids, query: query, sort_by: sort_by, sort_order: sort_order, &block
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arx
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Edwin Onuonga
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-24 00:00:00.000000000 Z
+date: 2019-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -42,16 +42,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.17'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.17'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '12.3'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.19.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.19.4
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -80,9 +94,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.22
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.22
 description: 
 email:
-- edwinonuonga@gmail.com
+- ed@eonu.net
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -100,23 +128,29 @@ files:
 - lib/arx/entities/category.rb
 - lib/arx/entities/link.rb
 - lib/arx/entities/paper.rb
-- lib/arx/exceptions.rb
+- lib/arx/error.rb
+- lib/arx/inspector.rb
 - lib/arx/query/query.rb
 - lib/arx/query/validate.rb
 - lib/arx/version.rb
-homepage: 
+homepage: https://github.com/eonu/arx
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/eonu/arx
+  homepage_uri: https://github.com/eonu/arx
+  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: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/arx/exceptions.rb

@@ -1,23 +0,0 @@
-module Arx
-
-  # Custom error for missing links on an arXiv paper.
-  class MissingLinkError < StandardError
-    def initialize(link_type)
-      super "This arXiv paper does not have a #{link_type} link"
-    end
-  end
-
-  # Custom error for missing fields on an arXiv paper.
-  class MissingFieldError < StandardError
-    def initialize(field)
-      super "This arXiv paper is missing the `#{field}` field"
-    end
-  end
-
-  # Custom error for missing arXiv papers.
-  class MissingPaper < StandardError
-    def initialize(id)
-      super "Couldn't find an arXiv paper with ID: #{id}"
-    end
-  end
-end