lacci 0.2.2 → 0.3.0

data/lib/shoes/{widgets → drawables}/slot.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-class Shoes::Slot < Shoes::Widget
+class Shoes::Slot < Shoes::Drawable
   # @incompatibility Shoes uses #content, not #children, for this
   attr_reader :children
 
+  shoes_events # No Slot-specific events yet
+
   # Do not call directly, use set_parent
   def remove_child(child)
     @children ||= []
@@ -19,29 +21,39 @@ class Shoes::Slot < Shoes::Widget
     @children << child
   end
 
-  # Get a list of child widgets
+  # Get a list of child drawables
   def contents
     @children ||= []
     @children.dup
   end
 
-  # Calling stack.app or flow.app will execute the block
-  # with the Shoes::App as self, and with that stack or
-  # flow as the current slot.
-  #
-  # @incompatibility Shoes Classic will only change self
-  #   via this method, while Scarpe will also change self
-  #   with the other Slot Manipulation methods: #clear,
-  #   #append, #prepend, #before and #after.
-  #
-  # @return [Shoes::App] the Shoes app
-  # @yield the block to call with the Shoes App as self
-  def app(&block)
-    Shoes::App.instance.with_slot(self, &block) if block_given?
-    Shoes::App.instance
+  # We use method_missing for drawable-creating methods like "button".
+  # The parent's method_missing will auto-create Shoes style getters and setters.
+  def method_missing(name, *args, **kwargs, &block)
+    klass = ::Shoes::Drawable.drawable_class_by_name(name)
+    return super unless klass
+
+    ::Shoes::Slot.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)
+        drawable_instance.set_parent self # Create drawable in THIS SLOT, not current app slot
+      end
+
+      drawable_instance
+    end
+
+    send(name, *args, **kwargs, &block)
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    return true if Drawable.drawable_class_by_name(name.to_s)
+
+    false
   end
 
-  # Remove all children from this widget. If a block
+  # Remove all children from this drawable. If a block
   # is given, call the block to replace the children with
   # new contents from that block.
   #
@@ -50,7 +62,7 @@ class Shoes::Slot < Shoes::Widget
   #
   # @incompatibility Shoes Classic calls the clear block with current self, while Scarpe uses the Shoes::App as self
   #
-  # @yield The block to call to replace the contents of the widget (optional)
+  # @yield The block to call to replace the contents of the drawable (optional)
   # @return [void]
   def clear(&block)
     @children.dup.each(&:destroy)
@@ -67,8 +79,8 @@ class Shoes::Slot < Shoes::Widget
   # @yield the block to call to replace children; will be called on the Shoes::App, appending to the called Slot as the current slot
   # @return [void]
   def append(&block)
-    raise("append requires a block!") unless block_given?
-    raise("Don't append to something that isn't a slot!") unless self.is_a?(Shoes::Slot)
+    raise(Shoes::Errors::InvalidAttributeValueError, "append requires a block!") unless block_given?
+    raise(Shoes::Errors::InvalidAttributeValueError, "Don't append to something that isn't a slot!") unless self.is_a?(Shoes::Slot)
 
     Shoes::App.instance.with_slot(self, &block)
   end

data/lib/shoes/{widgets → drawables}/span.rb

@@ -1,25 +1,26 @@
 # frozen_string_literal: true
 
-module Shoes
-  class Span < Shoes::Widget
-    display_properties :text, :stroke, :size, :font, :html_attributes
+class Shoes
+  class Span < Shoes::Drawable
+    shoes_styles :text, :stroke, :size, :font, :html_attributes
+    shoes_events # No Span-specific events yet
 
     def initialize(text, stroke: nil, size: :span, font: nil, **html_attributes)
+      super
+
       @text = text
       @stroke = stroke
       @size = size
       @font = font
       @html_attributes = html_attributes
 
-      super
-
-      create_display_widget
+      create_display_drawable
     end
 
     def replace(text)
       @text = text
 
-      # This should signal the display widget to change
+      # This should signal the display drawable to change
       self.text = @text
     end
   end

data/lib/shoes/{widgets → drawables}/stack.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
-module Shoes
+class Shoes
   class Stack < Shoes::Slot
     include Shoes::Background
     include Shoes::Border
     include Shoes::Spacing
 
     # TODO: sort out various margin and padding properties, including putting stuff into spacing
-    display_properties :width, :height, :scroll
+    shoes_styles :width, :height, :scroll
+
+    shoes_events # No Stack-specific events yet
 
     def initialize(width: nil, height: nil, margin: nil, padding: nil, scroll: false, margin_top: nil, margin_bottom: nil, margin_left: nil,
       margin_right: nil, **options, &block)
@@ -16,8 +18,8 @@ module Shoes
 
       super
 
-      create_display_widget
-      # Create the display-side widget *before* running the block, which will add child widgets with their display widgets
+      create_display_drawable
+      # Create the display-side drawable *before* running the block, which will add child drawables with their display drawables
       Shoes::App.instance.with_slot(self, &block) if block_given?
     end
   end

data/lib/shoes/drawables/star.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Shoes
+  class Star < Shoes::Drawable
+    shoes_styles :left, :top, :draw_context
+
+    shoes_style(:points) { |val| convert_to_integer(val, "points") }
+    shoes_style(:outer) { |val| convert_to_float(val, "outer") }
+    shoes_style(:inner) { |val| convert_to_float(val, "inner") }
+
+    shoes_events # No Star-specific events yet
+
+    def initialize(left, top, points = 10, outer = 100, inner = 50)
+      super
+      self.left = left
+      self.top = top
+      self.points = points
+      self.outer = outer
+      self.inner = inner
+
+      @draw_context = Shoes::App.instance.current_draw_context
+
+      create_display_drawable
+    end
+
+    def self.convert_to_integer(value, attribute_name)
+      begin
+        value = Integer(value)
+        raise Shoes::Errors::InvalidAttributeValueError, "Negative num '#{value}' not allowed for attribute '#{attribute_name}'" if value < 0
+
+        value
+      rescue ArgumentError
+        error_message = "Invalid value '#{value}' provided for attribute '#{attribute_name}'. The value should be a number."
+        raise Shoes::Errors::InvalidAttributeValueError, error_message
+      end
+    end
+
+    def self.convert_to_float(value, attribute_name)
+      begin
+        value = Float(value)
+        raise Shoes::Errors::InvalidAttributeValueError, "Negative num '#{value}' not allowed for attribute '#{attribute_name}'" if value < 0
+
+        value
+      rescue ArgumentError
+        error_message = "Invalid value '#{value}' provided for attribute '#{attribute_name}'. The value should be a number."
+        raise Shoes::Errors::InvalidAttributeValueError, error_message
+      end
+    end
+  end
+end

data/lib/shoes/drawables/subscription_item.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Certain Shoes calls like motion and keydown are basically an
+# event subscription, with no other visible presence. However,
+# they have a place in the drawable tree and can be deleted.
+#
+# Depending on the display library they may not have any
+# direct visual (or similar) presence there either.
+#
+# Inheriting from Drawable gives these a parent slot and a
+# linkable_id automatically.
+#
+# Events not yet implemented: start, finish events for slots -
+# start is first draw, finish is drawable destroyed
+class Shoes::SubscriptionItem < Shoes::Drawable
+  shoes_styles :shoes_api_name, :args
+  shoes_events :animate, :every, :timer, :hover, :leave, :motion, :click, :release, :keypress
+
+  def initialize(args: [], shoes_api_name:, &block)
+    super
+
+    @callback = block
+
+    case shoes_api_name
+    when "animate"
+      @unsub_id = bind_self_event("animate") do |frame|
+        @callback.call(frame)
+      end
+    when "every"
+      @unsub_id = bind_self_event("every") do |count|
+        @callback.call(count)
+      end
+    when "timer"
+      @unsub_id = bind_self_event("timer") do
+        @callback.call
+      end
+    when "hover"
+      # Hover passes the Shoes drawable as the block param
+      @unsub_id = bind_self_event("hover") do
+        @callback&.call(self)
+      end
+    when "leave"
+      # Leave passes the Shoes drawable as the block param
+      @unsub_id = bind_self_event("leave") do
+        @callback&.call(self)
+      end
+    when "motion"
+      # Shoes sends back x, y, mods as the args.
+      # Shoes3 uses the strings "control" "shift" and
+      # "control_shift" as the mods arg.
+      @unsub_id = bind_self_event("motion") do |x, y, ctrl_key, shift_key, **_kwargs|
+        mods = [ctrl_key ? "control" : nil, shift_key ? "shift" : nil].compact.join("_")
+        @callback&.call(x, y, mods)
+      end
+    when "click"
+      # Click has block params button, left, top
+      # button is the button number, left and top are coords
+      @unsub_id = bind_self_event("click") do |button, x, y, **_kwargs|
+        @callback&.call(button, x, y)
+      end
+    when "release"
+      # Click has block params button, left, top
+      # button is the button number, left and top are coords
+      @unsub_id = bind_self_event("release") do |button, x, y, **_kwargs|
+        @callback&.call(button, x, y)
+      end
+    when "keypress"
+      # Keypress passes the key string or symbol to the handler
+      # Do anything special for serialisation here?
+      @unsub_id = bind_self_event("keypress") do |key|
+        @callback&.call(key)
+      end
+    else
+      raise "Unknown Shoes event #{shoes_api_name.inspect} passed to SubscriptionItem!"
+    end
+
+    @unsub_id = bind_self_event(shoes_api_name) do |*args|
+      @callback&.call(*args)
+    end
+
+    # This won't create a visible display drawable, but will turn into
+    # an invisible drawable and a stream of events.
+    create_display_drawable
+  end
+
+  def destroy
+    # TODO: we need a better way to do this automatically. See https://github.com/scarpe-team/scarpe/issues/291
+    unsub_shoes_event(@unsub_id) if @unsub_id
+    @unsub_id = nil
+
+    super
+  end
+end

data/lib/shoes/drawables/text_drawable.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class Shoes
+  # TextDrawable is the parent class of various classes of
+  # text that can go inside a para. This includes normal
+  # text, but also links, italic text, bold text, etc.
+  class TextDrawable < Shoes::Drawable
+    class << self
+      # rubocop:disable Lint/MissingSuper
+      def inherited(subclass)
+        Shoes::Drawable.drawable_classes ||= []
+        Shoes::Drawable.drawable_classes << subclass
+
+        Shoes::Drawable.drawable_default_styles ||= {}
+        Shoes::Drawable.drawable_default_styles[subclass] = {}
+      end
+      # rubocop:enable Lint/MissingSuper
+    end
+
+    shoes_events # No TextDrawable-specific events yet
+  end
+
+  class << self
+    def default_text_drawable_with(element)
+      class_name = element.capitalize
+
+      drawable_class = Class.new(Shoes::TextDrawable) do
+        # Can we just change content to text to match the Shoes API?
+        shoes_style :content
+
+        def initialize(content)
+          super
+
+          @content = content
+
+          create_display_drawable
+        end
+
+        def text
+          self.content
+        end
+
+        def to_s
+          self.content
+        end
+
+        def text=(new_text)
+          self.content = new_text
+        end
+      end
+      Shoes.const_set class_name, drawable_class
+      drawable_class.class_eval do
+        shoes_style :content
+
+        shoes_events # No specific events
+      end
+    end
+  end
+end
+
+Shoes.default_text_drawable_with(:code)
+Shoes.default_text_drawable_with(:em)
+Shoes.default_text_drawable_with(:strong)

data/lib/shoes/drawables/video.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Shoes
+  class Video < Shoes::Drawable
+    shoes_styles :url
+    shoes_events # No specific events yet
+
+    def initialize(url)
+      super
+      @url = url
+      create_display_drawable
+    end
+
+    # other methods
+  end
+end

data/lib/shoes/drawables/widget.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# A Shoes::Widget is mostly a Slot (related to the
+# old Shoes concepts of Canvas) that creates drawables
+# inside itself. When a subclass of Widget is created,
+# it adds a method to create new objects of that type
+# on Shoes::App and all Shoes slots.
+#
+# The hardest part with a Shoes::Widget is that it
+# should work fine even if initialize() doesn't call
+# super, which would make it hard to set up a Shoes
+# linkable_id, create a display widget, etc.
+#
+# It would be possible to add an extra method to set
+# these up and call it on every created drawable
+# in case a Widget's initialize method doesn't call
+# super, which happens quite often. But then we wouldn't
+# support automatic setting of styles (e.g. padding)
+# for the widget object itself, which is mostly a Flow.
+# We also couldn't support default styles -- I can't tell
+# whether Shoes supports these things either.
+#
+# But there's another way to do all of this. When a
+# subclass of Widget defines an initialize method,
+# we can catch the method_added hook, save a copy of
+# that initialize method, and substitute our own
+# initialize that calls super. We have to be a little
+# careful -- if the widget's initialize *does* call
+# super that shouldn't be an error. But that's
+# workable by defining an extra method with the
+# copied-method name that does nothing.
+
+##### TODO: when this is subclassed, grab :initialize out
+# of the subclass, put it into :initialize_widget, and
+# replace with an initialize that creates the display
+# widget propertly, sets the linkable_id, etc.
+
+class Shoes::Widget < Shoes::Slot
+  include Shoes::Background
+  include Shoes::Border
+  include Shoes::Spacing
+
+  shoes_events
+
+  def self.method_added(name)
+    # We're only looking for the initialize() method, and only on subclasses
+    # of Shoes::Widget, not Shoes::Widget itself.
+    return if self == ::Shoes::Widget || name != :initialize
+
+    # Need to avoid infinite adding of initialize() if we're re-adding the default initialize
+    return if @midway_through_adding_initialize
+
+    # Take the user-provided initialize method and save a copy named __widget_initialize
+    alias_method :__widget_initialize, :initialize
+
+    # And add the default initialize back where it belongs
+    @midway_through_adding_initialize = true
+    define_method(:initialize) do |*args, **kwargs, &block|
+      super(*args, **kwargs, &block)
+      @options = kwargs
+      create_display_drawable
+      __widget_initialize(*args, **kwargs, &block)
+
+      # Do Widgets do this?
+      Shoes::App.instance.with_slot(self, &block) if block
+    end
+    @midway_through_adding_initialize = false
+  end
+end

data/lib/shoes/drawables.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "shoes/drawables/slot"
+require "shoes/drawables/stack"
+require "shoes/drawables/flow"
+require "shoes/drawables/widget"
+require "shoes/drawables/document_root"
+
+require "shoes/drawables/text_drawable"
+
+require "shoes/drawables/subscription_item"
+
+require "shoes/drawables/arc"
+require "shoes/drawables/line"
+require "shoes/drawables/rect"
+require "shoes/drawables/shape"
+require "shoes/drawables/star"
+require "shoes/drawables/arrow"
+
+require "shoes/drawables/button"
+require "shoes/drawables/check"
+require "shoes/drawables/edit_box"
+require "shoes/drawables/edit_line"
+require "shoes/drawables/image"
+require "shoes/drawables/link"
+require "shoes/drawables/list_box"
+require "shoes/drawables/para"
+require "shoes/drawables/radio"
+require "shoes/drawables/span"
+require "shoes/drawables/video"
+require "shoes/drawables/progress"

data/lib/shoes/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Shoes; end
+class Shoes::Errors
+  class InvalidAttributeValueError < Shoes::Error; end
+
+  class TooManyInstancesError < Shoes::Error; end
+
+  class NoSuchListItemError < Shoes::Error; end
+
+  class DuplicateCreateDrawableError < Shoes::Error; end
+
+  class MultipleDrawablesFoundError < Shoes::Error; end
+
+  class NoDrawablesFoundError < Shoes::Error; end
+
+  class NoSuchStyleError < Shoes::Error; end
+
+  class NoLinkableIdError < Shoes::Error; end
+
+  class BadLinkableIdError < Shoes::Error; end
+
+  class UnregisteredShoesEvent < Shoes::Error; end
+
+  class SingletonError < Shoes::Error; end
+
+  class MultipleShoesSpecRunsError < Shoes::Error; end
+end

data/lib/shoes/log.rb

@@ -8,7 +8,7 @@
 # If used alone, this will fail because the @instance is nil. It needs
 # an implementation to be plugged in.
 
-module Shoes
+class Shoes
   LOG_LEVELS = [:debug, :info, :warn, :error, :fatal].freeze
 
   # Include this module to get a @log instance variable to log as your
@@ -28,7 +28,7 @@ module Shoes
       attr_reader :current_log_config
 
       def instance=(impl_object)
-        raise(Shoes::Error, "Already have an instance for Shoes::Log!") if @instance
+        raise(Shoes::Errors::TooManyInstancesError, "Already have an instance for Shoes::Log!") if @instance
 
         @instance = impl_object
       end

data/lib/shoes/ruby_extensions.rb

@@ -0,0 +1,15 @@
+
+class Range
+  def rand
+    conv = (Integer === self.end && Integer === self.begin ? :to_i : :to_f)
+    ((Kernel.rand * (self.end - self.begin)) + self.begin).send(conv)
+  end
+end
+
+unless Time.respond_to? :today
+  def Time.today
+    t = Time.now
+    t - (t.to_i % 86_400)
+  end
+end
+

data/lib/shoes/spacing.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-module Shoes
+class Shoes
   module Spacing
     def self.included(includer)
-      includer.display_properties :margin, :padding, :margin_top, :margin_left, :margin_right, :margin_bottom, :options
+      includer.shoes_styles :margin, :padding, :margin_top, :margin_left, :margin_right, :margin_bottom, :options
     end
   end
 end

data/lib/shoes-spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+class Shoes
+  # A Scarpe-compatible display service can set Shoes::Spec.instance to
+  # a ShoesSpec testing class, and use it to run Shoes-Spec code.
+  # A Shoes application should never do this. It's intended to be used
+  # by display services.
+  module Spec
+    def self.instance
+      @instance
+    end
+
+    def self.instance=(spec_inst)
+      if @instance && @instance != spec_inst
+        raise "Lacci can only use a single ShoesSpec implementation at one time!"
+      end
+
+      @instance = spec_inst
+    end
+  end
+
+  # ShoesSpec testing objects can optionally inherit from this object,
+  # which shows the ShoesSpec testing API.
+  #
+  # @see {Shoes::Spec.instance=}
+  class SpecInstance
+    # Once a Shoes app has been created, this method can be called to
+    # execute Shoes-Spec testing code for that application. Shoes-Spec
+    # uses Minitest for most of its APIs, and Minitest generally reports
+    # results with a class name and test name. If those aren't passed
+    # explicitly, the SpecInstance can choose reasonable defaults.
+    #
+    # The test code should be set up to run automatically from the
+    # display service's existing hooks. For instance, the code might
+    # run in response to the first heartbeat, if the display service
+    # uses heartbeats.
+    #
+    # The test code will export assertion data in its native format.
+    # Multiple display services choose to use the Scarpe-Component
+    # for Minitest data export, which is straightforward to import
+    # into the Shoes-Spec test harness.
+    #
+    # @param code [String] the ShoesSpec code to execute
+    # @param class_name [String|NilClass] the Minitest class name for reporting or nil
+    # @param test_name [String|NilClass] the Minitest test name for reporting or nil
+    # @return [void]
+    def run_shoes_spec_test_code(code, class_name: nil, test_name: nil)
+      raise "Child class should override this!"
+    end
+  end
+
+  # ShoesSpec instances support finder methods like button() that return
+  # a proxy to the corresponding drawable. Those proxies should support
+  # standard Shoes::Drawable methods, including the ones appropriate to
+  # the same drawable object. They should also support certain other
+  # testing-specific methods like "trigger_click" that are used to
+  # simulate display-side events during testing.
+  #
+  # Keep in mind that a proxy will often be in a different process from
+  # the Shoes app. So the proxy can't portably return the object or
+  # display object, though it could possibly return another proxy for such
+  # a thing.
+  class SpecProxy
+    # The proxy will have finder methods for all drawables, such as
+    # button(), edit_line(), etc. How to document those?
+
+    # Trigger a click on a button or button-like drawable. Not every
+    # drawable will support this operation.
+    def trigger_click()
+      raise "Child class should override this!"
+    end
+
+    # Trigger a hover over a hoverable drawable. Not every
+    # drawable will support this operation. A drawable that supports
+    # hover should support leave and vice-versa.
+    def trigger_hover()
+      raise "Child class should override this!"
+    end
+
+    # Trigger ending hover over a hoverable drawable. Not every
+    # drawable will support this operation. A drawable that supports
+    # hover should support leave and vice-versa.
+    def trigger_leave()
+      raise "Child class should override this!"
+    end
+
+    # Trigger a change in value for a drawable like a list_box
+    # with multiple values.
+    def trigger_change(value)
+      raise "Child class should override this!"
+    end
+  end
+end