openhab-scripting 5.36.2 → 5.38.0

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