openhab-scripting 5.10.0 → 5.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acf8ae7ed285c32bb11070e6ae64c54b9687dae7883c272be4a9ad30f399ed8c
-  data.tar.gz: 8820ac3849f07734843d2863ff483fbde70bfe56c41981f2d48ec2e8c7bd73a8
+  metadata.gz: 9e7d078cc73659d0f435950d36438b67759b2e3b5c0abf80f258a36101792a0d
+  data.tar.gz: 2a76c20015d6320b64a2a9ea79557c7133b1101a8514fabba9241f91b455615d
 SHA512:
-  metadata.gz: ab2e153c20c4d81b4b4b5b7d3025d1f49812099ea1040eba85b03f6fc8ce4217d84a3204e1c0917ed53c8386220b25da7d1da4bc367b51459ef74d67a52d7d44
-  data.tar.gz: 0bdc096799e02f344f7d24c218af6ed045840c9a87ab890e81a339896801c53c6e18a6dabafd060e2c18023b69da8fdb4df9d3d58fcab3917baba6274fe992eb
+  metadata.gz: bc54b1fae7be3bee15b1af2c27526cf942a13741404dd1c0e61034b82d2d472703bfb48ef921d25ed608dbe3d9c964abbded85ab1d3adfd855847229c6bf2447
+  data.tar.gz: c454623c911c90be03464391f885b8ccebfd2789b5e9dbbe32a6f8309fdf7e1f948e2c0730373d383bf7892271ab752bf9d8c2197ed541cff7f33a692ea296ec

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/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/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/profile_callback.rb

@@ -14,9 +14,10 @@ module OpenHAB
         # @param [Command] command
         #
         def handle_command(command)
-          @dummy_channel_item ||= DSL::Items::ItemBuilder.item_factory.create_item(link.channel.accepted_item_type,
-                                                                                   "")
-          command = @dummy_channel_item.format_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
 

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/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.10.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.10.0
+  version: 5.11.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-25 00:00:00.000000000 Z
+date: 2023-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler