bonito 0.1.0

data/lib/bonito.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bonito/serial_timeline'
+require 'bonito/moment'
+require 'bonito/scope'
+require 'bonito/runner'
+require 'bonito/parallel_timeline'
+require 'bonito/progress'

data/lib/bonito/moment.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'bonito/timeline'
+
+module Bonito
+  class MomentScheduler < Scheduler # :nodoc:
+    def each
+      yield ScopedMoment.new(timeline, starting_offset, scope)
+    end
+  end
+
+  # A Moment represents a single instant in time in which events may occur.
+  # Scheduler classes may be used in order to yield a sequence of
+  # Moment objects, each of which has been decorated with a Scope object,
+  # within the context of which the events defined in the Moment will be
+  # evaluated, as well as an Integer offset representing a number of
+  # seconds from some arbitrary start point.
+  #
+  # Such a Scheduler object may be passed to a Runner, along with some fixed
+  # starting point.  The runner can the be used to  evaluate the events defined
+  # in each of the scheduled Moment objects, simulating the time at which they
+  # occur to be that of the starting point plus the offset.
+  class Moment < Timeline
+    schedule_with MomentScheduler
+
+    # Initialises a new Moment
+    # [block]
+    #   A Proc that will be evaluated at some simulated point in time by a
+    #   Runner
+    def initialize(&block)
+      @block = block
+      super 0
+    end
+
+    def to_proc # :nodoc:
+      @block
+    end
+  end
+end

data/lib/bonito/parallel_timeline.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'bonito/timeline'
+require 'bonito/serial_timeline'
+require 'algorithms'
+
+module Bonito
+  class ParallelScheduler < Scheduler # :nodoc:
+    def initialize(parallel, starting_offset, scope, opts = {})
+      super
+      @schedulers = parallel.map do |timeline|
+        timeline.schedule(starting_offset, scope, opts).to_enum
+      end
+      @heap = LazyMinHeap.new(*@schedulers)
+    end
+
+    def each
+      @heap.each { |moment| yield moment }
+    end
+  end
+
+  class ParallelTimeline < Timeline # :nodoc:
+    schedule_with ParallelScheduler
+
+    def initialize(&block)
+      super 0
+      instance_eval(&block) if block_given?
+    end
+
+    def over(duration, after: 0, &block)
+      use Bonito::SerialTimeline.new(duration, &block), after: after
+    end
+
+    def also(over: duration, after: 0, &block)
+      over(over, after: after, &block)
+    end
+
+    def use(*timelines, after: 0)
+      timelines.each do |timeline|
+        send :<<, OffsetTimeline.new(timeline, after)
+      end
+      self
+    end
+
+    def repeat(times:, over:, after: 0, &block)
+      times.times { over(over, after: after, &block) }
+      self
+    end
+
+    private
+
+    def <<(offset_timeline)
+      super offset_timeline
+      self.duration = [
+        duration, offset_timeline.offset + offset_timeline.duration
+      ].max
+      self
+    end
+  end
+
+  class LazyMinHeap # :nodoc:
+    include Enumerable
+
+    def initialize(*sorted_enums)
+      @heap = Containers::MinHeap.new []
+      @enums = Set[*sorted_enums]
+      @enums.each(&method(:push_from_enum))
+    end
+
+    def pop
+      moment = @heap.next_key
+      enum = @heap.pop
+      push_from_enum enum
+      moment
+    end
+
+    def empty?
+      @enums.empty? && @heap.empty?
+    end
+
+    def each
+      yield pop until empty?
+    end
+
+    private
+
+    def push_from_enum(enum)
+      @heap.push enum.next, enum
+    rescue StopIteration
+      @enums.delete enum
+    end
+  end
+end

data/lib/bonito/progress.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'ruby-progressbar'
+module Bonito
+  module ProgressCounter # :nodoc:
+    attr_reader :total
+    attr_reader :current
+
+    class Unknown # :nodoc:
+      include Singleton
+      def to_s
+        '-'
+      end
+    end
+
+    module ClassMethods # :nodoc:
+      def factory(*args)
+        ->(total: nil, prefix: nil) { new(*args, total: total, prefix: prefix) }
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    def setup(total: ProgressCounter::Unknown.instance, prefix: nil)
+      @total = total
+      @prefix = prefix
+      @current = 0
+    end
+
+    def increment(change)
+      @current += change
+      on_increment change
+      self
+    end
+
+    def to_s
+      "#{prefix} #{current} / #{total}"
+    end
+
+    private
+
+    def prefix
+      @prefix ||= "#{self.class}{#{object_id}} : Progress Made :"
+    end
+  end
+
+  class ProgressLogger # :nodoc:
+    include ProgressCounter
+
+    def initialize(logger = Logger.new(STDOUT), **opts)
+      @logger = logger
+      setup opts
+    end
+
+    def on_increment(_increment)
+      @logger.info to_s
+    end
+  end
+
+  class ProgressBar # :nodoc:
+    include ProgressCounter
+
+    def initialize(**opts)
+      @bar = ::ProgressBar.create opts
+      @bar.total = opts[:total]
+      setup opts
+    end
+
+    def on_increment(increment)
+      increment.times { @bar.increment }
+    end
+  end
+
+  class ProgressDecorator < SimpleDelegator # :nodoc:
+    def initialize(enumerable, progress)
+      @progress = progress
+      super enumerable
+    end
+
+    def each
+      return to_enum(:each) unless block_given?
+
+      __getobj__.each do |item|
+        yield item
+        @progress.increment 1
+      end
+    end
+  end
+end

data/lib/bonito/runner.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'timecop'
+module Bonito # :nodoc:
+  class Runner # :nodoc:
+    def initialize(enumerable, opts = {})
+      @enumerable = enumerable
+      @opts = opts
+    end
+
+    def live?
+      @opts.fetch(:live) { false }
+    end
+
+    def daemonise?
+      @opts.fetch(:daemonise) { false }
+    end
+
+    def call
+      Process.daemon if daemonise?
+      @enumerable.each do |moment|
+        maybe_sleep moment
+        moment.evaluate
+      end
+    end
+
+    private
+
+    def maybe_sleep(moment)
+      return unless live? && (nap_time = moment.offset - Time.now).positive?
+
+      sleep nap_time
+    end
+  end
+
+  def self.run(
+    serial, starting:, scope: Scope.new,
+    progress_factory: ProgressLogger.factory, **opts
+  )
+    scheduler = serial.scheduler(starting, scope, opts)
+    progress = progress_factory.call total: scheduler.count
+    scheduler = ProgressDecorator.new scheduler, progress
+    Runner.new(scheduler, opts).call
+  end
+end

data/lib/bonito/scope.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Bonito
+  class Accessor # :nodoc:
+    def initialize(scope, symbol)
+      @scope = scope
+      @symbol = symbol
+      @instance_var = :"@#{@symbol.to_s.chomp('=')}"
+    end
+
+    def access(*args)
+      assignment? ? set(*args) : get
+    end
+
+    # :reek:NilCheck
+    # String#match? Unavailable for Ruby 2.3
+    def assignment?
+      !@symbol.to_s.match(/\w+=/).nil?
+    end
+
+    private
+
+    def get
+      scope = @scope
+      while scope
+        if scope.instance_variable_defined? @instance_var
+          return scope.instance_variable_get @instance_var
+        end
+
+        scope = scope.parent
+      end
+      raise NameError
+    end
+
+    def set(value)
+      @scope.instance_variable_set @instance_var, value
+    end
+  end
+
+  class Scope # :nodoc:
+    def initialize(parent = nil)
+      @parent = parent
+    end
+
+    def push
+      self.class.new self
+    end
+
+    protected
+
+    attr_reader :parent
+
+    private
+
+    def method_missing(symbol, *args)
+      Accessor.new(self, symbol).access(*args)
+    rescue NameError
+      super
+    end
+
+    # :reek:BooleanParameter
+    # Inherits interface from Object#respond_to_missing?
+    def respond_to_missing?(symbol, respond_to_private = false)
+      accessor = Accessor.new(self, symbol)
+      return true if accessor.assignment?
+
+      accessor.access
+      true
+    rescue NameError
+      super
+    end
+  end
+end

data/lib/bonito/serial_timeline.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require 'bonito/timeline'
+require 'bonito/moment'
+require 'securerandom'
+require 'timecop'
+
+module Bonito # :nodoc:
+  class SerialScheduler < Scheduler # :nodoc:
+    def initialize(serial, starting_offset, parent_scope, opts = {})
+      super serial, starting_offset, parent_scope.push, opts
+      @distribution = Distribution.new starting_offset, serial, opts
+    end
+
+    # :reek:NestedIterators:
+    # Not sure how this can be avoided nicely at the moment
+    def each
+      @distribution.each do |timeline, offset|
+        timeline.scheduler(offset, scope, opts).each do |moment|
+          yield moment
+        end
+      end
+    end
+  end
+
+  # A SerialTimeline is a data structure with a duration (measured in seconds)
+  # that contains +timelines+. A +timeline+ is any instance of a class that
+  # inherits from the Timeline base class.
+  #
+  # A SerialTimeline serves to define an interval in which it may be
+  # _simulated_ that one or more Moment objects are _evaluated_ _in_ series_.
+  #
+  # A SerialTimeline exposes methods that can either be used to define these
+  # Moment objects directly or to create additional _child_ data structures
+  # (i.e ParallelTimeline objects or further, child SerialTimeline objects)
+  # which can in turn be provide more fine grained control over precisely _when_
+  # any given Moment objects may be evaluated.
+  #
+  # === Example
+  #
+  #   Bonito.over(2.weeks) do
+  #     please { puts Time.now }
+  #   end
+  #
+  # The above defines a SerialTimeline (using the Bonito#over module method)
+  # that specifies a 2 week time period. A single Moment is included in this
+  # serial (via the #please factory method).  When the top level SerialTimeline
+  # is evaluated (using a Runner object) the block
+  #
+  #   puts Time.now
+  #
+  # is evaluated _exactly_ _once_. Furthermore, the simulated time at which
+  # the block is evaluated will be contained at some point within the 2 week
+  # interval beginning on some start date provided when instantiating the
+  # Runner object.
+  #
+  # As mentioned, it is also possible to include other data structures within
+  # SerialTimeline objects, including other SerialTimeline objects.
+  #
+  # === Example
+  #
+  # We could use the #over method to add an empty SerialTimeline to the previous
+  # example in order to force the already included Moment to be evaluated
+  # during the last day of the 2 week period.
+  #
+  #   Bonito.over(2.weeks) do
+  #     over(2.weeks - 1.day)  # This defines an empty serial
+  #     please { puts Time.now }
+  #   end
+  #
+  # The empty SerialTimeline returned by the #over factory method consumes 13
+  # days of the parent SerialTimeline object's total duration of 2 weeks.  This
+  # means that when this parent SerialTimeline is evaluated, the Moment will be
+  # _as_ _if_ _it_ _occurred_ during the _final_ _day_ of the 2 week period.
+  #
+  # Finally, we may also define ParallelTimeline objects within serials using
+  # the #simultaneously method.  These allow for multiple SerialTimeline
+  # objects to be defined over the same time period and for any Moment
+  # objects contained within to be _interleaved_ when the parent SerialTimeline
+  # is ultimately evaluated.
+  #
+  # The #simultaneously method instantiates a ParallelTimeline object, whilst
+  # accepting a block.  The block is evaluated within the context of the new
+  # ParallelTimeline. Timelines defined within this block will be evaluated in
+  # parallel.
+  #
+  # Note that ParallelTimeline implements many of the same methods as
+  # SerialTimeline
+  #
+  # === Example
+  #
+  #   Bonito.over(2.weeks) do
+  #     simultaneously do
+  #       over 1.week do
+  #         puts "SerialTimeline 1 #{Time.now}"
+  #       end
+  #       over 6.days, after: 1.day do
+  #         puts "SerialTimeline 2 #{Time.now}"
+  #       end
+  #     end
+  #
+  #     over 1.week {}  # This defines an empty serial
+  #   end
+  #
+  # Now, when evaluating this SerialTimeline both the blocks
+  #   puts "SerialTimeline 1 #{Time.now}"
+  # and
+  #   puts "SerialTimeline 2 #{Time.now}"
+  # will be evaluated once during the first week.  The precise instant is
+  # chosen randomly within this interval with the only constraint being
+  # that the second block cannot be evaluated during the first day (This
+  # offset is controlled by the +after+ parameter of the #simultaneously
+  # method).
+  #
+  # *Note* that the moment from the second SerialTimeline could still be
+  # evaluated at a simulated time _before_ that at which the moment from the
+  # first SerialTimeline is evaluated.
+  class SerialTimeline < Timeline
+    schedule_with SerialScheduler
+
+    # Instantiate a new SerialTimeline object
+    #
+    # [duration]
+    #   The total time period (in seconds) that the
+    #   SerialTimeline encompasses
+    # [parent]
+    #   If the SerialTimeline is a child of another Timeline,
+    #   parent is this Timeline
+    # [block]
+    #   A block that will be evaluated within the context of
+    #   the newly created SerialTimeline.  Note that the following two
+    #   statements are equivalent
+    #
+    #   a_serial = Bonito::SerialTimeline.new(1.week) do
+    #     please { p Time.now }
+    #   end
+    #
+    #   another_serial = Bonito::SerialTimeline.new 1.week
+    #   serial.please { p Time.now }
+    #
+    # The ability to include a block in this way is in order to allow the
+    # code used to define a given SerialTimeline will reflect its hierarchy.
+    def initialize(duration, parent = nil, &block)
+      @parent = parent
+      @total_child_duration = 0
+      super duration
+      instance_eval(&block) if block_given?
+    end
+
+    # The the amount of #duration remaining taking into account the duration of
+    # any Timeline objects included as children of the SerialTimeline.
+    def unused_duration
+      duration - @total_child_duration
+    end
+
+    # Define a new SerialTimeline and add it as a child to the current
+    # SerialTimeline
+    #
+    # [duration]
+    #   The duration (in seconds) of the newly created child SerialTimeline
+    #
+    # [block]
+    #   A block passed to the #new method on the child SerialTimeline object
+    #
+    # Returns the newly created SerialTimeline object
+    def over(duration, &block)
+      self.class.new(duration, self, &block).tap(&method(:use))
+    end
+
+    # Define a new Moment and add it as a child to the current SerialTimeline
+    #
+    # [block]
+    #   A block passed to the #new method on the child Moment object
+    #
+    # Returns the newly created Moment object
+    def please(&block)
+      Moment.new(&block).tap(&method(:use))
+    end
+
+    # Define a new serial and append it multiple times as a child of the
+    # current SerialTimeline object.
+    #
+    # [times]
+    #   The number of times that the new SerialTimeline object to
+    #   be appended to the current SerialTimeline
+    #
+    # [over]
+    #   The total duration (in senconds) of the new
+    #   repeated SerialTimeline objects.
+    #
+    # [block]
+    #   A block passed to the #new method on the child SerialTimeline
+    #   object
+    #
+    # Returns the current SerialTimeline
+    def repeat(times:, over:, &block)
+      repeated_block = proc { times.times { instance_eval(&block) } }
+      over(over, &repeated_block)
+    end
+
+    # Define a new ParallelTimeline object append it as a child to the current
+    # SerialTimeline. Also permit the evaluation of methods within the context
+    # of the new ParallelTimeline.
+    #
+    # [block]
+    #   A block to be passed to the #new method on the child ParallelTimeline
+    #   method.
+    #
+    # Returns the current SerialTimeline object
+    def simultaneously(&block)
+      use ParallelTimeline.new(&block)
+    end
+
+    # Append an existing Timeline as a child of the current SerialTimeline
+    #
+    # [timelines]
+    #   An array of Timeline objects that will be
+    #   appended, in order to the current SerialTimeline
+    #
+    # Returns the current SerialTimeline object
+    def use(*timelines)
+      timelines.each { |timeline| send :<<, timeline }
+      self
+    end
+
+    # Combine two Windows into a single, larger SerialTimeline object.
+    #
+    # [other]
+    #   Some other SerialTimeline object
+    #
+    # Returns a SerialTimeline object consisting of the ordered child Timeline
+    # objects of the current SerialTimeline with the ordered child Timeline
+    # objects of +other+ appended to the end.
+    def +(other)
+      SerialTimeline.new duration + other.duration do
+        use(*(to_a + other.to_a))
+      end
+    end
+
+    # Repeatedly apply the #+ method of the current SerialTimeline to itself
+    #
+    # [other]
+    #   Denotes the number of times the current serial
+    #   should be added to itself.
+    #
+    # Returns a new SerialTimeline object
+    #
+    # Note that the following statements are equivalent for
+    # some serial +serial+:
+    #
+    #   serial * 3
+    #   serial + serial + serial
+    #
+    def *(other)
+      SerialTimeline.new(duration * other) do
+        use(*Array.new(other) { entries }.reduce(:+))
+      end
+    end
+
+    # Scale up a serial by parallelising it according to some factor
+    #
+    # [other]
+    #   An Integer denoting the degree of parallelism with
+    #   which to scale the serial.
+    #
+    # Returns a new ParallelTimeline whose child timelines are precisely
+    # the current serial repeated +other+ times.
+    def **(other)
+      this = self
+      SerialTimeline.new(duration) do
+        simultaneously { use(*Array.new(other) { this }) }
+      end
+    end
+
+    private
+
+    def <<(timeline)
+      tap do
+        @total_child_duration += timeline.duration
+        if @total_child_duration > duration
+          raise WindowDurationExceeded, "#{@total_child_duration} > #{duration}"
+        end
+
+        super timeline
+      end
+    end
+  end
+
+  class BonitoException < StandardError
+  end
+
+  class WindowDurationExceeded < BonitoException
+  end
+
+  def self.over(duration, &block)
+    SerialTimeline.new duration, &block
+  end
+
+  class Distribution # :nodoc:
+    include Enumerable
+
+    def initialize(start, serial, stretch: 1)
+      @start = start
+      @serial = serial
+      @stretch = stretch
+    end
+
+    def each
+      @serial.zip(generate_offsets).reduce(0) do |consumed, zipped|
+        timeline, offset = zipped
+        yield timeline, @start + (@stretch * (offset + consumed))
+        consumed + timeline.duration
+      end
+    end
+
+    private
+
+    def interval
+      @serial.unused_duration
+    end
+
+    def size
+      @serial.size
+    end
+
+    def generate_offsets
+      Array.new(size) { SecureRandom.random_number(interval) }.sort
+    end
+  end
+end