scarpe 0.2.1 → 0.2.2

data/lacci/lacci.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/lacci/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "lacci"
+  spec.version = Lacci::VERSION
+  spec.authors = ["Marco Concetto Rudilosso", "Noah Gibbs"]
+  spec.email = ["marcoc.r@outlook.com", "the.codefolio.guy@gmail.com"]
+
+  spec.summary = "Lacci - a portable Shoes DSL with switchable display backends, part of Scarpe"
+  spec.homepage = "https://github.com/scarpe-team/scarpe"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/scarpe-team/scarpe"
+  spec.metadata["changelog_uri"] = "https://github.com/scarpe-team/scarpe/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  #spec.add_dependency ""
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lacci/lib/lacci/scarpe_cli.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class Scarpe
+  module CLI
+    DEFAULT_USAGE = <<~'USAGE'
+      Usage: scarpe_core [OPTIONS] <scarpe app file>           # Same as "scarpe run"
+             scarpe_core [OPTIONS] run <scarpe app file>
+             scarpe_core [OPTIONS] env                         # print Scarpe environment settings
+             scarpe_core -v                                    # print the Scarpe gem version and exit
+        Options:
+            --dev                          Use development local scarpe, not an installed gem
+            --debug                        Turn on application debug mode
+    USAGE
+
+    def version_check
+      if RUBY_VERSION[0..2] < "3.2"
+        raise "Scarpe and Lacci require Ruby 3.2 or higher!"
+      end
+    end
+
+    def env_or_default(env_var, default_val)
+      [env_var, ENV[env_var] ? ENV[env_var].inspect : default_val]
+    end
+
+    def default_env_categories
+      {
+        "Lacci" => [
+          env_or_default("SCARPE_DISPLAY_SERVICE", "(none)"),
+          env_or_default("SCARPE_LOG_CONFIG", "(default)#{Shoes::Log::DEFAULT_LOG_CONFIG.inspect}"),
+          env_or_default("SCARPE_APP_TEST", "(none)"),
+        ],
+        "Ruby and Shell" => [
+          ["RUBY_DESCRIPTION", RUBY_DESCRIPTION],
+          ["RUBY_PLATFORM", RUBY_PLATFORM],
+          ["RUBY_ENGINE", RUBY_ENGINE],
+          env_or_default("SHELL", "(none)"),
+          env_or_default("PATH", "(none)"),
+          env_or_default("LD_LIBRARY_PATH", "(none)"),
+          env_or_default("DYLD_LIBRARY_PATH", "(none)"),
+          env_or_default("GEM_ROOT", "(none)"),
+          env_or_default("GEM_HOME", "(none)"),
+          env_or_default("GEM_PATH", "(none)"),
+        ],
+      }
+    end
+
+    def env_categories
+      @env_categories ||= default_env_categories
+      @env_categories
+    end
+
+    def add_env_categories(categories)
+      unless categories.is_a?(Hash)
+        raise("Please supply a hash with categories names as keys and an array of two-elt arrays as values!")
+      end
+
+      # Try to get categories into the *start* of the hash, insertion-order-wise
+      @env_categories = categories.merge(env_categories)
+    end
+
+    def print_env
+      env_categories.each do |category, entries|
+        puts "#{category} environment:"
+        entries.each do |name, val|
+          puts "  #{name}: #{val}"
+        end
+      end
+    end
+  end
+end

data/lacci/lib/lacci/scarpe_core.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Lacci is one place we put components that have no hard gem requirements.
+# It needs to connect to Scarpe, mostly via the Shoes DisplayService.
+# Some display services, like Wasm, cannot install or otherwise tolerate
+# Scarpe's need for a variety of gems, especially those with native extensions.
+# So we need a simple require-able Scarpe core here in Lacci that can be
+# required from display services that cannot link with the base Scarpe gem.
+
+if RUBY_VERSION[0..2] < "3.2"
+  Shoes::Log.logger("Scarpe").error("Scarpe requires Ruby 3.2 or higher!")
+  exit(-1)
+end
+
+class Scarpe; end
+
+# The base error class for Scarpe errors, but not necessarily {Shoes::Error}s
+class Scarpe::Error < StandardError; end
+
+require "lacci/version"
+require "scarpe/components/version"

data/lacci/lib/lacci/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# The name "scarpe" means "shoes" in Italian. "Lacci"
+# means "laces." Lacci is the display-independent part
+# of Scarpe, tying the Shoes API to the display service
+# of your choice.
+#
+# Almost nothing is called Lacci in your program. It's
+# mostly invisible. Instead, look at the {Shoes} module
+# to see what's in Lacci.
+module Lacci
+  VERSION = "0.2.2"
+end

data/lacci/lib/shoes/app.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Shoes
+  class App < Shoes::Widget
+    include Shoes::Log
+
+    class << self
+      attr_accessor :instance
+    end
+
+    attr_reader :document_root
+
+    display_properties :title, :width, :height, :resizable
+
+    CUSTOM_EVENT_LOOP_TYPES = ["displaylib", "return", "wait"]
+
+    def initialize(
+      title: "Shoes!",
+      width: 480,
+      height: 420,
+      resizable: true,
+      &app_code_body
+    )
+      log_init("Shoes::App")
+
+      if Shoes::App.instance
+        @log.error("Trying to create a second Shoes::App in the same process! Fail!")
+        raise "Cannot create multiple Shoes::App objects!"
+      else
+        Shoes::App.instance = self
+      end
+
+      @do_shutdown = false
+      @event_loop_type = "displaylib" # the default
+
+      super
+
+      # The draw context tracks current settings like fill and stroke,
+      # plus potentially other current state that changes from widget
+      # to widget and slot to slot.
+      @draw_context = {
+        "fill" => "",
+        "stroke" => "",
+      }
+
+      # This creates the DocumentRoot, including its corresponding display widget
+      @document_root = Shoes::DocumentRoot.new
+
+      @slots = []
+
+      # Now create the App display widget
+      create_display_widget
+
+      # 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 != ""
+          self.instance_eval test_code
+        end
+      end
+
+      @app_code_body = app_code_body
+
+      # 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
+        Shoes::DisplayService.unsub_from_events(@watch_for_destroy) if @watch_for_destroy
+        @watch_for_destroy = nil
+        self.destroy(send_event: false)
+      end
+
+      @watch_for_event_loop = bind_shoes_event(event_name: "custom_event_loop") do |loop_type|
+        raise("Unknown event loop type: #{loop_type.inspect}!") unless CUSTOM_EVENT_LOOP_TYPES.include?(loop_type)
+
+        @event_loop_type = loop_type
+      end
+
+      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")
+      return if @do_shutdown
+
+      ::Shoes::App.instance.with_slot(@document_root, &@app_code_body)
+    end
+
+    # "Container" widgets like flows, stacks, masks and the document root
+    # are considered "slots" in Shoes parlance. When a new slot is created,
+    # we push it here in order to track what widgets are found in that slot.
+    def push_slot(slot)
+      @slots.push(slot)
+    end
+
+    def pop_slot
+      return if @slots.size <= 1
+
+      @slots.pop
+    end
+
+    def current_slot
+      @slots[-1]
+    end
+
+    def with_slot(slot_item, &block)
+      return unless block_given?
+
+      push_slot(slot_item)
+      Shoes::App.instance.instance_eval(&block)
+    ensure
+      pop_slot
+    end
+
+    def current_draw_context
+      @draw_context.dup
+    end
+
+    # This usually doesn't return. The display service may take control
+    # of the main thread. Local Webview even stops any background threads.
+    # However, some display libraries don't want to shut down and don't
+    # 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!"
+        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")
+
+      case @event_loop_type
+      when "wait"
+        # Display lib wants us to busy-wait instead of it.
+        sleep 0.1 until @do_shutdown
+      when "displaylib"
+        # If run event returned, that means we're done.
+        destroy
+      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 "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
+    end
+
+    def all_widgets
+      out = []
+
+      to_add = @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
+      end
+
+      out
+    end
+
+    # We can add various ways to find widgets here.
+    # These are sort of like Shoes selectors, used for testing.
+    def find_widgets_by(*specs)
+      widgets = all_widgets
+      specs.each do |spec|
+        if spec.is_a?(Class)
+          widgets.select! { |w| spec === w }
+        elsif spec.is_a?(Symbol) || spec.is_a?(String)
+          s = spec.to_s
+          case s[0]
+          when "$"
+            begin
+              # I'm not finding a global_variable_get or similar...
+              global_value = eval s
+              widgets &= [global_value]
+            rescue
+              raise "Error getting global variable: #{spec.inspect}"
+            end
+          when "@"
+            if Shoes::App.instance.instance_variables.include?(spec.to_sym)
+              widgets &= [self.instance_variable_get(spec)]
+            else
+              raise "Can't find top-level instance variable: #{spec.inspect}!"
+            end
+          else
+          end
+        else
+          raise("Don't know how to find widgets by #{spec.inspect}!")
+        end
+      end
+      widgets
+    end
+  end
+end
+
+# DSL methods
+class Shoes::App
+  def background(...)
+    current_slot.background(...)
+  end
+
+  def border(...)
+    current_slot.border(...)
+  end
+
+  def motion(&block)
+    subscription_item(shoes_api_name: "motion", &block)
+  end
+
+  def hover(&block)
+    subscription_item(shoes_api_name: "hover", &block)
+  end
+
+  def click(&block)
+    subscription_item(shoes_api_name: "click", &block)
+  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"] = ""
+  end
+
+  # Shape DSL methods
+
+  def move_to(x, y)
+    raise("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])
+    end
+  end
+
+  def line_to(x, y)
+    raise("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])
+    end
+  end
+
+  # Not implemented yet: curve_to, arc_to
+
+  alias_method :info, :puts
+end

data/{lib/scarpe → lacci/lib/shoes}/background.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Scarpe
+module Shoes
   module Background
     def self.included(includer)
       includer.display_property(:background_color)

data/{lib/scarpe → lacci/lib/shoes}/border.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Scarpe
+module Shoes
   module Border
     def self.included(includer)
       includer.display_properties :border_color, :options

data/{lib/scarpe → lacci/lib/shoes}/colors.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Scarpe
+module Shoes
   module Colors
     COLORS = {
       aliceblue: [240, 248, 255],

data/lacci/lib/shoes/constants.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Shoes
+  module Constants
+    def self.find_lib_dir
+      begin
+        require "tmpdir"
+      rescue LoadError
+        return nil
+      end
+      homes = [
+        [ENV["LOCALAPPDATA"], "Shoes"],
+        [ENV["APPDATA"], "Shoes"],
+        [ENV["HOME"], ".shoes"],
+        [Dir.tmpdir, "shoes"],
+      ]
+      top, file = homes.detect { |home_top, _| home_top && File.exist?(home_top) }
+      File.join(top, file)
+    end
+
+    LIB_DIR = find_lib_dir
+
+    # Math constants from Shoes3
+    RAD2PI = 0.01745329251994329577
+    TWO_PI = 6.28318530717958647693
+    HALF_PI = 1.57079632679489661923
+    PI = 3.14159265358979323846
+  end
+end

data/{lib/scarpe → lacci/lib/shoes}/display_service.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-# Scarpe Shoes apps operate in multiple layers. A Shoes widget tree exists as fairly
+# Lacci Shoes apps operate in multiple layers. A Shoes widget tree exists as fairly
 # plain, simple Ruby objects. And then a display-service widget tree integrates with
-# the display technology, initially Webview. This lets us use Ruby as our API while
-# not tying it too closely to the limitations of Webview.
+# the display technology. This lets us use Ruby as our API while
+# not tying it too closely to the limitations of Webview, WASM, LibUI, etc.
 #
 # ## Choosing Display Services
 #
-# Before running a Scarpe app, you can set SCARPE_DISPLAY_SERVICE. If you
+# Before running a Lacci app, you can set SCARPE_DISPLAY_SERVICE. If you
 # set it to "whatever_service", Scarpe will require "scarpe/whatever_service",
 # which can be supplied by the Scarpe gem or another Scarpe-based gem.
 # Currently leaving the environment variable empty is equivalent to requesting
@@ -17,7 +17,7 @@
 #
 # Events are a lot of what tie the Shoes widgets and the display service together.
 #
-# Scarpe widgets *expect* to operate in a fairly "hands off" mode where they record
+# Shoes widgets *expect* to operate in a fairly "hands off" mode where they record
 # to an event queue to send to the display service, and the display service records
 # events to send back.
 #
@@ -26,25 +26,11 @@
 # And when a display-side event occurs (e.g. user pushes a button,) it will be
 # dispatched as a :shoes event, to be sent to the Shoes tree of widgets.
 #
-# It is normally assumed that there will only be a single 'real' consumer for each
-# queue. You wouldn't usually want multiple display services sending back click
-# events, for example. But that's not a technical limitation of the system.
-# You could have no display service and not get any events back, or a debug
-# display service that just records what happened. But in real situations,
-# exactly one display service is a reasonable and appropriate assumption.
-#
-# The event types are "queues" in the sense that they're separate from each
-# other. You need to subscribe separately to :shoes and :display events if
-# you want both. But internally they're immediately dispatched as events
-# rather than keeping a literal array of items.
-#
-class Scarpe
+module Shoes
   class DisplayService
     class << self
       # This is in the eigenclass/metaclass, *not* instances of DisplayService
-      include Scarpe::Log
-
-      attr_accessor :json_debug_serialize
+      include Shoes::Log
 
       # An event_target may be nil, to indicate there is no target.
       def dispatch_event(event_name, event_target, *args, **kwargs)
@@ -58,7 +44,8 @@ class Scarpe
 
         @log.debug("Dispatch event: #{event_name.inspect} T: #{event_target.inspect} A: #{args.inspect} KW: #{kwargs.inspect}")
 
-        if DisplayService.json_debug_serialize
+        # When true, this makes sure all events and properties are 100% strings, no symbols.
+        if ENV["SCARPE_DEBUG"]
           args = JSON.parse JSON.dump(args)
           new_kw = {}
           kwargs.each do |k, v|
@@ -139,29 +126,6 @@ class Scarpe
       end
     end
 
-    # This is for objects that can be referred to via events, using their
-    # IDs. There are also convenience functions for binding and sending
-    # events.
-    class Linkable
-      attr_reader :linkable_id
-
-      def initialize(linkable_id: object_id)
-        @linkable_id = linkable_id
-      end
-
-      def send_self_event(*args, event_name:, **kwargs)
-        DisplayService.dispatch_event(event_name, self.linkable_id, *args, **kwargs)
-      end
-
-      def send_shoes_event(*args, event_name:, target: nil, **kwargs)
-        DisplayService.dispatch_event(event_name, target, *args, **kwargs)
-      end
-
-      def bind_shoes_event(event_name:, target: nil, &handler)
-        DisplayService.subscribe_to_event(event_name, target, &handler)
-      end
-    end
-
     # These methods are an interface to DisplayService objects.
 
     def create_display_widget_for(widget_class_name, widget_id, properties)
@@ -186,4 +150,35 @@ class Scarpe
       raise "Override in DisplayService implementation!"
     end
   end
+
+  # This is for objects that can be referred to via events, using their
+  # IDs. There are also convenience functions for binding and sending
+  # events.
+  #
+  # Linkable objects may be event targets. Technically anything, linkable
+  # or not, can be an event subscriber, but linkables get easy convenience
+  # functions for subscription.
+  class Linkable
+    attr_reader :linkable_id
+
+    def initialize(linkable_id: object_id)
+      @linkable_id = linkable_id
+    end
+
+    def send_self_event(*args, event_name:, **kwargs)
+      DisplayService.dispatch_event(event_name, self.linkable_id, *args, **kwargs)
+    end
+
+    def send_shoes_event(*args, event_name:, target: nil, **kwargs)
+      DisplayService.dispatch_event(event_name, target, *args, **kwargs)
+    end
+
+    def bind_shoes_event(event_name:, target: nil, &handler)
+      DisplayService.subscribe_to_event(event_name, target, &handler)
+    end
+
+    def unsub_shoes_event(unsub_id)
+      DisplayService.unsub_from_events(unsub_id)
+    end
+  end
 end