openhab-scripting 5.16.0 → 5.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66607fb79de6b8b718ddd8cc5cc10662809001e67915074b44360ba9f6408d31
-  data.tar.gz: e21976073a7323b4e8bfe05a09e8959472d950ad28df26534371c857fe64699f
+  metadata.gz: b1a3e61eb7613c8235e61cf99dc8d97d4c8403d8c2af21f873434ebf89ecff49
+  data.tar.gz: '09330d12003c08cd0af744d14c52287e9588c9b440975839e3cbd18d4914e027'
 SHA512:
-  metadata.gz: 815f05142db0071b36cd45b9f9e81c1c033cf759823150066f2c65ec4f5eb61fdf9b1bf4dbc0e8125adf3535eb9e83b71fbbf401c2e6f1a716838fe6f37cdd29
-  data.tar.gz: 4fe2bd7469d2d4489bd41ee9c62c6b4e7d53e6350e095c895b936813582d89e088b772bb0a44fde82aaecbfe5ff1c3fac320505001e24d0ac4519646abac5889
+  metadata.gz: 2ee2f0a8eb080aaed28d4484f23828d3e926f957a574e67ab5231ab44cf2dcb46897e841a9a481cdadfa30e1d026b4f4375755ee85f75954707208001d3442d5
+  data.tar.gz: 95ff1eb5298403900d9fb3370efaf9c3ffa7f356c40d5176a5d9ccf64fce3b6f701b8ddbb2f1103cb3102f3628cf9f27b0e9209cc44e97537eb0e832cc64061d

data/lib/openhab/core/entity_lookup.rb

@@ -74,7 +74,7 @@ module OpenHAB
       ruby2_keywords def method_missing(method, *args)
         return super unless args.empty? && !block_given?
 
-        logger.trace("method missing, performing openHAB Lookup for: #{method}")
+        logger.trace { "method missing, performing openHAB Lookup for: #{method}" }
         EntityLookup.lookup_entity(method,
                                    create_dummy_items: self.class.respond_to?(:create_dummy_items?) &&
                                      self.class.create_dummy_items?) || super
@@ -82,7 +82,7 @@ module OpenHAB
 
       # @!visibility private
       def respond_to_missing?(method, *)
-        logger.trace("Checking if openHAB entities exist for #{method}")
+        logger.trace { "Checking if openHAB entities exist for #{method}" }
         EntityLookup.lookup_entity(method) || super
       end
 
@@ -121,14 +121,14 @@ module OpenHAB
         # @return [Things::Thing, nil]
         #
         def lookup_thing(uid)
-          logger.trace("Looking up thing '#{uid}'")
+          logger.trace { "Looking up thing '#{uid}'" }
           uid = uid.to_s if uid.is_a?(Symbol)
 
           uid = Things::ThingUID.new(uid) unless uid.is_a?(Things::ThingUID)
           thing = $things.get(uid)
           return unless thing
 
-          logger.trace("Retrieved Thing(#{thing}) from registry for uid: #{uid}")
+          logger.trace { "Retrieved Thing(#{thing}) from registry for uid: #{uid}" }
           Things::Proxy.new(thing)
         end
 
@@ -164,7 +164,7 @@ module OpenHAB
         # @return [Item, nil]
         #
         def lookup_item(name)
-          logger.trace("Looking up item '#{name}'")
+          logger.trace { "Looking up item '#{name}'" }
           name = name.to_s if name.is_a?(Symbol)
           item = $ir.get(name)
           Items::Proxy.new(item) unless item.nil?

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

@@ -2,21 +2,21 @@
 
 require_relative "item_state_event"
 
+# @deprecated OH3.4 guard only needed in OH 3.4
+return unless OpenHAB::Core.version >= OpenHAB::Core::V4_0
+
 module OpenHAB
   module Core
     module Events
-      # @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
+      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
+      #
+      # {AbstractEvent} sent when an item's state has updated.
+      #
+      # @since openHAB 4.0
+      #
+      class ItemStateUpdatedEvent < ItemEvent
+        include ItemState
       end
     end
   end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# @deprecated OH4.0 guard not needed in OH 4.1
+return unless OpenHAB::Core.version >= OpenHAB::Core::V4_1
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.ItemTimeSeriesUpdatedEvent
+
+      #
+      # {AbstractEvent} sent when an item received a time series update.
+      #
+      # @!attribute [r] time_series
+      #   @return [TimeSeries] The updated time series.
+      #
+      # @since openHAB 4.1
+      # @see DSL::Rules::BuilderDSL#time_series_updated #time_series_updated rule trigger
+      #
+      class ItemTimeSeriesUpdatedEvent < ItemEvent; end
+    end
+  end
+end

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

@@ -1,46 +1,46 @@
 # frozen_string_literal: true
 
+# @deprecated OH3.4 this guard is not needed on OH4
+return unless OpenHAB::Core.version >= OpenHAB::Core::V4_0
+
 module OpenHAB
   module Core
     module Events
-      # @deprecated OH3.4 this guard is not needed on OH4
-      if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
-        java_import org.openhab.core.automation.events.TimerEvent
+      java_import org.openhab.core.automation.events.TimerEvent
 
+      #
+      # Adds methods to core openHAB TimerEvent to make it more natural in Ruby
+      #
+      # This event can be triggered by a `DateTimeTrigger`, `cron`, or `TimeOfDay` trigger.
+      #
+      # @since openHAB 4.0
+      #
+      class TimerEvent < AbstractEvent
         #
-        # Adds methods to core openHAB TimerEvent to make it more natural in Ruby
+        # @!attribute [r] cron_expression
+        # @return [String, nil] The cron expression that triggered this event.
+        #   `nil` when this event wasn't triggered by a cron trigger.
         #
-        # This event can be triggered by a `DateTimeTrigger`, `cron`, or `TimeOfDay` trigger.
+        def cron_expression
+          payload&.[](:cronExpression)
+        end
+
         #
-        # @since openHAB 4.0
+        # @!attribute [r] item
+        # @return [Item, nil] The DateTime item that triggered this event.
+        #   `nil` when this event wasn't triggered by a DateTimeItem trigger.
         #
-        class TimerEvent < AbstractEvent
-          #
-          # @!attribute [r] cron_expression
-          # @return [String, nil] The cron expression that triggered this event.
-          #   `nil` when this event wasn't triggered by a cron trigger.
-          #
-          def cron_expression
-            payload&.[](:cronExpression)
-          end
-
-          #
-          # @!attribute [r] item
-          # @return [Item, nil] The DateTime item that triggered this event.
-          #   `nil` when this event wasn't triggered by a DateTimeItem trigger.
-          #
-          def item
-            payload&.[](:itemName)&.then { |item_name| EntityLookup.lookup_item(item_name) }
-          end
+        def item
+          payload&.[](:itemName)&.then { |item_name| EntityLookup.lookup_item(item_name) }
+        end
 
-          #
-          # @!attribute [r] time
-          # @return [LocalTime, nil] The configured time for this TimeOfDay trigger event.
-          #   `nil` when this event wasn't triggered by a TimeOfDay trigger.
-          #
-          def time
-            payload&.[](:time)&.then { |time| LocalTime.parse(time) }
-          end
+        #
+        # @!attribute [r] time
+        # @return [LocalTime, nil] The configured time for this TimeOfDay trigger event.
+        #   `nil` when this event wasn't triggered by a TimeOfDay trigger.
+        #
+        def time
+          payload&.[](:time)&.then { |time| LocalTime.parse(time) }
         end
       end
     end

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

@@ -207,6 +207,18 @@ module OpenHAB
           type.to_s
         end
 
+        #
+        # @method time_series=(time_series)
+        #   Set a new time series.
+        #
+        #   This will trigger a {DSL::Rules::BuilderDSL#time_series_updated time_series_updated} event.
+        #
+        #   @param [Core::Types::TimeSeries] time_series New time series to set.
+        #   @return [void]
+        #
+        #   @since openHAB 4.1
+        #
+
         #
         # Defers notifying openHAB of modifications to multiple attributes until the block is complete.
         #

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

@@ -7,7 +7,7 @@ module OpenHAB
     module Items
       # Mixin for implementing type coercion for number-like items
       module NumericItem
-        %i[positive? negative? zero?].each do |predicate|
+        %i[positive? negative? zero? nonzero?].each do |predicate|
           class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{predicate}              # def positive?
               return false unless state?  #   return false unless state?

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

@@ -83,9 +83,7 @@ module OpenHAB
                                   updated_since?])
 
         # @deprecated OH3.4 - in openHAB 4, just add :get_all_states_since and freeze the list above
-        if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
-          PERSISTENCE_METHODS << :get_all_states_since
-        end
+        PERSISTENCE_METHODS << :get_all_states_since if OpenHAB::Core.version >= OpenHAB::Core::V4_0
         PERSISTENCE_METHODS.freeze
 
         private_constant :QUANTITY_METHODS, :PERSISTENCE_METHODS
@@ -386,7 +384,7 @@ module OpenHAB
         alias_method :state_changes_since, :count_state_changes_since
         alias_method :state_changes_between, :count_state_changes_between
         # @deprecated OH 3.4 - if guard is unnecessary in OH4
-        if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
+        if OpenHAB::Core.version >= OpenHAB::Core::V4_0
           alias_method :all_states_since, :get_all_states_since
           alias_method :all_states_between, :get_all_states_between
         end

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

@@ -21,15 +21,13 @@ module OpenHAB
         # @return [Item] Item from registry, nil if item missing or requested item is a Group Type
         def [](name)
           EntityLookup.lookup_item(name)
-        rescue org.openhab.core.items.ItemNotFoundException
-          nil
         end
 
         # Returns true if the given item name exists
         # @param name [String] Item name to check
         # @return [true,false] true if the item exists, false otherwise
         def key?(name)
-          !$ir.getItems(name).empty?
+          !$ir.get(name).nil?
         end
         alias_method :include?, :key?
         # @deprecated

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

@@ -97,8 +97,8 @@ module Enumerable
   # Send a command to 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
-  def command(command)
-    self if count { |i| i.command(command) }.positive?
+  def command(command, **kwargs)
+    self if count { |i| i.command(command, **kwargs) }.positive?
   end
 
   # Send a command to every item in the collection, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.

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

@@ -226,10 +226,7 @@ module OpenHAB
 
             # @deprecated OH3.4 - the Property tag had an ID of "MeasurementProperty" in OH3.4.
             # This was corrected in OH4.
-            # Make sure we compare against pre-release versions
-            if id == "Property" && Gem::Version.new(Core::VERSION) < Gem::Version.new("4.0.0.M1")
-              id = "MeasurementProperty"
-            end
+            id = "MeasurementProperty" if id == "Property" && Core.version < Core::V4_0
 
             # @deprecated OH3.4 missing registry
             if Provider.registry

data/lib/openhab/core/profile_factory.rb

@@ -15,7 +15,12 @@ module OpenHAB
       include Singleton
 
       class Profile
-        include org.openhab.core.thing.profiles.StateProfile
+        # @deprecated OH 4.0 only include TimeSeriesProfile in OH 4.1, because it extends StateProfile
+        if OpenHAB::Core.version >= OpenHAB::Core::V4_1
+          include org.openhab.core.thing.profiles.TimeSeriesProfile
+        else
+          include org.openhab.core.thing.profiles.StateProfile
+        end
 
         def initialize(callback, context, uid, thread_locals, block)
           unless callback.class.ancestors.include?(Things::ProfileCallback)
@@ -64,6 +69,14 @@ module OpenHAB
           process_event(:state_from_item, state: state)
         end
 
+        # @deprecated OH 4.0 guard is only needed for < OH 4.1
+        if OpenHAB::Core.version >= OpenHAB::Core::V4_1
+          # @!visibility private
+          def onTimeSeriesFromHandler(time_series)
+            process_event(:time_series_from_handler, time_series: time_series)
+          end
+        end
+
         private
 
         def process_event(event, **params)
@@ -77,6 +90,8 @@ module OpenHAB
           params[:channel_uid] = @callback.link.linked_uid
           params[:state] ||= nil
           params[:command] ||= nil
+          # @deprecated OH 4.0 guard is only needed for < OH 4.1
+          params[:time_series] ||= nil if OpenHAB::Core.version >= OpenHAB::Core::V4_1
 
           kwargs = {}
           @block.parameters.each do |(param_type, name)|

data/lib/openhab/core/rules/registry.rb

@@ -63,7 +63,8 @@ module OpenHAB
         #
         def remove(rule_uid)
           rule_uid = rule_uid.uid if rule_uid.is_a?(Rule)
-          provider = Provider.registry.provider_for(rule_uid)
+          return nil unless (provider = Provider.registry.provider_for(rule_uid))
+
           unless provider.is_a?(org.openhab.core.common.registry.ManagedProvider)
             raise "Cannot remove rule #{rule_uid} from non-managed provider #{provider.inspect}"
           end

data/lib/openhab/core/rules/rule.rb

@@ -149,6 +149,7 @@ module OpenHAB
           r += " #{visibility}" unless visible?
           r += " #{status || "<detached>"}"
           r += " (#{status_info.status_detail})" if status_info && status_info.status_detail != RuleStatusDetail::NONE
+          r += " description=#{description.inspect}" if description
           r += " tags=#{tags.to_a.inspect}" unless tags.empty?
           r += " configuration=#{configuration.properties.to_h}" if configuration && !configuration.properties.empty?
           "#{r}>"

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

@@ -132,7 +132,9 @@ module OpenHAB
           builder = DSL::Sitemaps::Builder.new(self, builder_proxy, update: update)
           if block.arity == 1
             builder_proxy.__setobj__(builder)
-            yield builder_proxy
+            DSL::ThreadLocal.thread_local(openhab_create_dummy_items: true) do
+              yield builder_proxy
+            end
           else
             builder.instance_eval(&block)
           end

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

@@ -58,7 +58,7 @@ module OpenHAB
         end
 
         # @deprecated OH3.4 this whole section is not needed in OH4+. Also see Thing#config_eql?
-        if Gem::Version.new(Core::VERSION) < Gem::Version.new("4.0.0")
+        if Core.version < Core::V4_0
           # @!visibility private
           module ChannelComparable
             # @!visibility private

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

@@ -40,6 +40,11 @@ module OpenHAB
           state = link.item.format_update(state)
           super(state)
         end
+
+        # @!method send_time_series(time_series)
+        #   Send a time series to the framework.
+        #   @param [TimeSeries] time_series
+        #   @since openHAB 4.1
       end
     end
   end

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

@@ -165,6 +165,12 @@ module OpenHAB
           ThingType.registry.get_thing_type(thing_type_uid)
         end
 
+        # @!attribute [r] bridge
+        # @return [Thing, nil]
+        def bridge
+          bridge_uid && EntityLookup.lookup_thing(bridge_uid)
+        end
+
         # @return [String]
         def inspect
           r = "#<OpenHAB::Core::Things::Thing #{uid}"

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

@@ -26,7 +26,7 @@ module OpenHAB
         def eql?(other)
           return false unless other.instance_of?(self.class)
 
-          to_s.compare_to(other.to_s).zero?
+          to_s == other.to_s
         end
 
         #

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# @deprecated OH4.0 this guard is not needed on OH4.1
+return unless OpenHAB::Core.version >= OpenHAB::Core::V4_1
+
+require "forwardable"
+
+module OpenHAB
+  module Core
+    module Types
+      TimeSeries = org.openhab.core.types.TimeSeries
+
+      #
+      # {TimeSeries} is used to transport a set of states together with their timestamp.
+      #
+      # The states are sorted chronologically. The entries can be accessed like an array.
+      #
+      # @since openHAB 4.1
+      #
+      # @example
+      #   time_series = TimeSeries.new # defaults to :add policy
+      #                           .add(Time.at(2), DecimalType.new(2))
+      #                           .add(Time.at(1), DecimalType.new(1))
+      #                           .add(Time.at(3), DecimalType.new(3))
+      #   logger.info "first entry: #{time_series.first.state}" # => 1
+      #   logger.info "last entry: #{time_series.last.state}" # => 3
+      #   logger.info "second entry: #{time_series[1].state}" # => 2
+      #   logger.info "sum: #{time_series.sum(&:state)}" # => 6
+      #
+      # @see DSL::Rules::BuilderDSL#time_series_updated #time_series_updated rule trigger
+      #
+      class TimeSeries
+        extend Forwardable
+
+        # @!attribute [r] policy
+        #   Returns the persistence policy of this series.
+        #   @see org.openhab.core.types.TimeSeries#getPolicy()
+        #   @return [org.openhab.core.types.TimeSeries.Policy]
+
+        # @!attribute [r] begin
+        #   Returns the timestamp of the first element in this series.
+        #   @return [Instant]
+
+        # @!attribute [r] end
+        #   Returns the timestamp of the last element in this series.
+        #   @return [Instant]
+
+        # @!attribute [r] size
+        #   Returns the number of elements in this series.
+        #   @return [Integer]
+
+        #
+        # Create a new instance of TimeSeries
+        #
+        # @param [:add, :replace, org.openhab.core.types.TimeSeries.Policy] policy
+        #   The persistence policy of this series.
+        #
+        def initialize(policy = :replace)
+          policy = Policy.value_of(policy.to_s.upcase) if policy.is_a?(Symbol)
+          super
+        end
+
+        # Returns true if the series' policy is `ADD`.
+        # @return [true,false]
+        def add?
+          policy == Policy::ADD
+        end
+
+        # Returns true if the series' policy is `REPLACE`.
+        # @return [true,false]
+        def replace?
+          policy == Policy::REPLACE
+        end
+
+        # @!visibility private
+        def inspect
+          "#<OpenHAB::Core::Types::TimeSeries " \
+            "policy=#{policy} " \
+            "begin=#{self.begin} " \
+            "end=#{self.end} " \
+            "size=#{size}>"
+        end
+
+        #
+        # Returns the content of this series.
+        # @return [Array<org.openhab.core.types.TimeSeries.Entry>]
+        #
+        def states
+          get_states.to_array.to_a.freeze
+        end
+
+        # rename raw methods so we can overwrite them
+        # @!visibility private
+        alias_method :add_instant, :add
+
+        #
+        # Adds a new element to this series.
+        #
+        # Elements can be added in an arbitrary order and are sorted chronologically.
+        #
+        # @note This method returns self so it can be chained, unlike the Java version.
+        #
+        # @param [Instant, #to_zoned_date_time, #to_instant] instant An instant for the given state.
+        # @param [State, String, Numeric] state The State at the given timestamp.
+        #   If a String is given, it will be converted to {StringType}.
+        #   If a {Numeric} is given, it will be converted to {DecimalType}.
+        # @return [self]
+        # @raise [ArgumentError] if state is not a {State}, String or {Numeric}
+        #
+        def add(instant, state)
+          instant = instant.to_zoned_date_time if instant.respond_to?(:to_zoned_date_time)
+          instant = instant.to_instant if instant.respond_to?(:to_instant)
+          state = case state
+                  when State then state
+                  when String then StringType.new(state)
+                  when Numeric then DecimalType.new(state)
+                  else
+                    raise ArgumentError, "state must be a State, String or Numeric, but was #{state.class}"
+                  end
+          add_instant(instant, state)
+          self
+        end
+
+        # any method that exists on Array gets forwarded to states
+        delegate (Array.instance_methods - instance_methods) => :states
+      end
+    end
+  end
+end
+
+TimeSeries = OpenHAB::Core::Types::TimeSeries unless Object.const_defined?(:TimeSeries)

data/lib/openhab/core.rb

@@ -7,7 +7,20 @@ module OpenHAB
     # @return [String]
     VERSION = org.openhab.core.OpenHAB.version.freeze
 
-    raise "`openhab-scripting` requires openHAB >= 3.4.0" unless Gem::Version.new(VERSION) >= Gem::Version.new("3.4.0")
+    # @!visibility private
+    V4_0 = Gem::Version.new("4.0.0").freeze
+    # @!visibility private
+    V4_1 = Gem::Version.new("4.1.0").freeze
+    # @!visibility private
+    V4_2 = Gem::Version.new("4.2.0").freeze
+
+    # @return [Gem::Version] Returns the current openHAB version as a Gem::Version object
+    # @!visibility private
+    def self.version
+      @version ||= Gem::Version.new(VERSION).freeze
+    end
+
+    raise "`openhab-scripting` requires openHAB >= 3.4.0" unless version >= Gem::Version.new("3.4.0")
 
     # @return [Integer] Number of seconds to wait between checks for automation manager
     CHECK_DELAY = 10

data/lib/openhab/core_ext/java/instant.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module CoreExt
+    module Java
+      java_import java.time.Instant
+
+      # Extensions to {java.time.Instant}
+      class Instant < java.lang.Object; end
+    end
+  end
+end
+
+Instant = OpenHAB::CoreExt::Java::Instant unless Object.const_defined?(:Instant)

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

@@ -672,7 +672,6 @@ module OpenHAB
         # @param (see ItemBuilder#initialize)
         def initialize(*args, type: nil, function: nil, thing: nil, **kwargs)
           raise ArgumentError, "invalid function #{function}" if function && !function.match?(FUNCTION_REGEX)
-          raise ArgumentError, "state cannot be set on GroupItems" if kwargs[:state]
 
           super(type, *args, **kwargs)
           @function = function

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

@@ -74,6 +74,7 @@ module OpenHAB
         end
 
         Core::Items::GenericItem.prepend(self)
+        Core::Items::GroupItem.prepend(self)
 
         #
         # Sends command to an item for specified duration, then on timer expiration sends