arx 0.1.0 → 1.1.0

data/lib/arx/categories.rb

@@ -11,6 +11,7 @@ module Arx
     'astro-ph.HE' => 'High Energy Astrophysical Phenomena',
     'astro-ph.IM' => 'Instrumentation and Methods for Astrophysics',
     'astro-ph.SR' => 'Solar and Stellar Astrophysics',
+    'cond-mat' => 'Condensed Matter',
     'cond-mat.dis-nn' => 'Disordered Systems and Neural Networks',
     'cond-mat.mes-hall' => 'Mesoscale and Nanoscale Physics',
     'cond-mat.mtrl-sci' => 'Materials Science',
@@ -20,6 +21,7 @@ module Arx
     'cond-mat.stat-mech' => 'Statistical Mechanics',
     'cond-mat.str-el' => 'Strongly Correlated Electrons',
     'cond-mat.supr-con' => 'Superconductivity',
+    'cs' => 'Computer Science',
     'cs.AI' => 'Artificial Intelligence',
     'cs.AR' => 'Hardware Architecture',
     'cs.CC' => 'Computational Complexity',
@@ -60,7 +62,9 @@ module Arx
     'cs.SE' => 'Software Engineering',
     'cs.SI' => 'Social and Information Networks',
     'cs.SY' => 'Systems and Control',
+    'econ' => 'Economics',
     'econ.EM' => 'Econometrics',
+    'eess' => 'Electrical Engineering and Systems Science',
     'eess.AS' => 'Audio and Speech Processing',
     'eess.IV' => 'Image and Video Processing',
     'eess.SP' => 'Signal Processing',
@@ -69,6 +73,7 @@ module Arx
     'hep-lat' => 'High Energy Physics - Lattice',
     'hep-ph' => 'High Energy Physics - Phenomenology',
     'hep-th' => 'High Energy Physics - Theory',
+    'math' => 'Mathematics',
     'math.AC' => 'Commutative Algebra',
     'math.AG' => 'Algebraic Geometry',
     'math.AP' => 'Analysis of PDEs',
@@ -102,6 +107,7 @@ module Arx
     'math.SP' => 'Spectral Theory',
     'math.ST' => 'Statistics Theory',
     'math-ph' => 'Mathematical Physics',
+    'nlin' => 'Nonlinear Sciences',
     'nlin.AO' => 'Adaptation and Self-Organizing Systems',
     'nlin.CD' => 'Chaotic Dynamics',
     'nlin.CG' => 'Cellular Automata and Lattice Gases',
@@ -109,6 +115,7 @@ module Arx
     'nlin.SI' => 'Exactly Solvable and Integrable Systems',
     'nucl-ex' => 'Nuclear Experiment',
     'nucl-th' => 'Nuclear Theory',
+    'physics' => 'Physics',
     'physics.acc-ph' => 'Accelerator Physics',
     'physics.ao-ph' => 'Atmospheric and Oceanic Physics',
     'physics.app-ph' => 'Applied Physics',
@@ -131,6 +138,7 @@ module Arx
     'physics.pop-ph' => 'Popular Physics',
     'physics.soc-ph' => 'Physics and Society',
     'physics.space-ph' => 'Space Physics',
+    'q-bio' => 'Quantitative Biology',
     'q-bio.BM' => 'Biomolecules',
     'q-bio.CB' => 'Cell Behavior',
     'q-bio.GN' => 'Genomics',
@@ -141,6 +149,7 @@ module Arx
     'q-bio.QM' => 'Quantitative Methods',
     'q-bio.SC' => 'Subcellular Processes',
     'q-bio.TO' => 'Tissues and Organs',
+    'q-fin' => 'Quantitative Finance',
     'q-fin.CP' => 'Computational Finance',
     'q-fin.EC' => 'Economics',
     'q-fin.GN' => 'General Finance',
@@ -151,6 +160,7 @@ module Arx
     'q-fin.ST' => 'Statistical Finance',
     'q-fin.TR' => 'Trading and Market Microstructure',
     'quant-ph' => 'Quantum Physics',
+    'stat' => 'Statistics',
     'stat.AP' => 'Applications',
     'stat.CO' => 'Computation',
     'stat.ME' => 'Methodology',

data/lib/arx/cleaner.rb

@@ -1,13 +1,53 @@
 module Arx
 
   # Class for cleaning strings.
+  # @private
   class Cleaner
 
-    # Cleans strings.
-    # @param [String] string Removes newline/return characters and multiple spaces from a string.
-    # @return [String] The cleaned string.
-    def self.clean(string)
-      string.gsub(/\r\n|\r|\n/, ' ').strip.squeeze ' '
+    # arXiv paper URL prefix format
+    URL_PREFIX = /^(https?\:\/\/)?(www.)?arxiv\.org\/abs\//
+
+    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)
+        string.gsub(/\r\n|\r|\n/, ' ').strip.squeeze ' '
+      end
+
+      # Attempt to extract an arXiv identifier from a string such as a URL.
+      #
+      # @param string [String] The string to extract the ID from.
+      # @param version [Boolean] Whether or not to include the paper's version.
+      # @return [String] The extracted ID.
+      def extract_id(string, version: false)
+        if version == !!version
+          if string.is_a? String
+            trimmed = /#{URL_PREFIX}.+\/?$/.match?(string) ? string.gsub(/(#{URL_PREFIX})|(\/$)/, '') : string
+            raise ArgumentError.new("Couldn't extract arXiv identifier from: #{string}") unless Validate.id? trimmed
+            version ? trimmed : trimmed.sub(/v[0-9]+$/, '')
+          else
+            raise TypeError.new("Expected `string` to be a String, got: #{string.class}")
+          end
+        else
+          raise TypeError.new("Expected `version` to be boolean (TrueClass or FalseClass), got: #{version.class}")
+        end
+      end
+
+      # Attempt to extract a version number from an arXiv identifier.
+      #
+      # @param string [String] The arXiv identifier to extract the version number from.
+      # @return [String] The extracted version number.
+      def extract_version(string)
+        reversed = extract_id(string, version: true).reverse
+
+        if /^[0-9]+v/.match? reversed
+          reversed.partition('v').first.reverse.to_i
+        else
+          raise ArgumentError.new("Couldn't extract version number from identifier: #{string}")
+        end
+      end
     end
   end
 end

data/lib/arx/entities/author.rb

@@ -1,11 +1,9 @@
-require 'happymapper'
-require 'arx/cleaner'
-
 module Arx
 
   # Entity/model representing an arXiv paper's author.
   class Author
     include HappyMapper
+    include Inspector
 
     tag 'author'
 
@@ -19,11 +17,12 @@ module Arx
     # @return [Array<String>]
     has_many :affiliations, Cleaner, tag: 'affiliation', parser: :clean
 
-    # @!method affiliations?
     # Whether or not the author has any affiliations.
     # @return [Boolean]
-    def affiliations?
+    def affiliated?
       !affiliations.empty?
     end
+
+    inspector :name, :affiliated?, :affiliations
   end
 end

data/lib/arx/entities/category.rb

@@ -1,11 +1,9 @@
-require 'arx/categories'
-require 'arx/cleaner'
-
 module Arx
 
   # Entity/model representing an arXiv paper's category.
   class Category
     include HappyMapper
+    include Inspector
 
     tag 'category'
 
@@ -18,7 +16,9 @@ module Arx
     # @see CATEGORIES
     # @return [String]
     def full_name
-      CATEGORIES[term]
+      CATEGORIES[name]
     end
+
+    inspector :name, :full_name
   end
 end

data/lib/arx/entities/link.rb

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

data/lib/arx/entities/paper.rb

@@ -1,47 +1,56 @@
-require 'happymapper'
-require 'arx/exceptions'
-require 'arx/cleaner'
-require_relative 'author'
-require_relative 'category'
-require_relative 'link'
-
 module Arx
 
   # Entity/model representing an arXiv paper.
   class Paper
     include HappyMapper
+    include Inspector
 
     tag 'entry'
 
     element :id, Cleaner, parser: :clean, tag: 'id'
     # The identifier of the paper.
-    # @note This is either in {Validate::OLD_IDENTIFIER_FORMAT} or {Validate::NEW_IDENTIFIER_FORMAT}.
+    # @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
-      @id.sub /https?\:\/\/arxiv\.org\/abs\//, ''
+    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
-      @id
+    def url(version: false)
+      "http://arxiv.org/abs/#{id version: 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?
+      version > 1
     end
 
-    # @!method last_updated
+    # @!method updated_at
     # The date that the paper was last updated.
     # @return [DateTime]
-    element :last_updated, DateTime, tag: 'updated'
+    element :updated_at, DateTime, tag: 'updated'
 
-    # @!method publish_date
+    # @!method published_at
     # The original publish/submission date of the paper.
     # @return [DateTime]
-    element :publish_date, DateTime, tag: 'published'
+    element :published_at, DateTime, tag: 'published'
 
     # @!method title
     # The title of the paper.
@@ -57,19 +66,13 @@ module Arx
     # 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'
 
-    # Whether the paper is a revision or not.
-    # @note A paper is a revision if {last_updated} differs from {publish_date}.
-    # @return [Boolean]
-    def revision?
-      @publish_date != @last_updated
-    end
-
     # @!method summary
     # The summary (or abstract) of the paper.
     # @return [String]
@@ -83,7 +86,7 @@ module Arx
     # @!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 {MissingFieldError} If the paper does not have a comment.
+    # @raise {Error::MissingField} If the paper does not have a comment.
     # @return [String]
     element :comment, Cleaner, parser: :clean, tag: 'comment'
 
@@ -94,7 +97,7 @@ module Arx
     # @!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 {MissingFieldError} If the paper does not have a journal reference.
+    # @raise {Error::MissingField} If the paper does not have a journal reference.
     # @return [String]
     element :journal, Cleaner, parser: :clean, tag: 'journal_ref'
 
@@ -109,7 +112,7 @@ module Arx
         if self.send "#{optional}?"
           instance_variable_get("@#{optional}")
         else
-          raise MissingFieldError.new(optional)
+          raise Error::MissingField.new id, optional
         end
       end
     end
@@ -123,7 +126,7 @@ module Arx
     # @!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 {MissingLinkError} If the paper does not have a PDF link.
+    # @raise {Error::MissingLink} If the paper does not have a PDF link.
     # @return [String]
 
     # @!method doi?
@@ -137,7 +140,7 @@ module Arx
     # @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?}
-    # @raise {MissingLinkError} If the paper does not have a DOI link.
+    # @raise {Error::MissingLink} If the paper does not have a DOI link.
     # @return [String]
 
     %i[pdf doi].each do |link_type|
@@ -151,9 +154,20 @@ module Arx
         if self.send exists
           links.find(&exists).href
         else
-          raise MissingLinkError.new link_type.to_s.upcase
+          raise Error::MissingLink.new id, link_type.to_s.upcase
         end
       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
+    ]
   end
 end

data/lib/arx/error.rb

@@ -0,0 +1,27 @@
+module Arx
+
+  # Various arXiv-related errors.
+  module Error
+
+    # Custom error for missing links on an arXiv paper.
+    class MissingLink < StandardError
+      def initialize(id, link_type)
+        super "arXiv paper #{id} does not have a #{link_type} link"
+      end
+    end
+
+    # Custom error for missing fields on an arXiv paper.
+    class MissingField < StandardError
+      def initialize(id, field)
+        super "arXiv paper #{id} is missing the `#{field}` metadata 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
+end

data/lib/arx/inspector.rb

@@ -0,0 +1,42 @@
+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
+
+    # Overwrites the object's own inspect method.
+    def inspect
+      pairs = {}
+
+      self.class.inspector_fields.each do |field|
+        pairs[field] = self.send(field).inspect
+      rescue
+      end
+
+      "#<#{self.class.name}:#{self.object_id} #{pairs.map {|k,v| "#{k}=#{v}"}.join(", ")}>"
+    end
+
+    class << self
+      # Returns the +inspected+ instance variable, or sets it if undefined.
+      def inspected
+        @inspected ||= []
+      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
+        source.class_eval do
+          def self.inspector(*fields)
+            @inspector_fields = *fields
+          end
+
+          def self.inspector_fields
+            @inspector_fields ||= []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/arx/query/query.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require 'cgi'
-require_relative 'validate'
-
 module Arx
 
   # Class for generating arXiv search API query strings.
@@ -25,13 +22,6 @@ module Arx
       and_not: 'ANDNOT'
     }
 
-    # Logical connective method names.
-    CONNECTIVE_METHODS = {
-      '&': :and,
-      '!': :and_not,
-      '|': :or
-    }
-
     # 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)
@@ -69,69 +59,68 @@ module Arx
       @query = String.new
 
       Validate.sort_by sort_by, permitted: SORT_BY.keys
-      @query << "&#{PARAMS[:sort_by]}=#{SORT_BY[sort_by]}"
+      @query << "#{PARAMS[:sort_by]}=#{SORT_BY[sort_by]}"
 
       Validate.sort_order sort_order, permitted: SORT_ORDER.keys
       @query << "&#{PARAMS[:sort_order]}=#{SORT_ORDER[sort_order]}"
 
       ids.flatten!
       unless ids.empty?
-        ids.map! {|id| extract_id id}
-        Validate.ids ids
+        ids.map! &Cleaner.method(:extract_id)
         @query << "&#{PARAMS[:id_list]}=#{ids * ','}"
       end
 
       yield self if block_given?
     end
 
-    # @!method &
+    # @!method and
     # Logical conjunction (+AND+) of subqueries.
     # @see https://arxiv.org/help/api/user-manual#query_details arXiv user manual
     # @return [self]
 
-    # @!method !
+    # @!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 |
+    # @!method or
     # Logical disjunction (+OR+) of subqueries.
     # @see https://arxiv.org/help/api/user-manual#query_details arXiv user manual
     # @return [self]
 
-    CONNECTIVE_METHODS.each do |symbol, connective|
-      define_method(symbol) { add_connective connective }
+    CONNECTIVES.keys.each do |connective|
+      define_method(connective) { add_connective connective }
     end
 
-    # @!method title(*values, exact: false, connective: :and)
+    # @!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.
     # @return [self]
 
-    # @!method author(*values, exact: false, connective: :and)
+    # @!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.
     # @return [self]
 
-    # @!method abstract(*values, exact: false, connective: :and)
+    # @!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.
     # @return [self]
 
-    # @!method comment(*values, exact: false, connective: :and)
+    # @!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.
     # @return [self]
 
-    # @!method journal(*values, exact: false, connective: :and)
+    # @!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).
@@ -161,6 +150,8 @@ module Arx
       define_method(name) do |*values, exact: true, connective: :and|
         return if values.empty?
 
+        values.flatten!
+
         Validate.values values
         Validate.categories values if name == :category
         Validate.exact exact
@@ -182,6 +173,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]
@@ -197,8 +202,9 @@ module Arx
     # @param connective [Symbol] The symbol of the logical connective to add.
     # @return [self]
     def add_connective(connective)
-      return unless search_query?
-      @query << "+#{CONNECTIVES[connective]}" unless ends_with_connective?
+      if search_query?
+        @query << "+#{CONNECTIVES[connective]}" unless end_with_connective? || start_of_group?
+      end
       self
     end
 
@@ -206,13 +212,10 @@ module Arx
     #
     # @param subquery [String] The subquery to add.
     def add_subquery(subquery)
+      add_connective :and unless end_with_connective?
+
       if search_query?
-        if ends_with_connective?
-          @query << "+#{subquery}"
-        else
-          add_connective :and
-          @query << "+#{subquery}"
-        end
+        @query << (start_of_group? ? "#{subquery}" : "+#{subquery}")
       else
         @query << "&#{PARAMS[:search_query]}=#{subquery}"
       end
@@ -230,10 +233,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.
@@ -249,18 +259,5 @@ module Arx
     def enquote(string)
       CGI.escape("\"") + string + CGI.escape("\"")
     end
-
-    # Attempt to extract an ID from an arXiv URL.
-    #
-    # @param url [String] The URL to extract the ID from.
-    # @return [String] The extracted ID if successful, otherwise the original string.
-    def extract_id(url)
-      prefix = %r"^(https?\:\/\/)?(www.)?arxiv\.org\/abs\/"
-      if %r"#{prefix}.*$".match? url
-        url.sub(prefix, '').sub(%r"\/$", '')
-      else
-        url
-      end
-    end
   end
 end

data/lib/arx/query/validate.rb

@@ -1,30 +1,8 @@
-require_relative '../categories'
-
 module Arx
 
   # Validations for arXiv search query fields and identifier schemes.
+  # @private
   module Validate
-
-    # 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).
-    #
-    # @see https://arxiv.org/help/arxiv_identifier#new arXiv identifier (new)
-    # @example
-    #   1501.00001
-    #   1705.01662v1
-    #   1412.0135
-    #   0706.0001v2
-    NEW_IDENTIFIER_FORMAT = %r"^\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 = %r"^[a-z]+(\-[a-z]+)?\/\d{7}(v\d+)?$"
-
     class << self
       # Validates the +sortBy+ field of the query string.
       #
@@ -116,7 +94,9 @@ module Arx
       # @see NEW_IDENTIFIER_FORMAT
       # @see OLD_IDENTIFIER_FORMAT
       def id?(id)
-        NEW_IDENTIFIER_FORMAT.match?(id) || OLD_IDENTIFIER_FORMAT.match?(id)
+        return true if NEW_IDENTIFIER_FORMAT.match? id
+        return true if OLD_IDENTIFIER_FORMAT.match?(id) && Arx::CATEGORIES.keys.include?(id.split('/').first)
+        false
       end
     end
   end

data/lib/arx/version.rb

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