openhab-scripting 2.13.1 → 2.15.0

data/lib/openhab/core/dsl/rule/{cron.rb → triggers/cron.rb}

@@ -11,7 +11,7 @@ module OpenHAB
         #
         # Cron type rules
         #
-        module Cron
+        module Triggers
           java_import org.openhab.core.automation.util.TriggerBuilder
           java_import org.openhab.core.config.core.Configuration
 
@@ -58,18 +58,12 @@ module OpenHAB
           #
           #
           def every(value, at: nil)
-            case value
-            when Symbol
-              expression_map = EXPRESSION_MAP[value]
-              expression_map = at_condition(expression_map, at) if at
-              cron(map_to_cron(expression_map))
-            when Java::JavaTime::Duration
-              raise ArgumentError, '"at" cannot be used with duration' if at
-
-              cron(map_to_cron(duration_to_map(value)))
-            else
-              raise ArgumentExpression, 'Unknown interval' unless expression_map
-            end
+            cron_expression = case value
+                              when Symbol then cron_from_symbol(value, at)
+                              when Java::JavaTime::Duration then cron_from_duration(value, at)
+                              else raise ArgumentExpression, 'Unknown interval'
+                              end
+            cron(cron_expression)
           end
 
           #
@@ -83,6 +77,34 @@ module OpenHAB
 
           private
 
+          #
+          # Create a cron map from a duration
+          #
+          # @param [java::time::Duration] duration
+          # @param [Object] at TimeOfDay or String representing time of day
+          #
+          # @return [Hash] map describing cron expression
+          #
+          def cron_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 symbol
+          #
+          # @param [Symbol] symbol
+          # @param [Object] at TimeOfDay or String representing time of day
+          #
+          # @return [Hash] map describing cron expression created from symbol
+          #
+          def cron_from_symbol(symbol, at)
+            expression_map = EXPRESSION_MAP[symbol]
+            expression_map = at_condition(expression_map, at) if at
+            map_to_cron(expression_map)
+          end
+
           #
           # Map cron expression to to cron string
           #
@@ -126,7 +148,7 @@ module OpenHAB
           #
           def at_condition(expression_map, at_time)
             if at_time
-              tod = (at_time.is_a? TimeOfDay) ? at_time : TimeOfDay.parse(at_time)
+              tod = at_time.is_a?(TimeOfDay) ? at_time : TimeOfDay.parse(at_time)
               expression_map = expression_map.merge(hour: tod.hour, minute: tod.minute, second: tod.second)
             end
             expression_map

data/lib/openhab/core/dsl/rule/triggers/trigger.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'java'
+
+module OpenHAB
+  module Core
+    module DSL
+      module Rule
+        #
+        # Module holds rule triggers
+        #
+        module Triggers
+          #
+          # Create a trigger for a thing
+          #
+          # @param [Thing] thing to create trigger for
+          # @param [Trigger] trigger to map with thing
+          # @param [State] to for thing
+          # @param [State] from state of thing
+          #
+          # @return [Array] Trigger and config for thing
+          #
+          def trigger_for_thing(thing, trigger, to = nil, from = nil)
+            config = { 'thingUID' => thing.uid.to_s }
+            config['status'] = trigger_state_from_symbol(to).to_s if to
+            config['previousStatus'] = trigger_state_from_symbol(from).to_s if from
+            [trigger, config]
+          end
+
+          #
+          # converts object to upcase string if its a symbol
+          #
+          # @param [sym] sym potential symbol to convert
+          #
+          # @return [String] Upcased symbol as string
+          #
+          def trigger_state_from_symbol(sym)
+            sym.to_s.upcase if (sym.is_a? Symbol) || sym
+          end
+
+          #
+          # Append a trigger to the list of triggeres
+          #
+          # @param [String] type of trigger to create
+          # @param [Map] config map describing trigger configuration
+          #
+          # @return [Trigger] OpenHAB trigger
+          #
+          def append_trigger(type, config)
+            logger.trace("Creating trigger of type #{type} for #{config}")
+            trigger = Trigger.trigger(type: type, config: config)
+            @triggers << trigger
+            trigger
+          end
+
+          #
+          # Class for creating and managing triggers
+          #
+          class Trigger
+            java_import org.openhab.core.automation.util.TriggerBuilder
+            java_import org.openhab.core.config.core.Configuration
+
+            # @return [String] A channel event trigger
+            CHANNEL_EVENT = 'core.ChannelEventTrigger'
+
+            # @return [String] A thing status Change trigger
+            THING_CHANGE = 'core.ThingStatusChangeTrigger'
+
+            # @return [String] A thing status update trigger
+            THING_UPDATE = 'core.ThingStatusUpdateTrigger'
+
+            # @return [String] An item command trigger
+            ITEM_COMMAND = 'core.ItemCommandTrigger'
+
+            # @return [String] An item state update trigger
+            ITEM_STATE_UPDATE = 'core.ItemStateUpdateTrigger'
+
+            # @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'
+
+            # @return [String] A group state update trigger for items in the group
+            GROUP_STATE_UPDATE = 'core.GroupStateUpdateTrigger'
+
+            # @return [String] A group command trigger for items in the group
+            GROUP_COMMAND = 'core.GroupCommandTrigger'
+
+            # @return [String] A time of day trigger
+            TIME_OF_DAY = 'timer.TimeOfDayTrigger'
+
+            # @return [String] A cron trigger
+            CRON = 'timer.GenericCronTrigger'
+
+            #
+            # 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:)
+              TriggerBuilder.create
+                            .with_id(uuid)
+                            .with_type_uid(type)
+                            .with_configuration(Configuration.new(config))
+                            .build
+            end
+
+            #
+            # Generate a UUID for triggers
+            #
+            # @return [String] UUID
+            #
+            def self.uuid
+              SecureRandom.uuid
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/dsl/rule/triggers/updated.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'core/log'
+
+module OpenHAB
+  module Core
+    module DSL
+      module Rule
+        #
+        # Module holds rule triggers
+        #
+        module Triggers
+          include Logging
+
+          #
+          # Create a trigger when item, group or thing is updated
+          #
+          # @param [Array] items array to trigger on updated
+          # @param [State] to to match for tigger
+          #
+          # @return [Trigger] Trigger for updated entity
+          #
+          def updated(*items, to: nil)
+            items.flatten.each do |item|
+              logger.trace("Creating updated trigger for item(#{item}) to(#{to})")
+              [to].flatten.each do |to_state|
+                trigger, config = create_update_trigger(item, to_state)
+                append_trigger(trigger, config)
+              end
+            end
+          end
+
+          private
+
+          #
+          # 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
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def create_update_trigger(item, to_state)
+            case item
+            when GroupItems then group_update(item, to_state)
+            when Thing then thing_update(item, to_state)
+            else item_update(item, to_state)
+            end
+          end
+
+          #
+          # Create an update trigger for an item
+          #
+          # @param [Item] item to create trigger for
+          # @param [State] to_state optional state restriction for target
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def item_update(item, to_state)
+            config = { 'itemName' => item.name }
+            config['state'] = to_state.to_s unless to_state.nil?
+            trigger = Trigger::ITEM_STATE_UPDATE
+            [trigger, config]
+          end
+
+          #
+          # Create an update trigger for a group
+          #
+          # @param [Item] item to create trigger for
+          # @param [State] to_state optional state restriction for target
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def group_update(item, to_state)
+            config = { 'groupName' => item.group.name }
+            config['state'] = to_state.to_s unless to_state.nil?
+            trigger = Trigger::GROUP_STATE_UPDATE
+            [trigger, config]
+          end
+
+          #
+          # Create an update trigger for a thing
+          #
+          # @param [Thing] thing to create trigger for
+          # @param [State] to_state optional state restriction for target
+          #
+          # @return [Array<Hash,String>] first element is a String specifying trigger type
+          #  second element is a Hash configuring trigger
+          #
+          def thing_update(thing, to_state)
+            trigger_for_thing(thing, Trigger::THING_UPDATE, to_state)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/dsl/time_of_day.rb

@@ -50,7 +50,8 @@ module OpenHAB
 
           # Constructs a TimeOfDay representing the time when called
           # @since 0.0.1
-          # @param [String] string representation of TimeOfDay. Valid formats include "HH:MM:SS", "HH:MM", "H:MM", "HH", "H", "H:MM am"
+          # @param [String] string representation of TimeOfDay. Valid formats include "HH:MM:SS", "HH:MM",
+          #   "H:MM", "HH", "H", "H:MM am"
           # @return [TimeOfDay] object created by parsing supplied string
           def self.parse(string)
             format = /(am|pm)$/i.match?(string) ? 'h[:mm[:ss]][ ]a' : 'H[:mm[:ss]]'
@@ -67,10 +68,13 @@ module OpenHAB
           # @option opts [Number] :m Minute of the day, defaults to 0
           # @option opts [Number] :s Second of the day, defaults to 0
           # @return [TimeOfDay] representing time when method was invoked
+          # rubocop: disable Naming/MethodParameterName
+          # This method has a better feel with short parameter names
           def initialize(h: 0, m: 0, s: 0)
             @local_time = LocalTime.of(h, m, s)
             freeze
           end
+          # rubocop: enable Naming/MethodParameterName
 
           # Returns true if the time falls within a range
           def between?(range)
@@ -100,14 +104,16 @@ module OpenHAB
 
           # Returns the string representation of the TimeOfDay
           # @since 0.0.1
-          # @return [String] in any of the following formats depending on time representation HH:mm, HH:mm:ss, HH:mm:ss.SSS, HH:mm:ss.SSSSSS, HH:mm:ss.SSSSSSSSS
+          # @return [String] in any of the following formats depending on time representation HH:mm, HH:mm:ss,
+          #   HH:mm:ss.SSS, HH:mm:ss.SSSSSS, HH:mm:ss.SSSSSSSSS
           def to_s
             @local_time.to_s
           end
 
           # Compares one TimeOfDay to another
           # @since 0.0.1
-          # @return [Number, nil] -1,0,1 if other TimeOfDay is less than, equal to, or greater than this TimeOfDay or nil if an object other than TimeOfDay is provided
+          # @return [Number, nil] -1,0,1 if other TimeOfDay is less than, equal to, or greater than this TimeOfDay
+          #   or nil if an object other than TimeOfDay is provided
           def <=>(other)
             case other
             when TimeOfDay
@@ -143,28 +149,36 @@ module OpenHAB
           # @since 2.4.0
           # @return [Number, nil] -1,0,1 if other is less than, equal to, or greater than this TimeOfDay
           def <=>(other)
-            other_second_of_day = case other
-                                  when TimeOfDay
-                                    adjust_second_of_day(other.local_time.to_second_of_day)
-                                  when String
-                                    adjust_second_of_day(TimeOfDay.parse(other).local_time.to_second_of_day)
-                                  when Time
-                                    adjust_second_of_day(TimeOfDay.new(h: other.hour, m: other.min,
-                                                                       s: other.sec).local_time.to_second_of_day)
-                                  when TimeOfDayRangeElement
-                                    other.sod
-                                  else
-                                    raise ArgumentError, 'Supplied argument cannot be converted into Time Of Day Object'
-                                  end
-
+            other_second_of_day = to_second_of_day(other)
             logger.trace do
-              "SOD(#{sod}) other SOD(#{other_second_of_day}) Other Class (#{other.class}) Result (#{sod <=> other_second_of_day})"
+              "SOD(#{sod}) "\
+              "other SOD(#{other_second_of_day}) "\
+              "Other Class (#{other.class}) "\
+              "Result (#{sod <=> other_second_of_day})"
             end
             sod <=> other_second_of_day
           end
 
           private
 
+          #
+          # Convert object to the seconds of a day they reprsent
+          #
+          # @param [Object] object TimeofDay,String,Time, or TimeOfDayRangeElement to convert
+          #
+          # @return [Integer] seconds of day represented by supplied object
+          #
+          def to_second_of_day(object)
+            case object
+            when TimeOfDay then adjust_second_of_day(object.local_time.to_second_of_day)
+            when String then adjust_second_of_day(TimeOfDay.parse(object).local_time.to_second_of_day)
+            when Time then adjust_second_of_day(TimeOfDay.new(h: object.hour, m: object.min,
+                                                              s: object.sec).local_time.to_second_of_day)
+            when TimeOfDayRangeElement then object.sod
+            else raise ArgumentError, 'Supplied argument cannot be converted into Time Of Day Object'
+            end
+          end
+
           def adjust_second_of_day(second_of_day)
             second_of_day += NUM_SECONDS_IN_DAY if second_of_day < @range_begin
             second_of_day
@@ -175,14 +189,13 @@ module OpenHAB
         # to see if they are within the range
         # @since 2.4.0
         # @return Range object representing a TimeOfDay Range
+        module_function
+
         def between(range)
           raise ArgumentError, 'Supplied object must be a range' unless range.is_a? Range
 
-          start = range.begin
-          ending = range.end
-
-          start = TimeOfDay.parse(start) if start.is_a? String
-          ending = TimeOfDay.parse(ending) if ending.is_a? String
+          start = to_time_of_day(range.begin)
+          ending = to_time_of_day(range.end)
 
           start_sod = start.local_time.to_second_of_day
           ending_sod = ending.local_time.to_second_of_day
@@ -192,7 +205,20 @@ module OpenHAB
           ending_range = TimeOfDayRangeElement.new(sod: ending_sod, range_begin: start_sod)
           range.exclude_end? ? (start_range...ending_range) : (start_range..ending_range)
         end
-        module_function :between
+
+        #
+        # Convert object to TimeOfDay object
+        #
+        # @param [Object] object TimeOfDay or String to be converted
+        #
+        # @return [TimeOfDay] TimeOfDay created from supplied object
+        #
+        private_class_method def to_time_of_day(object)
+          case object
+          when String then TimeOfDay.parse(object)
+          else object
+          end
+        end
 
         MIDNIGHT = TimeOfDay.midnight
         NOON = TimeOfDay.noon

data/lib/openhab/core/dsl/timers.rb

@@ -39,15 +39,11 @@ module OpenHAB
             # occurs before the @timer variable can be set resulting in @timer being nil
             semaphore = Mutex.new
 
-            @block = proc do
-              semaphore.synchronize do
-                block.call(self)
-              end
-            end
+            timer_block = proc { semaphore.synchronize { block.call(self) } }
 
             semaphore.synchronize do
               @timer = ScriptExecution.createTimer(
-                ZonedDateTime.now.plus(@duration), @block
+                ZonedDateTime.now.plus(@duration), timer_block
               )
               super(@timer)
             end