openhab-scripting 2.14.0 → 2.16.0

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'pp'
+require 'core/dsl/property'
+require 'core/dsl/rule/triggers/cron'
+require 'core/dsl/rule/triggers/changed'
+require 'core/dsl/rule/triggers/channel'
+require 'core/dsl/rule/triggers/command'
+require 'core/dsl/rule/triggers/updated'
+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::Triggers
+          include Guard
+          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
+
+          # @return [Array] Of trigger guards
+          attr_accessor :guard
+
+          #
+          # 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(rule_name, caller_binding)
+            @triggers = []
+            @trigger_delays = {}
+            @caller = caller_binding.eval 'self'
+            enabled(true)
+            on_start(false)
+            name(rule_name)
+          end
+
+          #
+          # Start this rule on system startup
+          #
+          # @param [Boolean] run_on_start Run this rule on start, defaults to True
+          #
+          #
+          # rubocop: disable Style/OptionalBooleanParameter
+          # Disabled cop due to use in a DSL
+          def on_start(run_on_start = true)
+            @on_start = run_on_start
+          end
+          # rubocop: enable Style/OptionalBooleanParameter
+
+          #
+          # 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
+
+          #
+          # Create a logger where name includes rule name if name is set
+          #
+          # @return [Logging::Logger] Logger with name that appended with rule name if rule name is set
+          #
+          def logger
+            if name
+              Logging.logger(name.chomp.gsub(/\s+/, '_'))
+            else
+              super
+            end
+          end
+
+          #
+          # Inspect the config object
+          #
+          # @return [String] details of the config object
+          #
+          def inspect
+            "Name: (#{name}) " \
+            "Triggers: (#{triggers}) " \
+            "Run blocks: (#{run}) " \
+            "on_start: (#{on_start?}) " \
+            "Trigger Waits: #{trigger_delays} " \
+            "Trigger UIDs: #{triggers.map(&:id).join(', ')}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'core/log'
+
+module OpenHAB
+  module Core
+    module DSL
+      module Rule
+        #
+        # Module holds rule triggers
+        #
+        module Triggers
+          include Logging
+
+          #
+          # Struct capturing data necessary for a conditional trigger
+          #
+          TriggerDelay = Struct.new(:to, :from, :duration, :timer, :tracking_to, keyword_init: true) do
+            def timer_active?
+              timer&.is_active
+            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|
+              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|
+                  create_changed_trigger(item, from, to_state)
+                end
+              end
+            end
+          end
+
+          private
+
+          #
+          # 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)
+            # 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 changed trigger
+          #
+          # @param [Object] item to create changed trigger on
+          # @param [String] from state to restrict trigger to
+          # @param [String] to state restrict trigger to
+          #
+          #
+          def create_changed_trigger(item, from, to)
+            trigger, config = case item
+                              when GroupItems then create_group_changed_trigger(item, from, to)
+                              when Thing then create_thing_changed_trigger(item, from, to)
+                              else create_item_changed_trigger(item, from, to)
+                              end
+            append_trigger(trigger, config)
+          end
+
+          #
+          # Create a changed trigger for a thing
+          #
+          # @param [Thing] thing to detected changed states on
+          # @param [String] from state to restrict trigger to
+          # @param [String] to state to restrict trigger to
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def create_thing_changed_trigger(thing, from, to)
+            trigger_for_thing(thing, Trigger::THING_CHANGE, to, from)
+          end
+
+          #
+          # Create a changed trigger for an item
+          #
+          # @param [Item] item to detected changed states on
+          # @param [String] from state to restrict trigger to
+          # @param [String] to to restrict trigger to
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def create_item_changed_trigger(item, from, to)
+            config = { 'itemName' => item.name }
+            config['state'] = to.to_s if to
+            config['previousState'] = from.to_s if from
+            trigger = Trigger::ITEM_STATE_CHANGE
+            [trigger, config]
+          end
+
+          #
+          # Create a changed trigger for group items
+          #
+          # @param [Group] group to detected changed states on
+          # @param [String] from state to restrict trigger to
+          # @param [String] to to restrict trigger to
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def create_group_changed_trigger(group, from, to)
+            config = { 'groupName' => group.group.name }
+            config['state'] = to.to_s if to
+            config['previousState'] = from.to_s if from
+            trigger = Trigger::GROUP_STATE_CHANGE
+            [trigger, config]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/dsl/rule/{channel.rb → triggers/channel.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'core/log'
-require 'openhab/core/dsl/rule/triggers'
+require 'openhab/core/dsl/rule/triggers/trigger'
 
 module OpenHAB
   module Core
@@ -10,13 +10,14 @@ module OpenHAB
         #
         # Channel triggers
         #
-        module Channel
+        module Triggers
           include Logging
 
           #
           # Creates a channel trigger
           #
-          # @param [Array] channels array to create triggers for on form of 'binding_id:type_id:thing_id#channel_id' or 'channel_id' if thing is provided
+          # @param [Array] channels array to create triggers for on form of 'binding_id:type_id:thing_id#channel_id'
+          #   or 'channel_id' if thing is provided
           # @param [thing] thing to create trigger for if not specified with the channel
           # @param [String] triggered specific triggering condition to match for trigger
           #
@@ -26,14 +27,27 @@ module OpenHAB
               channel = [thing, channel].join(':') if thing
               logger.trace("Creating channel trigger for channel(#{channel}), thing(#{thing}), trigger(#{triggered})")
               [triggered].flatten.each do |trigger|
-                config = { 'channelUID' => channel }
-                config['event'] = trigger.to_s unless trigger.nil?
-                config['channelUID'] = channel
-                logger.trace("Creating Change Trigger for #{config}")
-                @triggers << Trigger.trigger(type: Trigger::CHANNEL_EVENT, config: config)
+                create_channel_trigger(channel, trigger)
               end
             end
           end
+
+          private
+
+          #
+          # Create a trigger for a channel
+          #
+          # @param [Channel] channel to look for triggers
+          # @param [Trigger] trigger specific channel trigger to match
+          #
+          #
+          def create_channel_trigger(channel, trigger)
+            config = { 'channelUID' => channel }
+            config['event'] = trigger.to_s unless trigger.nil?
+            config['channelUID'] = channel
+            logger.trace("Creating Change Trigger for #{config}")
+            @triggers << Trigger.trigger(type: Trigger::CHANNEL_EVENT, config: config)
+          end
         end
       end
     end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'core/log'
+
+module OpenHAB
+  module Core
+    module DSL
+      module Rule
+        #
+        # Module holds rule triggers
+        #
+        module Triggers
+          include Logging
+
+          #
+          # 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 = combine_commands(command, commands)
+              create_received_trigger(combined_commands, item)
+            end
+          end
+
+          private
+
+          #
+          # Create a received trigger based on item type
+          #
+          # @param [Array] commands to create trigger for
+          # @param [Object] item to create trigger for
+          #
+          #
+          def create_received_trigger(commands, item)
+            commands.each do |command|
+              if item.is_a? GroupItems
+                config, trigger = create_group_command_trigger(item)
+              else
+                config, trigger = create_item_command_trigger(item)
+              end
+              config['command'] = command.to_s unless command.nil?
+              append_trigger(trigger, config)
+            end
+          end
+
+          #
+          # Create trigger for item commands
+          #
+          # @param [Item] item to create trigger for
+          #
+          # @return [Array<Hash,Trigger>] first element is hash of trigger config properties
+          #   second element is trigger type
+          #
+          def create_item_command_trigger(item)
+            config = { 'itemName' => item.name }
+            trigger = Trigger::ITEM_COMMAND
+            [config, trigger]
+          end
+
+          #
+          # Create trigger for group items
+          #
+          # @param [Group] group to create trigger for
+          #
+          # @return [Array<Hash,Trigger>] first element is hash of trigger config properties
+          #   second element is trigger type
+          #
+          def create_group_command_trigger(group)
+            config = { 'groupName' => group.group.name }
+            trigger = Trigger::GROUP_COMMAND
+            [config, trigger]
+          end
+
+          #
+          # Combine command and commands into a single array
+          #
+          # @param [Array] command list of commands to trigger on
+          # @param [Array] commands list of commands to trigger on
+          #
+          # @return [Array] Combined flattened and compacted list of commands
+          #
+          def combine_commands(command, commands)
+            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
+          end
+        end
+      end
+    end
+  end
+end