openhab-scripting 2.16.2 → 2.16.3

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'openhab/dsl/rules/property'
+require 'openhab/log/logger'
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Guards for rules
+      #
+      module Guard
+        include OpenHAB::DSL::Rules::Property
+
+        prop_array(:only_if) do |item|
+          unless item.is_a?(Proc) || item.respond_to?(:truthy?)
+            raise ArgumentError, "Object passed to only_if must respond_to 'truthy?'"
+          end
+        end
+
+        prop_array(:not_if) do |item|
+          unless item.is_a?(Proc) || item.respond_to?(:truthy?)
+            raise ArgumentError, "Object passed to not_if must respond_to 'truthy?'"
+          end
+        end
+
+        #
+        # Guard that can prevent execute of a rule if not satisfied
+        #
+        class Guard
+          include OpenHAB::Log
+
+          #
+          # Create a new Guard
+          #
+          # @param [Object] only_if Item or Proc to use as guard
+          # @param [Object] not_if Item or Proc to use as guard
+          #
+          def initialize(only_if: nil, not_if: nil)
+            @only_if = only_if
+            @not_if = not_if
+          end
+
+          #
+          # Convert the guard into a string
+          #
+          # @return [String] describing the only_of and not_if guards
+          #
+          def to_s
+            "only_if: #{@only_if}, not_if: #{@not_if}"
+          end
+
+          #
+          # Checks if a guard should run
+          #
+          # @param [OpenHAB Trigger Event] event OpenHAB Trigger Event
+          #
+          # @return [Boolean] True if guard is satisfied, false otherwise
+          #
+          def should_run?(event)
+            logger.trace("Checking guards #{self}")
+            check(@only_if, check_type: :only_if, event: event) && check(@not_if, check_type: :not_if, event: event)
+          end
+
+          private
+
+          #
+          # Check if guard is satisfied
+          #
+          # @param [Array] conditions to check
+          # @param [Symbol] check_type type of check to perform (:only_if or :not_if)
+          # @param [Event] event OpenHAB event to see if it satisfies the guard
+          #
+          # @return [Boolean] True if guard is satisfied, false otherwise
+          #
+          def check(conditions, check_type:, event:)
+            return true if conditions.nil? || conditions.empty?
+
+            procs, items = conditions.flatten.partition { |condition| condition.is_a? Proc }
+            logger.trace("Procs: #{procs} Items: #{items}")
+
+            items.each { |item| logger.trace("#{item} truthy? #{item.truthy?}") }
+
+            process_check(check_type: check_type, event: event, items: items, procs: procs)
+          end
+
+          #
+          # Execute the guard check
+          #
+          # @param [Symbol] check_type :only_if or :not_if to check
+          # @param [OpenHAB Event] event event to check if meets guard
+          # @param [Array<Item>] items to check if satisfy criteria
+          # @param [Array] procs to check if satisfy criteria
+          #
+          # @return [Boolean] True if criteria are satisfied, false otherwise
+          #
+          def process_check(check_type:, event:, items:, procs:)
+            case check_type
+            when :only_if then process_only_if(event, items, procs)
+            when :not_if then  process_not_if(event, items, procs)
+            else raise ArgumentError, "Unexpected check type: #{check_type}"
+            end
+          end
+
+          #
+          # Check not_if guard
+          #
+          # @param [OpenHAB Event] event event to check if meets guard
+          # @param [Array<Item>] items to check if satisfy criteria
+          # @param [Array] procs to check if satisfy criteria
+          #
+          # @return [Boolean] True if criteria are satisfied, false otherwise
+          #
+          def process_not_if(event, items, procs)
+            items.none?(&:truthy?) && procs.none? { |proc| proc.call(event) }
+          end
+
+          #
+          # Check only_if guard
+          #
+          # @param [OpenHAB Event] event event to check if meets guard
+          # @param [Array<Item>] items to check if satisfy criteria
+          # @param [Array] procs to check if satisfy criteria
+          #
+          # @return [Boolean] True if criteria are satisfied, false otherwise
+          #
+          def process_only_if(event, items, procs)
+            items.all?(&:truthy?) && procs.all? { |proc| proc.call(event) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'openhab/log/logger'
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Provides methods to support DSL properties
+      #
+      module Property
+        include OpenHAB::Log
+
+        #
+        # Extend the calling object with the property methods
+        #
+        # @param [Object] base object to extend
+        #
+        #
+        def self.included(base)
+          base.extend PropertyMethods
+        end
+
+        #
+        # Methods that support creating properties in the DSL
+        #
+        module PropertyMethods
+          #
+          # Dynamically creates a property that acts and an accessor with no arguments
+          # and a setter with any number of arguments or a block.
+          #
+          # @param [String] name of the property
+          #
+          #
+          # rubocop:disable Metrics/MethodLength
+          # rubocop:disable Metrics/AbcSize
+          # rubocop:disable Metrics/CyclomaticComplexity
+          # rubocop:disable Metrics/PerceivedComplexity
+          def prop(name)
+            # rubocop rules are disabled because this method is dynamically defined on the calling
+            #   object making calls to other methods in this module impossible, or if done on methods
+            #   in this module than instance variable belong to the module not the calling class
+            define_method(name) do |*args, &block|
+              if args.length.zero? && block.nil? == true
+                instance_variable_get("@#{name}")
+              else
+                logger.trace("Property '#{name}' called with args(#{args}) and block(#{block})")
+                if args.length == 1
+                  instance_variable_set("@#{name}", args.first)
+                elsif args.length > 1
+                  instance_variable_set("@#{name}", args)
+                elsif block
+                  instance_variable_set("@#{name}", block)
+                end
+              end
+            end
+          end
+
+          #
+          # Dynamically creates a property array acts and an accessor with no arguments
+          # and a pushes any number of arguments or a block onto they property array
+          # You can provide a block to this method which can be used to check if the provided value is acceptable.
+          #
+          # @param [String] name of the property
+          # @param [String] array_name name of the array to use, defaults to name of property
+          # @param [Class] wrapper object to put around elements added to the array
+          #
+          def prop_array(name, array_name: nil, wrapper: nil)
+            define_method(name) do |*args, &block|
+              array_name ||= name
+              if args.length.zero? && block.nil? == true
+                instance_variable_get("@#{array_name}")
+              else
+                logger.trace("Property '#{name}' called with args(#{args}) and block(#{block})")
+                if args.length == 1
+                  insert = args.first
+                elsif args.length > 1
+                  insert = args
+                elsif block
+                  insert = block
+                end
+                yield insert if block_given?
+                insert = wrapper.new(insert) if wrapper
+                instance_variable_set("@#{array_name}", (instance_variable_get("@#{array_name}") || []) << insert)
+              end
+            end
+
+            return unless array_name
+
+            define_method(array_name) do
+              instance_variable_get("@#{array_name}")
+            end
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/CyclomaticComplexity
+        # rubocop:enable Metrics/PerceivedComplexity
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'openhab/dsl/rules/rule_config'
+require 'openhab/dsl/rules/automation_rule'
+require 'openhab/dsl/rules/guard'
+
+module OpenHAB
+  #
+  # Contains code to create an OpenHAB DSL
+  #
+  module DSL
+    #
+    # Creates and manages OpenHAB Rules
+    #
+    module Rules
+      #
+      # Create a new rule
+      #
+      # @param [String] rule_name <description>
+      # @yield [] Block executed in context of a RuleConfig
+      #
+      #
+      def rule(rule_name, &block)
+        @rule_name = rule_name
+        config = RuleConfig.new(rule_name, block.binding)
+        config.instance_eval(&block)
+        config.guard = Guard::Guard.new(only_if: config.only_if, not_if: config.not_if)
+        logger.trace { config.inspect }
+        process_rule_config(config)
+      end
+
+      #
+      # Create a logger where name includes rule name if name is set
+      #
+      # @return [Log::Logger] Logger with name that appended with rule name if rule name is set
+      #
+      def logger
+        if @rule_name
+          Log.logger(@rule_name.chomp.gsub(/\s+/, '_'))
+        else
+          super
+        end
+      end
+
+      private
+
+      #
+      # 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)
+        add_rule(rule)
+        rule.execute if config.on_start?
+      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.debug "Rule '#{config.name}' marked as disabled, not creating rule."
+        else
+          return true
+        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 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)
+        # rubocop: disable Style/GlobalVars
+        $scriptExtension.get('automationManager').addRule(rule)
+        # rubocop: enable Style/GlobalVars
+      end
+    end
+  end
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'pp'
+require 'openhab/dsl/rules/property'
+require 'openhab/dsl/rules/triggers/cron'
+require 'openhab/dsl/rules/triggers/changed'
+require 'openhab/dsl/rules/triggers/channel'
+require 'openhab/dsl/rules/triggers/command'
+require 'openhab/dsl/rules/triggers/updated'
+require 'openhab/dsl/rules/guard'
+require 'openhab/core/entity_lookup'
+require 'openhab/dsl/time_of_day'
+require 'openhab/dsl/dsl'
+require 'openhab/dsl/timers'
+
+module OpenHAB
+  module DSL
+    #
+    # Creates and manages OpenHAB Rules
+    #
+    module Rules
+      #
+      # Rule configuration for OpenHAB Rules engine
+      #
+      class RuleConfig
+        include OpenHAB::Log
+        include OpenHAB::Core::EntityLookup
+        include OpenHAB::DSL::Rules::Triggers
+        include OpenHAB::DSL::Rules::Guard
+        include OpenHAB::DSL::Rules::Property
+        extend OpenHAB::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 [Log::Logger] Logger with name that appended with rule name if rule name is set
+        #
+        def logger
+          if name
+            Log.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