openhab-scripting 2.9.1

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module OpenHAB
+  module Core
+    module DSL
+      module Rule
+        #
+        # 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/core/dsl/states.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module OpenHAB
+  module Core
+    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
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'core/log'
+require 'core/dsl/actions'
+require 'delegate'
+
+module OpenHAB
+  module Core
+    module DSL
+      #
+      # Support for OpenHAB Things
+      #
+      module Things
+        include Logging
+
+        #
+        # Ruby Delegator for Thing
+        #
+        class Thing < SimpleDelegator
+          include OpenHAB::Core::DSL::Actions
+          include Logging
+
+          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
+end

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

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'core/log'
+require 'time'
+require 'date'
+
+module OpenHAB
+  module Core
+    module DSL
+      # Namespace for classes and modules that handle Time Of Day - Times without specific dates e.g. 6:00:00
+      # @author Brian O'Connell
+      # @since 0.0.1
+      module Tod
+        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
+          def initialize(h: 0, m: 0, s: 0)
+            @local_time = LocalTime.of(h, m, s)
+            freeze
+          end
+
+          # 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
+          include Comparable
+          include Logging
+
+          NUM_SECONDS_IN_DAY = (60 * 60 * 24)
+
+          attr_reader :sod
+
+          def initialize(sod:, range_begin:)
+            @sod = sod
+            @range_begin = range_begin
+          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 = 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
+
+            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
+
+          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
+        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_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
+        module_function :between
+
+        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
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'delegate'
+require 'forwardable'
+
+require 'core/duration'
+
+module OpenHAB
+  module Core
+    module DSL
+      #
+      # Provides access to and ruby wrappers around OpenHAB timers
+      #
+      module Timers
+        java_import org.openhab.core.model.script.actions.ScriptExecution
+        java_import java.time.ZonedDateTime
+
+        # Ruby wrapper for OpenHAB Timer
+        # This class implements delegator to delegate methods to the OpenHAB timer
+        #
+        # @author Brian O'Connell
+        # @since 2.0.0
+        class Timer < SimpleDelegator
+          extend Forwardable
+
+          def_delegator :@timer, :is_active, :active?
+          def_delegator :@timer, :is_running, :running?
+          def_delegator :@timer, :has_terminated, :terminated?
+
+          #
+          # Create a new Timer Object
+          #
+          # @param [Duration] duration Duration until timer should fire
+          # @param [Block] block Block to execute when timer fires
+          #
+          def initialize(duration:, &block)
+            @duration = duration
+
+            # A semaphore is used to prevent a race condition in which calling the block from the timer thread
+            # 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
+
+            semaphore.synchronize do
+              @timer = ScriptExecution.createTimer(
+                ZonedDateTime.now.plus(Java::JavaTime::Duration.ofMillis(@duration.to_ms)), @block
+              )
+              super(@timer)
+            end
+          end
+
+          #
+          # Reschedule timer
+          #
+          # @param [Duration] duration
+          #
+          # @return [<Type>] <description>
+          #
+          def reschedule(duration = nil)
+            duration ||= @duration
+            @timer.reschedule(ZonedDateTime.now.plus(Java::JavaTime::Duration.ofMillis(duration.to_ms)))
+          end
+        end
+
+        #
+        # Execute the supplied block after the specified duration
+        #
+        # @param [Duration] duration after which to execute the block
+        # @param [Block] block to execute, block is passed a Timer object
+        #
+        # @return [Timer] Timer object
+        #
+        def after(duration, &block)
+          Timer.new(duration: duration, &block)
+        end
+      end
+    end
+  end
+end