scarpe 0.2.1 → 0.2.2

data/lib/scarpe/wv/webview_local_display.rb

@@ -1,24 +1,36 @@
 # frozen_string_literal: true
 
 class Scarpe
+  # This is the simplest type of Webview DisplayService. It creates Webview widgets
+  # corresponding to Shoes widgets, manages the Webview and its DOM tree, and
+  # generally keeps the Shoes/Webview connection working.
+  #
   # This is an in-process Webview-based display service, with all the limitations that
   # entails. Slow handlers will crash, ending this display service will end the
   # process, too many or too large evals can crash the process, etc.
-  # Normally the intention is to use a RelayDisplayService to a second
+  # Frequently it's better to use a RelayDisplayService to a second
   # process containing one of these.
-  class WebviewDisplayService < Scarpe::DisplayService
-    include Scarpe::Log
+  class WebviewDisplayService < Shoes::DisplayService
+    include Shoes::Log
 
     class << self
       attr_accessor :instance
     end
 
-    # TODO: re-think the list of top-level singleton objects.
+    # The ControlInterface is used to handle internal events in Webview Scarpe
     attr_reader :control_interface
+
+    # The DocumentRoot is the top widget of the Webview-side widget tree
     attr_reader :doc_root
+
+    # app is the Scarpe::WebviewApp
+    attr_reader :app
+
+    # wrangler is the Scarpe::WebWrangler
     attr_reader :wrangler
 
-    # This is called before any of the various WebviewWidgets are created.
+    # This is called before any of the various WebviewWidgets are created, to be
+    # able to create them and look them up.
     def initialize
       if WebviewDisplayService.instance
         raise "ERROR! This is meant to be a singleton!"
@@ -32,6 +44,13 @@ class Scarpe
       @display_widget_for = {}
     end
 
+    # Create a Webview display widget for a specific Shoes widget, and pair it with
+    # the linkable ID for this Shoes widget.
+    #
+    # @param widget_class_name [String] The class name of the Shoes widget, e.g. Shoes::Button
+    # @param widget_id [String] the linkable ID for widget events
+    # @param properties [Hash] a JSON-serialisable Hash with the widget's display properties
+    # @return [WebviewWidget] the newly-created Webview widget
     def create_display_widget_for(widget_class_name, widget_id, properties)
       if widget_class_name == "App"
         unless @doc_root
@@ -64,6 +83,9 @@ class Scarpe
       display_widget
     end
 
+    # Destroy the display service and the app. Quit the process (eventually.)
+    #
+    # @return [void]
     def destroy
       @app.destroy
       WebviewDisplayService.instance = nil

data/lib/scarpe/wv/webview_relay_display.rb

@@ -3,129 +3,24 @@
 require "socket"
 require "rbconfig"
 
-class Scarpe
-  class AppShutdownError < Scarpe::Error; end
-
-  module WVRelayUtil # Make sure the including class also includes Scarpe::Log
-    def ready_to_read?(timeout = 0.0)
-      r, _, e = IO.select [@from], [], [@from, @to].uniq, timeout
-
-      # On timeout, select returns nil instead of arrays.
-      return if r.nil?
-
-      unless e.empty?
-        raise "#{@i_am}: Got error on connection(s) from IO.select! Dying!"
-      end
-
-      !r.empty?
-    end
-
-    def send_datagram(contents)
-      str_data = JSON.dump contents
-      dgram_str = (str_data.length.to_s + "a" + str_data).encode(Encoding::BINARY)
-      to_write = dgram_str.bytesize
-      written = 0
-
-      until written == to_write
-        count = @to.write(dgram_str.byteslice(written..-1))
-        if count.nil? || count == 0
-          raise "Something was wrong in send_datagram! Write returned #{count.inspect}!"
-        end
-
-        written += count
-      end
-
-      nil
-    end
-
-    def receive_datagram
-      @readbuf ||= String.new.encode(Encoding::BINARY)
-      to_read = nil
-
-      loop do
-        # Have we read a packet length already, sitting in @readbuf?
-        a_idx = @readbuf.index("a")
-        if a_idx
-          to_read = @readbuf[0..a_idx].to_i
-          @readbuf = @readbuf[(a_idx + 1)..-1]
-          break
-        end
-
-        # If not, read more bytes
-        new_bytes = @from.read(10)
-        if new_bytes.nil?
-          # This is perfectly normal, if the connection closed
-          raise AppShutdownError, "Got an unexpected EOF reading datagram! " +
-            "Did the #{@i_am == :child ? "parent" : "child"} process die?"
-        end
-        @readbuf << new_bytes
-      end
-
-      loop do
-        if @readbuf.bytesize >= to_read
-          out = @readbuf.byteslice(0, to_read)
-          @readbuf = @readbuf.byteslice(to_read, -1)
-          return out
-        end
-
-        new_bytes = @from.read(to_read - @readbuf.bytesize)
-        @readbuf << new_bytes
-      end
-    rescue
-      raise AppShutdownError, "Got exception #{$!.class} when receiving datagram... #{$!.inspect}"
-    end
-
-    def respond_to_datagram
-      message = receive_datagram
-      m_data = JSON.parse(message)
-
-      if m_data["type"] == "event"
-        kwargs_hash = {}
-        m_data["kwargs"].each { |k, v| kwargs_hash[k.to_sym] = v }
-        send_shoes_event(
-          *m_data["args"],
-          event_name: m_data["kwargs"]["event_name"],
-          target: m_data["kwargs"]["event_target"],
-          **kwargs_hash,
-        )
-      elsif m_data["type"] == "create"
-        raise "Parent process should never receive :create datagram!" if @i_am == :parent
+require_relative "webview_relay_util"
 
-        @wv_display.create_display_widget_for(m_data["class_name"], m_data["id"], m_data["properties"])
-      elsif m_data["type"] == "destroy"
-        if @i_am == :parent
-          @shutdown = true
-        else
-          @log.info("Shutting down...")
-          exit 0
-        end
-      else
-        @log.error("Unrecognized datagram type:event: #{m_data.inspect}!")
-      end
-    end
-
-    def event_loop_for(t = 1.5)
-      t_start = Time.now
-      delay_time = t
-
-      while Time.now - t_start < delay_time
-        if ready_to_read?(0.1)
-          respond_to_datagram
-        else
-          sleep 0.1
-        end
-      end
-    end
-  end
-
-  # This "display service" actually creates a child process and sends events
-  # back and forth, but creates no widgets of its own.
-  class WVRelayDisplayService < Scarpe::DisplayService
-    include Scarpe::Log
-    include WVRelayUtil # Needs Scarpe::Log
+class Scarpe
+  # This display service creates a child process and sends events
+  # back and forth, but creates no widgets of its own. The child
+  # process will spawn a worker with its own WebviewDisplayService
+  # where the real Webview exists. By splitting the Webview
+  # process from the Shoes widgets, it can be easier to return
+  # control to Webview's event handler promptly. Also, the Ruby
+  # process could run background threads if it wanted, and
+  # otherwise behave like a process ***not*** containing Webview.
+  class WVRelayDisplayService < Shoes::DisplayService
+    include Shoes::Log
+    include WVRelayUtil # Needs Shoes::Log
 
     attr_accessor :shutdown
 
+    # Create a Webview Relay Display Service
     def initialize
       super()
       log_init("WV::RelayDisplayService")
@@ -158,6 +53,7 @@ class Scarpe
       end
     end
 
+    # Run, sending and responding to datagrams continuously.
     def run_event_loop
       until @shutdown
         respond_to_datagram while ready_to_read?
@@ -169,11 +65,14 @@ class Scarpe
       self.destroy
     end
 
+    # This method sends a message to the worker process to create a widget. No actual
+    # widget is created or registered with the display service.
     def create_display_widget_for(widget_class_name, widget_id, properties)
       send_datagram({ type: :create, class_name: widget_class_name, id: widget_id, properties: })
       # Don't need to return anything. It wouldn't be used anyway.
     end
 
+    # Tell the worker process to quit, and set a flag telling the event loop to shut down.
     def destroy
       unless @shutdown
         send_datagram({ type: :destroy })

data/lib/scarpe/wv/webview_relay_util.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "socket"
+
+class Scarpe
+  # An error occurred which would normally be handled by shutting down the app
+  class AppShutdownError < Scarpe::Error; end
+
+  # WVRelayUtil defines the datagram format for the sockets that connect a parent
+  # Shoes application with a child display server.
+  #
+  # The class including this module should also include Shoes::Log so that it can
+  # be used.
+  module WVRelayUtil
+    # Checks whether the internal socket is ready to be read from.
+    # If timeout is greater than 0, this will block for up to that long.
+    #
+    # @param timeout [Float] the longest to wait for more input to read
+    # @return [Boolean] whether the socket has data ready for reading
+    def ready_to_read?(timeout = 0.0)
+      r, _, e = IO.select [@from], [], [@from, @to].uniq, timeout
+
+      # On timeout, select returns nil instead of arrays.
+      return if r.nil?
+
+      unless e.empty?
+        raise "#{@i_am}: Got error on connection(s) from IO.select! Dying!"
+      end
+
+      !r.empty?
+    end
+
+    # Send bytes on the internal socket to the opposite side.
+    #
+    # @param contents [String] data to send
+    # @return [void]
+    def send_datagram(contents)
+      str_data = JSON.dump contents
+      dgram_str = (str_data.length.to_s + "a" + str_data).encode(Encoding::BINARY)
+      to_write = dgram_str.bytesize
+      written = 0
+
+      until written == to_write
+        count = @to.write(dgram_str.byteslice(written..-1))
+        if count.nil? || count == 0
+          raise "Something was wrong in send_datagram! Write returned #{count.inspect}!"
+        end
+
+        written += count
+      end
+
+      nil
+    end
+
+    # Read data from the internal socket. Read until a whole datagram
+    # has been received and then return it.
+    #
+    # @return [String] the received datagram
+    def receive_datagram
+      @readbuf ||= String.new.encode(Encoding::BINARY)
+      to_read = nil
+
+      loop do
+        # Have we read a packet length already, sitting in @readbuf?
+        a_idx = @readbuf.index("a")
+        if a_idx
+          to_read = @readbuf[0..a_idx].to_i
+          @readbuf = @readbuf[(a_idx + 1)..-1]
+          break
+        end
+
+        # If not, read more bytes
+        new_bytes = @from.read(10)
+        if new_bytes.nil?
+          # This is perfectly normal, if the connection closed
+          raise AppShutdownError, "Got an unexpected EOF reading datagram! " +
+            "Did the #{@i_am == :child ? "parent" : "child"} process die?"
+        end
+        @readbuf << new_bytes
+      end
+
+      loop do
+        if @readbuf.bytesize >= to_read
+          out = @readbuf.byteslice(0, to_read)
+          @readbuf = @readbuf.byteslice(to_read, -1)
+          return out
+        end
+
+        new_bytes = @from.read(to_read - @readbuf.bytesize)
+        @readbuf << new_bytes
+      end
+    rescue
+      raise AppShutdownError, "Got exception #{$!.class} when receiving datagram... #{$!.inspect}"
+    end
+
+    # Read a datagram from the internal buffer and then dispatch it to the
+    # appropriate handler.
+    def respond_to_datagram
+      message = receive_datagram
+      m_data = JSON.parse(message)
+
+      if m_data["type"] == "event"
+        kwargs_hash = {}
+        m_data["kwargs"].each { |k, v| kwargs_hash[k.to_sym] = v }
+        send_shoes_event(
+          *m_data["args"],
+          event_name: m_data["kwargs"]["event_name"],
+          target: m_data["kwargs"]["event_target"],
+          **kwargs_hash,
+        )
+      elsif m_data["type"] == "create"
+        raise "Parent process should never receive :create datagram!" if @i_am == :parent
+
+        @wv_display.create_display_widget_for(m_data["class_name"], m_data["id"], m_data["properties"])
+      elsif m_data["type"] == "destroy"
+        if @i_am == :parent
+          @shutdown = true
+        else
+          @log.info("Shutting down...")
+          exit 0
+        end
+      else
+        @log.error("Unrecognized datagram type:event: #{m_data.inspect}!")
+      end
+    end
+
+    # Loop for up to `t` seconds, reading data and waiting.
+    #
+    # @param t [Float] the number of seconds to loop for
+    def event_loop_for(t = 1.5)
+      t_start = Time.now
+      delay_time = t
+
+      while Time.now - t_start < delay_time
+        if ready_to_read?(0.1)
+          respond_to_datagram
+        else
+          sleep 0.1
+        end
+      end
+    end
+  end
+end

data/lib/scarpe/wv/widget.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 class Scarpe
-  class WebviewWidget < DisplayService::Linkable
-    include Scarpe::Log
+  # The WebviewWidget parent class helps connect a Webview widget with
+  # its Shoes equivalent, render itself to the Webview DOM, handle
+  # Javascript events and generally keep things working in Webview.
+  class WebviewWidget < Shoes::Linkable
+    include Shoes::Log
 
     class << self
+      # Return the corresponding Webview class for a particular Shoes class name
       def display_class_for(scarpe_class_name)
-        scarpe_class = Scarpe.const_get(scarpe_class_name)
-        unless scarpe_class.ancestors.include?(Scarpe::DisplayService::Linkable)
-          raise "Scarpe Webview can only get display classes for Scarpe " +
+        scarpe_class = Shoes.const_get(scarpe_class_name)
+        unless scarpe_class.ancestors.include?(Shoes::Linkable)
+          raise "Scarpe Webview can only get display classes for Shoes " +
             "linkable widgets, not #{scarpe_class_name.inspect}!"
         end
 
@@ -21,10 +25,17 @@ class Scarpe
       end
     end
 
+    # The Shoes ID corresponding to the Shoes widget for this Webview widget
     attr_reader :shoes_linkable_id
+
+    # The WebviewWidget parent of this widget
     attr_reader :parent
+
+    # An array of WebviewWidget children (possibly empty) of this widget
     attr_reader :children
 
+    # Set instance variables for the display properties of this widget. Bind Shoes
+    # events for changes of parent widget and changes of property values.
     def initialize(properties)
       log_init("WV::Widget")
 
@@ -64,17 +75,42 @@ class Scarpe
       super(linkable_id: @shoes_linkable_id)
     end
 
-    # This exists to be overridden by children watching for changes
+    # Properties_changed will be called automatically when properties change.
+    # The widget should delete any changes from the Hash that it knows how
+    # to incrementally handle, and pass the rest to super. If any changes
+    # go entirely un-handled, a full redraw will be scheduled.
+    # This exists to be overridden by children watching for changes.
+    #
+    # @param changes [Hash] a Hash of new values for properties that have changed
     def properties_changed(changes)
+      # If a widget does something really nonstandard with its html_id or element, it will
+      # need to override to prevent this from happening. That's easy enough, though.
+      if changes.key?("hidden")
+        hidden = changes.delete("hidden")
+        if hidden
+          html_element.set_style("display", "none")
+        else
+          new_style = style # Get current display CSS property, which may vary by subclass
+          disp = new_style[:display]
+          html_element.set_style("display", disp || "block")
+        end
+      end
+
       needs_update! unless changes.empty?
     end
 
+    # Give this widget a new parent, including managing the appropriate child lists for parent widgets.
     def set_parent(new_parent)
       @parent&.remove_child(self)
       new_parent&.add_child(self)
       @parent = new_parent
     end
 
+    # A shorter inspect text for prettier irb output
+    def inspect
+      "#<#{self.class}:#{self.object_id} @shoes_linkable_id=#{@shoes_linkable_id} @parent=#{@parent.inspect} @children=#{@children.inspect}>"
+    end
+
     protected
 
     # Do not call directly, use set_parent
@@ -122,24 +158,43 @@ class Scarpe
       "#%0.2X%0.2X%0.2X" % [r_int, g_int, b_int]
     end
 
+    # CSS styles
+    def style
+      styles = {}
+      if @hidden
+        styles[:display] = "none"
+      end
+      styles
+    end
+
     public
 
-    # This gets a mini-webview for just this element and its children, if any
+    # This gets a mini-webview for just this element and its children, if any.
+    # It is normally called by the widget itself to do its DOM management.
+    #
+    # @return [Scarpe::WebWrangler::ElementWrangler] a DOM object manager
     def html_element
-      @elt_wrangler ||= WebviewDisplayService.instance.doc_root.get_element_wrangler(html_id)
+      @elt_wrangler ||= Scarpe::WebWrangler::ElementWrangler.new(html_id)
     end
 
     # Return a promise that guarantees all currently-requested changes have completed
+    #
+    # @return [Scarpe::Promise] a promise that will be fulfilled when all pending changes have finished
     def promise_update
       html_element.promise_update
     end
 
+    # Get the object's HTML ID
+    #
+    # @return [String] the HTML ID
     def html_id
       object_id.to_s
     end
 
     # to_html is intended to get the HTML DOM rendering of this object and its children.
     # Calling it should be side-effect-free and NOT update the webview.
+    #
+    # @return [String] the rendered HTML
     def to_html
       @children ||= []
       child_markup = @children.map(&:to_html).join
@@ -150,27 +205,41 @@ class Scarpe
       end
     end
 
-    # This binds a Scarpe JS callback, handled via a single dispatch point in the document root
+    # This binds a Scarpe JS callback, handled via a single dispatch point in the app
+    #
+    # @param event [String] the Scarpe widget event name
+    # @yield the block to call when the event occurs
     def bind(event, &block)
       raise("Widget has no linkable_id! #{inspect}") unless linkable_id
 
-      WebviewDisplayService.instance.doc_root.bind("#{linkable_id}-#{event}", &block)
+      WebviewDisplayService.instance.app.bind("#{linkable_id}-#{event}", &block)
     end
 
     # Removes the element from both the Ruby Widget tree and the HTML DOM.
     # Return a promise for when that HTML change will be visible.
+    #
+    # @return [Scarpe::Promise] a promise that is fulfilled when the HTML change is complete
     def destroy_self
       @parent&.remove_child(self)
       html_element.remove
     end
 
+    # Request a full redraw of all widgets.
+    #
     # It's really hard to do dirty-tracking here because the redraws are fully asynchronous.
     # And so we can't easily cancel one "in flight," and we can't easily pick up the latest
     # changes... And we probably don't want to, because we may be halfway through a batch.
+    #
+    # @return [void]
     def needs_update!
-      WebviewDisplayService.instance.doc_root.request_redraw!
+      WebviewDisplayService.instance.app.request_redraw!
     end
 
+    # Generate JS code to trigger a specific event name on this widget with the supplies arguments.
+    #
+    # @param handler_function_name [String] the event name - @see #bind
+    # @param args [Array] additional arguments that will be passed to the event in the generated JS
+    # @return [String] the generated JS code
     def handler_js_code(handler_function_name, *args)
       raise("Widget has no linkable_id! #{inspect}") unless linkable_id
 

data/lib/scarpe/wv/wv_display_worker.rb

@@ -7,9 +7,12 @@ require "socket"
 SCARPE_DIR = File.join(__dir__, "../..")
 
 $LOAD_PATH.prepend(SCARPE_DIR)
+ENV["SCARPE_DISPLAY_SERVICE"] = "wv_local"
 require "scarpe"
 require "scarpe/wv_local"
 
+require_relative "webview_relay_util"
+
 # This script exists to create a WebviewDisplayService that can be operated remotely over a socket.
 
 if ARGV.length != 1
@@ -17,12 +20,22 @@ if ARGV.length != 1
   exit(-1)
 end
 
-class WebviewContainedService < Scarpe::DisplayService::Linkable
-  include Scarpe::Log
-  include Scarpe::WVRelayUtil # Needs Scarpe::Log
+# This is the implementation of a freestanding Scarpe Webview display server,
+# which connects via sockets and sends events and properties back and forth
+# with a display-less Shoes app. The interface is designed to allow fork-based
+# usage, where a parent process could create a paired sockets and start the
+# child server. It can also be used via TCP sockets or similar, where a single
+# socket is both input and output.
+class Scarpe::Webview::ContainedService < Shoes::Linkable
+  include Shoes::Log
+  include Scarpe::WVRelayUtil # Needs Shoes::Log
 
   attr_reader :log
 
+  # Create a new DisplayService.
+  #
+  # @param from [Socket] a readable socket to get input from the Shoes process
+  # @param to [Socket] a writable socket on which to send output to the Shoes process
   def initialize(from, to)
     super()
     log_init("WV::DisplayWorker")
@@ -60,6 +73,6 @@ end
 
 s = TCPSocket.new("localhost", ARGV[0].to_i)
 
-SERVICE = WebviewContainedService.new(s, s)
+SERVICE = Scarpe::Webview::ContainedService.new(s, s)
 
 SERVICE.log.info("Finished event loop. Exiting!")

data/lib/scarpe/wv.rb

@@ -2,29 +2,56 @@
 
 # Scarpe Webview Display Services
 
+# This file is for everything that should be included by *both* wv_local and wv_relay
+
+require "securerandom"
+require "json"
+
+require "bloops"
+require "scarpe/components/modular_logger"
+require "scarpe/components/promises"
+
+# Module to contain the various Scarpe Webview classes
+module Scarpe::Webview; end
+
+# Set up hierarchical logging using the SCARPE_LOG_CONFIG var for configuration
+log_config = if ENV["SCARPE_LOG_CONFIG"]
+  JSON.load_file(ENV["SCARPE_LOG_CONFIG"])
+else
+  ENV["SCARPE_DEBUG"] ? Shoes::Log::DEFAULT_DEBUG_LOG_CONFIG : Shoes::Log::DEFAULT_LOG_CONFIG
+end
+
+Shoes::Log.instance = Scarpe::Components::ModularLogImpl.new
+Shoes::Log.configure_logger(log_config)
+
+require "scarpe/components/segmented_file_loader"
+loader = Scarpe::Components::SegmentedFileLoader.new
+Shoes.add_file_loader loader
+
 require_relative "wv/web_wrangler"
 require_relative "wv/control_interface"
 
 require_relative "wv/widget"
-require_relative "wv/webview_local_display"
-require_relative "wv/webview_relay_display"
 
 require_relative "wv/dimensions"
 require_relative "wv/html"
 
 require_relative "wv/spacing"
 require_relative "wv/star"
+require_relative "wv/radio"
 require_relative "wv/background"
 require_relative "wv/border"
 
-require_relative "wv/fill"
 require_relative "wv/arc"
+require_relative "wv/font"
 
 require_relative "wv/app"
-require_relative "wv/document_root"
 require_relative "wv/para"
+require_relative "wv/slot"
 require_relative "wv/stack"
 require_relative "wv/flow"
+require_relative "wv/document_root"
+require_relative "wv/subscription_item"
 require_relative "wv/button"
 require_relative "wv/image"
 require_relative "wv/edit_box"
@@ -37,3 +64,5 @@ require_relative "wv/shape"
 require_relative "wv/text_widget"
 require_relative "wv/link"
 require_relative "wv/line"
+require_relative "wv/video"
+require_relative "wv/check"

data/lib/scarpe/wv_local.rb

@@ -3,4 +3,4 @@
 require_relative "wv"
 require_relative "wv/webview_local_display"
 
-Scarpe::DisplayService.set_display_service_class(Scarpe::WebviewDisplayService)
+Shoes::DisplayService.set_display_service_class(Scarpe::WebviewDisplayService)

data/lib/scarpe/wv_relay.rb

@@ -3,4 +3,4 @@
 require_relative "wv"
 require_relative "wv/webview_relay_display"
 
-Scarpe::DisplayService.set_display_service_class(Scarpe::WVRelayDisplayService)
+Shoes::DisplayService.set_display_service_class(Scarpe::WVRelayDisplayService)