reading 0.7.0 → 0.9.0

data/lib/reading/item/view.rb

@@ -0,0 +1,116 @@
+module Reading
+  class Item
+    # A view object for an Item, providing shortcuts to information that is handy
+    # to show (for example) on a webpage.
+    class View
+      using Util::HashArrayDeepFetch
+
+      attr_reader :name, :rating, :type_emoji, :genres, :date_or_status,
+        :isbn, :url, :experience_count, :groups, :blurb, :public_notes
+
+      # @param item [Item] the Item from which to extract view information.
+      def initialize(item)
+        @genres = item.genres
+        @rating = extract_star_or_rating(item)
+        @isbn, @url, variant = extract_first_source_info(item)
+        @name = extract_name(item, variant)
+        @type_emoji = extract_type_emoji(variant&.format)
+        @date_or_status = extract_date_or_status(item)
+        @experience_count = item.experiences.count
+        @groups = item.experiences.map(&:group).compact
+        @blurb = item.notes.find(&:blurb?)&.content
+        @public_notes = item.notes.reject(&:private?).reject(&:blurb?).map(&:content)
+      end
+
+      private
+
+      # A star (or nil if the item doesn't make the cut), or the number rating if
+      # star ratings are disabled.
+      # @param item [Item]
+      # @return [String, Integer, Float]
+      def extract_star_or_rating(item)
+        minimum_rating = Config.hash.deep_fetch(:item, :view, :minimum_rating_for_star)
+        if minimum_rating
+          "⭐" if item.rating && item.rating >= minimum_rating
+        else
+          item.rating
+        end
+      end
+
+
+      # The ISBN/ASIN, URL, format, and extra info of the first variant that has
+      # an ISBN/ASIN or URL. If an ISBN/ASIN is found first, it is used to build a
+      # Goodreads URL. If a URL is found first, the ISBN/ASIN is nil.
+      # @param item [Item]
+      # @return [Array(String, String, Symbol, Array<String>)]
+      def extract_first_source_info(item)
+        item.variants.map { |variant|
+          isbn = variant.isbn
+          if isbn
+            url = Config.hash.deep_fetch(:item, :view, :url_from_isbn).sub('%{isbn}', isbn)
+          else
+            url = variant.sources.map { |source| source.url }.compact.first
+          end
+
+          [isbn, url, variant]
+        }
+        .select { |isbn, url, _variant| isbn || url }
+        .first || [nil, nil, item.variants.first]
+      end
+
+      # The view name of the item.
+      # @param item [Item]
+      # @param variant [Data, nil] a variant from the Item.
+      # @return [String]
+      def extract_name(item, variant)
+        author_and_title = "#{item.author + " – " if item.author}#{item.title}"
+        return author_and_title if variant.nil?
+
+        unless variant.series.empty? && variant.extra_info.empty?
+          pretty_series = variant.series.map { |series|
+            if series.volume
+              "#{series.name}, ##{series.volume}"
+            else
+              "in #{series.name}"
+            end
+          }
+
+          name_separator = Config.hash.deep_fetch(:item, :view, :name_separator)
+          series_and_extra_info = name_separator +
+            (pretty_series + variant.extra_info).join(name_separator)
+        end
+
+        author_and_title + (series_and_extra_info || "")
+      end
+
+      # The emoji for the type that represents (encompasses) a given format.
+      # @param format [Symbol, nil]
+      # @return [String]
+      def extract_type_emoji(format)
+        types = Config.hash.deep_fetch(:item, :view, :types)
+
+        return types.deep_fetch(format, :emoji) if types.has_key?(format)
+
+        type = types
+          .find { |type, hash| hash[:from_formats]&.include?(format) }
+          &.first # key
+
+        types.deep_fetch(
+          type || Config.hash.deep_fetch(:item, :view, :default_type),
+          :emoji,
+        )
+      end
+
+      # The date (if done) or status, stringified.
+      # @param item [Item]
+      # @return [String]
+      def extract_date_or_status(item)
+        if item.done?
+          item.last_end_date&.strftime("%Y-%m-%d")
+        else
+          item.status.to_s.gsub('_', ' ')
+        end
+      end
+    end
+  end
+end

data/lib/reading/item.rb

@@ -0,0 +1,384 @@
+require 'forwardable'
+
+require_relative 'item/view'
+
+module Reading
+  # A wrapper for an item parsed from a CSV reading log, providing convenience
+  # methods beyond what the parser's raw Hash output can provide.
+  class Item
+    using Util::HashToData
+    using Util::HashArrayDeepFetch
+    extend Forwardable
+
+    ATTRIBUTES = %i[rating author title genres variants experiences notes]
+
+    private attr_reader :data
+    attr_reader :view
+
+    def_delegators :data, *ATTRIBUTES
+
+    # @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.
+    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)
+        add_statuses_and_last_end_dates!(item_hash)
+
+        @data = item_hash.to_data
+      end
+
+      @view = view.new(self) if view
+    end
+
+    # This item's status.
+    # @return [Symbol] :planned, :in_progress, or :done
+    def status
+      data.experiences.last&.status || :planned
+    end
+
+    # Whether this item is done.
+    # @return [Boolean]
+    def done?
+      status == :done
+    end
+
+    # 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.
+    # @other [Item]
+    # @return [Boolean]
+    def ==(other)
+      unless other.is_a?(Item)
+        raise ArgumentError, "An Item can be compared only with another Item."
+      end
+
+      data == other.send(:data)
+    end
+
+    private
+
+    # 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]
+    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
+        item_hash[k] = filler
+      end
+    end
+
+    # 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 add_statuses_and_last_end_dates!(item_hash)
+      item_hash[:experiences] = item_hash[:experiences].dup
+
+      item_hash[:experiences].each do |experience|
+        experience[:status] = :planned
+        experience[:last_end_date] = nil
+
+        next unless experience[:spans]&.any? { |span|
+          span[:dates]
+        }
+
+        experience[:status] = :in_progress
+
+        experience[:last_end_date] = experience[:spans]
+          .select { |span| span[:dates] }
+          .last[:dates]
+          .end
+
+        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,
+          )
+
+          indefinite_in_progress_grace_period_is_over =
+            (Date.today - grace_period) > experience[:last_end_date]
+
+          if indefinite_in_progress_grace_period_is_over
+            experience[:status] = :done
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,15 +4,8 @@ module Reading
       # 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].
+      # 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,20 +10,18 @@ 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
 
           # Extracts experiences from the parsed row.
           # @return [Array<Hash>] an array of experiences; see
-          #   Config#default_config[:item_template][:experiences]
+          #   Config#default_config[:item][:template][:experiences]
           def transform
             size = [parsed_row[:start_dates]&.count || 0, parsed_row[:end_dates]&.count || 0].max
             # Pad start dates with {} and end dates with nil up to the size of
@@ -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:)
 
             [
               {