openhab-scripting 5.11.0 → 5.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e7d078cc73659d0f435950d36438b67759b2e3b5c0abf80f258a36101792a0d
-  data.tar.gz: 2a76c20015d6320b64a2a9ea79557c7133b1101a8514fabba9241f91b455615d
+  metadata.gz: 0d3cc7138b6a4b42066a80ec926d31c2b6f1dc9538ae4498d1b6014be8d8aa1d
+  data.tar.gz: eae0f6ddcde8c3a2b8b6b747554e73dc3b86b63f599f9afe2e50676e4cc8c4f8
 SHA512:
-  metadata.gz: bc54b1fae7be3bee15b1af2c27526cf942a13741404dd1c0e61034b82d2d472703bfb48ef921d25ed608dbe3d9c964abbded85ab1d3adfd855847229c6bf2447
-  data.tar.gz: c454623c911c90be03464391f885b8ccebfd2789b5e9dbbe32a6f8309fdf7e1f948e2c0730373d383bf7892271ab752bf9d8c2197ed541cff7f33a692ea296ec
+  metadata.gz: 5fb2a8142e739424fabd68595923588066edc753f62467c6cd1e4b3ab38b9d2b1717d7d24dbfcd96533000fa1adcef1e8470790167d7b5f031dc24ce34c25f82
+  data.tar.gz: 5ea1f6bd0c4926ae9126f388af80c2d69bd643f14495226cad3388150b971080705bea645e52b76308a7c96a48026c5be02ae6ba6408973eba73d22b6bee3626

data/lib/openhab/core/events/channel_triggered_event.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.thing.events.ChannelTriggeredEvent
+
+      #
+      # {AbstractEvent} sent when a channel triggers.
+      #
+      class ChannelTriggeredEvent < AbstractEvent
+        extend Forwardable
+
+        # @!attribute [r] channel_uid
+        # @return [Things::ChannelUID] The UID of the {Things::Channel Channel} that triggered this event.
+        alias_method :channel_uid, :get_channel
+
+        # @!attribute [r] channel
+        # @return [Things::Channel, nil] The channel that triggered this event.
+
+        # @!attribute [r] thing
+        # @return [Things::Thing, nil] The thing that triggered this event.
+        def_delegators :channel_uid, :thing, :channel
+
+        # @!attribute [r] event
+        # @return [String] The event data
+      end
+    end
+  end
+end

data/lib/openhab/core/events/item_state_updated_event.rb

@@ -5,17 +5,18 @@ require_relative "item_state_event"
 module OpenHAB
   module Core
     module Events
-      begin
+      # @deprecated OH3.4 if guard only needed in OH 3.4
+      if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
         java_import org.openhab.core.items.events.ItemStateUpdatedEvent
 
         #
         # {AbstractEvent} sent when an item's state has updated.
         #
+        # @since openHAB 4.0
+        #
         class ItemStateUpdatedEvent < ItemEvent
           include ItemState
         end
-      rescue NameError
-        # @deprecated OH3.4 OH3 will raise an error ItemStateUpdatedEvent is only in OH4
       end
     end
   end

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

@@ -102,7 +102,7 @@ module OpenHAB
         #
         def dim(amount = 1)
           target = [state&.-(amount), 0].compact.max
-          command(target)
+          command!(target)
           target
         end
 
@@ -121,7 +121,7 @@ module OpenHAB
         #
         def brighten(amount = 1)
           target = [state&.+(amount), 100].compact.min
-          command(target)
+          command!(target)
           target
         end
 
@@ -133,16 +133,6 @@ module OpenHAB
         #   Send the {DECREASE} command to the item
         #   @return [DimmerItem] `self`
 
-        # @!method increase!
-        #   Send the {INCREASE} command to the item, even when
-        #     {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [DimmerItem] `self`
-
-        # @!method decrease!
-        #   Send the {DECREASE} command to the item, even when
-        #     {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [DimmerItem] `self`
-
         # raw numbers translate directly to PercentType, not a DecimalType
         # @!visibility private
         def format_type(command)

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

@@ -55,7 +55,7 @@ module OpenHAB
         #   Send the {REWIND} command to the item
         #   @return [PlayerItem] `self`
 
-        # @!method rewind
+        # @!method rewind!
         #   Send the {REWIND} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
         #   @return [PlayerItem] `self`
 
@@ -72,18 +72,9 @@ module OpenHAB
         #   Send the {NEXT} command to the item
         #   @return [PlayerItem] `self`
 
-        # @!method next!
-        #   Send the {NEXT} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [PlayerItem] `self`
-
         # @!method previous
         #   Send the {PREVIOUS} command to the item
         #   @return [PlayerItem] `self`
-
-        # @!method previous!
-        #   Send the {PREVIOUS} command to the item, even when
-        #     {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [PlayerItem] `self`
       end
     end
   end

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

@@ -57,18 +57,10 @@ module OpenHAB
         #   Send the {STOP} command to the item
         #   @return [RollershutterItem] `self`
 
-        # @!method stop!
-        #   Send the {STOP} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [RollershutterItem] `self`
-
         # @!method move
         #   Send the {MOVE} command to the item
         #   @return [RollershutterItem] `self`
 
-        # @!method move!
-        #   Send the {MOVE} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [RollershutterItem] `self`
-
         # raw numbers translate directly to PercentType, not a DecimalType
         # @!visibility private
         def format_type(command)

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

@@ -50,9 +50,9 @@ module OpenHAB
         # @return [self]
         #
         def toggle
-          return on unless state?
+          return on! unless state?
 
-          command(!state)
+          command!(!state)
         end
 
         # @!method on?

data/lib/openhab/core/items.rb

@@ -60,25 +60,43 @@ module OpenHAB
             command = Types::COMMAND_ALIASES[value.to_s]
             next if klass.instance_methods.include?(command)
 
-            logger.trace("Defining #{klass}##{command} for #{value}")
-            klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              ruby2_keywords def #{command}(*args, &block)  # ruby2_keywords def on(*args, &block)
-                command(#{value}, *args, &block)            #   command(ON, *args, &block)
-              end                                           # end
-              ruby2_keywords def #{command}!(*args, &block) # ruby2_keywords def on!(*args, &block)
-                command!(#{value}, *args, &block)           #   command!(ON, *args, &block)
-              end                                           # end
-            RUBY
+            if value.is_a?(Types::State)
+              logger.trace("Defining #{klass}/Enumerable##{command}/#{command}! for #{value}")
 
-            logger.trace("Defining Enumerable##{command} for #{value}")
-            Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              def #{command}         # def on
-                each(&:#{command})   #   each(&:on)
-              end                    # end
-              def #{command}!        # def on!
-                each(&:#{command}!)  #   each(&:on!)
-              end                    # end
-            RUBY
+              klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                ruby2_keywords def #{command}(*args, &block)   # ruby2_keywords def on(*args, &block)
+                  command(#{value}, *args, &block)             #   command(ON, *args, &block)
+                end                                            # end
+                                                               #
+                ruby2_keywords def #{command}!(*args, &block)  # ruby2_keywords def on!(*args, &block)
+                  command!(#{value}, *args, &block)            #   command!(ON, *args, &block)
+                end                                            # end
+              RUBY
+
+              Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                def #{command}         # def on
+                  each(&:#{command})   #   each(&:on)
+                end                    # end
+                                       #
+                def #{command}!        # def on!
+                  each(&:#{command}!)  #   each(&:on!)
+                end                    # end
+              RUBY
+            else
+              logger.trace("Defining #{klass}/Enumerable##{command} for #{value}")
+
+              klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                ruby2_keywords def #{command}(*args, &block)  # ruby2_keywords def refresh(*args, &block)
+                  command!(#{value}, *args, &block)           #   command!(REFRESH, *args, &block)
+                end                                           # end
+              RUBY
+
+              Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                def #{command}        # def refresh
+                  each(&:#{command})  #   each(&:refresh)
+                end                   # end
+              RUBY
+            end
 
             logger.trace("Defining ItemCommandEvent##{command}? for #{value}")
             Events::ItemCommandEvent.class_eval <<~RUBY, __FILE__, __LINE__ + 1

data/lib/openhab/core/profile_factory.rb

@@ -6,12 +6,14 @@ require_relative "script_handling"
 
 module OpenHAB
   module Core
+    # rubocop:disable Naming/MethodName
     # @!visibility private
     class ProfileFactory
+      include org.openhab.core.config.core.ConfigDescriptionProvider # This needs to be included first
       include org.openhab.core.thing.profiles.ProfileFactory
+      include org.openhab.core.thing.profiles.ProfileTypeProvider
       include Singleton
 
-      # rubocop:disable Naming/MethodName
       class Profile
         include org.openhab.core.thing.profiles.StateProfile
 
@@ -96,10 +98,10 @@ module OpenHAB
         end
       end
       private_constant :Profile
-      # rubocop:enable Naming/MethodName
 
       def initialize
         @profiles = {}
+        @uri_to_uid = {}
 
         @registration = OSGi.register_service(self)
         ScriptHandling.script_unloaded { unregister }
@@ -116,17 +118,56 @@ module OpenHAB
       end
 
       # @!visibility private
-      def register(uid, block)
-        @profiles[uid] = [DSL::ThreadLocal.persist, block]
+      def register(id, block, label: nil, config_description: nil)
+        uid = org.openhab.core.thing.profiles.ProfileTypeUID.new("ruby", id)
+        uri = java.net.URI.new("profile", uid.to_s, nil)
+        if config_description && config_description.uid != uri
+          config_description = org.openhab.core.config.core.ConfigDescriptionBuilder.create(uri)
+                                  .with_parameters(config_description.parameters)
+                                  .with_parameter_groups(config_description.parameter_groups)
+                                  .build
+        end
+
+        @profiles[uid] = {
+          thread_locals: DSL::ThreadLocal.persist,
+          label: label,
+          config_description: config_description,
+          block: block
+        }
+        @uri_to_uid[uri] = uid
       end
 
-      def createProfile(type, callback, context) # rubocop:disable Naming/MethodName
-        @profiles[type].then { |(thread_locals, block)| Profile.new(callback, context, type, thread_locals, block) }
+      # @!visibility private
+      def createProfile(uid, callback, context)
+        profile = @profiles[uid]
+        Profile.new(callback, context, uid, profile[:thread_locals], profile[:block])
       end
 
-      def getSupportedProfileTypeUIDs # rubocop:disable Naming/MethodName
+      # @!visibility private
+      def getSupportedProfileTypeUIDs
         @profiles.keys
       end
+
+      # @!visibility private
+      def getProfileTypes(_locale)
+        @profiles.map do |uid, profile|
+          next if profile[:label].nil?
+
+          org.openhab.core.thing.profiles.ProfileTypeBuilder.new_state(uid, "RUBY #{profile[:label]}").build
+        end.compact
+      end
+
+      # @!visibility private
+      def getConfigDescriptions(_locale)
+        @profiles.values.map { |profile| profile[:config_description] if profile[:label] }.compact
+      end
+
+      # @!visibility private
+      def getConfigDescription(uri, _locale)
+        uid = @uri_to_uid[uri]
+        @profiles.dig(uid, :config_description)
+      end
     end
+    # rubocop:enable Naming/MethodName
   end
 end

data/lib/openhab/core/sitemaps/provider.rb

@@ -70,13 +70,17 @@ module OpenHAB
         #         text label: "Climate", icon: "if:mdi:home-thermometer-outline" do
         #           frame label: "Main Floor" do
         #             text item: MainFloor_AmbTemp
-        #             switch item: MainFloorThermostat_TargetMode, label: "Mode", mappings: %w[off auto cool heat]
+        #             # colors are set with a hash, with key being condition, and value being the color
+        #             switch item: MainFloorThermostat_TargetMode, label: "Mode", mappings: %w[off auto cool heat], label_color: { "==heat" => "red", "" => "black" }
+        #             # an array of conditions are OR'd together
+        #             switch item: MainFloorThermostat_TargetMode, label: "Mode", mappings: %w[off auto cool heat], label_color: { ["==heat", "==cool"], => "green" }
         #             setpoint item: MainFloorThermostat_SetPoint, label: "Set Point", visibility: "MainFloorThermostat_TargetMode!=off"
         #           end
         #           frame label: "Basement" do
         #             text item: Basement_AmbTemp
         #             switch item: BasementThermostat_TargetMode, label: "Mode", mappings: { OFF: "off", COOL: "cool", HEAT: "heat" }
-        #             setpoint item: BasementThermostat_SetPoint, label: "Set Point", visibility: "BasementThermostat_TargetMode!=off"
+        #             # nested arrays are conditions that are AND'd together, instead of OR'd (requires openHAB 4.1)
+        #             setpoint item: BasementThermostat_SetPoint, label: "Set Point", visibility: [["BasementThermostat_TargetMode!=off", "Vacation_Switch!=OFF"]]
         #           end
         #         end
         #       end

data/lib/openhab/core/things/channel_uid.rb

@@ -22,6 +22,16 @@ module OpenHAB
           EntityLookup.lookup_thing(thing_uid)
         end
 
+        # @attribute [r] channel
+        #
+        # Return the channel object for this channel
+        #
+        # @return [Channel, nil]
+        #
+        def channel
+          thing.channels[self]
+        end
+
         #
         # @attribute [r] item
         #

data/lib/openhab/core/things/thing.rb

@@ -72,6 +72,7 @@ module OpenHAB
           # Allows indexing by both integer as an array or channel id acting like a hash.
           # @param [Integer, String, ChannelUID] index
           #   Numeric index, string channel id, or a {ChannelUID} to search for.
+          # @return [Channel, nil]
           def [](index)
             return @thing.get_channel(index) if index.is_a?(ChannelUID)
             return @thing.get_channel(index.to_str) if index.respond_to?(:to_str)

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

@@ -70,7 +70,7 @@ module OpenHAB
         #
         # Convert DecimalType to a QuantityType
         #
-        # @param [String, javax.measure.units.Unit] other
+        # @param [String, javax.measure.Unit] other
         #
         # @return [QuantityType] `self` as a {QuantityType} of the supplied Unit
         #

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

@@ -106,7 +106,7 @@ module OpenHAB
         #   #
         #   # Convert this {QuantityType} into another unit.
         #   #
-        #   # @param [String, javax.measure.units.Unit] unit
+        #   # @param [String, javax.measure.Unit] unit
         #   # @return [QuantityType]
         #   #
         #   # @example
@@ -287,7 +287,7 @@ module OpenHAB
           end
         end
 
-        # if unit is {org.openhab.core.library.unit.Units.ONE}, return a plain
+        # if unit is {org.openhab.core.library.unit.Units::ONE}, return a plain
         # Java BigDecimal
         # @!visibility private
         def deunitize

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Contains the DSL for creating {org.openhab.core.config.core.ConfigDescription} instances.
+    #
+    module ConfigDescription
+      #
+      # A ConfigDescriptionBuilder is used to create a {org.openhab.core.config.core.ConfigDescription}
+      # instance.
+      #
+      # @see DSL.config_description config_description
+      #
+      class Builder
+        def initialize
+          @parameters = []
+          @parameter_groups = []
+          @current_group = nil
+        end
+
+        #
+        # Create a parameter group.
+        #
+        # @param [String, Symbol] name The group name. This name will be referred to by {parameter}.
+        # @param [String, nil] label The group label
+        # @param [String, nil] description The group description
+        # @param [Boolean] advanced Whether the group is advanced
+        # @param [<Type>] context Context for the group
+        #
+        # @yield Block executed in the context of this group. Any {parameter} calls within the block will
+        #   automatically be added to this group, unless it specifies a different group name.
+        #
+        # @return [void]
+        #
+        def group(name, label: nil, description: nil, advanced: false, context: nil, &block)
+          raise ArgumentError, "Groups cannot be nested" if @current_group
+
+          name = name.to_s
+          @parameter_groups << org.openhab.core.config.core.ConfigDescriptionParameterGroupBuilder
+                                  .create(name)
+                                  .with_label(label)
+                                  .with_description(description)
+                                  .with_advanced(advanced)
+                                  .with_context(context)
+                                  .build
+
+          @current_group = name
+          instance_eval(&block) if block
+        ensure
+          @current_group = nil
+        end
+
+        #
+        # Adds a parameter to the config description.
+        #
+        # @param [String, Symbol] name Parameter name
+        # @param [:text, :integer, :decimal, :boolean] type
+        #   Parameter type. See {org.openhab.core.config.core.ConfigDescriptionParameter.Type}
+        # @param [String, nil] label Parameter label
+        # @param [String, nil] description Parameter description
+        # @param [Numeric, nil] min Minimum value for numeric types
+        # @param [Numeric, nil] max Maximum value for numeric types
+        # @param [Numeric, nil] step Step size for numeric types
+        # @param [String, nil] pattern Regular expression pattern for string types
+        # @param [true, false] required Whether the parameter is required
+        # @param [true, false] read_only Whether the parameter is read only
+        # @param [true, false] multiple Whether the parameter is a list of values
+        # @param [String, nil] context Context for the parameter
+        # @param [Object, nil] default Default value for the parameter
+        # @param [Hash] options Options for the parameter
+        # @param [Hash] filter_criteria Filter criteria for the parameter
+        # @param [String, nil] group_name Parameter group name.
+        #   When nil, it will be inferred when this method is called inside a {group} block.
+        # @param [true, false] advanced Whether the parameter is advanced
+        # @param [true, false] limit_to_options Whether the parameter is limited to the given options
+        # @param [Integer, nil] multiple_limit Maximum number of values for a multiple parameter
+        # @param [String, nil] unit Parameter unit
+        # @param [String, nil] unit_label Parameter unit label
+        # @param [true, false] verify Whether the parameter value should be verified
+        #
+        # @return [void]
+        #
+        # @see org.openhab.core.config.core.ConfigDescriptionParameter
+        #
+        def parameter(name,
+                      type,
+                      label: nil,
+                      description: nil,
+                      min: nil,
+                      max: nil,
+                      step: nil,
+                      pattern: nil,
+                      required: false,
+                      read_only: false,
+                      multiple: false,
+                      context: nil,
+                      default: nil,
+                      options: {},
+                      filter_criteria: {},
+                      group_name: nil,
+                      advanced: false,
+                      limit_to_options: false,
+                      multiple_limit: nil,
+                      unit: nil,
+                      unit_label: nil,
+                      verify: false)
+          # Extract the named arguments into a hash
+          @parameters << method(__method__).parameters
+                                           .select { |param_type, _| param_type == :key }
+                                           .to_h { |_, key| [key, binding.local_variable_get(key)] }
+                                           .then do |p|
+            p[:options] = p[:options].map do |opt_value, opt_label|
+              org.openhab.core.config.core.ParameterOption.new(opt_value, opt_label)
+            end
+            p[:filter_criteria] = p[:filter_criteria].map do |filter_name, filter_value|
+              org.openhab.core.config.core.FilterCriteria.new(filter_name, filter_value)
+            end
+            p[:minimum] = p.delete(:min)&.to_d&.to_java
+            p[:maximum] = p.delete(:max)&.to_d&.to_java
+            p[:step] = p.delete(:step)&.to_d&.to_java
+            p[:group_name] ||= @current_group
+            type = org.openhab.core.config.core.ConfigDescriptionParameter::Type.value_of(type.to_s.upcase)
+
+            parameter = org.openhab.core.config.core.ConfigDescriptionParameterBuilder.create(name.to_s, type)
+
+            p.each do |key, value|
+              parameter.send("with_#{key}", value) unless value.nil?
+            end
+            parameter.build
+          end
+        end
+
+        #
+        # Build the config description
+        #
+        # @param [String, java.net.URI] uri The URI for the config description. When nil, it will default to `dummy:uri`
+        # @yield Block executed in the context of this builder. Inside the block, you can call {parameter} and {group}.
+        #
+        # @return [org.openhab.core.config.core.ConfigDescription] The created ConfigDescription object
+        #
+        def build(uri = nil, &block)
+          instance_eval(&block) if block
+          raise ArgumentError, "No parameters defined" if @parameters.empty?
+
+          uri ||= "dummy:uri"
+          uri = java.net.URI.new(uri.to_s) unless uri.is_a?(java.net.URI)
+          org.openhab.core.config.core.ConfigDescriptionBuilder
+             .create(uri)
+             .with_parameters(@parameters)
+             .with_parameter_groups(@parameter_groups)
+             .build
+        end
+      end
+    end
+  end
+end

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

@@ -36,6 +36,8 @@ module OpenHAB
           # sending the command
           %i[command update].each do |ensured_method|
             # def command(state)
+            #   # immediately send the command if it's a command, but not a state (like REFRESH)
+            #   return super(state) if state.is_a?(Command) && !state.is_a?(State)
             #   return super(state) unless Thread.current[:openhab_ensure_states]
             #
             #   formatted_state = format_command(state)
@@ -48,6 +50,8 @@ module OpenHAB
             # end
             class_eval <<~RUBY, __FILE__, __LINE__ + 1 # rubocop:disable Style/DocumentDynamicEvalDefinition
               def #{ensured_method}(state)
+                # immediately send the command if it's a command, but not a state (like REFRESH)
+                #{"return super(state) if state.is_a?(Command) && !state.is_a?(State)" if ensured_method == :command}
                 return super(state) unless Thread.current[:openhab_ensure_states]
 
                 formatted_state = format_#{ensured_method}(state)

data/lib/openhab/dsl/rules/triggers/watch/watch_handler.rb

@@ -46,6 +46,7 @@ module OpenHAB
                 @block = block
                 @subdirs = subdirs
                 @path = Pathname.new(path)
+                @custom_watcher = nil
                 return if path.to_s.start_with?(OpenHAB::Core.config_folder.to_s)
 
                 @custom_watcher = "jrubyscripting-#{SecureRandom.uuid}"

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

@@ -36,12 +36,9 @@ module OpenHAB
       # Base class for all widgets
       # @see org.openhab.core.model.sitemap.sitemap.Widget
       class WidgetBuilder
-        # rubocop:disable Layout/LineLength, Lint/MixedRegexpCaptureTypes
-        # These are copied directly out of UIComponentSitemapProvider.java
-        VISIBILITY_PATTERN = /(?<item>[A-Za-z]\w*)\s*(?<condition>==|!=|<=|>=|<|>)\s*(?<sign>\+|-)?(?<state>\S+)/.freeze
-        COLOR_PATTERN = /((?<item>[A-Za-z]\w*)?\s*((?<condition>==|!=|<=|>=|<|>)\s*(?<sign>\+|-)?(?<state>\S+))?\s*=)?\s*(?<arg>\S+)/.freeze
-        # rubocop:enable Layout/LineLength, Lint/MixedRegexpCaptureTypes
-        private_constant :VISIBILITY_PATTERN, :COLOR_PATTERN
+        # This is copied directly out of UIComponentSitemapProvider.java
+        CONDITION_PATTERN = /(?<item>[A-Za-z]\w*)?\s*(?<condition>==|!=|<=|>=|<|>)?\s*(?<sign>\+|-)?(?<state>.+)/.freeze
+        private_constant :CONDITION_PATTERN
 
         # @return [String, nil]
         attr_accessor :label
@@ -52,15 +49,15 @@ module OpenHAB
         # @see https://www.openhab.org/docs/ui/sitemaps.html#icons
         attr_accessor :icon
         # Label color rules
-        # @return [Array<String>]
+        # @return [Hash<String, String>]
         # @see https://www.openhab.org/docs/ui/sitemaps.html#label-value-and-icon-colors
         attr_reader :label_colors
         # Value color rules
-        # @return [Array<String>]
+        # @return [Hash<String, String>]
         # @see https://www.openhab.org/docs/ui/sitemaps.html#label-value-and-icon-colors
         attr_reader :value_colors
         # Icon color rules
-        # @return [Array<String>]
+        # @return [Hash<String, String>]
         # @see https://www.openhab.org/docs/ui/sitemaps.html#label-value-and-icon-colors
         attr_reader :icon_colors
         # Visibility rules
@@ -94,32 +91,32 @@ module OpenHAB
           @label = label
           @icon = icon
           @visibilities = []
-          @label_colors = []
-          @value_colors = []
-          @icon_colors = []
+          @label_colors = {}
+          @value_colors = {}
+          @icon_colors = {}
 
-          self.label_color(*label_color) if label_color
-          self.value_color(*value_color) if value_color
-          self.icon_color(*icon_color) if icon_color
+          self.label_color(label_color) if label_color
+          self.value_color(value_color) if value_color
+          self.icon_color(icon_color) if icon_color
           self.visibility(*visibility) if visibility
         end
 
         # Adds one or more new rules for setting the label color
-        # @return [Array<String>] the current rules
-        def label_color(*rules)
-          @label_colors.concat(rules)
+        # @return [Hash<String, String>] the current rules
+        def label_color(rules)
+          @label_colors.merge!(rules)
         end
 
         # Adds one or more new rules for setting the value color
-        # @return [Array<String>] the current rules
-        def value_color(*rules)
-          @value_colors.concat(rules)
+        # @return [Hash<String, String>] the current rules
+        def value_color(rules)
+          @value_colors.merge!(rules)
         end
 
         # Adds one or more new rules for setting the icon color
-        # @return [Array<String>] the current rules
-        def icon_color(*rules)
-          @icon_colors.concat(rules)
+        # @return [Hash<String, String>] the current rules
+        def icon_color(rules)
+          @icon_colors.merge!(rules)
         end
 
         # Adds one or more new visibility rules
@@ -137,21 +134,28 @@ module OpenHAB
           widget.label = @label
           widget.icon = @icon
 
-          add_color(widget.label_color, label_colors) unless label_colors.empty?
-          add_color(widget.value_color, value_colors) unless value_colors.empty?
-          add_color(widget.icon_color, icon_colors) unless icon_colors.empty?
+          add_colors(widget, :label_color, label_colors)
+          add_colors(widget, :value_color, value_colors)
+          add_colors(widget, :icon_color, icon_colors)
 
-          visibilities.each do |v|
-            unless (match = VISIBILITY_PATTERN.match(v))
-              raise ArgumentError, "Syntax error in visibility rule #{v.inspect}"
+          # @deprecated OH 4.1
+          if SitemapBuilder.factory.respond_to?(:create_condition)
+            add_conditions(widget, :visibility, visibilities, :create_visibility_rule)
+          else
+            visibilities.each do |v|
+              raise ArgumentError, "AND conditions not supported prior to openHAB 4.1" if v.is_a?(Array)
+
+              unless (match = CONDITION_PATTERN.match(v))
+                raise ArgumentError, "Syntax error in visibility rule #{v.inspect}"
+              end
+
+              rule = SitemapBuilder.factory.create_visibility_rule
+              rule.item = match["item"]
+              rule.condition = match["condition"]
+              rule.sign = match["sign"]
+              rule.state = match["state"]
+              widget.visibility.add(rule)
             end
-
-            rule = SitemapBuilder.factory.create_visibility_rule
-            rule.item = match["item"]
-            rule.condition = match["condition"]
-            rule.sign = match["sign"]
-            rule.state = match["state"]
-            widget.visibility.add(rule)
           end
 
           widget
@@ -169,19 +173,51 @@ module OpenHAB
 
         private
 
-        def add_color(widget_color, colors)
-          colors.each do |c|
-            unless (match = COLOR_PATTERN.match(c))
-              raise ArgumentError, "Syntax error in color rule #{c.inspect}"
+        def add_colors(widget, method, conditions)
+          conditions.each do |condition, color|
+            condition = [condition] unless condition.is_a?(Array)
+            add_conditions(widget, method, condition, :create_color_array) do |color_array|
+              color_array.arg = color
+            end
+          end
+        end
+
+        def add_conditions(widget, method, conditions, container_method)
+          return if conditions.empty?
+
+          object = widget.send(method)
+          has_and_conditions = conditions.any?(Array)
+          # @deprecated OH 4.1
+          if !SitemapBuilder.factory.respond_to?(:create_condition) && has_and_conditions
+            raise ArgumentError, "AND conditions not supported prior to openHAB 4.1"
+          end
+
+          conditions = [conditions] unless has_and_conditions
+
+          conditions.each do |sub_conditions|
+            container = SitemapBuilder.factory.send(container_method)
+
+            add_conditions_to_container(container, sub_conditions)
+            yield container if block_given?
+            object.add(container)
+          end
+        end
+
+        def add_conditions_to_container(container, conditions)
+          # @deprecated OH 4.1
+          supports_and_conditions = SitemapBuilder.factory.respond_to?(:create_condition)
+
+          Array.wrap(conditions).each do |c|
+            unless (match = CONDITION_PATTERN.match(c))
+              raise ArgumentError, "Syntax error in condition #{c.inspect}"
             end
 
-            rule = SitemapBuilder.factory.create_color_array
-            rule.item = match["item"]
-            rule.condition = match["condition"]
-            rule.sign = match["sign"]
-            rule.state = match["state"]
-            rule.arg = match["arg"]
-            widget_color.add(color)
+            condition = supports_and_conditions ? SitemapBuilder.factory.create_condition : container
+            condition.item = match["item"]
+            condition.condition = match["condition"]
+            condition.sign = match["sign"]
+            condition.state = match["state"]
+            container.conditions.add(condition) if supports_and_conditions
           end
         end
       end
@@ -284,6 +320,7 @@ module OpenHAB
 
           @switch = switch
           @frequency = frequency
+          @switch_enabled = nil
         end
 
         # (see #switch=)

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

@@ -32,6 +32,36 @@ module OpenHAB
       #     end
       #   end
       #
+      # @example Create a Thing within a Bridge
+      #   things.build do
+      #     bridge "mqtt:broker:mosquitto", config: { host: "127.0.0.1", enableDiscovery: false } do
+      #       thing "mqtt:topic:window1", "My Window Sensor" do
+      #         channel "contact1", "contact", config: {
+      #           stateTopic: "zigbee2mqtt/window1/contact",
+      #           on: "false",
+      #           off: "true"
+      #         }
+      #       end
+      #     end
+      #   end
+      #
+      #   items.build do
+      #     contact_item Window1_Contact, channel: "mqtt:topic:window1:contact1"
+      #   end
+      #
+      # @example Create a Thing separately from the Bridge
+      #   things.build do
+      #     bridge = bridge "mqtt:broker:mosquitto", config: { host: "127.0.0.1", enableDiscovery: false }
+      #
+      #     thing "mqtt:topic:window1", "My Window Sensor", bridge: bridge do
+      #       channel "contact1", "contact", config: {
+      #         stateTopic: "zigbee2mqtt/window1/contact",
+      #         on: "false",
+      #         off: "true"
+      #       }
+      #     end
+      #   end
+      #
       # @see ThingBuilder#initialize ThingBuilder#initialize for #thing's parameters
       # @see ChannelBuilder#initialize ChannelBuilder#initialize for #channel's parameters
       # @see Items::Builder
@@ -61,6 +91,7 @@ module OpenHAB
 
         def build(klass, *args, **kwargs, &block)
           builder = klass.new(*args, **kwargs)
+          builder.parent_builder = self if builder.respond_to?(:parent_builder=)
           builder.instance_eval(&block) if block
           thing = builder.build
 
@@ -190,6 +221,7 @@ module OpenHAB
           @location = location.label if location.is_a?(Item)
           @config = config.transform_keys(&:to_s)
           @enabled = enabled
+          @builder = org.openhab.core.thing.binding.builder.ThingBuilder unless instance_variable_defined?(:@builder)
         end
 
         # Add an explicitly configured channel to this item
@@ -222,13 +254,12 @@ module OpenHAB
             @channels = merged_channels.values
           end
 
-          builder = org.openhab.core.thing.binding.builder.ThingBuilder
-                       .create(thing_type_uid, uid)
-                       .with_label(label)
-                       .with_location(location)
-                       .with_configuration(configuration)
-                       .with_bridge(bridge_uid)
-                       .with_channels(channels)
+          builder = @builder.create(thing_type_uid, uid)
+                            .with_label(label)
+                            .with_location(location)
+                            .with_configuration(configuration)
+                            .with_bridge(bridge_uid)
+                            .with_channels(channels)
 
           builder.with_properties(thing_type.properties) if thing_type
 
@@ -244,16 +275,26 @@ module OpenHAB
 
       # The BridgeBuilder DSL allows you to customize a thing
       class BridgeBuilder < ThingBuilder
+        # @!visibility private
+        attr_accessor :parent_builder
+
+        # Constructor for BridgeBuilder
+        # @see ThingBuilder#initialize
+        def initialize(uid, label = nil, binding: nil, type: nil, bridge: nil, location: nil, config: {}, enabled: nil)
+          @builder = org.openhab.core.thing.binding.builder.BridgeBuilder
+          super
+        end
+
         # Create a new Bridge with this Bridge as its Bridge
         # @see BridgeBuilder#initialize
         def bridge(*args, **kwargs, &block)
-          super(*args, bridge: self, **kwargs, &block)
+          parent_builder.bridge(*args, bridge: self, **kwargs, &block)
         end
 
         # Create a new Thing with this Bridge as its Bridge
         # @see ThingBuilder#initialize
         def thing(*args, **kwargs, &block)
-          super(*args, bridge: self, **kwargs, &block)
+          parent_builder.thing(*args, bridge: self, **kwargs, &block)
         end
       end
 
@@ -283,7 +324,7 @@ module OpenHAB
         # @param [String] uid The channel's ID.
         # @param [String, ChannelTypeUID, :trigger] type The concrete type of the channel.
         # @param [String] label The channel label.
-        # @param [thing] thing The thing associated with this channel.
+        # @param [Thing] thing The thing associated with this channel.
         #   This parameter is not needed for the {ThingBuilder#channel} method.
         # @param [String] description The channel description.
         # @param [String] group The group name.

data/lib/openhab/dsl/version.rb

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

data/lib/openhab/dsl.rb

@@ -77,7 +77,13 @@ module OpenHAB
     #
     # Defines a new profile that can be applied to item channel links.
     #
+    # To create a profile that can be used in the UI, provide a label and optionally a {config_description},
+    # otherwise the profile will not be visible in the UI.
+    #
     # @param [String, Symbol] id The id for the profile.
+    # @param [String, nil] label The label for the profile. When nil, the profile will not be visible in the UI.
+    # @param [org.openhab.core.config.core.ConfigDescription, nil] config_description
+    #   The configuration description for the profile so that it can be configured in the UI.
     # @yield [event, command: nil, state: nil, callback:, link:, item:, channel_uid:, configuration:, context:]
     #   All keyword params are optional. Any that aren't defined won't be passed.
     # @yieldparam [:command_from_item, :state_from_item, :command_from_handler, :state_from_handler] event
@@ -97,8 +103,8 @@ module OpenHAB
     # @yieldreturn [Boolean] Return true from the block in order to have default processing.
     # @return [void]
     #
-    # @see org.openhab.thing.Profile
-    # @see org.openhab.thing.StateProfile
+    # @see org.openhab.core.thing.profiles.Profile
+    # @see org.openhab.core.thing.profiles.StateProfile
     #
     # @example Vetoing a command
     #   profile(:veto_closing_shades) do |event, item:, command:|
@@ -142,17 +148,54 @@ module OpenHAB
     #   # can also be referenced from an `.items` file:
     #   # Number:Temperature MyTempWithNonUnitValueFromBinding "I prefer Celsius [%d °C]" { channel="something_that_returns_F"[profile="ruby:set_uom", unit="°F"] }
     #
-    def profile(id, &block)
+    # @example Create a profile that is usable in the UI
+    #   config_description = config_description do
+    #     parameter :min, :decimal, label: "Minimum", description: "Minimum value"
+    #     parameter :max, :decimal, label: "Maximum", description: "Maximum value"
+    #   end
+    #
+    #   profile(:range_filter, label: "Range Filter", config_description: config_description) do |event, state:, configuration:|
+    #     return true unless event == :state_from_handler
+    #
+    #     (configuration["min"]..configuration["max"]).cover?(state)
+    #   end
+    #
+    def profile(id, label: nil, config_description: nil, &block)
       raise ArgumentError, "Block is required" unless block
 
       id = id.to_s
-      uid = org.openhab.core.thing.profiles.ProfileTypeUID.new("ruby", id)
 
       ThreadLocal.thread_local(openhab_rule_type: "profile", openhab_rule_uid: id) do
-        Core::ProfileFactory.instance.register(uid, block)
+        Core::ProfileFactory.instance.register(id, block, label: label, config_description: config_description)
       end
     end
 
+    #
+    # Create a {org.openhab.core.config.core.ConfigDescription ConfigDescription} object.
+    #
+    # @param [String, java.net.URI] uri The URI for the ConfigDescription. When nil, a dummy URI is used which will
+    #   be replaced by the profile with the correct URI for that profile.
+    # @yield Block that consists of {ConfigDescription::Builder#parameter} and {ConfigDescription::Builder#group} calls.
+    #
+    # @return [org.openhab.core.config.core.ConfigDescription]
+    #   The created {org.openhab.core.config.core.ConfigDescription ConfigDescription} object
+    #
+    # @example
+    #  config_description = config_description do
+    #    parameter :ungrouped_parameter, :decimal, label: "Ungrouped Parameter", min: 1, max: 5
+    #
+    #    group "Config Group", label: "Grouped parameters", advanced: true do
+    #      parameter :my_parameter, :string, label: "My Parameter", description: "My Parameter Description"
+    #      parameter :other_parameter, :integer, label: "Other Parameter", description: "Other Parameter Description"
+    #    end
+    #  end
+    #
+    def config_description(uri = nil, &block)
+      raise ArgumentError, "Block is required" unless block
+
+      ConfigDescription::Builder.new.build(uri, &block)
+    end
+
     # rubocop:enable Layout/LineLength
 
     # @!group Object Access

data/lib/openhab/yard/code_objects/java/base.rb

@@ -9,7 +9,9 @@ module YARD
       # Which might be a class, an enum, or an interface
       module Base
         module ClassMethods
-          def new(name)
+          def new(name, _suffix = nil)
+            # _suffix is given when it encounters a class with ::, e.g. org.openhab.core.OpenHAB::DEFAULT_CONFIG_FOLDER
+
             super(:root, name)
           end
         end

data/lib/openhab/yard/code_objects/java/method_object.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module YARD
+  module CodeObjects
+    module Java
+      class MethodObject < CodeObjects::MethodObject
+        include Base
+
+        def type
+          :method
+        end
+      end
+    end
+  end
+end

data/lib/openhab/yard/handlers/jruby/base.rb

@@ -5,27 +5,76 @@ module YARD
     module JRuby
       module Base
         class << self
+          #
+          # Creates an external link to java documentation for a java class.
+          #
+          # The supported classes are defined in the `javadocs` configuration option.
+          #
+          # Supported syntaxes:
+          #   Package:
+          #   - org.openhab.core => href_base/org/openhab/core/package-summary.html
+          #
+          #   Class:
+          #   - org.openhab.core.OpenHAB => href_base/org/openhab/core/OpenHAB.html
+          #   This doesn't get mistaken as a constant:
+          #   - java.net.URI => href_base/java/net/URI.html
+          #
+          #   Constant: (To specify a constant, use Ruby's `::` syntax)
+          #   - org.openhab.core.OpenHAB::DEFAULT_CONFIG_FOLDER =>
+          #       href_base/org/openhab/core/OpenHAB.html#DEFAULT_CONFIG_FOLDER
+          #
+          #   Method:
+          #   - org.openhab.core.OpenHAB#getVersion() => href_base/org/openhab/core/OpenHAB.html#getVersion()
+          #   But can also work with constants, albeit not a valid Ruby syntax:
+          #   - org.openhab.core.OpenHAB#version => href_base/org/openhab/core/OpenHAB.html#version
+          #   - org.openhab.core.OpenHAB#DEFAULT_CONFIG_FOLDER =>
+          #       href_base/org/openhab/core/OpenHAB.html#DEFAULT_CONFIG_FOLDER
+          #
+          #   Inner class:
+          #   - org.openhab.core.config.core.ConfigDescriptionParameter::Type =>
+          #       href_base/org/openhab/core/config/core/ConfigDescriptionParameter.Type.html
+          #   - org.openhab.core.config.core.ConfigDescriptionParameter.Type =>
+          #       href_base/org/openhab/core/config/core/ConfigDescriptionParameter.Type.html
+          #
+          #   Constant in inner class:
+          #   - org.openhab.core.config.core.ConfigDescriptionParameter::Type::TEXT =>
+          #       href_base/org/openhab/core/config/core/ConfigDescriptionParameter.Type.html#TEXT
+          #   - org.openhab.core.config.core.ConfigDescriptionParameter.Type::TEXT =>
+          #       href_base/org/openhab/core/config/core/ConfigDescriptionParameter.Type.html#TEXT
+          #
           def infer_java_class(klass, inferred_type = nil, comments = nil, statement = nil)
-            components = klass.split(".")
-            components.pop if components.last == "freeze"
-
-            class_first_char = components.last[0]
-            is_field = components.last == components.last.upcase
-            container_first_char = components[-2]&.[](0)
-            is_method = container_first_char &&
-                        class_first_char != class_first_char.upcase &&
-                        container_first_char == container_first_char.upcase
-            is_package = !is_method && !is_field && class_first_char != class_first_char.upcase
-
-            # methods aren't supported right now
-            return if is_method
-
             javadocs = YARD::Config.options.dig(:jruby, "javadocs") || {}
 
             href_base = javadocs.find { |package, _href| klass == package || klass.start_with?("#{package}.") }&.last
             return unless href_base
 
+            components = klass.split(/\.(?=[A-Z])/, 2)
+            components.unshift(*components.shift.split("."))
+            components.push(components.pop.delete_suffix(".freeze"))
+
+            class_first_char = components.last[0]
+            if /#|::/.match?(components.last)
+              parts = components.pop.rpartition(/#|::/)
+              is_field = parts.last == parts.last.upcase
+              # explicit method is fine, e.g. `org.openhab.core.OpenHAB#getVersion()`
+              is_method = !is_field
+              components.push(parts.first.gsub("::", "."), parts.last)
+            else
+              is_field = is_method = false
+              if components.last.include?(".")
+                parts = components.last.split(".")
+                if (is_method = parts.last[0] == parts.last[0].downcase)
+                  # implicit method is not supported, e.g. `org.openhab.core.OpenHAB.version`
+                  # because we're not sure whether it should be #version() or #getVersion()
+                  return
+                end
+              end
+            end
+
+            is_package = !is_method && !is_field && class_first_char != class_first_char.upcase
+
             inferred_type = CodeObjects::Java::FieldObject if is_field
+            inferred_type = CodeObjects::Java::MethodObject if is_method
             inferred_type = CodeObjects::Java::PackageObject if is_package
             if inferred_type.nil?
               docstring = Docstring.parser.parse(comments || statement&.comments).to_docstring
@@ -36,12 +85,18 @@ module YARD
                               end
             end
 
+            orig_klass = klass.dup
+
+            # purposely calling gsub! to modify the caller's string
+            # YARD doesn't handle java inner classes well, so we convert them to ruby
+            klass.gsub!("::", ".")
+
             inferred_type.new(klass) do |o|
               o.source = statement if statement
               suffix = "/package-summary" if is_package
-              field = "##{components.pop}" if is_field
+              field = "##{components.pop}" if is_field || is_method
               link = "#{href_base}#{components.join("/")}#{suffix}.html#{field}"
-              o.docstring.add_tag(Tags::Tag.new(:see, klass, nil, link)) unless o.docstring.has_tag?(:see)
+              o.docstring.add_tag(Tags::Tag.new(:see, orig_klass, nil, link)) unless o.docstring.has_tag?(:see)
             end
           end
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.11.0
+  version: 5.12.1
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-29 00:00:00.000000000 Z
+date: 2023-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -124,20 +124,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
-- !ruby/object:Gem::Dependency
-  name: github_changelog_generator
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.16'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.16'
 - !ruby/object:Gem::Dependency
   name: guard-rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -391,6 +377,7 @@ files:
 - lib/openhab/core/events/abstract_event.rb
 - lib/openhab/core/events/abstract_item_registry_event.rb
 - lib/openhab/core/events/abstract_thing_registry_event.rb
+- lib/openhab/core/events/channel_triggered_event.rb
 - lib/openhab/core/events/item_command_event.rb
 - lib/openhab/core/events/item_event.rb
 - lib/openhab/core/events/item_state_changed_event.rb
@@ -505,6 +492,7 @@ files:
 - lib/openhab/core_ext/ruby/symbol.rb
 - lib/openhab/core_ext/ruby/time.rb
 - lib/openhab/dsl.rb
+- lib/openhab/dsl/config_description/builder.rb
 - lib/openhab/dsl/debouncer.rb
 - lib/openhab/dsl/events.rb
 - lib/openhab/dsl/events/watch_event.rb
@@ -569,6 +557,7 @@ files:
 - lib/openhab/yard/code_objects/java/class_object.rb
 - lib/openhab/yard/code_objects/java/field_object.rb
 - lib/openhab/yard/code_objects/java/interface_object.rb
+- lib/openhab/yard/code_objects/java/method_object.rb
 - lib/openhab/yard/code_objects/java/package_object.rb
 - lib/openhab/yard/code_objects/java/proxy.rb
 - lib/openhab/yard/coderay.rb