arx 0.3.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2fa216412d2bdf6261f3fd1ada0b0c50498f13e5a8142dfd3db3433b693e4b4
-  data.tar.gz: 31c272fcc9d1ed4750e88d4c179035a0f37995f1afc030378e656f402a2dfeec
+  metadata.gz: b23b9ea5d15ed9ed58108f69176cebe48f6d5ce44f7fd4f4bd6e2937d36e8a20
+  data.tar.gz: 0f0928e5737bbd6d5a0c2f058e4fc198b75f5968f94630d0648755616d2085a8
 SHA512:
-  metadata.gz: 8b8c8abf18d875a40e098f95dfb7452389a3b44691ecae568028563b12e5aa02e8b0233bf7fdfc25df58594df30b43f4caca37cf57df43240006ff22a5cfcdec
-  data.tar.gz: a8a40c0d3ccd18a86945e69a136b2275dcfd88a2ddc3678ab3b555f576e68b1d50d346b1c1a233def7bff62cb60fa0a071a870fcd6c41f34dcb8cf217d422437
+  metadata.gz: edf64375f0efffb2722afb5746d5fd5e7ce150c88f2a8ebecdf58db3ca8b1de9c24cb950630e33f418db54d98c7cc351d5ee370e3fc481de55a4b3da59b658bd
+  data.tar.gz: bdb9966e13ede3888ff707c8c5c1350cb74af45b276b392242985adc9e6f48ab41ca5ecc1b5f53289ac862adadcaabdd58f509932d930feac75aefc47a8ba6e1

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+# 1.0.0
+
+#### Major changes
+
+- Change `Query` connective instance methods ([#38](https://github.com/eonu/arx/pull/38)):
+  - `#&` -> `#and`
+  - `#|` -> `#or`
+  - `#!` -> `#and_not`
+- Split version number from paper identifier in `Paper` (add `version` key-word argument to `#id` and `#url`, and add `#version`). ([#39](https://github.com/eonu/arx/pull/39))
+- Add `Cleaner.extract_id` and `Cleaner.extract_version`. ([#39](https://github.com/eonu/arx/pull/39))
+- Make `Query#add_connective` always return `self`. ([#40](https://github.com/eonu/arx/pull/40))
+- Redefine `Arx.search` to user `Paper.parse`'s `search` key-word argument. ([#40](https://github.com/eonu/arx/pull/40))
+- Implement all tests. ([#40](https://github.com/eonu/arx/pull/40))
+
+#### Minor changes
+
+- Change declared regular expression literals from `%r""` to standard `//`. ([#39](https://github.com/eonu/arx/pull/39))
+- Remove `#extract_id` from `Query` and use `Cleaner.extract_id` instead. ([#39](https://github.com/eonu/arx/pull/39))
+- Redefine `Paper#revision?` to use the new `#version` instead of `#updated_at` and`#published_at`. ([#39](https://github.com/eonu/arx/pull/39))
+
 # 0.3.2
 
 #### Major changes

data/README.md

@@ -24,6 +24,23 @@ Although [Scholastica](https://github.com/scholastica) offer a great [Ruby gem](
 
 *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.*
 
+## Example
+
+Suppose we wish to search for:
+
+> Papers in the `cs.FL` (Formal Languages and Automata Theory) category whose title contains `"Buchi Automata"`, not authored by `Tomáš Babiak`, sorted by submission date (latest first).
+
+This query can be executed with the following code:
+
+```ruby
+require 'arx'
+
+papers = Arx(sort_by: :date_submitted) do |query|
+  query.category('cs.FL')
+  query.title('Buchi Automata').and_not.author('Tomáš Babiak')
+end
+```
+
 ## Features
 
 - Ruby classes `Arx::Paper`, `Arx::Author` and `Arx::Category` that wrap the resulting Atom XML query result from the search API.
@@ -178,13 +195,13 @@ 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:
+To change the logical connective used to chain subqueries, use the `and`, `or`, `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.and_not
 q.category('math.NA', 'math.CO', connective: :or)
 ```
 
@@ -202,9 +219,7 @@ Calling the `Arx()` method with a block allows for the construction and executio
 # 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')
+  query.title('Buchi Automata').and_not.author('Tomáš Babiak')
 end
 
 results.size #=> 18
@@ -220,9 +235,7 @@ The `Arx()` method accepts a predefined `Arx::Query` object through the `query`
 # 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')
+q.title('Buchi Automata').and_not.author('Tomáš Babiak')
 
 results = Arx(query: q)
 results.size #=> 18
@@ -259,9 +272,18 @@ paper = Arx('1809.09415')
 #=> #<Arx::Paper:0x00007fb657b59bd0>
 
 paper.id
+#=> "1809.09415"
+paper.id(version: true)
 #=> "1809.09415v1"
 paper.url
+#=> "http://arxiv.org/abs/1809.09415"
+paper.url(version: true)
 #=> "http://arxiv.org/abs/1809.09415v1"
+paper.version
+#=> 1
+paper.revision?
+#=> false
+
 paper.title
 #=> "On finitely ambiguous Büchi automata"
 paper.summary
@@ -280,8 +302,6 @@ 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?

data/lib/arx.rb

@@ -32,7 +32,7 @@ module Arx
   #   1705.01662v1
   #   1412.0135
   #   0706.0001v2
-  NEW_IDENTIFIER_FORMAT = %r"^\d{4}\.\d{4,5}(v\d+)?$"
+  NEW_IDENTIFIER_FORMAT = /^\d{4}\.\d{4,5}(v\d+)?$/
 
   # The legacy arXiv paper identifier scheme (before 1 April 2007).
   #
@@ -40,7 +40,7 @@ module Arx
   # @example
   #   math/0309136v1
   #   cond-mat/0211034
-  OLD_IDENTIFIER_FORMAT = %r"^[a-z]+(\-[a-z]+)?\/\d{7}(v\d+)?$"
+  OLD_IDENTIFIER_FORMAT = /^[a-z]+(\-[a-z]+)?\/\d{7}(v\d+)?$/
 
   class << self
 
@@ -59,9 +59,15 @@ module Arx
       yield query if block_given?
 
       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 Error::MissingPaper.new(ids.first) if results.empty? && ids.size == 1
-      ids.size == 1 && results.size == 1 ? results.first : results
+      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?}
+      end
+
+      results
     end
 
     alias_method :find, :search

data/lib/arx/cleaner.rb

@@ -4,11 +4,50 @@ module Arx
   # @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/paper.rb

@@ -13,18 +13,33 @@ module Arx
     # @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 updated_at
@@ -58,13 +73,6 @@ module Arx
     # @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]
@@ -152,9 +160,10 @@ module Arx
     end
 
     inspector *%i[
-      id url title summary authors
+      id url version revision?
+      title summary authors
       primary_category categories
-      published_at updated_at revision?
+      published_at updated_at
       comment? comment
       journal? journal
       pdf? pdf_url

data/lib/arx/query/query.rb

@@ -22,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)
@@ -73,31 +66,30 @@ module Arx
 
       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: true, connective: :and)
@@ -196,8 +188,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 ends_with_connective?
+      end
       self
     end
 
@@ -206,12 +199,8 @@ module Arx
     # @param subquery [String] The subquery to add.
     def add_subquery(subquery)
       if search_query?
-        if ends_with_connective?
-          @query << "+#{subquery}"
-        else
-          add_connective :and
-          @query << "+#{subquery}"
-        end
+        add_connective :and unless ends_with_connective?
+        @query << "+#{subquery}"
       else
         @query << "&#{PARAMS[:search_query]}=#{subquery}"
       end
@@ -248,18 +237,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

@@ -94,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,
-    minor: 3,
-    patch: 2,
+    major: 1,
+    minor: 0,
+    patch: 0,
     meta: nil,
   }.compact.values.join('.').freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arx
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Edwin Onuonga
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-30 00:00:00.000000000 Z
+date: 2019-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri