openhab-scripting 5.22.0 → 5.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 195fdc136c01213d162a6e82a75003c2c52102ffe68e8eaf48fe96d39517d6b0
-  data.tar.gz: bae1950261063adc7b741158a6a4c16cd4a390de63717f3a391d140734a659f9
+  metadata.gz: 55ff8734004f7befde1f1d3bb27560cfc8c5dbb7287f8dbb5e19a50fadec0d23
+  data.tar.gz: dba9276e8b4845e1b265973440aa0e036da3137176ba44c5c256ddfcd5dad227
 SHA512:
-  metadata.gz: e9d2406ccc8a7140e5de11207aac0e6341dfe4c37cf397fa3e43e026a6b84a63b1b1030c0ea7982ac84de3be8a087aca8c4b990c759058c9cbbf5bb579071226
-  data.tar.gz: 0f317d5d7d1594466752ae47b2f6f0285974c7d159c423ad3d95f8a5519809cdbb08059da89273307b6bfc449dce4ec840dcdfb848f315ce524e4a35f412d9dc
+  metadata.gz: 6c4692d9a8ce6104b511e1475e01fcae49f0fda6bdf04f498c26b023237f8332e87166cbdc5e2754f1375b4e2cbf31f70c706e68beda3657d6f09b28d37b59bf
+  data.tar.gz: 133e78f26b440c5ffbb628ee323d56d2e4b4e74c1a65762cec75818f7ebfe5eeda4275e7cd6157fb68d90d551c5e2b4c984016c149abf222dc1917428f4c7e49

data/lib/openhab/core/actions/notification.rb

@@ -29,8 +29,11 @@ module OpenHAB
           # @param on_click [String, nil] The action to be performed when the user clicks on the notification.
           #   Specified using the {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax
           #   action syntax}.
-          # @param attachment [String, nil] The URL of the media attachment to be displayed with the notification.
-          #   This URL must be reachable by the push notification client.
+          # @param attachment [String, Item, nil] The URL of the media attachment to be displayed with the notification.
+          #   This can either be a fully qualified URL, prefixed with
+          #   `http://` or `https://` and reachable by the client device,
+          #   a relative path on the user's openHAB instance starting with `/`,
+          #   or an image item.
           # @param buttons [Array<String>, Hash<String, String>, nil] Buttons to include in the notification.
           #   - In array form, each element is specified as `Title=$action`, where `$action` follows the
           #   {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax action syntax}.
@@ -94,6 +97,8 @@ module OpenHAB
               buttons = buttons.map { |title, action| "#{title}=#{action}" } if buttons.is_a?(Hash)
               raise ArgumentError, "buttons must contain (0..3) elements." unless (0..3).cover?(buttons.size)
 
+              attachment = "item:#{attachment.name}" if attachment.is_a?(Item) && attachment.image_item?
+
               args.push(title&.to_s,
                         id&.to_s,
                         on_click&.to_s,

data/lib/openhab/core/items/group_item.rb

@@ -146,7 +146,7 @@ module OpenHAB
           base_item.format_type(command)
         end
 
-        %w[color contact date_time dimmer image location number player rollershutter string switch].each do |type|
+        %w[call color contact date_time dimmer image location number player rollershutter string switch].each do |type|
           type_class = type.gsub(/(^[a-z]|_[a-z])/) { |letter| letter[-1].upcase }
           class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{type}_item?                      # def date_time_item?

data/lib/openhab/core/types/time_series.rb

@@ -4,6 +4,7 @@
 return unless OpenHAB::Core.version >= OpenHAB::Core::V4_1
 
 require "forwardable"
+require "openhab/core/lazy_array"
 
 module OpenHAB
   module Core
@@ -30,7 +31,7 @@ module OpenHAB
       # @see DSL::Rules::BuilderDSL#time_series_updated #time_series_updated rule trigger
       #
       class TimeSeries
-        extend Forwardable
+        include LazyArray
 
         # @!attribute [r] policy
         #   Returns the persistence policy of this series.
@@ -81,12 +82,19 @@ module OpenHAB
             "size=#{size}>"
         end
 
+        # Explicit conversion to Array
+        #
+        # @return [Array]
+        def to_a
+          get_states.to_array.to_a.freeze
+        end
+
         #
         # Returns the content of this series.
         # @return [Array<org.openhab.core.types.TimeSeries.Entry>]
         #
         def states
-          get_states.to_array.to_a.freeze
+          to_a
         end
 
         # rename raw methods so we can overwrite them
@@ -100,29 +108,62 @@ module OpenHAB
         #
         # @note This method returns self so it can be chained, unlike the Java version.
         #
-        # @param [Instant, #to_zoned_date_time, #to_instant] instant An instant for the given state.
+        # @param [Instant, #to_zoned_date_time, #to_instant] timestamp An instant for the given state.
         # @param [State, String, Numeric] state The State at the given timestamp.
         #   If a String is given, it will be converted to {StringType}.
         #   If a {Numeric} is given, it will be converted to {DecimalType}.
         # @return [self]
         # @raise [ArgumentError] if state is not a {State}, String or {Numeric}
         #
-        def add(instant, state)
-          instant = instant.to_zoned_date_time if instant.respond_to?(:to_zoned_date_time)
-          instant = instant.to_instant if instant.respond_to?(:to_instant)
-          state = case state
-                  when State then state
-                  when String then StringType.new(state)
-                  when Numeric then DecimalType.new(state)
-                  else
-                    raise ArgumentError, "state must be a State, String or Numeric, but was #{state.class}"
-                  end
-          add_instant(instant, state)
+        def add(timestamp, state)
+          timestamp = to_instant(timestamp)
+          state = format_state(state)
+          add_instant(timestamp, state)
           self
         end
 
-        # any method that exists on Array gets forwarded to states
-        delegate (Array.instance_methods - instance_methods) => :states
+        #
+        # Appends an entry to self, returns self
+        #
+        # @param [Array<Instant, State>] entry a two-element array with the timestamp and state.
+        #   The timestamp can be an {Instant} or any object that responds to #to_zoned_date_time.
+        # @return [self]
+        #
+        # @example Append an entry
+        #   time_series << [Time.at(2), 2]
+        #
+        def <<(entry)
+          raise ArgumentError, "entry must be an Array, but was #{entry.class}" unless entry.respond_to?(:to_ary)
+
+          entry = entry.to_ary
+          raise ArgumentError, "entry must be an Array of size 2, but was #{entry.size}" unless entry.size == 2
+
+          add(entry[0], entry[1])
+        end
+
+        private
+
+        def to_instant(timestamp)
+          if timestamp.is_a?(Instant)
+            timestamp
+          elsif timestamp.respond_to?(:to_instant)
+            timestamp.to_instant
+          elsif timestamp.respond_to?(:to_zoned_date_time)
+            timestamp.to_zoned_date_time.to_instant
+          else
+            raise ArgumentError, "timestamp must be an Instant, or convertible to one, but was #{timestamp.class}"
+          end
+        end
+
+        def format_state(state)
+          case state
+          when State then state
+          when String then StringType.new(state)
+          when Numeric then DecimalType.new(state)
+          else
+            raise ArgumentError, "state must be a State, String or Numeric, but was #{state.class}"
+          end
+        end
       end
     end
   end

data/lib/openhab/core.rb

@@ -15,9 +15,10 @@ module OpenHAB
     V4_2 = Gem::Version.new("4.2.0").freeze
 
     # @return [Gem::Version] Returns the current openHAB version as a Gem::Version object
+    #   Note, this strips off snapshots, milestones and RC versions and returns the release version.
     # @!visibility private
     def self.version
-      @version ||= Gem::Version.new(VERSION).freeze
+      @version ||= Gem::Version.new(VERSION).release.freeze
     end
 
     raise "`openhab-scripting` requires openHAB >= 3.4.0" unless version >= Gem::Version.new("3.4.0")

data/lib/openhab/dsl/items/timed_command.rb

@@ -64,6 +64,29 @@ module OpenHAB
           def cancelled?
             resolution == :cancelled
           end
+
+          #
+          # Reschedule the timed command.
+          #
+          # If the timed command was cancelled, this will also resume it.
+          #
+          # @param [java.time.temporal.TemporalAmount, #to_zoned_date_time, Proc, nil] time
+          #   When to reschedule the timer for. If unspecified, the original time is used.
+          # @return [void]
+          #
+          def reschedule(time = nil)
+            self.resolution = nil
+            timer.reschedule(time)
+          end
+
+          #
+          # Resume a cancelled timed command to its original expiration time.
+          #
+          # @return [void]
+          #
+          def resume
+            self.resolution = nil
+          end
         end
 
         @timed_commands = java.util.concurrent.ConcurrentHashMap.new
@@ -82,7 +105,13 @@ module OpenHAB
         #
         # @note If a block is provided, and the timer is canceled because the
         #   item changed state while it was waiting, the block will still be
-        #   executed. Be sure to check {TimedCommandDetails#expired? #expired?}
+        #   executed. The timed command can be reinstated by calling {TimedCommandDetails#resume #resume} or
+        #   {TimedCommandDetails#reschedule #reschedule}.
+        #
+        #   If the timer expired, the timed command can be rescheduled from inside the block by calling
+        #   {TimedCommandDetails#reschedule #reschedule}.
+        #
+        #   Be sure to check {TimedCommandDetails#expired? #expired?}
         #   and/or {TimedCommandDetails#cancelled? #cancelled?} to determine why
         #   the block was called.
         #
@@ -181,25 +210,30 @@ module OpenHAB
         end
 
         # Creates the timer to handle changing the item state when timer expires or invoking user supplied block
-        # @param [TimedCommandDetailes] timed_command_details details about the timed command
+        # @param [TimedCommandDetails] timed_command_details details about the timed command
         # @return [Timer] Timer
         def timed_command_timer(timed_command_details, duration)
           DSL.after(duration) do
             timed_command_details.mutex.synchronize do
               logger.trace "Timed command expired - #{timed_command_details}"
-              DSL.rules.remove(timed_command_details.rule_uid)
               timed_command_details.resolution = :expired
               case timed_command_details.on_expire
               when Proc
                 logger.trace "Invoking block #{timed_command_details.on_expire} after timed command for #{name} expired"
                 timed_command_details.on_expire.call(timed_command_details)
+                if timed_command_details.resolution.nil?
+                  logger.trace { "Block rescheduled the timer to #{timed_command_details.timer.execution_time}" }
+                end
               when Core::Types::UnDefType
                 update(timed_command_details.on_expire)
               else
                 command(timed_command_details.on_expire)
               end
+              if timed_command_details.resolution
+                DSL.rules.remove(timed_command_details.rule_uid)
+                TimedCommand.timed_commands.delete(timed_command_details.item)
+              end
             end
-            TimedCommand.timed_commands.delete(timed_command_details.item)
           end
         end
 
@@ -250,17 +284,26 @@ module OpenHAB
           def execute(_mod = nil, inputs = nil)
             ThreadLocal.thread_local(**@thread_locals) do
               @timed_command_details.mutex.synchronize do
-                logger.trace "Canceling implicit timer #{@timed_command_details.timer} for " \
-                             "#{@timed_command_details.item.name}  because received event #{inputs}"
+                logger.trace do
+                  "Canceling implicit timer #{@timed_command_details.timer} for " \
+                    "#{@timed_command_details.item.name} because of received event #{inputs}"
+                end
+                original_execution_time = @timed_command_details.timer.execution_time
                 @timed_command_details.timer.cancel
-                DSL.rules.remove(@timed_command_details.rule_uid)
+                DSL.rules[@timed_command_details.rule_uid].disable
                 @timed_command_details.resolution = :cancelled
                 if @timed_command_details.on_expire.is_a?(Proc)
                   logger.trace "Executing user supplied block on timed command cancelation"
                   @timed_command_details.on_expire.call(@timed_command_details)
                 end
+                if @timed_command_details.resolution
+                  DSL.rules.remove(@timed_command_details.rule_uid)
+                  TimedCommand.timed_commands.delete(@timed_command_details.item)
+                else
+                  DSL.rules[@timed_command_details.rule_uid].enable
+                  @timed_command_details.timer.reschedule(original_execution_time)
+                end
               end
-              TimedCommand.timed_commands.delete(@timed_command_details.item)
             rescue Exception => e
               raise if defined?(::RSpec)
 

data/lib/openhab/dsl/rules/builder.rb

@@ -1278,6 +1278,8 @@ module OpenHAB
         #
         # The `event` passed to run blocks will be a {Core::Events::TimerEvent}.
         #
+        # For a more complex schedule, use {cron}.
+        #
         # @param [String,
         #   Duration,
         #   java.time.MonthDay,
@@ -1294,8 +1296,8 @@ module OpenHAB
         #   :thursday,
         #   :friday,
         #   :saturday,
-        #   :sunday] value
-        #   When to execute rule.
+        #   :sunday] values
+        #   When to execute rule. Multiple day-of-week can be specified. Otherwise, only one value is allowed.
         # @param [LocalTime, String, Core::Items::DateTimeItem, nil] at What time of day to execute rule
         #   If `value` is `:day`, `at` can be a {Core::Items::DateTimeItem DateTimeItem}, and
         #   the trigger will run every day at the (time only portion of) current state of the
@@ -1304,6 +1306,7 @@ module OpenHAB
         # @return [void]
         #
         # @see at
+        # @see cron
         #
         # @example
         #   rule "Daily" do
@@ -1363,15 +1366,38 @@ module OpenHAB
         #     run { logger.info "Happy Valentine's Day!" }
         #   end
         #
-        def every(value, at: nil, attach: nil)
-          return every(java.time.MonthDay.parse(value), at: at, attach: attach) if value.is_a?(String)
+        # @example Multiple day-of-week
+        #   rule "Weekend" do
+        #     every :saturday, :sunday, at: "10:00"
+        #     run { logger.info "It's the weekend!" }
+        #   end
+        #
+        def every(*values, at: nil, attach: nil)
+          raise ArgumentError, "Missing values" if values.empty?
+
+          if Cron.all_dow_symbols?(values)
+            @ruby_triggers << [:every, values.join(", "), { at: at }]
+            return cron(Cron.from_dow_symbols(values, at), attach: attach)
+          end
+
+          if values.size != 1
+            raise ArgumentError,
+                  "Multiple values are only allowed for day-of-week. " \
+                  "Otherwise only one value is allowed, given: #{values.size}"
+          end
+
+          value = values.first
+          value = java.time.MonthDay.parse(value.to_str) if value.respond_to?(:to_str)
 
           @ruby_triggers << [:every, value, { at: at }]
 
           if value == :day && at.is_a?(Item)
-            raise ArgumentError, "Attachments are not supported with dynamic datetime triggers" unless attach.nil?
+            # @!deprecated OH 3.4 - attachments are supported in OH 4.0+
+            if Core.version <= Core::V4_0 && !attach.nil?
+              raise ArgumentError, "Attachments are not supported with dynamic datetime triggers in openHAB 3.x"
+            end
 
-            return trigger("timer.DateTimeTrigger", itemName: at.name, timeOnly: true)
+            return trigger("timer.DateTimeTrigger", itemName: at.name, timeOnly: true, attach: attach)
           end
 
           cron_expression = case value

data/lib/openhab/dsl/rules/triggers/cron/cron.rb

@@ -50,8 +50,13 @@ module OpenHAB
           }.freeze
           private_constant :DAY_OF_WEEK_MAP
 
+          DAY_OF_WEEK = DAY_OF_WEEK_MAP.keys.freeze
+          private_constant :DAY_OF_WEEK
+
           # @return [Hash] Converts the DAY_OF_WEEK_MAP to map used by Cron Expression
-          DAY_OF_WEEK_EXPRESSION_MAP = DAY_OF_WEEK_MAP.transform_values { |v| CRON_EXPRESSION_MAP.merge(dow: v) }
+          DAY_OF_WEEK_EXPRESSION_MAP = DAY_OF_WEEK_MAP.transform_values do |v|
+            CRON_EXPRESSION_MAP.merge(second: 0, minute: 0, hour: 0, dow: v)
+          end.freeze
           private_constant :DAY_OF_WEEK_EXPRESSION_MAP
 
           # @return [Hash] Create a set of cron expressions based on different time intervals
@@ -76,7 +81,7 @@ module OpenHAB
           # @param [Duration] duration
           # @param [Object] at LocalTime or String representing time of day
           #
-          # @return [Hash] map describing cron expression
+          # @return [String] cron expression
           #
           def self.from_duration(duration, at)
             raise ArgumentError, '"at" cannot be used with duration' if at
@@ -90,7 +95,7 @@ module OpenHAB
           # @param [MonthDay] monthday a {MonthDay} object
           # @param [Object] at LocalTime or String representing time of day
           #
-          # @return [Hash] map describing cron expression
+          # @return [String] cron expression
           #
           def self.from_monthday(monthday, at)
             expression_map = EXPRESSION_MAP[:day].merge(month: monthday.month_value, dom: monthday.day_of_month)
@@ -104,7 +109,7 @@ module OpenHAB
           # @param [Symbol] symbol
           # @param [Object] at LocalTime or String representing time of day
           #
-          # @return [Hash] map describing cron expression created from symbol
+          # @return [String] cron expression created from symbol
           #
           def self.from_symbol(symbol, at)
             expression_map = EXPRESSION_MAP[symbol]
@@ -112,12 +117,38 @@ module OpenHAB
             map_to_cron(expression_map)
           end
 
+          #
+          # Checks if all symbols are day-of-week symbols
+          #
+          # @param [Array<Symbol>] symbols
+          #
+          # @return [Boolean] true if all symbols are day-of-week symbols
+          #
+          def self.all_dow_symbols?(symbols)
+            (symbols & DAY_OF_WEEK) == symbols
+          end
+
+          #
+          # Create a cron map from a list of day-of-week symbols
+          #
+          # @param [Symbol] symbols
+          # @param [Object] at LocalTime or String representing time of day
+          #
+          # @return [String] cron expression created from symbols
+          #
+          def self.from_dow_symbols(symbols, at)
+            dow = DAY_OF_WEEK_MAP.fetch_values(*symbols).join(",")
+            expression_map = CRON_EXPRESSION_MAP.merge(dow: dow, hour: 0, minute: 0, second: 0)
+            expression_map = at_condition(expression_map, at) if at
+            map_to_cron(expression_map)
+          end
+
           #
           # Create a cron map from cron elements
           #
           # @param [Hash] fields Cron fields (second, minute, hour, dom, month, dow, year)
           #
-          # @return [Hash] map describing cron expression
+          # @return [String] cron expression
           #
           def self.from_fields(fields)
             extra_fields = fields.keys - CRON_EXPRESSION_MAP.keys
@@ -190,17 +221,14 @@ module OpenHAB
           #
           # If an at time is provided, parse that and merge the new fields into the expression.
           #
-          # @param [<Type>] expression_map <description>
-          # @param [<Type>] at_time <description>
+          # @param [Hash] expression_map
+          # @param [LocalTime,String] at_time
           #
-          # @return [<Type>] <description>
+          # @return [Hash] expression map with at time merged in
           #
           def self.at_condition(expression_map, at_time)
-            if at_time
-              tod = at_time.is_a?(LocalTime) ? at_time : LocalTime.parse(at_time)
-              expression_map = expression_map.merge(hour: tod.hour, minute: tod.minute, second: tod.second)
-            end
-            expression_map
+            tod = at_time.is_a?(LocalTime) ? at_time : LocalTime.parse(at_time)
+            expression_map.merge(hour: tod.hour, minute: tod.minute, second: tod.second)
           end
 
           #

data/lib/openhab/dsl/sitemaps/builder.rb

@@ -9,7 +9,32 @@ module OpenHAB
       # @!visibility private
       org.openhab.core.model.sitemap.sitemap.impl.SitemapImpl.alias_method :uid, :name
 
-      # Base sitemap builder DSL
+      #
+      # A sitemap builder allows you to dynamically create openHAB sitemaps at runtime.
+      #
+      # @example
+      #   sitemaps.build do
+      #     sitemap "demo", label: "My home automation" do
+      #       frame label: "Date" do
+      #         text item: Date
+      #       end
+      #       frame label: "Demo" do
+      #         switch item: Lights, icon: "light"
+      #         text item: LR_Temperature, label: "Livingroom [%.1f °C]"
+      #         group item: Heating
+      #         text item: LR_Multimedia_Summary, label: "Multimedia [%s]", static_icon: "video" do
+      #           selection item: LR_TV_Channel,
+      #                     mappings: { 0 => "off", 1 => "DasErste", 2 => "BBC One", 3 => "Cartoon Network" }
+      #           slider item: LR_TV_Volume
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @see https://www.openhab.org/docs/ui/sitemaps.html
+      # @see OpenHAB::DSL.sitemaps
+      # @see OpenHAB::Core::Sitemaps::Provider#build sitemaps.build
+      #
       class Builder
         # @!visibility private
         def initialize(provider, builder_proxy, update:)
@@ -698,88 +723,92 @@ module OpenHAB
         end
       end
 
-      # Builds a `Buttongrid` element
-      # @since openHAB 4.1
-      # @see https://www.openhab.org/docs/ui/sitemaps.html#element-type-buttongrid
-      # @see org.openhab.core.model.sitemap.sitemap.Buttongrid
-      class ButtongridBuilder < WidgetBuilder
-        # @return [Array<Array<int, int, Command, String, String>>]
-        #   An array of buttons to display
-        attr_reader :buttons
+      # Builds a `Button` element
+      #
+      # This element can only exist within a `Buttongrid` element.
+      #
+      # @since openHAB 4.2
+      # @see https://www.openhab.org/docs/ui/sitemaps.html#element-type-button
+      # @see org.openhab.core.model.sitemap.sitemap.Button
+      class ButtonBuilder < WidgetBuilder
+        # The row in which the button is placed
+        # @return [Integer]
+        attr_accessor :row
+
+        # The column in which the button is placed
+        # @return [Integer]
+        attr_accessor :column
+
+        # The command to send when the button is pressed
+        # @return [String, Command]
+        attr_accessor :click
+
+        # The command to send when the button is released
+        # @return [String, Command, nil]
+        attr_accessor :release
+
+        # Whether the button is stateless
+        # @return [true, false, nil]
+        attr_writer :stateless
 
         # (see WidgetBuilder#initialize)
-        # @!method initialize(item: nil, label: nil, icon: nil, static_icon: nil, buttons: nil, label_color: nil, value_color: nil, icon_color: nil, visibility: nil)
-        # @param [Array<Array<int, int, Command, String, String>>] buttons An array of buttons to display.
-        #   Each element is an array with the following elements:
-        #   - row: 1-12
-        #   - column: 1-12
-        #   - command: The command to send when the button is pressed
-        #   - label: The label to display on the button
-        #   - icon: The icon to display on the button (optional)
-        #
-        # @example
-        #   # This creates a buttongrid to emulate a TV remote control
-        #   sitemaps.build do
-        #     sitemap "remote", label: "TV Remote Control" do
-        #       buttongrid item: LivingRoom_TV_RCButton, buttons: [
-        #         [1, 1, "BACK", "Back", "f7:return"],
-        #         [1, 2, "HOME", "Menu", "material:apps"],
-        #         [1, 3, "YELLOW", "Search", "f7:search"],
-        #         [2, 2, "UP", "Up", "f7:arrowtriangle_up"],
-        #         [4, 2, "DOWN", "Down", "f7:arrowtriangle_down"],
-        #         [3, 1, "LEFT", "Left", "f7:arrowtriangle_left"],
-        #         [3, 3, "RIGHT", "Right", "f7:arrowtriangle_right"],
-        #         [3, 2, "ENTER", "Enter", "material:adjust"]
-        #       ]
-        #     end
-        #   end
+        # @!method initialize(item: nil, label: nil, icon: nil, static_icon: nil, row:, column:, click:, release: nil, stateless: nil, label_color: nil, value_color: nil, icon_color: nil, visibility: nil)
+        # @param [Integer] row
+        #   The row in which the button is placed (see {ButtonBuilder#row})
+        # @param [Integer] column
+        #   The column in which the button is placed (see {ButtonBuilder#column})
+        # @param [String, Command] click
+        #   The command to send when the button is pressed (see {ButtonBuilder#click})
+        # @param [String, Command, nil] release
+        #   The command to send when the button is released (see {ButtonBuilder#release})
+        # @param [true, false, nil] stateless
+        #   Whether the button is stateless (see {ButtonBuilder#stateless=})
         #
-        # @see https://www.openhab.org/docs/ui/sitemaps.html#element-type-buttongrid
         # @!visibility private
-        def initialize(type, builder_proxy, buttons: [], **kwargs, &block)
-          @buttons = buttons
-          super(type, builder_proxy, **kwargs, &block)
-          buttons.each { |button| validate_button(button) }
+        def initialize(builder_proxy,
+                       row:,
+                       column:,
+                       click:,
+                       release: nil,
+                       stateless: nil,
+                       **kwargs,
+                       &block)
+
+          super(:button, builder_proxy, **kwargs, &block)
+
+          @row = row
+          @column = column
+          @click = click
+          @release = release
+          @stateless = stateless
         end
 
-        #
-        # Adds a button to the buttongrid
-        #
-        # @param [Array<int, int, Command, String, String>] button the button to add
-        # @return [Array<Array<int, int, Command, String, String>>] the current buttons
-        #
-        def button(button)
-          validate_button(button)
-          @buttons << button
+        # (see #stateless=)
+        def stateless?
+          @stateless
         end
 
         # @!visibility private
         def build
-          widget = super
-          buttons.each do |button|
-            button_object = if SitemapBuilder.factory.respond_to?(:create_button_definition)
-                              SitemapBuilder.factory.create_button_definition
-                            else
-                              # @deprecated OH 4.1 in OH 4.2 this clause is not needed
-                              SitemapBuilder.factory.create_button
-                            end
-            button_object.row = button[0]
-            button_object.column = button[1]
-            button_object.cmd = button[2]
-            button_object.label = button[3]
-            button_object.icon = button[4] if button[4]
-            widget.buttons.add(button_object)
+          if Core.version >= Core::V4_2
+            super.tap do |widget|
+              widget.row = row
+              widget.column = column
+              widget.cmd = click.to_s
+              widget.release_cmd = release.to_s unless release.nil?
+              widget.stateless = stateless? unless @stateless.nil?
+            end
+          else
+            # @deprecated OH 4.1
+            # in OH 4.1, the button is a property of the Buttongrid, not a widget
+            SitemapBuilder.factory.create_button.tap do |button|
+              button.row = row
+              button.column = column
+              button.cmd = click.to_s
+              button.label = label
+              button.icon = icon if icon
+            end
           end
-
-          widget
-        end
-
-        private
-
-        def validate_button(button)
-          return if (4..5).cover?(button.size)
-
-          raise ArgumentError, "Invalid button: '#{button.inspect}'. It must be an array with (4..5) elements"
         end
       end
 
@@ -1169,6 +1198,209 @@ module OpenHAB
       class FrameBuilder < LinkableWidgetBuilder
       end
 
+      # Builds a `Buttongrid` element
+      # @since openHAB 4.1
+      # @see https://www.openhab.org/docs/ui/sitemaps.html#element-type-buttongrid
+      # @see org.openhab.core.model.sitemap.sitemap.Buttongrid
+      class ButtongridBuilder < LinkableWidgetBuilder
+        REQUIRED_BUTTON_ARGS = %i[row column click].freeze
+        private_constant :REQUIRED_BUTTON_ARGS
+
+        # @!deprecated OH 4.1 in OH 4.1, Buttongrid is not a LinkableWidget.
+        # Pretend that the buttons property is its children so we can add to it in LinkableWidgetBuilder#build
+        if (Core::V4_1...Core::V4_2).cover?(Core.version)
+          java_import org.openhab.core.model.sitemap.sitemap.Buttongrid
+          module Buttongrid
+            def children
+              buttons
+            end
+          end
+        end
+
+        # (see WidgetBuilder#initialize)
+        # @!method initialize(item: nil, label: nil, icon: nil, static_icon: nil, buttons: nil, label_color: nil, value_color: nil, icon_color: nil, visibility: nil)
+        # @param [Array<Array<int, int, Command, String, String>>] buttons An array of buttons to display.
+        #   Each element can be a hash with keyword arguments (see {Sitemaps::ButtongridBuilder#button}),
+        #   or an array with the following elements:
+        #   - row: 1-12
+        #   - column: 1-12
+        #   - click: The command to send when the button is pressed
+        #   - label: The label to display on the button (optional)
+        #   - icon: The icon to display on the button (optional)
+        #
+        # @example Create a buttongrid with buttons as an argument
+        #   # This creates a buttongrid to emulate a TV remote control
+        #   sitemaps.build do
+        #     sitemap "remote", label: "TV Remote Control" do
+        #       buttongrid item: LivingRoom_TV_RCButton, buttons: [
+        #         [1, 1, "BACK", "Back", "f7:return"],
+        #         [1, 2, "HOME", "Menu", "material:apps"],
+        #         [1, 3, "YELLOW", "Search", "f7:search"],
+        #         [2, 2, "UP", "Up", "f7:arrowtriangle_up"],
+        #         [4, 2, "DOWN", "Down", "f7:arrowtriangle_down"],
+        #         [3, 1, "LEFT", "Left", "f7:arrowtriangle_left"],
+        #         [3, 3, "RIGHT", "Right", "f7:arrowtriangle_right"],
+        #
+        #         # Using keyword arguments:
+        #         {row: 3, column: 2, click: "ENTER", label: "Enter", icon: "material:adjust" }
+        #       ]
+        #     end
+        #   end
+        #
+        # @example Create a buttongrid with button widgets
+        #   sitemaps.build do
+        #     sitemap "remote", label: "TV Remote Control" do
+        #       buttongrid item: LivingRoom_TV_RCButton do
+        #         button 1, 1, click: "BACK", icon: "f7:return"
+        #         button 1, 2, click: "HOME", icon: "material:apps"
+        #         button 1, 3, click: "YELLOW", icon: "f7:search"
+        #         button 2, 2, click: "UP", icon: "f7:arrowtriangle_up"
+        #         button 4, 2, click: "DOWN", icon: "f7:arrowtriangle_down"
+        #         button 3, 1, click: "LEFT", icon: "f7:arrowtriangle_left"
+        #         button 3, 3, click: "RIGHT", icon: "f7:arrowtriangle_right"
+        #         button 3, 2, click: "ENTER", icon: "material:adjust"
+        #       end
+        #
+        #       # The following buttons use widget features introduced in openHAB 4.2+
+        #       buttongrid item: LivingRoom_Curtain do
+        #         button 1, 1, click: "up", release: "stop", icon: "f7:arrowtriangle_up"
+        #         button 2, 1, click: "down", release: "stop", icon: "f7:arrowtriangle_up"
+        #       end
+        #     end
+        #   end
+        #
+        # @see https://www.openhab.org/docs/ui/sitemaps.html#element-type-buttongrid
+        # @!visibility private
+        def initialize(type, builder_proxy, buttons: [], **kwargs, &block)
+          super(type, builder_proxy, **kwargs, &block)
+
+          # Put the buttons given in the constructor before those added in the block
+          # We can't do this before calling the super constructor because `children` is initialized there
+          children.slice!(0..).then do |buttons_from_block|
+            buttons.each do |b|
+              if b.is_a?(Array)
+                button(*b)
+              else
+                button(**b)
+              end
+            end
+            children.concat(buttons_from_block)
+          end
+        end
+
+        #
+        # @!method button(row = nil, column = nil, click = nil, label = nil, icon = nil, item: nil, label: nil, icon: nil, static_icon: nil, row:, column:, click:, release: nil, stateless: nil, label_color: nil, value_color: nil, icon_color: nil, visibility: nil)
+        # Adds a button inside the buttongrid
+        #
+        # - In openHAB 4.1, buttons are direct properties of the buttongrid.
+        #   Only `row`, `column`, `click`, `label` (optional), and `icon` (optional) are used.
+        #   All the other parameters are ignored.
+        #   All the buttons will send commands to the same item assigned to the buttongrid.
+        #
+        # - In openHAB 4.2+, buttons are widgets within the containing buttongrid, and they
+        #   support all the parameters listed in the method signature such as
+        #   `release`, `label_color`, `visibility`, etc.
+        #   Each Button element has an item associated with that button.
+        #   When an item is not specified for the button, it will default to the containing buttongrid's item.
+        #
+        # This method supports positional arguments and/or keyword arguments.
+        # Their use can be mixed, however, the keyword arguments will override the positional arguments
+        # when both are specified.
+        #
+        # @param (see ButtonBuilder#initialize)
+        # @return [ButtonBuilder]
+        #
+        # @example Adding buttons to a buttongrid with positional arguments
+        #   sitemaps.build do
+        #     sitemap "remote" do
+        #       buttongrid item: RCButton do
+        #         button 1, 1, "BACK", "Back", "f7:return"
+        #         button 1, 2, "HOME", "Menu", "material:apps"
+        #         button 1, 3, "YELLOW", "Search", "f7:search"
+        #         button 2, 2, "UP", "Up", "f7:arrowtriangle_up"
+        #         button 4, 2, "DOWN", "Down", "f7:arrowtriangle_down"
+        #         button 3, 1, "LEFT", "Left", "f7:arrowtriangle_left"
+        #         button 3, 3, "RIGHT", "Right", "f7:arrowtriangle_right"
+        #         button 3, 2, "ENTER", "Enter", "material:adjust"
+        #       end
+        #     end
+        #   end
+        #
+        # @example Adding buttons to a buttongrid with keyword arguments
+        #   sitemaps.build do
+        #     sitemap "remote" do
+        #       buttongrid item: RCButton do
+        #         # These buttons will use the default item assigned to the buttongrid (RCButton)
+        #         button row: 1, column: 1, click: "BACK", icon: "f7:return"
+        #         button row: 1, column: 2, click: "HOME", icon: "material:apps"
+        #         button row: 1, column: 3, click: "YELLOW", icon: "f7:search"
+        #         button row: 2, column: 2, click: "UP", icon: "f7:arrowtriangle_up"
+        #         button row: 4, column: 2, click: "DOWN", icon: "f7:arrowtriangle_down"
+        #         button row: 3, column: 1, click: "LEFT", icon: "f7:arrowtriangle_left"
+        #         button row: 3, column: 3, click: "RIGHT", icon: "f7:arrowtriangle_right"
+        #         button row: 3, column: 2, click: "ENTER", icon: "material:adjust"
+        #       end
+        #     end
+        #   end
+        #
+        # @example Mixing positional and keyword arguments
+        #   sitemaps.build do
+        #     sitemap "remote" do
+        #       buttongrid item: RCButton do
+        #         button 1, 1, click: "BACK", icon: "f7:return"
+        #         button 1, 2, click: "HOME", icon: "material:apps"
+        #         button 1, 3, click: "YELLOW", icon: "f7:search"
+        #         button 2, 2, click: "UP", icon: "f7:arrowtriangle_up"
+        #         button 4, 2, click: "DOWN", icon: "f7:arrowtriangle_down"
+        #         button 3, 1, click: "LEFT", icon: "f7:arrowtriangle_left"
+        #         button 3, 3, click: "RIGHT", icon: "f7:arrowtriangle_right"
+        #         button 3, 2, click: "ENTER", icon: "material:adjust"
+        #       end
+        #     end
+        #   end
+        #
+        # @example openHAB 4.2+ supports assigning different items to buttons, along with additional features
+        #   sitemaps.build do
+        #     sitemap "remote" do
+        #       buttongrid item: RCButton do
+        #         button 1, 1, click: "BACK", icon: "f7:return"
+        #         button 1, 2, click: "HOME", icon: "material:apps"
+        #         button 1, 3, click: "YELLOW", icon: "f7:search", icon_color: "yellow"
+        #         button 2, 2, click: "UP", icon: "f7:arrowtriangle_up"
+        #         button 4, 2, click: "DOWN", icon: "f7:arrowtriangle_down"
+        #         button 3, 1, click: "LEFT", icon: "f7:arrowtriangle_left"
+        #         button 3, 3, click: "RIGHT", icon: "f7:arrowtriangle_right"
+        #         button 3, 2, click: "ENTER", icon: "material:adjust", icon_color: "red"
+        #
+        #         # These buttons will use the specified item, only supported in openHAB 4.2+
+        #         button 4, 3, click: ON, static_icon: "switch-off", visibility: "TVPower!=ON", item: TVPower
+        #         button 4, 3, click: OFF, static_icon: "switch-on", visibility: "TVPower==ON", item: TVPower
+        #       end
+        #     end
+        #   end
+        #
+        def button(row = nil, column = nil, click = nil, label = nil, icon = nil, **kwargs, &block)
+          args = [row, column, click, label, icon].compact
+
+          args = args.first if args.first.is_a?(Array)
+          kwargs = %i[row column click label icon].zip(args).to_h.compact.merge(kwargs)
+
+          missing_args = (REQUIRED_BUTTON_ARGS - kwargs.keys).compact
+          unless missing_args.empty?
+            args = kwargs.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+            missing_args = missing_args.map(&:to_s).join(", ")
+            raise ArgumentError, "button(#{args}) missing required parameters: #{missing_args}"
+          end
+
+          kwargs[:item] ||= item if item # default to the buttongrid's item
+          kwargs[:label] ||= kwargs[:click].to_s
+
+          ButtonBuilder.new(@builder_proxy, **kwargs, &block).tap do |b|
+            children << b
+          end
+        end
+      end
+
       # Builds a `Sitemap`
       # @see https://www.openhab.org/docs/ui/sitemaps.html
       # @see org.openhab.core.model.sitemap.sitemap.Sitemap

data/lib/openhab/dsl/version.rb

@@ -4,6 +4,6 @@ module OpenHAB
   module DSL
     # Version of openHAB helper libraries
     # @return [String]
-    VERSION = "5.22.0"
+    VERSION = "5.23.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.22.0
+  version: 5.23.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-07-05 00:00:00.000000000 Z
+date: 2024-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -490,7 +490,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.14
+rubygems_version: 3.5.16
 signing_key: 
 specification_version: 4
 summary: JRuby Helper Libraries for openHAB Scripting