fable 0.5.0

data/lib/fable/observer.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+# from: https://github.com/ruby/observer
+#
+# Implementation of the _Observer_ object-oriented design pattern.  The
+# following documentation is copied, with modifications, from "Programming
+# Ruby", by Hunt and Thomas; http://www.ruby-doc.org/docs/ProgrammingRuby/html/lib_patterns.html.
+#
+# See Observable for more info.
+
+# The Observer pattern (also known as publish/subscribe) provides a simple
+# mechanism for one object to inform a set of interested third-party objects
+# when its state changes.
+#
+# == Mechanism
+#
+# The notifying class mixes in the +Observable+
+# module, which provides the methods for managing the associated observer
+# objects.
+#
+# The observable object must:
+# * assert that it has +#changed+
+# * call +#notify_observers+
+#
+# An observer subscribes to updates using Observable#add_observer, which also
+# specifies the method called via #notify_observers. The default method for
+# #notify_observers is #update.
+#
+# === Example
+#
+# The following example demonstrates this nicely.  A +Ticker+, when run,
+# continually receives the stock +Price+ for its <tt>@symbol</tt>.  A +Warner+
+# is a general observer of the price, and two warners are demonstrated, a
+# +WarnLow+ and a +WarnHigh+, which print a warning if the price is below or
+# above their set limits, respectively.
+#
+# The +update+ callback allows the warners to run without being explicitly
+# called.  The system is set up with the +Ticker+ and several observers, and the
+# observers do their duty without the top-level code having to interfere.
+#
+# Note that the contract between publisher and subscriber (observable and
+# observer) is not declared or enforced.  The +Ticker+ publishes a time and a
+# price, and the warners receive that.  But if you don't ensure that your
+# contracts are correct, nothing else can warn you.
+#
+#   require "observer"
+#
+#   class Ticker          ### Periodically fetch a stock price.
+#     include Observable
+#
+#     def initialize(symbol)
+#       @symbol = symbol
+#     end
+#
+#     def run
+#       last_price = nil
+#       loop do
+#         price = Price.fetch(@symbol)
+#         print "Current price: #{price}\n"
+#         if price != last_price
+#           changed                 # notify observers
+#           last_price = price
+#           notify_observers(Time.now, price)
+#         end
+#         sleep 1
+#       end
+#     end
+#   end
+#
+#   class Price           ### A mock class to fetch a stock price (60 - 140).
+#     def self.fetch(symbol)
+#       60 + rand(80)
+#     end
+#   end
+#
+#   class Warner          ### An abstract observer of Ticker objects.
+#     def initialize(ticker, limit)
+#       @limit = limit
+#       ticker.add_observer(self)
+#     end
+#   end
+#
+#   class WarnLow < Warner
+#     def update(time, price)       # callback for observer
+#       if price < @limit
+#         print "--- #{time.to_s}: Price below #@limit: #{price}\n"
+#       end
+#     end
+#   end
+#
+#   class WarnHigh < Warner
+#     def update(time, price)       # callback for observer
+#       if price > @limit
+#         print "+++ #{time.to_s}: Price above #@limit: #{price}\n"
+#       end
+#     end
+#   end
+#
+#   ticker = Ticker.new("MSFT")
+#   WarnLow.new(ticker, 80)
+#   WarnHigh.new(ticker, 120)
+#   ticker.run
+#
+# Produces:
+#
+#   Current price: 83
+#   Current price: 75
+#   --- Sun Jun 09 00:10:25 CDT 2002: Price below 80: 75
+#   Current price: 90
+#   Current price: 134
+#   +++ Sun Jun 09 00:10:25 CDT 2002: Price above 120: 134
+#   Current price: 134
+#   Current price: 112
+#   Current price: 79
+#   --- Sun Jun 09 00:10:25 CDT 2002: Price below 80: 79
+module Observable
+
+  #
+  # Add +observer+ as an observer on this object. So that it will receive
+  # notifications.
+  #
+  # +observer+:: the object that will be notified of changes.
+  # +func+:: Symbol naming the method that will be called when this Observable
+  #          has changes.
+  #
+  #          This method must return true for +observer.respond_to?+ and will
+  #          receive <tt>*arg</tt> when #notify_observers is called, where
+  #          <tt>*arg</tt> is the value passed to #notify_observers by this
+  #          Observable
+  def add_observer(observer, func=:update)
+    @observer_peers = {} unless defined? @observer_peers
+    unless observer.respond_to? func
+      raise NoMethodError, "observer does not respond to `#{func}'"
+    end
+    @observer_peers[observer] = func
+  end
+
+  #
+  # Remove +observer+ as an observer on this object so that it will no longer
+  # receive notifications.
+  #
+  # +observer+:: An observer of this Observable
+  def delete_observer(observer)
+    @observer_peers.delete observer if defined? @observer_peers
+  end
+
+  #
+  # Remove all observers associated with this object.
+  #
+  def delete_observers
+    @observer_peers.clear if defined? @observer_peers
+  end
+
+  #
+  # Return the number of observers associated with this object.
+  #
+  def count_observers
+    if defined? @observer_peers
+      @observer_peers.size
+    else
+      0
+    end
+  end
+
+  #
+  # Set the changed state of this object.  Notifications will be sent only if
+  # the changed +state+ is +true+.
+  #
+  # +state+:: Boolean indicating the changed state of this Observable.
+  #
+  def changed(state=true)
+    @observer_state = state
+  end
+
+  #
+  # Returns true if this object's state has been changed since the last
+  # #notify_observers call.
+  #
+  def changed?
+    if defined? @observer_state and @observer_state
+      true
+    else
+      false
+    end
+  end
+
+  #
+  # Notify observers of a change in state *if* this object's changed state is
+  # +true+.
+  #
+  # This will invoke the method named in #add_observer, passing <tt>*arg</tt>.
+  # The changed state is then set to +false+.
+  #
+  # <tt>*arg</tt>:: Any arguments to pass to the observers.
+  def notify_observers(*arg)
+    if defined? @observer_state and @observer_state
+      if defined? @observer_peers
+        @observer_peers.each do |k, v|
+          k.send v, *arg
+        end
+      end
+      @observer_state = false
+    end
+  end
+
+end

data/lib/fable/path.rb

@@ -0,0 +1,186 @@
+module Fable
+  class Path
+    PARENT_ID = "^".freeze
+
+    attr_accessor :components, :relative
+
+    def relative?
+      relative == true
+    end
+
+    def head
+      components.first
+    end
+
+    def tail
+      if components.size >= 2
+        self.class.new(components[1..])
+      else
+        Path.self
+      end
+    end
+
+    def empty?
+      length == 0
+    end
+
+    def length
+      components.size
+    end
+
+    def contains_named_component?
+      components.any?{|x| !x.is_index? }
+    end
+
+    def self.self
+      Path.new(".")
+    end
+
+    def initialize(components, relative= false)
+      if components.is_a?(String)
+        parse_components_string(components)
+      else
+        self.components = components
+        self.relative = relative
+      end
+    end
+
+    def path_by_appending_path(path_to_append)
+      new_path = Path.new("")
+
+      upward_moves = 0
+
+      path_to_append.components.each do |component|
+        if component.is_parent?
+          upward_moves += 1
+        else
+          break
+        end
+      end
+
+      upward_jumps_to_make = (components.size - upward_moves-1)
+      components_to_add_at_this_level = (0..upward_jumps_to_make)
+
+      components_to_add_at_this_level.each do |i|
+        new_path.components << components[i]
+      end
+
+      components_to_add_after_upward_move = (upward_moves..path_to_append.components.size)
+
+      components_to_add_after_upward_move.each do |i|
+        new_path.components << path_to_append.components[i]
+      end
+
+      new_path
+    end
+
+    def path_by_appending_component(component)
+      if !component.is_a?(Path::Component)
+        component = Component.new(Component.component_type(component))
+      end
+      new_path = Path.new("")
+
+      new_path.components += self.components
+
+      new_path.components << component
+      new_path
+    end
+
+    def components_string
+      string = components.map{|x| x.to_s}.join('.')
+      if relative?
+        string = ".#{string}"
+      end
+
+      string
+    end
+
+    def parse_components_string(components_string)
+      self.components = []
+      return if components_string.strip.empty?
+
+      # Relative path when components staet with "."
+      # example: .^.^.hello.5 is equivalent to filesystem path
+      # ../../hello/5
+
+      if components_string.start_with?(".")
+        @relative = true
+      else
+        @relative = false
+      end
+
+      components_string.split('.').each do |section|
+        next if section.empty? #usually the first item in a relative path
+
+        components << Component.new(Component.component_type(section))
+      end
+    end
+
+    def ==(other_path)
+      return false if other_path.nil?
+      return false if other_path.components.size != components.size
+      return false if other_path.relative? != relative?
+      return other_path.components == components
+    end
+
+    def to_s
+      components_string
+    end
+
+    class Component
+      attr_accessor :index, :name
+
+      def is_index?
+        index >= 0
+      end
+
+      def is_parent?
+        name == Path::PARENT_ID
+      end
+
+      def self.component_type(value)
+        if value.is_a?(Numeric) || value.match?(/^\d+$/)
+          return {index: Integer(value)}
+        else
+          return {name: value}
+        end
+      end
+
+      def initialize(options)
+        if options[:index]
+          self.index = options[:index]
+          self.name = nil
+        elsif options[:name]
+          self.name = options[:name]
+          self.index = -1
+        end
+      end
+
+      def to_s
+        if is_index?
+          index.to_s
+        else
+          name
+        end
+      end
+
+      def ==(other_component)
+        return false if other_component.nil?
+
+        if self.is_index? == other_component.is_index?
+          if is_index?
+            return self.index == other_component.index
+          else
+            return self.name == other_component.name
+          end
+        end
+
+        return false
+      end
+
+      def self.parent_component
+        self.new(name: Path::PARENT_ID)
+      end
+    end
+  end
+end

data/lib/fable/pointer.rb

@@ -0,0 +1,42 @@
+module Fable
+  class Pointer
+    attr_accessor :container, :index
+
+    def self.start_of(container)
+      self.new(container, 0)
+    end
+
+    def self.null_pointer
+      self.new(nil, -1)
+    end
+
+    def initialize(container, index)
+      self.container = container
+      self.index = index
+    end
+
+    def resolve!
+      return container if index < 0
+      return nil if container.nil?
+      return container if container.content.empty?
+      return container.content[index]
+    end
+
+    def clone
+      self.class.new(self.container, self.index)
+    end
+
+    def null_pointer?
+      container.nil?
+    end
+
+    def path
+      return nil if null_pointer?
+      if index > 0
+        return container.path.path_by_appending_component(index)
+      else
+        return container.path
+      end
+    end
+  end
+end

data/lib/fable/profiler.rb

@@ -0,0 +1,287 @@
+module Fable
+  # Simple ink profiler that logs every instruction in the story and counts frequency and timing.
+  # To use:
+  #
+  #   profiler = story.start_profiling!
+  #
+  #   (play your story for a bit)
+  #
+  #   report = profiler.report;
+  #
+  #   story.end_profiling!;
+  class Profiler
+    # The root node in the hierarchical tree of recorded ink timings
+    attr_accessor :root_node, :continue_watch, :step_watch, :snapshot_watch,
+      :number_of_continues,
+      :continue_total, :step_total, :snapshot_total, :current_step_stack,
+      :current_step_details, :step_details
+
+    def initialize
+      self.root_node = ProfileNode.new
+      self.continue_watch = Stopwatch.new
+      self.step_watch = Stopwatch.new
+      self.snapshot_watch = Stopwatch.new
+      self.step_details = []
+      self.number_of_continues = 0
+      self.step_total = 0
+      self.snapshot_total = 0
+      self.continue_total = 0
+    end
+
+    # Generate a printable report based on the data recorded during profiling
+    def report
+      <<~STR
+      #{number_of_continues} CONTINUES / LINES:
+      TOTAL TIME: #{self.class.format_milliseconds(continue_total)}
+      SNAPSHOTTING: #{self.class.format_milliseconds(snapshot_total)}
+      OTHER: #{self.class.format_milliseconds(continue_total - (step_total + snapshot_total))}
+      #{root_node.to_s}
+      STR
+    end
+
+    def pre_continue!
+      self.continue_watch.restart!
+    end
+
+    def post_continue!
+      self.continue_watch.stop!
+      self.continue_total += continue_watch.elapsed_milliseconds
+      self.number_of_continues += 1
+    end
+
+    def pre_step!
+      self.current_step_stack = nil
+      self.step_watch.restart!
+    end
+
+    def step!(callstack)
+      self.step_watch.stop!
+
+      stack = []
+      callstack.elements.each do |element|
+        stack_element_name = ""
+        if !element.current_pointer.null_pointer?
+          path = element.current_pointer.path
+          path.components.each do |component|
+            if !component.is_index?
+              stack_element_name = component.name
+              break
+            end
+          end
+        end
+
+        stack << stack_element_name
+      end
+
+      self.current_step_stack = stack
+
+      current_object = callstack.current_element.current_pointer.resolve!
+
+      if current_object.is_a?(ControlCommand)
+        step_type = "#{current_object} CC"
+      else
+        step_type = current_object.class.to_s
+      end
+
+      self.current_step_details = OpenStruct.new(
+        type: step_type,
+        object: current_object
+      )
+
+      self.step_watch.start!
+    end
+
+    def post_step!
+      self.step_watch.stop!
+      duration = step_watch.elapsed_milliseconds
+      self.step_total += duration
+      self.root_node.add_sample(self.current_step_stack, duration)
+
+      self.current_step_details.time = duration
+      self.step_details << self.current_step_details
+    end
+
+    # Generate a printable report specifying the average and maximum times spent
+    # stepping over different internal ink instruction types.
+    # This report type is primarily used to profile the ink engine itself rather
+    # than your own specific ink.
+    def step_length_report
+      report = StringIO.new
+
+      report << "TOTAL:#{root_node.total_milliseconds}ms\n"
+
+      grouped_step_times = step_details.group_by{|x| x.type }
+
+      average_step_times = grouped_step_times.map do |type, details|
+        average = details.sum{|x| x.time }/details.size
+        [type, average]
+      end.sort_by{|type, average| average}.reverse.map{|type, average| "#{type}: #{average}ms" }
+
+      report << "AVERAGE STEP TIMES: #{average_step_times.join(", ")}\n"
+
+      accumulated_step_times = grouped_step_times.map do |type, details|
+        sum = details.sum{|x| x.time }
+        ["#{type} (x#{details.size})", sum]
+      end.sort_by{|type, sum| sum}.reverse.map{|type, sum| "#{type}: #{sum}ms" }
+
+      report << "ACCUMULATED STEP TIMES: #{accumulated_step_times.join(", ")}\n"
+
+      report.rewind
+      report.read
+    end
+
+    # Create a large log of all the internal instructions that were evaluated while
+    # profiling was active. Log is in a tab-separated format, for easing loading into
+    # a spreadsheet
+    def mega_log
+      report = StringIO.new
+      report << "Step type\tDescription\tPath\tTime\n"
+
+      step_details.each do |step|
+        report << "#{step.type}\t#{step.object.to_s}\t#{step.object.path.to_s}\t#{step.time.to_s}\n"
+      end
+
+      report.rewind
+      report.read
+    end
+
+    def pre_snapshot!
+      self.snapshot_watch.restart!
+    end
+
+    def post_snapshot!
+      self.snapshot_watch.stop!
+      self.snapshot_total += self.snapshot_watch.elapsed_milliseconds
+    end
+
+    def self.format_milliseconds(milliseconds)
+      if milliseconds > 1_000
+        "#{(milliseconds/1_000.0).round(2)} s"
+      else
+        "#{(milliseconds).round(3)} ms"
+      end
+    end
+
+    # Node used in the hierarchical tree of timings used by the Profiler.
+    # Each node corresponds to a single line viewable in a UI-based representation.
+    class ProfileNode
+      attr_accessor :key, :nodes, :total_milliseconds, :total_sample_count,
+        :self_sample_count, :self_milliseconds
+
+      def has_children?
+        !nodes.nil? && nodes.size > 0
+      end
+
+      def initialize(key="")
+        self.key = key
+        self.total_sample_count = 0
+        self.total_milliseconds = 0
+        self.self_sample_count = 0
+        self.self_milliseconds = 0
+      end
+
+      def add_sample(stack, duration)
+        add_sample_with_index(stack, -1, duration)
+      end
+
+      def add_sample_with_index(stack, stack_index, duration)
+        self.total_milliseconds += 1
+        self.total_milliseconds += duration
+
+        if stack_index == (stack.size - 1)
+          self.self_sample_count += 1
+          self.self_milliseconds += duration
+        end
+
+        if stack_index < stack.size
+          add_sample_to_node(stack, stack_index + 1, duration)
+        end
+      end
+
+      def add_sample_to_node(stack, stack_index, duration)
+        node_key = stack[stack_index]
+        nodes ||= {node_key => ProfileNode.new(node_key)}
+
+        nodes[node_key].add_sample_with_index(stack, stack_index, duration)
+      end
+
+      def print_hierarchy(io, indent)
+        self.class.pad(io, indent)
+
+        io << "#{key}: #{own_report}\n"
+
+        return if nodes.nil?
+
+        nodes.sort_by{|k,v| v.total_milliseconds }.reverse.each do |key, node|
+          node.print_hierarchy(io, indent + 1)
+        end
+      end
+
+      # Generates a string giving timing information for this single node, including
+      # total milliseconds spent on the piece of ink, the time spent within itself
+      # (v.s. spent in children), as well as the number of samples (instruction steps)
+      # recorded for both too.
+      def own_report
+        report = StringIO.new
+
+        report << "total #{Profiler.format_milliseconds(total_milliseconds)}"
+        report << ", self #{Profiler.format_milliseconds(self_milliseconds)}"
+        report << " (#{self_sample_count} self samples, #{total_sample_count} total)"
+
+        report.rewind
+        report.read
+      end
+
+      def to_s
+        report = StringIO.new
+        print_hierarchy(report, 0)
+        report.rewind
+        report.read
+      end
+
+      def self.pad(io, indent)
+        io << " " * indent
+      end
+    end
+
+    class Stopwatch
+      attr_accessor :start_time, :stop_time, :elapsed_milliseconds
+
+      def initialize
+        @elapsed_milliseconds = 0
+      end
+
+      def start!
+        @stop_time = nil
+        @start_time = Time.now.utc
+      end
+
+      def reset!
+        @elapsed_milliseconds = 0
+      end
+
+      def restart!
+        reset!
+        start!
+      end
+
+      def stop!
+        @stop_time = Time.now.utc
+        @elapsed_milliseconds += elapsed_from_start_to_stop
+      end
+
+      def elapsed_milliseconds
+        return -1 if start_time.nil?
+        if @elapsed_milliseconds == 0 && stop_time.nil?
+          return elapsed_from_start_to_stop
+        else
+          @elapsed_milliseconds
+        end
+      end
+
+      def elapsed_from_start_to_stop
+        ((@stop_time || Time.now.utc).to_r - @start_time.to_r) * 1000.0
+      end
+    end
+  end
+end