rfc-reader 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b42f53e0145a5153d21e1f555c006e2081c43c126b60c581f5687567530f00b
+  data.tar.gz: cb3d545f31ebba48757242e003e9f3ef2d9960c1a6277256cfc6dfcc389af38c
+SHA512:
+  metadata.gz: 3337413fc3634c92bf8ec4ff3f347749de4b4cff385e6b29184fa63a641e8456f9cfd21142e07d125b09e320aa38bbab57e90c7f64cc2f75d516c7fa3307d81a
+  data.tar.gz: 557038fda98a3ea623ea128cd99aa4423ff2befb1493f4f0e7313807a60273bf2c14007df1d818b90ce5e33bdd6de08a8d5814e69227104ede1eaa21cb4349e8

data/exe/rfc-reader

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "rfc_reader"
+
+RfcReader::Command.start

data/lib/rfc_reader/command.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module RfcReader
+  class Command < Thor
+    # @return [Boolean]
+    def self.exit_on_failure? = true
+
+    # @param command [String, nil]
+    def help(command = nil)
+      unless command
+        puts <<~DESCRIPTION
+          >>> rfc-reader
+
+          This command downloads the plaintext version of RFCs from
+          rfc-editor.org so that they can be read at the command line.
+
+          The last 100 downloaded RFCs are saved locally so that they can be
+          read later on without the need for an internet connection.
+
+        DESCRIPTION
+      end
+
+      super
+    end
+
+    desc "search [TERM]", "Search for RFCs by TERM for reading"
+    long_desc <<-LONGDESC
+      Search for RFCs on rfc-editor.org by the given term and list them.
+
+      Choose any RFC from the list that seems interesting and
+      it will get downloaded so that you can read it in your terminal.
+    LONGDESC
+    # @param term [String]
+    def search(term)
+      search_results = Search.search_by(term: term)
+      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)
+    end
+
+    desc "recent", "List recent RFC releases for reading"
+    long_desc <<-LONGDESC
+      Fetch the most recent 15 RFCs on rfc-editor.org and list them.
+
+      Choose any RFC from the list that seems interesting and
+      it will get downloaded so that you can read it in your terminal.
+    LONGDESC
+    def recent
+      recent_results = Recent.list
+      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)
+    end
+
+    desc "library", "List already downloaded RFCs for reading"
+    long_desc <<-LONGDESC
+      List the last 100 RFCs that have already been downloaded.
+
+      Choose any RFC from the list that seems interesting and
+      you can read it offline in your terminal.
+    LONGDESC
+    def library
+      rfc_catalog = Library.catalog
+      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)
+    end
+
+    desc "version", "Print the program version"
+    def version
+      puts VERSION
+    end
+  end
+end

data/lib/rfc_reader/library.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "net/http"
+
+module RfcReader
+  module Library
+    MAX_DOCUMENT_COUNT = 100
+    private_constant :MAX_DOCUMENT_COUNT
+
+    # @param title [String] the RFC title
+    # @param url [String] the text file URL for the RFC
+    # @return [String] the RFC content
+    def self.download_document(title:, url:)
+      file_name = File.basename(url)
+      file_path = File.join(library_cache_dir, file_name)
+
+      content = Net::HTTP.get(URI(url))
+      FileUtils.mkdir_p(library_cache_dir)
+      File.write(file_path, content)
+      add_to_catalog(title: title, url: url, path: file_path)
+
+      content
+    end
+
+    # @param title [String] the RFC title
+    # @param url [String] the text file URL for the RFC
+    # @param path [String] the path to the local copy of the RFC
+    # @return [String] the RFC content
+    def self.load_document(title:, url:, path:)
+      content = File.read(path)
+
+      add_to_catalog(title: title, url: url, path: path)
+
+      content
+    end
+
+    # These are referenced later on by the `rfc-reader library` command.
+    #
+    # @example
+    #   [
+    #     { title: "My RFC", url: "www.my-rfc.com/my-rfc.txt", path: ".cache/rfc-reader/library/my-rfc.txt" },
+    #     ...
+    #   ]
+    # @return [Array<Hash<String, String>>] a list of RFC info hashes
+    def self.catalog
+      if File.exist?(library_cache_list_path)
+        content = File.read(library_cache_list_path)
+        JSON.parse(content, symbolize_names: true)
+      else
+        []
+      end
+    end
+
+    # Adds the RFC to the beginning of the catalog and removes any existing entries.
+    # These are referenced later on by the `rfc-reader library` command.
+    #
+    # @param title [String] the RFC title
+    # @param url [String] the text file URL for the RFC
+    # @param path [String] the path to the local copy of the RFC
+    def self.add_to_catalog(title:, url:, path:)
+      list = catalog.reject do |rfc|
+        title == rfc[:title] ||
+          url == rfc[:url] ||
+          path == rfc[:path]
+      end
+
+      rfc = {
+        title: title,
+        url: url,
+        path: path,
+      }
+
+      list = [rfc, *list]
+      while list.size > MAX_DOCUMENT_COUNT
+        path = list.pop[:path]
+        FileUtils.rm_f(path) if path.start_with?(library_cache_dir)
+      end
+
+      json = JSON.pretty_generate(list)
+      FileUtils.mkdir_p(program_cache_dir)
+      File.write(library_cache_list_path, json)
+    end
+
+    # Cache directories
+
+    # @return [String]
+    def self.xdg_cache_home
+      ENV
+        .fetch("XDG_CACHE_HOME") { File.join(Dir.home, ".cache") }
+        .then { |path| File.expand_path(path) }
+    end
+
+    # @return [String]
+    def self.program_cache_dir
+      File.join(xdg_cache_home, "rfc_reader")
+    end
+
+    # @return [String]
+    def self.library_cache_list_path
+      File.join(program_cache_dir, "library_list.json")
+    end
+
+    # @return [String]
+    def self.library_cache_dir
+      File.join(program_cache_dir, "library")
+    end
+  end
+end

data/lib/rfc_reader/recent.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "nokogiri"
+
+module RfcReader
+  module Recent
+    RECENT_RFCS_RSS_URI = URI("https://www.rfc-editor.org/rfcrss.xml").freeze
+    private_constant :RECENT_RFCS_RSS_URI
+
+    # @return [Hash<String, String>] from RFC title to text file url
+    def self.list
+      xml = fetch
+      parse(xml)
+    end
+
+    # @return [String] the raw XML from the recent RFCs RSS feed
+    def self.fetch
+      Net::HTTP.get(RECENT_RFCS_RSS_URI)
+    end
+
+    # Example: XML fragment we're trying to parse title and link data from.
+    #
+    # ```xml
+    # <item>
+    #   <title>
+    #   RFC 9624: EVPN Broadcast, Unknown Unicast, or Multicast (BUM) Using Bit Index Explicit Replication (BIER)
+    #   </title>
+    #   <link>https://www.rfc-editor.org/info/rfc9624</link>
+    #   <description>
+    #   This document specifies protocols and procedures for forwarding Broadcast, Unknown Unicast, or Multicast (BUM) traffic of Ethernet VPNs (EVPNs) using Bit Index Explicit Replication (BIER).
+    #   </description>
+    # </item>
+    # ```
+    #
+    # @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
+
+        # 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",
+        ]
+      end
+    end
+  end
+end

data/lib/rfc_reader/search.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "nokogiri"
+
+module RfcReader
+  module Search
+    RFC_SEARCH_URI = URI("https://www.rfc-editor.org/search/rfc_search_detail.php").freeze
+    private_constant :RFC_SEARCH_URI
+
+    # @param term [String]
+    # @return [Hash<String, String>] from RFC title to text file url
+    def self.search_by(term:)
+      html = fetch_by(term: term)
+      parse(html)
+    end
+
+    # @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
+    end
+
+    # Example: HTML fragment we're trying to parse title and link info from.
+    #
+    # ```html
+    # <div class="scrolltable">
+    #   <table class='gridtable'>
+    #       <tr>
+    #           <th>
+    #               <a href='rfc_search_detail.php?sortkey=Number&sorting=DESC&page=25&title=ftp&pubstatus[]=Any&pub_date_type=any'>Number</a>
+    #           </th>
+    #           <th>Files</th>
+    #           <th>Title</th>
+    #           <th>Authors</th>
+    #           <th>
+    #               <a href='rfc_search_detail.php?sortkey=Date&sorting=DESC&page=25&title=ftp&pubstatus[]=Any&pub_date_type=any'>Date</a>
+    #           </th>
+    #           <th>More Info</th>
+    #           <th>Status</th>
+    #       </tr>
+    #       <tr>
+    #           <td>
+    #               <a href="https://www.rfc-editor.org/info/rfc114" target="_blank">RFC&nbsp;114</a>
+    #           </td>
+    #           <td>
+    #               <a href="https://www.rfc-editor.org/rfc/rfc114.txt" target="_blank">ASCII</a>
+    #               ,
+    #               <a href="https://www.rfc-editor.org/pdfrfc/rfc114.txt.pdf" target="_blank">PDF</a>
+    #               ,
+    #               <a href="https://www.rfc-editor.org/rfc/rfc114.html" target="_blank">HTML</a>
+    #           </td>
+    #           <td class="title"> File Transfer Protocol </td>
+    #           <td> A.K. Bhushan</td>
+    #           <td>April 1971</td>
+    #           <td>
+    #               Updated by
+    #               <a href="https://www.rfc-editor.org/info/rfc133" target="_blank">RFC&nbsp;133</a>
+    #               ,
+    #               <a href="https://www.rfc-editor.org/info/rfc141" target="_blank">RFC&nbsp;141</a>
+    #               ,
+    #               <a href="https://www.rfc-editor.org/info/rfc171" target="_blank">RFC&nbsp;171</a>
+    #               ,
+    #               <a href="https://www.rfc-editor.org/info/rfc172" target="_blank">RFC&nbsp;172</a>
+    #           </td>
+    #           <td>Unknown</td>
+    #       </tr>
+    # ...
+    # ```
+    #
+    # @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") }
+
+        [title, url]
+      end
+    end
+  end
+end

data/lib/rfc_reader/terminal.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RfcReader
+  module Terminal
+    # @param content [String]
+    def self.page(content)
+      require "tty-pager"
+      TTY::Pager.page(content)
+    end
+
+    # @param prompt [String]
+    # @param choices [Array<String>] where all choices are unique
+    def self.choose(prompt, choices)
+      require "tty-prompt"
+      TTY::Prompt
+        .new(
+          quiet: true,
+          track_history: false,
+          interrupt: :exit,
+          symbols: { marker: ">" },
+          enable_color: !ENV["NO_COLOR"]
+        )
+        .select(prompt, choices)
+    end
+  end
+end

data/lib/rfc_reader/version.rb

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

data/lib/rfc_reader.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "rfc_reader/version"
+
+module RfcReader
+  autoload :Command, "rfc_reader/command"
+  autoload :Recent, "rfc_reader/recent"
+  autoload :Search, "rfc_reader/search"
+  autoload :Terminal, "rfc_reader/terminal"
+  autoload :Library, "rfc_reader/library"
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: rfc-reader
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kevin Robell
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-09-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: tty-pager
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+description:
+email:
+- apainintheneck@gmail.com
+executables:
+- rfc-reader
+extensions: []
+extra_rdoc_files: []
+files:
+- exe/rfc-reader
+- lib/rfc_reader.rb
+- lib/rfc_reader/command.rb
+- lib/rfc_reader/library.rb
+- lib/rfc_reader/recent.rb
+- lib/rfc_reader/search.rb
+- lib/rfc_reader/terminal.rb
+- lib/rfc_reader/version.rb
+homepage: https://github.com/apainintheneck/rfc-reader/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/apainintheneck/rfc-reader/
+  source_code_uri: https://github.com/apainintheneck/rfc-reader/
+  changelog_uri: https://github.com/apainintheneck/rfc-reader/blob/main/CHANELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.6
+signing_key:
+specification_version: 4
+summary: Search for and read RFCs at the command line.
+test_files: []