Initial commit! 🎉

.gitignore

@@ -0,0 +1,42 @@
+## Ruby
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/tmp/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Used by dotenv library to load environment variables
+.env
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+/coverage/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+## OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+## Other
+/.bundle/
+Gemfile.lock
+.rvmrc

.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+before_install: gem update --system
+script: bundle exec rake
+rvm: 2.5

CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.1.0
+
+Initial commit! 🎉

Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Edwin Onuonga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,3 @@
+# Arx
+
+A Ruby interface for querying academic papers on the arXiv search API.

Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc 'Run application specs'
+RSpec::Core::RakeTask.new :spec
+
+task default: [:spec]

arx.gemspec

@@ -0,0 +1,24 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'arx/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'arx'
+  spec.version       = Arx::VERSION
+  spec.authors       = ['Edwin Onuonga']
+  spec.email         = ['[email protected]']
+
+  spec.summary       = %q{A Ruby interface for querying academic papers on the arXiv search API.}
+  spec.license       = 'MIT'
+  spec.require_paths = ['lib']
+  spec.files         = Dir.glob('lib/**/*', File::FNM_DOTMATCH) + %w[
+    Gemfile LICENSE CHANGELOG.md README.md Rakefile arx.gemspec
+  ]
+
+  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 'rspec', '~> 3.7'
+end

lib/arx.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'open-uri'
+require 'arx/version'
+require 'arx/categories'
+require 'arx/query/query'
+require 'arx/query/validate'
+require 'arx/entities/author'
+require 'arx/entities/category'
+require 'arx/entities/paper'
+
+# A Ruby interface for querying academic papers on the arXiv search API.
+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.
+  #
+  # @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)
+
+    yield query if block_given?
+
+    document = Nokogiri::XML open(ENDPOINT + query.to_s + '&max_results=10000')
+    document.remove_namespaces!
+
+    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
+  end
+end
+
+# Performs a search query for papers on the arXiv search API.
+#
+# @note This is an alias of the {Arx.search} method.
+# @see Arx.search
+# @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 {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
+end

lib/arx/categories.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Arx
+
+  # arXiv categories and their full names
+  CATEGORIES = {
+    'astro-ph' => 'Astrophysics',
+    'astro-ph.CO' => 'Cosmology and Nongalactic Astrophysics',
+    'astro-ph.EP' => 'Earth and Planetary Astrophysics',
+    'astro-ph.GA' => 'Astrophysics of Galaxies',
+    'astro-ph.HE' => 'High Energy Astrophysical Phenomena',
+    'astro-ph.IM' => 'Instrumentation and Methods for Astrophysics',
+    'astro-ph.SR' => 'Solar and Stellar Astrophysics',
+    'cond-mat.dis-nn' => 'Disordered Systems and Neural Networks',
+    'cond-mat.mes-hall' => 'Mesoscale and Nanoscale Physics',
+    'cond-mat.mtrl-sci' => 'Materials Science',
+    'cond-mat.other' => 'Other Condensed Matter',
+    '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',
+    'cs.AI' => 'Artificial Intelligence',
+    'cs.AR' => 'Hardware Architecture',
+    'cs.CC' => 'Computational Complexity',
+    'cs.CE' => 'Computational Engineering, Finance, and Science',
+    'cs.CG' => 'Computational Geometry',
+    'cs.CL' => 'Computation and Language',
+    'cs.CR' => 'Cryptography and Security',
+    'cs.CV' => 'Computer Vision and Pattern Recognition',
+    'cs.CY' => 'Computers and Society',
+    'cs.DB' => 'Databases',
+    'cs.DC' => 'Distributed, Parallel, and Cluster Computing',
+    'cs.DL' => 'Digital Libraries',
+    'cs.DM' => 'Discrete Mathematics',
+    'cs.DS' => 'Data Structures and Algorithms',
+    'cs.ET' => 'Emerging Technologies',
+    'cs.FL' => 'Formal Languages and Automata Theory',
+    'cs.GL' => 'General Literature',
+    'cs.GR' => 'Graphics',
+    'cs.GT' => 'Computer Science and Game Theory',
+    'cs.HC' => 'Human-Computer Interaction',
+    'cs.IR' => 'Information Retrieval',
+    'cs.IT' => 'Information Theory',
+    'cs.LG' => 'Learning',
+    'cs.LO' => 'Logic in Computer Science',
+    'cs.MA' => 'Multiagent Systems',
+    'cs.MM' => 'Multimedia',
+    'cs.MS' => 'Mathematical Software',
+    'cs.NA' => 'Numerical Analysis',
+    'cs.NE' => 'Neural and Evolutionary Computing',
+    'cs.NI' => 'Networking and Internet Architecture',
+    'cs.OH' => 'Other Computer Science',
+    'cs.OS' => 'Operating Systems',
+    'cs.PF' => 'Performance',
+    'cs.PL' => 'Programming Languages',
+    'cs.RO' => 'Robotics',
+    'cs.SC' => 'Symbolic Computation',
+    'cs.SD' => 'Sound',
+    'cs.SE' => 'Software Engineering',
+    'cs.SI' => 'Social and Information Networks',
+    'cs.SY' => 'Systems and Control',
+    'econ.EM' => 'Econometrics',
+    'eess.AS' => 'Audio and Speech Processing',
+    'eess.IV' => 'Image and Video Processing',
+    'eess.SP' => 'Signal Processing',
+    'gr-qc' => 'General Relativity and Quantum Cosmology',
+    'hep-ex' => 'High Energy Physics - Experiment',
+    'hep-lat' => 'High Energy Physics - Lattice',
+    'hep-ph' => 'High Energy Physics - Phenomenology',
+    'hep-th' => 'High Energy Physics - Theory',
+    'math.AC' => 'Commutative Algebra',
+    'math.AG' => 'Algebraic Geometry',
+    'math.AP' => 'Analysis of PDEs',
+    'math.AT' => 'Algebraic Topology',
+    'math.CA' => 'Classical Analysis and ODEs',
+    'math.CO' => 'Combinatorics',
+    'math.CT' => 'Category Theory',
+    'math.CV' => 'Complex Variables',
+    'math.DG' => 'Differential Geometry',
+    'math.DS' => 'Dynamical Systems',
+    'math.FA' => 'Functional Analysis',
+    'math.GM' => 'General Mathematics',
+    'math.GN' => 'General Topology',
+    'math.GR' => 'Group Theory',
+    'math.GT' => 'Geometric Topology',
+    'math.HO' => 'History and Overview',
+    'math.IT' => 'Information Theory',
+    'math.KT' => 'K-Theory and Homology',
+    'math.LO' => 'Logic',
+    'math.MG' => 'Metric Geometry',
+    'math.MP' => 'Mathematical Physics',
+    'math.NA' => 'Numerical Analysis',
+    'math.NT' => 'Number Theory',
+    'math.OA' => 'Operator Algebras',
+    'math.OC' => 'Optimization and Control',
+    'math.PR' => 'Probability',
+    'math.QA' => 'Quantum Algebra',
+    'math.RA' => 'Rings and Algebras',
+    'math.RT' => 'Representation Theory',
+    'math.SG' => 'Symplectic Geometry',
+    'math.SP' => 'Spectral Theory',
+    'math.ST' => 'Statistics Theory',
+    'math-ph' => 'Mathematical Physics',
+    'nlin.AO' => 'Adaptation and Self-Organizing Systems',
+    'nlin.CD' => 'Chaotic Dynamics',
+    'nlin.CG' => 'Cellular Automata and Lattice Gases',
+    'nlin.PS' => 'Pattern Formation and Solitons',
+    'nlin.SI' => 'Exactly Solvable and Integrable Systems',
+    'nucl-ex' => 'Nuclear Experiment',
+    'nucl-th' => 'Nuclear Theory',
+    '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',
+    'q-bio.BM' => 'Biomolecules',
+    'q-bio.CB' => 'Cell Behavior',
+    'q-bio.GN' => 'Genomics',
+    'q-bio.MN' => 'Molecular Networks',
+    'q-bio.NC' => 'Neurons and Cognition',
+    'q-bio.OT' => 'Other Quantitative Biology',
+    'q-bio.PE' => 'Populations and Evolution',
+    'q-bio.QM' => 'Quantitative Methods',
+    'q-bio.SC' => 'Subcellular Processes',
+    'q-bio.TO' => 'Tissues and Organs',
+    'q-fin.CP' => 'Computational Finance',
+    'q-fin.EC' => 'Economics',
+    'q-fin.GN' => 'General Finance',
+    'q-fin.MF' => 'Mathematical Finance',
+    'q-fin.PM' => 'Portfolio Management',
+    'q-fin.PR' => 'Pricing of Securities',
+    'q-fin.RM' => 'Risk Management',
+    'q-fin.ST' => 'Statistical Finance',
+    'q-fin.TR' => 'Trading and Market Microstructure',
+    'quant-ph' => 'Quantum Physics',
+    'stat.AP' => 'Applications',
+    'stat.CO' => 'Computation',
+    'stat.ME' => 'Methodology',
+    'stat.ML' => 'Machine Learning',
+    'stat.OT' => 'Other Statistics',
+    'stat.TH' => 'Statistics Theory'
+  }.freeze
+end

lib/arx/cleaner.rb

@@ -0,0 +1,13 @@
+module Arx
+
+  # Class for cleaning strings.
+  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 ' '
+    end
+  end
+end

lib/arx/entities/author.rb

@@ -0,0 +1,29 @@
+require 'happymapper'
+require 'arx/cleaner'
+
+module Arx
+
+  # Entity/model representing an arXiv paper's author.
+  class Author
+    include HappyMapper
+
+    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
+
+    # @!method affiliations?
+    # Whether or not the author has any affiliations.
+    # @return [Boolean]
+    def affiliations?
+      !affiliations.empty?
+    end
+  end
+end