reading 0.8.0 → 0.9.0

data/lib/reading/stats/grouping.rb

@@ -0,0 +1,243 @@
+module Reading
+  module Stats
+    # The part of the query right after the operation, which groups the results,
+    # e.g. "by genre, rating".
+    class Grouping
+      # Determines which group(s) the input indicates, and then groups the
+      # Items accordingly. For the groups and their actions, see the constants
+      # below.
+      # @param input [String] the query string.
+      # @param items [Array<Item>] the Items on which to run the operation.
+      # @return [Hash] the return value of the group action(s).
+      def self.group(input, items)
+        grouped_items = {}
+
+        match = input.match(REGEX)
+
+        if match
+          group_names = match[:groups]
+            .split(',')
+            .tap { _1.last.sub!(/(\w)\s+\w+/, '\1') }
+            .map(&:strip)
+            .map { _1.delete_suffix('s') }
+            .map(&:to_sym)
+
+          if group_names.uniq.count < group_names.count
+            raise InputError, "Each grouping can be applied only once in a query."
+          end
+
+          begin
+            return group_hash(items, group_names)
+          rescue InputError => e
+            raise e.class, "#{e.message} in \"#{input}\""
+          end
+        end
+
+        { all: items }
+      end
+
+      # Recursively builds a tree of groupings based on group_names.
+      # @group_names [Array<Symbol>]
+      # @items [Array<Item>]
+      # @return [Hash, Array<Item>]
+      private_class_method def self.group_hash(items, group_names)
+        return items if group_names.empty?
+
+        key = group_names.first
+        action = ACTIONS[key]
+
+        unless action
+          raise InputError, "Invalid grouping \"#{key}\""
+        end
+
+        action.call(items).transform_values do |grouped_items|
+          group_hash(grouped_items, group_names[1..])
+        end
+      end
+
+      private
+
+      INPUT_SPLIT = /\s+(?=[\w\-]+\s*(?:!=|=|!~|~|>=|>|<=|<))/
+
+      # Each action groups the given Items.
+      # @param items [Array<Item>]
+      # @return [Hash{Symbol => Array<Item>}] the Items separated into groups.
+      ACTIONS = {
+        rating: proc { |items|
+          items
+            .group_by(&:rating)
+            .reject { |rating, _items| rating.nil? }
+            .sort_by { |rating, _items| rating }
+            .reverse
+            .to_h
+        },
+        format: proc { |items|
+          groups = Hash.new { |h, k| h[k] = [] }
+
+          items.each do |item|
+            item.variants.group_by(&:format).each do |format, variants|
+              groups[format] << item.with_variants(variants)
+            end
+          end
+
+          groups.sort.to_h
+        },
+        source: proc { |items|
+          groups = Hash.new { |h, k| h[k] = [] }
+
+          items.each do |item|
+            item
+              .variants
+              .map { |variant|
+                variant.sources.map { |source|
+                  [variant, source.name || source.url]
+                }
+              }
+              .flatten(1)
+              .group_by { |_variant, source| source }
+              .transform_values { |variants_and_sources|
+                variants_and_sources.map(&:first)
+              }
+              .each do |source, variants|
+                groups[source] << item.with_variants(variants)
+              end
+          end
+
+          groups.sort.to_h
+        },
+        year: proc { |items|
+          begin_date = items
+            .map { _1.experiences.first&.spans&.first&.dates&.begin }
+            .compact
+            .min
+
+          if begin_date.nil?
+            {}
+          else
+            end_date = items
+              .flat_map { _1.experiences.map(&:last_end_date) }
+              .compact
+              .max
+
+            year_ranges = (begin_date.year..end_date.year).flat_map { |year|
+              beginning_of_year = Date.new(year, 1, 1)
+              end_of_year = Date.new(year + 1, 1, 1).prev_day
+
+              beginning_of_year..end_of_year
+            }
+
+            groups = year_ranges.map { [_1, []] }.to_h
+
+            groups.each do |year_range, year_items|
+              items.each do |item|
+                without_before = item.split(year_range.end.next_day).first
+                without_before_or_after = without_before&.split(year_range.begin)&.last
+
+                year_items << without_before_or_after if without_before_or_after
+              end
+            end
+
+            groups.transform_keys! { |year_range|
+              year_range.begin.year
+            }
+
+            groups
+          end
+        },
+        month: proc { |items|
+          begin_date = items
+            .map { _1.experiences.first&.spans&.first&.dates&.begin }
+            .compact
+            .min
+
+          if begin_date.nil?
+            {}
+          else
+            end_date = items
+              .flat_map { _1.experiences.map(&:last_end_date) }
+              .compact
+              .max
+
+            month_ranges = (begin_date.year..end_date.year).flat_map { |year|
+              (1..12).map { |month|
+                beginning_of_month = Date.new(year, month, 1)
+
+                end_of_month =
+                  if month == 12
+                    Date.new(year + 1, 1, 1).prev_day
+                  else
+                    Date.new(year, month + 1, 1).prev_day
+                  end
+
+                beginning_of_month..end_of_month
+              }
+            }
+
+            groups = month_ranges.map { [_1, []] }.to_h
+
+            groups.each do |month_range, month_items|
+              items.each do |item|
+                without_before = item.split(month_range.end.next_day).first
+                without_before_or_after = without_before&.split(month_range.begin)&.last
+
+                month_items << without_before_or_after if without_before_or_after
+              end
+            end
+
+            groups.transform_keys! { |month_range|
+              [month_range.begin.year, month_range.begin.month]
+            }
+
+            groups
+          end
+        },
+        genre: proc { |items|
+          groups = Hash.new { |h, k| h[k] = [] }
+
+          items.each do |item|
+            item.genres.each { |genre| groups[genre] << item }
+          end
+
+          groups.sort.to_h
+        },
+        length: proc { |items|
+          boundaries = Config.hash.fetch(:length_group_boundaries)
+
+          groups = boundaries.each_cons(2).map { |a, b|
+            [a..b, []]
+          }
+
+          groups.unshift([0..boundaries.first, []])
+          groups << [boundaries.last.., []]
+
+          groups = groups.to_h
+
+          items.each do |item|
+            item
+              .variants
+              .map { |variant| [variant, variant.length] }
+              .group_by { |_variant, length|
+                groups.keys.find { |length_range| length_range.include?(length) }
+              }
+              .transform_values { |variants_and_lengths|
+                variants_and_lengths.map(&:first)
+              }
+              .reject { |length_range, _variants| length_range.nil? }
+              .each do |length_range, variants|
+                groups[length_range] << item.with_variants(variants)
+              end
+          end
+
+          groups
+        },
+      }
+
+      REGEX = %r{\A
+        [^=]+ # the operation
+        by
+        \s*
+        (?<groups>[\w,\s]+)
+      }x
+    end
+  end
+end

data/lib/reading/stats/operation.rb

@@ -0,0 +1,313 @@
+module Reading
+  module Stats
+    # The beginning of a query which specifies what it does, e.g.
+    # "average rating" or "total amount".
+    class Operation
+      using Util::NumericToIIfWhole
+
+      # Determines which operation is contained in the given input, and then
+      # runs it to get the result. For the operations and their actions, see
+      # the constants below.
+      # @param input [String] the query string.
+      # @param grouped_items [Hash{Symbol => Array<Item>}] if no group was used,
+      #   the hash is just { all: items }
+      # @param result_formatters [Hash{Symbol => Proc}] to alter the appearance
+      #   of results. Keys should be from among the keys of Operation::ACTIONS.
+      # @return [Object] the return value of the action; if items are grouped
+      #   then a hash is returned with the same keys as grouped_items, otherwise
+      #   just the array of all results (not grouped) is returned.
+      def self.execute(input, grouped_items, result_formatters)
+        REGEXES.each do |key, regex|
+          match = input.match(regex)
+
+          if match
+            if match[:number_arg]
+              number_arg = Integer(match[:number_arg], exception: false) ||
+                (raise InputError, "Argument must be an integer. Example: top 5 ratings")
+            end
+
+            results = apply_to_inner_items(grouped_items) do |inner_items|
+              result = ACTIONS[key].call(inner_items, number_arg)
+
+              default_formatter = :itself.to_proc # just the result itself
+              result_formatter = result_formatters[key] || default_formatter
+
+              result_formatter.call(result)
+            end
+
+            if results.keys == [:all] # no groupings
+              return results[:all]
+            else
+              return results
+            end
+          end
+        end
+
+        raise InputError, "No valid operation in stats query \"#{input}\""
+      end
+
+      # A recursive method that applies the block to the leaf nodes (arrays of
+      # Items) of the given hash of grouped items.
+      # @param grouped_items [Hash]
+      # @yield [Array<Item>]
+      def self.apply_to_inner_items(grouped_items, &)
+        if grouped_items.values.first.is_a? Array
+          grouped_items.transform_values! { |inner_items|
+            yield inner_items
+          }
+        else # It's a Hash, so go one level deeper.
+          grouped_items.each do |group_name, grouped|
+            apply_to_inner_items(grouped, &)
+          end
+        end
+      end
+
+      private
+
+      # The default number argument if one is not given, as in "top ratings"
+      # rather than "top 5 ratings".
+      DEFAULT_NUMBER_ARG = 10
+
+      # Each action makes some calculation based on the given Items.
+      # @param items [Array<Item>]
+      # @return [Object] in most cases an Integer.
+      ACTIONS = {
+        average_rating: proc { |items|
+          ratings = items.map(&:rating).compact
+
+          if ratings.any?
+            (ratings.sum.to_f / ratings.count).to_i_if_whole
+          end
+        },
+        average_length: proc { |items|
+          lengths = items.flat_map { |item|
+            item.variants.map(&:length)
+          }
+          .compact
+
+          if lengths.any?
+            (lengths.sum / lengths.count.to_f).to_i_if_whole
+          end
+        },
+        :"average_amount" => proc { |items|
+          total_amount = items.sum { |item|
+            item.experiences.sum { |experience|
+              experience.spans.sum(&:amount)
+            }
+          }
+
+          (total_amount / items.count.to_f).to_i_if_whole
+        },
+        :"average_daily-amount" => proc { |items|
+          amounts_by_date = calculate_amounts_by_date(items)
+
+          if amounts_by_date.any?
+            amounts_by_date.values.sum / amounts_by_date.count
+          end
+        },
+        total_item: proc { |items|
+          items.count
+        },
+        total_amount: proc { |items|
+          items.sum { |item|
+            item.experiences.sum { |experience|
+              experience.spans.sum { |span|
+                (span.amount * span.progress).to_i_if_whole
+              }
+            }
+          }
+        },
+        top_rating: proc { |items, number_arg|
+          items
+            .max_by(number_arg || DEFAULT_NUMBER_ARG, &:rating)
+            .map { |item| [author_and_title(item), item.rating] }
+        },
+        top_length: proc { |items, number_arg|
+          items
+            .map { |item| [author_and_title(item), item.variants.map(&:length).max] }
+            .reject { |_title, length| length.nil? }
+            .max_by(number_arg || DEFAULT_NUMBER_ARG) { |_title, length| length }
+        },
+        top_amount: proc { |items, number_arg|
+          items
+            .map { |item|
+              amount = item.experiences.sum { |experience|
+                experience.spans.sum { |span|
+                  (span.amount * span.progress).to_i_if_whole
+                }
+              }
+
+              [author_and_title(item), amount]
+            }
+            .reject { |_title, amount| amount.zero? }
+            .max_by(number_arg || DEFAULT_NUMBER_ARG) { |_title, amount| amount }
+        },
+        top_speed: proc { |items, number_arg|
+          items
+            .map { |item| calculate_speed(item) }
+            .compact
+            .max_by(number_arg || DEFAULT_NUMBER_ARG) { |_title, speed_hash|
+              speed_hash[:amount] / speed_hash[:days].to_f
+            }
+        },
+        bottom_rating: proc { |items, number_arg|
+          items
+            .min_by(number_arg || DEFAULT_NUMBER_ARG, &:rating)
+            .map { |item| [author_and_title(item), item.rating] }
+        },
+        bottom_length: proc { |items, number_arg|
+          items
+            .map { |item| [author_and_title(item), item.variants.map(&:length).max] }
+            .reject { |_title, length| length.nil? }
+            .min_by(number_arg || DEFAULT_NUMBER_ARG) { |_title, length| length }
+        },
+        bottom_amount: proc { |items, number_arg|
+          items
+            .map { |item|
+              amount = item.experiences.sum { |experience|
+                experience.spans.sum { |span|
+                  (span.amount * span.progress).to_i_if_whole
+                }
+              }
+
+              [author_and_title(item), amount]
+            }
+            .reject { |_title, amount| amount.zero? }
+            .min_by(number_arg || DEFAULT_NUMBER_ARG) { |_title, amount| amount }
+        },
+        bottom_speed: proc { |items, number_arg|
+          items
+            .map { |item| calculate_speed(item) }
+            .compact
+            .min_by(number_arg || DEFAULT_NUMBER_ARG) { |_title, speed_hash|
+              speed_hash[:amount] / speed_hash[:days].to_f
+            }
+        },
+      }
+
+      ALIASES = {
+        average_rating: %w[ar],
+        average_length: %w[al],
+        average_amount: %w[aia ai],
+        :"average_daily-amount" => %w[ada ad],
+        total_item: %w[item count],
+        total_amount: %w[amount],
+        top_rating: %w[tr],
+        top_length: %w[tl],
+        top_amount: %w[ta],
+        top_speed: %w[ts],
+        bottom_rating: %w[br],
+        bottom_length: %w[bl],
+        bottom_amount: %w[ba],
+        bottom_speed: %w[bs],
+      }
+
+      REGEXES = ACTIONS.map { |key, _action|
+        first_word, second_word = key.to_s.split('_')
+        aliases = ALIASES.fetch(key)
+
+        regex =
+          %r{
+            (
+              \A
+              \s*
+              #{first_word}
+              s?
+              \s*
+              (?<number_arg>
+                \d+
+              )?
+              \s*
+              (
+                #{second_word}
+                s?
+              )
+              \s*
+            )
+            |
+            (
+              \A
+              \s*
+              (#{aliases.join('|')})
+              s?
+              \s*
+              (?<number_arg>
+                \d+
+              )?
+              \s*
+            )
+          }x
+
+        [key, regex]
+      }.to_h
+
+      # Sums the given Items' amounts per date.
+      # @param items [Array<Item>]
+      # @return [Hash{Date => Numeric, Reading::Item::TimeLength}]
+      private_class_method def self.calculate_amounts_by_date(items)
+        amounts_by_date = {}
+
+        items.each do |item|
+          item.experiences.each do |experience|
+            experience.spans.each do |span|
+              next unless span.dates
+
+              dates = span.dates.begin..(span.dates.end || Date.today)
+
+              amount = span.amount / dates.count.to_f
+              progress = span.members.include?(:progress) ? span.progress : 1.0
+
+              dates.each do |date|
+                amounts_by_date[date] ||= 0
+                amounts_by_date[date] += amount * progress
+              end
+            end
+          end
+        end
+
+        amounts_by_date
+      end
+
+      # Calculates an Item's speed (total amount over how many days). Returns
+      # nil if a speed is not able to be calculated (e.g. in a planned Item).
+      # @param item [Item]
+      # @return [Array(String, Hash), nil]
+      private_class_method def self.calculate_speed(item)
+        speeds = item.experiences.map { |experience|
+          spans_with_finite_dates = experience.spans.reject { |span|
+            span.dates.nil? || span.dates.end.nil?
+          }
+          next unless spans_with_finite_dates.any?
+
+          amount = spans_with_finite_dates.sum { |span|
+            # Conditional in case Item was created with fragmentary experience hashes,
+            # as in stats_test.rb
+            progress = span.members.include?(:progress) ? span.progress : 1.0
+
+            span.amount * progress
+          }
+          .to_i_if_whole
+
+          days = spans_with_finite_dates.sum { |span| span.dates.count }.to_i
+
+          { amount:, days: }
+        }
+        .compact
+
+        return nil unless speeds.any?
+
+        speed = speeds
+          .max_by { |hash| hash[:amount] / hash[:days].to_f }
+
+        [author_and_title(item), speed]
+      end
+
+      # A shorter version of Item::View#name.
+      # @param item [Item]
+      # @return [String]
+      private_class_method def self.author_and_title(item)
+        "#{item.author + " – " if item.author}#{item.title}"
+      end
+    end
+  end
+end

data/lib/reading/stats/query.rb

@@ -0,0 +1,37 @@
+require 'pastel'
+require_relative 'operation'
+require_relative 'filter'
+require_relative 'grouping'
+
+module Reading
+  module Stats
+    # Gives statistics on an array of Items.
+    class Query
+      private attr_reader :input, :items, :result_formatters, :pastel
+
+      # @param input [String] the query string.
+      # @param items [Array<Item>] the Items to be queried.
+      # @param result_formatters [Boolean, Hash{Symbol => Proc}] to alter the
+      #   appearance of results; keys should be from among the keys of
+      #   Operation::ACTIONS. Pre-made formatters for terminal output are in
+      #   terminal_result_formatters.rb.
+      def initialize(input:, items:, result_formatters: {})
+        @input = input
+        @items = items
+        @result_formatters = result_formatters
+        @pastel = Pastel.new
+      end
+
+      # Parses the query and returns the result.
+      # @return [Object]
+      def result
+        filtered_items = Stats::Filter.filter(input, items)
+        grouped_items = Grouping.group(input, filtered_items)
+
+        Operation.execute(input, grouped_items, result_formatters || {})
+      rescue Reading::Error => e
+        raise e.class, pastel.bright_red(e.message)
+      end
+    end
+  end
+end

data/lib/reading/stats/terminal_result_formatters.rb

@@ -0,0 +1,91 @@
+require 'pastel'
+
+module Reading
+  module Stats
+    module ResultFormatters
+      TERMINAL = {
+        average_length: ->(result) { length_to_s(result) },
+        average_amount: ->(result) { length_to_s(result) },
+        :'average_daily-amount' => ->(result) { "#{length_to_s(result)} per day" },
+        total_item: ->(result) {
+          if result.zero?
+            PASTEL.bright_black("none")
+          else
+            color("#{result} #{result == 1 ? "item" : "items"}")
+          end
+        },
+        total_amount: ->(result) { length_to_s(result) },
+        top_length: ->(result) { top_or_bottom_lengths(result) },
+        top_amount: ->(result) { top_or_bottom_lengths(result) },
+        top_speed: ->(result) { top_or_bottom_speeds(result) },
+        bottom_length: ->(result) { top_or_bottom_lengths(result) },
+        botom_amount: ->(result) { top_or_bottom_lengths(result) },
+        bottom_speed: ->(result) { top_or_bottom_speeds(result) },
+      }
+
+      private
+
+      PASTEL = Pastel.new
+
+      # Applies a terminal color.
+      # @param string [String]
+      # @return [String]
+      private_class_method def self.color(string)
+        PASTEL.bright_blue(string)
+      end
+
+      # Converts a length/amount (pages or time) into a string.
+      # @param length [Numeric, Reading::Item::TimeLength]
+      # @param color [Boolean] whether a terminal color should be applied.
+      # @return [String]
+      private_class_method def self.length_to_s(length, color: true)
+        if length.is_a?(Numeric)
+          length_string = "#{length.round} pages"
+        else
+          length_string = length.to_s
+        end
+
+        color ? color(length_string) : length_string
+      end
+
+      # Formats a list of top/bottom length results as a string.
+      # @param result [Array]
+      # @return [String]
+      private_class_method def self.top_or_bottom_lengths(result)
+        offset = result.count.digits.count
+
+        result
+          .map.with_index { |(title, length), index|
+            pad = ' ' * (offset - (index + 1).digits.count)
+
+            title_line = "#{index + 1}. #{pad}#{title}"
+            indent = "    #{' ' * offset}"
+
+            "#{title_line}\n#{indent}#{length_to_s(length)}"
+          }
+          .join("\n")
+      end
+
+      # Formats a list of top/bottom speed results as a string.
+      # @param result [Array]
+      # @return [String]
+      private_class_method def self.top_or_bottom_speeds(result)
+        offset = result.count.digits.count
+
+        result
+          .map.with_index { |(title, hash), index|
+            amount = length_to_s(hash[:amount], color: false)
+            days = "#{hash[:days]} #{hash[:days] == 1 ? "day" : "days"}"
+            pad = ' ' * (offset - (index + 1).digits.count)
+
+            title_line = "#{index + 1}. #{pad}#{title}"
+            indent = "    #{' ' * offset}"
+            colored_speed = color("#{amount} in #{days}")
+
+            "#{title_line}\n#{indent}#{colored_speed}"
+          }
+          .join("\n")
+      end
+    end
+  end
+end

data/lib/reading/util/exclude.rb

@@ -0,0 +1,12 @@
+# Copied from activesupport/lib/active_support/core_ext/enumerable.rb
+module Enumerable
+  def exclude?(object)
+    !include?(object)
+  end
+end
+
+class String
+  def exclude?(object)
+    !include?(object)
+  end
+end

data/lib/reading/util/hash_to_data.rb

@@ -12,9 +12,9 @@ module Reading
             if v.is_a?(Hash)
               v.to_data
             elsif v.is_a?(Array) && v.all? { |el| el.is_a?(Hash) }
-              v.map(&:to_data)
+              v.map(&:to_data).freeze
             else
-              v
+              v.freeze
             end
           }.values