openhab-scripting 4.32.6 → 4.33.1

data/lib/openhab/dsl/states.rb

@@ -8,12 +8,45 @@ module OpenHAB
     # Manages storing and restoring item state
     #
     module States
-      java_import org.openhab.core.model.script.actions.BusEvent
+      module_function
 
+      #
+      # Store states of supplied items
+      #
+      # @param [Array] items to store states of
+      #
+      # @return [StateStorage] item states
+      #
+      def store_states(*items)
+        items = items.flatten.map do |item|
+          item.respond_to?(:__getobj__) ? item.__getobj__ : item
+        end
+        states = OpenHAB::DSL::Support::StateStorage.from_items(*items)
+        if block_given?
+          yield
+          states.restore
+        end
+        states
+      end
+    end
+
+    module Support
+      java_import org.openhab.core.model.script.actions.BusEvent
       #
       # Delegates state storage to a Hash providing methods to operate with states
       #
       class StateStorage < SimpleDelegator
+        #
+        # Create a StateStorage object that stores the states of the given items
+        #
+        # @param [Array<Item>] *items A list of items
+        #
+        # @return [StateStorage] A state storage object
+        #
+        def self.from_items(*items)
+          StateStorage.new(BusEvent.storeStates(*items).to_h)
+        end
+
         #
         # Restore the stored states of all items
         #
@@ -39,25 +72,6 @@ module OpenHAB
           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 do |item|
-          item.respond_to?(:__getobj__) ? item.__getobj__ : item
-        end
-        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

@@ -132,6 +132,8 @@ module OpenHAB
         end
       end
 
+      module_function
+
       #
       # Get all things known to OpenHAB
       #

data/lib/openhab/dsl/time/month_day.rb

@@ -48,8 +48,8 @@ module OpenHAB
           DAYS_IN_YEAR = 366
 
           # Create a new MonthDayRange element
-          # @param [MonthDay] MonthDay element
-          # @param [Range] Underlying MonthDay range
+          # @param [MonthDay] month_day MonthDay element
+          # @param [Range] range Underlying MonthDay range
           #
           def initialize(month_day:, range:)
             @month_day = month_day

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

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
+require 'set'
 require 'openhab/log/logger'
 require_relative 'reentrant_timer'
 
 module OpenHAB
   module DSL
     #
-    # Provides access to and ruby wrappers around OpenHAB timers
+    # Provides supporting classes for Timers module
     #
-    module Timers
+    module Support
       #
       # Manages data structures that track timers
       #
@@ -52,7 +53,7 @@ module OpenHAB
 
         # Fetches the reentrant timer that matches the supplied id and block if it exists
         #
-        # @param [Object] Object to associate with timer
+        # @param [Object] id Object to associate with timer
         # @param [Block] block to execute, block is passed a Timer object
         #
         # @return [RentrantTimer] Timer object if it exists, nil otherwise

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

@@ -5,38 +5,33 @@ require_relative 'timer'
 
 module OpenHAB
   module DSL
+    # A reentrant timer is a timer that is automatically rescheduled
+    # when the block it refers to is encountered again
     #
-    # Provides access to and ruby wrappers around OpenHAB timers
-    #
-    module Timers
-      # A reentrant timer is a timer that is automatically rescheduled
-      # when the block it refers to is encountered again
-      #
-      # @author Brian O'Connell
-      # @since 2.0.0
-      class ReentrantTimer < Timer
-        include OpenHAB::Log
+    # @author Brian O'Connell
+    # @since 2.0.0
+    class ReentrantTimer < Timer
+      include OpenHAB::Log
 
-        attr_reader :id, :reentrant_id
+      attr_reader :id, :reentrant_id
 
-        #
-        # 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:, id:, thread_locals: {}, &block)
-          raise 'Reentrant timers do not work in dynamically generated code' unless block.source_location
+      #
+      # 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:, id:, thread_locals: {}, &block)
+        raise 'Reentrant timers do not work in dynamically generated code' unless block.source_location
 
-          @id = id
-          @reentrant_id = self.class.reentrant_id(id: id, &block)
-          super(duration: duration, thread_locals: thread_locals, &block)
-          logger.trace("Created Reentrant Timer #{self} with reentrant Key #{@reentrant_id}")
-        end
+        @id = id
+        @reentrant_id = self.class.reentrant_id(id: id, &block)
+        super(duration: duration, thread_locals: thread_locals, &block)
+        logger.trace("Created Reentrant Timer #{self} with reentrant Key #{@reentrant_id}")
+      end
 
-        def self.reentrant_id(id:, &block)
-          [id, block.source_location].flatten
-        end
+      def self.reentrant_id(id:, &block)
+        [id, block.source_location].flatten
       end
     end
   end

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

@@ -8,115 +8,109 @@ require 'openhab/core/thread_local'
 
 module OpenHAB
   module DSL
+    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
     #
-    # Provides access to and ruby wrappers around OpenHAB timers
-    #
-    module Timers
+    # @author Brian O'Connell
+    # @since 2.0.0
+    class Timer < SimpleDelegator
       include OpenHAB::Log
-      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
-        include OpenHAB::Log
-        include OpenHAB::Core::ThreadLocal
-        extend Forwardable
+      include OpenHAB::Core::ThreadLocal
+      extend Forwardable
 
-        def_delegator :@timer, :has_terminated, :terminated?
+      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
-        #
-        # rubocop: disable Metrics/MethodLength
-        def initialize(duration:, thread_locals: {}, &block)
-          @duration = duration
-          @thread_locals = thread_locals
+      #
+      # Create a new Timer Object
+      #
+      # @param [Duration] duration Duration until timer should fire
+      # @param [Block] block Block to execute when timer fires
+      #
+      # rubocop: disable Metrics/MethodLength
+      def initialize(duration:, thread_locals: {}, &block)
+        @duration = duration
+        @thread_locals = thread_locals
 
-          # 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
+        # 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
 
-          semaphore.synchronize do
-            @timer = ScriptExecution.createTimer(
-              ZonedDateTime.now.plus(to_duration(@duration)), timer_block(semaphore, &block)
-            )
-            @rule_timers = Thread.current[:rule_timers]
-            super(@timer)
-            Timers.timer_manager.add(self)
-          end
+        semaphore.synchronize do
+          @timer = ScriptExecution.createTimer(
+            ZonedDateTime.now.plus(to_duration(@duration)), timer_block(semaphore, &block)
+          )
+          @rule_timers = Thread.current[:rule_timers]
+          super(@timer)
+          Timers.timer_manager.add(self)
         end
-        # rubocop: enable Metrics/MethodLength
+      end
+      # rubocop: enable Metrics/MethodLength
 
-        #
-        # Reschedule timer
-        #
-        # @param [Duration] duration
-        #
-        # @return [Timer] Rescheduled timer instances
-        #
-        def reschedule(duration = nil)
-          duration ||= @duration
+      #
+      # Reschedule timer
+      #
+      # @param [Duration] duration
+      #
+      # @return [Timer] Rescheduled timer instances
+      #
+      def reschedule(duration = nil)
+        duration ||= @duration
 
-          Timers.timer_manager.add(self)
-          @timer.reschedule(ZonedDateTime.now.plus(to_duration(duration)))
-        end
+        Timers.timer_manager.add(self)
+        @timer.reschedule(ZonedDateTime.now.plus(to_duration(duration)))
+      end
 
-        #
-        # Cancel timer
-        #
-        # @return [Boolean] True if cancel was successful, false otherwise
-        #
-        def cancel
-          Timers.timer_manager.delete(self)
-          @timer.cancel
-        end
+      #
+      # Cancel timer
+      #
+      # @return [Boolean] True if cancel was successful, false otherwise
+      #
+      def cancel
+        Timers.timer_manager.delete(self)
+        @timer.cancel
+      end
 
-        private
+      private
 
-        #
-        # Constructs a block to execute timer within
-        #
-        # @param [Semaphore] Semaphore to obtain before executing
-        #
-        # @return [Proc] Block for timer to execute
-        #
-        def timer_block(semaphore)
-          proc {
-            semaphore.synchronize do
-              Timers.timer_manager.delete(self)
-              thread_local(@thread_locals) do
-                yield(self)
-              end
+      #
+      # Constructs a block to execute timer within
+      #
+      # @param [Semaphore] semaphore to obtain before executing
+      #
+      # @return [Proc] Block for timer to execute
+      #
+      def timer_block(semaphore)
+        proc {
+          semaphore.synchronize do
+            Timers.timer_manager.delete(self)
+            thread_local(@thread_locals) do
+              yield(self)
             end
-          }
-        end
-
-        #
-        # Convert argument to a duration
-        #
-        # @params [Java::JavaTimeTemporal::TemporalAmount, #to_f, #to_i, nil] duration Duration
-        #
-        # @raise if duration cannot be used for a timer
-        #
-        # @return Argument converted to seconds if it responds to #to_f or #to_i, otherwise duration unchanged
-        #
-        def to_duration(duration)
-          if duration.nil? || duration.is_a?(Java::JavaTimeTemporal::TemporalAmount)
-            duration
-          elsif duration.respond_to?(:to_f)
-            duration.to_f.seconds
-          elsif duration.respond_to?(:to_i)
-            duration.to_i.seconds
-          else
-            raise ArgumentError, "Supplied argument '#{duration}' cannot be converted to a duration"
           end
+        }
+      end
+
+      #
+      # Convert argument to a duration
+      #
+      # @param [Java::JavaTimeTemporal::TemporalAmount, #to_f, #to_i, nil] duration Duration
+      #
+      # @raise if duration cannot be used for a timer
+      #
+      # @return Argument converted to seconds if it responds to #to_f or #to_i, otherwise duration unchanged
+      #
+      def to_duration(duration)
+        if duration.nil? || duration.is_a?(Java::JavaTimeTemporal::TemporalAmount)
+          duration
+        elsif duration.respond_to?(:to_f)
+          duration.to_f.seconds
+        elsif duration.respond_to?(:to_i)
+          duration.to_i.seconds
+        else
+          raise ArgumentError, "Supplied argument '#{duration}' cannot be converted to a duration"
         end
       end
     end

data/lib/openhab/dsl/timers.rb

@@ -13,12 +13,14 @@ module OpenHAB
       include OpenHAB::Log
 
       # Manages timers
-      @timer_manager = TimerManager.new
+      @timer_manager = OpenHAB::DSL::Support::TimerManager.new
 
       class << self
         attr_reader :timer_manager
       end
 
+      module_function
+
       #
       # Execute the supplied block after the specified duration
       #
@@ -34,8 +36,10 @@ module OpenHAB
         thread_locals ||= {}
         return Timers.reentrant_timer(duration: duration, thread_locals: thread_locals, id: id, &block) if id
 
-        Timer.new(duration: duration, thread_locals: thread_locals, &block)
+        OpenHAB::DSL::Timer.new(duration: duration, thread_locals: thread_locals, &block)
       end
+      # An alias for +after+
+      alias create_timer after
 
       #
       # Provdes access to the hash for mapping timer ids to the set of active timers associated with that id
@@ -66,7 +70,7 @@ module OpenHAB
         else
           logger.trace('No reentrant timer found, creating new timer')
         end
-        ReentrantTimer.new(duration: duration, id: id, thread_locals: thread_locals, &block)
+        OpenHAB::DSL::ReentrantTimer.new(duration: duration, id: id, thread_locals: thread_locals, &block)
       end
     end
   end

data/lib/openhab/dsl/types/decimal_type.rb

@@ -22,9 +22,10 @@ module OpenHAB
         include ComparableType
 
         #
-        # Create a new instance of DateTimeType
+        # Create a new instance of DecimalType
+        #
+        # @param [java.math.BigDecimal, Items::NumericItem, Numeric] args Create a DecimalType from the given value
         #
-        # @param value [java.math.BigDecimal, Items::NumericItem, Numeric]
         def initialize(*args) # rubocop:disable Metrics
           unless args.length == 1
             super

data/lib/openhab/dsl/types/point_type.rb

@@ -13,9 +13,10 @@ module OpenHAB
       class PointType
         # @!parse include PrimitiveType
 
-        # @param latitude [DecimalType, QuantityType, StringType, Numeric]
-        # @param longitude [DecimalType, QuantityType, StringType, Numeric]
-        # @param altitude [DecimalType, QuantityType, StringType, Numeric]
+        # @overload initialize(latitude, longitude, altitude)
+        #   @param [DecimalType, QuantityType, StringType, Numeric] latitude
+        #   @param [DecimalType, QuantityType, StringType, Numeric] longitude
+        #   @param [DecimalType, QuantityType, StringType, Numeric] altitude
         def initialize(*args) # rubocop:disable Metrics
           args = from_hash(args.first.to_hash) if args.first.respond_to? :to_hash
           if (2..3).cover?(args.length)

data/lib/openhab/dsl/types/quantity_type.rb

@@ -26,10 +26,6 @@ module OpenHAB
         #
         # Convert this quantity into a another unit
         #
-        # @param [Object] other String or Unit to convert to
-        #
-        # @return [QuantityType] This quantity converted to another unit
-        #
         alias | to_unit
 
         #

data/lib/openhab/dsl/types/types.rb

@@ -24,6 +24,28 @@ require_relative 'un_def_type'
 
 module OpenHAB
   module DSL
+    # Hash taking a Enum value, and returning two symbols of
+    # predicates to be defined for it. the first is the "command" form,
+    # which should be defined on ItemCommandEvent, and on the Type itself.
+    # the second is "state" form, which should be defined on the applicable
+    # Item, and on the Type itself.
+    # @!visibility private
+    PREDICATE_ALIASES = Hash.new { |_h, k| [:"#{k.downcase}?"] * 2 }
+                            .merge({
+                                     'PLAY' => %i[play? playing?],
+                                     'PAUSE' => %i[pause? paused?],
+                                     'REWIND' => %i[rewind? rewinding?],
+                                     'FASTFORWARD' => %i[fast_forward? fast_forwarding?]
+                                   }).freeze
+
+    # Hash taking a Enum value, and returning an array of symbols
+    # of the command to define for it
+    # @!visibility private
+    COMMAND_ALIASES = Hash.new { |_h, k| k.downcase.to_sym }
+                          .merge({
+                                   'FASTFORWARD' => :fast_forward
+                                 }).freeze
+
     #
     # Contains all OpenHAB *Type classes, as well as associated support
     # modules
@@ -31,28 +53,6 @@ module OpenHAB
     module Types
       include OpenHAB::Log
 
-      # Hash taking a Enum value, and returning two symbols of
-      # predicates to be defined for it. the first is the "command" form,
-      # which should be defined on ItemCommandEvent, and on the Type itself.
-      # the second is "state" form, which should be defined on the applicable
-      # Item, and on the Type itself.
-      # @!visibility private
-      PREDICATE_ALIASES = Hash.new { |_h, k| [:"#{k.downcase}?"] * 2 }
-                              .merge({
-                                       'PLAY' => %i[play? playing?],
-                                       'PAUSE' => %i[pause? paused?],
-                                       'REWIND' => %i[rewind? rewinding?],
-                                       'FASTFORWARD' => %i[fast_forward? fast_forwarding?]
-                                     }).freeze
-
-      # Hash taking a Enum value, and returning an array of symbols
-      # of the command to define for it
-      # @!visibility private
-      COMMAND_ALIASES = Hash.new { |_h, k| k.downcase.to_sym }
-                            .merge({
-                                     'FASTFORWARD' => :fast_forward
-                                   }).freeze
-
       constants.map { |c| const_get(c) }
                .grep(Module)
                .select { |k| k < java.lang.Enum }
@@ -65,8 +65,8 @@ module OpenHAB
           # include all the aliases that we define for items both command and
           # state aliases (since types can be interrogated as an incoming
           # command, or as the state of an item)
-          command = :"#{COMMAND_ALIASES[value.to_s]}?"
-          states = PREDICATE_ALIASES[value.to_s]
+          command = :"#{OpenHAB::DSL::COMMAND_ALIASES[value.to_s]}?"
+          states = OpenHAB::DSL::PREDICATE_ALIASES[value.to_s]
 
           ([command] | states).each do |method|
             logger.trace("Defining #{klass}##{method} for #{value}")

data/lib/openhab/dsl/units.rb

@@ -17,6 +17,8 @@ module OpenHAB
     # Provides support for interacting with OpenHAB Units of Measurement
     #
     module Units
+      module_function
+
       # @return The default unit for the current thread
       def unit(unit = nil, &block)
         return with_unit(unit, &block) if unit || block # back-compat

data/lib/openhab/log/logger.rb

@@ -2,13 +2,8 @@
 
 require 'openhab/log/configuration'
 require 'java'
-require 'pp'
 
 module OpenHAB
-  #
-  # Provides access to the OpenHAB logging using a Ruby logging methods
-  #
-
   module Core
     #
     # Ruby Logger that forwards messages at appropriate levels to OpenHAB Logger
@@ -65,7 +60,7 @@ module OpenHAB
       #
       # Logs a map of key(value) with an optional preamble at trace level
       # @param [String] preamble to put at start of log message
-      # @param [Hash] key and values to log
+      # @param [Hash] kwargs key and values to log
       def state(preamble = 'State:', **kwargs)
         return unless trace_enabled?
 
@@ -102,7 +97,8 @@ module OpenHAB
       #
       # Print error and stack trace without calls to internal classes
       #
-      # @param [Exception] error A rescued error
+      # @param [Exception] exception A rescued error
+      # @param [String] rule_name The name of the rule where the exception occurred
       #
       def log_exception(exception, rule_name)
         exception = clean_backtrace(exception)
@@ -157,10 +153,11 @@ module OpenHAB
     end
   end
 
+  #
+  # Provides access to the OpenHAB logging using a Ruby logging methods
+  #
   module Log
-    #
-    # Ruby Logger that forwards messages at appropriate levels to OpenHAB Logger
-    #
+    module_function
 
     # Logger caches
     @loggers = {}
@@ -180,7 +177,7 @@ module OpenHAB
       #
       # Injects a logger into the base class
       #
-      # @param [Class] class the logger is for
+      # @param [Object] object the logger is for
       #
       # @return [Logger] for the supplied name
       #
@@ -189,7 +186,7 @@ module OpenHAB
         # of logger name requires lots of operations and logger
         # names for some objects are specific to the class
         logger_name = logger_name(object)
-        @loggers[logger_name] ||= OpenHAB::Core::Logger.new(logger_name)
+        @loggers[logger_name] ||= Core::Logger.new(logger_name)
       end
 
       private
@@ -230,11 +227,7 @@ module OpenHAB
       end
 
       #
-      # Configure a logger for the supplied classname
-      #
-      # @param [String] classname to create logger for
-      #
-      # @return [Logger] Logger for the supplied classname
+      # Returns the rules file name
       #
       def rules_file
         # Each rules file gets its own context
@@ -256,13 +249,6 @@ module OpenHAB
         klass_name
       end
 
-      #  "#{rule_name.downcase}.#{klass_name}"
-      #  if klass_name == 'Object'
-      #  "rules.#{rules_file_name.downcase}"
-      #  else
-      #  "rules.#{rules_file_name.downcase}.#{klass_name}"
-      #  end
-
       #
       # Figure out the log prefix
       #

data/lib/openhab/version.rb

@@ -5,5 +5,5 @@
 #
 module OpenHAB
   # @return [String] Version of OpenHAB helper libraries
-  VERSION = '4.32.6'
+  VERSION = '4.33.1'
 end

data/lib/openhab.rb

@@ -19,16 +19,13 @@ module OpenHAB
   #
   # @param [Object] base Object to decorate with DSL and helper methods
   #
-  #
-  # Number of extensions and includes requires more lines
   def self.extended(base)
     OpenHAB::Core.wait_till_openhab_ready
-    base.extend Log
     base.extend OpenHAB::Core::ScriptHandling
+    base.extend OpenHAB::Core::ScriptHandlingCallbacks
     base.extend OpenHAB::Core::EntityLookup
     base.extend OpenHAB::DSL
 
-    base.send :include, OpenHAB::Core::ScriptHandlingCallbacks
     logger.debug "OpenHAB JRuby Scripting Library Version #{OpenHAB::VERSION} Loaded"
 
     OpenHAB::Core.add_rubylib_to_load_path
@@ -36,7 +33,4 @@ module OpenHAB
 end
 
 # Extend caller with OpenHAB methods
-
-# rubocop: disable Style/MixinUsage
-extend OpenHAB
-# rubocop: enable Style/MixinUsage
+extend OpenHAB # rubocop:disable Style/MixinUsage