arx 1.0.0 → 1.3.0

data/Rakefile

@@ -13,7 +13,7 @@ namespace :gem do
 
   desc 'Debug the gem (load into IRB)'
   task :debug do
-    exec 'bundle exec rake install && irb -I lib/arx.rb -r arx'
+    exec 'bin/console'
   end
 
   desc 'Prepare a new gem release'

data/arx.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
   spec.name          = 'arx'
   spec.version       = Arx::VERSION
   spec.authors       = ['Edwin Onuonga']
-  spec.email         = ['ed@mail.eonu.net']
+  spec.email         = ['ed@eonu.net']
   spec.homepage      = 'https://github.com/eonu/arx'
 
   spec.summary       = %q{A Ruby interface for querying academic papers on the arXiv search API.}
@@ -16,15 +16,17 @@ Gem::Specification.new do |spec|
     Gemfile LICENSE CHANGELOG.md README.md Rakefile arx.gemspec
   ]
 
-  spec.required_ruby_version = '~> 2.5'
+  spec.required_ruby_version = '>= 2.5'
 
   spec.add_runtime_dependency 'nokogiri', '~> 1.10'
   spec.add_runtime_dependency 'nokogiri-happymapper', '~> 0.8'
 
-  spec.add_development_dependency 'bundler', '~> 2.0'
-  spec.add_development_dependency 'rake', '~> 12.3'
-  spec.add_development_dependency 'thor', '~> 0.20'
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'thor', '~> 0.20.3'
   spec.add_development_dependency 'rspec', '~> 3.7'
+  spec.add_development_dependency 'coveralls', '0.8.23'
+  spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.10'
 
   spec.metadata = {
     'source_code_uri' => spec.homepage,

data/lib/arx.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
 require 'cgi'
+require 'json'
+
+# Temporary fix for JSON warning in Ruby >= 2.7.0
+# See: https://github.com/flori/json/issues/399#issuecomment-734863279
+if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.7.0')
+  module JSON
+    module_function
+    def parse(source, opts = {})
+      Parser.new(source, **opts).parse
+    end
+  end
+end
+
 require 'nokogiri'
 require 'open-uri'
 require 'happymapper'
@@ -46,31 +59,38 @@ module Arx
 
     # 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+.
+    # @note The +sort_by+, +sort_order+, +start+ and +max_results+ 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}).
+    # @param start [Integer] The index of the first returned result.
+    # @param max_results [Integer] The number of results returned by the query
     # @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)
+    def search(*ids, query: nil, sort_by: :relevance, sort_order: :descending, start: 0, max_results: 10)
+      query ||= Query.new(*ids, sort_by: sort_by, sort_order: sort_order, start: start, max_results: max_results)
       raise TypeError.new("Expected `query` to be an Arx::Query, got: #{query.class}") unless query.is_a? Query
 
       yield query if block_given?
 
-      document = Nokogiri::XML(open ENDPOINT + query.to_s + '&max_results=10000').remove_namespaces!
+      document = Nokogiri::XML(URI.open ENDPOINT + query.to_s).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 :find, :search
     alias_method :get, :search
   end
 end
@@ -84,7 +104,9 @@ end
 # @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}).
+# @param start [Integer] The index of the first returned result.
+# @param max_results [Integer] The number of results returned by the query
 # @return [Array<Paper>, Paper] The {Arx::Paper}(s) found by the search query.
-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
+def Arx(*ids, query: nil, sort_by: :relevance, sort_order: :descending, start: 0, max_results: 10, &block)
+  Arx.search *ids, query: query, sort_by: sort_by, sort_order: sort_order, start: start, max_results: max_results, &block
 end

data/lib/arx/categories.rb

@@ -21,6 +21,14 @@ module Arx
     'cond-mat.stat-mech' => 'Statistical Mechanics',
     'cond-mat.str-el' => 'Strongly Correlated Electrons',
     'cond-mat.supr-con' => 'Superconductivity',
+    'dis-nn' => 'Disordered Systems and Neural Networks', # cond-mat
+    'mes-hall' => 'Mesoscale and Nanoscale Physics', # cond-mat
+    'mtrl-sci' => 'Materials Science', # cond-mat
+    'quant-gas' => 'Quantum Gases', # cond-mat
+    'soft' => 'Soft Condensed Matter', # cond-mat
+    'stat-mech' => 'Statistical Mechanics', # cond-mat
+    'str-el' => 'Strongly Correlated Electrons', # cond-mat
+    'supr-con' => 'Superconductivity', # cond-mat
     'cs' => 'Computer Science',
     'cs.AI' => 'Artificial Intelligence',
     'cs.AR' => 'Hardware Architecture',
@@ -138,6 +146,28 @@ module Arx
     'physics.pop-ph' => 'Popular Physics',
     'physics.soc-ph' => 'Physics and Society',
     'physics.space-ph' => 'Space Physics',
+    'acc-ph' => 'Accelerator Physics', # physics
+    'ao-ph' => 'Atmospheric and Oceanic Physics', # physics
+    'app-ph' => 'Applied Physics', # physics
+    'atm-clus' => 'Atomic and Molecular Clusters', # physics
+    'atom-ph' => 'Atomic Physics', # physics
+    'bio-ph' => 'Biological Physics', # physics
+    'chem-ph' => 'Chemical Physics', # physics
+    'class-ph' => 'Classical Physics', # physics
+    'comp-ph' => 'Computational Physics', # physics
+    'data-an' => 'Data Analysis, Statistics and Probability', # physics
+    'ed-ph' => 'Physics Education', # physics
+    'flu-dyn' => 'Fluid Dynamics', # physics
+    'gen-ph' => 'General Physics', # physics
+    'geo-ph' => 'Geophysics', # physics
+    'hist-ph' => 'History and Philosophy of Physics', # physics
+    'ins-det' => 'Instrumentation and Detectors', # physics
+    'med-ph' => 'Medical Physics', # physics
+    'optics' => 'Optics', # physics
+    'plasm-ph' => 'Plasma Physics', # physics
+    'pop-ph' => 'Popular Physics', # physics
+    'soc-ph' => 'Physics and Society', # physics
+    'space-ph' => 'Space Physics', # physics
     'q-bio' => 'Quantitative Biology',
     'q-bio.BM' => 'Biomolecules',
     'q-bio.CB' => 'Cell Behavior',

data/lib/arx/cleaner.rb

@@ -1,6 +1,7 @@
 module Arx
 
   # Class for cleaning strings.
+  #
   # @private
   class Cleaner
 
@@ -10,6 +11,7 @@ module Arx
     class << self
 
       # Cleans strings.
+      #
       # @param [String] string Removes newline/return characters and multiple spaces from a string.
       # @return [String] The cleaned string.
       def clean(string)

data/lib/arx/entities/author.rb

@@ -5,24 +5,71 @@ module Arx
     include HappyMapper
     include Inspector
 
+    # The attributes of an arXiv paper's author.
+    ATTRIBUTES = %i[name affiliated? affiliations]
+
     tag 'author'
 
     # @!method name
     # The name of the author.
+    #
     # @return [String]
     element :name, Cleaner, tag: 'name', parser: :clean
 
     # @!method affiliations
     # The author's affiliations.
+    #
     # @return [Array<String>]
     has_many :affiliations, Cleaner, tag: 'affiliation', parser: :clean
 
     # Whether or not the author has any affiliations.
+    #
     # @return [Boolean]
     def affiliated?
       !affiliations.empty?
     end
 
-    inspector :name, :affiliated?, :affiliations
+    # Serializes the {Author} object into a +Hash+.
+    #
+    # @return [Hash]
+    def to_h
+      Hash[*ATTRIBUTES.map {|_| [_, send(_)]}.flatten(1)]
+    end
+
+    # Serializes the {Author} object into a valid JSON hash.
+    #
+    # @return [Hash] The resulting JSON hash.
+    def as_json
+      JSON.parse to_json
+    end
+
+    # Serializes the {Author} object into a valid JSON string.
+    #
+    # @return [String] The resulting JSON string.
+    def to_json
+      to_h.to_json
+    end
+
+    # Equality check against another author.
+    #
+    # @note This only performs a basic equality check between the authors' names.
+    # @param author [Author] The author to compare against.
+    # @return [Boolean]
+    def ==(author)
+      if author.is_a? Author
+        name == author.name
+      else
+        false
+      end
+    end
+
+    # A string representation of the {Author} object.
+    #
+    # @return [String]
+    def to_s
+      "Arx::Author(name: #{name}, affiliations: [#{affiliations.join(', ')}])"
+    end
+
+    inspector *ATTRIBUTES
   end
 end

data/lib/arx/entities/category.rb

@@ -5,20 +5,65 @@ module Arx
     include HappyMapper
     include Inspector
 
+    # The attributes of an arXiv paper's category.
+    ATTRIBUTES = %i[name full_name]
+
     tag 'category'
 
     # @!method name
     # The abbreviated name of the category.
+    #
     # @return [String]
     attribute :name, Cleaner, parser: :clean, tag: 'term'
 
     # The full name of the category.
+    #
     # @see CATEGORIES
     # @return [String]
     def full_name
       CATEGORIES[name]
     end
 
-    inspector :name, :full_name
+    # Serializes the {Category} object into a +Hash+.
+    #
+    # @return [Hash]
+    def to_h
+      Hash[*ATTRIBUTES.map {|_| [_, send(_)]}.flatten(1)]
+    end
+
+    # Serializes the {Category} object into a valid JSON hash.
+    #
+    # @return [Hash] The resulting JSON hash.
+    def as_json
+      JSON.parse to_json
+    end
+
+    # Serializes the {Category} object into a valid JSON string.
+    #
+    # @return [String] The resulting JSON string.
+    def to_json
+      to_h.to_json
+    end
+
+    # Equality check against another category.
+    #
+    # @param category [Category] The category to compare against.
+    # @return [Boolean]
+    def ==(category)
+      if category.is_a? Category
+        name == category.name
+      else
+        false
+      end
+    end
+
+    # A string representation of the {Category} object.
+    #
+    # @return [String]
+    def to_s
+      "Arx::Category(name: #{name}, full_name: #{full_name || 'nil'})"
+    end
+
+    inspector *ATTRIBUTES
   end
 end

data/lib/arx/entities/link.rb

@@ -1,6 +1,7 @@
 module Arx
 
   # Helper entity/model representing a link on an arXiv paper.
+  #
   # @private
   class Link
     include HappyMapper

data/lib/arx/entities/paper.rb

@@ -5,37 +5,54 @@ module Arx
     include HappyMapper
     include Inspector
 
+    # The attributes of an arXiv paper.
+    # @note {comment}, {journal}, {pdf_url} and {doi_url} may raise errors when called.
+    ATTRIBUTES = %i[
+      id url version revision?
+      title summary authors
+      primary_category categories
+      published_at updated_at
+      comment? comment
+      journal? journal
+      pdf? pdf_url
+      doi? doi_url
+    ]
+
     tag 'entry'
 
     element :id, Cleaner, parser: :clean, tag: 'id'
     # The identifier of the paper.
+    #
     # @note This is either in {OLD_IDENTIFIER_FORMAT} or {NEW_IDENTIFIER_FORMAT}.
     # @example
     #   1705.01662v1
     #   cond-mat/0211034
     # @param version [Boolean] Whether or not to include the paper's version.
     # @return [String] The paper's identifier.
-    def id(version: false)
+    def id(version = false)
       Cleaner.extract_id @id, version: version
     end
 
     # The URL of the paper on the arXiv website.
+    #
     # @example
     #   http://arxiv.org/abs/1705.01662v1
     #   http://arxiv.org/abs/cond-mat/0211034
     # @param version [Boolean] Whether or not to include the paper's version.
     # @return [String] The paper's arXiv URL.
-    def url(version: false)
-      "http://arxiv.org/abs/#{id version: version}"
+    def url(version = false)
+      "http://arxiv.org/abs/#{id version}"
     end
 
     # The version of the paper.
+    #
     # @return [Integer] The paper's version.
     def version
       Cleaner.extract_version @id
     end
 
     # Whether the paper is a revision or not.
+    #
     # @note A paper is a revision if its {version} is greater than 1.
     # @return [Boolean]
     def revision?
@@ -44,47 +61,56 @@ module Arx
 
     # @!method updated_at
     # The date that the paper was last updated.
+    #
     # @return [DateTime]
     element :updated_at, DateTime, tag: 'updated'
 
     # @!method published_at
     # The original publish/submission date of the paper.
+    #
     # @return [DateTime]
     element :published_at, DateTime, tag: 'published'
 
     # @!method title
     # The title of the paper.
+    #
     # @return [DateTime]
     element :title, Cleaner, parser: :clean, tag: 'title'
 
     # @!method authors
     # The authors of the paper.
+    #
     # @return [Array<Author>]
     has_many :authors, Author, tag: 'author'
 
     # @!method primary_category
     # The primary category of the paper.
+    #
     # @return [Category]
     element :primary_category, Category, tag: 'primary_category'
     alias_method :category, :primary_category
 
     # @!method categories
     # The categories of the paper.
+    #
     # @return [Array<Category>]
     has_many :categories, Category, tag: 'category'
 
     # @!method summary
     # The summary (or abstract) of the paper.
+    #
     # @return [String]
     element :summary, Cleaner, parser: :clean, tag: 'summary'
     alias_method :abstract, :summary
 
     # @!method comment?
     # Whether or not the paper has a comment.
+    #
     # @return [Boolean]
 
     # @!method comment
     # The comment of the paper.
+    #
     # @note This is an optional metadata field on an arXiv paper. To check whether the paper has a comment, use {comment?}
     # @raise {Error::MissingField} If the paper does not have a comment.
     # @return [String]
@@ -92,10 +118,12 @@ module Arx
 
     # @!method journal?
     # Whether or not the paper has a journal reference.
+    #
     # @return [Boolean]
 
     # @!method journal
     # The journal reference of the paper.
+    #
     # @note This is an optional metadata field on an arXiv paper. To check whether the paper has a journal reference, use {journal?}
     # @raise {Error::MissingField} If the paper does not have a journal reference.
     # @return [String]
@@ -121,22 +149,26 @@ module Arx
 
     # @!method pdf?
     # Whether or not the paper has a PDF link.
+    #
     # @return [Boolean]
 
     # @!method pdf_url
     # Link to the PDF version of the paper.
+    #
     # @note This is an optional metadata field on an arXiv paper. To check whether the paper has a PDF link, use {pdf?}
     # @raise {Error::MissingLink} If the paper does not have a PDF link.
     # @return [String]
 
     # @!method doi?
     # Whether or not the paper has a DOI (Digital Object Identifier) link.
+    #
     # @see https://arxiv.org/help/jref#doi
     # @see https://arxiv.org/help/prep#doi
     # @return [Boolean]
 
     # @!method doi_url
     # Link to the DOI (Digital Object Identifier) of the paper.
+    #
     # @see https://arxiv.org/help/jref#doi
     # @see https://arxiv.org/help/prep#doi
     # @note This is an optional metadata field on an arXiv paper. To check whether the paper has a DOI link, use {doi?}
@@ -159,15 +191,74 @@ module Arx
       end
     end
 
-    inspector *%i[
-      id url version revision?
-      title summary authors
-      primary_category categories
-      published_at updated_at
-      comment? comment
-      journal? journal
-      pdf? pdf_url
-      doi? doi_url
-    ]
+    # Serializes the {Paper} object into a +Hash+.
+    #
+    # @param deep [Boolean] Whether to deep-serialize {Author} and {Category} objects.
+    # @return [Hash]
+    def to_h(deep = false)
+      Hash[*ATTRIBUTES.map {|_| [_, send(_)] rescue nil}.compact.flatten(1)].tap do |hash|
+        if deep
+          hash[:authors].map! &:to_h
+          hash[:categories].map! &:to_h
+          hash[:primary_category] = hash[:primary_category].to_h
+        end
+      end
+    end
+
+    # Serializes the {Paper} object into a valid JSON hash.
+    #
+    # @note Deep-serializes {Author} and {Category} objects.
+    # @return [Hash] The resulting JSON hash.
+    def as_json
+      JSON.parse to_json
+    end
+
+    # Serializes the {Paper} object into a valid JSON string.
+    #
+    # @note Deep-serializes {Author} and {Category} objects.
+    # @return [String] The resulting JSON string.
+    def to_json
+      to_h(true).to_json
+    end
+
+    # Equality check against another paper.
+    #
+    # @note This only performs a basic equality check between the papers' identifiers (disregarding version).
+    #   This means that a different version of the same paper will be viewed as equal.
+    # @param paper [Paper] The paper to compare against.
+    # @return [Boolean]
+    def ==(paper)
+      if paper.is_a? Paper
+        id == paper.id
+      else
+        false
+      end
+    end
+
+    # Downloads the paper and saves it in PDF format at the specified path.
+    #
+    # @param path [String] The file path to store the PDF at.
+    def save(path)
+      begin
+        pdf_content = URI.open(pdf_url).read
+        File.open(path, 'wb') {|f| f.write pdf_content}
+      rescue
+        File.delete(path) if File.file? path
+        raise
+      end
+    end
+
+    # A string representation of the {Paper} object.
+    #
+    # @return [String]
+    def to_s
+      _id = id true
+      _published_at = published_at.strftime("%Y-%m-%d")
+      _authors = authors.map(&:name)
+      _authors = [*_authors.first(2), '...'] if _authors.size > 2
+      "Arx::Paper(id: #{_id}, published_at: #{_published_at}, authors: [#{_authors.join(', ')}], title: #{title})"
+    end
+
+    inspector *ATTRIBUTES
   end
 end