openhab-jrubyscripting 5.0.0.rc1

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "trigger"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Creates channel triggers
+        #
+        class Channel < Trigger
+          # @return [String] A channel event trigger
+          CHANNEL_EVENT = "core.ChannelEventTrigger"
+
+          #
+          # Get an enumerator over the product of the channels and things and map them to a channel id
+          # @param [Object] channels to iterate over
+          # @param [Object] thing to combine with channels and iterate over
+          # @return [Enumerable] enumerable channel ids to trigger on
+          def self.channels(channels:, 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
+
+          #
+          # Get a channel id from a channel and thing
+          # @param [Object] channel part of channel id, get UID if object is a Channel
+          # @param [Object] thing part of channel id, get UID if object is a Thing
+          #
+          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?(Core::Things::Thing)
+            [thing, channel].compact.join(":")
+          end
+
+          #
+          # Create a trigger for a channel
+          #
+          # @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:)
+            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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "trigger"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Creates command triggers
+        #
+        class Command < Trigger
+          #
+          # Create a received command trigger
+          #
+          # @param [Object] item item to create trigger for
+          # @param [Object] command to check against
+          # @param [Object] attach object to be attached to the trigger
+          #
+          # @return [Trigger] OpenHAB triggers
+          #
+          def trigger(item:, command:, attach:)
+            case command
+            when Range then range_trigger(item: item, command: command, attach: attach)
+            when Proc then proc_trigger(item: item, command: command, attach: attach)
+            else command_trigger(item: item, command: command, attach: attach)
+            end
+          end
+
+          #
+          # 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 object to be attached to the trigger
+          # @return [Trigger] OpenHAB trigger
+          #
+          def range_trigger(item:, command:, attach:)
+            command_range, * = Conditions::Proc.range_procs(command)
+            proc_trigger(item: item, command: command_range, attach: attach)
+          end
+
+          #
+          # 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 object to be attached to the trigger
+          # @return [Trigger] OpenHAB trigger
+          #
+          def proc_trigger(item:, command:, attach:)
+            conditions = Conditions::Proc.new(command: command)
+            command_trigger(item: item, command: nil, attach: attach, conditions: conditions)
+          end
+
+          #
+          # Create a received trigger based on item type
+          #
+          # @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?(GroupItem::Members)
+                             group(group: item)
+                           else
+                             item(item: item)
+                           end
+            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"
+
+          # @return [String] A group command trigger for items in the group
+          GROUP_COMMAND = "core.GroupCommandTrigger"
+
+          #
+          # Create trigger for item commands
+          #
+          # @param [Item] item to create trigger for
+          #
+          # @return [Array<Hash,Trigger>] first element is hash of trigger config properties
+          #   second element is trigger type
+          #
+          def item(item:)
+            [ITEM_COMMAND, { "itemName" => item.name }]
+          end
+
+          #
+          # Create trigger for group items
+          #
+          # @param [Group] group to create trigger for
+          #
+          # @return [Array<Hash,Trigger>] first element is hash of trigger config properties
+          #   second element is trigger type
+          #
+          def group(group:)
+            [GROUP_COMMAND, { "groupName" => group.group.name }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        module Conditions
+          #
+          # this is a no-op condition which simply executes the provided block
+          #
+
+          #
+          # Struct capturing data necessary for a conditional trigger
+          #
+          # TriggerDelay = Struct.new(:to, :from, :duration, :timer, :tracking_to, keyword_init: true) do
+          #  def timer_active?
+          #    timer&.active?
+          #  end
+          # end
+          class Duration
+            #
+            # Create a new duration condition
+            # @param [Object] to optional condition on to state
+            # @param [Object] from optional condition on from state
+            # @param [java.time.temporal.TemporalAmount] duration to state must stay at specific value before triggering
+            #
+            def initialize(to:, from:, duration:)
+              to = Conditions::Proc.from_value(to)
+              from = Conditions::Proc.from_value(from)
+              @conditions = Conditions::Proc.new(to: to, from: from)
+              @duration = duration
+              @timer = nil
+              logger.trace "Created Duration Condition To(#{to}) From(#{from}) "\
+                           "Conditions(#{@conditions}) Duration(#{@duration})"
+            end
+
+            # Process rule
+            # @param [Hash] inputs inputs from trigger
+            #
+            def process(mod:, inputs:, &block)
+              process_trigger_delay(mod, inputs, &block)
+            end
+
+            # Cleanup any resources from the condition
+            #
+            # Cancels the timer, if it's active
+            def cleanup
+              @timer&.cancel
+            end
+
+            private
+
+            #
+            # Checks if there is an active timer
+            # @return [true, false] true if the timer exists and is active, false otherwise
+            def timer_active?
+              @timer&.active?
+            end
+
+            #
+            # Check if trigger guards prevent rule execution
+            #
+            # @param [Map] inputs OpenHAB map object describing rule trigger
+            #
+            # @return [true,false] True if the rule should execute, false if trigger guard prevents execution
+            #
+            def check_trigger_guards(inputs)
+              new_state, old_state = retrieve_states(inputs)
+              @conditions.check_from(state: old_state) && @conditions.check_to(state: new_state)
+            end
+
+            #
+            # Rerieve the newState and oldState, alternatively newStatus and oldStatus
+            # from the input map
+            #
+            # @param [Map] inputs OpenHAB map object describing rule trigger
+            #
+            # @return [Array] An array of the values for [newState, oldState] or [newStatus, oldStatus]
+            #
+            def retrieve_states(inputs)
+              new_state = inputs["newState"] || thing_status_to_sym(inputs["newStatus"])
+              old_state = inputs["oldState"] || thing_status_to_sym(inputs["oldStatus"])
+
+              [new_state, old_state]
+            end
+
+            #
+            # Converts a ThingStatus object to a ruby Symbol
+            #
+            # @param [org.openhab.core.thing.ThingStatus] status A ThingStatus instance
+            #
+            # @return [Symbol] A corresponding symbol, in lower case
+            #
+            def thing_status_to_sym(status)
+              status&.to_s&.downcase&.to_sym
+            end
+
+            #
+            # Process any matching trigger delays
+            #
+            # @param [Map] mod OpenHAB map object describing rule trigger
+            # @param [Map] inputs OpenHAB map object describing rule trigger
+            #
+            #
+            def process_trigger_delay(mod, inputs, &block)
+              if timer_active?
+                process_active_timer(inputs, mod, &block)
+              elsif check_trigger_guards(inputs)
+                logger.trace("Trigger Guards Matched for #{self}, delaying rule execution")
+                # Add timer and attach timer to delay object, and also state being tracked to so
+                # timer can be cancelled if state changes
+                # Also another timer should not be created if changed to same value again but instead rescheduled
+                create_trigger_delay_timer(inputs, mod, &block)
+              else
+                logger.trace("Trigger Guards did not match for #{self}, ignoring trigger.")
+              end
+            end
+
+            #
+            # Creates a timer for trigger delays
+            #
+            # @param [Hash] inputs rule trigger inputs
+            # @param [Hash] _mod rule trigger mods
+            #
+            #
+            def create_trigger_delay_timer(inputs, _mod)
+              logger.trace("Creating timer for trigger delay #{self}")
+              @timer = DSL.after(@duration) do
+                logger.trace("Delay Complete for #{self}, executing rule")
+                @timer = nil
+                yield
+              end
+              @tracking_to, = retrieve_states(inputs)
+            end
+
+            #
+            # Process an active trigger timer
+            #
+            # @param [Hash] inputs rule trigger inputs
+            # @param [Hash] mod rule trigger mods
+            #
+            #
+            def process_active_timer(inputs, mod, &block)
+              state, = retrieve_states(inputs)
+              if state == @tracking_to
+                logger.trace("Item changed to #{state} for #{self}, rescheduling timer.")
+                @timer.reschedule(ZonedDateTime.now.plus(@duration))
+              else
+                logger.trace("Item changed to #{state} for #{self}, canceling timer.")
+                @timer.cancel
+                # Reprocess trigger delay after canceling to track new state (if guards matched, etc)
+                process_trigger_delay(mod, inputs, &block)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        module Conditions
+          #
+          # This creates trigger conditions that work on procs
+          # @param [Proc] from Proc
+          # @param [Proc] to Proc
+          #
+          class Proc
+            #
+            # Converts supplied ranges to procs that check range
+            # @param [Array] ranges objects to convert to range proc if they are ranges
+            # @return [Array] of procs or supplied arguments if argument was not of type Range
+            #
+            def self.range_procs(*ranges)
+              ranges.map { |range| range.is_a?(Range) ? range_proc(range) : range }
+            end
+
+            #
+            # Create a range proc for the supplied range object
+            # @param [Range] range to build proc for
+            #
+            def self.range_proc(range)
+              logger.trace("Creating range proc for #{range}")
+              lambda do |val|
+                logger.trace("Range proc checking if #{val} is in #{range}")
+                range.cover? val
+              end
+            end
+
+            #
+            # 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}")
+              lambda do |state|
+                logger.trace("Equality proc comparing #{value} against #{state}")
+                value == state
+              end
+            end
+
+            #
+            # Constructs a proc for the specific value type
+            #  if the value is a proc return the proc
+            #  if the value is a range create a range proc
+            #  if the value is nil, return nil
+            #  otherwise create an equality proc
+            # @param [Object] value to construct proc from
+            def self.from_value(value)
+              logger.trace("Creating proc for Value(#{value})")
+              return value if value.nil?
+              return value if value.is_a?(::Proc)
+              return range_proc(value) if value.is_a?(Range)
+
+              equality_proc(value)
+            end
+
+            #
+            # Create a new Proc Condition that executes only if procs return true
+            # @param [Proc] from Proc to check against from value
+            # @param [Proc] to Proc to check against to value
+            #
+            def initialize(from: nil, to: nil, command: nil)
+              @from = from
+              @to = to
+              @command = command
+            end
+
+            # Proc that doesn't check any fields
+            ANY = Proc.new.freeze # this needs to be defined _after_ initialize so its instance variables are set
+
+            #
+            # Process rule
+            # @param [Hash] inputs inputs from trigger
+            #
+            def process(mod:, inputs:) # rubocop:disable Lint/UnusedMethodArgument - mod is unused here but required
+              logger.trace("Checking #{inputs} against condition trigger #{self}")
+              yield if check_procs(inputs: inputs)
+            end
+
+            # Cleanup any resources from the condition
+            def cleanup; end
+
+            #
+            # Check if command condition match the proc
+            # @param [Hash] inputs from trigger must be supplied if state is not supplied
+            # @return [true/false] depending on if from is set and matches supplied conditions
+            #
+            def check_command(inputs: nil)
+              command = input_state(inputs, "command")
+              logger.trace "Checking command(#{@command}) against command(#{command})"
+              check_proc(proc: @command, value: command)
+            end
+
+            #
+            # Check if from condition match the proc
+            # @param [Hash] inputs from trigger must be supplied if state is not supplied
+            # @param [String] state if supplied proc will be passed state value for comparision
+            # @return [true/false] depending on if from is set and matches supplied conditions
+            #
+            def check_from(inputs: nil, state: nil)
+              state ||= input_state(inputs, "oldState")
+              logger.trace "Checking from(#{@from}) against state(#{state})"
+              check_proc(proc: @from, value: state)
+            end
+
+            #
+            # Check if to conditions match the proc
+            # @param [Hash] inputs from trigger must be supplied if state is not supplied
+            # @param [String] state if supplied proc will be passed state value for comparision
+            # @return [true/false] depending on if from is set and matches supplied conditions
+            #
+            def check_to(inputs: nil, state: nil)
+              state ||= input_state(inputs, "newState", "state")
+              logger.trace "Checking to(#{@to}) against state(#{state})"
+              check_proc(proc: @to, value: state)
+            end
+
+            # Describe the Proc Condition as a string
+            # @return [String] string representation of proc condition
+            #
+            def to_s
+              "From:(#{@from}) To:(#{@to}) Command:(#{@command})"
+            end
+
+            private
+
+            #
+            # Check all procs
+            # @param [Hash] inputs from event
+            # @return [true/false] true if all procs return true, false otherwise
+            def check_procs(inputs:)
+              check_from(inputs: inputs) && check_to(inputs: inputs) && check_command(inputs: inputs)
+            end
+
+            # Check if a field matches the proc condition
+            # @param [Proc] proc to call
+            # @param [Hash] value to check
+            # @return [true,false] true if proc is nil or proc.call returns true, false otherwise
+            def check_proc(proc:, value:)
+              return true if proc.nil? || proc.call(value)
+
+              logger.trace("Skipped execution of rule because value #{value} evaluated false for (#{proc})")
+              false
+            end
+
+            # Get the first field from supplied fields in inputs
+            # @param [Hash] inputs containing fields
+            # @param [Array] fields array of fields to extract from inputs, first one found is returned
+            def input_state(inputs, *fields)
+              fields.map { |f| inputs[f] }.compact.first
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "openhab/dsl/rules/triggers/trigger"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Creates cron triggers
+        #
+        class Cron < Trigger
+          # Trigger ID for Watch Triggers
+          CRON_TRIGGER_MODULE_ID = "jsr223.jruby.CronTrigger"
+
+          #
+          # Returns a default map for cron expressions that fires every second
+          # This map is usually updated via merge by other methods to refine cron type triggers.
+          #
+          # @return [Hash] Map with symbols for :seconds, :minute, :hour, :dom, :month, :dow
+          #   configured to fire every second
+          #
+          CRON_EXPRESSION_MAP =
+            {
+              second: "*",
+              minute: "*",
+              hour: "*",
+              dom: "?",
+              month: "*",
+              dow: "?",
+              year: "*"
+            }.freeze
+          private_constant :CRON_EXPRESSION_MAP
+
+          # @return [Hash] Map of days of the week from symbols to to OpenHAB cron strings
+          DAY_OF_WEEK_MAP = {
+            monday: "MON",
+            tuesday: "TUE",
+            wednesday: "WED",
+            thursday: "THU",
+            friday: "FRI",
+            saturday: "SAT",
+            sunday: "SUN"
+          }.freeze
+          private_constant :DAY_OF_WEEK_MAP
+
+          # @return [Hash] Converts the DAY_OF_WEEK_MAP to map used by Cron Expression
+          DAY_OF_WEEK_EXPRESSION_MAP = DAY_OF_WEEK_MAP.transform_values { |v| CRON_EXPRESSION_MAP.merge(dow: v) }
+
+          private_constant :DAY_OF_WEEK_EXPRESSION_MAP
+
+          # @return [Hash] Create a set of cron expressions based on different time intervals
+          EXPRESSION_MAP = {
+            second: CRON_EXPRESSION_MAP,
+            minute: CRON_EXPRESSION_MAP.merge(second: "0"),
+            hour: CRON_EXPRESSION_MAP.merge(second: "0", minute: "0"),
+            day: CRON_EXPRESSION_MAP.merge(second: "0", minute: "0", hour: "0"),
+            week: CRON_EXPRESSION_MAP.merge(second: "0", minute: "0", hour: "0", dow: "MON"),
+            month: CRON_EXPRESSION_MAP.merge(second: "0", minute: "0", hour: "0", dom: "1"),
+            year: CRON_EXPRESSION_MAP.merge(second: "0", minute: "0", hour: "0", dom: "1", month: "1")
+          }.merge(DAY_OF_WEEK_EXPRESSION_MAP).freeze
+
+          private_constant :EXPRESSION_MAP
+
+          #
+          # Create a cron map from a duration
+          #
+          # @param [Duration] duration
+          # @param [Object] at LocalTime or String representing time of day
+          #
+          # @return [Hash] map describing cron expression
+          #
+          def self.from_duration(duration, at)
+            raise ArgumentError, '"at" cannot be used with duration' if at
+
+            map_to_cron(duration_to_map(duration))
+          end
+
+          #
+          # Create a cron map from a MonthDay
+          #
+          # @param [MonthDay] monthday a {MonthDay} object
+          # @param [Object] at LocalTime or String representing time of day
+          #
+          # @return [Hash] map describing cron expression
+          #
+          def self.from_monthday(monthday, at)
+            expression_map = EXPRESSION_MAP[:day].merge(month: monthday.month_value, dom: monthday.day_of_month)
+            expression_map = at_condition(expression_map, at) if at
+            map_to_cron(expression_map)
+          end
+
+          #
+          # Create a cron map from a symbol
+          #
+          # @param [Symbol] symbol
+          # @param [Object] at LocalTime or String representing time of day
+          #
+          # @return [Hash] map describing cron expression created from symbol
+          #
+          def self.from_symbol(symbol, at)
+            expression_map = EXPRESSION_MAP[symbol]
+            expression_map = at_condition(expression_map, at) if at
+            map_to_cron(expression_map)
+          end
+
+          #
+          # Create a cron map from cron elements
+          #
+          # @param [Hash] fields Cron fields (second, minute, hour, dom, month, dow, year)
+          #
+          # @return [Hash] map describing cron expression
+          #
+          def self.from_fields(fields)
+            extra_fields = fields.keys - CRON_EXPRESSION_MAP.keys
+            unless extra_fields.empty?
+              raise ArgumentError,
+                    "unknown keyword#{"s" if extra_fields.size > 1}: #{extra_fields.map(&:inspect).join(", ")}"
+            end
+
+            fields = fields.transform_values { |value| value.to_s.delete(" ") }
+            # find the first expression map that has a field from fields.
+            # this ensure more-specific fields get set to 0, not *
+            base_key = EXPRESSION_MAP.keys.find { |field, _| fields.key?(field) }
+            base_expression = EXPRESSION_MAP[base_key]
+            expression_map = base_expression.merge(fields)
+
+            map_to_cron(expression_map)
+          end
+
+          #
+          # Map cron expression to to cron string
+          #
+          # @param [Map] map of cron expression
+          #
+          # @return [String] OpenHAB cron string
+          #
+          def self.map_to_cron(map)
+            %i[second minute hour dom month dow year].map { |field| map.fetch(field) }.join(" ")
+          end
+
+          #
+          # Convert a Java Duration to a map for the map_to_cron method
+          #
+          # @param duration [Duration] The duration object
+          #
+          # @return [Hash] a map suitable for map_to_cron
+          #
+          def self.duration_to_map(duration)
+            if duration.to_millis_part.zero? && duration.to_nanos_part.zero? && duration.to_days.zero?
+              %i[second minute hour].each do |unit|
+                to_unit_part = duration.public_send("to_#{unit}s_part")
+                next unless to_unit_part.positive?
+
+                to_unit = duration.public_send("to_#{unit}s")
+                break unless to_unit_part == to_unit
+
+                return EXPRESSION_MAP[unit].merge(unit => "*/#{to_unit}")
+              end
+            end
+            raise ArgumentError, "Cron Expression not supported for duration: #{duration}"
+          end
+
+          #
+          # If an at time is provided, parse that and merge the new fields into the expression.
+          #
+          # @param [<Type>] expression_map <description>
+          # @param [<Type>] at_time <description>
+          #
+          # @return [<Type>] <description>
+          #
+          def self.at_condition(expression_map, at_time)
+            if at_time
+              tod = at_time.is_a?(LocalTime) ? at_time : LocalTime.parse(at_time)
+              expression_map = expression_map.merge(hour: tod.hour, minute: tod.minute, second: tod.second)
+            end
+            expression_map
+          end
+
+          #
+          # Create a cron trigger based on item type
+          #
+          # @param [Config] config Rule configuration
+          # @param [Object] attach object to be attached to the trigger
+          #
+          #
+          def trigger(config:, attach:)
+            append_trigger(type: CRON_TRIGGER_MODULE_ID, config: config, attach: attach)
+          end
+        end
+      end
+    end
+  end
+end