scarpe-components 0.1.0 → 0.3.0

data/lib/scarpe/components/promises.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+module Scarpe; end
+module Scarpe::Components; end
+module Scarpe
+  # Scarpe::Promise is a promises library, but one with no form of built-in
+  # concurrency. Instead, promise callbacks are executed synchronously.
+  # Even execution is usually synchronous, but can also be handled manually
+  # for forms of execution not controlled in Ruby (like Webview.)
+  #
+  # Funny thing... We need promises as an API concept since we have a JS event
+  # loop doing its thing, and we need to respond to actions that it takes.
+  # But there's not really a Ruby implementation of Promises *without* an
+  # attached form of concurrency. So here we are, writing our own :-/
+  #
+  # In theory you could probably write some kind of "no-op thread pool"
+  # for the ruby-concurrency gem, pass it manually to every promise we
+  # created and then raise an exception any time we tried to do something
+  # in the background. That's probably more code than writing our own, though,
+  # and we'd be fighting it constantly.
+  #
+  # This class is inspired by concurrent-ruby [Promise](https://ruby-concurrency.github.io/concurrent-ruby/1.1.5/Concurrent/Promise.html)
+  # which is inspired by Javascript Promises, which is what we actually need
+  # for our use case. We can't easily tell when our WebView begins processing
+  # our request, which removes the :processing state. This can be used for
+  # executing JS, but also generally waiting on events.
+  #
+  # We don't fully control ordering here, so it *is* conceivable that a
+  # child waiting on a parent can be randomly fulfilled, even if we didn't
+  # expect it. We don't consider that an error. Similarly, we'll call
+  # on_scheduled callbacks if a promise is fulfilled, even though we
+  # never explicitly scheduled it. If a promise is *rejected* without
+  # ever being scheduled, we won't call those callbacks.
+  class Promise
+    include Shoes::Log
+
+    # The unscheduled promise state means it's waiting on a parent promise that
+    # hasn't completed yet. The pending state means it's waiting to execute.
+    # Fulfilled means it has completed successfully and returned a value,
+    # while rejected means it has failed, normally producing a reason.
+    PROMISE_STATES = [:unscheduled, :pending, :fulfilled, :rejected]
+
+    # The state of the promise, which should be one of PROMISE_STATES
+    attr_reader :state
+
+    # The parent promises of this promise, sometimes an empty array
+    attr_reader :parents
+
+    # If the promise is fulfilled, this is the value returned
+    attr_reader :returned_value
+
+    # If the promise is rejected, this is the reason, sometimes an exception
+    attr_reader :reason
+
+    # Create a promise and then instantly fulfill it.
+    def self.fulfilled(return_val = nil, parents: [], &block)
+      p = Promise.new(parents: parents, &block)
+      p.fulfilled!(return_val)
+      p
+    end
+
+    # Create a promise and then instantly reject it.
+    def self.rejected(reason = nil, parents: [])
+      p = Promise.new(parents: parents)
+      p.rejected!(reason)
+      p
+    end
+
+    # Fulfill the promise, setting the returned_value to value
+    def fulfilled!(value = nil)
+      set_state(:fulfilled, value)
+    end
+
+    # Reject the promise, setting the reason to reason
+    def rejected!(reason = nil)
+      set_state(:rejected, reason)
+    end
+
+    # Create a new promise with this promise as a parent. It runs the
+    # specified code in block when scheduled.
+    def then(&block)
+      Promise.new(parents: [self], &block)
+    end
+
+    # The Promise.new method, along with all the various handlers,
+    # are pretty raw. They'll do what promises do, but they're not
+    # the prettiest. However, they ensure that guarantees are made
+    # and so on, so they're great as plumbing under the syntactic
+    # sugar above.
+    #
+    # Note that the state passed in may not be the actual initial
+    # state. If a parent is rejected, the state will become
+    # rejected. If no parents are waiting or failed then a state
+    # of nil or :unscheduled will become :pending.
+    #
+    # @param state [Symbol] One of PROMISE_STATES for the initial state
+    # @param parents [Array] A list of promises that must be fulfilled before this one is scheduled
+    # @yield A block that executes when this promise is scheduled - when its parents, if any, are all fulfilled
+    def initialize(state: nil, parents: [], &scheduler)
+      log_init("Promise")
+
+      # These are as initially specified, and effectively immutable
+      @state = state
+      @parents = parents
+
+      # These are what we're waiting on, and will be
+      # removed as time goes forward.
+      @waiting_on = parents.select { |p| !p.complete? }
+      @on_fulfilled = []
+      @on_rejected = []
+      @on_scheduled = []
+      @scheduler = scheduler
+      @executor = nil
+      @returned_value = nil
+      @reason = nil
+
+      if complete?
+        # Did we start out already fulfilled or rejected?
+        # If so, we can skip a lot of fiddly checking.
+        # Don't need a scheduler or to care about parents
+        # or anything.
+        @waiting_on = []
+        @scheduler = nil
+      elsif @parents.any? { |p| p.state == :rejected }
+        @state = :rejected
+        @waiting_on = []
+        @scheduler =  nil
+      elsif @state == :pending
+        # Did we get an explicit :pending? Then we don't need
+        # to schedule ourselves, or care about the scheduler
+        # in general.
+        @scheduler = nil
+      elsif @state.nil? || @state == :unscheduled
+        # If no state was given or we're unscheduled, we'll
+        # wait until our parents have all completed to
+        # schedule ourselves.
+
+        if @waiting_on.empty?
+          # No further dependencies, we can schedule ourselves
+          @state = :pending
+
+          # We have no on_scheduled handlers yet, but this will
+          # call and clear the scheduler.
+          call_handlers_for(:pending)
+        else
+          # We're still waiting on somebody, no scheduling yet
+          @state = :unscheduled
+          @waiting_on.each do |dep|
+            dep.on_fulfilled { parent_fulfilled!(dep) }
+            dep.on_rejected { parent_rejected!(dep) }
+          end
+        end
+      end
+    end
+
+    # Return true if the Promise is either fulfilled or rejected.
+    #
+    # @return [Boolean] true if the promise is fulfilled or rejected
+    def complete?
+      @state == :fulfilled || @state == :rejected
+    end
+
+    # Return true if the promise is already fulfilled.
+    #
+    # @return [Boolean] true if the promise is fulfilled
+    def fulfilled?
+      @state == :fulfilled
+    end
+
+    # Return true if the promise is already rejected.
+    #
+    # @return [Boolean] true if the promise is rejected
+    def rejected?
+      @state == :rejected
+    end
+
+    # An inspect method to give slightly smaller output, for ease of reading in irb
+    def inspect
+      "#<Scarpe::Promise:#{object_id} " +
+        "@state=#{@state.inspect} @parents=#{@parents.inspect} " +
+        "@waiting_on=#{@waiting_on.inspect} @on_fulfilled=#{@on_fulfilled.size} " +
+        "@on_rejected=#{@on_rejected.size} @on_scheduled=#{@on_scheduled.size} " +
+        "@scheduler=#{@scheduler ? "Y" : "N"} @executor=#{@executor ? "Y" : "N"} " +
+        "@returned_value=#{@returned_value.inspect} @reason=#{@reason.inspect}" +
+        ">"
+    end
+
+    # These promises are mostly designed for external execution.
+    # You could put together your own thread-pool, or use RPC,
+    # a WebView, a database or similar source of external calculation.
+    # But in many cases it's reasonable to execute locally.
+    # In those cases, you can register an executor which will be
+    # called when the promise is ready to execute but has not yet
+    # done so. Registering an executor on a promise that is
+    # already fulfilled is an error. Registering an executor on
+    # a promise that has already rejected is a no-op.
+    def to_execute(&block)
+      case @state
+      when :fulfilled
+        # Should this be a no-op instead?
+        raise Scarpe::NoOperationError, "Registering an executor on an already fulfilled promise means it will never run!"
+      when :rejected
+        return
+      when :unscheduled
+        @executor = block # save for later
+      when :pending
+        @executor = block
+        call_executor
+      else
+        raise Scarpe::InternalError, "Internal error, illegal state!"
+      end
+
+      self
+    end
+
+    private
+
+    # set_state looks at the old and new states of the promise. It calls handlers and updates tracking
+    # data accordingly.
+    def set_state(new_state, value_or_reason = nil)
+      old_state = @state
+
+      # First, filter out illegal input
+      unless PROMISE_STATES.include?(old_state)
+        raise Scarpe::InternalError, "Internal Promise error! Internal state was #{old_state.inspect}! Legal states: #{PROMISE_STATES.inspect}"
+      end
+
+      unless PROMISE_STATES.include?(new_state)
+        raise Scarpe::InternalError, "Internal Promise error! Internal state was set to #{new_state.inspect}! " +
+          "Legal states: #{PROMISE_STATES.inspect}"
+      end
+
+      if new_state != :fulfilled && new_state != :rejected && !value_or_reason.nil?
+        raise Scarpe::InternalError, "Internal promise error! Non-completed state transitions should not specify a value or reason!"
+      end
+
+      # Here's our state-transition grid for what we're doing here.
+      # "From" state is on the left, "to" state is on top.
+      #
+      #    U P F R
+      #
+      # U  - 1 . .
+      # P  X - . .
+      # F  X X - X
+      # R  X X X -
+      #
+      # -  Change from same to same, no effect
+      # X  Illegal for one reason or another, raise error
+      # .  Great, no problem, run handlers but not @scheduler or @executor
+      # 1  Interesting case - if we have an executor, actually change to a *different* state instead
+
+      # Transitioning from our state to our same state? No-op.
+      return if new_state == old_state
+
+      # Transitioning to any *different* state after being fulfilled or rejected? Nope. Those states are final.
+      if complete?
+        raise Scarpe::InternalError, "Internal Promise error! Trying to change state from #{old_state.inspect} to #{new_state.inspect}!"
+      end
+
+      if old_state == :pending && new_state == :unscheduled
+        raise Shoes::Errors::InvalidAttributeValueError, "Can't change state from :pending to :unscheduled! Scheduling is not reversible!"
+      end
+
+      # The next three checks should all be followed by calling handlers for the newly-changed state.
+      # See call_handlers_for below.
+
+      # Okay, we're getting scheduled.
+      if old_state == :unscheduled && new_state == :pending
+        @state = new_state
+        call_handlers_for(new_state)
+
+        # It's not impossible for the scheduler to do something that fulfills or rejects the promise.
+        # In that case it *also* called the appropriate handlers. Let's get out of here.
+        return if @state == :fulfilled || @state == :rejected
+
+        if @executor
+          # In this case we're still pending, but we have a synchronous executor. Let's do it.
+          call_executor
+        end
+
+        return
+      end
+
+      # Setting to rejected calls the rejected handlers. But no scheduling ever occurs, so on_scheduled handlers
+      # will never be called.
+      if new_state == :rejected
+        @state = :rejected
+        @reason = value_or_reason
+        call_handlers_for(new_state)
+      end
+
+      # If we go straight from :unscheduled to :fulfilled we *will* run the on_scheduled callbacks,
+      # because we pretend the scheduling *did* occur at some point. Normally that'll be no callbacks,
+      # of course.
+      #
+      # Fun-but-unfortunate trivia: you *can* fulfill a promise before all its parents are fulfilled.
+      # If you do, the unfinished parents will result in nil arguments to the on_fulfilled handler,
+      # because we have no other value to provide. The scheduler callback will never be called, but
+      # the on_scheduled callbacks, if any, will be.
+      if new_state == :fulfilled
+        @state = :fulfilled
+        @returned_value = value_or_reason
+        call_handlers_for(new_state)
+      end
+    end
+
+    # This private method calls handlers for a new state, removing those handlers
+    # since they have now been called. This interacts subtly with set_state()
+    # above, particularly in the case of fulfilling a promise without it ever being
+    # properly scheduled.
+    #
+    # The rejected handlers will be cleared if the promise is fulfilled and vice-versa.
+    # After rejection, no on_fulfilled handler should ever be called and vice-versa.
+    #
+    # When we go from :unscheduled to :pending, the scheduler, if any, should be
+    # called and cleared. That should *not* happen when going from :unscheduled to
+    # :fulfilled.
+    def call_handlers_for(state)
+      case state
+      when :fulfilled
+        @on_scheduled.each { |h| h.call(*@parents.map(&:returned_value)) }
+        @on_fulfilled.each { |h| h.call(*@parents.map(&:returned_value)) }
+        @on_scheduled = @on_rejected = @on_fulfilled = []
+        @scheduler = @executor = nil
+      when :rejected
+        @on_rejected.each { |h| h.call(*@parents.map(&:returned_value)) }
+        @on_fulfilled = @on_scheduled = @on_rejected = []
+        @scheduler = @executor = nil
+      when :pending
+        # A scheduler can get an exception. If so, treat it as rejection
+        # and the exception as the provided reason.
+        if @scheduler
+          begin
+            @scheduler.call(*@parents.map(&:returned_value))
+          rescue => e
+            @log.error("Error while running scheduler! #{e.full_message}")
+            rejected!(e)
+          end
+          @scheduler = nil
+        end
+        @on_scheduled.each { |h| h.call(*@parents.map(&:returned_value)) }
+        @on_scheduled = []
+      else
+        raise Scarpe::InternalError, "Internal error! Trying to call handlers for #{state.inspect}!"
+      end
+    end
+
+    def parent_fulfilled!(parent)
+      @waiting_on.delete(parent)
+
+      # Last parent? If so, schedule ourselves.
+      if @waiting_on.empty? && !self.complete?
+        # This will result in :pending if there's no executor,
+        # or fulfilled/rejected if there is an executor.
+        set_state(:pending)
+      end
+    end
+
+    def parent_rejected!(parent)
+      @waiting_on = []
+
+      unless self.complete?
+        # If our parent was rejected and we were waiting on them,
+        # now we're rejected too.
+        set_state(:rejected)
+      end
+    end
+
+    def call_executor
+      raise(Scarpe::InternalError, "Internal error! Should not call_executor with no executor!") unless @executor
+
+      begin
+        result = @executor.call(*@parents.map(&:returned_value))
+        fulfilled!(result)
+      rescue => e
+        @log.error("Error running executor! #{e.full_message}")
+        rejected!(e)
+      end
+    ensure
+      @executor = nil
+    end
+
+    public
+
+    # Register a handler to be called when the promise is fulfilled.
+    # If called on a fulfilled promise, the handler will be called immediately.
+    #
+    # @yield Handler to be called on fulfilled
+    # @return [Scarpe::Promise] self
+    def on_fulfilled(&handler)
+      unless handler
+        raise Shoes::Errors::InvalidAttributeValueError, "You must pass a block to on_fulfilled!"
+      end
+
+      case @state
+      when :fulfilled
+        handler.call(*@parents.map(&:returned_value))
+      when :pending, :unscheduled
+        @on_fulfilled << handler
+      when :rejected
+        # Do nothing
+      end
+
+      self
+    end
+
+    # Register a handler to be called when the promise is rejected.
+    # If called on a rejected promise, the handler will be called immediately.
+    #
+    # @yield Handler to be called on rejected
+    # @return [Scarpe::Promise] self
+    def on_rejected(&handler)
+      unless handler
+        raise Shoes::Errors::InvalidAttributeValueError, "You must pass a block to on_rejected!"
+      end
+
+      case @state
+      when :rejected
+        handler.call(*@parents.map(&:returned_value))
+      when :pending, :unscheduled
+        @on_rejected << handler
+      when :fulfilled
+        # Do nothing
+      end
+
+      self
+    end
+
+    # Register a handler to be called when the promise is scheduled.
+    # If called on a promise that was scheduled earlier, the handler
+    # will be called immediately.
+    #
+    # @yield Handler to be called on scheduled
+    # @return [Scarpe::Promise] self
+    def on_scheduled(&handler)
+      unless handler
+        raise Shoes::Errors::InvalidAttributeValueError, "You must pass a block to on_scheduled!"
+      end
+
+      # Add a pending handler or call it now
+      case @state
+      when :fulfilled, :pending
+        handler.call(*@parents.map(&:returned_value))
+      when :unscheduled
+        @on_scheduled << handler
+      when :rejected
+        # Do nothing
+      end
+
+      self
+    end
+  end
+  Components::Promise = Promise
+end

data/lib/scarpe/components/segmented_file_loader.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "scarpe/components/file_helpers"
+
+module Scarpe::Components
+  class SegmentedFileLoader
+    include Scarpe::Components::FileHelpers
+
+    # Add a new segment type (e.g. "catscradle") with a different
+    # file handler.
+    #
+    # @param type [String] the new name for this segment type
+    # @param handler [Object] an object that will be called as obj.call(filename) - often a proc
+    # @return <void>
+    def add_segment_type(type, handler)
+      if segment_type_hash.key?(type)
+        raise Shoes::Errors::InvalidAttributeValueError, "Segment type #{type.inspect} already exists!"
+      end
+
+      segment_type_hash[type] = handler
+    end
+
+    # Return an Array of segment type labels, such as "code" and "app_test".
+    #
+    # @return [Array<String>] the segment type labels
+    def segment_types
+      segment_type_hash.keys
+    end
+
+    # Normally a Shoes application will want to keep the default segment types,
+    # which allow loading a Shoes app and running a test inside. But sometimes
+    # the default handler will be wrong and a library will want to register
+    # its own "shoes" and "app_test" segment handlers, or not have any at all.
+    # For those applications, it makes sense to clear all segment types before
+    # registering its own.
+    #
+    # @return <void>
+    def remove_all_segment_types!
+      @segment_type_hash = {}
+    end
+
+    # Load a .sca file with an optional YAML frontmatter prefix and
+    # multiple file sections which can be treated differently.
+    #
+    # The file loader acts like a proc, being called with .call()
+    # and returning true or false for whether it has handled the
+    # file load. This allows chaining loaders in order and the
+    # first loader to recognise a file will run it.
+    #
+    # @param path [String] the file or directory to treat as a Scarpe app
+    # @return [Boolean] return true if the file is loaded as a segmented Scarpe app file
+    def call(path)
+      return false unless path.end_with?(".scas") || path.end_with?(".sspec")
+
+      file_load(path)
+      true
+    end
+
+    # Segment type handlers can call this to perform an operation after the load
+    # has completed. This is important for ordering, and because loading a Shoes
+    # app often doesn't return. So to have a later section (e.g. tests, additional
+    # data) do something that affects Shoes app loading (e.g. set an env var,
+    # affect the display service) it's important that app loading take place later
+    # in the sequence.
+    def after_load(&block)
+      @after_load ||= []
+      @after_load << block
+    end
+
+    def self.gen_name(segmap)
+      ctr = (1..10_000).detect { |i| !segmap.key?("%5d" % i) }
+      "%5d" % ctr
+    end
+
+    def self.front_matter_and_segments_from_file(contents)
+      require "yaml" # Only load when needed
+      require "English"
+
+      segments = contents.split(/\n-{5,}/)
+      front_matter = {}
+
+      # The very first segment can start with front matter, or with a divider, or with no divider.
+      if segments[0].start_with?("---\n") || segments[0] == "---"
+        # We have YAML front matter at the start. All later segments will have a divider.
+        front_matter = YAML.load segments[0]
+        front_matter ||= {} # If the front matter is just the three dashes it returns nil
+        segments = segments[1..-1]
+      elsif segments[0].start_with?("-----")
+        # We have a divider at the start. Great! We're already well set up for this case.
+      elsif segments.size == 1
+        # No front matter, no divider, a single unnamed segment. No more parsing needed.
+        return [{}, { "" => segments[0] }]
+      else
+        # No front matter, no divider before the first segment, multiple segments.
+        # We'll add an artificial divider to the first segment for uniformity.
+        segments = ["-----\n" + segments[0]] + segments[1..-1]
+      end
+
+      segmap = {}
+      segments.each do |segment|
+        if segment =~ /\A-* +(.*?)\n/
+          # named segment with separator
+          name = ::Regexp.last_match(1)
+
+          raise("Duplicate segment name: #{name.inspect}!") if segmap.key?(name)
+
+          segmap[name] = ::Regexp.last_match.post_match
+        elsif segment =~ /\A-* *\n/
+          # unnamed segment with separator
+          segmap[gen_name(segmap)] = ::Regexp.last_match.post_match
+        else
+          raise Scarpe::InternalError, "Internal error when parsing segments in segmented app file! seg: #{segment.inspect}"
+        end
+      end
+
+      [front_matter, segmap]
+    end
+
+    def file_load(path)
+      contents = File.read(path)
+
+      front_matter, segmap = self.class.front_matter_and_segments_from_file(contents)
+
+      if segmap.empty?
+        raise Scarpe::FileContentError, "Illegal segmented Scarpe file: must have at least one code segment, not just front matter!"
+      end
+
+      if front_matter[:segments]
+        if front_matter[:segments].size != segmap.size
+          raise Scarpe::FileContentError, "Number of front matter :segments must equal number of file segments!"
+        end
+      else
+        if segmap.size > 2
+          raise Scarpe::FileContentError, "Segmented files with more than two segments have to specify what they're for!"
+        end
+
+        # Set to default of shoes code only or shoes code and app test code.
+        front_matter[:segments] = segmap.size == 2 ? ["shoes", "app_test"] : ["shoes"]
+      end
+
+      # Match up front_matter[:segments] with the segments, or use the default of shoes and app_test.
+
+      sth = segment_type_hash
+      sv = segmap.values
+
+      tf_specs = []
+      front_matter[:segments].each.with_index do |seg_type, idx|
+        unless sth.key?(seg_type)
+          raise Scarpe::FileContentError, "Unrecognized segment type #{seg_type.inspect}! No matching segment type available!"
+        end
+
+        tf_specs << ["scarpe_#{seg_type}_segment_contents", sv[idx]]
+      end
+
+      with_tempfiles(tf_specs) do |filenames|
+        filenames.each.with_index do |filename, idx|
+          seg_name = front_matter[:segments][idx]
+          sth[seg_name].call(filename)
+        end
+
+        # Need to call @after_load hooks while tempfiles still exist
+        if @after_load && !@after_load.empty?
+          @after_load.each(&:call)
+          @after_load = []
+        end
+      end
+    end
+
+    # The hash of segment type labels mapped to handlers which will be called.
+    # This could be called by a display service, a test framework or similar
+    # code that wants to define a non-Scarpe-standard file format.
+    #
+    # @return [Hash<String, Object>] the name/handler pairs
+    def segment_type_hash
+      @segment_handlers ||= {
+        "shoes" => proc { |seg_file| after_load { load seg_file } },
+        "app_test" => proc do |seg_file|
+          ENV["SHOES_SPEC_TEST"] = seg_file
+          ENV["SHOES_MINITEST_EXPORT_FILE"] = "sspec.json"
+        end,
+      }
+    end
+  end
+end
+
+# You can add additional segment types to the segmented file loader
+# loader = Scarpe::Components::SegmentedFileLoader.new
+# loader.add_segment_type "capybara", proc { |seg_file| load_file_as_capybara(seg_file) }
+# Shoes.add_file_loader loader

data/lib/scarpe/components/string_helpers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Scarpe; module Components; end; end
+module Scarpe::Components::StringHelpers
+  # Cut down from Rails camelize
+  def self.camelize(string)
+    string = string.sub(/^[a-z\d]*/, &:capitalize)
+    string.gsub(/(?:_|(\/))([a-z\d]*)/) { "#{::Regexp.last_match(1)}#{::Regexp.last_match(2).capitalize}" }
+  end
+end