scarpe-components 0.1.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2033509feb830b1bc7fa18f1275c7e1735e7ef7212808d0c4e3618873016b23
-  data.tar.gz: 1c8f7bf639f4e4b00f578263ea9be8a2be4b1773aa002457f50866e89159ad73
+  metadata.gz: b7067a7b6f0e71d041289334dccf5c0edaae3db689a710450c1d8f585888f74d
+  data.tar.gz: c73105b84ae8468779ca93c216e7f618213a79086e2c0d7a7470bdece885c2b9
 SHA512:
-  metadata.gz: 7afb7e7b1e63029d673d3274f0c7b5cbe00871d2af4178863d2211f375eb222b65572adae625252da985b341c5df7e2c671df4c184b3f05fde2484a567199a72
-  data.tar.gz: 6b4b76d33119f9a1688d6614e06c07ac63fca5a9741f4a627ced93ed10bf5ff22e8d110a844f6a7a9c6badbcc88d80e709eb9cc5c51534997ff18dccee308825
+  metadata.gz: 8d0be001e64c94d3e82dcfc7dca65cbfe373edfd219905716075cfcb3655b0da9a9fec76cf2323cec7d151b83581b3762d7b7c81d51ba2b34dcc10451b33c4db
+  data.tar.gz: 78a734af216bf4c7275483258d20508a985782442a1b6700632905d26b6dfccf0a66ca3c752202b41f32893094450681fdfae7e0d832ee08ba43812b300b8427

data/Gemfile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "lacci", path: "../lacci"
+
+gem "rake", "~> 13.0"
+
+gem "nokogiri"
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "minitest-reporters"
+end
+
+group :development do
+  gem "debug"
+  gem "rubocop", "~> 1.21"
+  gem "rubocop-shopify"
+end

data/lib/scarpe/components/base64.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "base64"
+require "uri"
+
+class Scarpe; end
+module Scarpe::Components; end
+class Scarpe
+  module Components::Base64
+    def valid_url?(string)
+      uri = URI.parse(string)
+      uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+    rescue URI::InvalidURIError, URI::BadURIError
+      false
+    end
+
+    def encode_file_to_base64(image_filename)
+      directory_path = File.dirname(__FILE__, 5)
+
+      image_path = File.join(directory_path, image_filename)
+
+      image_data = File.binread(image_path)
+
+      encoded_data = ::Base64.strict_encode64(image_data)
+
+      encoded_data
+    end
+  end
+end

data/lib/scarpe/components/file_helpers.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+# These can be used for unit tests, but also more generally.
+
+module Scarpe::Components::FileHelpers
+  # Create a temporary file with the given prefix and contents.
+  # Execute the block of code with it in place. Make sure
+  # it gets cleaned up afterward.
+  #
+  # @param prefix [String] the prefix passed to Tempfile to identify this file on disk
+  # @param contents [String] the file contents that should be written to Tempfile
+  # @param dir [String] the directory to create the tempfile in
+  # @yield The code to execute with the tempfile present
+  # @yieldparam the path of the new tempfile
+  def with_tempfile(prefix, contents, dir: Dir.tmpdir)
+    t = Tempfile.new(prefix, dir)
+    t.write(contents)
+    t.flush # Make sure the contents are written out
+
+    yield(t.path)
+  ensure
+    t.close
+    t.unlink
+  end
+
+  # Create multiple tempfiles, with given contents, in given
+  # directories, and execute the block in that context.
+  # When the block is finished, make sure all tempfiles are
+  # deleted.
+  #
+  # Pass an array of arrays, where each array is of the form:
+  # [prefix, contents, (optional)dir]
+  #
+  # I don't love inlining with_tempfile's contents into here.
+  # But calling it iteratively or recursively was difficult
+  # when I tried it the obvious ways.
+  #
+  # This method should be equivalent to calling with_tempfile
+  # once for each entry in the array, in a set of nested
+  # blocks.
+  #
+  # @param tf_specs [Array<Array>] The array of tempfile prefixes, contents and directories
+  # @yield The code to execute with those tempfiles present
+  # @yieldparam An array of paths to tempfiles, in the same order as tf_specs
+  def with_tempfiles(tf_specs, &block)
+    tempfiles = []
+    tf_specs.each do |prefix, contents, dir|
+      dir ||= Dir.tmpdir
+      t = Tempfile.new(prefix, dir)
+      tempfiles << t
+      t.write(contents)
+      t.flush # Make sure the contents are written out
+    end
+
+    args = tempfiles.map(&:path)
+    yield(args)
+  ensure
+    tempfiles.each do |t|
+      t.close
+      t.unlink
+    end
+  end
+end

data/lib/scarpe/{logger.rb → components/modular_logger.rb}

@@ -5,10 +5,12 @@ require "json"
 
 require "shoes/log"
 
-# Requirements: logging gem
+# Requires the logging gem
 
+class Scarpe; end
+module Scarpe::Components; end
 class Scarpe
-  class LogImpl
+  class Components::ModularLogImpl
     include Shoes::Log # for constants
 
     def logger_for_component(component)
@@ -106,3 +108,6 @@ class Scarpe
     end
   end
 end
+
+#Shoes::Log.instance = Scarpe::Components::ModularLogImpl.new
+#Shoes::Log.configure_logger(Shoes::Log::DEFAULT_LOG_CONFIG)

data/lib/scarpe/components/print_logger.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "shoes/log"
+require "json"
+
+class Scarpe; end
+module Scarpe::Components; end
+class Scarpe::Components::PrintLogImpl
+  include Shoes::Log # for constants
+
+  class PrintLogger
+    def initialize(component_name)
+      @comp_name = component_name
+    end
+
+    def error(msg)
+      puts "#{@comp_name} error: #{msg}"
+    end
+
+    def warn(msg)
+      puts "#{@comp_name} warn: #{msg}"
+    end
+
+    def debug(msg)
+      puts "#{@comp_name} debug: #{msg}"
+    end
+
+    def info(msg)
+      puts "#{@comp_name} info: #{msg}"
+    end
+  end
+
+  def logger_for_component(component)
+    PrintLogger.new(component.to_s)
+  end
+
+  def configure_logger(log_config)
+    # For now, ignore
+  end
+end
+
+#Shoes::Log.instance = Scarpe::PrintLogImpl.new
+#Shoes::Log.configure_logger(Shoes::Log::DEFAULT_LOG_CONFIG)

data/lib/scarpe/components/promises.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+class Scarpe; end
+module Scarpe::Components; end
+class 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 "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 "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 "Internal Promise error! Internal state was #{old_state.inspect}! Legal states: #{PROMISE_STATES.inspect}"
+      end
+
+      unless PROMISE_STATES.include?(new_state)
+        raise "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 "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 "Internal Promise error! Trying to change state from #{old_state.inspect} to #{new_state.inspect}!"
+      end
+
+      if old_state == :pending && new_state == :unscheduled
+        raise "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 "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("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 "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 "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 "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,170 @@
+# 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 "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
+
+    # 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")
+
+      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
+
+    private
+
+    def gen_name(segmap)
+      ctr = (1..10_000).detect { |i| !segmap.key?("%5d" % i) }
+      "%5d" % ctr
+    end
+
+    def tokenize_segments(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
+          segmap[::Regexp.last_match(1)] = ::Regexp.last_match.post_match
+        elsif segment =~ /\A-* *\n/
+          # unnamed segment with separator
+          segmap[gen_name(segmap)] = ::Regexp.last_match.post_match
+        else
+          raise "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 = tokenize_segments(contents)
+
+      if segmap.empty?
+        raise "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 "Number of front matter :segments must equal number of file segments!"
+        end
+      else
+        if segmap.size > 2
+          raise "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 "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)
+        end
+      end
+    end
+
+    # The hash of segment type labels mapped to handlers which will be called.
+    # Normal client code shouldn't ever call this.
+    #
+    # @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 { |seg_file| ENV["SCARPE_APP_TEST"] = seg_file },
+      }
+    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/unit_test_helpers.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "json"
+require "fileutils"
+
+require "scarpe/components/file_helpers"
+
+module Scarpe::Test; end
+
+# We want test failures set up once *total*, not per Minitest::Test. So an instance var
+# doesn't do it.
+ALREADY_SET_UP_LOGGED_TEST_FAILURES = { setup: false }
+
+# General helpers for general usage.
+# Helpers here should *not* use Webview-specific functionality.
+# The intention is that these are helpers for various Scarpe display
+# services that do *not* necessarily use Webview.
+
+module Scarpe::Test::Helpers
+  # Very useful for tests
+  include Scarpe::Components::FileHelpers
+
+  # Temporarily set env vars for the block of code inside. The old environment
+  # variable values will be restored after the block finishes.
+  #
+  # @param envs [Hash<String,String>] A hash of environment variable names and values
+  def with_env_vars(envs)
+    old_env = {}
+    envs.each do |k, v|
+      old_env[k] = ENV[k]
+      ENV[k] = v
+    end
+    yield
+  ensure
+    old_env.each { |k, v| ENV[k] = v }
+  end
+end
+
+# This test will save extensive logs in case of test failure.
+# Note that it defines setup/teardown methods. If you want
+# multiple setup/teardowns from multiple places to happen you
+# may need to explictly call (e.g. with logged_test_setup/teardown)
+# to ensure everything you want happens.
+module Scarpe::Test::LoggedTest
+  def self.included(includer)
+    class << includer
+      attr_accessor :logger_dir
+    end
+  end
+
+  def file_id
+    "#{self.class.name}_#{self.name}"
+  end
+
+  # This should be called by the test during setup to make sure that
+  # failure logs will be saved if this test fails. It makes sure the
+  # log config will save all logs from all sources, but keeps a copy
+  # of the old log config to restore after the test is finished.
+  #
+  # @return [void]
+  def logged_test_setup
+    # Make sure test failures will be saved at the end of the run.
+    # Delete stale test failures and logging only the *first* time this is called.
+    set_up_test_failures
+
+    @normal_log_config = Shoes::Log.current_log_config
+    Shoes::Log.configure_logger(log_config_for_test)
+
+    Shoes::Log.logger("LoggedScarpeTest").info("Test: #{self.class.name}##{self.name}")
+  end
+
+  # If you include this module and don't override setup/teardown, everything will
+  # work fine. But if you need more setup/teardown steps, you can do that too.
+  #
+  # The setup method guarantees that just including this module will do setup
+  # automatically. If you override it, be sure to call `super` or `logged_test_setup`.
+  #
+  # @return [void]
+  def setup
+    logged_test_setup
+  end
+
+  # After the test has finished, this will restore the old log configuration.
+  # It will also save the logfiles, but only if the test failed, not if it
+  # succeeded or was skipped.
+  #
+  # @return [void]
+  def logged_test_teardown
+    # Restore previous log config
+    Shoes::Log.configure_logger(@normal_log_config)
+
+    if self.failure
+      save_failure_logs
+    else
+      remove_unsaved_logs
+    end
+  end
+
+  # Make sure that, by default, #logged_test_teardown will be called for teardown.
+  # If a class overrides teardown, it should also call `super` or `logged_test_teardown`
+  # to make sure this still happens.
+  #
+  # @return [void]
+  def teardown
+    logged_test_teardown
+  end
+
+  # Set additional LoggedTest configuration for specific logs to separate or save.
+  # This is normally going to be display-service-specific log components.
+  # Note that this only really works with the modular logger or another logger
+  # that does something useful with the log config. The simple print logger
+  # doesn't do a lot with it.
+  def extra_log_config=(additional_log_config)
+    @additional_log_config = additional_log_config
+  end
+
+  # This is the log config that LoggedTests use. It makes sure all components keep all
+  # logs, but also splits the logs into several different files for later ease of scanning.
+  #
+  # TODO: this shouldn't directly include any Webview entries like WebviewAPI or
+  #     CatsCradle. Those should be overridden in Webview.
+  #
+  # @return [Hash] the log config
+  def log_config_for_test
+    {
+      "default" => ["debug", "logger/test_failure_#{file_id}.log"],
+      "DisplayService" => ["debug", "logger/test_failure_events_#{file_id}.log"],
+    }.merge(@additional_log_config || {})
+  end
+
+  # The list of logfiles that should be saved. Normally this is called internally by the
+  # class, not externally from elsewhere.
+  #
+  # This could be a lot simpler except I want to only update the file list in one place,
+  # log_config_for_test(). Having a single spot should (I hope) make it a lot friendlier to
+  # add more logfiles for different components, logged API objects, etc.
+  def saved_log_files
+    lc = log_config_for_test
+    log_outfiles = lc.values.map { |_level, loc| loc }
+    log_outfiles.select { |s| s.start_with?("logger/") }.map { |s| s.delete_prefix("logger/") }
+  end
+
+  # Make sure that test failure logs will be noticed, and a message will be printed,
+  # if any logged tests fail. This needs to be called at least once in any Minitest-enabled
+  # process using logged tests.
+  #
+  # @return [void]
+  def set_up_test_failures
+    return if ALREADY_SET_UP_LOGGED_TEST_FAILURES[:setup]
+
+    log_dir = self.class.logger_dir
+    raise("Must set logger directory!") unless log_dir
+    raise("Can't find logger directory!") unless File.directory?(log_dir)
+
+    ALREADY_SET_UP_LOGGED_TEST_FAILURES[:setup] = true
+    # Delete stale test failures, if any, before starting the first failure-logged test
+    Dir["#{log_dir}/test_failure*.log"].each { |fn| File.unlink(fn) }
+
+    Minitest.after_run do
+      # Print test failure notice to console
+      unless Dir["#{log_dir}/test_failure*.out.log"].empty?
+        puts "Some tests have failed! See #{log_dir}/test_failure*.out.log for test logs!"
+      end
+
+      # Remove un-saved test logs
+      Dir["#{log_dir}/test_failure*.log"].each do |f|
+        next if f.include?(".out.log")
+
+        File.unlink(f) if File.exist?(f)
+      end
+    end
+  end
+
+  # Failure log output location for a given file path. This is normally used internally to this
+  # class, not externally.
+  #
+  # @return [String] the output path
+  def logfail_out_loc(filepath)
+    # Add a .out prefix before final .log
+    out_loc = filepath.gsub(%r{.log\Z}, ".out.log")
+
+    if out_loc == filepath
+      raise "Something is wrong! Could not figure out failure-log output path for #{filepath.inspect}!"
+    end
+
+    if File.exist?(out_loc)
+      raise "Duplicate test file #{out_loc.inspect}? This file should *not* already exist!"
+    end
+
+    out_loc
+  end
+
+  # Save the failure logs in the appropriate place(s). This is normally used internally, not externally.
+  #
+  # @return [void]
+  def save_failure_logs
+    saved_log_files.each do |log_file|
+      full_loc = File.expand_path("#{self.class.logger_dir}/#{log_file}")
+      # TODO: we'd like to skip 0-length logfiles. But also Logging doesn't flush. For now, ignore.
+      next unless File.exist?(full_loc)
+
+      FileUtils.mv full_loc, logfail_out_loc(full_loc)
+    end
+  end
+
+  # Remove unsaved failure logs. This is normally used internally, not externally.
+  #
+  # @return [void]
+  def remove_unsaved_logs
+    Dir["#{self.class.logger_dir}/test_failure*.log"].each do |f|
+      next if f.include?(".out.log") # Don't delete saved logs
+
+      File.unlink(f)
+    end
+  end
+end

data/lib/scarpe/components/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Scarpe
+  module Components
+    VERSION = "0.2.2"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scarpe-components
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Marco Concetto Rudilosso
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-08 00:00:00.000000000 Z
+date: 2023-08-29 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -19,9 +19,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- Gemfile
 - README.md
 - Rakefile
-- lib/scarpe/logger.rb
+- lib/scarpe/components/base64.rb
+- lib/scarpe/components/file_helpers.rb
+- lib/scarpe/components/modular_logger.rb
+- lib/scarpe/components/print_logger.rb
+- lib/scarpe/components/promises.rb
+- lib/scarpe/components/segmented_file_loader.rb
+- lib/scarpe/components/unit_test_helpers.rb
+- lib/scarpe/components/version.rb
 homepage: https://github.com/scarpe-team/scarpe
 licenses:
 - MIT
@@ -44,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Reusable components for Scarpe display libraries