openhab-scripting 2.15.0 → 2.16.4

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'java'
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # 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

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'openhab/log/logger'
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Module holds rule triggers
+      #
+      module Triggers
+        include OpenHAB::Log
+
+        #
+        # 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

data/lib/openhab/dsl/states.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module OpenHAB
+  module DSL
+    #
+    # Manages storing and restoring item state
+    #
+    module States
+      java_import org.openhab.core.model.script.actions.BusEvent
+
+      #
+      # Delegates state storage to a Hash providing methods to operate with states
+      #
+      class StateStorage < SimpleDelegator
+        #
+        # Restore the stored states of all items
+        #
+        #
+        def restore
+          BusEvent.restoreStates(to_h)
+        end
+
+        #
+        # Restore states for items that have changed
+        #
+        #
+        def restore_changes
+          BusEvent.restoreStates(select { |item, value| item != value })
+        end
+
+        #
+        # Detect if any item have changed states since being stored
+        #
+        # @return [Boolean] True if any items have changed states, false otherwise
+        #
+        def changed?
+          any? { |item, value| item != value }
+        end
+      end
+
+      #
+      # Store states of supplied items
+      #
+      # @param [Array] items to store states of
+      #
+      # @return [StateStorage] item states
+      #
+      def store_states(*items)
+        items = items.flatten.map { |item| item.is_a?(Group) ? item.group : item }
+        states = StateStorage.new(BusEvent.storeStates(*items).to_h)
+        if block_given?
+          yield
+          states.restore
+        end
+        states
+      end
+    end
+  end
+end

data/lib/openhab/dsl/things.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'openhab/log/logger'
+require 'openhab/dsl/actions'
+require 'delegate'
+
+module OpenHAB
+  module DSL
+    #
+    # Support for OpenHAB Things
+    #
+    module Things
+      include OpenHAB::Log
+
+      #
+      # Ruby Delegator for Thing
+      #
+      class Thing < SimpleDelegator
+        include OpenHAB::DSL::Actions
+        include OpenHAB::Log
+
+        def initialize(thing)
+          super
+          define_action_methods
+        end
+
+        private
+
+        java_import 'org.openhab.core.automation.annotation.RuleAction'
+
+        #
+        # Define methods from actions mapped to this thing
+        #
+        #
+        def define_action_methods
+          actions_for_thing(uid).each do |action|
+            methods = action.java_class.declared_instance_methods
+            methods.select { |method| method.annotation_present?(RuleAction.java_class) }
+                   .each { |method| define_action_method(action: action, method: method.name) }
+          end
+        end
+
+        #
+        # Define a method, delegating to supplied action class
+        #
+        # @param [Object] action object to delegate method to
+        # @param [String] method Name of method to delegate
+        #
+        #
+        def define_action_method(action:, method:)
+          logger.trace("Adding action method '#{method}' to thing '#{uid}'")
+          define_singleton_method(method) do |*args|
+            action.public_send(method, *args)
+          end
+        end
+      end
+
+      #
+      # Wraps all Things in a delegator to underlying set and provides lookup method
+      #
+      class Things < SimpleDelegator
+        java_import org.openhab.core.thing.ThingUID
+
+        # Gets a specific thing by name in the format binding_id:type_id:thing_id
+        # @return Thing specified by name or nil if name does not exist in thing registry
+        def[](uid)
+          thing_uid = ThingUID.new(*uid.split(':'))
+          # rubocop: disable Style/GlobalVars
+          thing = $things.get(thing_uid)
+          # rubocop: enable Style/GlobalVars
+          return unless thing
+
+          logger.trace("Retrieved Thing(#{thing}) from registry for uid: #{uid}")
+          Thing.new(thing)
+        end
+      end
+
+      #
+      # Get all things known to OpenHAB
+      #
+      # @return [Set] of all Thing objects known to openhab
+      #
+      def things
+        # rubocop: disable Style/GlobalVars
+        Things.new($things.getAll.map { |thing| Thing.new(thing) }.to_set)
+        # rubocop: enable Style/GlobalVars
+      end
+    end
+  end
+end

data/lib/openhab/dsl/time_of_day.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'openhab/log/logger'
+require 'time'
+require 'date'
+
+module OpenHAB
+  module DSL
+    # Times without specific dates e.g. 6:00:00
+    # @author Brian O'Connell
+    # @since 0.0.1
+    module TimeOfDay
+      java_import java.time.LocalTime
+      java_import java.time.format.DateTimeFormatterBuilder
+      java_import java.util.Locale
+
+      # Class that encapsulates a Time of Day, often viewed as hour-minute-second
+      # @author Brian O'Connell
+      # @since 0.0.1
+      class TimeOfDay
+        include Comparable
+
+        # Immutable Java object containing Time Of Day
+        # @return [Java.Time.LocalTime] reprsenting the Time Of Day
+        attr_reader :local_time
+
+        # Constructs a TimeOfDay representing the time when called
+        # @since 0.0.1
+        # @return [TimeOfDay] representing time when method was invoked
+        def self.now
+          now = LocalTime.now()
+          TimeOfDay.new(h: now.hour, m: now.minute, s: now.second)
+        end
+
+        # Constructs a TimeOfDay representing midnight
+        # @since 0.0.1
+        # @return [TimeOfDay] representing midnight
+        def self.midnight
+          TimeOfDay.new(h: 0, m: 0, s: 0)
+        end
+
+        # Constructs a TimeOfDay representing noon
+        # @since 0.0.1
+        # @return [TimeOfDay] representing noon
+        def self.noon
+          TimeOfDay.new(h: 12, m: 0, s: 0)
+        end
+
+        # 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"
+        # @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]]'
+          local_time = LocalTime.parse(string, DateTimeFormatterBuilder.new
+            .parseCaseInsensitive.appendPattern(format).toFormatter(Locale::ENGLISH))
+          TimeOfDay.new(h: local_time.hour, m: local_time.minute, s: local_time.second)
+        rescue java.time.format.DateTimeParseException => e
+          raise ArgumentError, e.message
+        end
+
+        # Constructs a TimeOfDay representing the time when called
+        # @since 0.0.1
+        # @option opts [Number] :h Hour of the day, defaults to 0
+        # @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)
+          between(range).cover? self
+        end
+
+        # Returns the hour of the TimeOfDay
+        # @since 0.0.1
+        # @return [Number] Hour of the day, from 0 to 23
+        def hour
+          @local_time.hour
+        end
+
+        # Returns the minute of the TimeOfDay
+        # @since 0.0.1
+        # @return [Number] minute of the day, from 0 to 59
+        def minute
+          @local_time.minute
+        end
+
+        # Returns the second of the TimeOfDay
+        # @since 0.0.1
+        # @return [Number] second of the day, from 0 to 59
+        def second
+          @local_time.second
+        end
+
+        # 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
+        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
+        def <=>(other)
+          case other
+          when TimeOfDay
+            @local_time.compare_to(other.local_time)
+          when String
+            @local_time.compare_to(TimeOfDay.parse(other).local_time)
+          else
+            -(other <=> self)
+          end
+        end
+      end
+
+      # Modules that refines the Ruby Range object cover? and include? methods to support TimeOfDay ranges
+      class TimeOfDayRangeElement < Numeric
+        include Comparable
+        include OpenHAB::Log
+
+        NUM_SECONDS_IN_DAY = (60 * 60 * 24)
+
+        attr_reader :sod
+
+        def initialize(sod:, range_begin:)
+          @sod = sod
+          @range_begin = range_begin
+          super()
+        end
+
+        # Returns the current second of day advanced by 1 second
+        def succ
+          TimeOfDayRangeElement.new(sod: @sod + 1, range_begin: @range_begin)
+        end
+
+        # Compares one TimeOfDayRangeElement to another
+        # @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 = 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})"
+          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
+        end
+      end
+
+      # Creates a range that can be compared against time of day objects or strings
+      # 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 = 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
+        ending_sod += TimeOfDayRangeElement::NUM_SECONDS_IN_DAY if ending_sod < start_sod
+
+        start_range = TimeOfDayRangeElement.new(sod: start_sod, range_begin: start_sod)
+        ending_range = TimeOfDayRangeElement.new(sod: ending_sod, range_begin: start_sod)
+        range.exclude_end? ? (start_range...ending_range) : (start_range..ending_range)
+      end
+
+      #
+      # 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
+      ALL_DAY = between(TimeOfDay.new(h: 0, m: 0, s: 0)..TimeOfDay.new(h: 23, m: 59, s: 59))
+    end
+  end
+end