openhab-scripting 4.32.4 → 4.32.7

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

@@ -16,118 +16,124 @@ module OpenHAB
     # Creates and manages OpenHAB Rules
     #
     module Rules
-      include OpenHAB::Core::ThreadLocal
-      include OpenHAB::Log
+      #
+      # The main rule DSL method
+      #
+      module Rule
+        include OpenHAB::Log
 
-      @script_rules = []
+        @script_rules = []
 
-      @automation_manager = OpenHAB::Core.automation_manager
-      @registry = OpenHAB::Core.rule_registry
-      class << self
-        attr_reader :script_rules, :automation_manager, :registry
-      end
+        @automation_manager = OpenHAB::Core.automation_manager
+        @registry = OpenHAB::Core.rule_registry
+        class << self
+          attr_reader :script_rules, :automation_manager, :registry
+        end
 
-      #
-      # Create a new rule
-      #
-      # @param [String] rule_name <description>
-      # @yield [] Block executed in context of a RuleConfig
-      #
-      #
-      # rubocop: disable Metrics/MethodLength
-      def rule(rule_name, &block)
-        thread_local(RULE_NAME: rule_name) do
-          @rule_name = rule_name
-          config = RuleConfig.new(rule_name, block.binding)
-          config.instance_exec(config, &block)
-          config.guard = Guard::Guard.new(run_context: config.caller, only_if: config.only_if, not_if: config.not_if)
-          logger.trace { config.inspect }
-          process_rule_config(config)
-          nil # Must return something other than the rule object. See https://github.com/boc-tothefuture/openhab-jruby/issues/438
+        module_function
+
+        #
+        # Create a new rule
+        #
+        # @param [String] rule_name <description>
+        # @yield [] Block executed in context of a RuleConfig
+        #
+        #
+        # rubocop:disable Metrics/MethodLength
+        def rule(rule_name, &block)
+          OpenHAB::Core::ThreadLocal.thread_local(RULE_NAME: rule_name) do
+            @rule_name = rule_name
+            config = RuleConfig.new(rule_name, block.binding)
+            config.instance_exec(config, &block)
+            config.guard = Guard::Guard.new(run_context: config.caller, only_if: config.only_if,
+                                            not_if: config.not_if)
+            logger.trace { config.inspect }
+            process_rule_config(config)
+          end
+        rescue StandardError => e
+          logger.log_exception(e, @rule_name)
         end
-      rescue StandardError => e
-        logger.log_exception(e, @rule_name)
-      end
-      # rubocop: enable Metrics/MethodLength
+        # rubocop:enable Metrics/MethodLength
 
-      #
-      # Cleanup rules in this script file
-      #
-      def self.cleanup_rules
-        @script_rules.each(&:cleanup)
-      end
-      Core::ScriptHandling.script_unloaded { cleanup_rules }
+        #
+        # Cleanup rules in this script file
+        #
+        def self.cleanup_rules
+          @script_rules.each(&:cleanup)
+        end
+        Core::ScriptHandling.script_unloaded { cleanup_rules }
 
-      private
+        private
 
-      #
-      # Process a rule based on the supplied configuration
-      #
-      # @param [RuleConfig] config for rule
-      #
-      #
-      def process_rule_config(config)
-        return unless create_rule?(config)
+        #
+        # Process a rule based on the supplied configuration
+        #
+        # @param [RuleConfig] config for rule
+        #
+        #
+        def process_rule_config(config)
+          return unless create_rule?(config)
 
-        rule = AutomationRule.new(config: config)
-        Rules.script_rules << rule
-        add_rule(rule)
+          rule = AutomationRule.new(config: config)
+          Rule.script_rules << rule
+          added_rule = add_rule(rule)
 
-        rule.execute(nil, { 'event' => Struct.new(:attachment).new(config.start_attachment) }) if config.on_start?
-        rule
-      end
+          rule.execute(nil, { 'event' => Struct.new(:attachment).new(config.start_attachment) }) if config.on_start?
+          added_rule
+        end
 
-      #
-      # Should a rule be created based on rule configuration
-      #
-      # @param [RuleConfig] config to check
-      #
-      # @return [Boolean] true if it should be created, false otherwise
-      #
-      def create_rule?(config)
-        if !triggers?(config)
-          logger.warn "Rule '#{config.name}' has no triggers, not creating rule"
-        elsif !execution_blocks?(config)
-          logger.warn "Rule '#{config.name}' has no execution blocks, not creating rule"
-        elsif !config.enabled
-          logger.trace "Rule '#{config.name}' marked as disabled, not creating rule."
-        else
-          return true
+        #
+        # Should a rule be created based on rule configuration
+        #
+        # @param [RuleConfig] config to check
+        #
+        # @return [Boolean] true if it should be created, false otherwise
+        #
+        def create_rule?(config)
+          if !triggers?(config)
+            logger.warn "Rule '#{config.name}' has no triggers, not creating rule"
+          elsif !execution_blocks?(config)
+            logger.warn "Rule '#{config.name}' has no execution blocks, not creating rule"
+          elsif !config.enabled
+            logger.trace "Rule '#{config.name}' marked as disabled, not creating rule."
+          else
+            return true
+          end
+          false
         end
-        false
-      end
 
-      #
-      # Check if the rule has any triggers
-      #
-      # @param [RuleConfig] config to check for triggers
-      #
-      # @return [Boolean] True if rule has triggers, false otherwise
-      #
-      def triggers?(config)
-        config.on_start? || config.triggers.length.positive?
-      end
+        #
+        # Check if the rule has any triggers
+        #
+        # @param [RuleConfig] config to check for triggers
+        #
+        # @return [Boolean] True if rule has triggers, false otherwise
+        #
+        def triggers?(config)
+          config.on_start? || config.triggers.length.positive?
+        end
 
-      #
-      # Check if the rule has any execution blocks
-      #
-      # @param [RuleConfig] config to check for triggers
-      #
-      # @return [Boolean] True if rule has execution blocks, false otherwise
-      #
-      def execution_blocks?(config)
-        (config.run || []).length.positive?
-      end
+        #
+        # Check if the rule has any execution blocks
+        #
+        # @param [RuleConfig] config to check for triggers
+        #
+        # @return [Boolean] True if rule has execution blocks, false otherwise
+        #
+        def execution_blocks?(config)
+          (config.run || []).length.positive?
+        end
 
-      #
-      # Add a rule to the automation managed
-      #
-      # @param [Java::OrgOpenhabCoreAutomationModuleScriptRulesupportSharedSimple::SimpleRule] rule to add
-      #
-      #
-      def add_rule(rule)
-        logger.trace("Adding rule: #{rule.inspect}")
-        Rules.automation_manager.addRule(rule)
+        #
+        # Add a rule to the automation managed
+        #
+        # @param [Java::OrgOpenhabCoreAutomationModuleScriptRulesupportSharedSimple::SimpleRule] rule to add
+        #
+        #
+        def add_rule(rule)
+          logger.trace("Adding rule: #{rule.inspect}")
+          Rule.automation_manager.addRule(rule)
+        end
       end
     end
   end

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

@@ -26,7 +26,6 @@ module OpenHAB
         prepend OpenHAB::DSL::Rules::Triggers
         include OpenHAB::DSL::Rules::Guard
         include OpenHAB::DSL::Rules::Property
-        extend OpenHAB::DSL
         extend Forwardable
 
         # Provide backwards compatibility for these fields
@@ -86,7 +85,7 @@ module OpenHAB
         # Start this rule on system startup
         #
         # @param [Boolean] run_on_start Run this rule on start, defaults to True
-        #
+        # @param [Object] attach object to be attached to the trigger
         #
         # rubocop: disable Style/OptionalBooleanParameter
         # Disabled cop due to use in a DSL

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

@@ -33,9 +33,6 @@ module OpenHAB
         #
         # Create a new RuleTrigger
         #
-        # @param [Object] caller_binding The object initializing this configuration.
-        #   Used to execute within the object's context
-        #
         def initialize
           @triggers = []
           @trigger_conditions = Hash.new(OpenHAB::DSL::Rules::Triggers::Conditions::Proc::ANY)
@@ -47,6 +44,7 @@ module OpenHAB
         #
         # @param [String] type of trigger to create
         # @param [Map] config map describing trigger configuration
+        # @param [Object] attach object to be attached to the trigger
         #
         # @return [Trigger] OpenHAB trigger
         #

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

@@ -4,7 +4,7 @@ module OpenHAB
   module DSL
     module Rules
       # Module containing terse rule stubs
-      module Terse
+      module TerseRule
         %i[changed channel cron every updated received_command].each do |trigger|
           class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
             def #{trigger}(*args, name: nil, **kwargs, &block)                   # def changed(*args, name: nil, **kwargs, &block)

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

@@ -22,6 +22,7 @@ module OpenHAB
         # @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
         #
@@ -69,7 +70,7 @@ module OpenHAB
           # @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 attach attachment
+          # @param [Object] attach object to be attached to the trigger
           #
           # @return [Trigger] OpenHAB triggers
           #
@@ -103,7 +104,7 @@ module OpenHAB
           # @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 [Object] attach to trigger
+          # @param [Object] attach object to be attached to the trigger
           #
           # @return [Trigger] OpenHAB trigger
           #
@@ -120,7 +121,7 @@ module OpenHAB
           # @param [Object] item to create changed trigger on
           # @param [Object] from state to restrict trigger to
           # @param [Object] to state restrict trigger to
-          # @param [Object] attach to trigger
+          # @param [Object] attach object to be attached to the trigger
           # @return [Trigger] OpenHAB trigger
           #
           def range_trigger(item:, from:, to:, attach:)
@@ -133,7 +134,7 @@ module OpenHAB
           # @param [Object] item to create changed trigger on
           # @param [Object] from state to restrict trigger to
           # @param [Object] to state restrict trigger to
-          # @param [Object] attach to trigger
+          # @param [Object] attach object to be attached to the trigger
           # @return [Trigger] OpenHAB trigger
           #
           def proc_trigger(item:, from:, to:, attach:)
@@ -152,7 +153,7 @@ module OpenHAB
           # @param [Object] item to create changed trigger on
           # @param [Object] from state to restrict trigger to
           # @param [Object] to state restrict trigger to
-          #
+          # @param [Object] attach object to be attached to the trigger
           #
           def changed_trigger(item:, from:, to:, attach: nil, conditions: nil)
             type, config = case item

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

@@ -22,6 +22,7 @@ module OpenHAB
         # @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)
@@ -68,6 +69,7 @@ module OpenHAB
           #
           # @param [String] channel to look for triggers
           # @param [String] trigger specific channel trigger to match
+          # @param [Object] attach object to be attached to the trigger
           #
           #
           def trigger(channel:, trigger:, attach:)

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

@@ -20,6 +20,7 @@ module OpenHAB
         # @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)
@@ -63,7 +64,7 @@ module OpenHAB
           #
           # @param [Object] item item to create trigger for
           # @param [Object] command to check against
-          # @param [Object] attach attachment
+          # @param [Object] attach object to be attached to the trigger
           #
           # @return [Trigger] OpenHAB triggers
           #
@@ -79,7 +80,7 @@ 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 [Object] attach to trigger
+          # @param [Object] attach object to be attached to the trigger
           # @return [Trigger] OpenHAB trigger
           #
           def range_trigger(item:, command:, attach:)
@@ -91,7 +92,7 @@ module OpenHAB
           # Creates a trigger with a proc condition on the 'command' field
           # @param [Object] item to create changed trigger on
           # @param [Object] command to restrict trigger to
-          # @param [Object] attach to trigger
+          # @param [Object] attach object to be attached to the trigger
           # @return [Trigger] OpenHAB trigger
           #
           def proc_trigger(item:, command:, attach:)
@@ -102,9 +103,9 @@ module OpenHAB
           #
           # Create a received trigger based on item type
           #
-          # @param [Array] commands to create trigger for
           # @param [Object] item to create trigger for
-          #
+          # @param [String] command to create trigger for
+          # @param [Object] attach object to be attached to the trigger
           #
           def command_trigger(item:, command:, attach: nil, conditions: nil)
             type, config = if item.is_a? OpenHAB::DSL::Items::GroupItem::GroupMembers

data/lib/openhab/dsl/rules/triggers/conditions/duration.rb

@@ -28,7 +28,7 @@ module OpenHAB
             # Create a new duration condition
             # @param [Object] to optional condition on to state
             # @param [Object] from optional condition on from state
-            # @param [Duration] Duration to state must stay at specific value before triggering
+            # @param [Duration] duration to state must stay at specific value before triggering
             #
             def initialize(to:, from:, duration:)
               to = Conditions::Proc.from_value(to)
@@ -118,7 +118,7 @@ module OpenHAB
             # Creates a timer for trigger delays
             #
             # @param [Hash] inputs rule trigger inputs
-            # @param [Hash] mod rule trigger mods
+            # @param [Hash] _mod rule trigger mods
             #
             #
             def create_trigger_delay_timer(inputs, _mod)

data/lib/openhab/dsl/rules/triggers/conditions/proc.rb

@@ -45,8 +45,8 @@ module OpenHAB
             end
 
             #
-            # Create a range proc for the supplied range object
-            # @param [Range] range to build proc for
+            # Create an equality proc for the supplied range object
+            # @param [State] value to build proc for
             #
             def self.equality_proc(value)
               logger.trace("Creating equality proc for #{value}")

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

@@ -15,6 +15,7 @@ module OpenHAB
         #
         # @param [Object] value Symbol or Duration to execute this rule
         # @param [Object] at TimeOfDay or String representing TimeOfDay in which to execute rule
+        # @param [Object] attach object to be attached to the trigger
         #
         #
         def every(value, at: nil, attach: nil)
@@ -30,6 +31,7 @@ module OpenHAB
         # Create a OpenHAB Cron trigger
         #
         # @param [String] expression OpenHAB style cron expression
+        # @param [Object] attach object to be attached to the trigger
         #
         def cron(expression, attach: nil)
           cron = Cron.new(rule_triggers: @rule_triggers)
@@ -171,8 +173,8 @@ module OpenHAB
           #
           # Create a cron trigger based on item type
           #
-          # @param [Array] commands to create trigger for
-          # @param [Object] item to create trigger for
+          # @param [Config] config Rule configuration
+          # @param [Object] attach object to be attached to the trigger
           #
           #
           def trigger(config:, attach:)

data/lib/openhab/dsl/rules/triggers/cron/cron_handler.rb

@@ -57,7 +57,7 @@ module OpenHAB
             field_accessor :callback
 
             # Creates a new CronTriggerHandler
-            # @param [Trigger] OpenHAB trigger associated with handler
+            # @param [Trigger] trigger OpenHAB trigger associated with handler
             #
             def initialize(trigger)
               @trigger = trigger
@@ -113,7 +113,7 @@ module OpenHAB
             include org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory
 
             # Invoked by the OpenHAB core to get a trigger handler for the supllied trigger
-            # @param [Trigger] OpenHAB trigger
+            # @param [Trigger] trigger OpenHAB trigger
             #
             # @return [WatchTriggerHandler] trigger handler for supplied trigger
             def get(trigger)

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

@@ -15,8 +15,9 @@ module OpenHAB
         #
         # Create a generic trigger given the trigger type uid and a configuration hash
         #
-        # @param [Type] Trigger type UID
-        # @param [Configuration] A hash containing the trigger configuration entries
+        # @param [Type] type Trigger type UID
+        # @param [Object] attach object to be attached to the trigger
+        # @param [Configuration] configuration A hash containing the trigger configuration entries
         #
         # @return [Trigger] Trigger object
         #

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

@@ -38,7 +38,7 @@ module OpenHAB
 
           #
           # Creates a new Trigger
-          # @param [RuleTrigger] rule trigger information
+          # @param [RuleTrigger] rule_triggers rule trigger information
           def initialize(rule_triggers:)
             @rule_triggers = rule_triggers
           end
@@ -47,7 +47,7 @@ module OpenHAB
           # Create a trigger for a thing
           #
           # @param [Thing] thing to create trigger for
-          # @param [Trigger] trigger to map with thing
+          # @param [Trigger] type trigger to map with thing
           # @param [State] to for thing
           # @param [State] from state of thing
           #

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

@@ -17,6 +17,7 @@ module OpenHAB
         #
         # @param [Array] items array to trigger on updated
         # @param [State] to to match for tigger
+        # @param [Object] attach object to be attached to the trigger
         #
         # @return [Trigger] Trigger for updated entity
         #
@@ -40,9 +41,8 @@ module OpenHAB
           # 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 attach attachment
+          # @param [Object] attach object to be attached to the trigger
           #
           # @return [Trigger] OpenHAB triggers
           #
@@ -69,7 +69,7 @@ module OpenHAB
           # Creates a trigger with a range condition on the 'to' field
           # @param [Object] item to create changed trigger on
           # @param [Object] to state restrict trigger to
-          # @param [Object] attach to trigger
+          # @param [Object] attach object to be attached to the trigger
           # @return [Trigger] OpenHAB trigger
           #
           def range_trigger(item:, to:, attach:)
@@ -81,7 +81,7 @@ module OpenHAB
           # Creates a trigger with a proc condition on the 'to' field
           # @param [Object] item to create changed trigger on
           # @param [Object] to state restrict trigger to
-          # @param [Object] attach to trigger
+          # @param [Object] attach object to be attached to the trigger
           # @return [Trigger] OpenHAB trigger
           #
           def proc_trigger(item:, to:, attach:)
@@ -93,7 +93,8 @@ module OpenHAB
           # Create a trigger for updates
           #
           # @param [Object] item Type of item [Group,Thing,Item] to create update trigger for
-          # @param [State] to_state state restriction on trigger
+          # @param [State] to state restriction on trigger
+          # @param [Object] attach object to be attached to the trigger
           #
           # @return [Trigger] OpenHAB triggers
           #
@@ -110,7 +111,7 @@ module OpenHAB
           # Create an update trigger for an item
           #
           # @param [Item] item to create trigger for
-          # @param [State] to_state optional state restriction for target
+          # @param [State] to optional state restriction for target
           #
           # @return [Array<Hash,String>] first element is a String specifying trigger type
           #  second element is a Hash configuring trigger
@@ -125,7 +126,7 @@ module OpenHAB
           # Create an update trigger for a group
           #
           # @param [Item] item to create trigger for
-          # @param [State] to_state optional state restriction for target
+          # @param [State] to optional state restriction for target
           #
           # @return [Array<Hash,String>] first element is a String specifying trigger type
           #  second element is a Hash configuring trigger
@@ -140,7 +141,7 @@ module OpenHAB
           # Create an update trigger for a thing
           #
           # @param [Thing] thing to create trigger for
-          # @param [State] to_state optional state restriction for target
+          # @param [State] to optional state restriction for target
           #
           # @return [Array<Hash,String>] first element is a String specifying trigger type
           #  second element is a Hash configuring trigger

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

@@ -18,6 +18,9 @@ module OpenHAB
         # Create a trigger to watch a path
         #
         # @param [String] path to watch
+        # @param [String] glob
+        # @param [Array, Symbol] for types of changes to watch: +:created+, +:deleted+, +:modified+
+        # @param [Object] attach object to be attached to the trigger
         #
         # @return [Trigger] Trigger object
         #
@@ -40,10 +43,12 @@ module OpenHAB
 
           #
           # Automatically creates globs for supplied paths if necessary
+          #
           # @param [Pathname] path to check
-          # @param [String] specified glob
+          # @param [String] glob
           #
           # @return [Pathname,String] Pathname to watch and glob to match
+          #
           def self.glob_for_path(path, glob)
             # Checks if the supplied pathname last element contains a glob char
             if GLOB_CHARS.any? { |char| path.basename.to_s.include? char }
@@ -60,8 +65,8 @@ module OpenHAB
           #
           # Create a watch trigger based on item type
           #
-          # @param [Array] commands to create trigger for
-          # @param [Object] item to create trigger for
+          # @param [Config] config Rule configuration
+          # @param [Object] attach object to be attached to the trigger
           #
           #
           def trigger(config:, attach:)

data/lib/openhab/dsl/rules/triggers/watch/watch_handler.rb

@@ -79,7 +79,7 @@ module OpenHAB
             # Invoked by java super class when an watch event occurs
             # @param [String] _event ignored
             # @param [StandardWatchEventKind] kind NIO watch event kind
-            # @param [java.nio.Path] Path that had an event
+            # @param [java.nio.Path] path that had an event
             def processWatchEvent(_event, kind, path)
               @block.call(WatchEvent.new(EVENT_TO_SYMBOL[kind], Pathname.new(path.to_s)))
             end
@@ -92,7 +92,7 @@ module OpenHAB
             include org.openhab.core.automation.handler.TriggerHandler
 
             # Creates a new WatchTriggerHandler
-            # @param [Trigger] OpenHAB trigger associated with handler
+            # @param [Trigger] trigger OpenHAB trigger associated with handler
             #
             def initialize(trigger)
               @trigger = trigger
@@ -139,7 +139,7 @@ module OpenHAB
             include org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory
 
             # Invoked by the OpenHAB core to get a trigger handler for the supllied trigger
-            # @param [Trigger] OpenHAB trigger
+            # @param [Trigger] trigger OpenHAB trigger
             #
             # @return [WatchTriggerHandler] trigger handler for supplied trigger
             def get(trigger)