reading 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4145847e60a6045a1381afe207be44d30636ca7b058d4c1c1e0db70009af0b4
-  data.tar.gz: 833b042be4b575e4ed166d0269610504c031d03460a0f75c4dedc214b1eaf152
+  metadata.gz: 531b4f54f11eed2f638079efbc0542977287d3ca887bea04a0785b6ca10c45fe
+  data.tar.gz: 58881344b75fc84041275d3ad9b84955f03d53ff8ca35f09932509b584c8b218
 SHA512:
-  metadata.gz: '09f08e0be8d6cd97481097d4193209af3cda404e076f2d5529c7c4bdee5f146afbf980a2cb05f2435c06633b89954067ee8bea9d02dae4eddd924f86626a9f63'
-  data.tar.gz: 3a50b075c63f2a8b0082b309bef201a8351344c729e90b18482b5796a53bedee1af7fad71af3a0dd884d1245440cfd14dbf6d28aa38bdf5d09717059bd22e7f8
+  metadata.gz: 3539806e8c4472ba98d1ac19c862989a21d25782e4ec94ac04a3dfd4a3f30509187dce4ee6fa86fc189f742e19e2e649ffcf94f5e539cc1bc576856748b9adf6
+  data.tar.gz: 1be98e8aa5fc04a87aae46832cc981a49d3b725eeeaee2c6b75f1d723cf907d2e6567b9474022a5b19bc113db3555a7d358ec924c469f269d361b440d1963ca2

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:)
 
 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/alex/reading.csv'
+#   reading '/home/alex/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/alex/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:)
+
+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,182 +25,144 @@ 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
 
-      # 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) }
+      # 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
 
-      # Add the Regex config, which is built based on the config so far.
-      @hash[:csv][:regex] = build_regex_config
+      @hash[:enabled_columns] = enabled_columns
+
+      # 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:
           {
-            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
+            print:     "📕",
+            ebook:     "⚡",
+            audiobook: "🔊",
+            pdf:       "📄",
+            audio:     "🎤",
+            video:     "🎞️",
+            course:    "🏫",
+            piece:     "✏️",
+            website:   "🌐",
           },
-        item:
+        source_names_from_urls:
           {
-            formats:
-              {
-                print:     "📕",
-                ebook:     "⚡",
-                audiobook: "🔊",
-                pdf:       "📄",
-                audio:     "🎤",
-                video:     "🎞️",
-                course:    "🏫",
-                piece:     "✏️",
-                website:   "🌐",
-              },
-            sources:
-              {
-                names_from_urls:
-                  {
-                    "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",
-                  },
-                default_name_for_url: "site",
-              },
-            template:
-              {
-                rating: nil,
-                author: nil,
-                title: nil,
-                genres: [],
-                variants:
+            "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",
+          },
+        # 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:
+          {
+            rating: nil,
+            author: nil,
+            title: nil,
+            genres: [],
+            variants:
+              [{
+                format: nil,
+                series:
                   [{
-                    format: nil,
-                    series:
-                      [{
-                        name: nil,
-                        volume: nil,
-                      }],
-                    sources:
-                      [{
-                        name: nil,
-                        url: nil,
-                      }],
-                    isbn: nil,
-                    length: nil,
-                    extra_info: [],
+                    name: nil,
+                    volume: nil,
                   }],
-                experiences:
+                sources:
                   [{
-                    spans:
-                      [{
-                        dates: nil,
-                        amount: nil,
-                        progress: nil,
-                        name: nil,
-                        favorite?: false,
-                      }],
-                    group: nil,
-                    variant_index: 0,
+                    name: nil,
+                    url: nil,
                   }],
-                notes:
+                isbn: nil,
+                length: nil,
+                extra_info: [],
+              }],
+            experiences:
+              [{
+                spans:
                   [{
-                    blurb?: false,
-                    private?: false,
-                    content: nil,
+                    dates: nil,
+                    amount: 0,
+                    progress: nil,
+                    name: nil,
+                    favorite?: false,
                   }],
-              },
-          },
-        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,
+                group: nil,
+                variant_index: 0,
+              }],
+            notes:
+              [{
+                blurb?: false,
+                private?: false,
+                content: nil,
+              }],
           },
       }
     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/item/time_length.rb

@@ -0,0 +1,138 @@
+module Reading
+  module Item
+    # For coercion, see https://www.mutuallyhuman.com/blog/class-coercion-in-ruby/
+    class TimeLength
+      include Comparable
+
+      attr_reader :value # in total minutes
+
+      # @param value [Numeric] the total minutes
+      def initialize(value)
+        @value = value
+      end
+
+      # Builds a 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? TimeLength
+          self.class.new(value + other.value)
+        elsif other.zero?
+          self
+        else
+          raise TypeError, "#{other.class} can't be added to 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? TimeLength
+          self.class.new(value - other.value)
+        elsif other.zero?
+          self
+        else
+          raise TypeError, "#{other.class} can't be subtracted from 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)
+      # @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? TimeLength
+          raise TypeError, "TimeLength can't be compared to #{other.class} #{other}."
+        end
+
+        value <=> other.value
+      end
+    end
+  end
+end

data/lib/reading/parsing/attributes/attribute.rb

@@ -0,0 +1,26 @@
+module Reading
+  module Parsing
+    module Attributes
+      # The base class for all the attribute in parsing/attributes, each of which
+      # extracts an attribute from a parsed row. Together they transform the
+      # parsed row (an intermediate hash) into item attributes, as in
+      # Config#default_config[:item_template].
+      class Attribute
+        private attr_reader :config
+
+        # @param config [Hash] an entire config.
+        def initialize(config)
+          @config = config
+        end
+
+        # Extracts this attribute's value from a parsed row.
+        # @param parsed_row [Hash] a parsed row (the intermediate hash).
+        # @param head_index [Integer] current item's position in the Head column.
+        # @return [Object]
+        def transform_from_parsed(parsed_row, head_index)
+          raise NotImplementedError, "#{self.class} should have implemented #{__method__}"
+        end
+      end
+    end
+  end
+end

data/lib/reading/parsing/attributes/author.rb

@@ -0,0 +1,15 @@
+module Reading
+  module Parsing
+    module Attributes
+      # Transformer for the :author item attribute.
+      class Author < Attribute
+        # @param parsed_row [Hash] a parsed row (the intermediate hash).
+        # @param head_index [Integer] current item's position in the Head column.
+        # @return [String]
+        def transform_from_parsed(parsed_row, head_index)
+          parsed_row[:head][head_index][:author]
+        end
+      end
+    end
+  end
+end