reading 0.8.0 → 0.9.0

data/lib/reading/item.rb

@@ -1,9 +1,6 @@
-require "forwardable"
+require 'forwardable'
 
-require_relative "item/view"
-require_relative "config"
-require_relative "util/hash_to_data"
-require_relative "util/hash_array_deep_fetch"
+require_relative 'item/view'
 
 module Reading
   # A wrapper for an item parsed from a CSV reading log, providing convenience
@@ -15,28 +12,36 @@ module Reading
 
     ATTRIBUTES = %i[rating author title genres variants experiences notes]
 
-    private attr_reader :attributes, :config
-    attr_reader :view, :status, :last_end_date
+    private attr_reader :data
+    attr_reader :view
 
-    def_delegators :attributes, *ATTRIBUTES
+    def_delegators :data, *ATTRIBUTES
 
-    # @param item_hash [Hash] a parsed item like the template in
-    #   Config#default_config[:item][:template].
-    # @param config [Hash] an entire config.
+    # @param item_hash_or_data [Hash, Data] a parsed item Hash like the template
+    #   in Config#default_config[:item][:template]; or a Data from another Item.
     # @param view [Class, nil, Boolean] the class that will be used to build the
     #   view object, or nil/false if no view object should be built. If you use
     #   a custom view class, the only requirement is that its #initialize take
-    #   an Item and a full config as arguments.
-    def initialize(item_hash, config: Config.new.hash, view: Item::View)
-      item_hash = item_hash.dup
+    #   an Item.
+    def initialize(item_hash_or_data, view: Item::View)
+      if item_hash_or_data.is_a? Data
+        @data = item_hash_or_data
+      elsif item_hash_or_data.is_a? Hash
+        item_hash = item_hash_or_data.dup
 
-      add_missing_attributes_with_filler_values(item_hash, config)
+        add_missing_attributes_with_filler_values!(item_hash)
+        add_statuses_and_last_end_dates!(item_hash)
 
-      @attributes = item_hash.to_data
-      @config = config
+        @data = item_hash.to_data
+      end
+
+      @view = view.new(self) if view
+    end
 
-      @status, @last_end_date = get_status_and_last_end_date
-      @view = view.new(self, config) if view
+    # This item's status.
+    # @return [Symbol] :planned, :in_progress, or :done
+    def status
+      data.experiences.last&.status || :planned
     end
 
     # Whether this item is done.
@@ -45,11 +50,260 @@ module Reading
       status == :done
     end
 
-    # Whether this item has a fixed length, such as a book or audiobook (as
-    # opposed to an ongoing podcast).
-    # @return [Boolean]
-    def definite_length?
-      attributes.variants.any? { |variant| !!variant.length }
+    # This item's last end date.
+    # @return [Date, nil]
+    def last_end_date
+      data.experiences.last&.last_end_date
+    end
+
+    # Returns a new Item containing shallow copy of @data, with its experiences
+    # replaced with new_experiences.
+    # @param new_experiences [Array<Data>]
+    # @param view [Class, nil, Boolean]
+    # @return [Item]
+    def with_experiences(new_experiences, view: false)
+      new_variants = variants.filter.with_index { |variant, old_index|
+        new_experiences.any? { _1.variant_index == old_index }
+      }
+
+      with_variants(
+        new_variants,
+        new_experiences:,
+        view:,
+      )
+    end
+
+    # Returns a new Item containing shallow copy of @data, with its variants
+    # replaced with new_variants.
+    # @param new_variants [Array<Data>]
+    # @param new_experiences [Array<Data>]
+    # @param view [Class, nil, Boolean]
+    # @return [Item]
+    def with_variants(new_variants, new_experiences: nil, view: false)
+      updated_variant_indices = []
+
+      # Map old to new indices, omitting those of variants that are not in new_variants.
+      variants.each.with_index { |variant, old_index|
+        new_index = new_variants.index(variant)
+        updated_variant_indices[old_index] = new_index if new_index
+      }
+
+      # Remove experiences associated with the removed variants.
+      kept_experiences = (new_experiences || experiences).select { |experience|
+        # Conditional in case Item was created with fragmentary experience hashes,
+        # as in stats_test.rb
+        variant_index = experience.variant_index if experience.members.include?(:variant_index)
+
+        !!updated_variant_indices[variant_index || 0]
+      }
+
+      # Then update the kept experiences' variant indices.
+      updated_kept_experiences = kept_experiences.map { |experience|
+        updated_variant_index = updated_variant_indices[experience.variant_index]
+        experience.with(variant_index: updated_variant_index)
+      }
+
+      self.class.new(
+        data.with(
+          variants: new_variants,
+          experiences: updated_kept_experiences,
+        ),
+        view:,
+      )
+    end
+
+    # Splits this Item into two Items: one < the given date, and the other >= it.
+    # @date [Date] must be the first day of a month.
+    # @return [Array(Item, Item)]
+    def split(date)
+      before_index = nil
+      middle_indices = experiences.map.with_index { |experience, i|
+        if experience.spans.first.dates &&
+          experience.spans.first.dates.begin < date &&
+          experience.last_end_date
+
+          before_index = i
+
+          if experience.last_end_date >= date
+            i
+          else
+            nil
+          end
+        end
+      }
+      .compact
+
+      # There are no experiences with done spans that overlap the date.
+      if middle_indices.none?
+        # The Item is planned.
+        return [] if experiences.none? { _1.spans.first.dates }
+        # date is after all spans.
+        return [self, nil] if experiences.all? { _1.last_end_date && date > _1.last_end_date }
+        # date is before all spans, or overlaps with an in-progress span.
+        return [nil, self] if experiences.all? { _1.spans.first.dates.begin >= date } ||
+          experiences.any? { _1.spans.first.dates.begin < date && _1.last_end_date.nil? }
+
+        # Date is in between experiences.
+        if before_index
+          item_before = with_experiences(experiences[..before_index])
+          item_after = with_experiences(experiences[(before_index + 1)..])
+
+          return [item_before, item_after]
+        end
+      end
+
+      if middle_indices.first == 0
+        experiences_before = []
+      else
+        experiences_before = experiences[..(middle_indices.first - 1)]
+      end
+      experiences_after = experiences[(middle_indices.first + middle_indices.count)..]
+      experiences_middle = experiences.values_at(*middle_indices)
+
+      # TODO remove this check?
+      unless middle_indices == (middle_indices.min..middle_indices.max).to_a
+        raise Reading::Error, "Non-consecutive experiences found during Item#split."
+      end
+
+      experiences_middle.each do |experience_middle|
+        before_index = nil
+        span_middle_index = experience_middle
+          .spans
+          .index.with_index { |span, i|
+            if span.dates && span.dates.begin < date
+              before_index = i
+
+              span.dates.end >= date
+            end
+          }
+
+        if span_middle_index.nil? # date is between spans.
+          spans_before = experience_middle.spans[..before_index]
+          spans_after = experience_middle.spans[(before_index + 1)..]
+        else
+          span_middle = experience_middle.spans[span_middle_index]
+
+          dates_before = span_middle.dates.begin..date.prev_day
+          amount_before = span_middle.amount * (dates_before.count / span_middle.dates.count.to_f)
+          span_middle_before = span_middle.with(
+            dates: dates_before,
+            amount: amount_before,
+          )
+
+          dates_after = date..span_middle.dates.end
+          amount_after = span_middle.amount * (dates_after.count / span_middle.dates.count.to_f)
+          span_middle_after = span_middle.with(
+            dates: dates_after,
+            amount: amount_after,
+          )
+
+          if span_middle_index.zero?
+            spans_before = [span_middle_before]
+          else
+            spans_before = [
+              *experience_middle.spans[..(span_middle_index - 1)],
+              span_middle_before,
+            ]
+          end
+
+          spans_after = [
+            span_middle_after,
+            *experience_middle.spans[(span_middle_index + 1)..],
+          ]
+        end
+
+        experience_middle_before = experience_middle.with(
+          spans: spans_before,
+          last_end_date: spans_before.map { _1.dates&.end }.compact.last,
+        )
+        experience_middle_after = experience_middle.with(
+          spans: spans_after,
+        )
+
+        experiences_before << experience_middle_before
+        experiences_after.unshift(*experience_middle_after)
+      end
+
+      # RM (alternate implementation)
+      # experiences_before = experiences
+      #   .select(&:last_end_date)
+      #   .select { _1.last_end_date < date }
+      # experiences_after = experiences
+      #   .select { _1.spans.first.dates.nil? || _1.spans.first.dates.begin >= date }
+
+      # experiences_middle = experiences.select {
+      #   _1.spans.first.dates.begin < date && _1.last_end_date >= date
+      # }
+      # experiences_middle.each do |experience_middle|
+      #   spans_before = experience_middle
+      #     .spans
+      #     .select { _1.dates&.end }
+      #     .select { _1.dates.end < date }
+      #   spans_after = experience_middle
+      #     .spans
+      #     .select(&:dates)
+      #     .select { _1.dates.begin >= date }
+
+      #   span_middle = experience_middle
+      #     .spans
+      #     .find { _1.dates && _1.dates.begin < date && _1.dates.end >= date }
+
+      #   middle_index = experience_middle.spans.index(span_middle)
+      #   planned_spans_before = experience_middle
+      #     .spans
+      #     .map.with_index { |span, i|
+      #       [i, span] if span.dates.nil? && i < middle_index
+      #     }
+      #     .compact
+      #   planned_spans_after = experience_middle
+      #     .spans
+      #     .map.with_index { |span, i|
+      #       [i, span] if span.dates.nil? && i > middle_index
+      #     }
+      #     .compact
+
+      #   if span_middle
+      #     dates_before = span_middle.dates.begin..date.prev_day
+      #     amount_before = span_middle.amount * (dates_before.count / span_middle.dates.count.to_f)
+      #     span_middle_before = span_middle.with(
+      #       dates: dates_before,
+      #       amount: amount_before,
+      #     )
+
+      #     dates_after = date..span_middle.dates.end
+      #     amount_after = span_middle.amount * (dates_after.count / span_middle.dates.count.to_f)
+      #     span_middle_after = span_middle.with(
+      #       dates: dates_after,
+      #       amount: amount_after,
+      #     )
+
+      #     spans_before = [*spans_before, span_middle_before]
+      #     spans_after = [span_middle_after, *spans_after]
+
+      #     planned_spans_before.each do |i, planned_span|
+      #       spans_before.insert(i, planned_span)
+      #     end
+      #     planned_spans_after.each do |i, planned_span|
+      #       spans_after.insert(i - middle_index, planned_span)
+      #     end
+      #   end
+
+      #   experience_middle_before = experience_middle.with(
+      #     spans: spans_before,
+      #     last_end_date: spans_before.last.dates.end,
+      #   )
+      #   experience_middle_after = experience_middle.with(
+      #     spans: spans_after,
+      #   )
+
+      #   experiences_before << experience_middle_before
+      #   experiences_after = [experience_middle_after, *experiences_after]
+      # end
+
+      item_before = with_experiences(experiences_before)
+      item_after = with_experiences(experiences_after)
+
+      [item_before, item_after]
     end
 
     # Equality to another Item.
@@ -60,17 +314,16 @@ module Reading
         raise ArgumentError, "An Item can be compared only with another Item."
       end
 
-      attributes == other.send(:attributes)
+      data == other.send(:data)
     end
 
     private
 
-    # For each missing item attribute (key in config[:item][:template]) in
+    # For each missing item attribute (key in Config.hash[:item][:template]) in
     # item_hash, adds the key and a filler value.
     # @param item_hash [Hash]
-    # @param config [Hash] an entire config.
-    def add_missing_attributes_with_filler_values(item_hash, config)
-      config.deep_fetch(:item, :template).each do |k, v|
+    def add_missing_attributes_with_filler_values!(item_hash)
+      Config.hash.deep_fetch(:item, :template).each do |k, v|
         next if item_hash.has_key?(k)
 
         filler = v.is_a?(Array) ? [] : nil
@@ -78,39 +331,53 @@ module Reading
       end
     end
 
-    # Determines the status and the last end date. Note: for an item of indefinite
-    # length (e.g. podcast) there is a grace period during which the status
-    # remains :in_progress after the last activity. If that grace period is over,
-    # the status is :done. It's :planned if there are no spans with dates.
+    # Determines the status and the last end date of each experience, and adds
+    # it into the experience hash. Note: for an item of indefinite length (e.g.
+    # podcast) there is a grace period during which the status remains
+    # :in_progress after the last activity. If that grace period is over, the
+    # status is :done. It's :planned if there are no spans with dates.
+    # @param item_hash [Hash]
     # @return [Array(Symbol, Date)]
-    def get_status_and_last_end_date
-      return [:planned, nil] if experiences.none? || experiences.flat_map(&:spans).none?
+    def add_statuses_and_last_end_dates!(item_hash)
+      item_hash[:experiences] = item_hash[:experiences].dup
 
-      experiences_with_spans_with_dates = experiences
-        .select { |experience| experience.spans.any? { |span| span.dates } }
+      item_hash[:experiences].each do |experience|
+        experience[:status] = :planned
+        experience[:last_end_date] = nil
 
-      return [:planned, nil] unless experiences_with_spans_with_dates.any?
+        next unless experience[:spans]&.any? { |span|
+          span[:dates]
+        }
 
-      last_end_date = experiences_with_spans_with_dates
-        .last
-        .spans
-        .select { |span| span.dates }
-        .last
-        .dates
-        .end
+        experience[:status] = :in_progress
 
-      return [:in_progress, nil] unless last_end_date
+        experience[:last_end_date] = experience[:spans]
+          .select { |span| span[:dates] }
+          .last[:dates]
+          .end
 
-      if definite_length?
-        [:done, last_end_date]
-      else
-        grace_period = config.deep_fetch(:item, :indefinite_in_progress_grace_period_days)
-        indefinite_in_progress_grace_period_is_over =
-          (Date.today - grace_period) > last_end_date
+        next unless experience[:last_end_date]
+
+        # Whether this item has a fixed length, such as a book or audiobook (as
+        # opposed to e.g. an ongoing podcast).
+        has_definite_length =
+          !!item_hash[:variants][experience[:variant_index] || 0]&.dig(:length)
+
+        if has_definite_length
+          experience[:status] = :done
+        else
+          grace_period = Config.hash.deep_fetch(
+            :item,
+            :indefinite_in_progress_grace_period_days,
+          )
 
-        return [:done, last_end_date] if indefinite_in_progress_grace_period_is_over
+          indefinite_in_progress_grace_period_is_over =
+            (Date.today - grace_period) > experience[:last_end_date]
 
-        [:in_progress, last_end_date]
+          if indefinite_in_progress_grace_period_is_over
+            experience[:status] = :done
+          end
+        end
       end
     end
   end

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

@@ -6,13 +6,6 @@ module Reading
       # 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.

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

@@ -1,4 +1,4 @@
-require_relative "spans_validator"
+require_relative 'spans_validator'
 
 module Reading
   module Parsing
@@ -10,13 +10,11 @@ module Reading
         class DatesAndHeadTransformer
           using Util::HashArrayDeepFetch
 
-          private attr_reader :config, :parsed_row, :head_index
+          private attr_reader :parsed_row, :head_index
 
           # @param parsed_row [Hash] a parsed row (the intermediate hash).
           # @param head_index [Integer] current item's position in the Head column.
-          # @param config [Hash] an entire config.
-          def initialize(parsed_row, head_index, config)
-            @config = config
+          def initialize(parsed_row, head_index)
             @parsed_row = parsed_row
             @head_index = head_index
           end
@@ -42,8 +40,7 @@ module Reading
             }.presence
 
             if experiences_with_dates
-              # Raises an error if any sequence of dates does not make sense.
-              Experiences::SpansValidator.validate(experiences_with_dates, config)
+              Experiences::SpansValidator.validate(experiences_with_dates)
             end
 
             experiences_with_dates
@@ -54,13 +51,13 @@ module Reading
           # A shortcut to the experience template.
           # @return [Hash]
           def template
-            config.deep_fetch(:item, :template, :experiences).first
+            Config.hash.deep_fetch(:item, :template, :experiences).first
           end
 
           # A shortcut to the span template.
           # @return [Hash]
           def span_template
-            config.deep_fetch(:item, :template, :experiences, 0, :spans).first
+            Config.hash.deep_fetch(:item, :template, :experiences, 0, :spans).first
           end
 
           # The :spans sub-attribute for the given pair of date entries.
@@ -84,8 +81,10 @@ module Reading
             end
 
             variant_index = (start_entry[:variant] || 1).to_i - 1
-            length = Attributes::Shared.length(parsed_row[:sources]&.dig(variant_index)) ||
-              Attributes::Shared.length(parsed_row[:length])
+            format = parsed_row[:sources]&.dig(variant_index)&.dig(:format) ||
+              parsed_row[:head][head_index][:format]
+            length = Attributes::Shared.length(parsed_row[:sources]&.dig(variant_index), format:) ||
+              Attributes::Shared.length(parsed_row[:length], format:)
 
             [
               {

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

@@ -1,4 +1,4 @@
-require_relative "spans_validator"
+require_relative 'spans_validator'
 
 module Reading
   module Parsing
@@ -16,13 +16,13 @@ module Reading
           # many days, for example.
           AVERAGE_DAYS_IN_A_MONTH = 30.437r
 
-          private attr_reader :parsed_row, :config
+          private attr_reader :parsed_row, :head_index
 
           # @param parsed_row [Hash] a parsed row (the intermediate hash).
-          # @param config [Hash] an entire config
-          def initialize(parsed_row, config)
+          # @param head_index [Integer] current item's position in the Head column.
+          def initialize(parsed_row, head_index)
             @parsed_row = parsed_row
-            @config = config
+            @head_index = head_index
           end
 
           # Extracts experiences from the parsed row.
@@ -37,8 +37,7 @@ module Reading
               }
             }
 
-            # Raises an error if experiences overlap or are out of order.
-            Experiences::SpansValidator.validate(experiences, config, history_column: true)
+            Experiences::SpansValidator.validate(experiences, history_column: true)
 
             experiences
           end
@@ -48,7 +47,7 @@ module Reading
           # A shortcut to the span template.
           # @return [Hash]
           def span_template
-            @span_template ||= config.deep_fetch(:item, :template, :experiences, 0, :spans).first
+            @span_template ||= Config.hash.deep_fetch(:item, :template, :experiences, 0, :spans).first
           end
 
           # The :spans sub-attribute for the given History column entries.
@@ -154,6 +153,12 @@ module Reading
               raise InvalidHistoryError, "Missing or incomplete first date"
             end
 
+            if entry[:planned] || (active[:planned] && !start_day)
+              active[:planned] = true
+            elsif active[:planned] && start_day
+              active[:planned] = false
+            end
+
             duplicate_open_range = !start_day && active[:open_range]
             date_range = date_range(entry, active, duplicate_open_range:)
 
@@ -165,9 +170,13 @@ module Reading
             end
             active[:after_single_date] = !date_range
 
+            variant_index = (entry[:variant_index] || 1).to_i - 1
+            format = parsed_row[:sources]&.dig(variant_index)&.dig(:format) ||
+              parsed_row[:head][head_index][:format]
+
             amount =
-              Attributes::Shared.length(entry, key_name: :amount, ignore_repetitions: true) ||
-              Attributes::Shared.length(parsed_row[:length], episodic: true)
+              Attributes::Shared.length(entry, format:, key_name: :amount, ignore_repetitions: true) ||
+              Attributes::Shared.length(parsed_row[:length], format:, episodic: true)
             active[:amount] = amount if amount
 
             progress = Attributes::Shared.progress(entry)
@@ -178,7 +187,7 @@ module Reading
             # https://github.com/fpsvogel/reading/blob/main/doc/csv-format.md#history-pages-and-stopping-points-books
             if !amount && progress
               if progress.is_a? Float
-                total_length = Attributes::Shared.length(parsed_row[:length])
+                total_length = Attributes::Shared.length(parsed_row[:length], format:)
                 amount = total_length * progress
               else
                 amount = progress
@@ -202,7 +211,9 @@ module Reading
               span_without_dates = {
                 dates: nil,
                 amount: daily_amount || span_template[:amount],
-                progress: (progress unless amount_from_progress) || span_template[:progress],
+                progress: (progress unless amount_from_progress) ||
+                  (0.0 if entry[:planned] || active[:planned]) ||
+                  span_template[:progress],
                 name: entry[:name] || span_template[:name],
                 favorite?: !!entry[:favorite] || span_template[:favorite?],
                 # Temporary keys (not in the final item data) for marking
@@ -213,17 +224,15 @@ module Reading
                 amount_from_progress: amount_from_progress,
               }
 
-              if entry[:planned] || (active[:planned] && !start_day)
+              if entry[:planned] || active[:planned]
                 date = nil
-                active[:planned] = true
               end
 
               key = [date, span_without_dates[:name]]
 
-              # When any entry in an open range lacks a name, add a random
-              # number to the key so that it does not overwrite a different
-              # entry in the open range that also lacks a name.
-              if in_open_range && !entry[:name]
+              # For entries in an open range, add a random number to the key to
+              # avoid overwriting entries with the same name, or lacking a name.
+              if in_open_range
                 key << rand
               end