openhab-scripting 5.28.0 → 5.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c99d5ea37c52514af7dfa8b5316c8b8d196f46dac4fb4ce557ac01963de8bb51
-  data.tar.gz: d2ee0a5934babcd911d2584ba7e20f73164e568108657121870422fa247d6c6f
+  metadata.gz: 795ee1035ecfb1a7f38f50243ed0d28af8a578e7d586eedd97c8362d6f4cd03d
+  data.tar.gz: d1785eb66e599bb3b78a3ab473618a080bffa117a53ddaf13c506e298806d8ad
 SHA512:
-  metadata.gz: c353e9b41fb5e11e95eaf2fe8d048caf7b3aa6873c7a6017a0d099f4738a67c8b2ae1015d2a2c2248a2089ebb42d7fafecafcc5613998d39739fcf44dd77ee92
-  data.tar.gz: a54105ab52153231d2ee7871f74ae5d1743c23c18fa582a09114e15c754a0ccd86bd9772298352f7c9d4f191aa8f47b3807ca20919473f1795da4e0e3d643f2e
+  metadata.gz: 3af8371312fdf0dce313b87513db7540545639ef440358c1256f03fe8018768c33636f5aff09bcc1cdceb9a04988492921651fd4ed269f824b18a330feec8088
+  data.tar.gz: 698841f7a0fd45ca777e1561b915e9c695c309ba9ac802d7a319733f6501539959d55ce2d6ddae8fd9cbee4c35d8d089da74d74fa6011c9b6978b68028449b1c

data/lib/openhab/core/actions/notification.rb

@@ -4,14 +4,14 @@ module OpenHAB
   module Core
     module Actions
       #
-      # Provides methods for {https://next.openhab.org/addons/integrations/openhabcloud/#cloud-notification-actions
+      # Provides methods for {https://www.openhab.org/addons/integrations/openhabcloud/#cloud-notification-actions
       # openHAB Cloud Notification Actions}.
       #
       class Notification
         class << self
           #
           # Send a notification using
-          # {https://next.openhab.org/addons/integrations/openhabcloud/#cloud-notification-actions
+          # {https://www.openhab.org/addons/integrations/openhabcloud/#cloud-notification-actions
           # openHAB Cloud Notification Action}.
           #
           # @param msg [String] The message to send.
@@ -27,7 +27,7 @@ module OpenHAB
           #   Subsequent notifications using the same reference ID will
           #   update/overwrite the existing notification with the same ID.
           # @param on_click [String, nil] The action to be performed when the user clicks on the notification.
-          #   Specified using the {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax
+          #   Specified using the {https://www.openhab.org/addons/integrations/openhabcloud/#action-syntax
           #   action syntax}.
           # @param attachment [String, Item, nil] The URL of the media attachment to be displayed with the notification.
           #   This can either be a fully qualified URL, prefixed with
@@ -36,7 +36,7 @@ module OpenHAB
           #   or an image item.
           # @param buttons [Array<String>, Hash<String, String>, nil] Buttons to include in the notification.
           #   - In array form, each element is specified as `Title=$action`, where `$action` follows the
-          #   {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax action syntax}.
+          #   {https://www.openhab.org/addons/integrations/openhabcloud/#action-syntax action syntax}.
           #   - In hash form, the keys are the button titles and the values are the actions.
           #
           #   The maximum number of buttons is 3.
@@ -91,7 +91,7 @@ module OpenHAB
             tag ||= severity
             args.push(msg.to_s, icon&.to_s, tag&.to_s)
 
-            # @!deprecated OH 4.1
+            # @deprecated OH 4.1
             if Core.version >= Core::V4_2
               buttons ||= []
               buttons = buttons.map { |title, action| "#{title}=#{action}" } if buttons.is_a?(Hash)

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

@@ -34,6 +34,29 @@ module OpenHAB
           payload&.[](:itemName)&.then { |item_name| EntityLookup.lookup_item(item_name) }
         end
 
+        #
+        # @!attribute [r] time_only?
+        # @return [Boolean]
+        #   `true` when this event was triggered by a {Core::Items::DateTimeItem DateTimeItem} with `timeOnly` set.
+        #   `false` when this event wasn't triggered by a DateTimeItem or the `timeOnly` flag is not set.
+        # @see DSL::Rules::BuilderDSL::every #every trigger
+        # @see DSL::Rules::BuilderDSL::at #at trigger
+        # @since openHAB 4.3
+        #
+        def time_only?
+          !!payload&.[](:timeOnly)
+        end
+
+        #
+        # @!attribute [r] offset
+        # @return [Duration, nil] The offset from the configured time for this DateTime trigger event.
+        #   `nil` when this event wasn't triggered by a DateTime trigger.
+        # @since openHAB 4.3
+        #
+        def offset
+          payload&.[](:offset)&.seconds
+        end
+
         #
         # @!attribute [r] time
         # @return [LocalTime, nil] The configured time for this TimeOfDay trigger event.

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

@@ -51,6 +51,17 @@ module OpenHAB
           zoned_date_time
         end
 
+        # @!visibility private
+        def to_instant(_context = nil)
+          # @deprecated OH 3.4 getInstant() was added in OH 4.0
+          return get_instant if respond_to?(:get_instant)
+
+          zoned_date_time.to_instant
+        end
+
+        # @!method to_instant
+        # @return [Instant]
+
         # act like a Ruby Time
         def_delegator :zoned_date_time, :month_value, :month
         def_delegator :zoned_date_time, :day_of_month, :mday

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

@@ -1,12 +1,148 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
+require_relative "time"
+
 module OpenHAB
   module CoreExt
     module Java
-      java_import java.time.Instant
+      Instant = java.time.Instant
 
       # Extensions to {java.time.Instant}
-      class Instant < java.lang.Object; end
+      class Instant < java.lang.Object
+        extend Forwardable
+        include Time
+        include Between
+
+        class << self # rubocop:disable Lint/EmptyClass
+          # @!scope class
+
+          # @!attribute [r] now
+          #   @return [Instant]
+
+          # @!method parse(text, formatter = nil)
+          #   Parses a string into an Instant object.
+          #
+          #   @param [String] text The text to parse.
+          #   @param [java.time.format.DateTimeFormatter] formatter The formatter to use.
+          #   @return [Instant]
+        end
+
+        # @!scope instance
+
+        # @!method to_local_time
+        #   @return [LocalTime]
+        # @!method to_local_date
+        #   @return [LocalDate]
+        # @!method to_month_day
+        #   @return [MonthDay]
+        # @!method to_date
+        #   @return [Date]
+        # @!method to_month
+        #   @return [Month]
+        # @!method yesterday?
+        #   (see OpenHAB::CoreExt::Java::ZonedDateTime#yesterday?)
+        # @!method today?
+        #   (see OpenHAB::CoreExt::Java::ZonedDateTime#today?)
+        # @!method tomorrow?
+        #   (see OpenHAB::CoreExt::Java::ZonedDateTime#tomorrow?)
+        def_delegators :to_zoned_date_time,
+                       :to_local_time,
+                       :to_local_date,
+                       :to_date,
+                       :to_month_day,
+                       :to_month,
+                       :yesterday?,
+                       :today?,
+                       :tomorrow?
+
+        # @param [TemporalAmount, #to_instant, #to_zoned_date_time, Numeric] other
+        #   If other is a Numeric, it's interpreted as seconds.
+        # @return [Duration] If other responds to #to_zoned_date_time
+        # @return [Instant] If other is a TemporalAmount
+        def -(other)
+          if other.is_a?(Instant)
+            java.time.Duration.between(other, self)
+          elsif other.respond_to?(:to_instant)
+            java.time.Duration.between(other.to_instant, self)
+          elsif other.respond_to?(:to_zoned_date_time)
+            java.time.Duration.between(other.to_zoned_date_time.to_instant, self)
+          elsif other.is_a?(Numeric)
+            minus(other.seconds)
+          else
+            minus(other)
+          end
+        end
+
+        # @param [TemporalAmount, Numeric] other
+        #   If other is a Numeric, it's interpreted as seconds.
+        # @return [Instant]
+        def +(other)
+          return plus(other.seconds) if other.is_a?(Numeric)
+
+          plus(other)
+        end
+
+        #
+        # The number of seconds since the Unix epoch.
+        # @return [Integer]
+        #
+        def to_i
+          epoch_second
+        end
+
+        #
+        # The number of seconds since the Unix epoch.
+        # @return [Float]
+        #
+        def to_f
+          ((epoch_second * 1_000_000_000) + nano).fdiv(1_000_000_000.0)
+        end
+
+        # This comes from JRuby
+
+        # @!method to_time
+        #   @return [Time]
+
+        # @return [Integer, nil]
+        def <=>(other)
+          logger.trace { "(#{self.class}) #{self} <=> #{other} (#{other.class})" }
+          # compare instants, otherwise it will differ by timezone, which we don't want
+          # (use eql? if you care about that)
+          if other.respond_to?(:to_instant)
+            logger.trace { "Comparing #{self} to #{other.to_instant}" }
+            compare_to(other.to_instant(to_zoned_date_time))
+          elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(self))
+            lhs <=> rhs
+          end
+        end
+
+        # @param [ZonedDateTime, nil] context A {ZonedDateTime} used to match the zone id. Defaults to UTC.
+        # @return [ZonedDateTime]
+        def to_zoned_date_time(context = nil)
+          zone = context&.zone || java.time.ZoneOffset::UTC
+          at_zone(zone)
+        end
+
+        # @!visibility private
+        def to_instant(_context = nil)
+          self
+        end
+
+        #
+        # Converts `other` to {Instant}, if possible
+        #
+        # @param [#to_instant] other
+        # @return [Array, nil]
+        #
+        def coerce(other)
+          logger.trace { "Coercing #{self} as a request from #{other.class}" }
+          return [other.to_instant(to_zoned_date_time), self] if other.respond_to?(:to_instant)
+
+          [other.to_zoned_date_time(zoned_date_time).to_instant, self] if other.respond_to?(:to_zoned_date_time)
+        end
+      end
     end
   end
 end

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

@@ -96,6 +96,15 @@ module OpenHAB
           zone = context&.zone || java.time.ZoneId.system_default
           at_start_of_day(zone)
         end
+
+        # @param [ZonedDateTime, nil] context
+        #   A {ZonedDateTime} used to fill in missing fields
+        #   during conversion. {ZonedDateTime.now} is assumed if not given.
+        # @return [Instant]
+        def to_instant(context = nil)
+          zone = context&.zone || java.time.ZoneOffset::UTC
+          at_start_of_day(zone).to_instant
+        end
       end
     end
   end

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

@@ -111,6 +111,15 @@ module OpenHAB
           context ||= ZonedDateTime.now
           context.with(self)
         end
+
+        # @param [ZonedDateTime, nil] context
+        #   A {ZonedDateTime} used to fill in missing fields
+        #   during conversion. {ZonedDateTime.now} is assumed if not given.
+        # @return [Instant]
+        def to_instant(context = nil)
+          context ||= Instant.now.to_zoned_date_time
+          to_zoned_date_time(context).to_instant
+        end
       end
     end
   end

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

@@ -62,6 +62,16 @@ module OpenHAB
         def to_zoned_date_time(context = nil)
           to_local_date(context).to_zoned_date_time(context)
         end
+
+        # @param [ZonedDateTime, nil] context
+        #   A {ZonedDateTime} used to fill in the year during conversion,
+        #   with the date set to the first day of the month.
+        #   {Instant.now} is assumed if not given.
+        # @return [Instant]
+        def to_instant(context = nil)
+          context ||= Instant.now.to_zoned_date_time
+          to_local_date(context).to_instant
+        end
       end
     end
   end

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

@@ -112,6 +112,15 @@ module OpenHAB
         def to_zoned_date_time(context = nil)
           to_local_date(context).to_zoned_date_time(context)
         end
+
+        # @param [ZonedDateTime, nil] context
+        #   A {ZonedDateTime} used to fill in missing year during conversion,
+        #   {ZonedDateTime.now} is assumed if not given.
+        # @return [Instant]
+        def to_instant(context = nil)
+          context ||= Instant.now.to_zoned_date_time
+          to_local_date(context).to_instant
+        end
       end
     end
   end

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

@@ -38,6 +38,7 @@ module OpenHAB
         #   less than, equal to, or greater than self
         #
         def <=>(other)
+          logger.trace { "(#{self.class}) #{self} <=> #{other} (#{other.class})" }
           if other.is_a?(self.class)
             compare_to(other)
           elsif other.respond_to?(:coerce)
@@ -50,6 +51,7 @@ module OpenHAB
         # Convert `other` to this class, if possible
         # @return [Array, nil]
         def coerce(other)
+          logger.trace { "Coercing #{self} as a request from #{other.class}" }
           coercion_method = self.class.coercion_method
           return unless other.respond_to?(coercion_method)
           return [other.send(coercion_method), self] if other.method(coercion_method).arity.zero?

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 require_relative "time"
 
 module OpenHAB
@@ -9,6 +11,7 @@ module OpenHAB
 
       # Extensions to {java.time.ZonedDateTime}
       class ZonedDateTime
+        extend Forwardable
         include Time
         include Between
 
@@ -60,20 +63,20 @@ module OpenHAB
         end
 
         #
+        # @!method to_i
         # The number of seconds since the Unix epoch.
         #
         # @return [Integer]
-        def to_i
-          to_instant.epoch_second
-        end
+        #
 
         #
+        # @!method to_f
         # The number of seconds since the Unix epoch.
         #
         # @return [Float]
-        def to_f
-          to_instant.to_epoch_milli / 1000.0
-        end
+        #
+
+        delegate %i[to_i to_f] => :to_instant
 
         # @return [Date]
         def to_date
@@ -103,6 +106,36 @@ module OpenHAB
           self
         end
 
+        #
+        # Returns true if the date, converted to the system time zone, is yesterday.
+        #
+        # @return [true, false]
+        #
+        def yesterday?
+          with_zone_same_instant(ZoneId.system_default).to_local_date == LocalDate.now - 1
+        end
+
+        #
+        # Returns true if the date, converted to the system time zone, is today.
+        #
+        # This is the equivalent of checking if the current datetime is between midnight and end of the day
+        # of the system time zone.
+        #
+        # @return [true, false]
+        #
+        def today?
+          with_zone_same_instant(ZoneId.system_default).to_local_date == LocalDate.now
+        end
+
+        #
+        # Returns true if the date, converted to the system time zone, is tomorrow.
+        #
+        # @return [true, false]
+        #
+        def tomorrow?
+          with_zone_same_instant(ZoneId.system_default).to_local_date == LocalDate.now + 1
+        end
+
         # @group Ephemeris Methods
         #   (see CoreExt::Ephemeris)
 
@@ -196,6 +229,20 @@ module OpenHAB
           end
         end
 
+        # @!visibility private
+        alias_method :raw_to_instant, :to_instant
+
+        # @!visibility private
+        def to_instant(_context = nil)
+          raw_to_instant
+        end
+
+        #
+        # @!method to_instant
+        # Converts this object to an {Instant}
+        # @return [Instant]
+        #
+
         #
         # Converts `other` to {ZonedDateTime}, if possible
         #
@@ -203,6 +250,7 @@ module OpenHAB
         # @return [Array, nil]
         #
         def coerce(other)
+          logger.trace { "Coercing #{self} as a request from #{other.class}" }
           [other.to_zoned_date_time(self), self] if other.respond_to?(:to_zoned_date_time)
         end
       end

data/lib/openhab/core_ext/ruby/date.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require "forwardable"
 require "date"
 
 # Extensions to Date
 class Date
+  extend Forwardable
   include OpenHAB::CoreExt::Between
   include OpenHAB::CoreExt::Ephemeris
 
@@ -53,6 +55,14 @@ class Date
     java.time.MonthDay.of(month, day)
   end
 
+  # @!method yesterday?
+  #   (see OpenHAB::CoreExt::Java::ZonedDateTime#yesterday?)
+  # @!method today?
+  #   (see OpenHAB::CoreExt::Java::ZonedDateTime#today?)
+  # @!method tomorrow?
+  #   (see OpenHAB::CoreExt::Java::ZonedDateTime#tomorrow?)
+  def_delegators :to_zoned_date_time, :yesterday?, :today?, :tomorrow?
+
   # @param [ZonedDateTime, nil] context
   #   A {ZonedDateTime} used to fill in missing fields during conversion.
   #   {OpenHAB::CoreExt::Java::ZonedDateTime.now ZonedDateTime.now} is assumed
@@ -62,6 +72,16 @@ class Date
     to_local_date.to_zoned_date_time(context)
   end
 
+  # @param [ZonedDateTime, nil] context
+  #   A {ZonedDateTime} used to fill in missing fields during conversion.
+  #   {OpenHAB::CoreExt::Java::ZonedDateTime.now ZonedDateTime.now} is assumed
+  #   if not given.
+  # @return [Instant]
+  def to_instant(context = nil)
+    context ||= Instant.now.to_zoned_date_time
+    to_zoned_date_time(context).to_instant
+  end
+
   # @return [Integer, nil]
   def compare_with_coercion(other)
     return compare_without_coercion(other) if other.is_a?(self.class)
@@ -84,6 +104,7 @@ class Date
   # @return [Array, nil]
   #
   def coerce(other)
+    logger.trace { "Coercing #{self} as a request from #{other.class}" }
     return nil unless other.respond_to?(:to_date)
     return [other.to_date, self] if other.method(:to_date).arity.zero?
 

data/lib/openhab/core_ext/ruby/date_time.rb

@@ -45,8 +45,14 @@ class DateTime < Date
     to_java(ZonedDateTime)
   end
 
+  # @return [Instant]
+  def to_instant(_context = nil)
+    to_java(Instant)
+  end
+
   # (see Time#coerce)
   def coerce(other)
+    logger.trace { "Coercing #{self} as a request from #{other.class}" }
     return unless other.respond_to?(:to_zoned_date_time)
 
     zdt = to_zoned_date_time

data/lib/openhab/core_ext/ruby/time.rb

@@ -84,6 +84,14 @@ class Time
     java.time.MonthDay.of(month, day)
   end
 
+  # @!method yesterday?
+  #   (see OpenHAB::CoreExt::Java::ZonedDateTime#yesterday?)
+  # @!method today?
+  #   (see OpenHAB::CoreExt::Java::ZonedDateTime#today?)
+  # @!method tomorrow?
+  #   (see OpenHAB::CoreExt::Java::ZonedDateTime#tomorrow?)
+  def_delegators :to_zoned_date_time, :yesterday?, :today?, :tomorrow?
+
   # @param [ZonedDateTime, nil] context
   #   A {ZonedDateTime} used to fill in missing fields
   #   during conversion. Not used in this class.
@@ -92,8 +100,8 @@ class Time
     to_java(java.time.ZonedDateTime)
   end
 
-  # @return [java.time.Instant]
-  def to_instant
+  # @return [Instant]
+  def to_instant(_context = nil)
     to_java(java.time.Instant)
   end
 
@@ -105,6 +113,7 @@ class Time
   # @return [Array, nil]
   #
   def coerce(other)
+    logger.trace { "Coercing #{self} as a request from #{other.class}" }
     return unless other.respond_to?(:to_zoned_date_time)
 
     zdt = to_zoned_date_time

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

@@ -85,7 +85,11 @@ module OpenHAB
           # @return [void]
           #
           def resume
-            self.resolution = nil
+            if expired?
+              logger.warn "Cannot resume a timed command that has expired. Use reschedule instead."
+            else
+              self.resolution = nil
+            end
           end
         end
 
@@ -216,22 +220,25 @@ module OpenHAB
           DSL.after(duration) do
             timed_command_details.mutex.synchronize do
               logger.trace "Timed command expired - #{timed_command_details}"
+              DSL.rules[timed_command_details.rule_uid].disable
               timed_command_details.resolution = :expired
               case timed_command_details.on_expire
               when Proc
                 logger.trace "Invoking block #{timed_command_details.on_expire} after timed command for #{name} expired"
                 timed_command_details.on_expire.call(timed_command_details)
-                if timed_command_details.resolution.nil?
-                  logger.trace { "Block rescheduled the timer to #{timed_command_details.timer.execution_time}" }
-                end
               when Core::Types::UnDefType
                 update(timed_command_details.on_expire)
               else
                 command(timed_command_details.on_expire)
               end
+              # The on_expire block can call timed_command_details.reschedule, which sets resolution to nil
+              # to prevent removal of the timed command
               if timed_command_details.resolution
                 DSL.rules.remove(timed_command_details.rule_uid)
                 TimedCommand.timed_commands.delete(timed_command_details.item)
+              else
+                DSL.rules[timed_command_details.rule_uid].enable
+                logger.trace { "Block rescheduled the timer to #{timed_command_details.timer.execution_time}" }
               end
             end
           end

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

@@ -1403,7 +1403,7 @@ module OpenHAB
           @ruby_triggers << [:every, value, { at: at }]
 
           if value == :day && at.is_a?(Item)
-            # @!deprecated OH 3.4 - attachments are supported in OH 4.0+
+            # @deprecated OH 3.4 - attachments are supported in OH 4.0+
             if Core.version <= Core::V4_0 && !attach.nil?
               raise ArgumentError, "Attachments are not supported with dynamic datetime triggers in openHAB 3.x"
             end

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

@@ -1215,7 +1215,7 @@ module OpenHAB
         REQUIRED_BUTTON_ARGS = %i[row column click].freeze
         private_constant :REQUIRED_BUTTON_ARGS
 
-        # @!deprecated OH 4.1 in OH 4.1, Buttongrid is not a LinkableWidget.
+        # @deprecated OH 4.1 in OH 4.1, Buttongrid is not a LinkableWidget.
         # Pretend that the buttons property is its children so we can add to it in LinkableWidgetBuilder#build
         if (Core::V4_1...Core::V4_2).cover?(Core.version)
           java_import org.openhab.core.model.sitemap.sitemap.Buttongrid

data/lib/openhab/dsl/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.28.0
+  version: 5.29.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-09-15 00:00:00.000000000 Z
+date: 2024-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -490,7 +490,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
+rubygems_version: 3.5.19
 signing_key: 
 specification_version: 4
 summary: JRuby Helper Libraries for openHAB Scripting