openhab-scripting 2.14.3 → 2.16.3

data/lib/openhab/dsl/timers.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'delegate'
+require 'forwardable'
+
+module OpenHAB
+  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
+
+          timer_block = proc { semaphore.synchronize { block.call(self) } }
+
+          semaphore.synchronize do
+            @timer = ScriptExecution.createTimer(
+              ZonedDateTime.now.plus(@duration), timer_block
+            )
+            super(@timer)
+          end
+        end
+
+        #
+        # Reschedule timer
+        #
+        # @param [Duration] duration
+        #
+        # @return [<Type>] <description>
+        #
+        def reschedule(duration = nil)
+          duration ||= @duration
+          @timer.reschedule(ZonedDateTime.now.plus(duration))
+        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

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

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'forwardable'
+
+module OpenHAB
+  module DSL
+    #
+    # Ruby implementation of OpenHAB Types
+    #
+    module Types
+      #
+      # Ruby implementation for OpenHAB quantities
+      #
+      # rubocop: disable Metrics/ClassLength
+      # Disabled because this class has a single responsibility, there does not appear a logical
+      # way of breaking it up into multiple classes
+      class Quantity < Numeric
+        extend Forwardable
+        include OpenHAB::Log
+
+        def_delegator :@quantity, :to_s
+
+        java_import org.openhab.core.library.types.QuantityType
+        java_import 'tec.uom.se.format.SimpleUnitFormat'
+        java_import 'tec.uom.se.AbstractUnit'
+
+        # @return [Hash] Mapping of operation symbols to BigDecimal methods
+        OPERATIONS = {
+          '+' => 'add',
+          '-' => 'subtract',
+          '*' => 'multiply',
+          '/' => 'divide'
+        }.freeze
+
+        private_constant :OPERATIONS
+
+        attr_reader :quantity
+
+        #
+        # Create a new Quantity
+        #
+        # @param [object] quantity String,QuantityType or Numeric to be this quantity
+        #
+        # Cop disabled, case statement is compact and idiomatic
+        def initialize(quantity)
+          @quantity = case quantity
+                      when String then QuantityType.new(quantity)
+                      when QuantityType then quantity
+                      when NumberItem, Numeric then QuantityType.new(quantity.to_d.to_java, AbstractUnit::ONE)
+                      else raise ArgumentError, "Unexpected type #{quantity.class} provided to Quantity initializer"
+                      end
+          super()
+        end
+
+        #
+        # Convert this quantity into a another unit
+        #
+        # @param [Object] other String or Unit to convert to
+        #
+        # @return [Quantity] This quantity converted to another unit
+        #
+        def |(other)
+          other = SimpleUnitFormat.instance.unitFor(other) if other.is_a? String
+
+          Quantity.new(quantity.to_unit(other))
+        end
+
+        #
+        # Compare this quantity
+        #
+        # @param [Object] other object to compare to
+        #
+        # @return [Integer] -1,0,1 if this object is less than, equal to, or greater than the supplied object,
+        #   nil if it cannot be compared
+        #
+        def <=>(other)
+          logger.trace("Comparing #{self} to #{other}")
+          my_qt, other_qt = unitize(*to_qt(coerce(other).reverse))
+          my_qt.compare_to(other_qt)
+        end
+
+        #
+        # Coerce other object into a Quantity
+        #
+        # @param [Object] other object to convert to Quantity
+        #
+        # @return [Array] of self and other object as Quantity types, nil if object cannot be coerced
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} as a request from #{other.class}")
+          case other
+          when Quantity then [other.quantity, quantity]
+          when QuantityType then [other, quantity]
+          when NumberItem then [other.to_qt.quantity, quantity]
+          when Numeric, String then [Quantity.new(other), self]
+          end
+        end
+
+        #
+        # Forward missing methods to Openhab Quantity Item if they are defined
+        #
+        # @param [String] meth name of method invoked
+        # @param [Array] args arguments to invoked method
+        # @param [Proc] block block passed ot method
+        #
+        # @return [Object] result of delegation
+        #
+        def method_missing(meth, *args, &block)
+          logger.trace("Method missing, performing dynamic lookup for: #{meth}")
+          if quantity.respond_to?(meth)
+            quantity.__send__(meth, *args, &block)
+          elsif ::Kernel.method_defined?(meth) || ::Kernel.private_method_defined?(meth)
+            ::Kernel.instance_method(meth).bind_call(self, *args, &block)
+          else
+            super(meth, *args, &block)
+          end
+        end
+
+        #
+        # Checks if this method responds to the missing method
+        #
+        # @param [String] method_name Name of the method to check
+        # @param [Boolean] _include_private boolean if private methods should be checked
+        #
+        # @return [Boolean] true if this object will respond to the supplied method, false otherwise
+        #
+        def respond_to_missing?(method_name, _include_private = false)
+          quantity.respond_to?(method_name) ||
+            ::Kernel.method_defined?(method_name) ||
+            ::Kernel.private_method_defined?(method_name)
+        end
+
+        #
+        # Negate the quantity
+        #
+        # @return [Quantity] This quantity negated
+        #
+        def -@
+          Quantity.new(quantity.negate)
+        end
+
+        OPERATIONS.each do |operation, method|
+          define_method(operation) do |other|
+            logger.trace("Executing math operation '#{operation}' on quantity #{inspect} "\
+                         "with other type #{other.class} and value #{other.inspect}")
+
+            a, b = to_qt(coerce(other).reverse)
+            logger.trace("Coerced a='#{a}' with b='#{b}'")
+            a, b = unitize(a, b, operation)
+            logger.trace("Unitized a='#{a}' b='#{b}'")
+            logger.trace("Performing operation '#{operation}' with method '#{method}' on a='#{a}' with b='#{b}'")
+            Quantity.new(a.public_send(method, b))
+          end
+        end
+
+        #
+        # Provide details about quantity object
+        #
+        # @return [String] Representing details about the quantity object
+        #
+        def inspect
+          if @quantity.unit == AbstractUnit::ONE
+            "unit=#{@quantity.unit}, value=#{@quantity.to_string}"
+          else
+            @quantity.to_string
+          end
+        end
+
+        private
+
+        # @return [Array] Array of strings for operations for which the operands will not be unitized
+        DIMENSIONLESS_NON_UNITIZED_OPERATIONS = %w[* /].freeze
+
+        # Dimensionless numbers should only be unitzed for addition and subtraction
+
+        #
+        # Convert one or more Quantity obects to the underlying quantitytypes
+        #
+        # @param [Array] quanities Array of either Quantity or QuantityType objects
+        #
+        # @return [Array]  Array of QuantityType objects
+        #
+        def to_qt(*quanities)
+          [quanities].flatten.compact.map { |item| item.is_a?(Quantity) ? item.quantity : item }
+        end
+
+        #
+        # Checks if an item should be unitized
+        #
+        # @param [Quantity] quantity to check
+        # @param [String] operation quantity is being used with
+        #
+        # @return [Boolean] True if the quantity should be unitzed based on the unit and operation, false otherwise
+        #
+        def unitize?(quantity, operation)
+          !(quantity.unit == AbstractUnit::ONE && DIMENSIONLESS_NON_UNITIZED_OPERATIONS.include?(operation))
+        end
+
+        #
+        # Convert the unit for the quantity
+        #
+        # @param [Quantity] quantity being converted
+        #
+        # @return [Quantity] Quantity coverted to unit set by unit block
+        #
+        def convert_unit(quantity)
+          return quantity unless unit?
+
+          case quantity.unit
+          when unit
+            quantity
+          when AbstractUnit::ONE
+            convert_unit_from_dimensionless(quantity, unit)
+          else
+            convert_unit_from_dimensioned(quantity, unit)
+          end
+        end
+
+        #
+        # Converts a dimensioned quantity to a specific unit
+        #
+        # @param [Quantity] quantity to convert
+        # @param [Unit] unit to convert to
+        #
+        # @return [Java::org::openhab::core::library::types::QuantityType] converted quantity
+        #
+        def convert_unit_from_dimensioned(quantity, unit)
+          logger.trace("Converting dimensioned item #{inspect} to #{unit}")
+          quantity.to_unit(unit).tap do |converted|
+            raise "Conversion from #{quantity.unit} to #{unit} failed" unless converted
+          end
+        end
+
+        #
+        # Converts a dimensionless quantity to a unit
+        #
+        # @param [Quantity] quantity to convert
+        # @param [Unit] unit to convert to
+        #
+        # @return [Java::org::openhab::core::library::types::QuantityType] converted quantity
+        #
+        def convert_unit_from_dimensionless(quantity, unit)
+          logger.trace("Converting dimensionless #{quantity} to #{unit}")
+          QuantityType.new(quantity.to_big_decimal, unit)
+        end
+
+        #
+        # Convert quantities to appropriate units
+        #
+        # @param [Quantity] quantity_a Quantity on left side of operation
+        # @param [Quantity] quantity_b Quantity on right side of operation
+        # @param [String] operation Math operation
+        # @yield [quantity_a, quantity_b] yields unitized versions of supplied quantities
+        #
+        # @return [Array, Object] of quantites in correct units for the supplied operation and the unit
+        #   or the result of the block if a block is given
+        #
+        def unitize(quantity_a, quantity_b, operation = nil)
+          logger.trace("Unitizing (#{quantity_a}) and (#{quantity_b})")
+          quantity_a, quantity_b = [quantity_a, quantity_b].map do |qt|
+            unitize?(qt, operation) ? convert_unit(qt) : qt
+          end
+          return yield quantity_a, quantity_b if block_given?
+
+          [quantity_a, quantity_b]
+        end
+
+        #
+        # Get the unit from the current thread local variable
+        #
+        # @return [Object] Unit or string representation of Unit, or nil if not set
+        #
+        def unit
+          Thread.current.thread_variable_get(:unit)
+        end
+
+        #
+        # Is a unit set for this thread
+        #
+        # @return [boolean] true if a unit is set by this thread, false otherwise
+        #
+        def unit?
+          unit != nil
+        end
+      end
+    end
+  end
+end
+# rubocop: enable Metrics/ClassLength

data/lib/openhab/dsl/units.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'java'
+
+# Import Imperial and SI Units overriding provided values
+%i[ImperialUnits SIUnits].each do |type|
+  Object.send(:remove_const, type)
+  java_import "org.openhab.core.library.unit.#{type}"
+end
+
+Object.send(:remove_const, :QuantityType)
+java_import org.openhab.core.library.types.QuantityType
+
+module OpenHAB
+  module DSL
+    #
+    # Provides support for interacting with OpenHAB Units of Measurement
+    #
+    module Units
+      java_import 'tec.uom.se.format.SimpleUnitFormat'
+
+      #
+      # Sets a thread local variable to the supplied unit such that classes operating inside the block
+      # can perform automatic conversions to the supplied unit for NumberItems
+      #
+      # @param [Object] unit OpenHAB Unit or String representing unit
+      # @yield [] Block executed in context of the supplied unit
+      #
+      #
+      def unit(unit)
+        unit = SimpleUnitFormat.instance.unitFor(unit) if unit.is_a? String
+        Thread.current.thread_variable_set(:unit, unit)
+        yield
+      ensure
+        Thread.current.thread_variable_set(:unit, nil)
+      end
+    end
+  end
+end

data/lib/openhab/log/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  # Supports Logging
+  module Log
+    # This module holds global configuration values
+    module Configuration
+      # -*- coding: utf-8 -*-
+      LOG_PREFIX = 'jsr223.jruby'
+
+      #
+      # Gets the log prefix
+      #
+      # @return [String] Prefix for all log entries
+      #
+      def self.log_prefix
+        LOG_PREFIX
+      end
+    end
+  end
+end

data/lib/openhab/log/logger.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'openhab/log/configuration'
+require 'java'
+require 'pp'
+
+module OpenHAB
+  #
+  # Provides access to the OpenHAB logging using a Ruby logging methods
+  #
+  module Log
+    #
+    # Ruby Logger that forwards messages at appropriate levels to OpenHAB Logger
+    #
+    class Logger
+      java_import org.slf4j.LoggerFactory
+
+      # @return [Array] Supported logging levels
+      LEVELS = %i[TRACE DEBUG WARN INFO ERROR].freeze
+
+      #
+      # Create a new logger
+      #
+      # @param [String] name of the logger
+      #
+      def initialize(name)
+        @sl4fj_logger = LoggerFactory.getLogger(name)
+      end
+
+      # Dynamically define the methods for each level as identified by the levels constant
+      # This creates a method for each level that looks like this
+      # def <level>(msg=nil, &block)
+      #   log(severity: <level>, msg: msg, &block)
+      # end
+      LEVELS.each do |level|
+        method = level.to_s.downcase
+        define_method(method.to_s) do |msg = nil, &block|
+          log(severity: level, msg: msg, &block)
+        end
+      end
+
+      private
+
+      #
+      # Log a message to the OpenHAB Logger
+      #
+      # @param [Symbol] severity Severity to log message at
+      # @param [Object] msg to log, if no msg supplied and a block is provided,
+      #   the msg is taken from the result of the block
+      #
+      def log(severity:, msg: nil)
+        severity = severity.to_sym
+
+        raise ArgumentError, "Unknown Severity #{severity}" unless LEVELS.include? severity
+
+        # Dynamically check enablement of underlying logger, this expands to "is_<level>_enabled"
+        return unless @sl4fj_logger.send("is_#{severity.to_s.downcase}_enabled")
+
+        # Process block if no message provided
+        msg = yield if msg.nil? && block_given?
+
+        msg = message_to_string(msg: msg)
+
+        # Dynamically invoke underlying logger, this expands to "<level>(message)"
+        @sl4fj_logger.send(severity.to_s.downcase, msg)
+      end
+
+      #
+      # Conver the supplied message object to a String
+      #
+      # @param [object] msg object to convert
+      #
+      # @return [String] Msg object as a string
+      #
+      def message_to_string(msg:)
+        case msg
+        when ::String
+          msg
+        when ::Exception
+          "#{msg.message} (#{msg.class})\n#{msg.backtrace&.join("\n")}"
+        else
+          msg.inspect
+        end
+      end
+    end
+
+    @loggers = {}
+
+    # Return a logger with the configured log prefix plus the calling scripts name
+
+    #
+    # Create a logger for the current class
+    #
+    # @return [Logger] for the current class
+    #
+    def logger
+      Log.logger(self.class.name)
+    end
+
+    class << self
+      #
+      # Injects a logger into the base class
+      #
+      # @param [String] name of the logger
+      #
+      # @return [Logger] for the supplied name
+      #
+      def logger(name)
+        name ||= self.class.name
+        @loggers[name] ||= Log.logger_for(name)
+      end
+
+      #
+      # Configure a logger for the supplied class name
+      #
+      # @param [String] classname to configure logger for
+      #
+      # @return [Logger] for the supplied classname
+      #
+      def logger_for(classname)
+        configure_logger_for(classname)
+      end
+
+     private
+
+      #
+      # Configure a logger for the supplied classname
+      #
+      # @param [String] classname to create logger for
+      #
+      # @return [Logger] Logger for the supplied classname
+      #
+      def configure_logger_for(classname)
+        log_prefix = Configuration.log_prefix
+        log_prefix += if classname
+                        ".#{classname}"
+                      else
+                        ".#{log_caller}"
+                      end
+        Logger.new(log_prefix)
+      end
+
+      #
+      # Figure out the log prefix
+      #
+      # @return [String] Prefix for log messages
+      #
+      def log_caller
+        caller_locations.map(&:path)
+                        .grep_v(%r{openhab/core/})
+                        .grep_v(/rubygems/)
+                        .grep_v(%r{lib/ruby})
+                        .first
+                        .yield_self { |caller| File.basename(caller, '.*') }
+      end
+   end
+
+    #
+    # Add logger method to the object that includes this module
+    #
+    # @param [Object] base Object to add method to
+    #
+    #
+    def self.included(base)
+      class << base
+        def logger
+          Log.logger(self.class.name)
+        end
+      end
+    end
+  end
+end