openhab-scripting 5.37.0 → 5.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c7147931d90e0b4f5c7d16fb324ac46f6ddd579e25c32245c49fc1c4a770120
-  data.tar.gz: 718a8d07104975de5fd75900ba97b743319e8a18ff4076dc811ae7b5b0ffbdc5
+  metadata.gz: dcf7591d994378fb216137014e04dae3321ba891e11f201336e1afc6f1b7226b
+  data.tar.gz: d9917f8c8f5ead81623e39b3c606ab0f4efe7da519f654b081498bd743ebc721
 SHA512:
-  metadata.gz: '0998824497c882bc59e935f13a28aeda241c0f399428ab90403b817e4b4f664db37d2c2225b9ff356535e3cb2ae478f8b091ab09cfda1d091142ae7b0e6ccc85'
-  data.tar.gz: 72037d1a9d371458716fbc88955858d6a615dfc089878226cbb0109706df7c7a9d77f9ebc9001581a0f379e8785a7f752d060369dacb152bdefb5be9bdcbbc89
+  metadata.gz: 78aa38c7c90b81ead46d438543077abb55bf06db1476f6e73cf36577f4df10c3b305e5169de2df2580f7d1d963fd8e5a998521764d9377305f87717ff216fff5
+  data.tar.gz: 9a410509dc518a5019c3885d5123c8a1840a0a70c6abb99df85cdbc11897eb7d5367d6014c71ff16759baebe03083a409f8f254606f0fab22a51ef50f2cdcdc6

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

@@ -13,6 +13,14 @@ module OpenHAB
       class ItemStateChangedEvent < ItemEvent
         include ItemState
 
+        # @!attribute [r] last_state_update
+        #   @return [ZonedDateTime] the time the previous state update occurred
+        #   @since openHAB 5.0
+
+        # @!attribute [r] last_state_change
+        #   @return [ZonedDateTime] the time the previous state change occurred
+        #   @since openHAB 5.0
+
         # @!method was_undef?
         #   Check if {#was} is {UNDEF}
         #   @return [true, false]
@@ -74,6 +82,9 @@ module OpenHAB
         def inspect
           s = "#<OpenHAB::Core::Events::ItemStateChangedEvent item=#{item_name} " \
               "state=#{item_state.inspect} was=#{old_item_state.inspect}"
+          # @deprecated OH4.3 remove respond_to? checks in the next two lines when dropping OH 4.3
+          s += " last_state_update=#{last_state_update}" if respond_to?(:last_state_update) && last_state_update
+          s += " last_state_change=#{last_state_change}" if respond_to?(:last_state_change) && last_state_change
           s += " source=#{source.inspect}" if source
           "#{s}>"
         end

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

@@ -14,6 +14,19 @@ module OpenHAB
       #
       class ItemStateUpdatedEvent < ItemEvent
         include ItemState
+
+        # @!attribute [r] last_state_update
+        #   @return [ZonedDateTime] the time the previous state update occurred
+        #   @since openHAB 5.0
+
+        # @return [String]
+        def inspect
+          s = "#<OpenHAB::Core::Events::ItemStateUpdatedEvent item=#{item_name} state=#{item_state.inspect}"
+          # @deprecated OH4.3 remove respond_to? check when dropping OH 4.3
+          s += " last_state_update=#{last_state_update}" if respond_to?(:last_state_update) && last_state_update
+          s += " source=#{source.inspect}" if source
+          "#{s}>"
+        end
       end
     end
   end

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

@@ -13,6 +13,10 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [StringListType, nil]
       #
+      # @!attribute [r] was
+      #   @return [StringListType, nil]
+      #   @since openHAB 5.0
+      #
       class CallItem < GenericItem
         # @!visibility private
         def format_type(command)

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

@@ -35,6 +35,10 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [HSBType, nil]
       #
+      # @!attribute [r] was
+      #   @return [HSBType, nil]
+      #   @since openHAB 5.0
+      #
       class ColorItem < DimmerItem
         # Make sure to do the String => HSBType conversion in Ruby,
         # where we add support for hex

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

@@ -8,7 +8,7 @@ module OpenHAB
       java_import org.openhab.core.library.items.ContactItem
 
       #
-      #  A {ContactItem} can be used for sensors that return an "open" or
+      # A {ContactItem} can be used for sensors that return an "open" or
       # "closed" as a state.
       #
       # This is useful for doors, windows, etc.
@@ -16,6 +16,10 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [OpenClosedType, nil]
       #
+      # @!attribute [r] was
+      #   @return [OpenClosedType, nil]
+      #   @since openHAB 5.0
+      #
       # @example
       #   rule 'Log state of all doors on system startup' do
       #     on_load
@@ -30,20 +34,29 @@ module OpenHAB
       #     end
       #   end
       #
+      # @!method open?
+      #   Check if the item state == {OPEN}
+      #   @return [true,false]
+      #
+      #   @example Log open contacts
+      #     Contacts.select(&:open?).each { |contact| logger.info("Contact #{contact.name} is open")}
+      #
+      # @!method closed?
+      #   Check if the item state == {CLOSED}
+      #   @return [true,false]
+      #
+      #   @example Log closed contacts
+      #     Contacts.select(&:closed?).each { |contact| logger.info("Contact #{contact.name} is closed")}
+      #
+      # @!method was_open?
+      #   Check if {#was} is {OPEN}
+      #   @return [true, false]
+      #
+      # @!method was_closed?
+      #   Check if {#was} is {CLOSED}
+      #   @return [true, false]
+      #
       class ContactItem < GenericItem
-        # @!method open?
-        #   Check if the item state == {OPEN}
-        #   @return [true,false]
-        #
-        # @example Log open contacts
-        #   Contacts.select(&:open?).each { |contact| logger.info("Contact #{contact.name} is open")}
-
-        # @!method closed?
-        #   Check if the item state == {CLOSED}
-        #   @return [true,false]
-        #
-        # @example Log closed contacts
-        #   Contacts.select(&:closed?).each { |contact| logger.info("Contact #{contact.name} is closed")}
       end
     end
   end

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

@@ -13,6 +13,10 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [DateTimeType, nil]
       #
+      # @!attribute [r] was
+      #   @return [DateTimeType, nil]
+      #   @since openHAB 5.0
+      #
       # @example DateTime items can be updated and commanded with Ruby Time objects or Java ZonedDateTime objects
       #   Example_DateTimeItem << Time.now
       #   Example_DateTimeItem << ZonedDateTime.now

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

@@ -15,6 +15,10 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [PercentType, nil]
       #
+      # @!attribute [r] was
+      #   @return [PercentType, nil]
+      #   @since openHAB 5.0
+      #
       # @example
       #   DimmerOne << DimmerOne.state - 5
       #   DimmerOne << 100 - DimmerOne.state

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

@@ -79,10 +79,45 @@ module OpenHAB
         #   [Ruby safe navigation operator `&.`](https://docs.ruby-lang.org/en/master/syntax/calling_methods_rdoc.html#label-Safe+Navigation+Operator)
         #   Use {#undef?} or {#null?} to check for those states.
         #
+        # @see was
+        #
         def state
           raw_state if state?
         end
 
+        # @!method was_undef?
+        #   Check if {#was} is {UNDEF}
+        #   @return [true, false]
+
+        # @!method was_null?
+        #   Check if {#was} is {NULL}
+        #   @return [true, false]
+
+        #
+        # Check if the item's previous state was not `nil`, {UNDEF} or {NULL}
+        #
+        # @return [true, false]
+        #
+        # @since openHAB 5.0
+        #
+        def was?
+          !last_state.nil? && !last_state.is_a?(Types::UnDefType)
+        end
+
+        #
+        # @!attribute [r] was
+        #
+        # @return [State] The previous state of the item. nil if the item was never updated, or
+        #   if the item was updated to {NULL} or {UNDEF}.
+        # @since openHAB 5.0
+        #
+        # @see state
+        # @see Item#last_state
+        #
+        def was
+          last_state if was?
+        end
+
         # @!method null?
         #   Check if the item state == {NULL}
         #   @return [true,false]

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

@@ -18,7 +18,11 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [RawType, nil]
       #
-      # @example Update from a base 64 encode image string
+      # @!attribute [r] was
+      #   @return [RawType, nil]
+      #   @since openHAB 5.0
+      #
+      # @example Update from a base 64 encoded image string
       #   Image.update("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEUAAACnej3aAAAAAXRSTlMAQObYZgAAAApJREFUCNdjYAAAAAIAAeIhvDMAAAAASUVORK5CYII=")
       #
       # @example Update from image bytes and mime type

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

@@ -70,6 +70,18 @@ module OpenHAB
         # @!attribute [r] command_description
         #   @return [Types::CommandDescription, nil]
 
+        # @!attribute [r] last_state
+        #   @return [State] The previous state of the item.
+        #   @since openHAB 5.0
+
+        # @!attribute [r] last_state_change
+        #   @return [ZonedDateTime] The time of the last state change.
+        #   @since openHAB 5.0
+
+        # @!attribute [r] last_state_update
+        #   @return [ZonedDateTime] The time of the last state update.
+        #   @since openHAB 5.0
+
         #
         # The item's {GenericItem#label label} if one is defined, otherwise its {#name}.
         #
@@ -550,6 +562,12 @@ module OpenHAB
         # @return [String]
         def inspect
           s = "#<OpenHAB::Core::Items::#{type}Item#{type_details} #{name} #{label.inspect} state=#{raw_state.inspect}"
+          # @deprecated OH 4.3 Remove if guard when dropping support for OH 4.3
+          if respond_to?(:last_state)
+            s += " last_state=#{last_state.inspect}" if last_state
+            s += " last_state_update=#{last_state_update}" if last_state_update
+            s += " last_state_change=#{last_state_change}" if last_state_change
+          end
           s += " category=#{category.inspect}" if category
           s += " tags=#{tags.to_a.inspect}" unless tags.empty?
           s += " groups=#{group_names}" unless group_names.empty?

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

@@ -16,6 +16,10 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [PointType, nil]
       #
+      # @!attribute [r] was
+      #   @return [PointType, nil]
+      #   @since openHAB 5.0
+      #
       # @example Send point commands
       #   Location << '30,20'   # latitude of 30, longitude of 20
       #   Location << '30,20,80' # latitude of 30, longitude of 20, altitude of 80

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

@@ -25,6 +25,9 @@ module OpenHAB
       #   @return [javax.measure.Unit, nil]
       # @!attribute [r] state
       #   @return [DecimalType, QuantityType, nil]
+      # @!attribute [r] was
+      #   @return [DecimalType, QuantityType, nil]
+      #   @since openHAB 5.0
       #
       # @example Number Items can be selected in an enumerable with grep.
       #   # Get all NumberItems

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

@@ -623,6 +623,7 @@ module OpenHAB
         #   Returns the time the item was last updated.
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [ZonedDateTime, nil] The timestamp of the last update
+        #   @see Item#last_state_update
 
         # @!method next_update(service = nil)
         #   Returns the first future update time of the item.
@@ -636,6 +637,7 @@ module OpenHAB
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [ZonedDateTime, nil] The timestamp of the last update
         #   @since openHAB 4.2
+        #   @see Item#last_state_change
 
         # @!method next_change(service = nil)
         #   Returns the first future change time of the item.
@@ -670,6 +672,8 @@ module OpenHAB
         #   @return [PersistedState, nil] the previous state or nil if no previous state could be found,
         #           or if the default persistence service is not configured or
         #           does not refer to a valid service
+        #
+        #   @see Item#last_state
 
         # @!method next_state(service = nil, skip_equal: false)
         #   Return the next state of the item

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

@@ -10,71 +10,92 @@ module OpenHAB
       #
       # A {PlayerItem} allows control of a player, e.g. an audio player.
       #
-      # @!attribute [r] state
-      #   @return [PlayPauseType, RewindFastforwardType, nil]
-      #
       # @example Start playing on a player item
       #   Chromecast.play
       # @example Check if a player is paused
       #   logger.warn("#{item.name} is paused") if Chromecast.paused?
       #
+      # @!attribute [r] state
+      #   @return [PlayPauseType, RewindFastforwardType, nil]
+      #
+      # @!attribute [r] was
+      #   @return [PlayPauseType, RewindFastforwardType, nil]
+      #   @since openHAB 5.0
+      #
+      # @!method play?
+      #   Check if the item state == {PLAY}
+      #   @return [true,false]
+      #
+      # @!method paused?
+      #   Check if the item state == {PAUSE}
+      #   @return [true,false]
+      #
+      # @!method rewinding?
+      #   Check if the item state == {REWIND}
+      #   @return [true,false]
+      #
+      # @!method fast_forwarding?
+      #   Check if the item state == {FASTFORWARD}
+      #   @return [true,false]
+      #
+      # @!method was_playing?
+      #   Check if {#was} is {PLAY}
+      #   @return [true, false]
+      #
+      # @!method was_paused?
+      #   Check if {#was} is {PAUSE}
+      #   @return [true, false]
+      #
+      # @!method was_rewinding?
+      #   Check if {#was} is {REWIND}
+      #   @return [true, false]
+      #
+      # @!method was_fast_forwarding?
+      #   Check if {#was} is {FASTFORWARD}
+      #   @return [true, false]
+      #
+      # @!method play
+      #   Send the {PLAY} command to the item
+      #   @return [PlayerItem] `self`
+      #
+      # @!method play!
+      #   Send the {PLAY} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+      #   @return [PlayerItem] `self`
+      #
+      # @!method pause
+      #   Send the {PAUSE} command to the item
+      #   @return [PlayerItem] `self`
+      #
+      # @!method pause!
+      #   Send the {PAUSE} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+      #   @return [PlayerItem] `self`
+      #
+      # @!method rewind
+      #   Send the {REWIND} command to the item
+      #   @return [PlayerItem] `self`
+      #
+      # @!method rewind!
+      #   Send the {REWIND} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+      #   @return [PlayerItem] `self`
+      #
+      # @!method fast_forward
+      #   Send the {FASTFORWARD} command to the item
+      #   @return [PlayerItem] `self`
+      #
+      # @!method fast_forward!
+      #   Send the {FASTFORWARD} command to the item, even when
+      #     {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+      #   @return [PlayerItem] `self`
+      #
+      # @!method next
+      #   Send the {NEXT} command to the item
+      #   @return [PlayerItem] `self`
+      #
+      # @!method previous
+      #   Send the {PREVIOUS} command to the item
+      #   @return [PlayerItem] `self`
+      #
       class PlayerItem < GenericItem
-        # @!method play?
-        #   Check if the item state == {PLAY}
-        #   @return [true,false]
-
-        # @!method paused?
-        #   Check if the item state == {PAUSE}
-        #   @return [true,false]
-
-        # @!method rewinding?
-        #   Check if the item state == {REWIND}
-        #   @return [true,false]
-
-        # @!method fast_forwarding?
-        #   Check if the item state == {FASTFORWARD}
-        #   @return [true,false]
-
-        # @!method play
-        #   Send the {PLAY} command to the item
-        #   @return [PlayerItem] `self`
-
-        # @!method play!
-        #   Send the {PLAY} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [PlayerItem] `self`
-
-        # @!method pause
-        #   Send the {PAUSE} command to the item
-        #   @return [PlayerItem] `self`
-
-        # @!method pause!
-        #   Send the {PAUSE} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [PlayerItem] `self`
-
-        # @!method rewind
-        #   Send the {REWIND} command to the item
-        #   @return [PlayerItem] `self`
-
-        # @!method rewind!
-        #   Send the {REWIND} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [PlayerItem] `self`
-
-        # @!method fast_forward
-        #   Send the {FASTFORWARD} command to the item
-        #   @return [PlayerItem] `self`
-
-        # @!method fast_forward!
-        #   Send the {FASTFORWARD} command to the item, even when
-        #     {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
-        #   @return [PlayerItem] `self`
-
-        # @!method next
-        #   Send the {NEXT} command to the item
-        #   @return [PlayerItem] `self`
-
-        # @!method previous
-        #   Send the {PREVIOUS} command to the item
-        #   @return [PlayerItem] `self`
       end
     end
   end

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

@@ -16,6 +16,10 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [PercentType, UpDownType, nil]
       #
+      # @!attribute [r] was
+      #   @return [PercentType, UpDownType, nil]
+      #   @since openHAB 5.0
+      #
       # @example Roll up all Rollershutters in a group
       #   Shutters.up
       #
@@ -37,6 +41,14 @@ module OpenHAB
         #   Check if the item state == {DOWN}
         #   @return [true,false]
 
+        # @!method was_up?
+        #   Check if {#was} is {UP}
+        #   @return [true, false]
+
+        # @!method was_down?
+        #   Check if {#was} is {DOWN}
+        #   @return [true, false]
+
         # @!method up
         #   Send the {UP} command to the item
         #   @return [RollershutterItem] `self`

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

@@ -543,17 +543,14 @@ module OpenHAB
         # @example Given a A/V receiver's input item, search for its power item
         #   FamilyReceiver_Input.points(Semantics::Switch) # => [FamilyReceiver_Switch]
         #
-        # @param [SemanticTag] point_or_property_types
-        #   Pass 1 or 2 classes that are sub-classes of {Point} or {Property}.
-        #   Note that when comparing against semantic tags, it does a sub-class check.
-        #   So if you search for [Control], you'll get items tagged with [Switch].
+        # @param (see Enumerable#points)
         # @return [Array<Item>]
         #
-        def points(*point_or_property_types)
-          return members.points(*point_or_property_types) if equipment? || location?
+        def points(...)
+          return members.points(...) if equipment? || location?
 
           # automatically search the parent equipment (or location?!) for sibling points
-          result = (equipment || location)&.points(*point_or_property_types) || []
+          result = (equipment || location)&.points(...) || []
           result.delete(self)
           result
         end
@@ -572,6 +569,14 @@ module Enumerable
 
   #
   # Returns a new array of items that are a semantics Location (optionally of one of the given types)
+  #
+  # @param [SemanticTag] types
+  #   Pass 1 or more classes that are sub-classes of {Semantics::Location Semantics::Location}.
+  #   Note that when comparing against semantic tags, it does a sub-class check by default.
+  #   So if you search for [Room], you'll get items tagged with [LivingRoom], [Kitchen], etc.
+  # @param [true, false] subclasses
+  #   If true, match all subclasses of the given types.
+  #   If false, only match the exact type.
   # @return [Array<Item>]
   #
   # @example Get all rooms
@@ -580,7 +585,7 @@ module Enumerable
   # @example Get all bedrooms and bathrooms
   #   items.locations(Semantics::Bedroom, Semantics::Bathroom)
   #
-  def locations(*types)
+  def locations(*types, subclasses: true)
     begin
       raise ArgumentError unless types.all? { |type| type < Semantics::Location }
     rescue ArgumentError, TypeError
@@ -588,7 +593,13 @@ module Enumerable
     end
 
     result = select(&:location?)
-    result.select! { |i| types.any? { |type| i.location_type <= type } } unless types.empty?
+    unless types.empty?
+      if subclasses
+        result.select! { |i| types.any? { |type| i.location_type <= type } }
+      else
+        result.select! { |i| types.include?(i.location_type) }
+      end
+    end
 
     result
   end
@@ -602,6 +613,13 @@ module Enumerable
   #   that belong to the {Semantics::Equipment equipments}, use {#members}
   #   before calling {#points}. See the example with {#points}.
   #
+  # @param [SemanticTag] types
+  #   Pass 1 or more classes that are sub-classes of {Semantics::Equipment Semantics::Equipment}.
+  #   Note that when comparing against semantic tags, it does a sub-class check by default.
+  #   So if you search for [Fan], you'll get items tagged with [CeilingFan], [KitchenHood], etc.
+  # @param [true, false] subclasses
+  #   If true, match all subclasses of the given types.
+  #   If false, only match the exact type.
   # @return [Array<Item>]
   #
   # @example Get all TVs in a room
@@ -610,7 +628,7 @@ module Enumerable
   # @example Get all TVs and Speakers in a room
   #   lGreatRoom.equipments(Semantics::Television, Semantics::Speaker)
   #
-  def equipments(*types)
+  def equipments(*types, subclasses: true)
     begin
       raise ArgumentError unless types.all? { |type| type < Semantics::Equipment }
     rescue ArgumentError, TypeError
@@ -618,13 +636,27 @@ module Enumerable
     end
 
     result = select(&:equipment?)
-    result.select! { |i| types.any? { |type| i.equipment_type <= type } } unless types.empty?
+    unless types.empty?
+      if subclasses
+        result.select! { |i| types.any? { |type| i.equipment_type <= type } }
+      else
+        result.select! { |i| types.include?(i.equipment_type) }
+      end
+    end
 
     result
   end
 
   # Returns a new array of items that are semantics points (optionally of a given type)
   #
+  # @param [SemanticTag] point_or_property_types
+  #   Pass 1 or 2 classes that are sub-classes of {Semantics::Point Semantics::Point} or
+  #   {Semantics::Property Semantics::Property}.
+  #   Note that when comparing against semantic tags, it does a sub-class check by default.
+  #   So if you search for [Control], you'll get items tagged with [Switch].
+  # @param [true, false] subclasses
+  #   If true, match all subclasses of the given types.
+  #   If false, only match the exact type.
   # @return [Array<Item>]
   #
   # @example Get all the power switch items for every equipment in a room
@@ -632,7 +664,7 @@ module Enumerable
   #
   # @see #members
   #
-  def points(*point_or_property_types)
+  def points(*point_or_property_types, subclasses: true)
     unless (0..2).cover?(point_or_property_types.length)
       raise ArgumentError, "wrong number of arguments (given #{point_or_property_types.length}, expected 0..2)"
     end
@@ -652,8 +684,13 @@ module Enumerable
 
     select do |point|
       point.point? && point_or_property_types.all? do |tag|
-        (tag < Semantics::Point && point.point_type&.<=(tag)) ||
-          (tag < Semantics::Property && point.property_type&.<=(tag))
+        if subclasses
+          (tag < Semantics::Point && point.point_type&.<=(tag)) ||
+            (tag < Semantics::Property && point.property_type&.<=(tag))
+        else
+          (tag < Semantics::Point && point.point_type == tag) ||
+            (tag < Semantics::Property && point.property_type == tag)
+        end
       end
     end
   end

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

@@ -14,6 +14,10 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [StringType, nil]
       #
+      # @!attribute [r] was
+      #   @return [StringType, nil]
+      #   @since openHAB 5.0
+      #
       # @example
       #   # StringOne has a current state of "Hello"
       #   StringOne << StringOne + " World!"

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

@@ -14,6 +14,9 @@ module OpenHAB
       # @!attribute [r] state
       #   @return [OnOffType, nil]
       #
+      # @!attribute [r] was
+      #   @return [OnOffType, nil]
+      #   @since openHAB 5.0
       #
       # @example Turn on all switches in a `Group:Switch` called Switches
       #   Switches.on
@@ -76,6 +79,14 @@ module OpenHAB
         # @!method off!
         #   Send the {OFF} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
         #   @return [SwitchItem] `self`
+
+        # @!method was_on?
+        #   Check if {#was} is (implicitly convertible to) {ON}
+        #   @return [true, false]
+
+        # @!method was_off?
+        #   Check if {#was} is (implicitly convertible to) {OFF}
+        #   @return [true, false]
       end
     end
   end

data/lib/openhab/core/items.rb

@@ -49,6 +49,10 @@ module OpenHAB
               def #{state_predicate}                                                  # def on?
                 raw_state.as(#{state.class.java_class.simple_name}).equal?(#{state})  #   raw_state.as(OnOffType) == ON
               end                                                                     # end
+
+              def was_#{state_predicate}                                              # def was_on?
+                last_state.as(#{state.class.java_class.simple_name}).equal?(#{state}) #   last_state.as(OnOffType) == ON
+              end                                                                     # end
             RUBY
           end
         end

data/lib/openhab/core/timer.rb

@@ -45,6 +45,7 @@ module OpenHAB
       #
       # @!visibility private
       def initialize(time, id:, thread_locals:, block:)
+        @managed = true
         @time = time
         @id = id
         @thread_locals = thread_locals
@@ -95,7 +96,7 @@ module OpenHAB
       # @!visibility private
       def reschedule!(time = nil)
         Thread.current[:openhab_rescheduled_timer] = true if Thread.current[:openhab_rescheduled_timer] == self
-        DSL.timers.add(self)
+        DSL.timers.add(self) if managed?
         @timer.reschedule(new_execution_time(time || @time))
         self
       end
@@ -122,6 +123,79 @@ module OpenHAB
         @timer.cancel
       end
 
+      #
+      # Returns the openHAB Timer object.
+      #
+      # This can be used to share the timer with other scripts via {OpenHAB::DSL.shared_cache shared_cache}.
+      # The other scripts can be other JRuby scripts or scripts written in a different language
+      # such as JSScripting, Python, etc. which can either be file-based or UI based scripts.
+      #
+      # 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 {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.
+      #
+      # @return [org.openhab.core.automation.module.script.action.Timer]
+      #
+      # @see unmanage
+      #
+      # @example
+      #   # script1.rb:
+      #   timer = after(10.hours) { logger.warn "Timer created in script1.rb fired" }
+      #   shared_cache[:script1_timer] = timer.to_java
+      #
+      #   # script2.js: (JavaScript!)
+      #   rules.when().item("TestSwitch1").receivedCommand().then(event => {
+      #     cache.shared.get("script1_timer")?.cancel()
+      #   })
+      #
+      #   # or in Ruby script2.rb
+      #   received_command(TestSwitch2, command: ON) do
+      #     # This is an openHAB timer object, not a JRuby timer object
+      #     # the reschedule method expects a ZonedDateTime
+      #     shared_cache[:script1_timer]&.reschedule(3.seconds.from_now)
+      #   end
+      #
+      # @!visibility private
+      def to_java
+        @timer
+      end
+
+      #
+      # Removes the timer from the {TimerManager TimerManager}
+      #
+      # The effects of calling this method are:
+      # - The timer will no longer be automatically cancelled when the script unloads.
+      #   It will still execute as scheduled even if the script is unloaded/removed.
+      # - It can no longer be referenced by its `id`.
+      # - Subsequent calls to {OpenHAB::DSL.after after} with the same `id` will create a separate new timer.
+      # - Normal timer operations such as {reschedule}, {cancel}, etc. will still work.
+      #
+      # @return [org.openhab.core.automation.module.script.action.Timer] The openHAB Timer object
+      #
+      # @example
+      #   timer = after(10.hours) { logger.warn "Timer created in script1.rb fired" }
+      #   shared_cache[:script1_timer] = timer
+      #   # Don't cancel the timer when this script unloads,
+      #   # but openHAB will do it if all scripts that had referenced the shared cache are unloaded.
+      #   timer.unmanage
+      #
+      def unmanage
+        @managed = false
+        DSL.timers.delete(self)
+        @id = nil
+        @timer
+      end
+
+      # @return [true,false] True if the timer is managed by TimerManager, false otherwise.
+      #   A timer is managed by default, and becomes un-managed when {unmanage} is called.
+      def managed?
+        @managed
+      end
+
       private
 
       #

data/lib/openhab/core/value_cache.rb

@@ -47,7 +47,7 @@ module OpenHAB
     module ValueCache
       # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-5B-5D Hash#[]
       def [](key)
-        get(key.to_s)
+        get(key)
       end
 
       #
@@ -58,18 +58,18 @@ module OpenHAB
       # @return [Object] new value or current value
       #
       def compute_if_absent(key, &)
-        get(key.to_s, &)
+        get(key, &)
       end
 
       # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-5B-5D-3D Hash#[]=
       def []=(key, value)
-        put(key.to_s, value)
+        put(key, value)
       end
       alias_method :store, :[]
 
       # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-delete Hash#delete
       def delete(key)
-        key = key.to_s
+        key = key.to_s # needed for remove below
         if block_given?
           fetch(key) do
             return yield(key)
@@ -89,8 +89,8 @@ module OpenHAB
                 "wrong number of arguments (given #{default_value.length + 1}, expected 0..1)"
         end
 
-        key = key.to_s
         if default_value.empty?
+          key = key.to_s
           if block_given?
             get(key) do
               return yield(key)
@@ -184,6 +184,44 @@ module OpenHAB
           self[k]
         end
       end
+
+      #
+      # Converts values before storing them in the cache.
+      #
+      # This is used to convert JRuby timers created with {OpenHAB::DSL.after} to openHAB timers.
+      #
+      # Because we generally can't store JRuby objects in the shared cache,
+      # we can convert other things to Java objects here too as necessary.
+      #
+      # @!visibility private
+      module ValueConverter
+        # @!visibility private
+        def get(key, &)
+          key = key.to_s
+          return super(key) unless block_given?
+
+          super do
+            convert(yield(key))
+          end
+        end
+
+        # @!visibility private
+        def put(key, value)
+          key = key.to_s
+          value = convert(value)
+          super
+        end
+
+        private
+
+        def convert(value)
+          value.respond_to?(:to_java) ? value.to_java : value
+        end
+      end
+
+      # We use prepend here instead of overriding the methods inside ValueCache module/interface
+      # because the methods are defined in the implementation class
+      $sharedCache.class.prepend(ValueConverter)
     end
   end
 end

data/lib/openhab/core.rb

@@ -13,6 +13,8 @@ module OpenHAB
     V4_2 = Gem::Version.new("4.2.0").freeze
     # @!visibility private
     V4_3 = Gem::Version.new("4.3.0").freeze
+    # @!visibility private
+    V5_0 = Gem::Version.new("5.0.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.
@@ -21,6 +23,21 @@ module OpenHAB
       @version ||= Gem::Version.new(VERSION).release.freeze
     end
 
+    #
+    # Returns the full version of openHAB
+    #
+    # The {version} method returns the release version, stripping off any
+    # additional qualifiers such as M1, or snapshots.
+    # This method returns the full version string, including the qualifiers.
+    #
+    # @return [Gem::Version] Returns the full version of openHAB
+    #
+    # @!visibility private
+    #
+    def self.full_version
+      @full_version ||= Gem::Version.new(VERSION).freeze
+    end
+
     raise "`openhab-scripting` requires openHAB >= 4.1.0" unless version >= V4_1
 
     # @return [Integer] Number of seconds to wait between checks for automation manager

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.37.0"
+    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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.37.0
+  version: 5.38.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -9,7 +9,7 @@ authors:
 - Jimmy Tanagra
 bindir: bin
 cert_chain: []
-date: 2025-03-25 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: []