reading 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 531b4f54f11eed2f638079efbc0542977287d3ca887bea04a0785b6ca10c45fe
-  data.tar.gz: 58881344b75fc84041275d3ad9b84955f03d53ff8ca35f09932509b584c8b218
+  metadata.gz: e839c46251c307a65a234a9a374ad964f68d934d974005d6aa38cbb35e10f756
+  data.tar.gz: fa20c0b78f3fd1194495e1e604bb1d95b37e0334ac12c745d6508e026cd6fe97
 SHA512:
-  metadata.gz: 3539806e8c4472ba98d1ac19c862989a21d25782e4ec94ac04a3dfd4a3f30509187dce4ee6fa86fc189f742e19e2e649ffcf94f5e539cc1bc576856748b9adf6
-  data.tar.gz: 1be98e8aa5fc04a87aae46832cc981a49d3b725eeeaee2c6b75f1d723cf907d2e6567b9474022a5b19bc113db3555a7d358ec924c469f269d361b440d1963ca2
+  metadata.gz: 2bbca1450b2f6ae4c0d2b6d4cfeec495bf30b20639fcb3a5b121711e1d995a8b13a5ca64100d7a5e11d00d60c3808d61d25583510e3cd19902d412eca216154f
+  data.tar.gz: 74a676238941cdd5a0a7ecf8b2a4ed3c705883daadc25b3710a17eb9e325ec294d8b9fad71e653779af1ea9e01d0e8fed6423592dbe750b4f37c79f0f690387d

data/bin/reading

@@ -1,31 +1,101 @@
 #!/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 'debug'
+require_relative '../lib/reading'
+require_relative '../lib/reading/stats/terminal_result_formatters'
+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.empty?
+    puts "  " * indent_level + PASTEL.bright_black("none") + "\n"
+    return
+  elsif !grouped_results.is_a? Hash
+    puts "  " * indent_level + grouped_results.gsub("\n", "\n" + "  " * indent_level) + "\n"
+    return
+  end
+
+  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
+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. Examples:\n" \
+    "parsereading /home/felipe/reading.csv\n" \
+    "parsereading '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:)
+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,
+    )
+
+    print_grouped_results(results, GROUP_HEADING_FORMATTERS)
+  rescue Reading::Error => e
+    puts e
+  end
+else # CSV string arg
+  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",
@@ -94,61 +116,83 @@ module Reading
             "librivox.org"        => "LibriVox",
             "tv.apple.com"        => "Apple TV",
           },
-        # The structure of an item, along with default values.
-        # Wherever an array of hashes ends up with no data (i.e. equal to the
-        # value in the template), it is collapsed into an empty array.
-        # E.g. the row "|Dracula||🤝🏼book club" is parsed to a Struct analogous to:
-        # {
-        #   rating: nil,
-        #   author: nil,
-        #   title: "Dracula",
-        #   genres: [],
-        #   variants: [],
-        #   experiences: [{ spans: [], group: "book club", variant_index: 0 }],
-        #   notes: [],
-        # }
-        item_template:
+        item:
           {
-            rating: nil,
-            author: nil,
-            title: nil,
-            genres: [],
-            variants:
-              [{
-                format: nil,
-                series:
+            # After how many days of no activity an item of indefinite length
+            # (e.g. a podcast) should change its status from :in_progress to :done.
+            indefinite_in_progress_grace_period_days: 30,
+            view:
+              {
+                name_separator: " 〜 ",
+                url_from_isbn: "https://www.goodreads.com/book/isbn?isbn=%{isbn}",
+                # Items rated this or above get a star. If nil, number ratings are shown instead.
+                minimum_rating_for_star: 5,
+                types:
+                  {
+                    book: { emoji: "📕", from_formats: %i[print ebook audiobook pdf] },
+                    course: { emoji: "🏫", from_formats: %i[website] },
+                    piece: { emoji: "✏️" },
+                    video: { emoji: "🎞️" },
+                    audio: { emoji: "🎤" },
+                  },
+                default_type: :book,
+              },
+            # The structure of an item, along with default values.
+            # Wherever an array of hashes ends up with no data (i.e. equal to the
+            # value in the template), it is collapsed into an empty array.
+            # E.g. the row "|Dracula||🤝🏼book club" is parsed to an Item analogous to:
+            # {
+            #   rating: nil,
+            #   author: nil,
+            #   title: "Dracula",
+            #   genres: [],
+            #   variants: [],
+            #   experiences: [{ spans: [], group: "book club", variant_index: 0 }],
+            #   notes: [],
+            # }
+            template:
+              {
+                rating: nil,
+                author: nil,
+                title: nil,
+                genres: [],
+                variants:
                   [{
-                    name: nil,
-                    volume: nil,
+                    format: nil,
+                    series:
+                      [{
+                        name: nil,
+                        volume: nil,
+                      }],
+                    sources:
+                      [{
+                        name: nil,
+                        url: nil,
+                      }],
+                    isbn: nil,
+                    length: nil,
+                    extra_info: [],
                   }],
-                sources:
+                experiences:
                   [{
-                    name: nil,
-                    url: nil,
+                    spans:
+                      [{
+                        dates: nil,
+                        progress: 1.0,
+                        amount: 0,
+                        name: nil,
+                        favorite?: false,
+                      }],
+                    group: nil,
+                    variant_index: 0,
                   }],
-                isbn: nil,
-                length: nil,
-                extra_info: [],
-              }],
-            experiences:
-              [{
-                spans:
+                notes:
                   [{
-                    dates: nil,
-                    amount: 0,
-                    progress: nil,
-                    name: nil,
-                    favorite?: false,
+                    blurb?: false,
+                    private?: false,
+                    content: nil,
                   }],
-                group: nil,
-                variant_index: 0,
-              }],
-            notes:
-              [{
-                blurb?: false,
-                private?: false,
-                content: nil,
-              }],
+              },
           },
       }
     end

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/filter.rb

@@ -0,0 +1,95 @@
+module Reading
+  # Filters Items based on given criteria.
+  class Filter
+    class << self
+      # Filters Items based on given criteria, and returns them sorted by last
+      # end date or (where there is none) status, where :planned Items are
+      # placed last, and :in_progress just before those.
+      # @param items [Array<Item>]
+      # @param no_sort [Boolean] to preserve the original ordering of the Items.
+      # @param criteria [Hash] one or more of the filters defined in by_x methods below.
+      # @return [Array<Item>]
+      # @raise [ArgumentError] if criteria are invalid or missing.
+      def by(items:, no_sort: false, **criteria)
+        validate_criteria(**criteria)
+
+        filtered = criteria.each.with_object(items.dup) { |(criterion, arg), filtered_items|
+          send("#{CRITERIA_PREFIX}#{criterion}#{CRITERIA_SUFFIX}", filtered_items, arg)
+        }
+
+        return filtered if no_sort
+
+        filtered.sort_by { |item|
+          if item.done?
+            item.last_end_date.strftime("%Y-%m-%d")
+          else
+            item.status.to_s
+          end
+        }
+      end
+
+      private
+
+      CRITERIA_PREFIX = "by_".freeze
+      CRITERIA_SUFFIX = "!".freeze
+
+      # Checks that the args match real Filter criteria.
+      # @param criteria [Hash] must include only one or more of the criteria
+      #   defined in by_x methods below.
+      # @raise [ArgumentError] if criteria are empty or invalid.
+      def validate_criteria(**criteria)
+        available_criteria = private_methods(false)
+          .select { _1.to_s.start_with?(CRITERIA_PREFIX) }
+          .map { _1.to_s.delete_prefix(CRITERIA_PREFIX).delete_suffix(CRITERIA_SUFFIX).to_sym }
+
+        if criteria.empty?
+          raise ArgumentError, "Filter requires at least one of these criteria: #{available_criteria}"
+        end
+
+        unrecognized_criteria = criteria.keys - available_criteria
+        if unrecognized_criteria.any?
+          raise ArgumentError, "Unrecognized criteria passed to Filter: #{unrecognized_criteria}"
+        end
+      end
+
+      # Mutates the given array of Items to select only Items with a rating
+      # greater than or equal to the given minimum.
+      # @param items [Array<Item>]
+      # @param minimum_rating [Integer]
+      def by_minimum_rating!(items, minimum_rating)
+        return items unless minimum_rating
+
+        items.select! do |item|
+          if item.rating
+            item.rating >= minimum_rating
+          end
+        end
+      end
+
+      # Mutates the given array of Items to exclude Items with genres including
+      # any of the given genres.
+      # @param items [Array<Item>]
+      # @param excluded_genres [Array<String>]
+      def by_excluded_genres!(items, excluded_genres)
+        return items unless excluded_genres&.any?
+
+        items.select! do |item|
+          overlapping = item.genres & excluded_genres
+          overlapping.empty?
+        end
+      end
+
+      # Mutates the given array of Items to select only Items with a status
+      # equal to the given status (or one of the given statuses).
+      # @param items [Array<Item>]
+      # @param statuses [Symbol, Array<Symbol>]
+      def by_status!(items, statuses)
+        statuses = Array(statuses)
+
+        items.select! do |item|
+          statuses.include? item.status
+        end
+      end
+    end
+  end
+end

data/lib/reading/item/time_length.rb

@@ -1,7 +1,8 @@
 module Reading
-  module Item
-    # For coercion, see https://www.mutuallyhuman.com/blog/class-coercion-in-ruby/
-    class TimeLength
+  class Item
+    # The length of an item when it is a time, as opposed to pages. (Pages are
+    # represented simply with an Integer or Float.)
+    class Item::TimeLength
       include Comparable
 
       attr_reader :value # in total minutes
@@ -11,18 +12,34 @@ module Reading
         @value = value
       end
 
-      # Builds a TimeLength from a string.
+      # 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".
@@ -34,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]
@@ -42,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!
@@ -61,29 +90,27 @@ 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? TimeLength
+        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 TimeLength."
+          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? TimeLength
+        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 TimeLength."
+          raise TypeError, "#{other.class} can't be subtracted from Item::TimeLength."
         end
       end
 
@@ -107,32 +134,44 @@ module Reading
         end
       end
 
-      # TODO: add coercion for pages (nonzero Integer)
-      # @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? TimeLength
+        unless other.is_a? Item::TimeLength
           raise TypeError, "TimeLength can't be compared to #{other.class} #{other}."
         end
 
         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