openhab-jrubyscripting 5.0.0.rc1

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "property"
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Guard that can prevent execution of a rule if not satisfied
+      #
+      # @!visibility private
+      class Guard
+        #
+        # 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(run_context:, only_if: nil, not_if: nil)
+          @run_context = run_context
+          @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 [true,false] 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 [true,false] 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 [true,false] 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 to check if meets guard
+        # @param [Array<Item>] items to check if satisfy criteria
+        # @param [Array] procs to check if satisfy criteria
+        #
+        # @return [true,false] True if criteria are satisfied, false otherwise
+        #
+        def process_not_if(event, items, procs)
+          items.flatten.none?(&:truthy?) && procs.none? { |proc| @run_context.instance_exec(event, &proc) }
+        end
+
+        #
+        # Check only_if guard
+        #
+        # @param [OpenHAB 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 [true,false] True if criteria are satisfied, false otherwise
+        #
+        def process_only_if(event, items, procs)
+          items.flatten.all?(&:truthy?) && procs.all? { |proc| @run_context.instance_exec(event, &proc) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "triggers/cron/cron"
+
+module OpenHAB
+  module DSL
+    module Rules
+      # Contains helper methods for inferring a rule name from its triggers
+      # @!visibility private
+      module NameInference
+        # Trigger Type UIDs that we know how to generate a name for
+        KNOWN_TRIGGER_TYPES = [
+          "core.ChannelEventTrigger",
+          "core.GenericEventTrigger",
+          "core.GroupCommandTrigger",
+          "core.GroupStateChangeTrigger",
+          "core.GroupStateUpdateTrigger",
+          "core.ItemCommandTrigger",
+          "core.ItemStateChangeTrigger",
+          "core.ItemStateUpdateTrigger",
+          Triggers::Cron::CRON_TRIGGER_MODULE_ID
+        ].freeze
+        private_constant :KNOWN_TRIGGER_TYPES
+
+        class << self
+          # takes a freeform rule name and makes it more palatable as an id
+          def infer_rule_id_from_name(name)
+            name.downcase.delete("'\"").gsub(/\W+/, "_")
+          end
+
+          # get the block's source location, and simplify to a simple filename
+          def infer_rule_id_from_block(block)
+            file = File.basename(block.source_location.first)
+            "#{file}:#{block.source_location.last}"
+          end
+
+          # formulate a readable rule name such as "TestSwitch received command ON" if possible
+          def infer_rule_name(config)
+            known_triggers, unknown_triggers = config.triggers.partition do |t|
+              KNOWN_TRIGGER_TYPES.include?(t.type_uid)
+            end
+            return nil unless unknown_triggers.empty?
+
+            cron_triggers = known_triggers.select { |t| t.type_uid == "jsr223.jruby.CronTrigger" }
+            ruby_every_triggers = config.ruby_triggers.select { |t| t.first == :every }
+
+            # makes sure there aren't any true cron triggers cause we can't format them
+            return nil unless cron_triggers.length == ruby_every_triggers.length
+            return nil unless config.ruby_triggers.length == 1
+
+            infer_rule_name_from_trigger(*config.ruby_triggers.first)
+          end
+
+          private
+
+          # formulate a readable rule name from a single trigger if possible
+          def infer_rule_name_from_trigger(trigger, items = nil, kwargs = {})
+            case trigger
+            when :every
+              infer_rule_name_from_every_trigger(items, **kwargs)
+            when :channel
+              infer_rule_name_from_channel_trigger(items, **kwargs)
+            when :changed, :updated, :received_command
+              infer_rule_name_from_item_trigger(trigger, items, kwargs)
+            when :channel_linked, :channel_unlinked
+              infer_rule_name_from_channel_link_trigger(trigger)
+            when :thing_added, :thing_removed, :thing_updated
+              infer_rule_name_from_thing_trigger(trigger)
+            end
+          end
+
+          # formulate a readable rule name from an item-type trigger
+          def infer_rule_name_from_item_trigger(trigger, items, kwargs)
+            kwargs.delete(:command) if kwargs[:command] == [nil]
+            return unless items.length <= 3 &&
+                          (kwargs.keys - %i[from to command duration]).empty?
+            return if kwargs.values_at(:from, :to, :command).compact.any? do |v|
+              next false if v.is_a?(Array) && v.length <= 4 # arbitrary length
+              next false if v.is_a?(Range)
+
+              v.is_a?(Proc) || v.is_a?(Enumerable)
+            end
+
+            trigger_name = trigger.to_s.tr("_", " ")
+            item_names = items.map do |item|
+              if item.is_a?(GroupItem::Members)
+                "#{item.group.name}.members"
+              else
+                item.name
+              end
+            end
+            name = "#{format_beginning_of_sentence_array(item_names)} #{trigger_name}"
+
+            name += " from #{format_inspected_array(kwargs[:from])}" if kwargs[:from]
+            name += " to #{format_inspected_array(kwargs[:to])}" if kwargs[:to]
+            name += " #{format_inspected_array(kwargs[:command])}" if kwargs[:command]
+            name += " for #{kwargs[:duration]}" if kwargs[:duration]
+            name.freeze
+          end
+
+          # formulate a readable rule name from an every-style cron trigger
+          def infer_rule_name_from_every_trigger(value, at:)
+            name = "Every #{value}"
+            name += " at #{at}" if at
+            name
+          end
+
+          # formulate a readable rule name from a channel trigger
+          def infer_rule_name_from_channel_trigger(channels, triggers:)
+            triggers = [] if triggers == [nil]
+            name = "#{format_beginning_of_sentence_array(channels)} triggered"
+            name += " #{format_inspected_array(triggers)}" unless triggers.empty?
+            name
+          end
+
+          # formulate a readable rule name from a channel link trigger
+          def infer_rule_name_from_channel_link_trigger(trigger)
+            trigger == :channel_linked ? "Channel linked to item" : "Channel unlinked from item"
+          end
+
+          # formulate a readable rule name from a thing added/updated/remove trigger
+          def infer_rule_name_from_thing_trigger(trigger)
+            {
+              thing_added: "Thing Added",
+              thing_updated: "Thing updated",
+              thing_removed: "Thing removed"
+            }[trigger]
+          end
+
+          # format an array of words that will be the beginning of a sentence
+          def format_beginning_of_sentence_array(array)
+            result = format_array(array)
+            if array.length > 2
+              result = result.dup
+              result[0] = "A"
+              result.freeze
+            end
+            result
+          end
+
+          # format an array of items that need to be inspected individually
+          def format_inspected_array(array)
+            return array.inspect if array.is_a?(Range)
+
+            array = [array] unless array.is_a?(Array)
+            format_array(array.map(&:inspect))
+          end
+
+          # format an array of words in a friendly way
+          def format_array(array)
+            return array[0] if array.length == 1
+            return "#{array[0]} or #{array[1]}" if array.length == 2
+
+            "any of #{array.join(", ")}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Provides methods to support DSL properties
+      #
+      # @visibility private
+      module Property
+        #
+        # 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
+        #
+        #
+        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
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require "securerandom"
+
+require_relative "triggers/conditions/proc"
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Rule configuration for OpenHAB Rules engine
+      #
+      # @!visibility private
+      class RuleTriggers
+        # @return [Array] Of triggers
+        attr_accessor :triggers
+
+        # @return [Hash] Of trigger conditions
+        attr_reader :trigger_conditions
+
+        # @return [Hash] Hash of trigger UIDs to attachments
+        attr_reader :attachments
+
+        #
+        # Create a new RuleTrigger
+        #
+        def initialize
+          @triggers = []
+          @trigger_conditions = Hash.new(Triggers::Conditions::Proc::ANY)
+          @attachments = {}
+        end
+
+        #
+        # Append a trigger to the list of triggers
+        #
+        # @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
+        #
+        def append_trigger(type:, config:, attach: nil, conditions: nil)
+          config.transform_keys!(&:to_s)
+          RuleTriggers.trigger(type: type, config: config).tap do |trigger|
+            logger.trace("Appending trigger (#{trigger}) attach (#{attach}) conditions(#{conditions})")
+            @triggers << trigger
+            @attachments[trigger.id] = attach if attach
+            @trigger_conditions[trigger.id] = conditions if conditions
+          end
+        end
+
+        #
+        # Create a trigger
+        #
+        # @param [String] type of trigger
+        # @param [Map] config map
+        #
+        # @return [OpenHAB Trigger] configured by type and supplied config
+        #
+        def self.trigger(type:, config:)
+          logger.trace("Creating trigger of type '#{type}' config: #{config}")
+          org.openhab.core.automation.util.TriggerBuilder.create
+             .with_id(uuid)
+             .with_type_uid(type)
+             .with_configuration(org.openhab.core.config.core.Configuration.new(config))
+             .build
+        end
+
+        #
+        # Generate a UUID for triggers
+        #
+        # @return [String] UUID
+        #
+        def self.uuid
+          SecureRandom.uuid
+        end
+
+        #
+        # Inspect the config object
+        #
+        # @return [String] details of the config object
+        #
+        def inspect
+          <<~TEXT.tr("\n", " ")
+            #<RuleTriggers #{triggers.inspect}
+            Conditions: #{trigger_conditions.inspect}
+            UIDs: #{triggers.map(&:id).inspect}
+            Attachments: #{attachments.inspect}>
+          TEXT
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Rules
+      # 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, **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.
+          #   @yield The execution block for the rule.
+          #   @return [void]
+          #   @see Builder#$1
+          def def_terse_rule(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)
+                raise ArgumentError, "Block is required" unless block         #   raise ArgumentError, "Block is required" unless block
+                                                                              #
+                id ||= NameInference.infer_rule_id_from_name(name) if name    #   id ||= NameInference.infer_rule_id_from_name(name) if name
+                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
+                  #{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(:received_command)
+        def_terse_rule(:thing_added)
+        def_terse_rule(:thing_updated)
+        def_terse_rule(:thing_removed)
+        def_terse_rule(:updated)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "conditions/duration"
+require_relative "conditions/proc"
+require_relative "trigger"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Creates changed triggers
+        #
+        class Changed < Trigger
+          #
+          # 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 [Duration, nil] duration ruration to delay trigger until to state is met
+          # @param [Object] attach object to be attached to the trigger
+          #
+          # @return [Trigger] OpenHAB triggers
+          #
+          def trigger(item:, from:, to:, duration:, attach:)
+            if duration
+              wait_trigger(item: item, from: from, to: to, duration: duration, attach: attach)
+            elsif [to, from].grep(Range).any?
+              range_trigger(item: item, from: from, to: to, attach: attach)
+            elsif [to, from].grep(Proc).any?
+              proc_trigger(item: item, from: from, to: to, attach: attach)
+            else
+              changed_trigger(item: item, from: from, to: to, attach: attach)
+            end
+          end
+
+          private
+
+          # @return [String] A thing status Change trigger
+          THING_CHANGE = "core.ThingStatusChangeTrigger"
+
+          # @return [String] An item state change trigger
+          ITEM_STATE_CHANGE = "core.ItemStateChangeTrigger"
+
+          # @return [String] A group state change trigger for items in the group
+          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 [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 object to be attached to the trigger
+          #
+          # @return [Trigger] OpenHAB trigger
+          #
+          def wait_trigger(item:, duration:, to: nil, from: nil, attach: nil)
+            item_name = item.respond_to?(:name) ? item.name : item.to_s
+            logger.trace("Creating Changed Wait Change Trigger for Item(#{item_name}) Duration(#{duration}) "\
+                         "To(#{to}) From(#{from}) Attach(#{attach})")
+            conditions = Conditions::Duration.new(to: to, from: from, duration: duration)
+            changed_trigger(item: item, to: nil, from: nil, attach: attach, conditions: conditions)
+          end
+
+          #
+          # 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 [Object] attach object to be attached to the trigger
+          # @return [Trigger] OpenHAB trigger
+          #
+          def range_trigger(item:, from:, to:, attach:)
+            from, to = Conditions::Proc.range_procs(from, to)
+            proc_trigger(item: item, from: from, to: to, attach: attach)
+          end
+
+          #
+          # 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 [Object] attach object to be attached to the trigger
+          # @return [Trigger] OpenHAB 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)
+            # 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)
+          end
+
+          #
+          # 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 [Object] attach object to be attached to the trigger
+          #
+          def changed_trigger(item:, from:, to:, attach: nil, conditions: nil)
+            type, config = case item
+                           when GroupItem::Members then group(group: item, from: from,
+                                                              to: to)
+                           when Core::Things::Thing then 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
+
+          #
+          # 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 thing(thing:, from:, to:)
+            trigger_for_thing(thing: thing, type: THING_CHANGE, to: to, from: 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 item(item:, from:, to:)
+            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 [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 group(group:, from:, to:)
+            config = { "groupName" => group.group.name }
+            config["state"] = to.to_s if to
+            config["previousState"] = from.to_s if from
+            [GROUP_STATE_CHANGE, config]
+          end
+        end
+      end
+    end
+  end
+end