openhab-scripting 5.25.0 → 5.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd540981ebe38c1c9caa47519ef602482ae3f3f9fb9bdfce0c9f7f82e8354e7
-  data.tar.gz: f41c35b263ae2806eb7bd0e5c921cf77992c772165b3dd772515f6208682b20e
+  metadata.gz: 59deb6289921c0c6d35579783efbb35f75ceac9ff24922e0f74d6652ef575b59
+  data.tar.gz: 260ee0993a3ab89775d9b5a2e8f3e40f295dd16ad8f0adf3b003b521cb08a12e
 SHA512:
-  metadata.gz: 15c663deb2da069fb03179638b89d7df1068c5dd1f7b16312dce90c81d97a8b949c6b60208855ea2b7c4ec6210aa2dca57ec7a29dc8ddc5abb3cc4ffe7ac4572
-  data.tar.gz: 67043ce7f88d1c5cacb92f2cb172b7faaeb376d0ad2258901b603e61241e70732f41f5c2abcc05880daac2446fe9031f298112910c29bb69ffbdf81e18c760bc
+  metadata.gz: 127b6e33961395b973b8aa543940502530101f30e15526aa598b574e8d3a05ec82c65d79fd0d0d6176a2aa57aed8f244fbd480c76457e3440f94503f92028530
+  data.tar.gz: 4949521fcc45fdb1dba17a09c960d4a5e7afd2c964328a9fd8b66b11ac2c773c7e413e6ec2d797f9e6d9f8e9130297c9700af4d46bf968ec064b0dfa2ea6eb32

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

@@ -47,7 +47,15 @@ module OpenHAB
         def format_type(command)
           return command if command.is_a?(Types::DateTimeType)
           return Types::DateTimeType.new(command.to_zoned_date_time) if command.respond_to?(:to_zoned_date_time)
-          return Types::DateTimeType.new(DSL.try_parse_time_like(command.to_str)) if command.respond_to?(:to_str)
+
+          if command.respond_to?(:to_str)
+            command = command.to_str
+            begin
+              return Types::DateTimeType.new(DSL.try_parse_time_like(command))
+            rescue ArgumentError
+              return Types::DateTimeType.new(command)
+            end
+          end
 
           super
         end

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

@@ -176,6 +176,31 @@ module OpenHAB
         #   @return [DecimalType, QuantityType, nil] The standard deviation between `start` and `finish`,
         #     or nil if no states could be found.
 
+        # @!method median_since(timestamp, service = nil)
+        #   Returns the median of the item's state since the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The median since `timestamp`,
+        #     or nil if no previous states could be found.
+        #   @since openHAB 4.3
+
+        # @!method median_until(timestamp, service = nil)
+        #   Returns the median of the item's state beetween now until the given time
+        #   @param [#to_zoned_date_time] timestamp The point in time until which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The median until `timestamp`,
+        #     or nil if no future states could be found.
+        #   @since openHAB 4.3
+
+        # @!method median_between(start, finish, service = nil)
+        #   Returns the median of the item's state between two points in time
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The median between `start` and `finish`,
+        #     or nil if no states could be found.
+        #   @since openHAB 4.3
+
         # @!method sum_since(timestamp, service = nil)
         #   Returns the sum of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
@@ -661,6 +686,7 @@ module OpenHAB
         end
 
         def_persistence_methods(:average, quantify: true)
+        def_persistence_methods(:median, quantify: true) if OpenHAB::Core.version >= OpenHAB::Core::V4_3
         def_persistence_methods(:delta, quantify: true)
         def_persistence_methods(:deviation, quantify: true)
         def_persistence_methods(:sum, quantify: true)

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

@@ -97,6 +97,13 @@ module OpenHAB
           __getobj__.members
         end
 
+        # @return [String]
+        def to_s
+          return name if __getobj__.nil?
+
+          __getobj__.to_s
+        end
+
         # @return [String]
         def inspect
           return super unless __getobj__.nil?

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

@@ -12,9 +12,8 @@ module OpenHAB
       # Provides sitemaps created in Ruby to openHAB
       #
       class Provider < Core::Provider
-        PREFIX = "jruby_"
         SUFFIX = ".sitemap"
-        private_constant :PREFIX, :SUFFIX
+        private_constant :SUFFIX
 
         class << self
           # @!visibility private
@@ -49,6 +48,7 @@ module OpenHAB
 
         # @!visibility private
         def unregister
+          clear
           @registration.unregister
         end
 
@@ -150,13 +150,30 @@ module OpenHAB
           end
         end
 
+        #
+        # Notify listeners about updated sitemap
+        #
+        # @param [String, org.openhab.core.model.sitemap.sitemap.Sitemap] sitemap The sitemap to update.
+        # @return [void]
+        #
+        def update(sitemap)
+          if sitemap.respond_to?(:to_str)
+            sitemap = get(sitemap).tap do |obj|
+              raise ArgumentError, "Sitemap #{sitemap} not found" unless obj
+            end
+          end
+          super
+        end
+
         #
         # Remove a sitemap.
         #
-        # @param [String] sitemap_name
+        # @param [String, org.openhab.core.model.sitemap.sitemap.Sitemap] sitemap
         # @return [Boolean] If a sitemap was removed
-        def remove(sitemap_name)
-          super("#{PREFIX}#{sitemap_name}#{SUFFIX}")
+        #
+        def remove(sitemap)
+          sitemap = sitemap.uid if sitemap.respond_to?(:uid)
+          super
         end
 
         private
@@ -169,15 +186,24 @@ module OpenHAB
         end
 
         def notify_listeners_about_added_element(element)
-          @listeners.each { |l| l.model_changed(element.name, org.openhab.core.model.core.EventType::ADDED) }
+          model_name = "#{element.name}#{SUFFIX}"
+          @listeners.each do |l|
+            l.modelChanged(model_name, org.openhab.core.model.core.EventType::ADDED)
+            # Ensure that when a script is reloaded, the sitemap is updated.
+            # This is because our listener, org.openhab.core.io.rest.sitemap.SitemapSubscriptionService
+            # only handles MODIFIED events in its modelChanged() method.
+            l.modelChanged(model_name, org.openhab.core.model.core.EventType::MODIFIED)
+          end
         end
 
         def notify_listeners_about_removed_element(element)
-          @listeners.each { |l| l.model_changed(element.name, org.openhab.core.model.core.EventType::REMOVED) }
+          model_name = "#{element.name}#{SUFFIX}"
+          @listeners.each { |l| l.modelChanged(model_name, org.openhab.core.model.core.EventType::REMOVED) }
         end
 
         def notify_listeners_about_updated_element(_old_element, element)
-          @listeners.each { |l| l.model_changed(element.name, org.openhab.core.model.core.EventType::MODIFIED) }
+          model_name = "#{element.name}#{SUFFIX}"
+          @listeners.each { |l| l.modelChanged(model_name, org.openhab.core.model.core.EventType::MODIFIED) }
         end
       end
     end

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

@@ -30,6 +30,14 @@ module OpenHAB
       #   # replace ':' with '_' in thing uid
       #   mqtt_broker_mosquitto.online? # is mqtt:broker:mosquitto thing online?
       #
+      # @!attribute label
+      #   Return the thing label
+      #   @return [String]
+      #
+      # @!attribute location
+      #   Return the thing location
+      #   @return [String]
+      #
       # @!attribute [r] status
       #   Return the {https://www.openhab.org/docs/concepts/things.html#thing-status thing status}
       #   @return [org.openhab.core.thing.ThingStatus]
@@ -43,7 +51,7 @@ module OpenHAB
       #
       # @!attribute [r] bridge_uid
       #   Return the Bridge UID when available.
-      #   @return [ThingUID]
+      #   @return [ThingUID, nil]
       #
       # @!attribute [r] thing_type_uid
       #   @return [ThingTypeUID]

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

@@ -18,7 +18,13 @@ module OpenHAB
         remove_method :==
 
         extend Forwardable
-        include Comparable
+
+        # @deprecated OH 4.2 DateTimeType implements Java's Comparable interface in openHAB 4.3
+        if OpenHAB::Core.version >= OpenHAB::Core::V4_3
+          include ComparableType
+        else
+          include Comparable
+        end
 
         #
         # Regex expression to identify strings defining a time in hours, minutes and optionally seconds

data/lib/openhab/core.rb

@@ -13,6 +13,8 @@ module OpenHAB
     V4_1 = Gem::Version.new("4.1.0").freeze
     # @!visibility private
     V4_2 = Gem::Version.new("4.2.0").freeze
+    # @!visibility private
+    V4_3 = Gem::Version.new("4.3.0").freeze
 
     # @return [Gem::Version] Returns the current openHAB version as a Gem::Version object
     #   Note, this strips off snapshots, milestones and RC versions and returns the release version.

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

@@ -1302,6 +1302,10 @@ module OpenHAB
         #   If `value` is `:day`, `at` can be a {Core::Items::DateTimeItem DateTimeItem}, and
         #   the trigger will run every day at the (time only portion of) current state of the
         #   item. If the item is {NULL} or {UNDEF}, the trigger will not run.
+        # @param [Duration, Integer, nil] offset Offset the execution time from the time specified in the item.
+        #   This can be a negative value to execute the rule before the time specified in the item.
+        #   A Duration will be converted to its total length in seconds, with any excess precision information dropped.
+        #   @since openHAB 4.3
         # @param [Object] attach Object to be attached to the trigger
         # @return [void]
         #
@@ -1322,12 +1326,6 @@ module OpenHAB
         #     run { Light.on }
         #   end
         #
-        # @example Trigger at the time portion of a DateTime Item
-        #   rule "Every day at sunset" do
-        #     every :day, at: Sunset_Time
-        #     run { logger.info "It's getting dark" }
-        #   end
-        #
         # @example Specific day of the week
         #   rule "Weekly" do
         #     every :monday, at: '5:15'
@@ -1372,8 +1370,21 @@ module OpenHAB
         #     run { logger.info "It's the weekend!" }
         #   end
         #
-        def every(*values, at: nil, attach: nil)
+        # @example Trigger at the time portion of a DateTime Item
+        #   rule "Every day at sunset" do
+        #     every :day, at: Sunset_Time
+        #     run { logger.info "It's sunset!" }
+        #   end
+        #
+        # @example Using DateTime trigger with offset
+        #   rule "Every day before sunset" do
+        #     every :day, at: Sunset_Time, offset: -20.minutes
+        #     run { logger.info "It's almost sunset!" }
+        #   end
+        #
+        def every(*values, at: nil, offset: nil, attach: nil)
           raise ArgumentError, "Missing values" if values.empty?
+          raise ArgumentError, "Offset can only be used when 'at' is given a DateTimeItem" if offset && !at.is_a?(Item)
 
           if Cron.all_dow_symbols?(values)
             @ruby_triggers << [:every, values.join(", "), { at: at }]
@@ -1397,7 +1408,10 @@ module OpenHAB
               raise ArgumentError, "Attachments are not supported with dynamic datetime triggers in openHAB 3.x"
             end
 
-            return trigger("timer.DateTimeTrigger", itemName: at.name, timeOnly: true, attach: attach)
+            offset ||= 0
+            offset = offset.to_i # Duration#to_i converts it to seconds, but we also want to convert float/string to int
+            @ruby_triggers.last[2][:offset] = offset
+            return trigger("timer.DateTimeTrigger", itemName: at.name, timeOnly: true, offset: offset, attach: attach)
           end
 
           cron_expression = case value
@@ -1797,6 +1811,10 @@ module OpenHAB
         # The `event` passed to run blocks will be a {Core::Events::TimerEvent}.
         #
         # @param [Item, String, Symbol] item The item (or its name)
+        # @param [Duration, Integer, nil] offset Offset the execution time from the time specified in the item.
+        #   This can be a negative value to execute the rule before the time specified in the item.
+        #   A Duration will be converted to its total length in seconds, with any excess precision information dropped.
+        #   @since openHAB 4.3
         # @return [void]
         #
         # @see every
@@ -1817,9 +1835,18 @@ module OpenHAB
         #     end
         #   end
         #
-        def at(item)
+        # @example Using an offset
+        #   rule "Turn on lights 15 minutes before sunset" do
+        #     at Sunset_Time, offset: -15.minutes
+        #     run { Lights.on }
+        #   end
+        #
+        def at(item, offset: nil)
           item = item.name if item.is_a?(Item)
-          trigger("timer.DateTimeTrigger", itemName: item.to_s)
+          offset ||= 0
+          offset = offset.to_i if offset.is_a?(Duration)
+          @ruby_triggers << [:at, item, { offset: offset }]
+          trigger("timer.DateTimeTrigger", itemName: item.to_s, offset: offset)
         end
 
         #

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

@@ -8,21 +8,6 @@ module OpenHAB
       # Contains helper methods for inferring a rule name from its triggers
       # @!visibility private
       module NameInference
-        # Trigger Type UIDs that we know how to generate a name for
-        KNOWN_TRIGGER_TYPES = [
-          "core.ChannelEventTrigger",
-          "core.GenericEventTrigger",
-          "core.GroupCommandTrigger",
-          "core.GroupStateChangeTrigger",
-          "core.GroupStateUpdateTrigger",
-          "core.ItemCommandTrigger",
-          "core.ItemStateChangeTrigger",
-          "core.ItemStateUpdateTrigger",
-          "core.SystemStartlevelTrigger",
-          Triggers::Cron::CRON_TRIGGER_MODULE_ID
-        ].freeze
-        private_constant :KNOWN_TRIGGER_TYPES
-
         class << self
           # get the block's source location, and simplify to a simple filename
           def infer_rule_id_from_block(block)
@@ -33,24 +18,14 @@ module OpenHAB
 
           # formulate a readable rule name such as "TestSwitch received command ON" if possible
           def infer_rule_name(config)
-            known_triggers, unknown_triggers = config.triggers.partition do |t|
-              KNOWN_TRIGGER_TYPES.include?(t.type_uid)
-            end
-            return nil unless unknown_triggers.empty?
-
-            cron_triggers = known_triggers.select { |t| t.type_uid == "jsr223.jruby.CronTrigger" }
-            ruby_every_triggers = config.ruby_triggers.select { |t| t.first == :every }
-
-            # makes sure there aren't any true cron triggers cause we can't format them
-            return nil unless cron_triggers.length == ruby_every_triggers.length
-            return nil unless config.ruby_triggers.length == 1
-
-            infer_rule_name_from_trigger(*config.ruby_triggers.first)
+            infer_rule_name_from_trigger(*config.ruby_triggers.first) if config.ruby_triggers.length == 1
           end
 
           # formulate a readable rule name from a single trigger if possible
           def infer_rule_name_from_trigger(trigger, items = nil, kwargs = {})
             case trigger
+            when :at
+              infer_rule_name_from_at_trigger(items, **kwargs)
             when :every
               infer_rule_name_from_every_trigger(items, **kwargs)
             when :channel
@@ -101,10 +76,18 @@ module OpenHAB
             name.freeze
           end
 
+          # formulate a readable rule name from an at-style cron trigger
+          def infer_rule_name_from_at_trigger(item, offset: nil)
+            name = "At #{item}"
+            name += format_offset(offset)
+            name
+          end
+
           # formulate a readable rule name from an every-style cron trigger
-          def infer_rule_name_from_every_trigger(value, at:)
+          def infer_rule_name_from_every_trigger(value, at:, offset: nil)
             name = "Every #{value}"
             name += " at #{at}" if at
+            name += format_offset(offset)
             name
           end
 
@@ -175,6 +158,12 @@ module OpenHAB
 
             "#{array[0..-2].join(", ")}, or #{array[-1]}"
           end
+
+          def format_offset(offset)
+            return "" unless offset&.nonzero?
+
+            " #{offset.positive? ? "+" : ""}#{offset.seconds.to_s.downcase[2..]}" # Remove "PT" from the ISO8601 string
+          end
         end
       end
     end

data/lib/openhab/dsl/version.rb

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

data/lib/openhab/dsl.rb

@@ -1077,7 +1077,7 @@ module OpenHAB
       return string unless string.is_a?(String)
 
       exception = nil
-      [java.time.LocalTime, java.time.LocalDate, java.time.MonthDay, java.time.ZonedDateTime].each do |klass|
+      [java.time.LocalTime, java.time.LocalDate, java.time.MonthDay, java.time.ZonedDateTime, Time].each do |klass|
         return klass.parse(string)
       rescue ArgumentError => e
         exception ||= e

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.25.0
+  version: 5.27.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-08-20 00:00:00.000000000 Z
+date: 2024-09-08 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.17
+rubygems_version: 3.5.18
 signing_key: 
 specification_version: 4
 summary: JRuby Helper Libraries for openHAB Scripting