rfc-reader 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b42f53e0145a5153d21e1f555c006e2081c43c126b60c581f5687567530f00b
-  data.tar.gz: cb3d545f31ebba48757242e003e9f3ef2d9960c1a6277256cfc6dfcc389af38c
+  metadata.gz: cc7f0a4142e7e5cb5b1ed4b8a5ecda4728177df15e6f9c8d7e84dcc557b660e4
+  data.tar.gz: 89e7ac7472c84e84d87feed86e66f35f14dbc65a7af39e6a55fe65e158b78e89
 SHA512:
-  metadata.gz: 3337413fc3634c92bf8ec4ff3f347749de4b4cff385e6b29184fa63a641e8456f9cfd21142e07d125b09e320aa38bbab57e90c7f64cc2f75d516c7fa3307d81a
-  data.tar.gz: 557038fda98a3ea623ea128cd99aa4423ff2befb1493f4f0e7313807a60273bf2c14007df1d818b90ce5e33bdd6de08a8d5814e69227104ede1eaa21cb4349e8
+  metadata.gz: 0b0588ecb6c225fa8d2ef6c1c27506dda70d59ae2af050797f6ed71536a379423848570022223b04f0911ca3d987431d2b28ab4c019c8c74c31ece1fed3e037a
+  data.tar.gz: 51e9100f05269801e8fcbbe879405181ae0d3910e42593d5a9ad5933d6d8f3f45214cc8a8827d809b75e920029ccfd7584139c707e6a9e3fe0ec12ca750c4f77

data/exe/rfc-reader

@@ -4,4 +4,4 @@
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "rfc_reader"
 
-RfcReader::Command.start
+exit RfcReader.start

data/lib/rfc_reader/command.rb

@@ -4,10 +4,17 @@ require "thor"
 
 module RfcReader
   class Command < Thor
+    SUCCESS = 0
+    private_constant :SUCCESS
+
+    FAILURE = 1
+    private_constant :FAILURE
+
     # @return [Boolean]
     def self.exit_on_failure? = true
 
     # @param command [String, nil]
+    # @return [Integer] exit code
     def help(command = nil)
       unless command
         puts <<~DESCRIPTION
@@ -23,6 +30,8 @@ module RfcReader
       end
 
       super
+
+      SUCCESS
     end
 
     desc "search [TERM]", "Search for RFCs by TERM for reading"
@@ -33,12 +42,18 @@ module RfcReader
       it will get downloaded so that you can read it in your terminal.
     LONGDESC
     # @param term [String]
+    # @return [Integer] exit code
     def search(term)
       search_results = Search.search_by(term: term)
+      if search_results.empty?
+        warn "No search results for: #{term}"
+        return FAILURE
+      end
       title = Terminal.choose("Choose an RFC to read:", search_results.keys)
       url = search_results.fetch(title)
       content = Library.download_document(title: title, url: url)
       Terminal.page(content)
+      SUCCESS
     end
 
     desc "recent", "List recent RFC releases for reading"
@@ -48,12 +63,18 @@ module RfcReader
       Choose any RFC from the list that seems interesting and
       it will get downloaded so that you can read it in your terminal.
     LONGDESC
+    # @return [Integer] exit code
     def recent
       recent_results = Recent.list
+      if recent_results.empty?
+        warn "Error: Empty recent RFC list from rfc-editor.org RSS feed"
+        return FAILURE
+      end
       title = Terminal.choose("Choose an RFC to read:", recent_results.keys)
       url = recent_results.fetch(title)
       content = Library.download_document(title: title, url: url)
       Terminal.page(content)
+      SUCCESS
     end
 
     desc "library", "List already downloaded RFCs for reading"
@@ -63,18 +84,29 @@ module RfcReader
       Choose any RFC from the list that seems interesting and
       you can read it offline in your terminal.
     LONGDESC
+    # @return [Integer] exit code
     def library
       rfc_catalog = Library.catalog
+      if rfc_catalog.empty?
+        warn <<~MESSAGE
+          No RFCs are currently saved in the library. Try using the
+          `search` or `recent` commands to download some RFCs first.
+        MESSAGE
+        return FAILURE
+      end
       all_titles = rfc_catalog.map { _1[:title] }
       title = Terminal.choose("Choose an RFC to read:", all_titles)
       rfc = rfc_catalog.find { _1[:title] == title }
       content = Library.load_document(**rfc)
       Terminal.page(content)
+      SUCCESS
     end
 
     desc "version", "Print the program version"
+    # @return [Integer] exit code
     def version
       puts VERSION
+      SUCCESS
     end
   end
 end

data/lib/rfc_reader/error_context.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module RfcReader
+  module ErrorContext
+    class ContextError < StandardError
+      extend Forwardable
+
+      attr_reader :context
+
+      def_delegators :@cause, :message, :to_s, :backtrace, :backtrace_locations
+
+      # @param cause [StandardError]
+      # @param context [String] (Optional)
+      def initialize(cause:, context: nil)
+        @cause = cause
+        @context = context || default_context
+        super
+      end
+
+      def short_message
+        "Error: #{context}"
+      end
+
+      def full_message
+        <<~MESSAGE
+          Context:
+          #{indent(@context)}
+          Error:
+             #{@cause.class}
+          Message:
+          #{indent(message)}
+          Backtrace:
+          #{indent(backtrace)}
+        MESSAGE
+      end
+
+      private
+
+      def default_context
+        "#{@cause.class}: #{message.lines.first}"
+      end
+
+      def indent(string_or_array)
+        strings = case string_or_array
+                  when Array then string_or_array
+                  when String then string_or_array.lines
+                  else raise ArgumentError, "Expected string or array instead of #{string_or_array.class}"
+                  end
+
+        strings
+          .map { _1.prepend("   ") }
+          .join("\n")
+      end
+    end
+
+    # Yields an error context. Any `StandardError` that gets raised in this block
+    # gets wrapped by `ContextError` automatically and re-raised.
+    #
+    # If no error has been raised, it returns the result of the block.
+    #
+    # @param context [String]
+    # @return yielded block value
+    def self.wrap(context)
+      yield
+    rescue StandardError => e
+      raise ContextError.new(cause: e, context: context)
+    end
+
+    # Yields a handler context where any `StandardError` is caught and the error message is
+    # printed to stderr along with the context. It prints only a short message by default
+    # and prints the full error message if the `DEBUG` error message is set. It then exits
+    # with a non-zero error code.
+    #
+    # If no error has been raised, it returns the result of the block as an integer.
+    # If the result of block cannot be turned into an integer, it returns zero.
+    #
+    # @return [Integer] exit code
+    def self.handler
+      error = nil
+
+      begin
+        result = yield
+        return result.respond_to?(:to_i) ? result.to_i : 0
+      rescue ContextError => e
+        error = e
+      rescue StandardError => e
+        error = ContextError.new(cause: e)
+      end
+
+      if ENV["DEBUG"]
+        warn error.full_message
+      else
+        warn error.short_message
+        warn "Note: Set the `DEBUG` environment variable to see the full error context"
+      end
+
+      1
+    end
+  end
+end

data/lib/rfc_reader/library.rb

@@ -16,7 +16,10 @@ module RfcReader
       file_name = File.basename(url)
       file_path = File.join(library_cache_dir, file_name)
 
-      content = Net::HTTP.get(URI(url))
+      content = ErrorContext.wrap("Downloading RFC document") do
+        Net::HTTP.get(URI(url))
+      end
+
       FileUtils.mkdir_p(library_cache_dir)
       File.write(file_path, content)
       add_to_catalog(title: title, url: url, path: file_path)

data/lib/rfc_reader/recent.rb

@@ -16,7 +16,9 @@ module RfcReader
 
     # @return [String] the raw XML from the recent RFCs RSS feed
     def self.fetch
-      Net::HTTP.get(RECENT_RFCS_RSS_URI)
+      ErrorContext.wrap("Fetching the recent RFCs list") do
+        Net::HTTP.get(RECENT_RFCS_RSS_URI)
+      end
     end
 
     # Example: XML fragment we're trying to parse title and link data from.
@@ -36,18 +38,20 @@ module RfcReader
     # @param xml [String] the XML of the recent RFCs RSS endpoint
     # @return [Hash<String, String>] from RFC title to text file url
     def self.parse(xml)
-      Nokogiri::XML(xml).xpath("//item").to_h do |item|
-        item_hash = item.elements.to_h do |elem|
-          [elem.name, elem.text.strip]
-        end
+      ErrorContext.wrap("Parsing the recent RFCs list") do
+        Nokogiri::XML(xml).xpath("//item").to_h do |item|
+          item_hash = item.elements.to_h do |elem|
+            [elem.name, elem.text.strip]
+          end
 
-        # The link is to the webpage and not the plaintext document so we must convert it.
-        file_name = File.basename(item_hash.fetch("link"))
+          # The link is to the webpage and not the plaintext document so we must convert it.
+          file_name = File.basename(item_hash.fetch("link"))
 
-        [
-          item_hash.fetch("title"),
-          "https://www.rfc-editor.org/rfc/#{file_name}.txt",
-        ]
+          [
+            item_hash.fetch("title"),
+            "https://www.rfc-editor.org/rfc/#{file_name}.txt",
+          ]
+        end
       end
     end
   end

data/lib/rfc_reader/search.rb

@@ -18,7 +18,9 @@ module RfcReader
     # @param term [String]
     # @return [String] the raw HTML of the search results for the given term
     def self.fetch_by(term:)
-      Net::HTTP.post_form(RFC_SEARCH_URI, { combo_box: term }).body
+      ErrorContext.wrap("Fetching RFC search results") do
+        Net::HTTP.post_form(RFC_SEARCH_URI, { combo_box: term }).body
+      end
     end
 
     # Example: HTML fragment we're trying to parse title and link info from.
@@ -71,13 +73,23 @@ module RfcReader
     # @param html [String] the HTML of the search results
     # @return [Hash<String, String>] from RFC title to text file url
     def self.parse(html)
-      # NOTE: The first element in the table is just some general search information. See example HTML above.
-      Nokogiri::HTML(html).xpath("//div[@class='scrolltable']//table[@class='gridtable']//tr").drop(1).to_h do |tr_node|
-        td_nodes = tr_node.elements
-        title = td_nodes[2].text.strip
-        url = td_nodes[1].elements.map { _1.attribute("href").text.strip }.find { _1.end_with?(".txt") }
+      ErrorContext.wrap("Parsing RFC search results") do
+        # NOTE: The first element in the table is just some general search information. See example HTML above.
+        Nokogiri::HTML(html)
+          .xpath("//div[@class='scrolltable']//table[@class='gridtable']//tr")
+          .drop(1)
+          .to_h do |tr_node|
+            td_nodes = tr_node.elements
+            title = td_nodes[2]
+              .text
+              .strip
+            url = td_nodes[1]
+              .elements
+              .map { _1.attribute("href").text.strip }
+              .find { _1.end_with?(".txt") }
 
-        [title, url]
+            [title, url]
+          end
       end
     end
   end

data/lib/rfc_reader/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RfcReader
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
 end

data/lib/rfc_reader.rb

@@ -8,4 +8,12 @@ module RfcReader
   autoload :Search, "rfc_reader/search"
   autoload :Terminal, "rfc_reader/terminal"
   autoload :Library, "rfc_reader/library"
+  autoload :ErrorContext, "rfc_reader/error_context"
+
+  # @return [Integer] exit code
+  def self.start
+    ErrorContext.handler do
+      Command.start
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rfc-reader
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Kevin Robell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-24 00:00:00.000000000 Z
+date: 2024-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -77,6 +77,7 @@ files:
 - exe/rfc-reader
 - lib/rfc_reader.rb
 - lib/rfc_reader/command.rb
+- lib/rfc_reader/error_context.rb
 - lib/rfc_reader/library.rb
 - lib/rfc_reader/recent.rb
 - lib/rfc_reader/search.rb