arx 0.3.2 → 1.2.1

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,14 +1,55 @@
 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

@@ -5,24 +5,63 @@ 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.
+    def ==(author)
+      if author.is_a? Author
+        name == author.name
+      else
+        false
+      end
+    end
+
+    inspector *ATTRIBUTES
   end
 end

data/lib/arx/entities/category.rb

@@ -5,20 +5,57 @@ 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.
+    def ==(category)
+      if category.is_a? Category
+        name == category.name
+      else
+        false
+      end
+    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,78 +5,112 @@ 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
-      @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}"
+    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 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'
 
-    # Whether the paper is a revision or not.
-    # @note A paper is a revision if {updated_at} differs from {published_at}.
-    # @return [Boolean]
-    def revision?
-      @published_at != @updated_at
-    end
-
     # @!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]
@@ -84,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]
@@ -113,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?}
@@ -151,14 +191,62 @@ module Arx
       end
     end
 
-    inspector *%i[
-      id url title summary authors
-      primary_category categories
-      published_at updated_at revision?
-      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.
+    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
+
+    inspector *ATTRIBUTES
   end
 end