arx 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77d25732b98e3be9492bc5e103c51a2919217510e4b85e4690c1338ece3ef1fd
-  data.tar.gz: 0cb9a4134e64581160c079fdd47c3082f39eb72b3069a13c3f6ebd2a74c14eae
+  metadata.gz: 060171d105d65f9380f65232ebc4ba838c88c0ea83a1019f07b7ee54c5156cd6
+  data.tar.gz: e8253d7a61f2954f1b5522b7ed98cabd1103973bb85d29bf7f4ace357e2739ea
 SHA512:
-  metadata.gz: f91faea3efef98fc048906719b2919267fa78b99ae2e4623b7500a575691af90df5c3a7ed03328f94ebb89f5d17d754e51b6e77548e23b4482d7b603144fcf7c
-  data.tar.gz: 898c9c61db65c62852f0b7a097df59a0fccc77f03a1e853a06b92a0edcf31e3d5c912de1a8fde61e6b511c51523cf89bcd902a64a862d7f6f264e2869dbbad35
+  metadata.gz: 3c7ca66790bd3688556174120132e6eae5618202a32d05fe4b9c10c07892ca5e92f9bf71da3adf8f17cbc9a94a05550ed194c85a4dda69217920f2eda230daff
+  data.tar.gz: 8cf1b676f6f18494a1b8b91678b2668ef110114b9987204e92a0ddc6d38001c9bcaa8ae3c065562329c806069a25cfd4ff2ce1ffba28838b27e6e46708f87c55

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 0.3.0
+
+#### Major changes
+
+- Add documentation, images, installation and usage instructions to `README.md`. ([#22](https://github.com/eonu/arx/pull/22), [#17](https://github.com/eonu/arx/pull/17))
+- Allow prior construction of a search query in `Arx.search`. ([#18](https://github.com/eonu/arx/pull/18))
+- Fix `Arx.search` query object yielding. ([#20](https://github.com/eonu/arx/pull/20))
+
+#### Minor changes
+
+- Remove conditional with `block_given?` in `Arx()` method. ([#16](https://github.com/eonu/arx/pull/16))
+- Remove leading ampersand (&) from search query string. ([#19](https://github.com/eonu/arx/pull/19))
+- Add base paper categories and more aliases. ([#21](https://github.com/eonu/arx/pull/21))
+
 # 0.2.0
 
 #### Major changes

data/README.md

@@ -10,4 +10,333 @@
 [![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://www.rubydoc.info/gems/arx/toplevel)
 [![Build Status](https://travis-ci.com/eonu/arx.svg?branch=master)](https://travis-ci.com/eonu/arx)
 
-A Ruby interface for querying academic papers on the arXiv search API.
+**A Ruby interface for querying academic papers on the arXiv search API.**
+
+<img src="https://i.ibb.co/19Djpzk/arxiv.png" width="25%" align="left"></img>
+
+> arXiv is an e-print service in the fields of physics, mathematics, non-linear science, computer science, quantitative biology, quantitative finance and statistics.
+
+---
+
+[arXiv](https://arxiv.org/) provides an advanced search utility (shown left) on their website, as well as an extensive [search API](https://arxiv.org/help/api) that allows for the external querying of academic papers hosted on their website.
+
+Although [Scholastica](https://github.com/scholastica) offer a great [Ruby gem](https://github.com/scholastica/arxiv) for retrieving papers from arXiv through the search API, this gem is only intended for retrieving one paper at a time, and only supports searching for paper by ID.
+
+*Arx is a gem that allows for quick and easy querying of the arXiv search API, without having to worry about manually writing your own search query strings or parse the resulting XML query response to find the data you need.*
+
+## Features
+
+- Ruby classes `Arx::Paper`, `Arx::Author` and `Arx::Category` that wrap the resulting Atom XML query result from the search API.
+- Supports querying by a paper's ID, title, author(s), abstract, subject category, comment, journal reference, or report number.
+- Provides a small embedded DSL for writing queries.
+- Supports searching fields by exact match.
+
+## Installation
+
+To install Arx, run the following in your terminal:
+
+```bash
+$ gem install arx
+```
+
+## Documentation
+
+The documentation for Arx is hosted on [![rubydoc.info](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://www.rubydoc.info/gems/arx/toplevel).
+
+## Usage
+
+Before you start using Arx, you'll have to ensure that the gem is required (either in your current working file, or shell such as [IRB](https://en.wikipedia.org/wiki/Interactive_Ruby_Shell)):
+
+```ruby
+require 'arx'
+```
+
+### Building search queries
+
+Query requests submitted to the arXiv search API are typically of the following form (where the query string is indicated in bold):
+
+[http://export.arxiv.org/api/query?**search_query=ti:%22Buchi+Automata%22+AND+cat:%22cs.FL%22**](http://export.arxiv.org/api/query?search_query=ti:%22Buchi+Automata%22+AND+cat:%22cs.FL%22)
+
+> This particular query searches for papers whose title includes the string `Buchi Automata`, and are in the *Formal Languages and Automata Theory* (`cs.FL`) category.
+
+Obviously writing out queries like this can quickly become time-consuming and tedious.
+
+---
+
+The `Arx::Query` class provides a small embedded DSL for writing these query strings.
+
+#### Sorting criteria and order
+
+The order in which search results are returned can be modified through the `sort_by` and `sort_order` keyword arguments (in the `Arx::Query` initializer):
+
+- `sort_by` accepts the symbols: `:relevance`, `:last_updated` or `:date_submitted`
+
+- `sort_order` accepts the symbols: `:ascending` or `:descending`
+
+```ruby
+# Sort by submission date in ascending order (earliest first)
+Arx::Query.new(sort_by: :date_submitted, sort_order: :ascending)
+#=> sortBy=submittedDate&sortOrder=ascending
+```
+
+**Note**: The default setting is to sort by `:relevance` in `:descending` order:
+
+```ruby
+Arx::Query.new #=> sortBy=relevance&sortOrder=descending
+```
+
+#### Searching by ID
+
+The arXiv search API doesn't only support searching for papers by metadata fields, but also by ID. When searching by ID, a different URL query string parameter `id_list` is used (instead of `search_query` as seen before).
+
+Although the `id_list` can be used to *"search by ID"*, it is better to **think of it as restricting the search space to the papers with the provided IDs**:
+
+| `search_query` present? | `id_list` present? | Returns                                              |
+| ----------------------- | ------------------ | ---------------------------------------------------- |
+| Yes                     | No                 | Articles that match `search_query`                   |
+| No                      | Yes                | Articles that are in `id_list`                       |
+| Yes                     | Yes                | Articles in `id_list` that also match `search_query` |
+
+To search by ID, simply pass the arXiv paper identifiers (ID) or URLs into the `Arx::Query` initializer method:
+
+```ruby
+Arx::Query.new('https://arxiv.org/abs/1711.05738', '1809.09415')
+#=> sortBy=relevance&sortOrder=descending&id_list=1711.05738,1809.09415
+```
+
+#### Searching by metadata fields
+
+The arXiv search API supports searches for the following paper metadata fields:
+
+```ruby
+FIELDS = {
+  title: 'ti',     # Title
+  author: 'au',    # Author
+  abstract: 'abs', # Abstract
+  comment: 'co',   # Comment
+  journal: 'jr',   # Journal reference
+  category: 'cat', # Subject category
+  report: 'rn',    # Report number
+  all: 'all'       # All (of the above)
+}
+```
+
+Each of these fields has an instance method defined under the `Arx::Query` class. For example:
+
+```ruby
+# Papers whose title contains the string "Buchi Automata".
+q = Arx::Query.new
+q.title('Buchi Automata')
+#=> sortBy=relevance&sortOrder=descending&search_query=ti:%22Buchi+Automata%22
+```
+
+##### Exact matches
+
+By default, this searches for exact matches of the provided string (by adding double quotes around the string - in the query string, this is represented by the `%22`s). To disable this, you can use the `exact` keyword argument (which defaults to `true`):
+
+```ruby
+# Papers whose title contains either the words "Buchi" or "Automata".
+q = Arx::Query.new
+q.title('Buchi Automata', exact: false)
+#=> sortBy=relevance&sortOrder=descending&search_query=ti:Buchi+Automata
+```
+
+##### Multiple values for one field
+
+Sometimes you might want to provide multiple field values to search for a paper by. This can simply be done by adding them as another argument (or providing an `Array`):
+
+**Note**: The default logical connective used when there are multiple values for one field is `and`.
+
+```ruby
+# Papers authored by both "Eleonora Andreotti" and "Dominik Edelmann".
+q = Arx::Query.new
+q.author('Eleonora Andreotti', 'Dominik Edelmann')
+```
+
+To change the logical connective to `or` or `not` (and not), use the `connective` keyword argument:
+
+```ruby
+# Papers authored by either "Eleonora Andreotti" or "Dominik Edelmann".
+q = Arx::Query.new
+q.author('Eleonora Andreotti', 'Dominik Edelmann', connective: :or)
+```
+
+```ruby
+# Papers authored by "Eleonora Andreotti" and not "Dominik Edelmann".
+q = Arx::Query.new
+q.author('Eleonora Andreotti', 'Dominik Edelmann', connective: :and_not)
+```
+
+#### Chaining subqueries (logical connectives)
+
+**Note**: By default, subqueries (successive instance method calls) are chained with a logical `and` connective.
+
+```ruby
+# Papers authored by "Dominik Edelmann" in the "Numerical Analysis" (math.NA) category.
+q = Arx::Query.new
+q.author('Dominik Edelmann')
+q.category('math.NA')
+```
+
+To change the logical connective used to chain subqueries, use the `&()` (and), `|()` (or) and `!()` (and not) instance methods between the subquery calls:
+
+```ruby
+# Papers authored by "Eleonora Andreotti" in neither the "Numerical Analysis" (math.NA) or "Combinatorics (math.CO)" categories.
+q = Arx::Query.new
+q.author('Eleonora Andreotti')
+q.!()
+q.category('math.NA', 'math.CO', connective: :or)
+```
+
+### Running search queries
+
+Search queries can be executed with the `Arx()` method (alias of `Arx.search`). This method contains the same parameters as the `Arx::Query` initializer - including the list of IDs.
+
+#### Without a predefined query
+
+Calling the `Arx()` method with a block allows for the construction and execution of a new query.
+
+**Note**: If running a search query this way, then the `sort_by` and `sort_order` parameters can be added as additional keyword arguments.
+
+```ruby
+# Papers in the cs.FL category whose title contains "Buchi Automata", not authored by Tomáš Babiak
+results = Arx(sort_by: :date_submitted) do |query|
+  query.category('cs.FL')
+  query.title('Buchi Automata')
+  query.!()
+  query.author('Tomáš Babiak')
+end
+
+results.size #=> 18
+```
+
+#### With a predefined query
+
+The `Arx()` method accepts a predefined `Arx::Query` object through the `query` keyword parameter.
+
+**Note**: If using the `query` parameter, the `sort_by` and `sort_order` criteria should be defined in the `Arx::Query` object initializer rather than as arguments in `Arx()`.
+
+```ruby
+# Papers in the cs.FL category whose title contains "Buchi Automata", not authored by Tomáš Babiak
+q = Arx::Query.new(sort_by: :date_submitted)
+q.category('cs.FL')
+q.title('Buchi Automata')
+q.!()
+q.author('Tomáš Babiak')
+
+results = Arx(query: q)
+results.size #=> 18
+```
+
+#### With IDs
+
+The `Arx()` methods accepts a list of IDs as a splat parameter, just like the `Arx::Query` initializer.
+
+If only one ID is specified, then a single `Arx::Paper` is returned:
+
+```ruby
+result = Arx('1809.09415')
+result.class #=> Arx::Paper
+```
+
+Otherwise, an `Array` of `Arx::Paper`s is returned.
+
+### Query results
+
+Search results are typically:
+
+- an `Array`, either empty if no papers matched the supplied query, or containing `Arx::Paper` objects.
+- a single `Arx::Paper` object (when the search method is only supplied with one ID).
+
+### Entities
+
+The `Arx::Paper`, `Arx::Author` and `Arx::Category` classes provide a simple interface for the metadata concerning a single arXiv paper:
+
+#### `Arx::Paper`
+
+```ruby
+paper = Arx('1809.09415')
+#=> #<Arx::Paper:0x00007fb657b59bd0>
+
+paper.id
+#=> "1809.09415v1"
+paper.url
+#=> "http://arxiv.org/abs/1809.09415v1"
+paper.title
+#=> "On finitely ambiguous Büchi automata"
+paper.summary
+#=> "Unambiguous B\\\"uchi automata, i.e. B\\\"uchi automata allowing..."
+paper.authors
+#=> [#<Arx::Author:0x00007fb657b63108>, #<Arx::Author:0x00007fb657b62438>]
+
+# Paper's categories
+paper.primary_category
+#=> #<Arx::Category:0x00007fb657b61830>
+paper.categories
+#=> [#<Arx::Category:0x00007fb657b60e80>]
+
+# Dates
+paper.published_at
+#=> #<DateTime: 2018-09-25T11:40:39+00:00 ((2458387j,42039s,0n),+0s,2299161j)>
+paper.updated_at
+#=> #<DateTime: 2018-09-25T11:40:39+00:00 ((2458387j,42039s,0n),+0s,2299161j)>
+paper.revision?
+#=> false
+
+# Paper's comment
+paper.comment?
+#=> false
+paper.comment
+#=> Arx::MissingFieldError (This arXiv paper is missing the `comment` field)
+
+# Paper's journal reference
+paper.journal?
+#=> false
+paper.journal
+#=> Arx::MissingFieldError (This arXiv paper is missing the `journal` field)
+
+# Paper's PDF URL
+paper.pdf?
+#=> true
+paper.pdf_url
+#=> "http://arxiv.org/pdf/1809.09415v1"
+
+# Paper's DOI (Digital Object Identifier) URL
+paper.doi?
+#=> true
+paper.doi_url
+#=> "http://dx.doi.org/10.1007/978-3-319-98654-8_41"
+```
+
+#### `Arx::Author`
+
+```ruby
+paper = Arx('cond-mat/9609089')
+#=> #<Arx::Paper:0x00007fb657a7b8d0>
+
+author = paper.authors.first
+#=> #<Arx::Author:0x00007fb657a735e0>
+
+author.name
+#=> "F. Gebhard"
+
+author.affiliations?
+#=> true
+author.affiliations
+#=> ["ILL Grenoble, France"]
+```
+
+#### `Arx::Category`
+
+```ruby
+paper = Arx('cond-mat/9609089')
+#=> #<Arx::Paper:0x00007fb657b59bd0>
+
+category = paper.primary_category
+#=> #<Arx::Category:0x00007fb6570609b8>
+
+category.name
+#=> "cond-mat"
+category.full_name
+#=> "Condensed Matter"
+```

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/entities/category.rb

@@ -18,7 +18,7 @@ module Arx
     # @see CATEGORIES
     # @return [String]
     def full_name
-      CATEGORIES[term]
+      CATEGORIES[name]
     end
   end
 end

data/lib/arx/entities/paper.rb

@@ -37,11 +37,13 @@ module Arx
     # The date that the paper was last updated.
     # @return [DateTime]
     element :last_updated, DateTime, tag: 'updated'
+    alias_method :updated_at, :last_updated
 
     # @!method publish_date
     # The original publish/submission date of the paper.
     # @return [DateTime]
     element :publish_date, DateTime, tag: 'published'
+    alias_method :published_at, :publish_date
 
     # @!method title
     # The title of the paper.
@@ -57,11 +59,13 @@ module Arx
     # The primary category of the paper.
     # @return [Category]
     element :primary_category, Category, tag: 'primary_category'
+    alias_method :primary_subject, :primary_category
 
     # @!method categories
     # The categories of the paper.
     # @return [Array<Category>]
     has_many :categories, Category, tag: 'category'
+    alias_method :subjects, :categories
 
     # Whether the paper is a revision or not.
     # @note A paper is a revision if {last_updated} differs from {publish_date}.

data/lib/arx/query/query.rb

@@ -69,7 +69,7 @@ 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]}"

data/lib/arx/version.rb

@@ -5,7 +5,7 @@ module Arx
   # The current version of Arx.
   VERSION = {
     major: 0,
-    minor: 2,
+    minor: 3,
     patch: 0,
     meta: nil
   }.compact.values.join('.').freeze

data/lib/arx.rb

@@ -20,17 +20,21 @@ 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+.
     # @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, 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)
+      if query.nil?
+        query = Query.new(*ids, sort_by: sort_by, sort_order: sort_order)
+        yield query if block_given?
+      else
+        raise TypeError.new("Expected `query` to be an Arx::Query, got: #{query.class}") unless query.is_a? Query
+      end
 
-      yield query if block_given?
-
-      document = Nokogiri::XML open(ENDPOINT + query.to_s + '&max_results=10000')
-      document.remove_namespaces!
+      document = Nokogiri::XML(open ENDPOINT + query.to_s + '&max_results=10000').remove_namespaces!
 
       results = Paper.parse(document, single: false).reject {|paper| paper.id.empty?}
       raise MissingPaper.new(ids.first) if results.empty? && ids.size == 1
@@ -45,15 +49,13 @@ 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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Edwin Onuonga
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-25 00:00:00.000000000 Z
+date: 2019-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri