reading 0.6.0 → 0.7.0

data/lib/reading/parsing/attributes/experiences/spans_validator.rb

@@ -0,0 +1,149 @@
+module Reading
+  module Parsing
+    module Attributes
+      class Experiences < Attribute
+        # Methods to validate dates in spans. This does not cover all the ways
+        # dates can be invalid, just the ones not caught during parsing.
+        module SpansValidator
+          using Util::HashArrayDeepFetch
+
+          class << self
+            # Checks the dates in the given experiences hash, and raises an error
+            # at the first invalid date found.
+            # @param experiences [Array<Hash>] experience hashes.
+            # @param config [Hash] an entire config.
+            # @param history_column [Boolean] whether this validation is for
+            #   experiences from the History column.
+            # @raise [InvalidDateError] if any date is invalid.
+            def validate(experiences, config, history_column: false)
+              if both_date_columns?(config)
+                validate_number_of_start_dates_and_end_dates(experiences)
+              end
+
+              if start_dates_column?(config) || history_column
+                validate_start_dates_are_in_order(experiences)
+              end
+
+              if end_dates_column?(config) || history_column
+                validate_end_dates_are_in_order(experiences)
+              end
+
+              if both_date_columns?(config) || history_column
+                validate_experiences_of_same_variant_do_not_overlap(experiences)
+              end
+
+              validate_spans_are_in_order_and_not_overlapping(experiences)
+            end
+
+            private
+
+            # Whether the Start Dates column is enabled.
+            # @return [Boolean]
+            def start_dates_column?(config)
+              config.fetch(:enabled_columns).include?(:start_dates)
+            end
+
+            # Whether the End Dates column is enabled.
+            # @return [Boolean]
+            def end_dates_column?(config)
+              config.fetch(:enabled_columns).include?(:end_dates)
+            end
+
+            # Whether both the Start Dates and End Dates columns are enabled.
+            # @return [Boolean]
+            def both_date_columns?(config)
+              start_dates_column?(config) && end_dates_column?(config)
+            end
+
+            # Raises an error if there are more end dates than start dates, or
+            # if there is more than one more start date than end dates.
+            # @raise [InvalidDateError]
+            def validate_number_of_start_dates_and_end_dates(experiences)
+              both_dates, not_both_dates = experiences
+                .filter { |exp| exp[:spans].first&.dig(:dates) }
+                .map { |exp| [exp[:spans].first[:dates].begin, exp[:spans].last[:dates].end] }
+                .partition { |start_date, end_date| start_date && end_date }
+
+              all_dates_paired = not_both_dates.empty?
+              last_date_started_present = not_both_dates.count == 1 && not_both_dates.first
+
+              unless all_dates_paired || last_date_started_present
+                raise InvalidDateError, "Start dates or end dates are missing"
+              end
+            end
+
+            # Raises an error if the spans' first start dates are not in order.
+            # @raise [InvalidDateError]
+            def validate_start_dates_are_in_order(experiences)
+              experiences
+                .filter { |exp| exp[:spans].first&.dig(:dates) }
+                .map { |exp| exp[:spans].first[:dates].begin }
+                .each_cons(2) do |a, b|
+                  if (a.nil? && b.nil?) || (a && b && a > b )
+                    raise InvalidDateError, "Start dates are not in order"
+                  end
+                end
+            end
+
+            # Raises an error if the spans' last end dates are not in order.
+            # @raise [InvalidDateError]
+            def validate_end_dates_are_in_order(experiences)
+              experiences
+                .filter { |exp| exp[:spans].first&.dig(:dates) }
+                .map { |exp| exp[:spans].last[:dates].end }
+                .each_cons(2) do |a, b|
+                  if (a.nil? && b.nil?) || (a && b && a > b )
+                    raise InvalidDateError, "End dates are not in order"
+                  end
+                end
+            end
+
+            # Raises an error if two experiences of the same variant overlap.
+            # @raise [InvalidDateError]
+            def validate_experiences_of_same_variant_do_not_overlap(experiences)
+              experiences
+                .group_by { |exp| exp[:variant_index] }
+                .each do |_variant_index, exps|
+                  exps.filter { |exp| exp[:spans].any? }.each_cons(2) do |a, b|
+                    a_metaspan = a[:spans].first[:dates].begin..a[:spans].last[:dates].end
+                    b_metaspan = b[:spans].first[:dates].begin..b[:spans].last[:dates].end
+                    if a_metaspan.cover?(b_metaspan.begin || a_metaspan.begin || a_metaspan.end) ||
+                        b_metaspan.cover?(a_metaspan.begin || b_metaspan.begin || b_metaspan.end)
+                      raise InvalidDateError, "Experiences are overlapping"
+                    end
+                  end
+                end
+            end
+
+            # Raises an error if the spans within an experience are out of order
+            # or if the spans overlap.
+            # @raise [InvalidDateError]
+            def validate_spans_are_in_order_and_not_overlapping(experiences)
+              experiences
+                .filter { |exp| exp[:spans].first&.dig(:dates) }
+                .each do |exp|
+                  exp[:spans]
+                    .map { |span| span[:dates] }
+                    # Exclude nil dates (planned entries in History).
+                    .reject { |dates| dates.nil? }
+                    .each do |dates|
+                      if dates.begin && dates.end && dates.begin > dates.end
+                        raise InvalidDateError, "A date range is backward"
+                      end
+                    end
+                    .each_cons(2) do |a, b|
+                      if a.begin > b.begin || a.end > b.end
+                        raise InvalidDateError, "Dates are not in order"
+                      end
+                      if a.cover?(b.begin + 1)
+                        raise InvalidDateError, "Dates are overlapping"
+                      end
+                    end
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+require "date"
+require_relative "experiences/history_transformer"
+require_relative "experiences/dates_and_head_transformer"
+
+module Reading
+  module Parsing
+    module Attributes
+      # Transformer for the :experiences item attribute.
+      class Experiences < Attribute
+        using Util::HashArrayDeepFetch
+        using Util::HashDeepMerge
+
+        # @param parsed_row [Hash] a parsed row (the intermediate hash).
+        # @param head_index [Integer] current item's position in the Head column.
+        # @return [Array<Hash>] an array of experiences; see
+        #   Config#default_config[:item_template][:experiences]
+        def transform_from_parsed(parsed_row, head_index)
+          if !parsed_row[:history].blank?
+            return HistoryTransformer.new(parsed_row, config).transform
+          end
+
+          DatesAndHeadTransformer.new(parsed_row, head_index, config).transform
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Reading
+  module Parsing
+    module Attributes
+      # Transformer for the :genres item attribute.
+      class Genres < Attribute
+        # @param parsed_row [Hash] a parsed row (the intermediate hash).
+        # @param head_index [Integer] current item's position in the Head column.
+        # @return [Array<String>]
+        def transform_from_parsed(parsed_row, head_index)
+          (parsed_row[:genres] || parsed_row[:head][head_index][:genres])
+            &.map { _1.is_a?(Hash) ? _1[:genre] : _1 }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module Reading
+  module Parsing
+    module Attributes
+      # Transformer for the :notes item attribute.
+      class Notes < Attribute
+        # @param parsed_row [Hash] a parsed row (the intermediate hash).
+        # @param _head_index [Integer] current item's position in the Head column.
+        # @return [Array<Hash>] an array of notes; see
+        #   Config#default_config[:item_template][:notes]
+        def transform_from_parsed(parsed_row, _head_index)
+          parsed_row[:notes]&.map { |note|
+            {
+              blurb?: note.has_key?(:note_blurb),
+              private?: note.has_key?(:note_private),
+              content: note[:note_regular] || note[:note_blurb] || note[:note_private],
+            }
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Reading
+  module Parsing
+    module Attributes
+      # Transformer for the :rating item attribute.
+      class Rating < Attribute
+        # @param parsed_row [Hash] a parsed row (the intermediate hash).
+        # @param _head_index [Integer] current item's position in the Head column.
+        # @return [Integer, Float]
+        def transform_from_parsed(parsed_row, _head_index)
+          rating = parsed_row[:rating]&.dig(:number)
+
+          Integer(rating, exception: false) || Float(rating, exception: false)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module Reading
+  module Parsing
+    module Attributes
+      # Shared
+      module Shared
+        # Extracts the :progress sub-attribute (percent, pages, or time) from
+        # the given hash.
+        # @param hash [Hash] any parsed hash that contains progress.
+        # @return [Float, Integer, Reading::Item::TimeLength]
+        def self.progress(hash)
+          hash[:progress_percent]&.to_f&./(100) ||
+            hash[:progress_pages]&.to_i ||
+            hash[:progress_time]&.then { Item::TimeLength.parse _1 } ||
+            (0 if hash[:progress_dnf]) ||
+            (1.0 if hash[:progress_done]) ||
+            nil
+        end
+
+        # Extracts the :length sub-attribute (pages or time) from the given hash.
+        # @param hash [Hash] any parsed hash that contains length.
+        # @param key_name [Symbol] the first part of the keys to be checked.
+        # @param episodic [Boolean] whether to look for episodic (not total) length.
+        #   If false, returns nil if hash contains :each. If true, returns a
+        #   length only if hash contains :each or if it has repetitions, in
+        #   which case repetitions are ignored. Examples of episodic lengths
+        #   (before parsing) are "0:30 each" and "1:00 x14" (where the episodic
+        #   length is 1:00). Examples of non-episodic lengths are "0:30" and "14:00".
+        # @param ignore_repetitions [Boolean] if true, ignores repetitions so
+        #   that e.g. "1:00 x14" gives a length of 1 hour instead of 14 hours.
+        #   This is useful for the History column, where that 1 hour can be used
+        #   as the default amount.
+        # @return [Float, Integer, Reading::Item::TimeLength]
+        def self.length(hash, key_name: :length, episodic: false, ignore_repetitions: false)
+          return nil unless hash
+
+          length = hash[:"#{key_name}_pages"]&.to_i ||
+            hash[:"#{key_name}_time"]&.then { Item::TimeLength.parse _1 }
+
+          return nil unless length
+
+          if hash[:each]
+            # Length is calculated based on History column in this case.
+            if episodic
+              return length
+            else
+              return nil
+            end
+          end
+
+          if hash[:repetitions]
+            return length if episodic
+            length *= hash[:repetitions].to_i unless ignore_repetitions
+          else
+            return nil if episodic && !hash[:each]
+          end
+
+          length
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Reading
+  module Parsing
+    module Attributes
+      # Transformer for the :title item attribute.
+      class Title < 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)
+          title = parsed_row[:head][head_index][:title]
+
+          if title.nil? || title.end_with?(" -")
+            raise InvalidHeadError, "Missing title in the head #{parsed_row[:head][head_index]}"
+          end
+
+          title
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+module Reading
+  module Parsing
+    module Attributes
+      # Transformer for the :variant item attribute.
+      class Variants < Attribute
+        using Util::HashArrayDeepFetch
+
+        # @param parsed_row [Hash] a parsed row (the intermediate hash).
+        # @param head_index [Integer] current item's position in the Head column.
+        # @return [Array<Hash>] an array of variants; see
+        #   Config#default_config[:item_template][:variants]
+        def transform_from_parsed(parsed_row, head_index)
+          head = parsed_row[:head][head_index]
+
+          # || [{}] in case there is no Sources column.
+          (parsed_row[:sources].presence || [{}])&.map { |variant|
+            {
+              format: variant[:format] || head[:format],
+              series: (series(head) + series(variant)).presence,
+              sources: sources(variant) || sources(head),
+              isbn: variant[:isbn] || variant[:asin],
+              length: Attributes::Shared.length(variant) ||
+                Attributes::Shared.length(parsed_row[:length]),
+              extra_info: Array(head[:extra_info]) + Array(variant[:extra_info]),
+            }.map { |k, v| [k, v || template.fetch(k)] }.to_h
+          }&.compact&.presence
+        end
+
+        # A shortcut to the variant template.
+        # @return [Hash]
+        def template
+          config.deep_fetch(:item_template, :variants).first
+        end
+
+        # The :series sub-attribute for the given parsed hash.
+        # @param hash [Hash] any parsed hash that contains :series_names and :series_volumes.
+        # @return [Array<Hash>]
+        def series(hash)
+          (hash[:series_names] || [])
+            .zip(hash[:series_volumes] || [])
+            .map { |name, volume|
+              { name:, volume: Integer(volume, exception: false) }
+            }
+        end
+
+        # The :sources sub-attribute for the given parsed hash.
+        # @param hash [Hash] any parsed hash that contains :sources.
+        # @return [Array<Hash>]
+        def sources(hash)
+          hash[:sources]&.map { |source|
+            if source.match?(/\Ahttps?:\/\//)
+              { name: url_name(source), url: source }
+            else
+              { name: source, url: nil }
+            end
+          }
+        end
+
+        # The name for the given URL string, according to
+        # config[:source_names_from_urls], or nil.
+        # @param url [String] a URL.
+        # @return [String, nil]
+        def url_name(url)
+          config
+            .fetch(:source_names_from_urls)
+            .each do |url_part, name|
+              if url.include?(url_part)
+                return name
+              end
+            end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/reading/parsing/csv.rb

@@ -0,0 +1,101 @@
+# Used throughout, in other files.
+require_relative "../util/blank"
+require_relative "../util/string_remove"
+require_relative "../util/string_truncate"
+require_relative "../util/numeric_to_i_if_whole"
+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 "parser"
+require_relative "transformer"
+
+module Reading
+  module Parsing
+    #
+    # Validates a path or stream (string, file, etc.) of a CSV reading log, then
+    # parses it into item data (an array of Structs).
+    #
+    # Parsing happens in two steps:
+    #   (1) Parse a row string into an intermediate hash representing the columns.
+    #       - See parsing/parser.rb, which uses parsing/rows/*
+    #   (2) Transform the intermediate hash into an array of hashes structured
+    #       around item attributes rather than CSV columns.
+    #       - See parsing/transformer.rb, which uses parsing/attributes/*
+    #
+    # Keeping these steps separate makes the code easier to understand. It was
+    # inspired by the Parslet gem: https://kschiess.github.io/parslet/transform.html
+    #
+    class CSV
+      using Util::HashToStruct
+
+      private attr_reader :parser, :transformer
+
+      # Validates a path or stream (string, file, etc.) of a CSV reading log,
+      # builds the config, and initializes the parser and transformer.
+      # @param path [String] path to the CSV file; if nil, stream is used instead.
+      # @param stream [Object] an object responding to #each_linewith CSV row(s);
+      #   used if no path is given.
+      # @param config [Hash] a custom config which overrides the defaults,
+      #   e.g. { errors: { styling: :html } }
+      def initialize(path = nil, stream: nil, config: {})
+        validate_path_or_stream(path, stream)
+        full_config = Config.new(config).hash
+
+        @path = path
+        @stream = stream
+        @parser = Parser.new(full_config)
+        @transformer = Transformer.new(full_config)
+      end
+
+      # Parses and transforms the reading log into item data.
+      # @return [Array<Struct>] an array of Structs like the template in
+      #   Config#default_config[:item_template]. The Structs are identical in
+      #   structure to that Hash (with every inner Hash replaced by a Struct).
+      def parse
+        input = @path ? File.open(@path) : @stream
+        items = []
+
+        input.each_line do |line|
+          begin
+            intermediate = parser.parse_row_to_intermediate_hash(line)
+            next if intermediate.empty? # When the row is blank or a comment.
+            row_items = transformer.transform_intermediate_hash_to_item_hashes(intermediate)
+          rescue Reading::Error => e
+            raise e.class, "#{e.message} in the row \"#{line}\""
+          end
+
+          items += row_items
+        end
+
+        items.map(&:to_struct)
+      ensure
+        input&.close if input.respond_to?(:close)
+      end
+
+      private
+
+      # Checks on the given stream and path (arguments to #initialize).
+      # @raise [FileError] if the given path is invalid.
+      # @raise [ArgumentError] if both stream and path are nil.
+      def validate_path_or_stream(path, stream)
+        if path
+          if !File.exist?(path)
+            raise FileError, "File not found! #{path}"
+          elsif File.directory?(path)
+            raise FileError, "A file is expected, but the path given is a directory: #{path}"
+          end
+        elsif stream && stream.respond_to?(:each_line)
+          return true
+        else
+          raise ArgumentError,
+            "Either a file path or a stream (string, file, etc.) must be provided."
+        end
+      end
+    end
+  end
+end