qfill 0.0.3 → 0.1.1

data/lib/qfill/manager.rb

@@ -1,91 +1,120 @@
-#Qfill::Manager.new(
+# frozen_string_literal: true
+
+require 'forwardable'
+
+# A Qfill::Manager builds a set of result data (as `result`) from the source data in Qfill::Popper,
+#   according to the Qfill::Result definitions in the Qfill::Pusher, and the selected strategy.
+#
+# Qfill::Manager.new(
 #  :all_list_max => 40,
 #  :popper => popper,
 #  :pusher => pusher,
-#)
+# )
 module Qfill
   class Manager
-    attr_accessor :all_list_max, :popper, :pusher, :fill_count, :strategy
+    extend Forwardable
+    def_delegators :@strategy,
+                   :popper,
+                   :pusher,
+                   :result,
+                   :remaining_to_fill
+    attr_accessor :all_list_max,
+                  :primary_list_total,
+                  :popper,
+                  :pusher,
+                  :fill_count,
+                  :result,
+                  :strategy_options
 
-    STRATEGY_OPTIONS = [:drain, :sample]
+    STRATEGY_OPTIONS = %i[drain_to_limit drain_to_empty sample time_slice].freeze
 
     def initialize(options = {})
-      unless options[:popper] && options[:pusher]
-        raise ArgumentError, "#{self.class}: popper and pusher are required options for #{self.class}.new(options)"
-      end
       unless options[:strategy].nil? || STRATEGY_OPTIONS.include?(options[:strategy])
-        raise ArgumentError, "#{self.class}: strategy is optional, but must be one of #{STRATEGY_OPTIONS.inspect} if provided"
+        raise ArgumentError,
+              "#{self.class}: strategy is optional, but must be one of #{STRATEGY_OPTIONS.inspect} if provided"
       end
+
+      @fill_count = 0
+
       @popper = options[:popper]
       @pusher = options[:pusher]
-      # Provided by user, or defaults to the total number of primary elements in popper list set
-      @all_list_max = options[:all_list_max] ? [options[:all_list_max], self.popper.get_primary_elements].min : self.popper.get_primary_elements
-      @fill_count = 0
-      @strategy = options[:strategy] || :drain # or :sample
+      @strategy_name = options[:strategy] || :drain_to_limit # or :drain_to_empty or :sample
+      @strategy_options = options[:strategy_options]
+
+      # Allow the strategy to define the pusher when not defined by user
+      @pusher ||= strategy.default_pusher
+      unless @popper && @pusher
+        raise ArgumentError, "#{self.class}: popper and pusher (except where defined by the strategy) are required options for #{self.class}.new(options)"
+      end
+
+      # Provided by user, or defaults to the total number of elements in popper list set
+      @all_list_max = if options[:all_list_max]
+                        [options[:all_list_max],
+                         popper.count_all_elements].min
+                      else
+                        popper.count_all_elements
+                      end
+      @primary_list_total = popper.count_primary_elements
+    end
+
+    def strategy
+      @strategy ||= case @strategy_name
+                    when :drain_to_empty
+                      Qfill::Strategy::DrainToEmpty.new(self)
+                    when :drain_to_limit
+                      Qfill::Strategy::DrainToLimit.new(self)
+                    when :sample
+                      Qfill::Strategy::Sample.new(self)
+                    when :time_slice
+                      Qfill::Strategy::TimeSlice.new(self)
+                    end
     end
 
     def fill!
-      while !is_full? && !self.popper.primary_empty? && (result = self.pusher.current_list)
-        self.fill_to_ratio!(result, self.all_list_max)
-        self.pusher.set_next_as_current!
+      while !is_full? && !popper.primary_empty? && (self.result = pusher.current_list)
+        strategy.on_fill!
+        fill_to_ratio!
+        pusher.set_next_as_current!
+        result.elements.shuffle! if result.shuffle
       end
     end
 
-    def fill_to_ratio!(result, all_list_max)
-      result.max = Qfill::Result.get_limit_from_max_and_ratio(all_list_max, result.ratio)
-      if !result.list_ratios.empty?
-        self.fill_according_to_list_ratios!(result)
+    def fill_to_ratio!
+      strategy.result_max!
+      if result.list_ratios.empty?
+        fill_up_to_ratio!
       else
-        self.fill_up_to_ratio!(result)
+        fill_according_to_list_ratios!
       end
     end
 
-    def fill_according_to_list_ratios!(result)
-      added = 0
-      if self.strategy == :drain
-        result.list_ratios.each do |list_name, list_ratio|
-          #puts "fill_according_to_list_ratios!, :drain, #{list_name}: Primary remaining => #{self.popper.get_primary_elements}"
-          max_from_list = Qfill::Result.get_limit_from_max_and_ratio(result.max, list_ratio)
-          array_to_push = self.popper.next_objects!(list_name, max_from_list)
-          added = result.push(array_to_push, list_name)
-        end
-        self.fill_count += added
-      elsif self.strategy == :sample
-        while !is_full? && !result.is_full? && !self.popper.totally_empty? && (list_ratio_tuple = result.current_list_ratio)
-          #puts "fill_according_to_list_ratios!, :sample, #{list_ratio_tuple[0]}: Primary remaining => #{self.popper.get_primary_elements}"
-          max_from_list = Qfill::Result.get_limit_from_max_and_ratio(result.max, list_ratio_tuple[1])
-          array_to_push = self.popper.next_objects!(list_ratio_tuple[0], max_from_list)
-          added = result.push(array_to_push, list_ratio_tuple[0])
-          self.fill_count += added
-          result.set_next_as_current!
-        end
-      end
+    def remaining_to_fill
+      primary_list_total - fill_count
     end
 
-    def fill_up_to_ratio!(result)
-      ratio = 1.0 / self.popper.primary.length
-      max_from_list = Qfill::Result.get_limit_from_max_and_ratio(result.max, ratio)
-      added = 0
-      if self.strategy == :drain
-        self.popper.primary.each do |queue|
-          #puts "fill_up_to_ratio!, :drain max #{max_from_list}, #{queue.name}: Primary remaining => #{self.popper.get_primary_elements}"
-          array_to_push = self.popper.next_objects!(queue.name, max_from_list)
-          added = result.push(array_to_push, queue.name)
-        end
-        self.fill_count += added
-      elsif self.strategy == :sample
-        while !is_full? && !result.is_full? && !self.popper.totally_empty? && (origin_list = self.popper.current_list)
-          #puts "fill_up_to_ratio!, :sample max #{max_from_list}, #{origin_list.name}: Primary remaining => #{self.popper.get_primary_elements}"
-          array_to_push = self.popper.next_objects!(origin_list.name, max_from_list)
-          added = result.push(array_to_push, origin_list.name)
-          self.fill_count += added
-          self.popper.set_next_as_current!
-        end
-      end
+    # Go through the queues this result should be filled from and push elements from them onto the current result list.
+    def fill_according_to_list_ratios!
+      strategy.fill_according_to_list_ratios!
+    end
+
+    # Go through the primary (non backfill) queues in the popper and push elements from them onto the current result list.
+    def fill_up_to_ratio!
+      strategy.fill_up_to_ratio!
     end
 
     def is_full?
-      self.fill_count >= self.all_list_max
+      fill_count >= all_list_max
+    end
+
+    def each(&block)
+      # NOTE: on magic: http://blog.arkency.com/2014/01/ruby-to-enum-for-enumerator/
+      return enum_for(:each) unless block # Sparkling magic!
+
+      pusher.each(&block)
+    end
+
+    def to_s
+      "[#{strategy_name}][Result Max:#{result.max}][All Max:#{all_list_max}][Current Max:#{result.max}][Filled:#{fill_count}][Primary #:#{popper.count_primary_elements}]"
     end
   end
 end

data/lib/qfill/origin.rb

@@ -1,4 +1,6 @@
-#Qfill::Origin.new(:name => "High List",
+# frozen_string_literal: true
+
+# Qfill::Origin.new(:name => "High List",
 #                     :elements => [Thing1, Thing3],
 #                     :backfill => "Medium List",
 #                     :filter => filter1),
@@ -12,8 +14,7 @@ module Qfill
     end
 
     def has_backfill?
-      !!self.backfill
+      !!backfill
     end
-
   end
 end

data/lib/qfill/popper.rb

@@ -1,4 +1,10 @@
-#popper = Qfill::Popper.new(
+# frozen_string_literal: true
+
+# A Qfill::Popper (which inherits from Qfill::ListSet) is a set of source data
+#   which will be added to the Qfill::Pusher, by the Qfill::Manager, when generating the result data.
+# Qfill::Popper is made up of an array (called queues) of Qfill::Origin objects (which inherit from Qfill::List).
+#
+# popper = Qfill::Popper.new(
 #  Qfill::Origin.new( :name => "High List",
 #                        :elements => [Thing1, Thing3],
 #                        :backfill => "Medium List",
@@ -11,9 +17,9 @@
 #                        :elements => [Thing4, Thing5],
 #                        :backfill => nil,
 #                        :filter => filter1),
-#)
+# )
 #
-#popper = Qfill::Popper.from_array_of_hashes([
+# popper = Qfill::Popper.from_array_of_hashes([
 #  { :name => "High List",
 #    :elements => [Thing1, Thing3, Thing7, Thing8, Thing12, Thing15, Thing17],
 #    :backfill => "Medium List",
@@ -26,32 +32,39 @@
 #    :elements => [Thing4, Thing5, Thing9, Thing10, Thing13, Thing14, Thing18, Thing19, Thing20],
 #    :backfill => nil,
 #    :filter => filter1},
-#])
+# ])
 #
-# Popper is made up of an array (called queues) of Origin objects.
 module Qfill
   class Popper < Qfill::ListSet
-
     attr_accessor :total_elements
 
+    class << self
+      def from_array_of_hashes(array_of_hashes = [])
+        args = array_of_hashes.map do |hash|
+          Qfill::Origin.new(hash)
+        end
+        Qfill::Popper.new(*args)
+      end
+    end
+
     def initialize(*args)
       super(*args)
-      @total_elements = get_total_elements
+      @total_elements = count_all_elements
     end
 
     def primary
-      @primary ||= self.queues.select {|x| x.backfill != true}
+      @primary ||= queues.reject { |x| x.backfill == true }
     end
 
     def current_list
-      self.primary[self.current_index]
+      primary[current_index]
     end
 
     def set_next_as_current!
-      next_index = self.current_index + 1
-      if (next_index) >= self.primary.length
+      next_index = current_index + 1
+      if (next_index) >= primary.length
         # If we have iterated through all the queues, then we reset
-        self.reset!
+        reset!
       else
         self.current_index = next_index
       end
@@ -60,7 +73,7 @@ module Qfill
     def next_objects!(list_name, n = 1)
       origin_list = self[list_name]
       if origin_list.elements.length >= n
-        return origin_list.elements.pop(n)
+        origin_list.elements.pop(n)
       else
         result = origin_list.elements.pop(n)
         while result.length < n && origin_list.has_backfill?
@@ -69,28 +82,20 @@ module Qfill
           result += secondary_list.elements.pop(remaining)
           origin_list = secondary_list
         end
-        return result
+        result
       end
     end
 
-    def self.from_array_of_hashes(array_of_hashes = [])
-      args = array_of_hashes.map do |hash|
-        Qfill::Origin.new(hash)
-      end
-      Qfill::Popper.new(*args)
-    end
-
     def primary_empty?
-      self.get_primary_elements == 0
+      count_primary_elements.zero?
     end
 
     def totally_empty?
-      self.get_total_elements == 0
+      count_all_elements.zero?
     end
 
-    def get_primary_elements
-      self.primary.inject(0) {|counter, queue| counter += queue.elements.length}
+    def count_primary_elements
+      primary.inject(0) { |counter, queue| counter += queue.elements.length }
     end
-
   end
 end

data/lib/qfill/pusher.rb

@@ -1,4 +1,10 @@
-#pusher = Qfill::Pusher.new(
+# frozen_string_literal: true
+
+# A Qfill::Pusher (which inherits from Qfill::ListSet) is a set of result data
+#   which contribute to the definition of the result set created by the Qfill::Manager.
+# Qfill::Pusher is made up of an array (called queues) of Qfill::Result objects (which inherit from Qfill::List).
+#
+# pusher = Qfill::Pusher.new(
 #  Qfill::Result.new( :name => "Best Results",
 #                        :filter => filter3,
 #                        :ratio => 0.5,
@@ -16,9 +22,9 @@
 #                          "Low List" => 0.4
 #                        }
 #  )
-#)
+# )
 #
-#pusher = Qfill::Pusher.from_array_of_hashes([
+# pusher = Qfill::Pusher.from_array_of_hashes([
 #  { :name => "First Result",
 #    :ratio => 0.125,
 #    :filter => filter3,
@@ -34,41 +40,40 @@
 #    :ratio => 0.125 },
 #  { :name => "Fourth Result",
 #    :ratio => 0.50 },
-#])
+# ])
 #
 # Pusher is made up of an array (called queues) of Result objects.
 module Qfill
   class Pusher < Qfill::ListSet
-
     def initialize(*args)
       super(*args)
-      with_ratio = self.queues.map {|x| x.ratio}.compact
-      ratio_to_split = (1 - with_ratio.inject(0, :+))
-      if ratio_to_split < 0
-        raise ArgumentError, "#{self.class}: mismatched ratios for queues #{with_ratio.join(' + ')} must not total more than 1"
-      end
-      num_without_ratio = self.queues.length - with_ratio.length
-      if num_without_ratio > 0 && ratio_to_split <= 1
+      with_ratio = queues.map(&:ratio).compact
+      ratio_to_split = (1 - with_ratio.sum)
+      # if ratio_to_split < 0
+      #  raise ArgumentError, "#{self.class}: mismatched ratios for queues #{with_ratio.join(' + ')} must not total more than 1"
+      # end
+      num_without_ratio = queues.length - with_ratio.length
+      if num_without_ratio.positive? && ratio_to_split <= 1
         equal_portion = ratio_to_split / num_without_ratio
-        self.queues.each do |queue|
-          if queue.ratio.nil?
-            queue.tap do |q|
-              q.ratio = equal_portion
-            end
+        queues.each do |queue|
+          next unless queue.ratio.nil?
+
+          queue.tap do |q|
+            q.ratio = equal_portion
           end
         end
       end
     end
 
     def current_list
-      self.queues[self.current_index]
+      queues[current_index]
     end
 
     def set_next_as_current!
-      next_index = self.current_index + 1
-      if (next_index) == self.queues.length
+      next_index = current_index + 1
+      if (next_index) == queues.length
         # If we have iterated through all the queues, then we reset
-        self.reset!
+        reset!
       else
         self.current_index = next_index
       end
@@ -82,12 +87,18 @@ module Qfill
     end
 
     def more_to_fill?
-      !self.queues.select {|x| !x.is_full?}.empty?
+      !queues.reject(&:is_full?).empty?
     end
 
     def next_to_fill
-      self.queues.select {|x| !x.is_full?}.first
+      queues.reject(&:is_full?).first
     end
 
+    def each(&block)
+      # NOTE: on magic: http://blog.arkency.com/2014/01/ruby-to-enum-for-enumerator/
+      return enum_for(:each) unless block # Sparkling magic!
+
+      queues.each(&block)
+    end
   end
 end

data/lib/qfill/result.rb

@@ -1,105 +1,141 @@
+# frozen_string_literal: true
+
+# :preferred is used for :drain_to_empty
+# :ratio is used for the other strategies
 # Qfill::Result.new(:name => "Best Results",
 #                      :filter => filter3,
 #                      :ratio => 0.5,
 #                      :list_ratios => {
 #                        "High List" => 0.4,
 #                        "Medium List" => 0.2,
-#                        "Low List" => 0.4 } )
+#                        "Low List" => 0.4 },
+#                      :preferred => ["High List", "Medium List"]
+# )
 module Qfill
   class Result < Qfill::List
-    attr_accessor :ratio, :list_ratios, :fill_tracker, :fill_count, :validate, :filter, :current_list_ratio_index, :max
+    attr_accessor :ratio,
+                  :list_ratios,
+                  :fill_tracker,
+                  :total_count,
+                  :current_count,
+                  :validate,
+                  :current_list_ratio_index,
+                  :max,
+                  :shuffle,
+                  :preferred,
+                  :preferred_potential,
+                  :preferred_potential_ratio,
+                  :max_tracker
+
+    def self.get_limit_from_max_and_ratio(all_list_max, ratio, remain = nil)
+      return 1 if remain == 1
 
-    def self.get_limit_from_max_and_ratio(all_list_max, ratio)
       limit = (all_list_max * ratio).round(0)
       # If we rounded down to zero we have to keep at least one.
       # This is because with small origin sets all ratios might round down to 0.
-      if limit == 0
-        limit += 1
-      end
-      limit
+      limit += 1 if limit.zero?
+      remain ? [limit, remain].min : limit
     end
 
     def initialize(options = {})
       super(options)
       @list_ratios = options[:list_ratios] || {}
-      with_ratio = self.list_ratio_as_array.map {|tuple| tuple[1]}.compact
-      ratio_leftover = (1 - with_ratio.inject(0, :+))
-      if ratio_leftover < 0
-        raise ArgumentError, "#{self.class}: invalid list_ratios for queue '#{self.name}'. List Ratios (#{with_ratio.join(' + ')}) must not total more than 1"
+      with_ratio = list_ratio_as_array.map { |tuple| tuple[1] }.compact
+      ratio_leftover = (1 - with_ratio.sum)
+      if ratio_leftover.negative?
+        raise ArgumentError,
+              "#{self.class}: invalid list_ratios for queue '#{name}'. List Ratios (#{with_ratio.join(' + ')}) must not total more than 1"
       end
-      @ratio = options[:ratio]
+
+      @ratio = options[:ratio] || 1
       @max = 0
+      @preferred = options[:preferred] # Used by :drain_to_empty and :drain_to_limit
+      @preferred_potential = 0
+      @preferred_potential_ratio = 0
       @fill_tracker = {}
-      @fill_count = 0
+      @max_tracker = {}
+      # Doesn't reset to 0 on reset!
+      @total_count = 0
+      # Does reset to 0 on reset!
+      @current_count = 0
+      @shuffle = options[:shuffle] || false
       @current_list_ratio_index = 0 # Used by :sample strategy
-      @validate = self.use_validation?
+      @validate = use_validation?
     end
 
     def list_ratio_full?(list_name, max_from_list)
-      self.fill_tracker[list_name] >= max_from_list
+      fill_tracker[list_name] >= max_from_list
     end
 
     def push(objects, list_name)
-      self.validate!(list_name)
+      validate!(list_name)
       added = 0
+      fill_tracker[list_name] ||= 0
       objects.each do |object|
-        if self.allow?(object, list_name)
-          self.bump_fill_tracker!(list_name)
-          self.add!(object)
-          added += 1
-          #self.print(list_name)
-        end
+        # The objects have already been popped.
+        # The only valid reason to not push an object at this point is if !allow?.
+        # break if is_full?
+
+        next unless allow?(object, list_name)
+
+        bump_fill_tracker!(list_name)
+        add!(object)
+        added += 1
+        # self.print(list_name)
       end
-      return added
+      added
     end
 
     def print(list_name)
-      puts "Added to #{list_name}.\nResult List #{self.name} now has #{self.elements.length} total objects.\nSources:\n #{self.fill_tracker.inspect} "
+      puts "Added to #{list_name}.\nResult List #{name} now has #{elements.length} total objects.\nSources:\n #{fill_tracker.inspect} "
     end
 
     def add!(object)
-      self.elements << object
+      elements << object
     end
 
     def allow?(object, list_name)
-      !self.filter.respond_to?(:call) ||
+      !filter.respond_to?(:call) ||
         # If there is a filter, then it must return true to proceed
-        self.filter.run(object, list_name)
+        filter.run(object, list_name)
     end
 
     def bump_fill_tracker!(list_name)
-      self.fill_tracker[list_name] ||= 0
-      self.fill_tracker[list_name] += 1
-      self.fill_count += 1
+      fill_tracker[list_name] += 1
+      self.total_count += 1
+      self.current_count += 1
     end
 
     # Does the queue being pushed into match one of the list_ratios
     def valid?(list_name)
-      self.list_ratios.has_key?(list_name)
+      list_ratios.key?(list_name)
     end
 
     def validate!(list_name)
-      raise ArgumentError, "#{self.class}: #{list_name} is an invalid list_name.  Valid list_names are: #{self.list_ratios.keys}" if self.validate && !self.valid?(list_name)
+      if validate && !valid?(list_name)
+        raise ArgumentError,
+              "#{self.class}: #{list_name} is an invalid list_name.  Valid list_names are: #{list_ratios.keys}"
+      end
     end
 
     def use_validation?
-      !self.list_ratios.empty?
+      !list_ratios.empty?
     end
 
     def list_ratio_as_array
       # [["high",0.4],["medium",0.4],["low",0.2]]
-      @list_ratio_as_array ||= self.list_ratios.to_a
+      @list_ratio_as_array ||= list_ratios.to_a
     end
 
     def current_list_ratio
-      self.list_ratio_as_array[self.current_list_ratio_index]
+      list_ratio_as_array[current_list_ratio_index]
     end
 
     def set_next_as_current!
-      next_index = self.current_list_ratio_index + 1
-      if (next_index) == self.list_ratio_as_array.length
+      next_index = current_list_ratio_index + 1
+      if (next_index) == list_ratio_as_array.length
         # If we have iterated through all the list_ratios, then we reset
-        self.reset!
+        reset!
       else
         self.current_list_ratio_index = next_index
       end
@@ -107,14 +143,16 @@ module Qfill
 
     def reset!
       self.current_list_ratio_index = 0
+      self.current_count = 0
     end
 
+    # Results can overfill, because fractions.
     def is_full?
-      self.fill_count >= self.max
+      self.total_count >= max
     end
 
     def to_s
-      "Qfill::Result: ratio: #{self.ratio}, list_ratios: #{self.list_ratios}, fill_tracker: #{self.fill_tracker}, fill_count: #{self.fill_count}, filter: #{!!self.filter ? 'Yes' : 'No'}, current_list_ratio_index: #{self.current_list_ratio_index}, max: #{self.max}"
+      "Qfill::Result: ratio: #{ratio}, list_ratios: #{list_ratios}, fill_tracker: #{fill_tracker}, total_count: #{self.total_count}, current_count: #{self.current_count}, filter: #{!!filter ? 'Yes' : 'No'}, current_list_ratio_index: #{current_list_ratio_index}, max: #{max}"
     end
   end
 end

data/lib/qfill/strategy/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Qfill
+  module Strategy
+    class Base
+      extend Forwardable
+      def_delegators :@manager,
+                     :all_list_max,
+                     :popper,
+                     :pusher,
+                     :result,
+                     :primary_list_total,
+                     :fill_count,
+                     :fill_count=,
+                     :is_full?,
+                     :strategy_options
+      attr_accessor :added,
+                    :tally,
+                    :ratio_modifier
+
+      def initialize(manager)
+        @manager = manager
+        @added = 0
+        @tally = 0
+        @ratio_modifier = 1
+      end
+
+      def name
+        NAME
+      end
+
+      def on_fill!
+        raise NotImplementedError
+      end
+
+      def fill_to_ratio!
+        raise NotImplementedError
+      end
+
+      # Go through the queues this result should be filled from and push elements from them onto the current result list.
+      def fill_according_to_list_ratios!
+        raise NotImplementedError
+      end
+
+      def fill_up_to_ratio!
+        raise NotImplementedError
+      end
+
+      def default_pusher
+        # NOOP
+      end
+
+      def bump!
+        self.tally += added
+        self.fill_count += added
+      end
+
+      def remaining
+        all_list_max - fill_count
+      end
+    end
+  end
+end