reading 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4145847e60a6045a1381afe207be44d30636ca7b058d4c1c1e0db70009af0b4
-  data.tar.gz: 833b042be4b575e4ed166d0269610504c031d03460a0f75c4dedc214b1eaf152
+  metadata.gz: ecba33e4bbdb2dd11482113bf46d6196b17c89e2274e574b2286818f309c9ccb
+  data.tar.gz: 95d094b19fd4509e8608f5db414062e633ba6665c949526cd34c271314db6845
 SHA512:
-  metadata.gz: '09f08e0be8d6cd97481097d4193209af3cda404e076f2d5529c7c4bdee5f146afbf980a2cb05f2435c06633b89954067ee8bea9d02dae4eddd924f86626a9f63'
-  data.tar.gz: 3a50b075c63f2a8b0082b309bef201a8351344c729e90b18482b5796a53bedee1af7fad71af3a0dd884d1245440cfd14dbf6d28aa38bdf5d09717059bd22e7f8
+  metadata.gz: ccfaace79d20ab57ab73349732735858049f217f3d0ad86408ae49b0f0f20591032dffd30e30d3f64d8c2644561d0b68e609e07398f3923fc85f4d25421504a6
+  data.tar.gz: 578c7f8389d12eda16a30f2d702a944a92dd931e62fa4db4908521ca1d1a01ca0fa0100d96b32f6e624fec1e7abf0f907417fc3043ce0aabe605fdde5b2c181c

data/bin/reading

@@ -4,15 +4,16 @@
 #
 # Usage:
 # Run on the command line:
-#   reading "<CSV string>" "<optional comma-separated names of enabled columns>`
+#   reading "<CSV string>" "<optional comma-separated names of enabled columns>"
 #
 # Examples:
 #   reading '3|📕Trying|Little Library 1970147288'
 #   reading '📕Trying|Little Library 1970147288' 'head, sources'
 
 
-require_relative "../lib/reading/csv"
+require_relative "../lib/reading"
 require "amazing_print"
+require "debug"
 
 input = ARGV[0]
 unless input
@@ -22,10 +23,9 @@ end
 config = {}
 if ARGV[1]
   enabled_columns = ARGV[1].split(",").map(&:strip).map(&:to_sym)
-  config[:csv] = { enabled_columns: }
+  config = { enabled_columns: }
 end
 
-csv = Reading::CSV.new(input, config:)
-items = csv.parse
+items = Reading.parse(stream: input, config:, hash_output: true)
 
 ap items

data/bin/readingfile

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+# A script that provides a quick way to see the output of a CSV file.
+#
+# Usage:
+# Run on the command line:
+#   reading "<file path>" "<optional comma-separated names of enabled columns>"
+#
+# Examples:
+#   reading '/home/felipe/reading.csv'
+#   reading '/home/felipe/reading.csv' 'head, sources'
+
+
+require_relative "../lib/reading"
+require "amazing_print"
+require "debug"
+
+path = ARGV[0]
+unless path
+  raise ArgumentError, "CSV path argument required, such as '/home/felipe/reading.csv'"
+end
+
+config = {}
+if ARGV[1]
+  enabled_columns = ARGV[1].split(",").map(&:strip).map(&:to_sym)
+  config = { enabled_columns: }
+end
+
+items = Reading.parse(path, config:, hash_output: true)
+
+ap items

data/lib/reading/config.rb

@@ -1,3 +1,7 @@
+require_relative "util/hash_deep_merge"
+require_relative "util/hash_array_deep_fetch"
+require_relative "errors"
+
 module Reading
   # Builds a hash config.
   class Config
@@ -7,7 +11,7 @@ module Reading
     attr_reader :hash
 
     # @param custom_config [Hash] a custom config which overrides the defaults,
-    #   e.g. { errors: { styling: :html } }
+    #   e.g. { enabled_columns: [:head, :end_dates] }
     def initialize(custom_config = {})
       @custom_config = custom_config
 
@@ -21,61 +25,109 @@ module Reading
     def build_hash
       @hash = default_config.deep_merge(@custom_config)
 
-      # If custom formats are given, use only the custom formats. #dig is used here
-      # (not #deep_fetch as most elsewhere) because custom_config may not include this data.
-      if @custom_config[:item] && @custom_config.dig(:item, :formats)
-        @hash[:item][:formats] = @custom_config.dig(:item, :formats)
+      # If custom formats are given, use only the custom formats.
+      if @custom_config.has_key?(:formats)
+        @hash[:formats] = @custom_config[:formats]
+      end
+
+      # Ensure enabled_columns includes :head, and sort them.
+      enabled_columns =
+        (@hash.fetch(:enabled_columns) + [:head])
+        .uniq
+        .sort_by { |col| default_config[:enabled_columns].index(col) || 0 }
+
+      invalid_columns = enabled_columns - default_config[:enabled_columns]
+      if invalid_columns.any?
+        raise ConfigError, "Invalid columns in custom config: #{invalid_columns.join(", ")}"
       end
 
-      # Validate enabled_columns
-      enabled_columns = @hash.deep_fetch(:csv, :enabled_columns)
-      enabled_columns << :head
-      enabled_columns.uniq!
-      enabled_columns.sort_by! { |col| default_config.deep_fetch(:csv, :enabled_columns).index(col) }
+      @hash[:enabled_columns] = enabled_columns
 
-      # Add the Regex config, which is built based on the config so far.
-      @hash[:csv][:regex] = build_regex_config
+      # Add the regex config, which is built based on the config so far.
+      @hash[:regex] = regex_config
     end
 
     # The default config, excluding Regex config (see further down).
     # @return [Hash]
     def default_config
       {
-        errors:
+        comment_character:        "\\",
+        column_separator:         "|",
+        ignored_characters:       "✅❌💲❓⏳",
+        skip_compact_planned:     false,
+        # The Head column is always enabled; the others can be disabled by
+        # using a custom config that omits columns from this array.
+        enabled_columns:
+          %i[
+            rating
+            head
+            sources
+            start_dates
+            end_dates
+            genres
+            length
+            notes
+            history
+          ],
+        # If your custom config includes formats, they will replace the defaults
+        # (unlike the rest of the config, to which custom config is deep merged).
+        # So if you want to keep any of these defaults, include them in your config.
+        formats:
+          {
+            print:     "📕",
+            ebook:     "⚡",
+            audiobook: "🔊",
+            pdf:       "📄",
+            audio:     "🎤",
+            video:     "🎞️",
+            course:    "🏫",
+            piece:     "✏️",
+            website:   "🌐",
+          },
+        source_names_from_urls:
           {
-            handle_error:     -> (error) { puts error },
-            max_length:       100, # or require "io/console", then IO.console.winsize[1]
-            catch_all_errors: false, # set this to false during development.
-            styling:          :terminal, # or :html
+            "youtube.com"         => "YouTube",
+            "youtu.be"            => "YouTube",
+            "books.google.com"    => "Google Books",
+            "archive.org"         => "Internet Archive",
+            "thegreatcourses.com" => "The Great Courses",
+            "librivox.org"        => "LibriVox",
+            "tv.apple.com"        => "Apple TV",
           },
         item:
           {
-            formats:
+            # 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:
               {
-                print:     "📕",
-                ebook:     "⚡",
-                audiobook: "🔊",
-                pdf:       "📄",
-                audio:     "🎤",
-                video:     "🎞️",
-                course:    "🏫",
-                piece:     "✏️",
-                website:   "🌐",
-              },
-            sources:
-              {
-                names_from_urls:
+                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:
                   {
-                    "youtube.com"         => "YouTube",
-                    "youtu.be"            => "YouTube",
-                    "books.google.com"    => "Google Books",
-                    "archive.org"         => "Internet Archive",
-                    "thegreatcourses.com" => "The Great Courses",
-                    "librivox.org"        => "LibriVox",
-                    "tv.apple.com"        => "Apple TV",
+                    book: { emoji: "📕", from_formats: %i[print ebook audiobook pdf] },
+                    course: { emoji: "🏫", from_formats: %i[website] },
+                    piece: { emoji: "✏️" },
+                    video: { emoji: "🎞️" },
+                    audio: { emoji: "🎤" },
                   },
-                default_name_for_url: "site",
+                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,
@@ -104,7 +156,7 @@ module Reading
                     spans:
                       [{
                         dates: nil,
-                        amount: nil,
+                        amount: 0,
                         progress: nil,
                         name: nil,
                         favorite?: false,
@@ -120,83 +172,19 @@ module Reading
                   }],
               },
           },
-        csv:
-          {
-            # The Head column is always enabled; the others can be disabled by
-            # using a custom config that omits columns from this array.
-            enabled_columns:
-              %i[
-                rating
-                head
-                sources
-                dates_started
-                dates_finished
-                genres
-                length
-                notes
-                history
-              ],
-            # Custom columns are listed in a hash with default values, like simple columns in item[:template] above.
-            custom_numeric_columns:   {}, # e.g. { family_friendliness: 5, surprise_factor: nil }
-            custom_text_columns:      {}, # e.g. { mood: nil, rec_by: nil, will_reread: "no" }
-            comment_character:        "\\",
-            column_separator:         "|",
-            separator:                ",",
-            short_separator:          " - ",
-            long_separator:           " -- ",
-            date_separator:           "/",
-            date_range_separator:     "..",
-            dnf_string:               "DNF",
-            series_prefix:            "in",
-            group_emoji:              "🤝🏼",
-            blurb_emoji:              "💬",
-            private_emoji:            "🔒",
-            compact_planned_source_prefix: "@",
-            compact_planned_ignored_chars: "✅💲❓⏳⭐",
-            skip_compact_planned:     false,
-          },
       }
     end
 
-    # Builds the Regex portion of the config, based on the given config.
+    # Builds the regex portion of the config, based on the config so far.
     # @return [Hash]
-    def build_regex_config
-      return @hash[:csv][:regex] if @hash.dig(:csv, :regex)
-
-      comment_character = Regexp.escape(@hash.deep_fetch(:csv, :comment_character))
-      formats = @hash.deep_fetch(:item, :formats).values.join("|")
-      dnf_string = Regexp.escape(@hash.deep_fetch(:csv, :dnf_string))
-      compact_planned_ignored_chars = (
-        @hash.deep_fetch(:csv, :compact_planned_ignored_chars).chars - [" "]
-      ).join("|")
-      time_length = /(?<time>\d+:\d\d)/
-      pages_length = /p?(?<pages>\d+)p?/
-      url = /https?:\/\/[^\s#{@hash.deep_fetch(:csv, :separator)}]+/
-      date_sep = @hash.deep_fetch(:csv, :date_separator)
+    def regex_config
+      return @hash[:regex] if @hash.has_key?(:regex)
 
-      isbn_lookbehind = "(?<=\\A|\\s|#{@hash.deep_fetch(:csv, :separator)})"
-      isbn_lookahead = "(?=\\z|\\s|#{@hash.deep_fetch(:csv, :separator)})"
-      isbn_bare_regex = /(?:\d{3}[-\s]?)?[A-Z\d]{10}/ # also includes ASIN
-      isbn = /#{isbn_lookbehind}#{isbn_bare_regex.source}#{isbn_lookahead}/
+      formats = @hash.fetch(:formats).values.join("|")
 
       {
-        compact_planned_row_start: /\A\s*#{comment_character}\s*(?:(?<genres>[^a-z@:\|]+)?\s*(?<sources>@[^\|]+)?\s*:)?\s*(?=#{formats})/,
-        compact_planned_item: /\A(?<format_emoji>(?:#{formats}))(?<author_title>[^@\|]+)(?<sources>@.+)?(?:\|(?<sources_column>.+))?\z/,
         formats: /#{formats}/,
         formats_split: /\s*(?:,|--)?\s*(?=#{formats})/,
-        compact_planned_ignored_chars: /#{compact_planned_ignored_chars}/,
-        series_volume: /,\s*#(\d+)\z/,
-        isbn: isbn,
-        url: url,
-        dnf: /\A\s*(#{dnf_string})/,
-        progress: /(?<=#{dnf_string}|\A)\s*(?:(?<percent>\d?\d)%|#{time_length}|#{pages_length})\s+/,
-        group_experience: /#{@hash.deep_fetch(:csv, :group_emoji)}\s*(.*)\s*\z/,
-        variant_index: /\s+v(\d+)/,
-        date: /\d{4}#{date_sep}\d?\d#{date_sep}\d?\d/,
-        time_length: /\A#{time_length}(?<each>\s+each)?\z/,
-        time_length_in_variant: time_length,
-        pages_length: /\A#{pages_length}(?<each>\s+each)?\z/,
-        pages_length_in_variant: /(?:\A|\s+|p)(?<pages>\d{1,9})(?:p|\s+|\z)/, # to exclude ISBN-10 and ISBN-13
       }
     end
   end

data/lib/reading/errors.rb

@@ -1,80 +1,24 @@
-require "pastel"
-
 module Reading
-  # The base error class, which provides flexible error handling.
-  class Error < StandardError
-    using Util::StringTruncate
-
-    # Handles this error based on config settings, and augments the error message
-    # with styling and the line from the file. All this is handled here so that
-    # the parser doesn't have to know all these things at the error's point of origin.
-    # @param line [Reading::Line] the CSV line, through which the CSV config and
-    #   line string are accessed.
-    def handle(line:)
-      errors_config = line.csv.config.fetch(:errors)
-      styled_error = styled_with_line(line.string, errors_config)
-
-      handle = errors_config.fetch(:handle_error)
-      handle.call(styled_error)
-    end
-
-    protected
-
-    # Can be overridden in subclasses, e.g. yellow for a warning.
-    def color
-      :red
-    end
-
-    # Creates a new error having a message augmented with styling and the line string.
-    # @return [AppError]
-    def styled_with_line(line_string, errors_config)
-      truncated_line = line_string.truncate(
-        errors_config.fetch(:max_length),
-        padding: message.length,
-      )
-
-      styled_message = case errors_config.fetch(:styling)
-        when :terminal
-          COLORS.send("bright_#{color}").bold(message)
-        when :html
-          "<rl-error class=\"#{color}\">#{message}</rl-error>"
-        end
-
-      self.class.new("#{styled_message}: #{truncated_line}")
-    end
-
-    private
-
-    COLORS = Pastel.new
-  end
-
-  # FILE # # # # # # # # # # # # # # # # # # # # # # # # # #
+  class Error < StandardError; end
 
   # Means there was a problem accessing a file.
   class FileError < Reading::Error; end
 
-  # MISC # # # # # # # # # # # # # # # # # # # # # # # # # #
-
-  # Means the user-supplied custom config is invalid.
+  # Means there is something wrong with the user-supplied custom config.
   class ConfigError < Reading::Error; end
 
-  # VALIDATION # # # # # # # # # # # # # # # # # # # # # # #
+  # Means unexpected input was encountered during parsing.
+  class ParsingError < Reading::Error; end
+
+  # Means something in the Head column (author, title, etc.) is invalid.
+  class InvalidHeadError < Reading::Error; end
+
+  # Means something in the History column is invalid.
+  class InvalidHistoryError < Reading::Error; end
 
   # Means there are too many columns in a row.
   class TooManyColumnsError < Reading::Error; end
 
   # Means a date is unparsable, or a set of dates does not make logical sense.
   class InvalidDateError < Reading::Error; end
-
-  # Means something in the Source column is invalid.
-  class InvalidSourceError < Reading::Error; end
-
-  # Means something in the Head column (author, title, etc.) is invalid.
-  class InvalidHeadError < Reading::Error; end
-
-  # Means the Rating column can't be parsed as a number.
-  class InvalidRatingError < Reading::Error; end
-
-  # Means a valid length is missing.
-  class InvalidLengthError < 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

@@ -0,0 +1,140 @@
+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.)
+    class Item::TimeLength
+      include Comparable
+
+      attr_reader :value # in total minutes
+
+      # @param value [Numeric] the total minutes
+      def initialize(value)
+        @value = value
+      end
+
+      # Builds an Item::TimeLength from a string.
+      # @param string [String] a time duration in "h:mm" format.
+      # @return [TimeLength]
+      def self.parse(string)
+        hours, minutes = string.split(':').map(&:to_i)
+        new((hours * 60) + minutes)
+      end
+
+      # Only the hours, e.g. the "h" value in "h:mm".
+      # @return [Numeric]
+      def hours
+        value / 60
+      end
+
+      # Only the hours, e.g. the "mm" value in "h:mm".
+      # @return [Numeric]
+      def minutes
+        value % 60
+      end
+
+      # A string in "h:mm" format.
+      # @return [String]
+      def to_s
+        "#{hours}:#{minutes}"
+      end
+
+      # @return [Boolean]
+      def zero?
+        value.zero?
+      end
+
+      # Converts @value to an Integer if it's a whole number, and returns self.
+      # @return [TimeLength]
+      def to_i_if_whole!
+        if @value.to_i == @value
+          @value = @value.to_i
+        end
+
+        self
+      end
+
+      # A non-mutating version of #to_i_if_whole! for compatibility with the
+      # refinement Numeric#to_i_if_whole.
+      # @return [TimeLength]
+      def to_i_if_whole
+        return self if @value.is_a?(Integer) || @value.to_i != @value
+
+        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.
+      # @return [TimeLength]
+      def +(other)
+        if other.is_a? Item::TimeLength
+          self.class.new(value + other.value)
+        elsif other.zero?
+          self
+        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.
+      # @return [TimeLength]
+      def -(other)
+        if other.is_a? Item::TimeLength
+          self.class.new(value - other.value)
+        elsif other.zero?
+          self
+        else
+          raise TypeError, "#{other.class} can't be subtracted from Item::TimeLength."
+        end
+      end
+
+      # @param other [TimeLength, Numeric]
+      # @return [TimeLength]
+      def *(other)
+        if other.is_a? Numeric
+          self.class.new(value * other).to_i_if_whole!
+        else
+          raise TypeError, "TimeLength can't be multiplied by #{other.class}."
+        end
+      end
+
+      # @param other [TimeLength, Numeric]
+      # @return [TimeLength]
+      def /(other)
+        if other.is_a? Numeric
+          self.class.new(value / other).to_i_if_whole!
+        else
+          raise TypeError, "TimeLength can't be divided by #{other.class}."
+        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.
+      def coerce(other)
+        if other.zero?
+          [self.class.new(other), self]
+        else
+          raise TypeError, "TimeLength can't be coerced into #{other.class}."
+        end
+      end
+
+      # TODO: add comparison to pages (nonzero Integer)
+      # @param other [TimeLength, Integer] if Integer, must be zero.
+      def <=>(other)
+        return 1 if other.nil?
+
+        if other.zero?
+          return 0 if value.zero?
+          return 1
+        end
+
+        unless other.is_a? Item::TimeLength
+          raise TypeError, "TimeLength can't be compared to #{other.class} #{other}."
+        end
+
+        value <=> other.value
+      end
+    end
+  end
+end