openhab-scripting 5.9.0 → 5.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f531c0d4e77bbee531e574b759f56e458d4eacde89520b8cf9f810dd46e61d9
-  data.tar.gz: 7724b5709c56fb80f095c14930fd3077a2019111731865f1956f4b080a8039ab
+  metadata.gz: 9e7d078cc73659d0f435950d36438b67759b2e3b5c0abf80f258a36101792a0d
+  data.tar.gz: 2a76c20015d6320b64a2a9ea79557c7133b1101a8514fabba9241f91b455615d
 SHA512:
-  metadata.gz: 11237012154342229a7b1a4b24a2e5e8f81833d758e81614b067c4a1187a598e5fbc45cfd300312ef0f039130a039e6df7c75f59e08e458d0bdf7761e2a85f8d
-  data.tar.gz: 3bd394f5d950d2ab5a0016a4219d7d1ac0cb9f4fbdca541d4f41c9e59406c01a1d0df242334cc95a4cf1668f546e1f0fc7aa03cd835f71384e4a3de4cace8304
+  metadata.gz: bc54b1fae7be3bee15b1af2c27526cf942a13741404dd1c0e61034b82d2d472703bfb48ef921d25ed608dbe3d9c964abbded85ab1d3adfd855847229c6bf2447
+  data.tar.gz: c454623c911c90be03464391f885b8ccebfd2789b5e9dbbe32a6f8309fdf7e1f948e2c0730373d383bf7892271ab752bf9d8c2197ed541cff7f33a692ea296ec

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

@@ -10,6 +10,9 @@ module OpenHAB
         # @return [Object]
         attr_accessor :attachment
 
+        # @return [Hash]
+        attr_accessor :inputs
+
         # @return [String]
         alias_method :inspect, :to_s
 

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

@@ -16,6 +16,25 @@ module OpenHAB
         def item
           EntityLookup.lookup_item(item_name)
         end
+
+        #
+        # @!attribute [r] group
+        #
+        # Returns the group item whose member had triggered this event.
+        #
+        # This is the equivalent of openHAB's `triggeringGroup`, and it is only available
+        # on a member-of-group trigger.
+        #
+        # @return [Item,nil] The group item whose member had triggered this event.
+        #   `nil` when the event wasn't triggered by a member-of-group trigger.
+        #
+        # @since openHAB 4.0 for file-based rules
+        # @since openHAB 4.1 for UI rules
+        #
+        def group
+          triggering_group = inputs&.[]("triggeringGroup") || $ctx&.[]("triggeringGroup")
+          Items::Proxy.new(triggering_group) if triggering_group
+        end
       end
     end
   end

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

@@ -133,6 +133,16 @@ 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/generic_item.rb

@@ -128,15 +128,19 @@ module OpenHAB
         # Send a command to this item
         #
         # When this method is chained after the {OpenHAB::DSL::Items::Ensure::Ensurable#ensure ensure}
-        # method, or issued inside an {OpenHAB::DSL.ensure_states ensure_states} block,
+        # method, or issued inside an {OpenHAB::DSL.ensure_states ensure_states} block, or after
+        # {OpenHAB::DSL.ensure_states! ensure_states!} have been called,
         # the command will only be sent if the item is not already in the same state.
         #
+        # The similar method `command!`, however, will always send the command regardless of the item's state.
+        #
         # @param [Command] command command to send to the item
         # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
         #   otherwise the item.
         #
         # @see DSL::Items::TimedCommand#command Timed Command
         # @see OpenHAB::DSL.ensure_states ensure_states
+        # @see OpenHAB::DSL.ensure_states! ensure_states!
         # @see DSL::Items::Ensure::Ensurable#ensure ensure
         #
         def command(command)
@@ -145,6 +149,7 @@ module OpenHAB
           $events.send_command(self, command)
           Proxy.new(self)
         end
+        alias_method :command!, :command
 
         # not an alias to allow easier stubbing and overriding
         def <<(command)
@@ -170,6 +175,7 @@ module OpenHAB
           $events.post_update(self, state)
           Proxy.new(self)
         end
+        alias_method :update!, :update
 
         # @!visibility private
         def format_command(command)

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

@@ -251,6 +251,7 @@ module OpenHAB
           !(self.tags.to_a & tags).empty?
         end
 
+        # @!attribute thing [r]
         # Return the item's thing if this item is linked with a thing. If an item is linked to more than one thing,
         # this method only returns the first thing.
         #
@@ -260,6 +261,7 @@ module OpenHAB
         end
         alias_method :linked_thing, :thing
 
+        # @!attribute things [r]
         # Returns all of the item's linked things.
         #
         # @return [Array<Thing>] An array of things or an empty array
@@ -268,11 +270,80 @@ module OpenHAB
         end
         alias_method :all_linked_things, :things
 
+        #
+        # @!attribute links [r]
         # Returns all of the item's links (channels and link configurations).
         #
-        # @return [Array<ItemChannelLink>] An array of ItemChannelLink or an empty array
+        # @return [ItemChannelLinks] An array of ItemChannelLink or an empty array
+        #
+        # @example Get the configuration of the first link
+        #   LivingRoom_Light_Power.links.first.configuration
+        #
+        # @example Remove all managed links
+        #   LivingRoom_Light_Power.links.clear
+        #
+        # @see link
+        # @see unlink
+        #
         def links
-          Things::Links::Provider.registry.get_links(name)
+          ItemChannelLinks.new(self, Things::Links::Provider.registry.get_links(name))
+        end
+
+        #
+        # Links the item to a channel.
+        #
+        # @param [String, Things::Channel, Things::ChannelUID] channel The channel to link to.
+        # @param [Hash] config The configuration for the link.
+        #
+        # @return [Things::ItemChannelLink] The created link.
+        #
+        # @example Link an item to a channel
+        #   LivingRoom_Light_Power.link("mqtt:topic:livingroom-light:power")
+        #
+        # @example Link to a Thing's channel
+        #   LivingRoom_Light_Power.link(things["mqtt:topic:livingroom-light"].channels["power"])
+        #
+        # @example Specify a link configuration
+        #   High_Temperature_Alert.link(
+        #     "mqtt:topic:outdoor-thermometer:temperature",
+        #     profile: "system:hysteresis",
+        #     lower: "29 °C",
+        #     upper: "30 °C")
+        #
+        # @see links
+        # @see unlink
+        #
+        def link(channel, config = {})
+          Core::Things::Links::Provider.create_link(self, channel, config).tap do |new_link|
+            provider = Core::Things::Links::Provider.current
+            if !(current_link = provider.get(new_link.uid))
+              provider.add(new_link)
+            elsif current_link.configuration != config
+              provider.update(new_link)
+            end
+          end
+        end
+
+        #
+        # Removes a link to a channel from managed link providers.
+        #
+        # @param [String, Things::Channel, Things::ChannelUID] channel The channel to remove the link to.
+        #
+        # @return [Things::ItemChannelLink, nil] The removed link, if found.
+        # @raise [FrozenError] if the link is not managed by a managed link provider.
+        #
+        # @see link
+        # @see links
+        #
+        def unlink(channel)
+          link_to_delete = Things::Links::Provider.create_link(self, channel, {})
+          provider = Things::Links::Provider.registry.provider_for(link_to_delete.uid)
+          unless provider.is_a?(ManagedProvider)
+            raise FrozenError,
+                  "Cannot remove the link #{link_to_delete.uid} from non-managed provider #{provider.inspect}"
+          end
+
+          provider.remove(link_to_delete.uid)
         end
 
         # @return [String]
@@ -286,7 +357,8 @@ module OpenHAB
           "#{s}>"
         end
 
-        # @return [org.openhab.core.common.registry.Provider, nil]
+        # @!attribute provider [r]
+        # @return [org.openhab.core.common.registry.Provider, nil] Returns the provider for this item.
         def provider
           Provider.registry.provider_for(self)
         end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module OpenHAB
+  module Core
+    module Items
+      #
+      # A wrapper for {Item#links} delegated to Set<{org.openhab.core.thing.link.ItemChannelLink}>.
+      #
+      # Adds methods for clearing item's links to channels.
+      #
+      class ItemChannelLinks < SimpleDelegator
+        #
+        # @param [Item] item The item that the links belong to
+        # @param [Set<ItemChannelLink>] links The set of links to delegate to
+        #
+        # @!visibility private
+        def initialize(item, links)
+          super(links)
+          @item = item
+        end
+
+        #
+        # Removes all links to channels from managed link providers.
+        # @return [self]
+        #
+        def clear
+          Things::Links::Provider.registry.all.each do |link|
+            next unless link.item_name == @item.name
+
+            provider = Things::Links::Provider.registry.provider_for(link.uid)
+            if provider.is_a?(ManagedProvider)
+              provider.remove(link.uid)
+            else
+              logger.warn("Cannot remove the link #{link.uid} from non-managed provider #{provider.inspect}")
+            end
+          end
+          self
+        end
+      end
+    end
+  end
+end

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

@@ -39,25 +39,51 @@ module OpenHAB
         #   Send the {PLAY} command to the item
         #   @return [PlayerItem] `self`
 
+        # @!method play!
+        #   Send the {PLAY} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [PlayerItem] `self`
+
         # @!method pause
         #   Send the {PAUSE} command to the item
         #   @return [PlayerItem] `self`
 
+        # @!method pause!
+        #   Send the {PAUSE} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [PlayerItem] `self`
+
         # @!method rewind
         #   Send the {REWIND} command to the item
         #   @return [PlayerItem] `self`
 
+        # @!method rewind
+        #   Send the {REWIND} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [PlayerItem] `self`
+
         # @!method fast_forward
         #   Send the {FASTFORWARD} command to the item
         #   @return [PlayerItem] `self`
 
+        # @!method fast_forward!
+        #   Send the {FASTFORWARD} command to the item, even when
+        #     {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [PlayerItem] `self`
+
         # @!method next
         #   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

@@ -41,18 +41,34 @@ module OpenHAB
         #   Send the {UP} command to the item
         #   @return [RollershutterItem] `self`
 
+        # @!method up!
+        #   Send the {UP} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [RollershutterItem] `self`
+
         # @!method down
         #   Send the {DOWN} command to the item
         #   @return [RollershutterItem] `self`
 
+        # @!method down!
+        #   Send the {DOWN} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [RollershutterItem] `self`
+
         # @!method stop
         #   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/semantics/enumerable.rb

@@ -101,6 +101,15 @@ module Enumerable
     self if count { |i| i.command(command) }.positive?
   end
 
+  # Send a command to every item in the collection, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+  # @return [self]
+  def command!(command)
+    # We cannot alias this to #command above, otherwise it will call
+    # DSL::Items::Ensure::Item#command which checks for ensure_states
+    each { |i| i.command!(command) }
+    self
+  end
+
   # Update the state of every item in the collection
   # @return [self, nil] nil when `ensure` is in effect and all the items were already in the same state,
   #   otherwise self
@@ -108,6 +117,16 @@ module Enumerable
     self if count { |i| i.update(state) }.positive?
   end
 
+  # Update the state of every item in the collection, even when
+  #   {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+  # @return [self]
+  def update!(state)
+    # We cannot alias this to #update above, otherwise it will call
+    # DSL::Items::Ensure::Item#update which checks for ensure_states
+    each { |i| i.update!(state) }
+    self
+  end
+
   # @!method refresh
   #   Send the {REFRESH} command to every item in the collection
   #   @return [self]

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

@@ -311,6 +311,11 @@ module OpenHAB
               synonyms = Array.wrap(synonyms).map { |s| s.to_s.strip }
 
               tags.map do |name, parent|
+                if (existing_tag = lookup(name))
+                  logger.warn("Tag already exists: #{existing_tag.inspect}")
+                  next
+                end
+
                 unless parent.is_a?(SemanticTag)
                   parent_tag = lookup(parent)
                   raise ArgumentError, "Unknown parent: #{parent}" unless parent_tag
@@ -318,8 +323,6 @@ module OpenHAB
                   parent = parent_tag
                 end
 
-                next if lookup(name)
-
                 new_tag = org.openhab.core.semantics.SemanticTagImpl.new("#{parent.uid}_#{name}",
                                                                          label,
                                                                          description,

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

@@ -67,9 +67,17 @@ module OpenHAB
         #   Send the {ON} command to the item
         #   @return [SwitchItem] `self`
 
+        # @!method on!
+        #   Send the {ON} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [SwitchItem] `self`
+
         # @!method off
         #   Send the {OFF} command to the item
         #   @return [SwitchItem] `self`
+
+        # @!method off!
+        #   Send the {OFF} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [SwitchItem] `self`
       end
     end
   end

data/lib/openhab/core/items.rb

@@ -65,13 +65,19 @@ module OpenHAB
               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
 
             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
+              def #{command}!        # def on!
+                each(&:#{command}!)  #   each(&:on!)
+              end                    # end
             RUBY
 
             logger.trace("Defining ItemCommandEvent##{command}? for #{value}")

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

@@ -42,8 +42,7 @@ module OpenHAB
         # @return [Array<Item>] An array of things or an empty array
         #
         def items
-          registry = OSGi.service("org.openhab.core.thing.link.ItemChannelLinkRegistry")
-          registry.get_linked_items(self).map { |i| Items::Proxy.new(i) }
+          Links::Provider.registry.get_linked_items(self).map { |i| Items::Proxy.new(i) }
         end
       end
     end

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

@@ -26,6 +26,12 @@ module OpenHAB
           DSL.items[item_name]
         end
 
+        # @!attribute [r] channel
+        # @return [Channel]
+        def channel
+          DSL.things[linked_uid.thing_uid].channels[linked_uid.id]
+        end
+
         alias_method :channel_uid, :linked_uid
       end
     end

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

@@ -8,44 +8,38 @@ module OpenHAB
       # and channels.
       #
       module ProfileCallback
-        class << self
-          #
-          # Wraps the parent class's method to format non-Types.
-          #
-          # @!macro def_state_parsing_method
-          #   @!method $1($2)
-          #   @return [void]
-          # @!visibility private
-          def def_state_parsing_method(method, param_name)
-            class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              def #{method}(type)                                                             # def handle_command(type)
-                type = link.item.format_#{(param_name == :state) ? :update : param_name}(type)  #   type = link.item.format_command(type)
-                super(type)                                                                   #   super(type)
-              end                                                                             # end
-            RUBY
-          end
-        end
-
         #
         # Forward the given command to the respective thing handler.
         #
         # @param [Command] command
         #
-        def_state_parsing_method(:handle_command, :command)
+        def handle_command(command)
+          unless instance_variable_defined?(:@dummy_channel_item)
+            @dummy_channel_item = DSL::Items::ItemBuilder.item_factory.create_item(link.channel.accepted_item_type, "")
+          end
+          command = @dummy_channel_item.format_command(command) if @dummy_channel_item
+          super(command)
+        end
 
         #
         # Send a command to the framework.
         #
         # @param [Command] command
         #
-        def_state_parsing_method(:send_command, :command)
+        def send_command(command)
+          command = link.item.format_command(command)
+          super(command)
+        end
 
         #
         # Send a state update to the framework.
         #
         # @param [State] state
         #
-        def_state_parsing_method(:send_update, :state)
+        def send_update(state)
+          state = link.item.format_update(state)
+          super(state)
+        end
       end
     end
   end

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

@@ -156,7 +156,6 @@ module OpenHAB
             item.update(builder.state) unless builder.state.nil?
 
             # make sure to add the item to the registry before linking it
-            provider = Core::Things::Links::Provider.current
             channel_uids = builder.channels.to_set do |(channel, config)|
               # fill in partial channel names from group's thing id
               if !channel.include?(":") &&
@@ -165,17 +164,11 @@ module OpenHAB
                 channel = "#{thing}:#{channel}"
               end
 
-              new_link = Core::Things::Links::Provider.create_link(item, channel, config)
-              if !(current_link = provider.get(new_link.uid))
-                provider.add(new_link)
-              elsif current_link.configuration != config
-                provider.update(new_link)
-              end
-
-              new_link.linked_uid
+              item.link(channel, config).linked_uid
             end
 
             # remove links not in the new item
+            provider = Core::Things::Links::Provider.current
             provider.all.each do |link|
               provider.remove(link.uid) if link.item_name == item.name && !channel_uids.include?(link.linked_uid)
             end

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

@@ -24,7 +24,7 @@ module OpenHAB
 
         # Extensions for {::Item} to implement {Ensure}'s functionality
         #
-        # @see OpenHAB::DSL.ensure ensure
+        # @see OpenHAB::DSL::Items::Ensure::Ensurable#ensure ensure
         # @see OpenHAB::DSL.ensure_states ensure_states
         module Item
           include Ensurable

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

@@ -149,6 +149,8 @@ module OpenHAB
             end
 
             event.attachment = attachment
+            # events that are not from AbstractEvent do not have inputs
+            event.inputs = inputs if event.respond_to?(:inputs=)
             return event
           end
 

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

@@ -210,7 +210,18 @@ module OpenHAB
               thing_type,
               self.class.config_description_registry
             )
+
+            predefined_channels = self.class.thing_factory_helper
+                                      .create_channels(thing_type, uid, self.class.config_description_registry)
+                                      .to_h { |channel| [channel.uid, channel] }
+            new_channels = channels.to_h { |channel| [channel.uid, channel] }
+            merged_channels = predefined_channels.merge(new_channels) do |_key, predefined_channel, new_channel|
+              predefined_channel.configuration.merge!(new_channel.configuration)
+              predefined_channel
+            end
+            @channels = merged_channels.values
           end
+
           builder = org.openhab.core.thing.binding.builder.ThingBuilder
                        .create(thing_type_uid, uid)
                        .with_label(label)
@@ -219,15 +230,7 @@ module OpenHAB
                        .with_bridge(bridge_uid)
                        .with_channels(channels)
 
-          if thing_type
-            # can't use with_channels, or it will wipe out custom channels from above
-            self.class.thing_factory_helper.create_channels(thing_type,
-                                                            uid,
-                                                            self.class.config_description_registry).each do |channel|
-              builder.with_channel(channel)
-            end
-            builder.with_properties(thing_type.properties)
-          end
+          builder.with_properties(thing_type.properties) if thing_type
 
           builder.build
         end
@@ -263,8 +266,14 @@ module OpenHAB
                     :default_tags,
                     :properties,
                     :description,
-                    :auto_update_policy,
-                    :accepted_item_type
+                    :auto_update_policy
+
+        class << self
+          # @!visibility private
+          def channel_type_registry
+            @channel_type_registry ||= OSGi.service("org.openhab.core.thing.type.ChannelTypeRegistry")
+          end
+        end
 
         #
         # Constructor for ChannelBuilder
@@ -284,7 +293,7 @@ module OpenHAB
         #   The default tags for this channel.
         # @param [:default, :recommend, :veto, org.openhab.core.thing.type.AutoUpdatePolicy] auto_update_policy
         #   The channel's auto update policy.
-        # @param [String] accepted_item_type The accepted item type.
+        # @param [String] accepted_item_type The accepted item type. If nil, infer the item type from the channel type.
         #
         def initialize(uid,
                        type,
@@ -343,6 +352,12 @@ module OpenHAB
              .build
         end
 
+        # @!attribute [r] accepted_item_type
+        # @return [String] The accepted item type.
+        def accepted_item_type
+          @accepted_item_type ||= self.class.channel_type_registry.get_channel_type(type)&.item_type
+        end
+
         private
 
         def kind

data/lib/openhab/dsl/version.rb

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

data/lib/openhab/dsl.rb

@@ -557,10 +557,49 @@ module OpenHAB
     #   to reduce repetitions
     #
 
+    #
+    # Permanently enable conditional execution of commands and updates for the current thread.
+    #
+    # When conditional executions are enabled, commands and updates will only be sent if the
+    # item's current state is not the same as the command or updated state.
+    # This eliminates the need to chain the command and update calls through
+    # {DSL::Items::Ensure::Ensurable#ensure ensure}.
+    #
+    # When conditional executions are enabled either by this method or within a block of {ensure_states},
+    # commands and updates can still be forcefully executed using the corresponding bang methods, e.g.
+    # `Item1.on!`, `Item1.command!(50)`, or `Item1.update!(ON)`.
+    #
+    # @note This method is only intended for use at the top level of rule
+    #   scripts. If it's used within library methods, or hap-hazardly within
+    #   rules, things can get very confusing because the prior state won't be
+    #   properly restored.
+    #
+    # @param [Boolean] active Whether to enable or disable conditional executions.
+    # @return [Boolean] The previous ensure_states setting.
+    #
+    # @example Make ensure_states the default for the rest of the script
+    #   ensure_states!
+    #
+    #   # From now, all commands are "ensured", i.e. only sent when the current state is different
+    #   Item1.on
+    #   Item2.command(ON)
+    #
+    #   # While ensure_states! is active, we can still forcibly send a command
+    #   # regardless of the item's current state
+    #   Item2.on!
+    #
+    # @see ensure_states
+    #
+    def ensure_states!(active: true)
+      old = Thread.current[:openhab_ensure_states]
+      Thread.current[:openhab_ensure_states] = active
+      old
+    end
+
     #
     # Global method that takes a block and for the duration of the block
     # all commands sent will check if the item is in the command's state
-    # before sending the command.
+    # before sending the command. This also applies to updates.
     #
     # @yield
     # @return [Object] The result of the block.
@@ -603,11 +642,10 @@ module OpenHAB
     #   end
     #
     def ensure_states
-      old = Thread.current[:openhab_ensure_states]
-      Thread.current[:openhab_ensure_states] = true
+      old = ensure_states!
       yield
     ensure
-      Thread.current[:openhab_ensure_states] = old
+      ensure_states!(active: old)
     end
 
     #
@@ -841,7 +879,7 @@ module OpenHAB
     #     elements, the {Core::Items::Metadata::Hash} will be passed as an argument. Therefore it's
     #     recommended that you use a Proc, not a Lambda, for permissive argument matching.
     #
-    # @return [void]
+    # @return [Hash] the prior provider configuration.
     #
     # @see provider
     # @see OpenHAB::Core::Provider.current Provider.current for how the current provider is calculated

data/lib/openhab/rspec/shell.rb

@@ -5,26 +5,36 @@ module OpenHAB
     # based on https://stackoverflow.com/questions/1197224/source-shell-script-into-environment-within-a-ruby-script#19826329
     # @!visibility private
     module Shell
-      module_function
+      # @!visibility private
+      DEFAULT_PRINTENV_COMMAND = "printenv -0"
+      @printenv_command = DEFAULT_PRINTENV_COMMAND
+      @printenv_separator = "\0"
 
-      # Read in the bash environment, after an optional command.
-      #   Returns Array of key/value pairs.
-      def shell_env(cmd = nil)
-        cmd = "#{cmd} > /dev/null; " if cmd
-        env = `#{cmd}printenv -0`
-        env.split("\0").map { |l| l.split("=", 2) }
-      end
+      class << self
+        # Read in the bash environment, after an optional command.
+        #   Returns Array of key/value pairs.
+        def shell_env(cmd = nil)
+          cmd = "#{cmd} > #{IO::NULL}; " if cmd
+          env = `#{cmd}#{@printenv_command} 2> #{IO::NULL}`
+          if !$?.success? && @printenv_command.equal?(DEFAULT_PRINTENV_COMMAND)
+            @printenv_command = "printenv"
+            @printenv_separator = "\n"
+            env = `#{cmd}#{@printenv_command}`
+          end
+          env.split(@printenv_separator).map { |l| l.split("=", 2) }
+        end
 
-      # Source a given file, and compare environment before and after.
-      #   Returns Hash of any keys that have changed.
-      def shell_source(file)
-        (shell_env(". #{File.realpath(file)}") - shell_env).to_h
-      end
+        # Source a given file, and compare environment before and after.
+        #   Returns Hash of any keys that have changed.
+        def shell_source(file)
+          (shell_env(". #{File.realpath(file)}") - shell_env).to_h
+        end
 
-      # Find variables changed as a result of sourcing the given file,
-      #   and update in ENV.
-      def source_env_from(file)
-        shell_source(file).each { |k, v| ENV[k] = v }
+        # Find variables changed as a result of sourcing the given file,
+        #   and update in ENV.
+        def source_env_from(file)
+          shell_source(file).each { |k, v| ENV[k] = v }
+        end
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.9.0
+  version: 5.11.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-09 00:00:00.000000000 Z
+date: 2023-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -409,6 +409,7 @@ files:
 - lib/openhab/core/items/group_item.rb
 - lib/openhab/core/items/image_item.rb
 - lib/openhab/core/items/item.rb
+- lib/openhab/core/items/item_channel_links.rb
 - lib/openhab/core/items/location_item.rb
 - lib/openhab/core/items/metadata.rb
 - lib/openhab/core/items/metadata/hash.rb