openhab-scripting 2.13.1 → 2.15.0

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

@@ -15,6 +15,7 @@ module OpenHAB
           extend Forwardable
           include Comparable
 
+          # @return [Regex] Regular expression matching blank strings
           BLANK_RE = /\A[[:space:]]*\z/.freeze
           private_constant :BLANK_RE
 
@@ -33,7 +34,8 @@ module OpenHAB
           #
           # Convert the StringItem into a String
           #
-          # @return [String] String representation of the StringItem or nil if underlying OpenHAB StringItem does not have a state
+          # @return [String] String representation of the StringItem or
+          #   nil if underlying OpenHAB StringItem does not have a state
           #
           def to_str
             @string_item.state&.to_full_string&.to_s
@@ -64,7 +66,8 @@ module OpenHAB
           #
           # @param [Object] other object to compare to
           #
-          # @return [Integer] -1,0,1 or nil depending on value supplied, nil comparison to supplied object is not possible.
+          # @return [Integer] -1,0,1 or nil depending on value supplied,
+          #   nil comparison to supplied object is not possible.
           #
           def <=>(other)
             case other
@@ -87,7 +90,7 @@ module OpenHAB
           def method_missing(meth, *args, &block)
             if @string_item.respond_to?(meth)
               @string_item.__send__(meth, *args, &block)
-            elsif @string_item.state? && @string_item.state.to_full_string.to_s.respond_to?(meth)
+            elsif @string_item.state&.to_full_string&.to_s.respond_to?(meth)
               @string_item.state.to_full_string.to_s.__send__(meth, *args, &block)
             elsif ::Kernel.method_defined?(meth) || ::Kernel.private_method_defined?(meth)
               ::Kernel.instance_method(meth).bind_call(self, *args, &block)
@@ -95,6 +98,21 @@ module OpenHAB
               super(meth, *args, &block)
             end
           end
+
+          #
+          # Checks if this method responds to the missing method
+          #
+          # @param [String] method_name Name of the method to check
+          # @param [Boolean] _include_private boolean if private methods should be checked
+          #
+          # @return [Boolean] true if this object will respond to the supplied method, false otherwise
+          #
+          def respond_to_missing?(method_name, _include_private = false)
+            @string_item.respond_to?(method_name) ||
+              @string_item.state&.to_full_string&.to_s.respond_to?(method_name) ||
+              ::Kernel.method_defined?(method_name) ||
+              ::Kernel.private_method_defined?(method_name)
+          end
         end
       end
     end

data/lib/openhab/core/dsl/monkey_patch/items/items.rb

@@ -6,6 +6,7 @@ require 'bigdecimal'
 
 # Monkey patch items
 require 'openhab/core/dsl/monkey_patch/items/metadata'
+require 'openhab/core/dsl/monkey_patch/items/persistence'
 require 'openhab/core/dsl/monkey_patch/items/contact_item'
 require 'openhab/core/dsl/monkey_patch/items/dimmer_item'
 require 'openhab/core/dsl/monkey_patch/items/switch_item'
@@ -127,4 +128,5 @@ class Java::OrgOpenhabCoreItems::GenericItem
   # rubocop:enable Style/ClassAndModuleChildren
   prepend OpenHAB::Core::DSL::MonkeyPatch::Items::ItemExtensions
   prepend OpenHAB::Core::DSL::MonkeyPatch::Items::Metadata
+  prepend OpenHAB::Core::DSL::MonkeyPatch::Items::Persistence
 end

data/lib/openhab/core/dsl/monkey_patch/items/metadata.rb

@@ -123,25 +123,7 @@ module OpenHAB
               # @return [OpenHAB::Core::DSL::MonkeyPatch::Items::MetadataItem]
               #
               def []=(namespace, value)
-                case value
-                when MetadataItem
-                  meta_value = value.value
-                  configuration = value.__getobj__
-                when Metadata
-                  meta_value = value.value
-                  configuration = value.configuration
-                when Array
-                  raise ArgumentError, 'Array must contain 2 elements: value, config' if value.length < 2
-
-                  meta_value = value[0]
-                  configuration = value[1]
-                when Hash
-                  meta_value = nil
-                  configuration = value
-                else
-                  meta_value = value
-                  configuration = nil
-                end
+                meta_value, configuration = update_from_value(value)
 
                 key = MetadataKey.new(namespace, @item_name)
                 metadata = Metadata.new(key, meta_value, configuration)
@@ -185,12 +167,12 @@ module OpenHAB
               #
               # @return [Boolean] True if the given namespace exists, false otherwise
               #
-              def has_key?(namespace)
+              def key?(namespace)
                 !NamespaceAccessor.registry.get(MetadataKey.new(namespace, @item_name)).nil?
               end
 
-              alias key? has_key?
-              alias include? has_key?
+              alias has_key? key?
+              alias include? key?
 
               #
               # Merge the given hash with the current metadata. Existing namespace that matches the name
@@ -201,25 +183,9 @@ module OpenHAB
 
                 others.each do |other|
                   case other
-                  when Hash
-                    other.each do |key, new_meta|
-                      if block_given?
-                        current_meta = self[key]&.to_a
-                        new_meta = yield key, current_meta, new_meta unless current_meta.nil?
-                      end
-                      self[key] = new_meta
-                    end
-                  when self.class
-                    other.each do |key, new_value, new_config|
-                      new_meta = new_value, new_config
-                      if block_given?
-                        current_meta = self[key]&.to_a
-                        new_meta = yield key, current_meta, new_meta unless current_meta.nil?
-                      end
-                      self[key] = new_meta
-                    end
-                  else
-                    raise ArgumentError, "merge only supports Hash, or another item's metadata"
+                  when Hash then merge_hash!(other)
+                  when self.class then merge_metadata!(other)
+                  else raise ArgumentError, "merge only supports Hash, or another item's metadata"
                   end
                 end
                 self
@@ -238,7 +204,65 @@ module OpenHAB
               # @return [Java::org::openhab::core::items::MetadataRegistry]
               #
               def self.registry
-                @@registry ||= OpenHAB::OSGI.service('org.openhab.core.items.MetadataRegistry')
+                @registry ||= OpenHAB::OSGI.service('org.openhab.core.items.MetadataRegistry')
+              end
+
+              private
+
+              #
+              # perform an updated based on the supplied value
+              #
+              # @param [MetadataItem,Metadata,Array,Hash] value to perform update from
+              #
+              # @return [Array<Object,Hash>] Array containing the value and configuration based on the
+              #   the supplied object
+              #
+              def update_from_value(value)
+                case value
+                when MetadataItem then [value.value, value.__getobj__]
+                when Metadata then [value.value, value.configuration]
+                when Array
+                  raise ArgumentError, 'Array must contain 2 elements: value, config' if value.length != 2
+
+                  value
+                when Hash then [nil, value]
+                else [value, nil]
+                end
+              end
+
+              #
+              # Merge the metadata from the supplied other metadata object
+              #
+              # @param [Hash] other metadata object to merge
+              # @yield [key, current_metadata, new_meta] to process merge
+              #
+              #
+              def merge_metadata!(other)
+                other.each do |key, new_value, new_config|
+                  new_meta = new_value, new_config
+                  if block_given?
+                    current_meta = self[key]&.to_a
+                    new_meta = yield key, current_meta, new_meta unless current_meta.nil?
+                  end
+                  self[key] = new_meta
+                end
+              end
+
+              #
+              # Merge a hash into the metadata
+              #
+              # @param [Hash] other to merge into metadata
+              # @yield [key, current_metadata, new_meta] to process merge
+              #
+              #
+              def merge_hash!(other)
+                other.each do |key, new_meta|
+                  if block_given?
+                    current_meta = self[key]&.to_a
+                    new_meta = yield key, current_meta, new_meta unless current_meta.nil?
+                  end
+                  self[key] = new_meta
+                end
               end
             end
 

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module DSL
+      module MonkeyPatch
+        module Items
+          #
+          # Persistence extension for Items
+          #
+          module Persistence
+            %w[persist last_update].each do |method|
+              define_method(method) do |service = nil|
+                service ||= persistence_service
+                PersistenceExtensions.public_send(method, self, service&.to_s)
+              end
+            end
+
+            #
+            # Return the previous state of the item
+            #
+            # @param skip_equal [Boolean] if true, skips equal state values and
+            #        searches the first state not equal the current state
+            # @param service [String] the name of the PersistenceService to use
+            #
+            # @return 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
+            #
+            def previous_state(service = nil, skip_equal: false)
+              service ||= persistence_service
+              PersistenceExtensions.previous_state(self, skip_equal, service&.to_s)
+            end
+
+            %w[
+              average_since
+              changed_since
+              delta_since
+              deviation_since
+              evolution_rate
+              historic_state
+              maximum_since
+              minimum_since
+              sum_since
+              updated_since
+              variance_since
+            ].each do |method|
+              define_method(method) do |timestamp, service = nil|
+                service ||= persistence_service
+                if timestamp.is_a? Java::JavaTimeTemporal::TemporalAmount
+                  timestamp = Java::JavaTime::ZonedDateTime.now.minus(timestamp)
+                end
+                PersistenceExtensions.public_send(method, self, timestamp, service&.to_s)
+              end
+            end
+
+            private
+
+            #
+            # Get the specified persistence service from the current thread local variable
+            #
+            # @return [Object] Persistence service name as String or Symbol, or nil if not set
+            #
+            def persistence_service
+              Thread.current.thread_variable_get(:persistence_service)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -74,7 +74,8 @@ class Java::OrgOpenhabCoreLibraryItems::SwitchItem
   #
   # @param [Object] other object to compare to
   #
-  # @return [Boolean] True if other is a OnOffType and other equals state for this switch item, otherwise result from super
+  # @return [Boolean] True if other is a OnOffType and other equals state for this switch item,
+  #   otherwise result from super
   #
   def ==(other)
     if other.is_a? OnOffType

data/lib/openhab/core/dsl/monkey_patch/ruby/range.rb

@@ -24,7 +24,8 @@ module OpenHAB
             #
             # @param [Object] other object to compare for case equals
             #
-            # @return [Boolean] if other is DimmerItem and state is covered by range, result from parent Range class if not DimmerItem
+            # @return [Boolean] if other is DimmerItem and state is covered by range,
+            #   result from parent Range class if not DimmerItem
             #
             def ===(other)
               return super unless other.is_a? DimmerItem

data/lib/openhab/core/dsl/monkey_patch/ruby/ruby.rb

@@ -3,3 +3,4 @@
 # Monkey patch ruby
 require 'openhab/core/dsl/monkey_patch/ruby/range'
 require 'openhab/core/dsl/monkey_patch/ruby/number'
+require 'bigdecimal/util'

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module DSL
+      #
+      # Provides support for interacting with OpenHAB Persistence service
+      #
+      module Persistence
+        #
+        # Sets a thread local variable to set the default persistence service
+        # for method calls inside the block
+        #
+        # @param [Object] Persistence service either as a String or a Symbol
+        # @yield [] Block executed in context of the supplied persistence service
+        #
+        #
+        def persistence(service)
+          Thread.current.thread_variable_set(:persistence_service, service)
+          yield
+        ensure
+          Thread.current.thread_variable_set(:persistence_service, nil)
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/dsl/property.rb

@@ -29,7 +29,14 @@ module DSLProperty
     # @param [String] name of the property
     #
     #
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
     def prop(name)
+      # rubocop rules are disabled because this method is dynamically defined on the calling
+      #   object making calls to other methods in this module impossible, or if done on methods
+      #   in this module than instance variable belong to the module not the calling class
       define_method(name) do |*args, &block|
         if args.length.zero? && block.nil? == true
           instance_variable_get("@#{name}")
@@ -75,11 +82,15 @@ module DSLProperty
         end
       end
 
-      if array_name
-        define_method(array_name) do
-          instance_variable_get("@#{array_name}")
-        end
+      return unless array_name
+
+      define_method(array_name) do
+        instance_variable_get("@#{array_name}")
       end
     end
   end
+  # rubocop:enable Metrics/MethodLength
+  # rubocop:enable Metrics/AbcSize
+  # rubocop:enable Metrics/CyclomaticComplexity
+  # rubocop:enable Metrics/PerceivedComplexity
 end

data/lib/openhab/core/dsl/rule/automation_rule.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require 'java'
+
+module OpenHAB
+  module Core
+    module DSL
+      #
+      # Creates and manages OpenHAB Rules
+      #
+      module Rule
+        #
+        # JRuby extension to OpenHAB Rule
+        #
+        # rubocop: disable Metrics/ClassLength
+        # Disabled because this class has a single responsibility, there does not appear a logical
+        # way of breaking it up into multiple classes
+        class AutomationRule < Java::OrgOpenhabCoreAutomationModuleScriptRulesupportSharedSimple::SimpleRule
+          include Logging
+          include OpenHAB::Core::DSL::Tod
+          java_import java.time.ZonedDateTime
+
+          #
+          # Create a new Rule
+          #
+          # @param [Config] config Rule configuration
+          #
+          def initialize(config:)
+            super()
+            set_name(config.name)
+            set_description(config.description)
+            set_triggers(config.triggers)
+            @run_queue = config.run
+            @guard = config.guard
+            between = config.between&.yield_self { between(config.between) }
+            @between = between || OpenHAB::Core::DSL::Tod::ALL_DAY
+            # Convert between to correct range or nil if not set
+            @trigger_delays = config.trigger_delays
+          end
+
+          #
+          # Execute the rule
+          #
+          # @param [Map] mod map provided by OpenHAB rules engine
+          # @param [Map] inputs map provided by OpenHAB rules engine containing event and other information
+          #
+          #
+          def execute(mod = nil, inputs = nil)
+            logger.trace { "Execute called with mod (#{mod&.to_string}) and inputs (#{inputs&.pretty_inspect}" }
+            logger.trace { "Event details #{inputs['event'].pretty_inspect}" } if inputs&.key?('event')
+            if trigger_delay inputs
+              trigger_delay = trigger_delay(inputs)
+              process_trigger_delay(trigger_delay, mod, inputs)
+            else
+              # If guards are satisfied execute the run type blocks
+              # If they are not satisfied, execute the Othewise blocks
+              queue = create_queue(inputs)
+              process_queue(queue, mod, inputs)
+            end
+          end
+
+          private
+
+          #
+          # Create the run queue based on guards
+          #
+          # @param [Map] inputs rule inputs
+          #
+          # @return [Queue] <description>
+          #
+          def create_queue(inputs)
+            case check_guards(event: inputs&.dig('event'))
+            when true
+              @run_queue.dup
+            when false
+              @run_queue.dup.grep(RuleConfig::Otherwise)
+            end
+          end
+
+          #
+          # Returns trigger delay from inputs if it exists
+          #
+          # @param [Map] inputs map from OpenHAB containing UID
+          #
+          # @return [Array] Array of trigger delays that match rule UID
+          #
+          def trigger_delay(inputs)
+            # Parse this to get the trigger UID:
+            # ["72698819-83cb-498a-8e61-5aab8b812623.event", "oldState", "module", \
+            #  "72698819-83cb-498a-8e61-5aab8b812623.oldState", "event", "newState",\
+            #  "72698819-83cb-498a-8e61-5aab8b812623.newState"]
+            @trigger_delays[inputs&.keys&.grep(/\.event$/)&.first&.chomp('.event')]
+          end
+
+          #
+          # Check if trigger guards prevent rule execution
+          #
+          # @param [Delay] trigger_delay rules delaying trigger because of
+          # @param [Map] inputs OpenHAB map object describing rule trigger
+          #
+          # @return [Boolean] True if the rule should execute, false if trigger guard prevents execution
+          #
+          def check_trigger_guards(trigger_delay, inputs)
+            old_state = inputs['oldState']
+            new_state = inputs['newState']
+            if check_from(trigger_delay, old_state)
+              return true if check_to(trigger_delay, new_state)
+
+              logger.trace("Skipped execution of rule '#{name}' because to state #{new_state}"\
+                                   " does not equal specified state(#{trigger_delay.to})")
+            else
+              logger.trace("Skipped execution of rule '#{name}' because old state #{old_state}"\
+                                   " does not equal specified state(#{trigger_delay.from})")
+            end
+          end
+
+          #
+          # Check the from state against the trigger delay
+          #
+          # @param [TriggerDelay] trigger_delay Information about the trigger delay
+          # @param [Item State] state from state to check
+          #
+          # @return [Boolean] true if no from state is defined or defined state equals supplied state
+          #
+          def check_from(trigger_delay, state)
+            trigger_delay.from.nil? || trigger_delay.from == state
+          end
+
+          #
+          # Check the to state against the trigger delay
+          #
+          # @param [TriggerDelay] trigger_delay Information about the trigger delay
+          # @param [Item State] state to-state to check
+          #
+          # @return [Boolean] true if no to state is defined or defined state equals supplied state
+          #
+          def check_to(trigger_delay, state)
+            trigger_delay.to.nil? || trigger_delay.to == state
+          end
+
+          #
+          # Process any matching trigger delays
+          #
+          # @param [Map] mod OpenHAB map object describing rule trigger
+          # @param [Map] inputs OpenHAB map object describing rule trigger
+          #
+          #
+          def process_trigger_delay(trigger_delay, mod, inputs)
+            if check_trigger_guards(trigger_delay, inputs)
+              logger.trace("Trigger Guards Matched for #{trigger_delay}, delaying rule execution")
+              # Add timer and attach timer to delay object, and also state being tracked to so timer can be cancelled if
+              #   state changes
+              # Also another timer should not be created if changed to same value again but instead rescheduled
+              if trigger_delay.timer_active?
+                process_active_timer(inputs, mod, trigger_delay)
+              else
+                create_trigger_delay_timer(inputs, mod, trigger_delay)
+              end
+            else
+              logger.trace("Trigger Guards did not match for #{trigger_delay}, ignoring trigger.")
+            end
+          end
+
+          #
+          # Creatas a timer for trigger delays
+          #
+          # @param [Hash] inputs rule trigger inputs
+          # @param [Hash] mod rule trigger mods
+          # @param [TriggerDelay] trigger_delay specifications
+          #
+          #
+          def create_trigger_delay_timer(inputs, mod, trigger_delay)
+            logger.trace("Creating timer for rule #{name} and trigger delay #{trigger_delay}")
+            trigger_delay.timer = after(trigger_delay.duration) do
+              logger.trace("Delay Complete for #{trigger_delay}, executing rule")
+              trigger_delay.timer = nil
+              process_queue(@run_queue.dup, mod, inputs)
+            end
+            trigger_delay.tracking_to = inputs['newState']
+          end
+
+          #
+          # Process an active trigger timer
+          #
+          # @param [Hash] inputs rule trigger inputs
+          # @param [Hash] mod rule trigger mods
+          # @param [TriggerDelay] trigger_delay specifications
+          #
+          #
+          def process_active_timer(inputs, mod, trigger_delay)
+            state = inputs['newState']
+            if state == trigger_delay.tracking_to
+              logger.trace("Item changed to #{state} for #{trigger_delay}, rescheduling timer.")
+              trigger_delay.timer.reschedule(ZonedDateTime.now.plus(duration))
+            else
+              logger.trace("Item changed to #{state} for #{trigger_delay}, cancelling timer.")
+              trigger_delay.timer.cancel
+              # Reprocess trigger delay after cancelling to track new state (if guards matched, etc)
+              process_trigger_delay(trigger_delay, mod, inputs)
+            end
+          end
+
+          #
+          # Check if any guards prevent execution
+          #
+          # @param [Map] event OpenHAB rule trigger event
+          #
+          # @return [Boolean] True if guards says rule should execute, false otherwise
+          #
+          def check_guards(event:)
+            if @guard.should_run? event
+              now = TimeOfDay.now
+              return true if @between.cover? now
+
+              logger.trace("Skipped execution of rule '#{name}' because the current time #{now} "\
+                                   "is not between #{@between.begin} and #{@between.end}")
+            else
+              logger.trace("Skipped execution of rule '#{name}' because of guard #{@guard}")
+            end
+            false
+          end
+
+          #
+          # Patch event to include event.item when it doesn't exist
+          # This is to patch a bug see https://github.com/boc-tothefuture/openhab-jruby/issues/75
+          # It may be fixed in the openhab core in the future, in which case, this patch will no longer be necessary
+          #
+          # @param [OpenHAB Event] event to check for item accessor
+          # @param [OpenHAB Event Inputs] inputs inputs to running rule
+          #
+          def add_event_item(event, inputs)
+            return if event.nil? || defined?(event.item)
+
+            class << event
+              attr_accessor :item
+            end
+            event.item = inputs&.dig('triggeringItem')
+          end
+
+          #
+          # Process the run queue
+          #
+          # @param [Array] run_queue array of procs of various types to execute
+          # @param [Map] mod OpenHAB map object describing rule trigger
+          # @param [Map] inputs OpenHAB map object describing rule trigge
+          #
+          #
+          def process_queue(run_queue, mod, inputs)
+            event = inputs&.dig('event')
+
+            while (task = run_queue.shift)
+              case task
+              when RuleConfig::Run then process_run_task(event, inputs, task)
+              when RuleConfig::Trigger then process_trigger_task(event, task)
+              when RuleConfig::Delay then process_delay_task(inputs, mod, run_queue, task)
+              when RuleConfig::Otherwise then process_otherwise_task(event, task)
+              end
+            end
+          end
+
+          #
+          # Process an otherwise block
+          #
+          # @param [OpenHab Event] event that triggered the rule
+          # @param [Task] task task containing otherwise block to execute
+          #
+          #
+          def process_otherwise_task(event, task)
+            logger.trace { "Executing rule '#{name}' otherwise block with event(#{event})" }
+            task.block.call(event)
+          end
+
+          #
+          # Process delay task
+          #
+          # @param [Map] inputs Rule trigger inputs
+          # @param [Map] mod Rule modes
+          # @param [Queue] run_queue Queue of tasks for this rule
+          # @param [Delay] task to process
+          #
+          #
+          def process_delay_task(inputs, mod, run_queue, task)
+            remaining_queue = run_queue.slice!(0, run_queue.length)
+            after(task.duration) { process_queue(remaining_queue, mod, inputs) }
+          end
+
+          #
+          # Process a task that is caused by a group item
+          #
+          # @param [Map] event Rule event map
+          # @param [Trigger] task to execute
+          #
+          #
+          def process_trigger_task(event, task)
+            # rubocop: disable Style/GlobalVars
+            triggering_item = $ir.get(event&.itemName)
+            # rubocop: enable Style/GlobalVars
+            logger.trace { "Executing rule '#{name}' trigger block with item (#{triggering_item})" }
+            task.block.call(triggering_item) if triggering_item
+          end
+
+          #
+          # Process a run task
+          #
+          # @param [OpenHab Event] event information
+          # @param [Map] inputs of rule trigger information
+          # @param [Run] task to execute
+          #
+          #
+          def process_run_task(event, inputs, task)
+            add_event_item(event, inputs)
+            logger.trace { "Executing rule '#{name}' run block with event(#{event})" }
+            task.block.call(event)
+          end
+
+          #
+          # Create a new hash in which all elements are converted to strings
+          #
+          # @param [Map] hash in which all elements should be converted to strings
+          #
+          # @return [Map] new map with values converted to strings
+          #
+          def inspect_hash(hash)
+            hash.each_with_object({}) do |(key, value), new_hash|
+              new_hash[inspect_item(key)] = inspect_item(value)
+            end
+          end
+
+          #
+          # Convert an individual element into a string based on if it a Ruby or Java object
+          #
+          # @param [Object] item to convert to a string
+          #
+          # @return [String] representation of item
+          #
+          def inspect_item(item)
+            if item.respond_to? :to_string
+              item.to_string
+            elsif item.respond_to? :to_str
+              item.to_str
+            end
+          end
+        end
+      end
+    end
+  end
+end
+# rubocop: enable Metrics/ClassLength