reading 0.6.0

data/lib/reading/attribute/variants/variants_attribute.rb

@@ -0,0 +1,69 @@
+require_relative "series_subattribute"
+require_relative "sources_subattribute"
+require_relative "length_subattribute"
+require_relative "extra_info_subattribute"
+
+module Reading
+  class Row
+    class VariantsAttribute < Attribute
+      using Util::HashArrayDeepFetch
+
+      def parse
+        sources_str = columns[:sources]&.presence || " "
+
+        format_as_separator = config.deep_fetch(:csv, :regex, :formats_split)
+
+        sources_str.split(format_as_separator).map { |variant_with_extras|
+          # without extra info or series
+          bare_variant = variant_with_extras
+            .split(config.deep_fetch(:csv, :long_separator))
+            .first
+
+          series_attr = SeriesSubattribute.new(item_head:, variant_with_extras:, config:)
+          sources_attr = SourcesSubattribute.new(bare_variant:, config:)
+          # Length, despite not being very complex, is still split out into a
+          # subattribute because it needs to be accessible to
+          # ExperiencesAttribute (more specifically SpansSubattribute) which
+          # uses length as a default value for amount.
+          length_attr = LengthSubattribute.new(bare_variant:, columns:, config:)
+          extra_info_attr = ExtraInfoSubattribute.new(item_head:, variant_with_extras:, config:)
+
+          variant =
+            {
+              format: format(bare_variant) || format(item_head) || template.fetch(:format),
+              series: series_attr.parse                         || template.fetch(:series),
+              sources: sources_attr.parse                       || template.fetch(:sources),
+              isbn: isbn(bare_variant)                          || template.fetch(:isbn),
+              length: length_attr.parse                         || template.fetch(:length),
+              extra_info: extra_info_attr.parse                 || template.fetch(:extra_info)
+            }
+
+          if variant != template
+            variant
+          else
+            nil
+          end
+        }.compact.presence
+      end
+
+      private
+
+      def template
+        @template ||= config.deep_fetch(:item, :template, :variants).first
+      end
+
+      def format(str)
+        emoji = str.match(/^#{config.deep_fetch(:csv, :regex, :formats)}/).to_s
+        config.deep_fetch(:item, :formats).key(emoji)
+      end
+
+      def isbn(str)
+        isbns = str.scan(config.deep_fetch(:csv, :regex, :isbn))
+        if isbns.count > 1
+          raise InvalidSourceError, "Only one ISBN/ASIN is allowed per item variant"
+        end
+        isbns[0]&.to_s
+      end
+    end
+  end
+end

data/lib/reading/config.rb

@@ -0,0 +1,202 @@
+module Reading
+  # Builds a hash config.
+  class Config
+    using Util::HashDeepMerge
+    using Util::HashArrayDeepFetch
+
+    attr_reader :hash
+
+    # @param custom_config [Hash] a custom config which overrides the defaults,
+    #   e.g. { errors: { styling: :html } }
+    def initialize(custom_config = {})
+      @custom_config = custom_config
+
+      build_hash
+    end
+
+    private
+
+    # Builds a hash of the default config combined with the given custom config.
+    # @return [Hash]
+    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)
+      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) }
+
+      # Add the Regex config, which is built based on the config so far.
+      @hash[:csv][:regex] = build_regex_config
+    end
+
+    # The default config, excluding Regex config (see further down).
+    # @return [Hash]
+    def default_config
+      {
+        errors:
+          {
+            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
+          },
+        item:
+          {
+            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:
+                  [{
+                    format: nil,
+                    series:
+                      [{
+                        name: nil,
+                        volume: nil,
+                      }],
+                    sources:
+                      [{
+                        name: nil,
+                        url: nil,
+                      }],
+                    isbn: nil,
+                    length: nil,
+                    extra_info: [],
+                  }],
+                experiences:
+                  [{
+                    spans:
+                      [{
+                        dates: nil,
+                        amount: nil,
+                        progress: nil,
+                        name: nil,
+                        favorite?: false,
+                      }],
+                    group: nil,
+                    variant_index: 0,
+                  }],
+                notes:
+                  [{
+                    blurb?: false,
+                    private?: false,
+                    content: nil,
+                  }],
+              },
+          },
+        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
+                public_notes
+                blurb
+                private_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:           " -- ",
+            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.
+    # @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)}]+/
+
+      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}/
+
+      {
+        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}\/\d?\d\/\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
+end

data/lib/reading/csv.rb

@@ -0,0 +1,67 @@
+# Used throughout, in other files.
+require_relative "util/blank"
+require_relative "util/string_remove"
+require_relative "util/string_truncate"
+require_relative "util/hash_to_struct"
+require_relative "util/hash_deep_merge"
+require_relative "util/hash_array_deep_fetch"
+require_relative "util/hash_compact_by_template"
+require_relative "errors"
+
+# Used just here.
+require_relative "config"
+require_relative "line"
+
+module Reading
+  class CSV
+    using Util::HashDeepMerge
+    using Util::HashArrayDeepFetch
+    using Util::HashToStruct
+
+    attr_reader :config
+
+    # @param feed [Object] the input source, which must respond to #each_line;
+    #   if nil, the file at the given path is used.
+    # @param path [String] the path of the source file.
+    # @param config [Hash] a custom config which overrides the defaults,
+    #   e.g. { errors: { styling: :html } }
+    def initialize(feed = nil, path: nil, config: {})
+      if feed.nil? && path.nil?
+        raise ArgumentError, "No file given to load."
+      end
+
+      if path
+        if !File.exist?(path)
+          raise FileError, "File not found! #{@path}"
+        elsif File.directory?(path)
+          raise FileError, "The reading log must be a file, but the path given is a directory: #{@path}"
+        end
+      end
+
+      @feed = feed
+      @path = path
+      @config ||= Config.new(config).hash
+    end
+
+    # Parses a CSV reading log into item data (an array of Structs).
+    # For what the Structs look like, see the Hash at @default_config[:item][:template]
+    # in config.rb. The Structs are identical in structure to that Hash (with
+    # every inner Hash replaced with a Struct).
+    # @return [Array<Struct>] an array of Structs like the template in config.rb
+    def parse
+      feed = @feed || File.open(@path)
+      items = []
+
+      feed.each_line do |string|
+        line = Line.new(string, self)
+        row = line.to_row
+
+        items += row.parse
+      end
+
+      items.map(&:to_struct)
+    ensure
+      feed&.close if feed.respond_to?(:close)
+    end
+  end
+end

data/lib/reading/errors.rb

@@ -0,0 +1,77 @@
+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 # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  # Means there was a problem accessing a file.
+  class FileError < Reading::Error; end
+
+  # MISC # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  # Means the user-supplied custom config is invalid.
+  class ConfigError < Reading::Error; end
+
+  # VALIDATION # # # # # # # # # # # # # # # # # # # # # # #
+
+  # 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/line.rb

@@ -0,0 +1,23 @@
+require_relative "row/compact_planned_row"
+require_relative "row/blank_row"
+require_relative "row/regular_row"
+
+module Reading
+  # A bridge between rows as strings and as parsable Rows, used whenever the
+  # context of the line in the CSV is needed, e.g. converting a line to a Row,
+  # or adding a CSV line to a Row parsing error.
+  class Line
+    attr_reader :string, :csv
+
+    def initialize(string, csv)
+      @string = string.dup.force_encoding(Encoding::UTF_8).strip
+      @csv = csv
+    end
+
+    def to_row
+      return CompactPlannedRow.new(self) if CompactPlannedRow.match?(self)
+      return BlankRow.new(self) if BlankRow.match?(self)
+      RegularRow.new(self)
+    end
+  end
+end

data/lib/reading/row/blank_row.rb

@@ -0,0 +1,23 @@
+require_relative "row"
+
+module Reading
+  # An empty or commented-out row. A null object which returns an empty array.
+  class BlankRow < Row
+    using Util::HashArrayDeepFetch
+
+    # Whether the given CSV line is a blank row.
+    # @param line [Reading::Line]
+    # @return [Boolean]
+    def self.match?(line)
+      comment_char = line.csv.config.deep_fetch(:csv, :comment_character)
+
+      line.string.strip.empty? ||
+        line.string.strip.start_with?(comment_char)
+    end
+
+    # Overrides Row#parse.
+    def parse
+      []
+    end
+  end
+end

data/lib/reading/row/compact_planned_row.rb

@@ -0,0 +1,130 @@
+require_relative "row"
+require "debug"
+
+module Reading
+  # Parses a row of compactly listed planned items into an array of hashes of
+  # item data.
+  class CompactPlannedRow < Row
+    using Util::StringRemove
+    using Util::HashDeepMerge
+    using Util::HashArrayDeepFetch
+
+    # Whether the given CSV line is a compact planned row.
+    # @param line [Reading::Line]
+    # @return [Boolean]
+    def self.match?(line)
+      comment_char = line.csv.config.deep_fetch(:csv, :comment_character)
+
+      line.string.strip.start_with?(comment_char) &&
+        line.string.match?(line.csv.config.deep_fetch(:csv, :regex, :compact_planned_row_start))
+    end
+
+    private
+
+    def skip?
+      config.deep_fetch(:csv, :skip_compact_planned)
+    end
+
+    def before_parse
+      to_ignore = config.deep_fetch(:csv, :regex, :compact_planned_ignored_chars)
+      start_regex = config.deep_fetch(:csv, :regex, :compact_planned_row_start)
+
+      string_without_ignored_chars = string.remove_all(to_ignore)
+      start = string_without_ignored_chars.match(start_regex)
+
+      @genres = Array(start[:genres]&.downcase&.strip&.split(",")&.map(&:strip))
+      @sources = sources(start[:sources])
+      @row_without_genre = string_without_ignored_chars.remove(start.to_s)
+    end
+
+    def string_to_be_split_by_format_emojis
+      @row_without_genre
+    end
+
+    def item_hash(item_head)
+      item_match = item_head.match(config.deep_fetch(:csv, :regex, :compact_planned_item))
+      unless item_match
+        raise InvalidHeadError, "Title missing after #{item_head} in compact planned row"
+      end
+
+      author = AuthorAttribute.new(item_head: item_match[:author_title], config:).parse
+
+      begin
+        title = TitleAttribute.new(item_head: item_match[:author_title], config:).parse
+      rescue InvalidHeadError
+        raise InvalidHeadError, "Title missing after #{item_head} in compact planned row"
+      end
+
+      if item_match[:sources_column]
+        if item_match[:sources_column].include?(config.deep_fetch(:csv, :column_separator))
+          raise InvalidSourceError, "Too many columns (only Sources allowed) " \
+            "after #{item_head} in compact planned row"
+        end
+
+        variants_attr = VariantsAttribute.new(
+          item_head: item_match[:format_emoji] + item_match[:author_title],
+          columns: { sources: item_match[:sources_column], length: nil },
+          config:,
+        )
+        variants = variants_attr.parse
+      else
+        variants = [parse_variant(item_match)]
+      end
+
+      template.deep_merge(
+        author: author || template.fetch(:author),
+        title: title,
+        genres: @genres.presence || template.fetch(:genres),
+        variants:,
+      )
+    end
+
+    def template
+      @template ||= config.deep_fetch(:item, :template)
+    end
+
+    def parse_variant(item_match)
+      item_head = item_match[:format_emoji] + item_match[:author_title]
+      series_attr = SeriesSubattribute.new(item_head:, config:)
+      extra_info_attr = ExtraInfoSubattribute.new(item_head:, config:)
+      sources = (@sources + sources(item_match[:sources])).uniq.presence
+
+      {
+        format: format(item_match[:format_emoji]),
+        series: series_attr.parse_head          || template.deep_fetch(:variants, 0, :series),
+        sources: sources                        || template.deep_fetch(:variants, 0, :sources),
+        isbn:                                   template.deep_fetch(:variants, 0, :isbn),
+        length:                                 template.deep_fetch(:variants, 0, :length),
+        extra_info: extra_info_attr.parse_head  || template.deep_fetch(:variants, 0, :extra_info),
+      }
+    end
+
+    def format(format_emoji)
+      config.deep_fetch(:item, :formats).key(format_emoji)
+    end
+
+    def sources(sources_str)
+      return [] if sources_str.nil?
+
+      sources_str
+        .split(config.deep_fetch(:csv, :compact_planned_source_prefix))
+        .map { |source| source.remove(/\s*,\s*/) }
+        .map(&:strip)
+        .reject(&:empty?)
+        .map { |source_name|
+          if valid_url?(source_name)
+            source_name = source_name.chop if source_name.chars.last == "/"
+            { name: config.deep_fetch(:item, :sources, :default_name_for_url),
+              url: source_name }
+          else
+            { name: source_name,
+              url: nil }
+          end
+        }
+    end
+
+    def valid_url?(str)
+      str&.match?(/http[^\s,]+/)
+    end
+  end
+end

data/lib/reading/row/regular_row.rb

@@ -0,0 +1,94 @@
+require_relative "row"
+require_relative "../attribute/all_attributes"
+
+module Reading
+  # Parses a normal CSV row into an array of hashes of item data. Typically
+  # a normal row describes one item and so it's parsed into an array containing
+  # a single hash, but it's also possible for a row to describe multiple items.
+  class RegularRow < Row
+    using Util::HashArrayDeepFetch
+
+    private attr_reader :columns, :attribute_classes
+
+    private
+
+    def after_initialize
+      set_attribute_classes
+    end
+
+    def before_parse
+      set_columns
+      ensure_head_column_present
+    end
+
+    def string_to_be_split_by_format_emojis
+      columns[:head]
+    end
+
+    def set_attribute_classes
+      @attribute_classes ||= config.deep_fetch(:item, :template).map { |attribute_name, _default|
+        attribute_name_camelcase = attribute_name.to_s.split("_").map(&:capitalize).join
+        attribute_class_name = "#{attribute_name_camelcase}Attribute"
+        attribute_class = self.class.const_get(attribute_class_name)
+
+        [attribute_name, attribute_class]
+      }.to_h
+      .merge(custom_attribute_classes)
+    end
+
+    def custom_attribute_classes
+      numeric = custom_attribute_classes_of_type(:numeric) do |value|
+        Float(value, exception: false)
+      end
+
+      text = custom_attribute_classes_of_type(:text) do |value|
+        value
+      end
+
+      (numeric + text).to_h
+    end
+
+    def custom_attribute_classes_of_type(type, &process_value)
+      config.deep_fetch(:csv, :"custom_#{type}_columns").map { |attribute, _default_value|
+        custom_class = Class.new(Attribute)
+
+        custom_class.define_method(:parse) do
+          value = columns[attribute.to_sym]&.strip&.presence
+          process_value.call(value)
+        end
+
+        [attribute.to_sym, custom_class]
+      }
+    end
+
+    def set_columns
+      @columns = (
+        config.deep_fetch(:csv, :enabled_columns) +
+          config.deep_fetch(:csv, :custom_numeric_columns).keys +
+          config.deep_fetch(:csv, :custom_text_columns).keys
+        )
+        .zip(string.split(config.deep_fetch(:csv, :column_separator)))
+        .to_h
+    end
+
+    def ensure_head_column_present
+      if columns[:head].nil? || columns[:head].strip.empty?
+        raise InvalidHeadError, "The Head column must not be blank"
+      end
+    end
+
+    def item_hash(item_head)
+      config
+        .deep_fetch(:item, :template)
+        .merge(config.deep_fetch(:csv, :custom_numeric_columns))
+        .merge(config.deep_fetch(:csv, :custom_text_columns))
+        .map { |attribute_name, default_value|
+          attribute_class = attribute_classes.fetch(attribute_name)
+          attribute_parser = attribute_class.new(item_head:, columns:, config:)
+          parsed = attribute_parser.parse
+
+          [attribute_name, parsed || default_value]
+        }.to_h
+    end
+  end
+end