openhab-scripting 4.46.2 → 5.0.0

data/lib/openhab/dsl/rules/terse.rb

@@ -3,21 +3,65 @@
 module OpenHAB
   module DSL
     module Rules
-      # Module containing terse rule stubs
-      module TerseRule
-        %i[changed channel cron every updated received_command].each do |trigger|
-          class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
-            def #{trigger}(*args, name: nil, id: nil, **kwargs, &block)   # def changed(*args, name: nil, id: nil, **kwargs, &block)
-              id ||= NameInference.infer_rule_id_from_block(block)        #   id ||= NameInference.infer_rule_id_from_block(block)
-              script = block.source rescue nil                            #   script = block.source rescue nil
-              rule name, id: id, script: script do                        #   rule name, id: id, script: script do
-                #{trigger}(*args, **kwargs)                               #     changed(*args, **kwargs)
-                run(&block)                                               #     run(&block)
-              end                                                         #   end
-            end                                                           # end
-            module_function #{trigger.inspect}                            # module_function :changed
-          RUBY
+      # If you have a single trigger and execution block, you can use a terse rule:
+      # All parameters to the trigger are passed through, and an optional `name:` parameter is added.
+      #
+      # @example
+      #   changed TestSwitch do |event|
+      #     logger.info("TestSwitch changed to #{event.state}")
+      #   end
+      #
+      # @example
+      #   received_command TestSwitch, name: "My Test Switch Rule", command: ON do
+      #     logger.info("TestSwitch received command ON")
+      #   end
+      #
+      module Terse
+        class << self
+          # @!visibility private
+          # @!macro def_terse_rule
+          #   @!method $1(*args, name :nil, id: nil, on_load: false, **kwargs, &block)
+          #   Create a new rule with a $1 trigger.
+          #   @param name [String] The name for the rule.
+          #   @param id [String] The ID for the rule.
+          #   @param on_load [true, false] If the rule should _also_ trigger immediately when the script loads.
+          #   @yield The execution block for the rule.
+          #   @return [void]
+          #   @see BuilderDSL#$1
+          def def_terse_rule(trigger)
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+              def #{trigger}(*args, name: nil, id: nil, on_load: false, **kwargs, &block)     # def changed(*args, name: nil, id: nil, on_load: false, **kwargs, &block)
+                raise ArgumentError, "Block is required" unless block                         #   raise ArgumentError, "Block is required" unless block
+                                                                                              #
+                id ||= NameInference.infer_rule_id_from_block(block)                          #   id ||= NameInference.infer_rule_id_from_block(block)
+                script = block.source rescue nil                                              #   script = block.source rescue nil
+                caller_binding = block.binding                                                #   caller_binding = block.binding
+                rule name, id: id, script: script, binding: caller_binding do                 #   rule name, id: id, script: script, binding: caller_binding do
+                  self.on_load if on_load                                                     #     self.on_load if on_load
+                  #{trigger}(*args, **kwargs)                                                 #     changed(*args, **kwargs)
+                  run(&block)                                                                 #     run(&block)
+                end                                                                           #   end
+              end                                                                             # end
+              module_function #{trigger.inspect}                                              # module_function :changed
+            RUBY
+          end
         end
+
+        def_terse_rule(:changed)
+        def_terse_rule(:channel)
+        def_terse_rule(:channel_linked)
+        def_terse_rule(:channel_unlinked)
+        def_terse_rule(:cron)
+        def_terse_rule(:every)
+        def_terse_rule(:item_added)
+        def_terse_rule(:item_updated)
+        def_terse_rule(:item_removed)
+        def_terse_rule(:on_start)
+        def_terse_rule(:received_command)
+        def_terse_rule(:thing_added)
+        def_terse_rule(:thing_updated)
+        def_terse_rule(:thing_removed)
+        def_terse_rule(:updated)
       end
     end
   end

data/lib/openhab/dsl/rules/triggers/changed.rb

@@ -1,80 +1,28 @@
 # frozen_string_literal: true
 
-require 'openhab/log/logger'
-require_relative 'conditions/duration'
-require_relative 'conditions/proc'
-require_relative 'trigger'
+require_relative "conditions/duration"
+require_relative "conditions/proc"
+require_relative "trigger"
 
 module OpenHAB
   module DSL
     module Rules
-      #
-      # Module for changed triggers
-      #
-
       module Triggers
-        include OpenHAB::Log
-
-        #
-        # 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
-        # @param [Object] attach object to be attached to the trigger
-        #
-        # @return [Trigger] OpenHAB trigger
-        #
-        def changed(*items, to: nil, from: nil, for: nil, attach: nil)
-          changed = Changed.new(rule_triggers: @rule_triggers)
-          # for is a reserved word in ruby, so use local_variable_get :for
-          duration = binding.local_variable_get(:for)
-
-          flattened_items = Changed.flatten_items(items)
-          @ruby_triggers << [:changed, flattened_items, { to: to, from: from, duration: duration }]
-          flattened_items.map do |item|
-            logger.trace("Creating changed trigger for entity(#{item}), to(#{to}), from(#{from})")
-
-            Changed.each_state(from, to) do |from_state, to_state|
-              changed.trigger(item: item, from: from_state, to: to_state, duration: duration, attach: attach)
-            end
-          end.flatten
-        end
-
+        # @!visibility private
         #
         # Creates changed triggers
         #
         class Changed < Trigger
-          #
-          # Run block for each state combination
-          #
-          # @param [Item State, Array<Item State>] from state to restrict trigger to
-          # @param [Item State, Array<Item State>] to state to restrict trigger to
-          #
-          # @yieldparam [Item State] from_state from state
-          # @yieldparam [Item State] to_state to state
-          #
-          # @return [Array] array of block return values
-          #
-          def self.each_state(from, to)
-            [to].flatten.each_with_object([]) do |to_state, agg|
-              [from].flatten.each do |from_state|
-                agg.push(yield(from_state, to_state))
-              end
-            end
-          end
-
           #
           # Create the trigger
           #
-          # @param [Object] item item to create trigger for
-          # @param [Item State] from state to restrict trigger to
-          # @param [Item State] to state to restrict trigger to
-          # @param [OpenHAB::Core::Duration, nil] duration ruration to delay trigger until to state is met
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item item to create trigger for
+          # @param [Core::Types::State, Array<Core::Types::State>, Range, Proc] from state to restrict trigger to
+          # @param [Core::Types::State, Array<Core::Types::State>, Range, Proc] to state to restrict trigger to
+          # @param [Duration, nil] duration duration to delay trigger until to state is met
           # @param [Object] attach object to be attached to the trigger
           #
-          # @return [Trigger] OpenHAB triggers
+          # @return [org.openhab.core.automation.Trigger] openHAB triggers
           #
           def trigger(item:, from:, to:, duration:, attach:)
             if duration
@@ -91,24 +39,26 @@ module OpenHAB
           private
 
           # @return [String] A thing status Change trigger
-          THING_CHANGE = 'core.ThingStatusChangeTrigger'
+          THING_CHANGE = "core.ThingStatusChangeTrigger"
 
           # @return [String] An item state change trigger
-          ITEM_STATE_CHANGE = 'core.ItemStateChangeTrigger'
+          ITEM_STATE_CHANGE = "core.ItemStateChangeTrigger"
 
           # @return [String] A group state change trigger for items in the group
-          GROUP_STATE_CHANGE = 'core.GroupStateChangeTrigger'
+          GROUP_STATE_CHANGE = "core.GroupStateChangeTrigger"
 
           #
           # 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
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item to create trigger delay for
+          # @param [Duration] duration to delay trigger for until condition is met
+          # @param [Core::Types::State, Array<Core::Types::State>, Range, Proc] to
+          #   State item or group needs to change to
+          # @param [Core::Types::State, Array<Core::Types::State>, Range, Proc] from
+          #   State item or group needs to be coming from
           # @param [Object] attach object to be attached to the trigger
           #
-          # @return [Trigger] OpenHAB trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def wait_trigger(item:, duration:, to: nil, from: nil, attach: nil)
             item_name = item.respond_to?(:name) ? item.name : item.to_s
@@ -120,11 +70,11 @@ module OpenHAB
 
           #
           # Creates a trigger with a range condition on either 'from' or 'to' field
-          # @param [Object] item to create changed trigger on
-          # @param [Object] from state to restrict trigger to
-          # @param [Object] to state restrict trigger to
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item to create changed trigger on
+          # @param [Range] from state to restrict trigger to
+          # @param [Range] to state restrict trigger to
           # @param [Object] attach object to be attached to the trigger
-          # @return [Trigger] OpenHAB trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def range_trigger(item:, from:, to:, attach:)
             from, to = Conditions::Proc.range_procs(from, to)
@@ -133,17 +83,17 @@ module OpenHAB
 
           #
           # Creates a trigger with a proc condition on either 'from' or 'to' field
-          # @param [Object] item to create changed trigger on
-          # @param [Object] from state to restrict trigger to
-          # @param [Object] to state restrict trigger to
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item to create changed trigger on
+          # @param [Proc] from state to restrict trigger to
+          # @param [Proc] to state restrict trigger to
           # @param [Object] attach object to be attached to the trigger
-          # @return [Trigger] OpenHAB trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def proc_trigger(item:, from:, to:, attach:)
             # swap from/to w/ nil if from/to is a proc
             # rubocop:disable Style/ParallelAssignment
-            from_proc, from = from, nil if from.is_a? Proc
-            to_proc, to = to, nil if to.is_a? Proc
+            from_proc, from = from, nil if from.is_a?(Proc)
+            to_proc, to = to, nil if to.is_a?(Proc)
             # rubocop:enable Style/ParallelAssignment
             conditions = Conditions::Proc.new(to: to_proc, from: from_proc)
             changed_trigger(item: item, from: from, to: to, attach: attach, conditions: conditions)
@@ -152,17 +102,21 @@ module OpenHAB
           #
           # Create a changed trigger
           #
-          # @param [Object] item to create changed trigger on
-          # @param [Object] from state to restrict trigger to
-          # @param [Object] to state restrict trigger to
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item to create changed trigger on
+          # @param [Core::Items::State, Array<Core::Items::State>] from state to restrict trigger to
+          # @param [Core::Items::State, Array<Core::Items::State>] to state restrict trigger to
           # @param [Object] attach object to be attached to the trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def changed_trigger(item:, from:, to:, attach: nil, conditions: nil)
             type, config = case item
-                           when OpenHAB::DSL::Items::GroupItem::GroupMembers then group(group: item, from: from,
-                                                                                        to: to)
-                           when Thing then thing(thing: item, from: from, to: to)
-                           else item(item: item, from: from, to: to)
+                           when GroupItem::Members
+                             group(group: item, from: from, to: to)
+                           when Core::Things::Thing,
+                                Core::Things::ThingUID
+                             thing(thing: item, from: from, to: to)
+                           else
+                             item(item: item, from: from, to: to)
                            end
             append_trigger(type: type, config: config, attach: attach, conditions: conditions)
           end
@@ -170,7 +124,7 @@ module OpenHAB
           #
           # Create a changed trigger for a thing
           #
-          # @param [Thing] thing to detected changed states on
+          # @param [Core::Things::Thing] thing to detected changed states on
           # @param [String] from state to restrict trigger to
           # @param [String] to state to restrict trigger to
           #
@@ -192,16 +146,16 @@ module OpenHAB
           #  second element is a Hash configuring trigger
           #
           def item(item:, from:, to:)
-            config = { 'itemName' => item.name }
-            config['state'] = to.to_s if to
-            config['previousState'] = from.to_s if from
+            config = { "itemName" => item.name }
+            config["state"] = to.to_s if to
+            config["previousState"] = from.to_s if from
             [ITEM_STATE_CHANGE, config]
           end
 
           #
           # Create a changed trigger for group items
           #
-          # @param [Group] group to detected changed states on
+          # @param [GroupItem] group to detected changed states on
           # @param [String] from state to restrict trigger to
           # @param [String] to to restrict trigger to
           #
@@ -209,9 +163,9 @@ module OpenHAB
           #  second element is a Hash configuring trigger
           #
           def group(group:, from:, to:)
-            config = { 'groupName' => group.group.name }
-            config['state'] = to.to_s if to
-            config['previousState'] = from.to_s if from
+            config = { "groupName" => group.name }
+            config["state"] = to.to_s if to
+            config["previousState"] = from.to_s if from
             [GROUP_STATE_CHANGE, config]
           end
         end

data/lib/openhab/dsl/rules/triggers/channel.rb

@@ -1,49 +1,18 @@
 # frozen_string_literal: true
 
-require 'openhab/log/logger'
-require 'openhab/dsl/things'
-require_relative 'trigger'
+require_relative "trigger"
 
 module OpenHAB
   module DSL
     module Rules
-      #
-      # Channel triggers
-      #
       module Triggers
-        include OpenHAB::Log
-
-        #
-        # Creates a channel trigger
-        #
-        # @param [String, Channel, ChannelUID, Array<String, Channel, ChannelUID>] channels
-        #   channels to create triggers for in form of 'binding_id:type_id:thing_id#channel_id'
-        #   or 'channel_id' if thing is provided
-        # @param [String, Thing, ThingUID, Array<String, Thing, ThingUID>] thing
-        #   thing(s) to create trigger for if not specified with the channel
-        # @param [String, Array<String>] triggered specific triggering condition(s) to match for trigger
-        # @param [Object] attach object to be attached to the trigger
-        #
-        def channel(*channels, thing: nil, triggered: nil, attach: nil)
-          channel_trigger = Channel.new(rule_triggers: @rule_triggers)
-          flattened_channels = Channel.channels(channels: channels, thing: thing)
-          triggers = [triggered].flatten
-          @ruby_triggers << [:channel, flattened_channels, { triggers: triggers }]
-          flattened_channels.each do |channel|
-            triggers.each do |trigger|
-              channel_trigger.trigger(channel: channel, trigger: trigger, attach: attach)
-            end
-          end
-        end
-
+        # @!visibility private
         #
         # Creates channel triggers
         #
         class Channel < Trigger
-          include OpenHAB::Log
-
           # @return [String] A channel event trigger
-          CHANNEL_EVENT = 'core.ChannelEventTrigger'
+          CHANNEL_EVENT = "core.ChannelEventTrigger"
 
           #
           # Get an enumerator over the product of the channels and things and map them to a channel id
@@ -51,7 +20,7 @@ module OpenHAB
           # @param [Object] thing to combine with channels and iterate over
           # @return [Enumerable] enumerable channel ids to trigger on
           def self.channels(channels:, thing:)
-            logger.state 'Creating Channel/Thing Pairs', channels: channels, thing: thing
+            logger.trace "Creating Channel/Thing Pairs for channels #{channels.inspect} and things #{thing.inspect}"
             channels.flatten.product([thing].flatten)
                     .map { |channel_thing| channel_id(*channel_thing) }
           end
@@ -63,8 +32,8 @@ module OpenHAB
           #
           def self.channel_id(channel, thing)
             channel = channel.uid if channel.is_a?(org.openhab.core.thing.Channel)
-            thing = thing.uid if thing.is_a?(Thing)
-            [thing, channel].compact.join(':')
+            thing = thing.uid if thing.is_a?(Core::Things::Thing)
+            [thing, channel].compact.join(":")
           end
 
           #
@@ -76,9 +45,9 @@ module OpenHAB
           #
           #
           def trigger(channel:, trigger:, attach:)
-            config = { 'channelUID' => channel }
-            config['event'] = trigger.to_s unless trigger.nil?
-            logger.state 'Creating Channel Trigger', channel: channel, config: config
+            config = { "channelUID" => channel }
+            config["event"] = trigger.to_s unless trigger.nil?
+            logger.trace "Creating Channel Trigger for channels #{channel.inspect} and config #{config.inspect}"
             append_trigger(type: CHANNEL_EVENT, config: config, attach: attach)
           end
         end

data/lib/openhab/dsl/rules/triggers/command.rb

@@ -1,66 +1,16 @@
 # frozen_string_literal: true
 
-require 'openhab/log/logger'
-require_relative 'trigger'
+require_relative "trigger"
 
 module OpenHAB
   module DSL
     module Rules
-      #
-      # Module holds rule triggers
-      #
       module Triggers
-        include OpenHAB::Log
-
-        #
-        # 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
-        # @param [Object] attach object to be attached to the trigger
-        #
-        #
-        def received_command(*items, command: nil, commands: nil, attach: nil)
-          command_trigger = Command.new(rule_triggers: @rule_triggers)
-
-          # Combine command and commands, doing union so only a single nil will be in the combined array.
-          combined_commands = Command.combine_commands(command: command, commands: commands)
-          flattened_items = Command.flatten_items(items)
-          @ruby_triggers << [:received_command, flattened_items, { command: combined_commands }]
-
-          flattened_items.map do |item|
-            combined_commands.map do |cmd|
-              logger.states 'Creating received command trigger', item: item, command: cmd
-
-              command_trigger.trigger(item: item, command: cmd, attach: attach)
-            end
-          end.flatten
-        end
-
+        # @!visibility private
         #
         # Creates command triggers
         #
         class Command < Trigger
-          # 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 self.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
-
           #
           # Create a received command trigger
           #
@@ -68,7 +18,7 @@ module OpenHAB
           # @param [Object] command to check against
           # @param [Object] attach object to be attached to the trigger
           #
-          # @return [Trigger] OpenHAB triggers
+          # @return [org.openhab.core.automation.Trigger]
           #
           def trigger(item:, command:, attach:)
             case command
@@ -81,9 +31,9 @@ module OpenHAB
           #
           # Creates a trigger with a range condition on the 'command' field
           # @param [Object] item to create changed trigger on
-          # @param [Object] command to restrict trigger to
+          # @param [Range] command to restrict trigger to
           # @param [Object] attach object to be attached to the trigger
-          # @return [Trigger] OpenHAB trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def range_trigger(item:, command:, attach:)
             command_range, * = Conditions::Proc.range_procs(command)
@@ -95,7 +45,7 @@ module OpenHAB
           # @param [Object] item to create changed trigger on
           # @param [Object] command to restrict trigger to
           # @param [Object] attach object to be attached to the trigger
-          # @return [Trigger] OpenHAB trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def proc_trigger(item:, command:, attach:)
             conditions = Conditions::Proc.new(command: command)
@@ -108,24 +58,25 @@ module OpenHAB
           # @param [Object] item to create trigger for
           # @param [String] command to create trigger for
           # @param [Object] attach object to be attached to the trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def command_trigger(item:, command:, attach: nil, conditions: nil)
-            type, config = if item.is_a? OpenHAB::DSL::Items::GroupItem::GroupMembers
+            type, config = if item.is_a?(GroupItem::Members)
                              group(group: item)
                            else
                              item(item: item)
                            end
-            config['command'] = command.to_s unless command.nil?
+            config["command"] = command.to_s unless command.nil?
             append_trigger(type: type, config: config, attach: attach, conditions: conditions)
           end
 
           private
 
           # @return [String] item command trigger
-          ITEM_COMMAND = 'core.ItemCommandTrigger'
+          ITEM_COMMAND = "core.ItemCommandTrigger"
 
           # @return [String] A group command trigger for items in the group
-          GROUP_COMMAND = 'core.GroupCommandTrigger'
+          GROUP_COMMAND = "core.GroupCommandTrigger"
 
           #
           # Create trigger for item commands
@@ -136,19 +87,19 @@ module OpenHAB
           #   second element is trigger type
           #
           def item(item:)
-            [ITEM_COMMAND, { 'itemName' => item.name }]
+            [ITEM_COMMAND, { "itemName" => item.name }]
           end
 
           #
           # Create trigger for group items
           #
-          # @param [Group] group to create trigger for
+          # @param [GroupItem::Members] group to create trigger for
           #
           # @return [Array<Hash,Trigger>] first element is hash of trigger config properties
           #   second element is trigger type
           #
           def group(group:)
-            [GROUP_COMMAND, { 'groupName' => group.group.name }]
+            [GROUP_COMMAND, { "groupName" => group.group.name }]
           end
         end
       end