openhab-scripting 5.15.1 → 5.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2150062e6b4a58f888b09bb106f39cb57c7e67749b85dfc13978a8437702e33
-  data.tar.gz: 22cfc6729962a702bae8ecc83d26280e4967834a8235bd7ee9ac8f3596796f50
+  metadata.gz: ecc05f177e95b3a962f2b1fac6f924c5af5d6c49ed8a7e38d896c03417fe9e23
+  data.tar.gz: 408fa59899bb838caa9a6f3fc80ef82a4051c03fc590249ab53e0a098c5f335d
 SHA512:
-  metadata.gz: bfab71ec2435493bafdf61bf447a34a644e366494a9ccdf174a98d9035b1cc8fd9828ca174c5288d2c41a5798cb6ea2bad8bd78f492cb5564f0f3cbf6fcf7023
-  data.tar.gz: 36ff08d089054720805effeb0fa16557b767a87b8238c45d7c3c2e5d5fc12ac0dffae5b0f2f7226435e68c5ddfb03a252a8ad12e680f422695040869865716cb
+  metadata.gz: ccbc0e426427d262cd1f2a5ed671979f5644b4c5b0da5ff34958254de6221283a9420e2b3c45384ac5aafc7feeffd41fa54740f76c4d99ccaa8adba207c32d52
+  data.tar.gz: 9f9a5f3b120a838f151a1f8edf5e1400f1df0a183cef5a47b921bc661889231c1b186ce2830f8cf7349ab3f89b166de5e1ffc89675628dba21799740b9029cc6

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.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
@@ -607,22 +604,31 @@ module Enumerable
   # @!group Filtering Methods
   #
 
-  # Returns a new array of items that are a semantics Location (optionally of the given type)
+  #
+  # Returns a new array of items that are a semantics Location (optionally of one of the given types)
   # @return [Array<Item>]
-  def locations(type = nil)
+  #
+  # @example Get all rooms
+  #   items.locations(Semantics::Room)
+  #
+  # @example Get all bedrooms and bathrooms
+  #   items.locations(Semantics::Bedroom, Semantics::Bathroom)
+  #
+  def locations(*types)
     begin
-      raise ArgumentError if type && !(type < Semantics::Location)
+      raise ArgumentError unless types.all? { |type| type < Semantics::Location }
     rescue ArgumentError, TypeError
       raise ArgumentError, "type must be a subclass of Location"
     end
 
     result = select(&:location?)
-    result.select! { |i| i.location_type <= type } if type
+    result.select! { |i| types.any? { |type| i.location_type <= type } } unless types.empty?
 
     result
   end
 
-  # Returns a new array of items that are a semantics equipment (optionally of the given type)
+  #
+  # Returns a new array of items that are a semantics equipment (optionally of one of the given types)
   #
   # @note As {Semantics::Equipment equipments} are usually
   #   {GroupItem GroupItems}, this method therefore returns an array of
@@ -633,16 +639,20 @@ module Enumerable
   # @return [Array<Item>]
   #
   # @example Get all TVs in a room
-  #   lGreatRoom.equipments(Semantics::Screen)
-  def equipments(type = nil)
+  #   lGreatRoom.equipments(Semantics::Television)
+  #
+  # @example Get all TVs and Speakers in a room
+  #   lGreatRoom.equipments(Semantics::Television, Semantics::Speaker)
+  #
+  def equipments(*types)
     begin
-      raise ArgumentError if type && !(type < Semantics::Equipment)
+      raise ArgumentError unless types.all? { |type| type < Semantics::Equipment }
     rescue ArgumentError, TypeError
       raise ArgumentError, "type must be a subclass of Equipment"
     end
 
     result = select(&:equipment?)
-    result.select! { |i| i.equipment_type <= type } if type
+    result.select! { |i| types.any? { |type| i.equipment_type <= type } } unless types.empty?
 
     result
   end
@@ -663,8 +673,8 @@ module Enumerable
 
     begin
       raise ArgumentError unless point_or_property_types.all? do |tag|
-                                   (tag < Semantics::Point ||
-                                    tag < Semantics::Property)
+                                   tag < Semantics::Point ||
+                                   tag < Semantics::Property
                                  end
     rescue ArgumentError, TypeError
       raise ArgumentError, "point_or_property_types must all be a subclass of Point or Property"

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/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

@@ -137,7 +137,7 @@ module OpenHAB
         #
 
         ThingStatus.constants.each do |thingstatus|
-          define_method("#{thingstatus.to_s.downcase}?") { status == ThingStatus.value_of(thingstatus) }
+          define_method(:"#{thingstatus.to_s.downcase}?") { status == ThingStatus.value_of(thingstatus) }
         end
 
         #
@@ -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/time_series.rb

@@ -0,0 +1,121 @@
+# 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] state The State at the given timestamp.
+        # @return [self]
+        #
+        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)
+          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/core_ext/java/list.rb

@@ -311,7 +311,7 @@ module Java::JavaUtil::List # rubocop:disable Style/ClassAndModuleChildren
   end
 
   def rotate!(count = 1)
-    count = count % length
+    count %= length
     push(*shift(count))
     self
   end

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

@@ -125,7 +125,7 @@ module OpenHAB
             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?
+              parameter.send(:"with_#{key}", value) unless value.nil?
             end
             parameter.build
           end