reading 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 531b4f54f11eed2f638079efbc0542977287d3ca887bea04a0785b6ca10c45fe
-  data.tar.gz: 58881344b75fc84041275d3ad9b84955f03d53ff8ca35f09932509b584c8b218
+  metadata.gz: ecba33e4bbdb2dd11482113bf46d6196b17c89e2274e574b2286818f309c9ccb
+  data.tar.gz: 95d094b19fd4509e8608f5db414062e633ba6665c949526cd34c271314db6845
 SHA512:
-  metadata.gz: 3539806e8c4472ba98d1ac19c862989a21d25782e4ec94ac04a3dfd4a3f30509187dce4ee6fa86fc189f742e19e2e649ffcf94f5e539cc1bc576856748b9adf6
-  data.tar.gz: 1be98e8aa5fc04a87aae46832cc981a49d3b725eeeaee2c6b75f1d723cf907d2e6567b9474022a5b19bc113db3555a7d358ec924c469f269d361b440d1963ca2
+  metadata.gz: ccfaace79d20ab57ab73349732735858049f217f3d0ad86408ae49b0f0f20591032dffd30e30d3f64d8c2644561d0b68e609e07398f3923fc85f4d25421504a6
+  data.tar.gz: 578c7f8389d12eda16a30f2d702a944a92dd931e62fa4db4908521ca1d1a01ca0fa0100d96b32f6e624fec1e7abf0f907417fc3043ce0aabe605fdde5b2c181c

data/bin/reading

@@ -26,6 +26,6 @@ if ARGV[1]
   config = { enabled_columns: }
 end
 
-items = Reading.parse(stream: input, config:)
+items = Reading.parse(stream: input, config:, hash_output: true)
 
 ap items

data/bin/readingfile

@@ -7,8 +7,8 @@
 #   reading "<file path>" "<optional comma-separated names of enabled columns>"
 #
 # Examples:
-#   reading '/home/alex/reading.csv'
-#   reading '/home/alex/reading.csv' 'head, sources'
+#   reading '/home/felipe/reading.csv'
+#   reading '/home/felipe/reading.csv' 'head, sources'
 
 
 require_relative "../lib/reading"
@@ -17,7 +17,7 @@ require "debug"
 
 path = ARGV[0]
 unless path
-  raise ArgumentError, "CSV path argument required, such as '/home/alex/reading.csv'"
+  raise ArgumentError, "CSV path argument required, such as '/home/felipe/reading.csv'"
 end
 
 config = {}
@@ -26,6 +26,6 @@ if ARGV[1]
   config = { enabled_columns: }
 end
 
-items = Reading.parse(path, config:)
+items = Reading.parse(path, config:, hash_output: true)
 
 ap items

data/lib/reading/config.rb

@@ -94,61 +94,83 @@ module Reading
             "librivox.org"        => "LibriVox",
             "tv.apple.com"        => "Apple TV",
           },
-        # The structure of an item, along with default values.
-        # Wherever an array of hashes ends up with no data (i.e. equal to the
-        # value in the template), it is collapsed into an empty array.
-        # E.g. the row "|Dracula||🤝🏼book club" is parsed to a Struct analogous to:
-        # {
-        #   rating: nil,
-        #   author: nil,
-        #   title: "Dracula",
-        #   genres: [],
-        #   variants: [],
-        #   experiences: [{ spans: [], group: "book club", variant_index: 0 }],
-        #   notes: [],
-        # }
-        item_template:
+        item:
           {
-            rating: nil,
-            author: nil,
-            title: nil,
-            genres: [],
-            variants:
-              [{
-                format: nil,
-                series:
+            # After how many days of no activity an item of indefinite length
+            # (e.g. a podcast) should change its status from :in_progress to :done.
+            indefinite_in_progress_grace_period_days: 30,
+            view:
+              {
+                name_separator: " 〜 ",
+                url_from_isbn: "https://www.goodreads.com/book/isbn?isbn=%{isbn}",
+                # Items rated this or above get a star. If nil, number ratings are shown instead.
+                minimum_rating_for_star: 5,
+                types:
+                  {
+                    book: { emoji: "📕", from_formats: %i[print ebook audiobook pdf] },
+                    course: { emoji: "🏫", from_formats: %i[website] },
+                    piece: { emoji: "✏️" },
+                    video: { emoji: "🎞️" },
+                    audio: { emoji: "🎤" },
+                  },
+                default_type: :book,
+              },
+            # The structure of an item, along with default values.
+            # Wherever an array of hashes ends up with no data (i.e. equal to the
+            # value in the template), it is collapsed into an empty array.
+            # E.g. the row "|Dracula||🤝🏼book club" is parsed to an Item analogous to:
+            # {
+            #   rating: nil,
+            #   author: nil,
+            #   title: "Dracula",
+            #   genres: [],
+            #   variants: [],
+            #   experiences: [{ spans: [], group: "book club", variant_index: 0 }],
+            #   notes: [],
+            # }
+            template:
+              {
+                rating: nil,
+                author: nil,
+                title: nil,
+                genres: [],
+                variants:
                   [{
-                    name: nil,
-                    volume: nil,
+                    format: nil,
+                    series:
+                      [{
+                        name: nil,
+                        volume: nil,
+                      }],
+                    sources:
+                      [{
+                        name: nil,
+                        url: nil,
+                      }],
+                    isbn: nil,
+                    length: nil,
+                    extra_info: [],
                   }],
-                sources:
+                experiences:
                   [{
-                    name: nil,
-                    url: nil,
+                    spans:
+                      [{
+                        dates: nil,
+                        amount: 0,
+                        progress: nil,
+                        name: nil,
+                        favorite?: false,
+                      }],
+                    group: nil,
+                    variant_index: 0,
                   }],
-                isbn: nil,
-                length: nil,
-                extra_info: [],
-              }],
-            experiences:
-              [{
-                spans:
+                notes:
                   [{
-                    dates: nil,
-                    amount: 0,
-                    progress: nil,
-                    name: nil,
-                    favorite?: false,
+                    blurb?: false,
+                    private?: false,
+                    content: nil,
                   }],
-                group: nil,
-                variant_index: 0,
-              }],
-            notes:
-              [{
-                blurb?: false,
-                private?: false,
-                content: nil,
-              }],
+              },
           },
       }
     end

data/lib/reading/filter.rb

@@ -0,0 +1,95 @@
+module Reading
+  # Filters Items based on given criteria.
+  class Filter
+    class << self
+      # Filters Items based on given criteria, and returns them sorted by last
+      # end date or (where there is none) status, where :planned Items are
+      # placed last, and :in_progress just before those.
+      # @param items [Array<Item>]
+      # @param no_sort [Boolean] to preserve the original ordering of the Items.
+      # @param criteria [Hash] one or more of the filters defined in by_x methods below.
+      # @return [Array<Item>]
+      # @raise [ArgumentError] if criteria are invalid or missing.
+      def by(items:, no_sort: false, **criteria)
+        validate_criteria(**criteria)
+
+        filtered = criteria.each.with_object(items.dup) { |(criterion, arg), filtered_items|
+          send("#{CRITERIA_PREFIX}#{criterion}#{CRITERIA_SUFFIX}", filtered_items, arg)
+        }
+
+        return filtered if no_sort
+
+        filtered.sort_by { |item|
+          if item.done?
+            item.last_end_date.strftime("%Y-%m-%d")
+          else
+            item.status.to_s
+          end
+        }
+      end
+
+      private
+
+      CRITERIA_PREFIX = "by_".freeze
+      CRITERIA_SUFFIX = "!".freeze
+
+      # Checks that the args match real Filter criteria.
+      # @param criteria [Hash] must include only one or more of the criteria
+      #   defined in by_x methods below.
+      # @raise [ArgumentError] if criteria are empty or invalid.
+      def validate_criteria(**criteria)
+        available_criteria = private_methods(false)
+          .select { _1.to_s.start_with?(CRITERIA_PREFIX) }
+          .map { _1.to_s.delete_prefix(CRITERIA_PREFIX).delete_suffix(CRITERIA_SUFFIX).to_sym }
+
+        if criteria.empty?
+          raise ArgumentError, "Filter requires at least one of these criteria: #{available_criteria}"
+        end
+
+        unrecognized_criteria = criteria.keys - available_criteria
+        if unrecognized_criteria.any?
+          raise ArgumentError, "Unrecognized criteria passed to Filter: #{unrecognized_criteria}"
+        end
+      end
+
+      # Mutates the given array of Items to select only Items with a rating
+      # greater than or equal to the given minimum.
+      # @param items [Array<Item>]
+      # @param minimum_rating [Integer]
+      def by_minimum_rating!(items, minimum_rating)
+        return items unless minimum_rating
+
+        items.select! do |item|
+          if item.rating
+            item.rating >= minimum_rating
+          end
+        end
+      end
+
+      # Mutates the given array of Items to exclude Items with genres including
+      # any of the given genres.
+      # @param items [Array<Item>]
+      # @param excluded_genres [Array<String>]
+      def by_excluded_genres!(items, excluded_genres)
+        return items unless excluded_genres&.any?
+
+        items.select! do |item|
+          overlapping = item.genres & excluded_genres
+          overlapping.empty?
+        end
+      end
+
+      # Mutates the given array of Items to select only Items with a status
+      # equal to the given status (or one of the given statuses).
+      # @param items [Array<Item>]
+      # @param statuses [Symbol, Array<Symbol>]
+      def by_status!(items, statuses)
+        statuses = Array(statuses)
+
+        items.select! do |item|
+          statuses.include? item.status
+        end
+      end
+    end
+  end
+end

data/lib/reading/item/time_length.rb

@@ -1,7 +1,8 @@
 module Reading
-  module Item
-    # For coercion, see https://www.mutuallyhuman.com/blog/class-coercion-in-ruby/
-    class TimeLength
+  class Item
+    # The length of an item when it is a time, as opposed to pages. (Pages are
+    # represented simply with an Integer.)
+    class Item::TimeLength
       include Comparable
 
       attr_reader :value # in total minutes
@@ -11,7 +12,7 @@ module Reading
         @value = value
       end
 
-      # Builds a TimeLength from a string.
+      # Builds an Item::TimeLength from a string.
       # @param string [String] a time duration in "h:mm" format.
       # @return [TimeLength]
       def self.parse(string)
@@ -65,12 +66,12 @@ module Reading
       # @param other [TimeLength, Integer] must be zero if it's an Integer.
       # @return [TimeLength]
       def +(other)
-        if other.is_a? TimeLength
+        if other.is_a? Item::TimeLength
           self.class.new(value + other.value)
         elsif other.zero?
           self
         else
-          raise TypeError, "#{other.class} can't be added to TimeLength."
+          raise TypeError, "#{other.class} can't be added to Item::TimeLength."
         end
       end
 
@@ -78,12 +79,12 @@ module Reading
       # @param other [TimeLength, Integer] must be zero if it's an Integer.
       # @return [TimeLength]
       def -(other)
-        if other.is_a? TimeLength
+        if other.is_a? Item::TimeLength
           self.class.new(value - other.value)
         elsif other.zero?
           self
         else
-          raise TypeError, "#{other.class} can't be subtracted from TimeLength."
+          raise TypeError, "#{other.class} can't be subtracted from Item::TimeLength."
         end
       end
 
@@ -108,6 +109,7 @@ module Reading
       end
 
       # TODO: add coercion for pages (nonzero Integer)
+      # See https://www.mutuallyhuman.com/blog/class-coercion-in-ruby
       # @param other [Integer] must be zero.
       def coerce(other)
         if other.zero?
@@ -127,7 +129,7 @@ module Reading
           return 1
         end
 
-        unless other.is_a? TimeLength
+        unless other.is_a? Item::TimeLength
           raise TypeError, "TimeLength can't be compared to #{other.class} #{other}."
         end
 

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

@@ -4,7 +4,7 @@ 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
 

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

@@ -23,7 +23,7 @@ module Reading
 
           # 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
@@ -54,13 +54,13 @@ module Reading
           # A shortcut to the experience template.
           # @return [Hash]
           def template
-            config.deep_fetch(:item_template, :experiences).first
+            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
+            config.deep_fetch(:item, :template, :experiences, 0, :spans).first
           end
 
           # The :spans sub-attribute for the given pair of date entries.

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

@@ -27,7 +27,7 @@ module Reading
 
           # 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
             experiences = parsed_row[:history].map { |entries|
               {
@@ -48,13 +48,13 @@ 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.deep_fetch(:item, :template, :experiences, 0, :spans).first
           end
 
           # The :spans sub-attribute for the given History column entries.
           # @param entries [Array<Hash>] History entries for one experience.
           # @return [Array<Hash>] an array of spans; see
-          #   Config#default_config[:item_template][:experiences].first[:spans]
+          #   Config#default_config[:item][:template][:experiences].first[:spans]
           def spans_from_history_entries(entries)
             daily_spans = {}
             active = {
@@ -304,11 +304,11 @@ module Reading
           # Distributes an amount across the given date(s).
           # @param date_or_range [Date, Range<Date>] the date or range across
           #   which the amount will be split up.
-          # @param amount [Float, Integer, Reading::Item::TimeLength] amount in
+          # @param amount [Float, Integer, Item::TimeLength] amount in
           #   pages or time.
           # @param repetitions [Integer] e.g. "x4" in a History entry.
           # @param frequency [Integer] e.g. "/week" in a History entry.
-          # @return [Hash{Date => Float, Integer, Reading::Item::TimeLength}]
+          # @return [Hash{Date => Float, Integer, Item::TimeLength}]
           def distribute_amount_across_date_range(date_or_range, amount, repetitions, frequency)
             unless amount
               raise InvalidHistoryError, "Missing length or amount"

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

@@ -59,7 +59,7 @@ module Reading
             # 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
+              _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 }

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

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

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

@@ -6,7 +6,7 @@ module Reading
         # @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]
+        #   Config#default_config[:item][:template][:notes]
         def transform_from_parsed(parsed_row, _head_index)
           parsed_row[:notes]&.map { |note|
             {

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

@@ -6,7 +6,7 @@ module Reading
         # 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]
+        # @return [Float, Integer, Item::TimeLength]
         def self.progress(hash)
           hash[:progress_percent]&.to_f&./(100) ||
             hash[:progress_pages]&.to_i ||
@@ -29,7 +29,7 @@ module Reading
         #   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]
+        # @return [Float, Integer, Item::TimeLength]
         def self.length(hash, key_name: :length, episodic: false, ignore_repetitions: false)
           return nil unless hash
 

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

@@ -8,7 +8,7 @@ module Reading
         # @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]
+        #   Config#default_config[:item][:template][:variants]
         def transform_from_parsed(parsed_row, head_index)
           head = parsed_row[:head][head_index]
 
@@ -29,7 +29,7 @@ module Reading
         # A shortcut to the variant template.
         # @return [Hash]
         def template
-          config.deep_fetch(:item_template, :variants).first
+          config.deep_fetch(:item, :template, :variants).first
         end
 
         # The :series sub-attribute for the given parsed hash.

data/lib/reading/parsing/csv.rb

@@ -3,7 +3,6 @@ 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"
@@ -11,6 +10,7 @@ require_relative "../errors"
 
 # Used just here.
 require_relative "../config"
+require_relative "../item"
 require_relative "parser"
 require_relative "transformer"
 
@@ -18,7 +18,7 @@ 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).
+    # parses it into an array of Items.
     #
     # Parsing happens in two steps:
     #   (1) Parse a row string into an intermediate hash representing the columns.
@@ -31,33 +31,40 @@ module Reading
     # inspired by the Parslet gem: https://kschiess.github.io/parslet/transform.html
     #
     class CSV
-      using Util::HashToStruct
-
-      private attr_reader :parser, :transformer
+      private attr_reader :parser, :transformer, :hash_output, :item_view
 
       # 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 path [String] path to the CSV file; used if no stream is given.
       # @param stream [Object] an object responding to #each_linewith CSV row(s);
-      #   used if no path is given.
+      #   if nil, path is used instead.
       # @param config [Hash] a custom config which overrides the defaults,
       #   e.g. { errors: { styling: :html } }
-      def initialize(path = nil, stream: nil, config: {})
+      # @param hash_output [Boolean] whether an array of raw Hashes should be
+      #   returned, without Items being created from them.
+      # @param view [Class, nil, Boolean] the class that will be used to build
+      #   each Item's 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(path = nil, stream: nil, config: {}, hash_output: false, item_view: Item::View)
         validate_path_or_stream(path, stream)
         full_config = Config.new(config).hash
 
         @path = path
         @stream = stream
+        @hash_output = hash_output
+        @item_view = item_view
         @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).
+      # @return [Array<Item>] an array of Items like the template in
+      #   Config#default_config[:item][:template]. The Items are identical in
+      #   structure to that Hash (with every inner Hash replaced by a Data for
+      #   dot access).
       def parse
-        input = @path ? File.open(@path) : @stream
+        input = @stream || File.open(@path)
         items = []
 
         input.each_line do |line|
@@ -72,7 +79,11 @@ module Reading
           items += row_items
         end
 
-        items.map(&:to_struct)
+        if hash_output
+          items
+        else
+          items.map { |item_hash| Item.new(item_hash, view: item_view) }
+        end
       ensure
         input&.close if input.respond_to?(:close)
       end
@@ -83,14 +94,14 @@ module Reading
       # @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 stream && stream.respond_to?(:each_line)
+          return true
+        elsif 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."

data/lib/reading/parsing/parser.rb

@@ -75,8 +75,8 @@ module Reading
       # @return [Hash{Class => String}] a hash whose keys are classes inheriting
       #   Parsing::Rows::Column.
       def extract_columns(string)
-        clean_string = string.dup.force_encoding(Encoding::UTF_8)
-        column_strings = clean_string.split(config.fetch(:column_separator))
+        string = string.dup.force_encoding(Encoding::UTF_8)
+        column_strings = string.split(config.fetch(:column_separator))
 
         row_types = [Rows::Regular, Rows::CompactPlanned, Rows::Comment]
         column_classes = row_types

data/lib/reading/parsing/transformer.rb

@@ -14,7 +14,7 @@ module Reading
     # Transforms an intermediate hash (parsed from a CSV row) into item data.
     # While the intermediate hash mirrors the structure of a row, the output of
     # Transformer is based around item attributes, which are listed in
-    # Config#default_config[:item_template] and in the files in parsing/attributes.
+    # Config#default_config[:item][:template] and in the files in parsing/attributes.
     #
     class Transformer
       using Util::HashArrayDeepFetch
@@ -34,13 +34,13 @@ module Reading
       # @param parsed_row [Hash{Symbol => Hash, Array}] output from
       #   Parsing::Parser#parse_row_to_intermediate_hash.
       # @return [Array<Hash>] an array of Hashes like the template in
-      #   Config#default_config[:item_template].
+      #   Config#default_config[:item][:template].
       def transform_intermediate_hash_to_item_hashes(parsed_row)
         if parsed_row[:head].blank?
           raise InvalidHeadError, "Blank or missing Head column"
         end
 
-        template = config.fetch(:item_template)
+        template = config.deep_fetch(:item, :template)
 
         parsed_row[:head].map.with_index { |_head, head_index|
           template.map { |attribute_name, default_value|
@@ -58,7 +58,7 @@ module Reading
       # Sets the attributes classes which do all the transforming work.
       # See parsing/attributes/*.
       def set_attributes
-        @attributes ||= config.fetch(:item_template).map { |attribute_name, _default|
+        @attributes ||= config.deep_fetch(:item, :template).map { |attribute_name, _default|
           attribute_name_camelcase = attribute_name.to_s.split("_").map(&:capitalize).join
           attribute_class = Attributes.const_get(attribute_name_camelcase)
 

data/lib/reading/util/hash_to_data.rb

@@ -0,0 +1,30 @@
+module Reading
+  module Util
+    # Converts a Hash to a Data. Converts inner hashes (and inner arrays of hashes) as well.
+    module HashToData
+      refine Hash do
+        # @return [Data]
+        def to_data
+          MEMOIZED_DATAS[keys] ||= Data.define(*keys)
+          data_class = MEMOIZED_DATAS[keys]
+
+          data_values = transform_values { |v|
+            if v.is_a?(Hash)
+              v.to_data
+            elsif v.is_a?(Array) && v.all? { |el| el.is_a?(Hash) }
+              v.map(&:to_data)
+            else
+              v
+            end
+          }.values
+
+          data_class.new(*data_values)
+        end
+      end
+
+      private
+
+      MEMOIZED_DATAS = {}
+    end
+  end
+end

data/lib/reading/version.rb

@@ -1,3 +1,3 @@
 module Reading
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/reading.rb

@@ -1,8 +1,27 @@
 require_relative "reading/parsing/csv"
+require_relative "reading/filter"
+require_relative "reading/config"
 require_relative "reading/item/time_length.rb"
 
 # The gem's public API. See https://github.com/fpsvogel/reading#usage
-
+#
+# Architectural overview:
+#
+#                 (CSV input)                    (Items)     (filtered Items)
+#                      |                          Λ   |           Λ
+#                      |                          |   ·---.       |
+#                      |                          |       |       |
+#                      V                          |       V       |
+#                   ::parse                       |     ::filter  |
+#                      |                          |          |    |
+#                      |            .----------> Item        Filter
+#  Config,             |           /             / \
+#  errors.rb ----- Parsing::CSV --·    Item::View  Item::TimeLength
+#                     / \
+#      Parsing::Parser  Parsing::Transformer
+#             |                 |
+#      parsing/attributes/*  parsing/rows/*
+#
 module Reading
   # Parses a CSV file or string. See Parsing::CSV#initialize and #parse for details.
   def self.parse(...)
@@ -10,9 +29,21 @@ module Reading
     csv.parse
   end
 
+  # Filters an array of Items. See Filter::by for details.
+  def self.filter(...)
+    Filter.by(...)
+  end
+
+  # The default config.
+  # @return [Hash]
+  def self.default_config
+    Config.new.hash
+  end
+
+  # A shortcut for getting a time from a string.
   # @param string [String] a time duration in "h:mm" format.
-  # @return [Reading::Item::TimeLength]
+  # @return [Item::TimeLength]
   def self.time(string)
-    Reading::Item::TimeLength.parse(string)
+    Item::TimeLength.parse(string)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reading
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Felipe Vogel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-05 00:00:00.000000000 Z
+date: 2023-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pastel
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: shoulda-context
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: pretty-diffs
   requirement: !ruby/object:Gem::Requirement
@@ -122,7 +136,10 @@ files:
 - lib/reading.rb
 - lib/reading/config.rb
 - lib/reading/errors.rb
+- lib/reading/filter.rb
+- lib/reading/item.rb
 - lib/reading/item/time_length.rb
+- lib/reading/item/view.rb
 - lib/reading/parsing/attributes/attribute.rb
 - lib/reading/parsing/attributes/author.rb
 - lib/reading/parsing/attributes/experiences.rb
@@ -156,7 +173,7 @@ files:
 - lib/reading/util/hash_array_deep_fetch.rb
 - lib/reading/util/hash_compact_by_template.rb
 - lib/reading/util/hash_deep_merge.rb
-- lib/reading/util/hash_to_struct.rb
+- lib/reading/util/hash_to_data.rb
 - lib/reading/util/numeric_to_i_if_whole.rb
 - lib/reading/util/string_remove.rb
 - lib/reading/util/string_truncate.rb

data/lib/reading/util/hash_to_struct.rb

@@ -1,30 +0,0 @@
-module Reading
-  module Util
-    # Converts a Hash to a Struct. Converts inner hashes (and inner arrays of hashes) as well.
-    module HashToStruct
-      refine Hash do
-        # @return [Struct]
-        def to_struct
-          MEMOIZED_STRUCTS[keys] ||= Struct.new(*keys)
-          struct_class = MEMOIZED_STRUCTS[keys]
-
-          struct_values = transform_values { |v|
-            if v.is_a?(Hash)
-              v.to_struct
-            elsif v.is_a?(Array) && v.all? { |el| el.is_a?(Hash) }
-              v.map(&:to_struct)
-            else
-              v
-            end
-          }.values
-
-          struct_class.new(*struct_values)
-        end
-      end
-
-      private
-
-      MEMOIZED_STRUCTS = {}
-    end
-  end
-end