reading 0.6.1 → 0.8.0

data/lib/reading/item/view.rb

@@ -0,0 +1,121 @@
+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.
+      # @param config [Hash] an entire config.
+      def initialize(item, config)
+        @genres = item.genres
+        @rating = extract_star_or_rating(item, config)
+        @isbn, @url, variant = extract_first_source_info(item, config)
+        @name = extract_name(item, variant, config)
+        @type_emoji = extract_type_emoji(variant&.format, config)
+        @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]
+      # @param config [Hash] an entire config.
+      # @return [String, Integer, Float]
+      def extract_star_or_rating(item, config)
+        minimum_rating = config.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]
+      # @param config [Hash] an entire config.
+      # @return [Array(String, String, Symbol, Array<String>)]
+      def extract_first_source_info(item, config)
+        item.variants.map { |variant|
+          isbn = variant.isbn
+          if isbn
+            url = config.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.
+      # @param config [Hash] an entire config.
+      # @return [String]
+      def extract_name(item, variant, config)
+        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.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]
+      # @param config [Hash] an entire config.
+      # @return [String]
+      def extract_type_emoji(format, config)
+        types = config.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.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,117 @@
+require "forwardable"
+
+require_relative "item/view"
+require_relative "config"
+require_relative "util/hash_to_data"
+require_relative "util/hash_array_deep_fetch"
+
+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 :attributes, :config
+    attr_reader :view, :status, :last_end_date
+
+    def_delegators :attributes, *ATTRIBUTES
+
+    # @param item_hash [Hash] a parsed item like the template in
+    #   Config#default_config[:item][:template].
+    # @param config [Hash] an entire config.
+    # @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
+
+      add_missing_attributes_with_filler_values(item_hash, config)
+
+      @attributes = item_hash.to_data
+      @config = config
+
+      @status, @last_end_date = get_status_and_last_end_date
+      @view = view.new(self, config) if view
+    end
+
+    # Whether this item is done.
+    # @return [Boolean]
+    def done?
+      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 }
+    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
+
+      attributes == other.send(:attributes)
+    end
+
+    private
+
+    # For each missing item attribute (key in config[: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|
+        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. 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.
+    # @return [Array(Symbol, Date)]
+    def get_status_and_last_end_date
+      return [:planned, nil] if experiences.none? || experiences.flat_map(&:spans).none?
+
+      experiences_with_spans_with_dates = experiences
+        .select { |experience| experience.spans.any? { |span| span.dates } }
+
+      return [:planned, nil] unless experiences_with_spans_with_dates.any?
+
+      last_end_date = experiences_with_spans_with_dates
+        .last
+        .spans
+        .select { |span| span.dates }
+        .last
+        .dates
+        .end
+
+      return [:in_progress, nil] unless last_end_date
+
+      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
+
+        return [:done, last_end_date] if indefinite_in_progress_grace_period_is_over
+
+        [:in_progress, last_end_date]
+      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

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

@@ -0,0 +1,106 @@
+require_relative "spans_validator"
+
+module Reading
+  module Parsing
+    module Attributes
+      class Experiences < Attribute
+        # Experiences#transform_from_parsed delegates to this class when the
+        # History column is blank (i.e. when experiences should be extracted
+        # from the Start Dates, End Dates, and Head columns).
+        class DatesAndHeadTransformer
+          using Util::HashArrayDeepFetch
+
+          private attr_reader :config, :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
+            @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]
+          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
+            # the larger of the two.
+            start_dates = Array.new(size) { |i| parsed_row[:start_dates]&.dig(i) || {} }
+            end_dates = Array.new(size) { |i| parsed_row[:end_dates]&.dig(i) || nil }
+
+            start_end_dates = start_dates.zip(end_dates).presence || [[{}, nil]]
+
+            experiences_with_dates = start_end_dates.map { |start_entry, end_entry|
+              {
+                spans: spans(start_entry, end_entry),
+                group: start_entry[:group],
+                variant_index: (start_entry[:variant] || 1).to_i - 1,
+              }.map { |k, v| [k, v || template.fetch(k)] }.to_h
+            }.presence
+
+            if experiences_with_dates
+              # Raises an error if any sequence of dates does not make sense.
+              Experiences::SpansValidator.validate(experiences_with_dates, config)
+            end
+
+            experiences_with_dates
+          end
+
+          private
+
+          # A shortcut to the experience template.
+          # @return [Hash]
+          def template
+            config.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
+          end
+
+          # The :spans sub-attribute for the given pair of date entries.
+          # single span in an array.
+          # @param start_entry [Hash] a parsed entry in the Start Dates column.
+          # @param end_entry [Hash] a parsed entry in the End Dates column.
+          # @return [Array(Hash)] an array containing a single span representing
+          #   the start and end date.
+          def spans(start_entry, end_entry)
+            if !start_entry&.dig(:date) && !end_entry&.dig(:date)
+              dates = nil
+            else
+              dates = [start_entry, end_entry].map { |date_hash|
+                begin
+                  Date.parse(date_hash[:date]) if date_hash&.dig(:date)
+                rescue Date::Error
+                  raise InvalidDateError, "Unparsable date \"#{date_hash[:date]}\""
+                end
+              }
+              dates = dates[0]..dates[1]
+            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])
+
+            [
+              {
+                dates: dates,
+                amount: (length if dates),
+                progress: Attributes::Shared.progress(start_entry) ||
+                  Attributes::Shared.progress(parsed_row[:head][head_index]) ||
+                  (1.0 if end_entry),
+                name: span_template.fetch(:name),
+                favorite?: span_template.fetch(:favorite?),
+              }.map { |k, v| [k, v || span_template.fetch(k)] }.to_h
+            ]
+          end
+        end
+      end
+    end
+  end
+end