openhab-scripting 2.16.2 → 2.19.0

data/lib/openhab/{core/dsl → dsl}/gems.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
-require 'core/log'
 require 'bundler/inline'

data/lib/openhab/dsl/group.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'delegate'
+require 'forwardable'
+require 'openhab/core/entity_lookup'
+
+module OpenHAB
+  module DSL
+    #
+    # Provides access to OpenHAB Groups
+    #
+    module Groups
+      #
+      # Indicator struct interpreted by rules to trigger based on items contained in a group
+      #
+      GroupItems = Struct.new(:group, keyword_init: true)
+
+      #
+      # Provide access to groups as a set
+      #
+      class Groups < SimpleDelegator
+        #
+        # Get a OpenHAB Group by name
+        # @param [String] name of the group to retrieve
+        #
+        # @return [Set] of OpenHAB Groups
+        #
+        def[](name)
+          group = OpenHAB::Core::EntityLookup.lookup_item(name)
+          group.is_a?(Group) ? group : nil
+        end
+      end
+
+      #
+      # Retreive all OpenHAB groups
+      #
+      # @return [Set] of OpenHAB Groups
+      #
+      def groups
+        # rubocop: disable Style/GlobalVars
+        Groups.new(OpenHAB::Core::EntityLookup.decorate_items($ir.items.select { |item| item.is_a? GroupItem }))
+        # rubocop: enable Style/GlobalVars
+      end
+
+      # Group class that provides access to OpenHAB group object and delegates other methods to
+      # a set of group items
+      class Group < SimpleDelegator
+        extend Forwardable
+
+        java_import org.openhab.core.items.GroupItem
+
+        # @return [org.openhab.core.items.GroupItem] OpenHAB Java Group Item
+        attr_accessor :group
+
+        # @!macro [attach] def_delegators
+        #   @!method $2
+        #     Forwards to org.openhab.core.items.GroupItem
+        #     @see org::openhab::core::items::GroupItem
+        def_delegator :@group, :name
+        def_delegator :@group, :label
+
+        #
+        # Gets members of this group that are themselves a group
+        #
+        # @return [Set] Set of members that are of type group
+        #
+        def groups
+          group.members.grep(org.openhab.core.items.GroupItem)
+        end
+
+        #
+        # Wraps the group in a struct, this method is intended to be called
+        # as an indicator to the rule method that the user wishes to trigger
+        # based on changes to group items
+        #
+        # @return [GroupItems] Indicator struct used by rules engine to trigger based on item changes
+        #
+        def items
+          GroupItems.new(group: group)
+        end
+
+        #
+        # @return [String] List of groups seperated by commas
+        #
+        def to_s
+          "[#{map(&:to_s).join(',')}]"
+        end
+
+        #
+        # Get an ID for the group, using the label if set, otherwise group name
+        #
+        # @return [String] label if set otherwise name
+        #
+        def id
+          label || name
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/items/datetime_item.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'java'
+require 'time'
+require 'openhab/dsl/types/datetime'
+
+module OpenHAB
+  module DSL
+    module Items
+      #
+      # Delegation to OpenHAB DateTime Item
+      #
+      # @author Anders Alfredsson
+      #
+      class DateTimeItem
+        extend Forwardable
+        include Comparable
+
+        def_delegator :@datetime_item, :to_s
+
+        #
+        # Create a new DateTimeItem
+        #
+        # @param [Java::org::openhab::core::libarary::items::DateTimeItem] datetime_item Openhab DateTimeItem to
+        # delegate to
+        #
+        def initialize(datetime_item)
+          @datetime_item = datetime_item
+        end
+
+        #
+        # Return an instance of DateTime that wraps the DateTimeItem's state
+        #
+        # @return [OpenHAB::DSL::Types::DateTime] Wrapper for the Item's state, or nil if it has no state
+        #
+        def to_dt
+          OpenHAB::DSL::Types::DateTime.new(@datetime_item.state) if state?
+        end
+
+        #
+        # Compare the Item's state to another Item or object that can be compared
+        #
+        # @param [Object] other Other objet to compare against
+        #
+        # @return [Integer] -1, 0 or 1 depending on the result of the comparison
+        #
+        def <=>(other)
+          return unless state?
+
+          logger.trace("Comparing self (#{self.class}) to #{other} (#{other.class})")
+          other = other.to_dt if other.is_a? DateTimeItem
+          to_dt <=> other
+        end
+
+        #
+        # Get the time zone of the Item
+        #
+        # @return [String] The timezone in `[+-]hh:mm(:ss)` format or nil if the Item has no state
+        #
+        def zone
+          to_dt.zone if state?
+        end
+
+        #
+        # Check if missing method can be delegated to other contained objects
+        #
+        # @param [String, Symbol] meth The method name to check for
+        #
+        # @return [Boolean] true if DateTimeItem or DateTime responds to the method, false otherwise
+        #
+        def respond_to_missing?(meth, *)
+          @datetime_item.respond_to?(meth) || to_dt.respond_to?(meth)
+        end
+
+        #
+        # Forward missing methods to the OpenHAB Item, or a DateTime object wrapping its state
+        #
+        # @param [String] meth method name
+        # @param [Array] args arguments for method
+        # @param [Proc] block <description>
+        #
+        # @return [Object] Value from delegated method in OpenHAB NumberItem
+        #
+        def method_missing(meth, *args, &block)
+          if @datetime_item.respond_to?(meth)
+            @datetime_item.__send__(meth, *args, &block)
+          elsif state?
+            to_dt.send(meth, *args, &block)
+          else
+            raise NoMethodError, "undefined method `#{meth}' for #{self.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/items/items.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'openhab/core/entity_lookup'
+
+module OpenHAB
+  module DSL
+    #
+    # Manages OpenHAB items
+    #
+    module Items
+      #
+      # Delegates to underlying set of all OpenHAB Items, provides convenience methods
+      #
+      class Items < SimpleDelegator
+        # Fetches the named item from the the ItemRegistry
+        # @param [String] name
+        # @return Item from registry, nil if item missing or requested item is a Group Type
+        def[](name)
+          OpenHAB::Core::EntityLookup.lookup_item(name)
+        rescue Java::OrgOpenhabCoreItems::ItemNotFoundException
+          nil
+        end
+
+        # Returns true if the given item name exists
+        # @param name [String] Item name to check
+        # @return [Boolean] true if the item exists, false otherwise
+        def include?(name)
+          # rubocop: disable Style/GlobalVars
+          !$ir.getItems(name).empty?
+          # rubocop: enable Style/GlobalVars
+        end
+        alias key? include?
+      end
+
+      java_import org.openhab.core.items.GroupItem
+      # Fetches all non-group items from the item registry
+      # @return [OpenHAB::DSL::Items::Items]
+      def items
+        # rubocop: disable Style/GlobalVars
+        Items.new(OpenHAB::Core::EntityLookup.decorate_items($ir.items.reject { |item| item.is_a? GroupItem }))
+        # rubocop: enable Style/GlobalVars
+      end
+    end
+  end
+end

data/lib/openhab/dsl/items/number_item.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'forwardable'
+require 'java'
+require 'openhab/dsl/types/quantity'
+
+module OpenHAB
+  module DSL
+    module Items
+      #
+      # Delegation to OpenHAB Number Item
+      #
+      # 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 NumberItem < Numeric
+        extend Forwardable
+
+        def_delegator :@number_item, :to_s
+
+        java_import org.openhab.core.library.types.DecimalType
+        java_import org.openhab.core.library.types.QuantityType
+        java_import 'tec.uom.se.format.SimpleUnitFormat'
+        java_import 'tec.uom.se.AbstractUnit'
+
+        #
+        # Create a new NumberItem
+        #
+        # @param [Java::Org::openhab::core::library::items::NumberItem] number_item OpenHAB number item to delegate to
+        #
+        def initialize(number_item)
+          @number_item = number_item
+          super()
+        end
+
+        #
+        # Check if NumberItem is truthy? as per defined by library
+        #
+        # @return [Boolean] True if item is not in state UNDEF or NULL and value is not zero.
+        #
+        def truthy?
+          @number_item.state? && @number_item.state != DecimalType::ZERO
+        end
+
+        #
+        # Coerce objects into a NumberItem
+        #
+        # @param [Object] other object to coerce to a NumberItem if possible
+        #
+        # @return [Object] NumberItem, QuantityTypes, BigDecimal or nil depending on NumberItem configuration
+        #  and/or supplied object
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} as a request from  #{other.class}")
+          case other
+          when Quantity then coerce_from_quantity(other)
+          when Numeric then  coerce_from_numeric(other)
+          else
+            logger.trace("#{self} cannot be coerced to #{other.class}")
+            nil
+          end
+        end
+
+        #
+        # Compare NumberItem to supplied object
+        #
+        # @param [Object] other object to compare to
+        #
+        # @return [Integer] -1,0,1 or nil depending on value supplied,
+        #   nil comparison to supplied object is not possible.
+        #
+        def <=>(other)
+          logger.trace("NumberItem #{self} <=> #{other} (#{other.class})")
+          case other
+          when NumberItem then number_item_compare(other)
+          when Numeric then numeric_compare(other)
+          when String then string_compare(other)
+          else state_compare(other)
+          end
+        end
+
+        #
+        # Convert NumberItem to a Quantity
+        #
+        # @param [Object] other String or Unit representing an OpenHAB Unit
+        #
+        # @return [OpenHAB::DSL::Types::Quantity] NumberItem converted to supplied Unit
+        #
+        def |(other)
+          other = SimpleUnitFormat.instance.unitFor(other) if other.is_a? String
+
+          if dimension
+            to_qt | other
+          else
+            Quantity.new(QuantityType.new(to_d.to_java, other))
+          end
+        end
+
+        #
+        # Convert NumberItem to a Quantity
+        #
+        # @return [OpenHAB::DSL::Types::Quantity] NumberItem converted to a QuantityUnit
+        #
+        def to_qt
+          if dimension
+            Quantity.new(@number_item.get_state_as(QuantityType))
+          else
+            Quantity.new(QuantityType.new(to_d.to_java, AbstractUnit::ONE))
+          end
+        end
+
+        #
+        # Converts the NumberItem to an Integer
+        #
+        # @return [Integer] NumberItem as an integer
+        #
+        def to_i
+          to_d&.to_i
+        end
+
+        #
+        # Converts the NumberItem to a float
+        #
+        # @return [Float] NumberItem as a float
+        #
+        def to_f
+          to_d&.to_f
+        end
+
+        #
+        # Converts the NumberItem to a BigDecimal
+        #
+        # @return [BigDecimal] NumberItem as a BigDecimal
+        #
+        def to_d
+          @number_item.state.to_big_decimal.to_d if @number_item.state.respond_to? :to_big_decimal
+        end
+
+        #
+        # Get the Dimension attached to the NumberItem
+        #
+        # @return [Java::org::openhab::core::library::types::QuantityType] dimension
+        #
+        def dimension
+          @number_item.dimension
+        end
+
+        #
+        # Forward missing methods to Openhab Number Item if they are defined
+        #
+        # @param [String] meth method name
+        # @param [Array] args arguments for method
+        # @param [Proc] block <description>
+        #
+        # @return [Object] Value from delegated method in OpenHAB NumberItem
+        #
+        def method_missing(meth, *args, &block)
+          logger.trace("Method missing, performing dynamic lookup for: #{meth}")
+          if @number_item.respond_to?(meth)
+            @number_item.__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)
+          @number_item.respond_to?(method_name) ||
+            ::Kernel.method_defined?(method_name) ||
+            ::Kernel.private_method_defined?(method_name)
+        end
+
+        %w[+ - * /].each do |operation|
+          define_method(operation) do |other|
+            logger.trace("Execution math operation '#{operation}' on #{inspect} with #{other.inspect}")
+            left_operand, right_operand = operands_for_operation(other)
+            left_operand.public_send(operation, right_operand)
+          end
+        end
+
+        private
+
+        #
+        # Compare if other responds to state
+        #
+        # @param [Object] other object to compare to
+        #
+        # @return [Integer] -1,0,1 depending on less than, equal to or greater than other
+        #
+        def state_compare(other)
+          other = other.state if other.respond_to? :state
+          @number_item.state <=> other
+        end
+
+        #
+        # Compare if other is a String
+        #
+        # @param [String] other object to compare to
+        #
+        # @return [Integer] -1,0,1,nil depending on less than, equal to or greater than other
+        #   nil if this number item does not have a dimension
+        #
+        def string_compare(other)
+          @number_item.state <=> QuantityType.new(other) if dimension
+        end
+
+        #
+        # Compare if other is a Numeric
+        #
+        # @param [String] other to compare to
+        #
+        # @return [Integer] -1,0,1 depending on less than, equal to or greater than other
+        #
+        def numeric_compare(other)
+          @number_item.state.to_big_decimal.to_d <=> other.to_d
+        end
+
+        #
+        # Get the operands for any operation
+        #
+        # @param [Object] other object to convert to a compatible operand
+        #
+        # @return [Array[Object,Object]] of operands where the first value is the left operand
+        #   and the second value is the right operand
+        #
+        def operands_for_operation(other)
+          case other
+          when NumberItem then number_item_operands(other)
+          when Numeric then [to_d, other.to_d]
+          when String then string_operands(other)
+          else
+            return other.coerce(to_d) if other.respond_to? :coerce
+
+            raise ArgumentError, "#{other.class} can't be coerced into a NumberItem"
+          end
+        end
+
+        #
+        # Get operands for an operation when the right operand is provided as a string
+        #
+        # @param [String] other right operand
+        #
+        # @return [Array[QuantityType,QuantiyType]] of operands where the first value is the left operand
+        #   and the second value is the right operand
+        #
+        def string_operands(other)
+          return [to_qt, Quantity.new(other)] if dimension
+
+          raise ArgumentError, 'Strings are only valid operands if NumberItem is dimensions=ed.'
+        end
+
+        #
+        # Get operands for an operation when the right operand is provided is another number item
+        #
+        # @param [NumberItem] other right operand
+        #
+        # @return [Array<QuantityType,QuantityType>,Array<BigDecimal,BigDecimal>] of operands depending on
+        #   if the left or right operand has a dimensions
+        #
+        def number_item_operands(other)
+          if dimension || other.dimension
+            dimensioned_operands(other)
+          else
+            logger.trace("Both objects lack dimension, self='#{self}' other='#{other}'")
+            # If nothing has a dimension, just use BigDecimals
+            [to_d, other.to_d]
+          end
+        end
+
+        #
+        # Get operands for an operation when the left or right operand has a dimension
+        #
+        # @param [NumberItem] other right operand
+        #
+        # @return [Array<QuantityType,QuantityType>] of operands
+        #
+        def dimensioned_operands(other)
+          logger.trace("Dimensions self='#{dimension}' other='#{other.dimension}'")
+          if dimension
+            if other.dimension
+              # If both numbers have dimensions, do the math on the quantity types.
+              [to_qt, other.to_qt]
+            else
+              # If this number has dimension and the other does not,
+              # do math with this quantity type and the other as a big decimal
+              [to_qt, other]
+            end
+          else
+            # If this number has no dimension and the other does, convert this into a dimensionless quantity
+            [to_qt, other]
+          end
+        end
+
+        #
+        # Compare two number items, taking into account any dimensions
+        #
+        # @param [NumberItem] other number item
+        #
+        # @return [-1,0,1] depending on if other object is less than, equal to or greater than self
+        #
+        def number_item_compare(other)
+          if other.dimension
+            logger.trace('Other is dimensioned, converting self and other to QuantityTypes to compare')
+            to_qt <=> other.to_qt
+          else
+            @number_item.state <=> other.state
+          end
+        end
+
+        #
+        # Coerce from a numberic object depnding on dimension and state
+        #
+        # @param [Numeric] other numeric object to convert
+        #
+        # @return [Array<QuantityType,QuantityType>,Array<BigDecimal,BigDecimal>,nil] depending on
+        #   if this object has a dimension or state
+        #
+        def coerce_from_numeric(other)
+          if dimension
+            [Quantity.new(other), to_qt]
+          elsif @number_item.state?
+            [other.to_d, @number_item.state.to_big_decimal.to_d]
+          end
+        end
+
+        #
+        # Coerce when other is a quantity
+        #
+        # @param [QuantityType] other
+        #
+        # @return [Array<QuanityType,QuantityType] other and self as a quantity type
+        #
+        def coerce_from_quantity(other)
+          as_qt = to_qt
+          logger.trace("Converted #{self} to a Quantity #{as_qt}")
+          [other, as_qt]
+        end
+      end
+    end
+  end
+end
+# rubocop: enable Metrics/ClassLength