openhab-scripting 2.9.1

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

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'core/log'
+require 'core/dsl/group'
+require 'core/dsl/things'
+require 'core/dsl/rule/triggers'
+require 'openhab/core/dsl/rule/triggers'
+
+module OpenHAB
+  module Core
+    module DSL
+      module Rule
+        #
+        # Triggers for items in rules
+        #
+        module Item
+          include Logging
+          include OpenHAB::Core::DSL::Rule
+          include OpenHAB::Core::DSL::Groups
+          include OpenHAB::Core::DSL::Things
+
+          #
+          # Struct capturing data necessary for a conditional trigger
+          #
+          TriggerDelay = Struct.new(:to, :from, :duration, :timer, :tracking_to, keyword_init: true)
+
+          #
+          # Create a TriggerDelay for for an item or group that is changed for a specific duration
+          #
+          # @param [Object] item to create trigger delay for
+          # @param [OpenHAB::Core::Duration] duration to delay trigger for until condition is met
+          # @param [Item State] to OpenHAB Item State item or group needs to change to
+          # @param [Item State] from OpenHAB Item State item or group needs to be coming from
+          #
+          # @return [Array] Array of current TriggerDelay objects
+          #
+          def changed_wait(item, duration:, to: nil, from: nil)
+            # Convert to testing the group if group specified rather than item
+            item = item.group if item.is_a? Group
+
+            # If GroupItems specified, use the group state trigger instead
+            if item.is_a? GroupItems
+              config = { 'groupName' => item.group.name }
+              trigger = Trigger::GROUP_STATE_CHANGE
+            else
+              config = { 'itemName' => item.name }
+              trigger = Trigger::ITEM_STATE_CHANGE
+            end
+            logger.trace("Creating Changed Wait Change Trigger for #{config}")
+            trigger = append_trigger(trigger, config)
+            @trigger_delays = { trigger.id => TriggerDelay.new(to: to, from: from, duration: duration) }
+          end
+
+          #
+          # Create a trigger for when an item or group receives a command
+          #
+          # The commands/commands parameters are replicated for DSL fluency
+          #
+          # @param [Array] items Array of items to create trigger for
+          # @param [Array] command commands to match for trigger
+          # @param [Array] commands commands to match for trigger
+          #
+          #
+          def received_command(*items, command: nil, commands: nil)
+            items.flatten.each do |item|
+              logger.trace("Creating received command trigger for item(#{item}) command(#{command}) commands(#{commands})")
+
+              # Combine command and commands, doing union so only a single nil will be in the combined array.
+              combined_commands = ([command] | [commands]).flatten
+
+              # If either command or commands has a value and one is nil, we need to remove nil from the array.
+              # If it is only now a single nil value, we leave the nil in place, so that we create a trigger
+              # That isn't looking for a specific command.
+              combined_commands = combined_commands.compact unless combined_commands.all?(&:nil?)
+
+              combined_commands.each do |cmd|
+                if item.is_a? GroupItems
+                  config = { 'groupName' => item.group.name }
+                  trigger = Trigger::GROUP_COMMAND
+                else
+                  config = { 'itemName' => item.name }
+                  trigger = Trigger::ITEM_COMMAND
+                end
+                config['command'] = cmd.to_s unless cmd.nil?
+                append_trigger(trigger, config)
+              end
+            end
+          end
+
+          #
+          # Create a trigger when item, group or thing is updated
+          #
+          # @param [Array] items array to trigger on updated
+          # @param [State] to to match for tigger
+          #
+          # @return [Trigger] Trigger for updated entity
+          #
+          def updated(*items, to: nil)
+            items.flatten.each do |item|
+              logger.trace("Creating updated trigger for item(#{item}) to(#{to})")
+              [to].flatten.each do |to_state|
+                case item
+                when GroupItems
+                  config = { 'groupName' => item.group.name }
+                  config['state'] = to_state.to_s unless to_state.nil?
+                  trigger = Trigger::GROUP_STATE_UPDATE
+                when Thing
+                  trigger, config = trigger_for_thing(item, Trigger::THING_UPDATE, to_state)
+                else
+                  config = { 'itemName' => item.name }
+                  config['state'] = to_state.to_s unless to_state.nil?
+                  trigger = Trigger::ITEM_STATE_UPDATE
+                end
+                append_trigger(trigger, config)
+              end
+            end
+          end
+
+          #
+          # Creates a trigger item, group and thing changed
+          #
+          # @param [Object] items array of objects to create trigger for
+          # @param [to] to state for object to change for
+          # @param [from] from <description>
+          # @param [OpenHAB::Core::Duration] for Duration to delay trigger until to state is met
+          #
+          # @return [Trigger] OpenHAB trigger
+          #
+          def changed(*items, to: nil, from: nil, for: nil)
+            items.flatten.each do |item|
+              item = item.group if item.is_a? Group
+              logger.trace("Creating changed trigger for entity(#{item}), to(#{to}), from(#{from})")
+              # for is a reserved word in ruby, so use local_variable_get :for
+              if (wait_duration = binding.local_variable_get(:for))
+                changed_wait(item, to: to, from: from, duration: wait_duration)
+              else
+                # Place in array and flatten to support multiple to elements or single or nil
+                [to].flatten.each do |to_state|
+                  case item
+                  when GroupItems
+                    config = { 'groupName' => item.group.name }
+                    config['state'] = to_state.to_s if to_state
+                    config['previousState'] = from.to_s if from
+                    trigger = Trigger::GROUP_STATE_CHANGE
+                  when Thing
+                    trigger, config = trigger_for_thing(item, Trigger::THING_CHANGE, to_state, from)
+                  else
+                    config = { 'itemName' => item.name }
+                    config['state'] = to_state.to_s if to_state
+                    config['previousState'] = from.to_s if from
+                    trigger = Trigger::ITEM_STATE_CHANGE
+                  end
+                  append_trigger(trigger, config)
+                end
+              end
+            end
+          end
+
+          private
+
+          #
+          # Append a trigger to the list of triggeres
+          #
+          # @param [String] type of trigger to create
+          # @param [Map] config map describing trigger configuration
+          #
+          # @return [Trigger] OpenHAB trigger
+          #
+          def append_trigger(type, config)
+            logger.trace("Creating trigger of type #{type} for #{config}")
+            trigger = Trigger.trigger(type: type, config: config)
+            @triggers << trigger
+            trigger
+          end
+
+          #
+          # Create a trigger for a thing
+          #
+          # @param [Thing] thing to create trigger for
+          # @param [Trigger] trigger to map with thing
+          # @param [State] to for thing
+          # @param [State] from state of thing
+          #
+          # @return [Array] Trigger and config for thing
+          #
+          def trigger_for_thing(thing, trigger, to = nil, from = nil)
+            config = { 'thingUID' => thing.uid.to_s }
+            config['status'] = trigger_state_from_symbol(to).to_s if to
+            config['previousStatus'] = trigger_state_from_symbol(from).to_s if from
+            [trigger, config]
+          end
+
+          #
+          # converts object to upcase string if its a symbol
+          #
+          # @param [sym] sym potential symbol to convert
+          #
+          # @return [String] Upcased symbol as string
+          #
+          def trigger_state_from_symbol(sym)
+            sym.to_s.upcase if (sym.is_a? Symbol) || sym
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'pp'
+require 'core/dsl/property'
+require 'core/dsl/rule/cron'
+require 'core/dsl/rule/triggers'
+require 'core/dsl/rule/item'
+require 'core/dsl/rule/channel'
+require 'core/dsl/rule/guard'
+require 'core/dsl/entities'
+require 'core/dsl/time_of_day'
+require 'core/dsl'
+require 'core/dsl/timers'
+
+module OpenHAB
+  module Core
+    module DSL
+      #
+      # Creates and manages OpenHAB Rules
+      #
+      module Rule
+        #
+        # Rule configuration for OpenHAB Rules engine
+        #
+        class RuleConfig
+          include EntityLookup
+          include OpenHAB::Core::DSL::Rule::Cron
+          include Guard
+          include Item
+          include Channel
+          include DSLProperty
+          include Logging
+          extend OpenHAB::Core::DSL
+
+          java_import org.openhab.core.library.items.SwitchItem
+
+          # @return [Array] Of triggers
+          attr_reader :triggers
+
+          # @return [Array] Of trigger delays
+          attr_reader :trigger_delays
+
+          #
+          # Struct holding a run block
+          #
+          Run = Struct.new(:block)
+
+          #
+          # Struct holding a Triggered block
+          #
+          Trigger = Struct.new(:block)
+
+          #
+          # Struct holding an otherwise block
+          #
+          Otherwise = Struct.new(:block)
+
+          #
+          # Struct holding rule delays
+          #
+          Delay = Struct.new(:duration)
+
+          prop_array :run, array_name: :run_queue, wrapper: Run
+          prop_array :triggered, array_name: :run_queue, wrapper: Trigger
+          prop_array :delay, array_name: :run_queue, wrapper: Delay
+          prop_array :otherwise, array_name: :run_queue, wrapper: Otherwise
+
+          prop :name
+          prop :description
+          prop :enabled
+          prop :between
+
+          #
+          # Create a new RuleConfig
+          #
+          # @param [Object] caller_binding The object initializing this configuration.
+          #   Used to execute within the object's context
+          #
+          def initialize(caller_binding)
+            @triggers = []
+            @trigger_delays = {}
+            @enabled = true
+            @on_start = false
+            @caller = caller_binding.eval 'self'
+          end
+
+          #
+          # Start this rule on system startup
+          #
+          # @param [Boolean] run_on_start Run this rule on start, defaults to True
+          #
+          #
+          def on_start(run_on_start = true)
+            @on_start = run_on_start
+          end
+
+          #
+          # Checks if this rule should run on start
+          #
+          # @return [Boolean] True if rule should run on start, false otherwise.
+          #
+          def on_start?
+            @on_start
+          end
+
+          #
+          # Run the supplied block inside the object instance of the object that created the rule config
+          #
+          # @yield [] Block executed in context of the object creating the rule config
+          #
+          #
+          def my(&block)
+            @caller.instance_eval(&block)
+          end
+        end
+
+        #
+        # Create a new rule
+        #
+        # @param [String] name <description>
+        # @yield [] Block executed in context of a RuleConfic
+        #
+        #
+        def rule(name, &block)
+          config = RuleConfig.new(block.binding)
+          config.name(name)
+          config.instance_eval(&block)
+          return if !config.on_start? && config.triggers.empty?
+
+          guard = Guard::Guard.new(only_if: config.only_if, not_if: config.not_if)
+
+          logger.trace do
+            "Triggers: #{config.triggers} Guard: #{guard} Runs: #{config.run} on_start: #{config.on_start?}"
+          end
+          config.triggers.each { |trigger| logger.trace { "Trigger UID: #{trigger.id}" } }
+          logger.trace { "Trigger Waits #{config.trigger_delays}" }
+
+          if config.enabled
+            # Convert between to correct range or nil if not set
+            between = config.between&.yield_self { between(config.between) }
+
+            rule = Rule.new(name: config.name, description: config.description, run_queue: config.run_queue,
+                            guard: guard, between: between, trigger_delays: config.trigger_delays)
+
+            rule.set_triggers(config.triggers)
+            am = $scriptExtension.get('automationManager')
+            am.addRule(rule)
+            rule.execute(nil, nil) if config.on_start?
+          else
+            logger.debug "#{name} marked as disabled, not creating rule."
+          end
+        end
+
+        #
+        # JRuby extension to OpenHAB Rule
+        #
+        class Rule < Java::OrgOpenhabCoreAutomationModuleScriptRulesupportSharedSimple::SimpleRule
+          include Logging
+          include OpenHAB::Core::DSL::Tod
+          java_import java.time.ZonedDateTime
+
+          #
+          # Create a new Rule
+          #
+          # @param [String] name Name of the rule
+          # @param [String] description of the rule
+          # @param [Array] run_queue array of procs to execute for rule
+          # @param [Array] guard array of guards
+          # @param [Range] between range in which the rule will execute
+          # @param [Array] trigger_delays Array of delays for tiggers based on item config
+          #
+          def initialize(name:, description:, run_queue:, guard:, between:, trigger_delays:)
+            super()
+            setName(name)
+            setDescription(description)
+            @run_queue = run_queue
+            @guard = guard
+            @between = between || OpenHAB::Core::DSL::Tod::ALL_DAY
+            @trigger_delays = 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, inputs)
+            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
+              process_trigger_delay(mod, inputs)
+            else
+              # If guards are satisfied execute the run type blocks
+              # If they are not satisfied, execute the Othewise blocks
+              queue = case check_guards(event: inputs&.dig('event'))
+                      when true
+                        @run_queue.dup
+                      when false
+                        @run_queue.dup.grep(RuleConfig::Otherwise)
+                      end
+              process_queue(queue, mod, inputs)
+            end
+          end
+
+          private
+
+          #
+          # 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 map from OpenHAB describing the rle 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 trigger_delay.from.nil? || trigger_delay.from == old_state
+              if trigger_delay.to.nil? || trigger_delay.to == new_state
+                return true
+              else
+                logger.trace("Skipped execution of rule '#{name}' because to state #{new_state} does not equal specified state(#{trigger_delay.to})")
+              end
+            else
+              logger.trace("Skipped execution of rule '#{name}' because old state #{old_state} does not equal specified state(#{trigger_delay.from})")
+            end
+            false
+          end
+
+          #
+          # Process any matching trigger delays
+          #
+          # @param [Map] mod OpenHAB map object describing rule trigger
+          # @param [Map] inputs OpenHAB map object describing rule trigge
+          #
+          #
+          def process_trigger_delay(mod, inputs)
+            trigger_delay = trigger_delay(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.nil? || trigger_delay.timer.is_active == false
+                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']
+              else
+                # Timer active
+                state = inputs['newState']
+                if state != trigger_delay.tracking_to
+                  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(mod, inputs)
+                else
+                  logger.trace("Item changed to #{state} for #{trigger_delay}, rescheduling timer.")
+                  trigger_delay.timer.reschedule(ZonedDateTime.now.plus(Java::JavaTime::Duration.ofMillis(duration.to_ms)))
+                end
+              end
+            else
+              logger.trace("Trigger Guards did not match for #{trigger_delay}, ignoring trigger.")
+            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
+              if @between.cover? now
+                return true
+              else
+                logger.trace("Skipped execution of rule '#{name}' because the current time #{now} is not between #{@between.begin} and #{@between.end}")
+              end
+            else
+              logger.trace("Skipped execution of rule '#{name}' because of guard #{@guard}")
+            end
+            false
+          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)
+            while (task = run_queue.shift)
+              case task
+              when RuleConfig::Run
+
+                event = inputs&.dig('event')
+
+                logger.trace { "Executing rule '#{name}' run block with event(#{event})" }
+                task.block.call(event)
+              when RuleConfig::Trigger
+
+                triggering_item = $ir.get(inputs&.dig('event')&.itemName)
+
+                logger.trace { "Executing rule '#{name}' trigger block with item (#{triggering_item})" }
+                task.block.call(triggering_item) if triggering_item
+
+              when RuleConfig::Delay
+                remaining_queue = run_queue.slice!(0, run_queue.length)
+                after(task.duration) { process_queue(remaining_queue, mod, inputs) }
+
+              when RuleConfig::Otherwise
+                event = inputs&.dig('event')
+                logger.trace { "Executing rule '#{name}' otherwise block with event(#{event})" }
+                task.block.call(event)
+
+              end
+            end
+          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