lacci 0.3.0 → 0.5.0

data/lib/shoes/app.rb

@@ -4,66 +4,93 @@ class Shoes
   class App < Shoes::Drawable
     include Shoes::Log
 
-    class << self
-      attr_accessor :instance
-    end
-
+    # The Shoes root of the drawable tree
     attr_reader :document_root
 
-    shoes_styles :title, :width, :height, :resizable
+    # The application directory for this app. Often this will be the directory
+    # containing the launched application file.
+    attr_reader :dir
+
+    shoes_styles :title, :width, :height, :resizable, :features
+
+    # This is defined to avoid the linkable-id check in the Shoes-style method_missing def'n
+    attr_reader :features
 
-    CUSTOM_EVENT_LOOP_TYPES = ["displaylib", "return", "wait"]
+    # These are the allowed values for custom_event_loop events.
+    #
+    # * displaylib means the display library is not going to return from running the app
+    # * return means the display library will return and the loop will be handled outside Lacci's control
+    # * wait means Lacci should busy-wait and send eternal heartbeats from the "run" event
+    #
+    # If the display service grabs control and keeps it, Webview-style, that means "displaylib"
+    # should be the value. A Scarpe-Wasm-style "return" is appropriate if the code can finish
+    # without Ruby ending the process at the end of the source file. A "wait" can prevent Ruby
+    # from finishing early, but also prevents multiple applications. Only "return" will normally
+    # allow multiple Shoes applications.
+    CUSTOM_EVENT_LOOP_TYPES = %w[displaylib return wait]
 
+    class << self
+      attr_accessor :set_test_code
+    end
+
+    init_args
     def initialize(
-      title: "Shoes!",
+      title: 'Shoes!',
       width: 480,
       height: 420,
       resizable: true,
+      features: [],
       &app_code_body
     )
-      log_init("Shoes::App")
+      log_init('Shoes::App')
 
-      if Shoes::App.instance
-        @log.error("Trying to create a second Shoes::App in the same process! Fail!")
-        raise Shoes::Errors::TooManyInstancesError, "Cannot create multiple Shoes::App objects!"
+      if Shoes::FEATURES.include?(:multi_app) || Shoes.APPS.empty?
+        Shoes.APPS.push self
       else
-        Shoes::App.instance = self
+        @log.error('Trying to create a second Shoes::App in the same process! Fail!')
+        raise Shoes::Errors::TooManyInstancesError, 'Cannot create multiple Shoes::App objects!'
       end
 
-      @do_shutdown = false
-      @event_loop_type = "displaylib" # the default
+      # We cd to the app's containing dir when running the app
+      @dir = Dir.pwd
 
-      super
+      @do_shutdown = false
+      @event_loop_type = 'displaylib' # the default
 
-      # The draw context tracks current settings like fill and stroke,
-      # plus potentially other current state that changes from drawable
-      # to drawable and slot to slot.
-      @draw_context = {
-        "fill" => "",
-        "stroke" => "",
-        "rotate" => 0,
-      }
+      @features = features
 
-      # This creates the DocumentRoot, including its corresponding display drawable
-      @document_root = Shoes::DocumentRoot.new
+      unknown_ext = features - Shoes::FEATURES - Shoes::EXTENSIONS
+      unsupported_features = unknown_ext & Shoes::KNOWN_FEATURES
+      unless unsupported_features.empty?
+        @log.error("Shoes app requires feature(s) not supported by this display service: #{unsupported_features.inspect}!")
+        raise Shoes::Errors::UnsupportedFeatureError, "Shoes app needs features: #{unsupported_features.inspect}"
+      end
+      unless unknown_ext.empty?
+        @log.warn("Shoes app requested unknown features #{unknown_ext.inspect}! Known: #{(Shoes::FEATURES + Shoes::EXTENSIONS).inspect}")
+      end
 
       @slots = []
 
+      @content_container = nil
+
+      @routes = {}
+
+      super
+
+      # This creates the DocumentRoot, including its corresponding display drawable
+      Drawable.with_current_app(self) do
+        @document_root = Shoes::DocumentRoot.new
+      end
+
       # Now create the App display drawable
       create_display_drawable
 
-      # Set up testing events *after* Display Service basic objects exist
-      if ENV["SCARPE_APP_TEST"]
-        test_code = File.read ENV["SCARPE_APP_TEST"]
-        if test_code != ""
-          @test_obj = Object.new
-          @test_obj.instance_eval test_code
-        end
-      end
+      # Set up testing *after* Display Service basic objects exist
 
-      if ENV["SHOES_SPEC_TEST"]
-        test_code = File.read ENV["SHOES_SPEC_TEST"]
+      if ENV['SHOES_SPEC_TEST'] && !Shoes::App.set_test_code
+        test_code = File.read ENV['SHOES_SPEC_TEST']
         unless test_code.empty?
+          Shoes::App.set_test_code = true
           Shoes::Spec.instance.run_shoes_spec_test_code test_code
         end
       end
@@ -72,30 +99,34 @@ class Shoes
 
       # Try to de-dup as much as possible and not send repeat or multiple
       # destroy events
-      @watch_for_destroy = bind_shoes_event(event_name: "destroy") do
+      @watch_for_destroy = bind_shoes_event(event_name: 'destroy') do
         Shoes::DisplayService.unsub_from_events(@watch_for_destroy) if @watch_for_destroy
         @watch_for_destroy = nil
-        self.destroy(send_event: false)
+        destroy(send_event: false)
       end
 
-      @watch_for_event_loop = bind_shoes_event(event_name: "custom_event_loop") do |loop_type|
-        raise(Shoes::Errors::InvalidAttributeValueError, "Unknown event loop type: #{loop_type.inspect}!") unless CUSTOM_EVENT_LOOP_TYPES.include?(loop_type)
+      @watch_for_event_loop = bind_shoes_event(event_name: 'custom_event_loop') do |loop_type|
+        unless CUSTOM_EVENT_LOOP_TYPES.include?(loop_type)
+          raise(Shoes::Errors::InvalidAttributeValueError,
+                "Unknown event loop type: #{loop_type.inspect}!")
+        end
 
         @event_loop_type = loop_type
       end
 
-      Signal.trap("INT") do
-        @log.warn("App interrupted by signal, stopping...")
+      Signal.trap('INT') do
+        @log.warn('App interrupted by signal, stopping...')
         puts "\nStopping Shoes app..."
         destroy
       end
     end
 
     def init
-      send_shoes_event(event_name: "init")
+      send_shoes_event(event_name: 'init')
       return if @do_shutdown
 
-      ::Shoes::App.instance.with_slot(@document_root, &@app_code_body)
+      with_slot(@document_root, &@app_code_body)
+      render_index_if_defined_on_first_boot
     end
 
     # "Container" drawables like flows, stacks, masks and the document root
@@ -119,7 +150,7 @@ class Shoes
       return unless block_given?
 
       push_slot(slot_item)
-      Shoes::App.instance.instance_eval(&block)
+      instance_eval(&block)
     ensure
       pop_slot
     end
@@ -133,22 +164,19 @@ class Shoes
       return super unless klass
 
       ::Shoes::App.define_method(name) do |*args, **kwargs, &block|
-        # Look up the Shoes drawable and create it...
-        drawable_instance = klass.new(*args, **kwargs, &block)
-
-        unless klass.ancestors.include?(::Shoes::TextDrawable)
-          # Create this drawable in the current app slot
-          drawable_instance.set_parent ::Shoes::App.instance.current_slot
+        Drawable.with_current_app(self) do
+          klass.new(*args, **kwargs, &block)
         end
-
-        drawable_instance
       end
 
       send(name, *args, **kwargs, &block)
     end
 
+    # Get the current draw context for the current slot
+    #
+    # @return [Hash] a hash of Shoes styles for the current draw context
     def current_draw_context
-      @draw_context.dup
+      current_slot&.current_draw_context
     end
 
     # This usually doesn't return. The display service may take control
@@ -157,40 +185,39 @@ class Shoes
     # want to (and/or can't) take control of the event loop.
     def run
       if @do_shutdown
-        $stderr.puts "Destroy has already been signaled, but we just called Shoes::App.run!"
+        warn 'Destroy has already been signaled, but we just called Shoes::App.run!'
         return
       end
 
       # The display lib can send us an event to customise the event loop handling.
       # But it must do so before the "run" event returns.
-      send_shoes_event(event_name: "run")
+      send_shoes_event(event_name: 'run')
 
       case @event_loop_type
-      when "wait"
+      when 'wait'
         # Display lib wants us to busy-wait instead of it.
-        until @do_shutdown
-          Shoes::DisplayService.dispatch_event("heartbeat", nil)
-        end
-      when "displaylib"
+        Shoes::DisplayService.dispatch_event('heartbeat', nil) until @do_shutdown
+      when 'displaylib'
         # If run event returned, that means we're done.
         destroy
-      when "return"
+      when 'return'
         # We can just return to the main event loop. But we shouldn't call destroy.
         # Presumably some event loop *outside* our event loop is handling things.
       else
-        raise Shoes::Errors::InvalidAttributeValueError, "Internal error! Incorrect event loop type: #{@event_loop_type.inspect}!"
+        raise Shoes::Errors::InvalidAttributeValueError,
+              "Internal error! Incorrect event loop type: #{@event_loop_type.inspect}!"
       end
     end
 
     def destroy(send_event: true)
       @do_shutdown = true
-      send_shoes_event(event_name: "destroy") if send_event
+      send_shoes_event(event_name: 'destroy') if send_event
     end
 
     def all_drawables
       out = []
 
-      to_add = @document_root.children
+      to_add = [@document_root, @document_root.children]
       until to_add.empty?
         out.concat(to_add)
         to_add = to_add.flat_map { |w| w.respond_to?(:children) ? w.children : [] }.compact
@@ -199,40 +226,52 @@ class Shoes
       out
     end
 
+    # We can add various ways to find drawables here.
+    # These are sort of like Shoes selectors, used for testing.
+    # This method finds a drawable across all active Shoes apps.
+    def self.find_drawables_by(*specs)
+      Shoes.APPS.flat_map do |app|
+        app.find_drawables_by(*specs)
+      end
+    end
+
     # We can add various ways to find drawables here.
     # These are sort of like Shoes selectors, used for testing.
     def find_drawables_by(*specs)
       drawables = all_drawables
       specs.each do |spec|
         if spec == Shoes::App
-          drawables = [Shoes::App.instance]
+          drawables = [@app]
         elsif spec.is_a?(Class)
           drawables.select! { |w| spec === w }
         elsif spec.is_a?(Symbol) || spec.is_a?(String)
           s = spec.to_s
           case s[0]
-          when "$"
+          when '$'
             begin
               # I'm not finding a global_variable_get or similar...
               global_value = eval s
               drawables &= [global_value]
             rescue
-              raise Shoes::Errors::InvalidAttributeValueError, "Error getting global variable: #{spec.inspect}"
+              # raise Shoes::Errors::InvalidAttributeValueError, "Error getting global variable: #{spec.inspect}"
+              drawables = []
             end
-          when "@"
-            if Shoes::App.instance.instance_variables.include?(spec.to_sym)
-              drawables &= [self.instance_variable_get(spec)]
+          when '@'
+            if @app.instance_variables.include?(spec.to_sym)
+              drawables &= [@app.instance_variable_get(spec)]
             else
-              raise Shoes::Errors::InvalidAttributeValueError, "Can't find top-level instance variable: #{spec.inspect}!"
+              # raise Shoes::Errors::InvalidAttributeValueError, "Can't find top-level instance variable: #{spec.inspect}!"
+              drawables = []
             end
           else
-            if s.start_with?("id:")
-              find_id = Integer(s[3..-1])
-              drawable = Shoes::Drawable.drawable_by_id(find_id)
-              drawables &= [drawable]
-            else
+            unless s.start_with?('id:')
               raise Shoes::Errors::InvalidAttributeValueError, "Don't know how to find drawables by #{spec.inspect}!"
             end
+
+            find_id = Integer(s[3..-1])
+            drawable = Shoes::Drawable.drawable_by_id(find_id)
+            drawables &= [drawable]
+
           end
         else
           raise(Shoes::Errors::InvalidAttributeValueError, "Don't know how to find drawables by #{spec.inspect}!")
@@ -240,11 +279,67 @@ class Shoes
       end
       drawables
     end
+
+    def page(name, &block)
+      @pages ||= {}
+      @pages[name] = proc do
+        stack(width: 1.0, height: 1.0) do
+          instance_eval(&block)
+        end
+      end
+    end
+
+    def visit(name_or_path)
+      # First, check for exact page match (symbol)
+      if @pages && @pages[name_or_path]
+        @document_root.clear do
+          instance_eval(&@pages[name_or_path])
+        end
+        return
+      end
+
+      # Second, check URL routes
+      route, method_name = @routes.find { |r, _| r === name_or_path }
+      if route
+        @document_root.clear do
+          if route.is_a?(Regexp)
+            match_data = route.match(name_or_path)
+            send(method_name, *match_data.captures)
+          else
+            send(method_name)
+          end
+        end
+        return
+      end
+
+      # Third, if it's a string path like "/page2", try matching page :page2
+      if name_or_path.is_a?(String) && name_or_path.start_with?("/")
+        page_name = name_or_path[1..-1].to_sym  # "/page2" -> :page2
+        if @pages && @pages[page_name]
+          @document_root.clear do
+            instance_eval(&@pages[page_name])
+          end
+          return
+        end
+      end
+
+      puts "Error: URL '#{name_or_path}' not found"
+    end
+
+    def url(path, method_name)
+      if path.is_a?(String) && path.include?('(')
+        # Convert string patterns to regex
+        regex = Regexp.new("^#{path.gsub(/\(.*?\)/, '(.*?)')}$")
+        @routes[regex] = method_name
+      else
+        @routes[path] = method_name
+      end
+    end
   end
 end
 
 # Event handler DSLs get defined in both App and Slot - same code, slightly different results
-events = [:motion, :hover, :leave, :click, :release, :keypress, :animate, :every, :timer]
+events = %i[motion hover leave click release keypress animate every timer]
 events.each do |event|
   Shoes::App.define_method(event) do |*args, &block|
     subscription_item(args:, shoes_api_name: event.to_s, &block)
@@ -256,54 +351,58 @@ end
 
 # These methods will need to be defined on Slots too, but probably need a rework in general.
 class Shoes::App < Shoes::Drawable
+  # This is going to go away. See issue #496
   def background(...)
     current_slot.background(...)
   end
 
+  # This is going to go away. See issue #498
   def border(...)
     current_slot.border(...)
   end
 
-  # Draw context methods
-
-  def fill(color)
-    @draw_context["fill"] = color
-  end
-
-  def nofill
-    @draw_context["fill"] = ""
-  end
-
-  def stroke(color)
-    @draw_context["stroke"] = color
-  end
-
-  def nostroke
-    @draw_context["stroke"] = ""
+  # Draw Context methods -- forward to the current slot
+  %i[fill nofill stroke strokewidth nostroke rotate].each do |dc_method|
+    define_method(dc_method) do |*args|
+      current_slot.send(dc_method, *args)
+    end
   end
 
   # Shape DSL methods
 
   def move_to(x, y)
-    raise(Shoes::Errors::InvalidAttributeValueError, "Pass only Numeric arguments to move_to!") unless x.is_a?(Numeric) && y.is_a?(Numeric)
-
-    if current_slot.is_a?(::Shoes::Shape)
-      current_slot.add_shape_command(["move_to", x, y])
+    unless x.is_a?(Numeric) && y.is_a?(Numeric)
+      raise(Shoes::Errors::InvalidAttributeValueError,
+            'Pass only Numeric arguments to move_to!')
     end
+
+    return unless current_slot.is_a?(::Shoes::Shape)
+
+    current_slot.add_shape_command(['move_to', x, y])
   end
 
   def line_to(x, y)
-    raise(Shoes::Errors::InvalidAttributeValueError, "Pass only Numeric arguments to line_to!") unless x.is_a?(Numeric) && y.is_a?(Numeric)
-
-    if current_slot.is_a?(::Shoes::Shape)
-      current_slot.add_shape_command(["line_to", x, y])
+    unless x.is_a?(Numeric) && y.is_a?(Numeric)
+      raise(Shoes::Errors::InvalidAttributeValueError,
+            'Pass only Numeric arguments to line_to!')
     end
-  end
 
-  def rotate(angle)
-    @draw_context["rotate"] = angle
+    return unless current_slot.is_a?(::Shoes::Shape)
+
+    current_slot.add_shape_command(['line_to', x, y])
   end
+
   # Not implemented yet: curve_to, arc_to
 
-  alias_method :info, :puts
+  alias info puts
+
+  private
+
+  def render_index_if_defined_on_first_boot
+    return if @first_boot_finished
+
+    visit('/') if @routes['/'] == :index
+
+    @first_boot_finished = true
+  end
 end

data/lib/shoes/constants.rb

@@ -13,10 +13,10 @@ class Shoes
         [ENV["LOCALAPPDATA"], "Shoes"],
         [ENV["APPDATA"], "Shoes"],
         [ENV["HOME"], ".shoes"],
-        [Dir.tmpdir, "shoes"],
       ]
 
       top, file = homes.detect { |home_top, _| home_top && File.exist?(home_top) }
+      return nil if top.nil?
       File.join(top, file)
     end
 
@@ -32,8 +32,30 @@ class Shoes
     HALF_PI = 1.57079632679489661923
     PI = 3.14159265358979323846
 
-    # This should be set up by the Display Service when it loads
+    # These should be set up by the Display Service when it loads. They are intentionally
+    # *not* frozen so that the Display Service can add to them (and then optionally
+    # freeze them.)
+
+    # Fonts currently loaded and available
     FONTS = []
+
+    # Standard features available in this display service - see KNOWN_FEATURES.
+    # These may or may not require the Shoes.app requesting them per-app.
+    FEATURES = []
+
+    # Nonstandard extensions, e.g. Scarpe extensions, supported by this display lib.
+    # An application may have to request the extensions for them to be available so
+    # that a casual reader can see Shoes.app(features: :scarpe) and realize why
+    # there are nonstandard styles or drawables.
+    EXTENSIONS = []
+
+    # These are all known features supported by this version of Lacci.
+    # Features on this list are allowed to be in FEATURES. Anything else
+    # goes in EXTENSIONS and is nonstandard.
+    KNOWN_FEATURES = [
+      :html, # Supports .to_html on display objects, HTML classes on drawables, etc.
+      :multi_app, # Supports multiple applications at once
+    ].freeze
   end
 
   # Access and assign the release constants

data/lib/shoes/display_service.rb

@@ -32,7 +32,14 @@ class Shoes
       # This is in the eigenclass/metaclass, *not* instances of DisplayService
       include Shoes::Log
 
+      # Send a Shoes event to all subscribers.
       # An event_target may be nil, to indicate there is no target.
+      #
+      # @param event_name [String] the name of the event
+      # @param event_target [String] the specific target, if any
+      # @param args [Array] arguments to pass to the subscribing block
+      # @param args [Array] keyword arguments to pass to the subscribing block
+      # @return [void]
       def dispatch_event(event_name, event_target, *args, **kwargs)
         @@display_event_handlers ||= {}
 
@@ -69,10 +76,20 @@ class Shoes
         kwargs[:event_name] = event_name
         kwargs[:event_target] = event_target if event_target
         handlers.each { |h| h[:handler].call(*args, **kwargs) }
+        nil
       end
 
-      # It's permitted to subscribe to event_name :any for all event names, and event_target :any for all targets.
-      # An event_target of nil means "no target", and only matches events dispatched with a nil target.
+      # Subscribe to the given event name and target.
+      # It's permitted to subscribe to event_name :any for all event names,
+      # and event_target :any for all targets. An event_target of nil means
+      # "no target", and only matches events dispatched with a nil target.
+      # The subscription will return an unsubscribe ID, which can be used
+      # later to unsubscribe from the notification.
+      #
+      # @param event_name [String,Symbol] the event name to subscribe to, or :any for all event names
+      # @param event_target [String,Symbol,NilClass] the event target to subscribe to, or :any for all targets - nil is a valid target
+      # @block the block to call when the event occurs - it will receive arguments from the event-dispatch call
+      # @return [Integer] an unsubscription ID which can be used later to cancel the subscription
       def subscribe_to_event(event_name, event_target, &handler)
         @@display_event_handlers ||= {}
         @@display_event_unsub_id ||= 0
@@ -96,6 +113,10 @@ class Shoes
         id
       end
 
+      # Unsubscribe from any event subscriptions matching the unsub ID.
+      #
+      # @param unsub_id [Integer] the unsub ID returned when subscribing
+      # @return [void]
       def unsub_from_events(unsub_id)
         raise "Must provide an unsubscribe ID!" if unsub_id.nil?
 
@@ -106,17 +127,32 @@ class Shoes
         end
       end
 
+      # Reset the display service, for instance between unit tests.
+      # This destroys all existing subscriptions.
+      #
+      # @return [void]
       def full_reset!
         @@display_event_handlers = {}
         @json_debug_serialize = nil
       end
 
+      # Set the Display Service class which will handle display service functions
+      # for this process. This can only be set once. The display service can be
+      # a subclass of Shoes::DisplayService, but isn't required to be.
+      #
+      # Shoes will create an instance of this class with no arguments passed to
+      # initialize, and use it as the display service for the lifetime of the
+      # process.
+      #
+      # @param klass [Class] the class for the display service
       def set_display_service_class(klass)
         raise "Can only set a single display service class!" if @display_service_klass
 
         @display_service_klass = klass
       end
 
+      # Get the current display service instance. This requires a display service
+      # class having been set first. @see set_display_service_class
       def display_service
         return @service if @service
 
@@ -126,9 +162,13 @@ class Shoes
       end
     end
 
+    def initialize
+      @display_drawable_for = {}
+    end
+
     # These methods are an interface to DisplayService objects.
 
-    def create_display_drawable_for(drawable_class_name, drawable_id, properties, is_widget:)
+    def create_display_drawable_for(drawable_class_name, drawable_id, properties, parent_id:, is_widget:)
       raise "Override in DisplayService implementation!"
     end
 
@@ -174,7 +214,6 @@ class Shoes
     def initialize(linkable_id: object_id)
       @linkable_id = linkable_id
       @subscriptions = {}
-      @display_drawable_for ||= {}
     end
 
     def send_self_event(*args, event_name:, **kwargs)