openhab-scripting 5.36.2 → 5.38.0

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

@@ -1059,7 +1059,11 @@ module OpenHAB
         # {Core::Events::ThingStatusInfoChangedEvent} depending on if the
         # triggering element was an item or a thing.
         #
-        # @param [Item, GroupItem::Members, Thing, ThingUID, Things::Registry] items Objects to create trigger for.
+        # @param [Item, GroupItem::Members, Thing, ThingUID, Things::Registry, String] items
+        #   Objects to create trigger for.
+        #   When a String is provided, it is assumed to be an item or group name, unless when it
+        #   contains a colon, in which case it is assumed to be a thing UID.
+        #   The String may contain `*` and `?` wildcards since openHAB 5.0.
         # @param [State, Array<State>, #===, nil] from
         #   Only execute rule if previous state matches `from` state(s).
         # @param [State, Array<State>, #===, nil] to
@@ -1149,11 +1153,25 @@ module OpenHAB
         # @example Trigger when any Thing changes status
         #   rule "Thing status monitoring" do
         #     changed things, to: :offline
+        #     # Alternatively, you can use the following:
+        #     # changed "*:*", to: :offline
         #     run do |event|
         #       Notification.send("Thing #{event.thing.uid} is offline")
         #     end
         #   end
         #
+        # @example Use Item wildcards (since openHAB 5.0)
+        #   rule "Execute rule when the state of a matching item changed" do
+        #     changed "*_Door", to: OPEN
+        #     run { |event| logger.info("Item #{event.item.name} changed to #{event.state}") }
+        #   end
+        #
+        # @example Use Thing wildcards (since openHAB 5.0)
+        #   rule "Execute rule when a matching thing changed status" do
+        #     changed "mqtt:topic:*light*", to: :online
+        #     run { |event| logger.info("Thing #{event.thing.uid} changed to #{event.status}") }
+        #   end
+        #
         # @example Real World Example
         #   rule "Log (or notify) when an exterior door is left open for more than 5 minutes" do
         #     changed ExteriorDoors.members, to: OPEN, for: 5.minutes
@@ -1175,11 +1193,12 @@ module OpenHAB
                  Core::Things::ThingUID,
                  Core::Things::Registry,
                  Core::Items::Item,
-                 Core::Items::GroupItem::Members
+                 Core::Items::GroupItem::Members,
+                 String
               nil
             else
               raise ArgumentError,
-                    "items must be an Item, GroupItem::Members, Thing, ThingUID, or Things::Registry"
+                    "items must be an Item, GroupItem::Members, Thing, ThingUID, Things::Registry, or a String"
             end
 
             logger.trace { "Creating changed trigger for entity(#{item}), to(#{to.inspect}), from(#{from.inspect})" }
@@ -1531,7 +1550,10 @@ module OpenHAB
         # The `event` passed to run blocks will be an
         # {Core::Events::ItemCommandEvent}.
         #
-        # @param [Item, GroupItem::Members] items Items to create trigger for
+        # @param [Item, GroupItem::Members, String] items
+        #   Items to create trigger for.
+        #   When a String is provided, it is assumed to be an item or group name.
+        #   The String may contain `*` and `?` wildcards since openHAB 5.0.
         # @param [Core::Types::Command, Array<Core::Types::Command>, #===, nil] command commands to match for trigger
         # @param [Array<Core::Types::Command>, #===, nil] commands Fluent alias for `command`
         # @param [Object] attach object to be attached to the trigger
@@ -1597,6 +1619,12 @@ module OpenHAB
         #     run { |event| logger.info("Item received command: #{event.command}" ) }
         #   end
         #
+        # @example Use Item wildcards (since openHAB 5.0)
+        #   rule 'Execute rule when the matching item received command' do
+        #     received_command '*_Light', command: ON
+        #     run { |event| logger.info("Item received command: #{event.command}") }
+        #   end
+        #
         def received_command(*items, command: nil, commands: nil, attach: nil)
           command_trigger = Command.new(rule_triggers: @rule_triggers)
 
@@ -1610,10 +1638,11 @@ module OpenHAB
           items.each do |item|
             case item
             when Core::Items::Item,
-                 Core::Items::GroupItem::Members
+                 Core::Items::GroupItem::Members,
+                 String
               nil
             else
-              raise ArgumentError, "items must be an Item or GroupItem::Members"
+              raise ArgumentError, "items must be an Item, GroupItem::Members, or a String"
             end
             commands.each do |cmd|
               logger.trace { "Creating received command trigger for items #{item.inspect} and commands #{cmd.inspect}" }
@@ -1888,8 +1917,11 @@ module OpenHAB
         # {Core::Events::ThingStatusInfoEvent} depending on if the triggering
         # element was an item or a thing.
         #
-        # @param [Item, GroupItem::Members, Thing] items
+        # @param [Item, GroupItem::Members, Thing, String] items
         #   Objects to create trigger for.
+        #   When a String is provided, it is assumed to be an item or group name, unless when it
+        #   contains a colon, in which case it is assumed to be a thing UID.
+        #   The String may contain `*` and `?` wildcards since openHAB 5.0.
         # @param [State, Array<State>, Symbol, String, #===, nil] to
         #   Only execute rule if the state matches `to` state(s). If the
         #   updated element is a {Core::Things::Thing}, the `to` accepts
@@ -1964,6 +1996,19 @@ module OpenHAB
         #      run { |event| logger.info("Thing #{event.uid} status <trigger> to #{event.status}") }
         #   end
         #
+        # @example Use Item wildcards (since openHAB 5.0)
+        #   rule 'Execute rule when the state of a matching item is updated' do
+        #     updated '*_Door', to: OPEN
+        #     run { |event| logger.info("Item #{event.item.name} updated to #{event.state}") }
+        #   end
+        #
+        # @example Use Thing wildcards (since openHAB 5.0)
+        #   rule 'Execute rule when the status of a matching thing is updated' do
+        #     updated 'mqtt:topic:*light*', to: :online
+        #     # to match all things, use "*:*" as the pattern
+        #     run { |event| logger.info("Thing #{event.thing.uid} updated to #{event.status}") }
+        #   end
+        #
         def updated(*items, to: nil, attach: nil)
           updated = Updated.new(rule_triggers: @rule_triggers)
           @ruby_triggers << [:updated, items, { to: }]
@@ -1972,10 +2017,11 @@ module OpenHAB
             when Core::Things::Thing,
                  Core::Things::ThingUID,
                  Core::Items::Item,
-                 Core::Items::GroupItem::Members
+                 Core::Items::GroupItem::Members,
+                 String
               nil
             else
-              raise ArgumentError, "items must be an Item, GroupItem::Members, Thing, or ThingUID"
+              raise ArgumentError, "items must be an Item, GroupItem::Members, Thing, ThingUID, or a String"
             end
 
             logger.trace { "Creating updated trigger for item(#{item}) to(#{to})" }

data/lib/openhab/dsl/rules/triggers/changed.rb

@@ -82,8 +82,16 @@ module OpenHAB
                              thing(thing: item, from:, to:)
                            when Core::Things::Registry
                              thing(thing: "*", from:, to:)
-                           else
+                           when Core::Items::Item
                              item(item:, from:, to:)
+                           when Core::Items::Registry
+                             item(item: "*", from:, to:)
+                           else
+                             if item.to_s.include?(":")
+                               thing(thing: item, from:, to:)
+                             else
+                               item(item:, from:, to:)
+                             end
                            end
             append_trigger(type:, config:, attach:, conditions:, label:)
           end
@@ -113,7 +121,7 @@ module OpenHAB
           #  second element is a Hash configuring trigger
           #
           def item(item:, from:, to:)
-            config = { "itemName" => item.name }
+            config = { "itemName" => item.is_a?(Item) ? item.name : item.to_s }
             config["state"] = to.to_s if to
             config["previousState"] = from.to_s if from
             [ITEM_STATE_CHANGE, config]

data/lib/openhab/dsl/rules/triggers/command.rb

@@ -26,10 +26,13 @@ module OpenHAB
               command = nil
             end
 
-            type, config = if item.is_a?(GroupItem::Members)
+            type, config = case item
+                           when GroupItem::Members
                              [GROUP_COMMAND, { "groupName" => item.group.name }]
-                           else
+                           when Item
                              [ITEM_COMMAND, { "itemName" => item.name }]
+                           else
+                             [ITEM_COMMAND, { "itemName" => item.to_s }]
                            end
             config["command"] = command.to_s unless command.nil?
             append_trigger(type:, config:, attach:, conditions:)

data/lib/openhab/dsl/rules/triggers/updated.rb

@@ -29,11 +29,16 @@ module OpenHAB
             type, config = case item
                            when GroupItem::Members
                              group_update(item:, to:)
-                           when Core::Things::Thing,
-                 Core::Things::ThingUID
+                           when Core::Things::Thing, Core::Things::ThingUID
                              thing_update(thing: item, to:)
-                           else
+                           when Core::Items::Item
                              item_update(item:, to:)
+                           else
+                             if item.to_s.include?(":")
+                               thing_update(thing: item, to:)
+                             else
+                               item_update(item:, to:)
+                             end
                            end
             append_trigger(type:, config:, attach:, conditions:)
           end
@@ -62,7 +67,7 @@ module OpenHAB
           #  second element is a Hash configuring trigger
           #
           def item_update(item:, to:)
-            config = { "itemName" => item.name }
+            config = { "itemName" => item.is_a?(Item) ? item.name : item.to_s }
             config["state"] = to.to_s unless to.nil?
             [ITEM_STATE_UPDATE, config]
           end

data/lib/openhab/dsl/version.rb

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

data/lib/openhab/dsl.rb

@@ -296,6 +296,19 @@ module OpenHAB
     # own instance of the timers object, so you don't need to worry about collisions among
     # different files.
     #
+    # ### Sharing Timers with other scripts
+    #
+    # When a timer is stored in the {shared_cache}, it will automatically be converted into
+    # an openHAB Timer object. It can then be used in other scripts or UI rules,
+    # written in JRuby or other supported languages.
+    #
+    # Timers are normally managed by TimerManager, and are normally automatically cancelled
+    # when the script unloads/reloads.
+    # To disable this automatic timer cancellation at script unload, call {Core::Timer#unmanage}.
+    #
+    # openHAB will cancel the timer stored in the {OpenHAB::DSL.shared_cache shared_cache}
+    # and remove the cache entry when all the scripts that _had accessed_ it have been unloaded.
+    #
     # @see timers
     # @see Rules::BuilderDSL#changed
     # @see Items::TimedCommand
@@ -377,6 +390,19 @@ module OpenHAB
     #     end
     #   end
     #
+    # @example Timers can be shared with other scripts
+    #   # script1.rb:
+    #   timer = after(10.hours) { logger.warn "Timer created in script1.rb fired" }
+    #   shared_cache[:script1_timer] = timer
+    #
+    #   # inside a different JRuby UI rule or script:
+    #   # This is an openHAB timer object, not a JRuby timer object
+    #   # the reschedule method expects a ZonedDateTime
+    #   shared_cache[:script1_timer]&.reschedule(10.seconds.from_now)
+    #
+    #   # inside another JS script:
+    #   cache.shared.get("script1_timer")?.cancel()
+    #
     def after(duration, id: nil, reschedule: true, &block)
       raise ArgumentError, "Block is required" unless block
 

data/lib/openhab/scripting.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# This is the default 'require' file in a Gemfile
+
+return unless defined?(Java::OrgOpenhabCore::OpenHAB)
+
+require_relative "dsl"

data/lib/openhab/yard/markdown_helper.rb

@@ -45,6 +45,9 @@ module OpenHAB
               if match
                 log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text#{match ? ":" : "."}\n" \
                          "\t#{match[1] ? "..." : ""}#{match[2].delete("\n")}#{match[3] ? "..." : ""}"
+                # Don't strip the link. This is so literals like {RUBY_ENGINE_VERSION} remain as they are,
+                # not stripped to "RUBY_ENGINE_VERSION"
+                next str
               end
             end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.36.2
+  version: 5.38.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -9,7 +9,7 @@ authors:
 - Jimmy Tanagra
 bindir: bin
 cert_chain: []
-date: 2025-03-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -433,6 +433,7 @@ files:
 - lib/openhab/rspec/openhab/core/things/proxy.rb
 - lib/openhab/rspec/shell.rb
 - lib/openhab/rspec/suspend_rules.rb
+- lib/openhab/scripting.rb
 - lib/openhab/yard.rb
 - lib/openhab/yard/base_helper.rb
 - lib/openhab/yard/cli/stats.rb
@@ -478,7 +479,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.6.7
 specification_version: 4
 summary: JRuby Helper Libraries for openHAB Scripting
 test_files: []