qfill 0.0.4 → 0.1.0

data/Gemfile

@@ -1,4 +1,37 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in qfill.gemspec
 gemspec
+
+ruby_version = Gem::Version.new(RUBY_VERSION)
+
+gem 'yard', '~> 0.9.24', require: false
+
+### deps for rdoc.info
+group :documentation do
+  gem 'github-markup', platform: :mri
+  gem 'redcarpet', platform: :mri
+end
+
+group :development, :test do
+  if ruby_version >= Gem::Version.new('2.4')
+    # No need to run byebug / pry on earlier versions
+    gem 'byebug', platform: :mri
+    gem 'pry', platform: :mri
+    gem 'pry-byebug', platform: :mri
+  end
+
+  if ruby_version >= Gem::Version.new('2.7')
+    # No need to run rubocop or simplecov on earlier versions
+    gem 'rubocop', '~> 1.9', platform: :mri
+    gem 'rubocop-md', platform: :mri
+    gem 'rubocop-packaging', platform: :mri
+    gem 'rubocop-performance', platform: :mri
+    gem 'rubocop-rake', platform: :mri
+    gem 'rubocop-rspec', platform: :mri
+
+    gem 'simplecov', '~> 0.21', platform: :mri
+  end
+end

data/Guardfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+guard 'rspec', version: 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
+end
+
+guard 'bundler' do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end

data/{LICENSE.txt → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2013 Peter Boling
+Copyright (c) 2013-2021 Peter Boling
 
 MIT License
 

data/README.md

@@ -1,4 +1,4 @@
-# Qfill - Advanced Queue Tranformations
+# Qfill - Advanced Queue Transformations
 
 This gem takes a dynamic number of queues (arrays) of things, and manages the transformation into a new set of queues,
 according to a dynamic set of guidelines.
@@ -23,7 +23,7 @@ There will be a dynamic number of origination queues each containing a set of sn
 some matching criteria.
 There is a Popper which is called to pop the next object from the next origination queue.
 There is a Filter which is optionally called to validate any object that is popped from the origin.
-Origin keeps popping until an object is validated for as a result-worthy object.
+Origin keeps popping until an object is validated as a result-worthy object.
 
 Example:
 

data/Rakefile

@@ -1 +1,24 @@
-require "bundler/gem_tasks"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  task :spec do
+    warn 'RSpec is disabled'
+  end
+end
+task test: :spec
+
+begin
+  require 'rubocop/rake_task'
+  RuboCop::RakeTask.new
+rescue LoadError
+  task :rubocop do
+    warn 'RuboCop is disabled'
+  end
+end
+
+task default: [:test]

data/lib/qfill.rb

@@ -1,13 +1,16 @@
-require "qfill/version"
-require "qfill/filter"
-require "qfill/list"
-require "qfill/list_set"
-require "qfill/origin"
-require "qfill/result"
-require "qfill/popper"
-require "qfill/pusher"
-require "qfill/manager"
+# frozen_string_literal: true
+
+require 'qfill/version'
+require 'qfill/filter'
+require 'qfill/list'
+require 'qfill/list_set'
+require 'qfill/origin'
+require 'qfill/popper'
+require 'qfill/pusher'
+require 'qfill/manager'
+require 'qfill/result'
+require 'qfill/strategy'
 
 module Qfill
-  VERBOSE = false
+  VERBOSE = ENV['QFILL_VERBOSE'] == 'true'
 end

data/lib/qfill/errors/invalid_index.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Qfill
+  module Errors
+    class InvalidIndex < StandardError
+    end
+  end
+end

data/lib/qfill/filter.rb

@@ -1,5 +1,7 @@
-#filter1 = Qfill::Filter.new( -> (object, stuff, stank) { object.is_awesome_enough_to_be_in_results?(stuff, stank) }, stuff, stank)
-#filter2 = Qfill::Filter.new( -> (object, rank, bank) { object.is_awesome_enough_to_be_in_results?(rank, bank) }, rank, bank)
+# frozen_string_literal: true
+
+# filter1 = Qfill::Filter.new( -> (object, stuff, stank) { object.is_awesome_enough_to_be_in_results?(stuff, stank) }, stuff, stank)
+# filter2 = Qfill::Filter.new( -> (object, rank, bank) { object.is_awesome_enough_to_be_in_results?(rank, bank) }, rank, bank)
 #
 # Filters are destructive. If an item is filtered from a Result list it is lost, since it has already been popped off the origin list, and won't be coming back
 module Qfill
@@ -12,7 +14,7 @@ module Qfill
     end
 
     def run(*args)
-      self.processor.call(*args, *self.processor_arguments)
+      processor.call(*args, *processor_arguments)
     end
   end
 end

data/lib/qfill/list.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 # This is the base queue class for Origin queues and Result queues.
 #
-#Qfill::List.new(:name => "High List",
+# Qfill::List.new(:name => "High List",
 #                    :elements => [Thing1, Thing3],
 #                    :filter => filter1),
 module Qfill
@@ -9,10 +11,10 @@ module Qfill
 
     def initialize(options = {})
       raise ArgumentError, "Missing required option :name for #{self.class}.new()" unless options && options[:name]
+
       @name = options[:name]
       @elements = options[:elements] || []
       @filter = options[:filter]
     end
-
   end
 end

data/lib/qfill/list_set.rb

@@ -1,35 +1,39 @@
-#popper = Qfill::ListSet.new(
+# frozen_string_literal: true
+
+# This is the base queues class for Popper queues and Pusher queues.
+#
+# popper = Qfill::ListSet.new(
 #  Qfill::List.new( :name => "High List",
 #                       :elements => [Thing1, Thing3],
 #                       :filter => filter1 ) )
 module Qfill
   class ListSet
-
     attr_accessor :queues, :current_index
 
     def initialize(*args)
-      raise ArgumentError, "Missing required arguments for #{self.class}.new(queues)" unless args.length > 0
+      raise ArgumentError, "Missing required arguments for #{self.class}.new(queues)" unless args.length.positive?
+
       @queues = args
       @current_index = 0
     end
 
     def [](key)
-      return self.queues.find { |queue| queue.name == key }
+      queues.find { |queue| queue.name == key }
     end
 
     def index_of(queue_name)
-      index = self.queues.index { |queue| queue.name == queue_name }
+      index = queues.index { |queue| queue.name == queue_name }
       return index if index
-      raise "Fuck #{index} index is missing for #{queue_name}"
+
+      raise Qfill::Errors::InvalidIndex, "Cannot locate index of #{queue_name}"
     end
 
     def reset!
       self.current_index = 0
     end
 
-    def get_total_elements
-      self.queues.inject(0) {|counter, queue| counter += queue.elements.length}
+    def count_all_elements
+      queues.inject(0) { |counter, queue| counter += queue.elements.length }
     end
-
   end
 end

data/lib/qfill/manager.rb

@@ -1,166 +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, :result
+    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_to_limit, :drain_to_empty, :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])
-        if options[:strategy] == :drain
-          warn "Qfill strategy :drain has been renamed :drain_to_limit, please update your code."
-          options[:strategy] = :drain_to_limit
-        else
-          raise ArgumentError, "#{self.class}: strategy is optional, but must be one of #{STRATEGY_OPTIONS.inspect} if provided"
-        end
+        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.count_primary_elements].min : self.popper.count_primary_elements
-      @fill_count = 0
-      @strategy = options[:strategy] || :drain_to_limit # or :drain_to_empty 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? && (self.result = self.pusher.current_list)
-        if self.current_strategy == :drain_to_empty
-          preferred_potential_ratio = 0
-          preferred_potential = 0
-          self.result.list_ratios.each do |list_name, list_ratio|
-            poppy = self.result.preferred.select {|x| x == list_name}
-            if poppy
-              preferred_potential_ratio += list_ratio
-              num = self.popper[list_name].elements.length
-              preferred_potential += num
-              self.result.max_tracker[list_name] = num
-            end
-          end
-          self.result.preferred_potential = preferred_potential
-          self.result.preferred_potential_ratio = preferred_potential_ratio
-        end
-        self.fill_to_ratio!
-        self.pusher.set_next_as_current!
-        self.result.elements.shuffle! if self.result.shuffle
+      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!
-      case self.current_strategy
-        when :drain_to_empty then
-          result.max = self.result.preferred_potential_ratio > 0 ? [(self.result.preferred_potential / self.result.preferred_potential_ratio), self.remaining_to_fill].min : self.remaining_to_fill
-        when :drain_to_limit, :sample then
-          result.max = Qfill::Result.get_limit_from_max_and_ratio(self.remaining_to_fill, result.ratio)
-      end
-      #result.max = Qfill::Result.get_limit_from_max_and_ratio(self.all_list_max, result.ratio)
-      if !result.list_ratios.empty?
-        self.fill_according_to_list_ratios!
+      strategy.result_max!
+      if result.list_ratios.empty?
+        fill_up_to_ratio!
       else
-        self.fill_up_to_ratio!
+        fill_according_to_list_ratios!
       end
     end
 
     def remaining_to_fill
-      self.all_list_max - self.fill_count
+      primary_list_total - fill_count
     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!
-      added = 0
-      tally = 0
-      ratio_modifier = 1
-      case self.current_strategy
-        when :drain_to_empty then
-          # Are there any elements in preferred queues that we should add?
-          if self.result.preferred_potential > 0
-            # Setup a ratio modifier for the non-preferred queues
-            result.list_ratios.each do |list_name, list_ratio|
-              max_from_list = self.result.max_tracker[list_name] || Qfill::Result.get_limit_from_max_and_ratio(result.max, list_ratio)
-              array_to_push = self.popper.next_objects!(list_name, max_from_list)
-              self.popper.current_index = self.popper.index_of(list_name)
-              added = result.push(array_to_push, list_name)
-              puts "[fill_according_to_list_ratios!]#{self}[#{list_name}][added:#{added}]" if Qfill::VERBOSE
-              tally += added
-            end
-            self.fill_count += tally
-          end
-        when :drain_to_limit
-          result.list_ratios.each do |list_name, list_ratio|
-            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)
-            self.popper.current_index = self.popper.index_of(list_name)
-            added = result.push(array_to_push, list_name)
-            puts "[fill_according_to_list_ratios!]#{self}[#{list_name}][added:#{added}]" if Qfill::VERBOSE
-            tally += added
-          end
-          self.fill_count += tally
-        when :sample then
-          #puts "#{!is_full?} && #{result.fill_count} >= #{result.max} && #{!self.popper.totally_empty?} && #{(list_ratio_tuple = result.current_list_ratio)}"
-          while !is_full? && !result.is_full? && !self.popper.totally_empty? && (list_ratio_tuple = result.current_list_ratio)
-            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
-            puts "[fill_according_to_list_ratios!]#{self}[#{list_ratio_tuple[0]}][added:#{added}]" if Qfill::VERBOSE
-            result.set_next_as_current!
-          end
-      end
+      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!
-      added = 0
-      tally = 0
-      if self.current_strategy == :drain_to_empty
-        self.popper.primary.each do |queue|
-          array_to_push = self.popper.next_objects!(queue.name, result.max)
-          added = result.push(array_to_push, queue.name)
-          self.popper.current_index = self.popper.index_of(queue.name)
-          puts "[fill_up_to_ratio!]#{self}[Q:#{queue.name}][added:#{added}]" if Qfill::VERBOSE
-          tally += added
-        end
-        self.fill_count += added
-      else
-        ratio = 1.0 / self.popper.primary.length # 1 divided by the number of queues
-        max_from_list = Qfill::Result.get_limit_from_max_and_ratio(result.max, ratio)
-        if self.current_strategy == :drain_to_limit
-          self.popper.primary.each do |queue|
-            array_to_push = self.popper.next_objects!(queue.name, max_from_list)
-            added = result.push(array_to_push, queue.name)
-            self.popper.current_index = self.popper.index_of(queue.name)
-            puts "[fill_up_to_ratio!]#{self}[Q:#{queue.name}][added:#{added}]" if Qfill::VERBOSE
-            tally += added
-          end
-          self.fill_count += tally
-        elsif self.current_strategy == :sample
-          while !is_full? && !result.is_full? && !self.popper.totally_empty? && (origin_list = self.popper.current_list)
-            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
-            puts "[fill_up_to_ratio!]#{self}[Added:#{added}][Max List:#{max_from_list}][ratio:#{ratio}][added:#{added}]" if Qfill::VERBOSE
-            self.popper.set_next_as_current!
-          end
-        end
-      end
+      strategy.fill_up_to_ratio!
     end
 
-    def current_strategy
-      (result.strategy || self.strategy)
+    def is_full?
+      fill_count >= all_list_max
     end
 
-    def is_full?
-      self.fill_count >= self.all_list_max
+    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
-      "[#{self.current_strategy}][Result Max:#{result.max}][All Max:#{self.all_list_max}][Current Max:#{self.result.max}][Filled:#{self.fill_count}][Primary #:#{self.popper.count_primary_elements}]"
+      "[#{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