openhab-scripting 2.9.1

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

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'forwardable'
+
+module OpenHAB
+  module Core
+    module DSL
+      #
+      # Ruby implementation of OpenHAB Types
+      #
+      module Types
+        #
+        # Ruby implementation for OpenHAB quantities
+        #
+        class Quantity < Numeric
+          extend Forwardable
+          include Logging
+
+          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'
+
+          OPERATIONS = {
+            '+' => 'add',
+            '-' => 'subtract',
+            '*' => 'multiply',
+            '/' => 'divide'
+          }.freeze
+
+          private_constant :OPERATIONS
+
+          attr_reader :quantity
+
+          #
+          # Create a new Quantity
+          #
+          # @param [Java::org::openhab::core::library::types::QuantityType] quantity OpenHAB quantity to delegate to
+          #
+          def initialize(quantity)
+            @quantity = case quantity
+                        when String
+                          QuantityType.new(quantity)
+                        when QuantityType
+                          quantity
+                        when Numeric
+                          QuantityType.new(BigDecimal(quantity).to_java, AbstractUnit::ONE)
+                        else
+                          raise "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}")
+            case other
+            when Quantity
+              logger.trace("Comparing Quantity #{self} to Quantity #{other}")
+              convert_unit(quantity).compare_to(convert_unit(other.quantity))
+            when QuantityType
+              other = convert_unit(other)
+              quantity.compare_to(other)
+            when String
+              other = QuantityType.new(other)
+              other = convert_unit(other)
+              quantity.compare_to(other)
+            when Numeric
+              quantity.compare_to(QuantityType.new(other, unit)) if unit
+            end
+          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
+              [other.quantity, quantity]
+            when QuantityType
+              [other, quantity]
+            when Numeric
+              [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)
+            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
+
+          #
+          # 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 = case other
+                     when Quantity
+                       [quantity, other.quantity]
+                     when String
+                       [quantity, QuantityType.new(other)]
+                     when NumberItem
+                       a, b = other.coerce(self)
+                       logger.trace("Number Item coerced result a(#{a.class})='#{a}' b(#{b.class})='#{b}'")
+                       [a.quantity, b.quantity]
+                     when Numeric
+                       [quantity, QuantityType.new(BigDecimal(other).to_java, AbstractUnit::ONE)]
+                     else
+                       raise TypeError,
+                             "Operation '#{operation}' cannot be performed between #{self} and #{other.class}"
+                     end
+              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
+
+          DIMENSIONLESS_NON_UNITIZED_OPERATIONS = %w[* /].freeze
+
+          # Dimensionless numbers should only be unitzed for addition and subtraction
+
+          #
+          # 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)
+            if quantity.unit == AbstractUnit::ONE && DIMENSIONLESS_NON_UNITIZED_OPERATIONS.include?(operation)
+              false
+            else
+              true
+            end
+          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)
+            if unit
+              case quantity.unit
+              when AbstractUnit::ONE
+                logger.trace("Converting dimensionless #{quantity} to #{unit}")
+                QuantityType.new(quantity.to_big_decimal, unit)
+              when unit
+                quantity
+              else
+                logger.trace("Converting dimensioned item #{inspect} to #{unit}")
+                converted = quantity.to_unit(unit)
+                raise "Conversion from #{quantity.unit} to #{unit} failed" if converted.nil?
+
+                converted
+              end
+            else
+              quantity
+            end
+          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
+          #
+          # @return [Array] of quantites in correct units for the supplied operation and set unit
+          #
+          def unitize(quantity_a, quantity_b, operation)
+            [quantity_a, quantity_b].map { |qt| unitize?(qt, operation) ? convert_unit(qt) : qt }
+          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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# 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 Core
+    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
+end

data/lib/openhab/core/duration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'openhab/core/cron'
+
+module OpenHAB
+  module Core
+    #
+    # This class represents a duration of time
+    #
+    class Duration
+      include OpenHAB::Core::Cron
+
+      # @return [Array] of supported temperal units (milliseconds, seconds, minutes and hours)
+      TEMPORAL_UNITS = %i[MILLISECONDS SECONDS MINUTES HOURS].freeze
+
+      #
+      # Create a new Duration object
+      #
+      # @param [Symbol] temporal_unit Unit for duration
+      # @param [Integer] amount of that unit
+      #
+      def initialize(temporal_unit:, amount:)
+        unless TEMPORAL_UNITS.include? temporal_unit
+          raise ArgumentError,
+                "Unexpected Temporal Unit: #{temporal_unit}"
+        end
+
+        @temporal_unit = temporal_unit
+        @amount = amount
+      end
+
+      #
+      # Return a map
+      #
+      # @return [Map] Map with fields representing this duration @see OpenHAB::Core::Cron
+      #
+      def cron_map
+        case @temporal_unit
+        when :SECONDS
+          cron_expression_map.merge(second: "*/#{@amount}")
+        when :MINUTES
+          cron_expression_map.merge(minute: "*/#{@amount}")
+        when :HOURS
+          cron_expression_map.merge(hour: "*/#{@amount}")
+        else
+          raise ArgumentError, "Cron Expression not supported for temporal unit: #{temporal_unit}"
+        end
+      end
+
+      #
+      # Convert the duration to milliseconds
+      #
+      # @return [Integer] Duration in milliseconds
+      #
+      def to_ms
+        case @temporal_unit
+        when :MILLISECONDS
+          @amount
+        when :SECONDS
+          @amount * 1000
+        when :MINUTES
+          @amount * 1000 * 60
+        when :HOURS
+          @amount * 1000 * 60 * 60
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/log.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'openhab/configuration'
+require 'java'
+require 'pp'
+
+#
+# Provides access to the OpenHAB logging using a Ruby logging methods
+#
+module Logging
+  #
+  # 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
+      if msg.nil?
+        if block_given?
+          msg = yield
+        else
+          return
+        end
+      end
+
+      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
+    Logging.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] ||= Logging.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
+        Logging.logger(self.class.name)
+      end
+    end
+  end
+end