openhab-scripting 4.1.4 → 4.2.0

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

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require 'delegate'
+require 'pp'
+require 'forwardable'
+require 'openhab/core/osgi'
+require 'openhab/log/logger'
+
+module OpenHAB
+  module DSL
+    module Items
+      #
+      # Metadata extension for Items
+      #
+      module Metadata
+        include OpenHAB::Log
+
+        java_import Java::OrgOpenhabCoreItems::Metadata
+        java_import Java::OrgOpenhabCoreItems::MetadataKey
+
+        #
+        # Provide the interface to access namespace's value and configuration
+        #
+        class MetadataItem < SimpleDelegator
+          extend Forwardable
+
+          def_delegator :@metadata, :value
+
+          def initialize(metadata: nil, key: nil, value: nil, config: nil)
+            @metadata = metadata || Metadata.new(key || MetadataKey.new('', ''), value&.to_s, config)
+            super(to_ruby(@metadata&.configuration))
+          end
+
+          #
+          # Updates the metadata configuration associated with the key
+          #
+          def []=(key, value)
+            configuration = {}.merge(@metadata&.configuration || {}).merge({ key => value })
+            metadata = Metadata.new(@metadata&.uID, @metadata&.value, configuration)
+            NamespaceAccessor.registry.update(metadata) if @metadata&.uID
+          end
+
+          #
+          # Delete the configuration with the given key
+          #
+          # @return [Java::Org::openhab::core::items::Metadata] the old metadata
+          #
+          def delete(key)
+            configuration = {}.merge(@metadata&.configuration || {})
+            configuration.delete(key)
+            metadata = Metadata.new(@metadata&.uID, @metadata&.value, configuration)
+            NamespaceAccessor.registry.update(metadata) if @metadata&.uID
+          end
+
+          #
+          # Set the metadata value
+          #
+          # @return [Java::Org::openhab::core::items::Metadata] the old metadata
+          #
+          def value=(value)
+            metadata = Metadata.new(@metadata&.uID, value&.to_s, @metadata&.configuration)
+            NamespaceAccessor.registry.update(metadata) if @metadata&.uID
+          end
+
+          #
+          # Set the entire configuration to a hash
+          #
+          # @return [Java::Org::openhab::core::items::Metadata] the old metadata
+          #
+          def config=(config)
+            raise ArgumentError, 'Configuration must be a hash' unless config.is_a? Hash
+
+            metadata = Metadata.new(@metadata&.uID, @metadata&.value, config)
+            NamespaceAccessor.registry.update(metadata) if @metadata&.uID
+          end
+          alias configuration= config=
+
+          #
+          # Convert the metadata to an array
+          #
+          # @return [Array[2]] An array of [value, configuration]
+          #
+          def to_a
+            [@metadata&.value, @metadata&.configuration || {}]
+          end
+
+          private
+
+          #
+          # Recursively convert the supplied Hash object into a Ruby Hash and recreate the keys and values
+          #
+          # @param [Hash] Hash to convert
+          #
+          # @return [Hash] The converted hash
+          #
+          def to_ruby_hash(hash)
+            return unless hash.respond_to? :each_with_object
+
+            hash.each_with_object({}) { |(key, value), ruby_hash| ruby_hash[to_ruby(key)] = to_ruby(value) }
+          end
+
+          #
+          # Recursively convert the supplied array to a Ruby array and recreate all String values
+          #
+          # @param [Object] array to convert
+          #
+          # @return [Array] The converted array
+          #
+          def to_ruby_array(array)
+            return unless array.respond_to? :each_with_object
+
+            array.each_with_object([]) { |value, ruby_array| ruby_array << to_ruby(value) }
+          end
+
+          # Convert the given object to Ruby equivalent
+          def to_ruby(value)
+            case value
+            when Hash, Java::JavaUtil::Map then to_ruby_hash(value)
+            when Array, Java::JavaUtil::List then to_ruby_array(value)
+            when String then String.new(value)
+            else value
+            end
+          end
+        end
+
+        #
+        # Provide the interface to access item metadata
+        #
+        class NamespaceAccessor
+          include Enumerable
+
+          def initialize(item_name:)
+            @item_name = item_name
+          end
+
+          #
+          # Return the metadata namespace
+          #
+          # @return [OpenHAB::DSL::Items::MetadataItem], or nil if the namespace doesn't exist
+          #
+          def [](namespace)
+            logger.trace("Getting metadata for item: #{@item_name}, namespace '#{namespace}'")
+            metadata = NamespaceAccessor.registry.get(MetadataKey.new(namespace, @item_name))
+            MetadataItem.new(metadata: metadata) if metadata
+          end
+
+          #
+          # Set the metadata namespace. If the namespace does not exist, it will be created
+          #
+          # @param value [Object] The assigned value can be a OpenHAB::DSL::Items::MetadataItem,
+          # Java::Org::openhab::core::items::Metadata, Array[2] of [value, configuration],
+          # A String to set the value and clear the configuration,
+          # or a Hash to set the configuration and set the value to nil
+          #
+          # @return [OpenHAB::DSL::Items::MetadataItem]
+          #
+          def []=(namespace, value)
+            meta_value, configuration = update_from_value(value)
+
+            key = MetadataKey.new(namespace, @item_name)
+            metadata = Metadata.new(key, meta_value&.to_s, configuration)
+            # registry.get can be omitted, but registry.update will log a warning for nonexistent metadata
+            if NamespaceAccessor.registry.get(key)
+              NamespaceAccessor.registry.update(metadata)
+            else
+              NamespaceAccessor.registry.add(metadata)
+            end
+          end
+
+          #
+          # Implements Hash#dig-like functionaity to metadata
+          #
+          # @param [String] key The first key
+          # @param [Array<String, Symbol>] keys More keys to dig deeper
+          #
+          # @return [OpenHAB::DSL::Items::MetadataItem], or nil if the namespace doesn't exist
+          #
+          def dig(key, *keys)
+            keys.empty? ? self[key]&.value : self[key]&.dig(*keys)
+          end
+
+          #
+          # Enumerates through all the namespaces
+          #
+          def each
+            return unless block_given?
+
+            NamespaceAccessor.registry.getAll.each do |meta|
+              yield meta.uID.namespace, meta.value, meta.configuration if meta.uID.itemName == @item_name
+            end
+          end
+
+          #
+          # Remove all the namespaces
+          #
+          def clear
+            NamespaceAccessor.registry.removeItemMetadata @item_name
+          end
+
+          #
+          # Delete a specific namespace
+          #
+          # @param namespace [String] The namespace to delete
+          #
+          def delete(namespace)
+            NamespaceAccessor.registry.remove(MetadataKey.new(namespace, @item_name))
+          end
+
+          alias delete_all clear
+
+          #
+          # @return [Boolean] True if the given namespace exists, false otherwise
+          #
+          def key?(namespace)
+            !NamespaceAccessor.registry.get(MetadataKey.new(namespace, @item_name)).nil?
+          end
+
+          alias has_key? key?
+          alias include? key?
+
+          #
+          # Merge the given hash with the current metadata. Existing namespace that matches the name
+          # of the new namespace will be overwritten. Others will be added.
+          #
+          def merge!(*others)
+            return self if others.empty?
+
+            others.each do |other|
+              case other
+              when Hash then merge_hash!(other)
+              when self.class then merge_metadata!(other)
+              else raise ArgumentError, "merge only supports Hash, or another item's metadata"
+              end
+            end
+            self
+          end
+
+          #
+          # @return [String] the string representation of all the namespaces with their value and config
+          #
+          def to_s
+            namespaces = []
+            each { |ns, value, config| namespaces << "\"#{ns}\"=>[\"#{value}\",#{config}]" }
+            "{#{namespaces.join(',')}}"
+          end
+
+          #
+          # @return [Java::org::openhab::core::items::MetadataRegistry]
+          #
+          def self.registry
+            @registry ||= OpenHAB::Core::OSGI.service('org.openhab.core.items.MetadataRegistry')
+          end
+
+          private
+
+          #
+          # perform an updated based on the supplied value
+          #
+          # @param [MetadataItem,Metadata,Array,Hash] value to perform update from
+          #
+          # @return [Array<Object,Hash>] Array containing the value and configuration based on the
+          #   the supplied object
+          #
+          def update_from_value(value)
+            case value
+            when MetadataItem then [value.value, value.__getobj__]
+            when Metadata then [value.value, value.configuration]
+            when Array
+              raise ArgumentError, 'Array must contain 2 elements: value, config' if value.length != 2
+
+              value
+            when Hash then [nil, value]
+            else [value, nil]
+            end
+          end
+
+          #
+          # Merge the metadata from the supplied other metadata object
+          #
+          # @param [Hash] other metadata object to merge
+          # @yield [key, current_metadata, new_meta] to process merge
+          #
+          #
+          def merge_metadata!(other)
+            other.each do |key, new_value, new_config|
+              new_meta = new_value, new_config
+              if block_given?
+                current_meta = self[key]&.to_a
+                new_meta = yield key, current_meta, new_meta unless current_meta.nil?
+              end
+              self[key] = new_meta
+            end
+          end
+
+          #
+          # Merge a hash into the metadata
+          #
+          # @param [Hash] other to merge into metadata
+          # @yield [key, current_metadata, new_meta] to process merge
+          #
+          #
+          def merge_hash!(other)
+            other.each do |key, new_meta|
+              if block_given?
+                current_meta = self[key]&.to_a
+                new_meta = yield key, current_meta, new_meta unless current_meta.nil?
+              end
+              self[key] = new_meta
+            end
+          end
+        end
+
+        #
+        # Accessor to the item's metadata
+        #
+        # @return [NamespaceAccessor] an Enumerable object to access item's namespaces
+        #
+        def meta
+          @meta ||= NamespaceAccessor.new(item_name: name)
+        end
+        alias metadata meta
+      end
+    end
+  end
+end

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

@@ -1,323 +1,17 @@
 # frozen_string_literal: true
 
-require 'bigdecimal'
-require 'forwardable'
-require 'java'
-require 'openhab/dsl/types/quantity'
-require 'openhab/dsl/items/item_delegate'
+require 'openhab/dsl/items/numeric_item'
 
 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 OpenHAB::DSL::Items::ItemDelegate
-        extend OpenHAB::DSL::Items::ItemCommand
+      java_import org.openhab.core.library.items.NumberItem
 
-        def_item_delegator :@number_item
-
-        java_import org.openhab.core.library.types.DecimalType
-        java_import org.openhab.core.library.types.QuantityType
-        java_import org.openhab.core.types.util.UnitUtils
-        java_import org.openhab.core.library.unit.Units
-
-        item_type Java::OrgOpenhabCoreLibraryItems::NumberItem
-
-        #
-        # 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
-          item_missing_delegate { @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 = UnitUtils.parse_unit(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, Units::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
-
-        %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
+      # Adds methods to core OpenHAB NumberItem type to make it more natural in
+      # Ruby
+      class NumberItem < GenericItem
+        include NumericItem
       end
     end
   end
 end
-# rubocop: enable Metrics/ClassLength