reading 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecba33e4bbdb2dd11482113bf46d6196b17c89e2274e574b2286818f309c9ccb
-  data.tar.gz: 95d094b19fd4509e8608f5db414062e633ba6665c949526cd34c271314db6845
+  metadata.gz: e30d2e08f85d4ecb58352862165f63b62dbcbeb436103cf0761f318592359571
+  data.tar.gz: 7991e2a241345bd8f5b8fe268c462b721d610157d2c2652aec16882d3833c65f
 SHA512:
-  metadata.gz: ccfaace79d20ab57ab73349732735858049f217f3d0ad86408ae49b0f0f20591032dffd30e30d3f64d8c2644561d0b68e609e07398f3923fc85f4d25421504a6
-  data.tar.gz: 578c7f8389d12eda16a30f2d702a944a92dd931e62fa4db4908521ca1d1a01ca0fa0100d96b32f6e624fec1e7abf0f907417fc3043ce0aabe605fdde5b2c181c
+  metadata.gz: 1357b2ecd226209ff58e5fa7215ca073bfda99225a9d1623b111417d9bf01ecc9ec61406b2bde9fb3a26f1c7ce6a24e9495eb2bedca403a45d029d9e94e83c0e
+  data.tar.gz: 10285aa58757b8fa07e94945811a9195f6e5015e06ace666c963885b5a5eb19839bae855013a54a76fb4d2a038a9dd1fc53611b2ea0d28a4385073811064cb46

data/bin/reading

@@ -1,31 +1,116 @@
 #!/usr/bin/env ruby
 
-# A script that provides a quick way to see the output of a CSV string.
+# Starts the reading statistics interactive CLI, if a CSV file path arg is given.
+# If a CSV string is given instead, then parsing output (item hashes) is displayed.
 #
 # Usage:
 # Run on the command line:
-#   reading "<CSV string>" "<optional comma-separated names of enabled columns>"
+#   reading "<CSV file path or string>" "<optional comma-separated names of enabled columns>"
 #
 # Examples:
+#   reading /home/felipe/reading.csv
+#   reading /home/felipe/reading.csv 'head, sources'
 #   reading '3|📕Trying|Little Library 1970147288'
 #   reading '📕Trying|Little Library 1970147288' 'head, sources'
 
+require_relative '../lib/reading'
+require_relative '../lib/reading/stats/terminal_result_formatters'
+require 'debug'
+require 'amazing_print'
+require 'readline'
+require 'pastel'
 
-require_relative "../lib/reading"
-require "amazing_print"
-require "debug"
+EXIT_COMMANDS = %w[exit e quit q]
+PASTEL = Pastel.new
+GROUP_HEADING_FORMATTERS = [
+  -> { PASTEL.magenta.bold.underline(_1) },
+  -> { PASTEL.green.bold.underline(_1) },
+  -> { PASTEL.yellow.bold.underline(_1) },
+  -> { PASTEL.cyan.bold.underline(_1) },
+  -> { PASTEL.magenta.on_white(_1) },
+  -> { PASTEL.green.on_white(_1) },
+  -> { PASTEL.yellow.on_white(_1) },
+]
+
+# Recursively prints a hash of results (possibly grouped).
+# @param grouped_results [Hash, Array]
+# @param group_heading_formatters [Array<Proc>] a subset of GROUP_HEADING_FORMATTERS
+def print_grouped_results(grouped_results, group_heading_formatters)
+  indent_level = GROUP_HEADING_FORMATTERS.count - group_heading_formatters.count
+
+  if grouped_results.nil? || (grouped_results.respond_to?(:empty?) && grouped_results.empty?)
+    puts "  " * indent_level + PASTEL.bright_black("none") + "\n"
+    return
+  end
+
+  if grouped_results.is_a?(Hash) ||
+    (grouped_results.is_a?(Array) && grouped_results.first.length == 2)
+
+    grouped_results.each do |group_name, grouped|
+      puts "  " * indent_level + group_heading_formatters.first.call(group_name)
+      print_grouped_results(grouped, group_heading_formatters[1..])
+    end
+  elsif grouped_results.is_a?(Array)
+    numbered_results = grouped_results.map.with_index { |v, i| "#{i + 1}. #{v}" }
+
+    puts "  " * indent_level + numbered_results.join("\n" + "  " * indent_level) + "\n"
+  else
+    puts "  " * indent_level + grouped_results.to_s + "\n"
+  end
+end
 
 input = ARGV[0]
 unless input
-  raise ArgumentError, "CSV string argument required, such as '3|📕Trying|Little Library 1970147288'"
+  raise ArgumentError,
+    "Argument required, either a CSV file path or a CSV string.\nExamples:\n" \
+    "reading /home/felipe/reading.csv\n" \
+    "reading '3|📕Trying|Little Library 1970147288'"
 end
 
-config = {}
 if ARGV[1]
   enabled_columns = ARGV[1].split(",").map(&:strip).map(&:to_sym)
-  config = { enabled_columns: }
+  Reading::Config.build(enabled_columns:)
 end
 
-items = Reading.parse(stream: input, config:, hash_output: true)
+input_is_csv_path = input.end_with?('.csv')
+
+if input_is_csv_path
+  error_handler = ->(e) { puts "Skipped a row due to a parsing error: #{e}" }
+
+  items = Reading.parse(path: input, item_view: false, error_handler:)
 
-ap items
+  loop do
+    raw_input = Readline.readline(PASTEL.bright_cyan("> "), true)
+
+    exit if EXIT_COMMANDS.include?(raw_input)
+
+    input = raw_input.presence
+    next if raw_input.blank?
+
+    results = Reading.stats(
+      input:,
+      items:,
+      result_formatters: Reading::Stats::ResultFormatters::TERMINAL,
+    )
+
+    if results.is_a?(Array) && results.first.is_a?(Reading::Item) # `debug` operation
+      r = results
+      puts PASTEL.red.bold("Enter 'c' to leave the debugger.")
+      debugger
+    else
+      print_grouped_results(results, GROUP_HEADING_FORMATTERS)
+    end
+  rescue Reading::Error => e
+    puts e
+  end
+else # CSV string arg
+  input = input.gsub("\\|", "|") # because some pipes are escaped when pasting into the terminal
+
+  begin
+    item_hashes = Reading.parse(lines: input, hash_output: true, item_view: false)
+  rescue Reading::Error => e
+    puts "Skipped a row due to a parsing error: #{e}"
+  end
+
+  ap item_hashes
+end

data/lib/reading/config.rb

@@ -1,15 +1,26 @@
-require_relative "util/hash_deep_merge"
-require_relative "util/hash_array_deep_fetch"
-require_relative "errors"
+require_relative 'errors'
 
 module Reading
-  # Builds a hash config.
+  # Builds a singleton hash config.
   class Config
     using Util::HashDeepMerge
     using Util::HashArrayDeepFetch
 
     attr_reader :hash
 
+    # Builds an entire config hash from a custom config hash (which is typically
+    # not an entire config, but it can be, in which case a copy is returned).
+    # @param custom_config [Hash, Config]
+    # @return [Hash]
+    def self.build(custom_config = {})
+      @hash = new(custom_config).hash
+    end
+
+    # @return [Hash]
+    def self.hash
+      @hash ||= build
+    end
+
     # @param custom_config [Hash] a custom config which overrides the defaults,
     #   e.g. { enabled_columns: [:head, :end_dates] }
     def initialize(custom_config = {})
@@ -55,6 +66,16 @@ module Reading
         column_separator:         "|",
         ignored_characters:       "✅❌💲❓⏳",
         skip_compact_planned:     false,
+        pages_per_hour:           35,
+        length_group_boundaries:  [200, 400, 600, 1000, 2000],
+        speed: # e.g. listening speed for audiobooks and podcasts.
+          {
+            format:
+              {
+                audiobook: 1.0,
+                audio: 1.0,
+              },
+          },
         # The Head column is always enabled; the others can be disabled by
         # using a custom config that omits columns from this array.
         enabled_columns:
@@ -86,6 +107,7 @@ module Reading
           },
         source_names_from_urls:
           {
+            "audible.com"         => "Audible",
             "youtube.com"         => "YouTube",
             "youtu.be"            => "YouTube",
             "books.google.com"    => "Google Books",
@@ -157,7 +179,7 @@ module Reading
                       [{
                         dates: nil,
                         amount: 0,
-                        progress: nil,
+                        progress: 1.0,
                         name: nil,
                         favorite?: false,
                       }],

data/lib/reading/errors.rb

@@ -7,7 +7,7 @@ module Reading
   # Means there is something wrong with the user-supplied custom config.
   class ConfigError < Reading::Error; end
 
-  # Means unexpected input was encountered during parsing.
+  # Means unexpected input was encountered during CSV parsing.
   class ParsingError < Reading::Error; end
 
   # Means something in the Head column (author, title, etc.) is invalid.
@@ -21,4 +21,7 @@ module Reading
 
   # Means a date is unparsable, or a set of dates does not make logical sense.
   class InvalidDateError < Reading::Error; end
+
+  # Means a stats command was entered incorrectly.
+  class InputError < Reading::Error; end
 end

data/lib/reading/item/time_length.rb

@@ -1,7 +1,7 @@
 module Reading
   class Item
     # The length of an item when it is a time, as opposed to pages. (Pages are
-    # represented simply with an Integer.)
+    # represented simply with an Integer or Float.)
     class Item::TimeLength
       include Comparable
 
@@ -14,16 +14,32 @@ module Reading
 
       # Builds an Item::TimeLength from a string.
       # @param string [String] a time duration in "h:mm" format.
-      # @return [TimeLength]
+      # @return [TimeLength, nil]
       def self.parse(string)
+        return nil unless string.match? /\A\d+:\d\d\z/
+
         hours, minutes = string.split(':').map(&:to_i)
         new((hours * 60) + minutes)
       end
 
+      # Builds an Item::TimeLength based on a page count.
+      # @param pages [Integer, Float]
+      # @return [TimeLength]
+      def self.from_pages(pages)
+        new(pages_to_minutes(pages))
+      end
+
+      # Converts a page count to minutes.
+      # @param pages [Integer, Float]
+      # @return [Integer]
+      def self.pages_to_minutes(pages)
+        (pages.to_f / Config.hash.fetch(:pages_per_hour) * 60)
+      end
+
       # Only the hours, e.g. the "h" value in "h:mm".
       # @return [Numeric]
       def hours
-        value / 60
+        value.to_i / 60
       end
 
       # Only the hours, e.g. the "mm" value in "h:mm".
@@ -35,7 +51,13 @@ module Reading
       # A string in "h:mm" format.
       # @return [String]
       def to_s
-        "#{hours}:#{minutes}"
+        "#{hours}:#{minutes.round.to_s.rjust(2, '0')} or #{(value / 60.0 * Config.hash.fetch(:pages_per_hour)).round} pages"
+      end
+
+      # To pages.
+      # @return [Integer]
+      def to_i
+        ((value / 60.0) * Config.hash.fetch(:pages_per_hour)).to_i
       end
 
       # @return [Boolean]
@@ -43,6 +65,12 @@ module Reading
         value.zero?
       end
 
+      # A copy of self with a rounded @value.
+      # @return [TimeLength]
+      def round
+        self.class.new(@value.round)
+      end
+
       # Converts @value to an Integer if it's a whole number, and returns self.
       # @return [TimeLength]
       def to_i_if_whole!
@@ -62,27 +90,25 @@ module Reading
         self.class.new(@value.to_i)
       end
 
-      # TODO: addition with pages (nonzero Integer)
-      # @param other [TimeLength, Integer] must be zero if it's an Integer.
+      # @param other [TimeLength, Numeric]
       # @return [TimeLength]
       def +(other)
         if other.is_a? Item::TimeLength
           self.class.new(value + other.value)
-        elsif other.zero?
-          self
+        elsif other.is_a? Numeric
+          self.class.new(value + self.class.pages_to_minutes(other))
         else
           raise TypeError, "#{other.class} can't be added to Item::TimeLength."
         end
       end
 
-      # TODO: subtraction with pages (nonzero Integer)
-      # @param other [TimeLength, Integer] must be zero if it's an Integer.
+      # @param other [TimeLength, Numeric]
       # @return [TimeLength]
       def -(other)
         if other.is_a? Item::TimeLength
           self.class.new(value - other.value)
-        elsif other.zero?
-          self
+        elsif other.is_a? Numeric
+          self.class.new(value - self.class.pages_to_minutes(other))
         else
           raise TypeError, "#{other.class} can't be subtracted from Item::TimeLength."
         end
@@ -108,25 +134,23 @@ module Reading
         end
       end
 
-      # TODO: add coercion for pages (nonzero Integer)
-      # See https://www.mutuallyhuman.com/blog/class-coercion-in-ruby
-      # @param other [Integer] must be zero.
+      # See https://web.archive.org/web/20221206095821/https://www.mutuallyhuman.com/blog/class-coercion-in-ruby/
+      # @param other [Numeric]
       def coerce(other)
-        if other.zero?
-          [self.class.new(other), self]
+        if other.is_a? Numeric
+          [self.class.from_pages(other), self]
         else
-          raise TypeError, "TimeLength can't be coerced into #{other.class}."
+          raise TypeError, "#{other.class} can't be coerced into a TimeLength."
         end
       end
 
-      # TODO: add comparison to pages (nonzero Integer)
-      # @param other [TimeLength, Integer] if Integer, must be zero.
+      # @param other [TimeLength, Numeric]
+      # @return  [Integer]
       def <=>(other)
         return 1 if other.nil?
 
-        if other.zero?
-          return 0 if value.zero?
-          return 1
+        if other.is_a? Numeric
+          other = self.class.from_pages(other)
         end
 
         unless other.is_a? Item::TimeLength
@@ -135,6 +159,19 @@ module Reading
 
         value <=> other.value
       end
+
+      # Must be implemented for hash key equality checks.
+      # @param other [TimeLength, Numeric]
+      # @return [Boolean]
+      def eql?(other)
+        hash == other.hash
+      end
+
+      # Must be implemented along with #eql? for hash key equality checks.
+      # @return [Integer]
+      def hash
+        value
+      end
     end
   end
 end

data/lib/reading/item/view.rb

@@ -9,13 +9,12 @@ module Reading
         :isbn, :url, :experience_count, :groups, :blurb, :public_notes
 
       # @param item [Item] the Item from which to extract view information.
-      # @param config [Hash] an entire config.
-      def initialize(item, config)
+      def initialize(item)
         @genres = item.genres
-        @rating = extract_star_or_rating(item, config)
-        @isbn, @url, variant = extract_first_source_info(item, config)
-        @name = extract_name(item, variant, config)
-        @type_emoji = extract_type_emoji(variant&.format, config)
+        @rating = extract_star_or_rating(item)
+        @isbn, @url, variant = extract_first_source_info(item)
+        @name = extract_name(item, variant)
+        @type_emoji = extract_type_emoji(variant&.format)
         @date_or_status = extract_date_or_status(item)
         @experience_count = item.experiences.count
         @groups = item.experiences.map(&:group).compact
@@ -28,10 +27,9 @@ module Reading
       # A star (or nil if the item doesn't make the cut), or the number rating if
       # star ratings are disabled.
       # @param item [Item]
-      # @param config [Hash] an entire config.
       # @return [String, Integer, Float]
-      def extract_star_or_rating(item, config)
-        minimum_rating = config.deep_fetch(:item, :view, :minimum_rating_for_star)
+      def extract_star_or_rating(item)
+        minimum_rating = Config.hash.deep_fetch(:item, :view, :minimum_rating_for_star)
         if minimum_rating
           "⭐" if item.rating && item.rating >= minimum_rating
         else
@@ -44,13 +42,12 @@ module Reading
       # an ISBN/ASIN or URL. If an ISBN/ASIN is found first, it is used to build a
       # Goodreads URL. If a URL is found first, the ISBN/ASIN is nil.
       # @param item [Item]
-      # @param config [Hash] an entire config.
       # @return [Array(String, String, Symbol, Array<String>)]
-      def extract_first_source_info(item, config)
+      def extract_first_source_info(item)
         item.variants.map { |variant|
           isbn = variant.isbn
           if isbn
-            url = config.deep_fetch(:item, :view, :url_from_isbn).sub('%{isbn}', isbn)
+            url = Config.hash.deep_fetch(:item, :view, :url_from_isbn).sub('%{isbn}', isbn)
           else
             url = variant.sources.map { |source| source.url }.compact.first
           end
@@ -64,9 +61,8 @@ module Reading
       # The view name of the item.
       # @param item [Item]
       # @param variant [Data, nil] a variant from the Item.
-      # @param config [Hash] an entire config.
       # @return [String]
-      def extract_name(item, variant, config)
+      def extract_name(item, variant)
         author_and_title = "#{item.author + " – " if item.author}#{item.title}"
         return author_and_title if variant.nil?
 
@@ -79,7 +75,7 @@ module Reading
             end
           }
 
-          name_separator = config.deep_fetch(:item, :view, :name_separator)
+          name_separator = Config.hash.deep_fetch(:item, :view, :name_separator)
           series_and_extra_info = name_separator +
             (pretty_series + variant.extra_info).join(name_separator)
         end
@@ -89,10 +85,9 @@ module Reading
 
       # The emoji for the type that represents (encompasses) a given format.
       # @param format [Symbol, nil]
-      # @param config [Hash] an entire config.
       # @return [String]
-      def extract_type_emoji(format, config)
-        types = config.deep_fetch(:item, :view, :types)
+      def extract_type_emoji(format)
+        types = Config.hash.deep_fetch(:item, :view, :types)
 
         return types.deep_fetch(format, :emoji) if types.has_key?(format)
 
@@ -101,7 +96,7 @@ module Reading
           &.first # key
 
         types.deep_fetch(
-          type || config.deep_fetch(:item, :view, :default_type),
+          type || Config.hash.deep_fetch(:item, :view, :default_type),
           :emoji,
         )
       end