openhab-scripting 5.5.0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b21bcd2b958405fb4b4843435e3a6ffa14690af1b6f58139897982a7d55323f
-  data.tar.gz: a1c258192db348813c49b94e21492771d9b2e7d6515e6aff0e04b5bba7786711
+  metadata.gz: 8c8baeb1d9f83c584fd3affe173ceecd5d00fedb8547701c134cc7f1e7e8b924
+  data.tar.gz: b202b62cba639b270e60a73c405b6de5ede001a8bd6ee4fa065363156497b396
 SHA512:
-  metadata.gz: 81fd4bfaa0f3cb1907622938750dc0eabcc51b0d46d8ad39fd63282ad6118771f79b38a72fc10ffaa19f0037564d1adb710c7da0b981dad37f9cdf9b6f665cfd
-  data.tar.gz: 1b30d461514d2f952e71e3ce7325dd5582fa386ca21723458b725378f6f78880f96bf5693a03aeb64d8a70775830979fe6d8f732c67076abaf9fd687e0ff4948
+  metadata.gz: 06a58a345353b826ca398943d50295dd54a137b42d6fb803058507f6df19e673a27cacdfdaf7f7fa445d881468122535178e0a0f4f00eaa831ebe78bb4b060de
+  data.tar.gz: 5572ccf8e1e094d7b1eec9415e8d39b1f18b468e99d661b25f4064b1fde0d34a89d85163c4ce77b7f97b32f1532249d66cff310377e0850de0a1388f1e7f44a3

data/lib/openhab/core/configuration.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "emulate_hash"
+
+module OpenHAB
+  module Core
+    java_import org.openhab.core.config.core.Configuration
+
+    #
+    # {Configuration} represents openHAB's {org.openhab.core.config.core.Configuration} data
+    # with the full interface of {::Hash}.
+    #
+    # All keys are converted to strings.
+    #
+    class Configuration
+      include EmulateHash
+      extend Forwardable
+
+      alias_method :to_map, :properties
+      private :to_map
+
+      # @!visibility private
+      def [](key)
+        get(key.to_s)
+      end
+
+      # @!visibility private
+      def store(key, value)
+        put(key.to_s, value)
+      end
+
+      # @!visibility private
+      def delete(key)
+        key = key.to_s
+        return yield(key) if block_given? && !key?(key)
+
+        remove(key)
+      end
+
+      # @!visibility private
+      def key?(key)
+        contains_key(key.to_s)
+      end
+
+      # @!visibility private
+      def replace(new_pairs)
+        set_properties(new_pairs.to_h.transform_keys(&:to_s))
+        self
+      end
+
+      # @!visibility private
+      alias_method :keys, :key_set
+
+      # @!visibility private
+      def dup
+        self.class.new(self)
+      end
+
+      # @!visibility private
+      def ==(other)
+        if !other.is_a?(self.class) && other.respond_to?(:to_hash)
+          return to_hash == other.to_hash.transform_keys(&:to_s)
+        end
+
+        equals(other)
+      end
+    end
+  end
+end

data/lib/openhab/core/emulate_hash.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module OpenHAB
+  module Core
+    #
+    # Make a class acts like a Ruby Hash that supports indifferent keys.
+    #
+    # Methods that accepts keys will convert symbolic keys to string keys, but only shallowly.
+    # This key indifference does not extend to Hash return values, however.
+    # Hash return values will behave like a normal Hash
+    # which treats symbolic and string keys differently.
+    #
+    # The including class must implement at least:
+    # - `#to_map` to provide the hash-like data
+    # - `#replace`
+    # - `#store`
+    # - Other methods and mutators as applicable to the underlying storage.
+    #
+    module EmulateHash
+      include Enumerable
+      extend Forwardable
+
+      # Methods delegated to to_map
+      DELEGATED_METHODS = %i[>
+                             >=
+                             <
+                             <=
+                             ==
+                             any?
+                             compact
+                             deconstruct_keys
+                             transform_keys
+                             to_hash
+                             length
+                             size
+                             compare_by_identity?
+                             each
+                             each_key
+                             each_pair
+                             each_value
+                             equals
+                             empty?
+                             filter
+                             flatten
+                             has_value?
+                             invert
+                             key
+                             keys
+                             rassoc
+                             reject
+                             select
+                             shift
+                             to_a
+                             to_h
+                             to_hash
+                             transform_keys
+                             transform_values
+                             value?
+                             values].freeze
+      private_constant :DELEGATED_METHODS
+
+      def_delegators :to_map, *DELEGATED_METHODS
+
+      def_delegator :to_h, :inspect
+
+      # @!visibility private
+      alias_method :to_s, :inspect
+
+      # @!visibility private
+      def except(*keys)
+        to_map.except(*keys.map(&:to_s))
+      end
+
+      # @!visibility private
+      def key?(key)
+        to_map.key?(key.to_s)
+      end
+      alias_method :has_key?, :key?
+      alias_method :include?, :key?
+
+      #
+      # @see https://ruby-doc.org/core/Hash.html#method-i-merge
+      #
+      # java.util.Map#merge is incompatible to Ruby's, but JRuby provides #ruby_merge for it
+      #
+      # @!visibility private
+      def merge(*others, &block)
+        return self if others.empty?
+
+        others.map! { |hash| hash.transform_keys(&:to_s) }
+        map = to_map
+        if map.respond_to?(:ruby_merge)
+          map.ruby_merge(*others, &block)
+        else
+          # fall back to #merge in case #to_map returns a Ruby Hash
+          map.merge(*others, &block)
+        end
+      end
+
+      # @!visibility private
+      def merge!(*others, &block)
+        return self if others.empty?
+
+        replace(merge(*others, &block))
+      end
+      alias_method :update, :merge!
+
+      # @!visibility private
+      def replace
+        raise NotImplementedError
+      end
+
+      # @!visibility private
+      def slice(*keys)
+        to_map.slice(*keys.map(&:to_s))
+      end
+
+      # @!visibility private
+      def fetch(key, *default, &block)
+        to_map.fetch(key.to_s, *default, &block)
+      end
+
+      # @!visibility private
+      def [](key)
+        fetch(key, nil)
+      end
+
+      # @!visibility private
+      def store(key, value)
+        raise NotImplementedError
+      end
+
+      # @!visibility private
+      def []=(key, value)
+        store(key, value)
+      end
+
+      # @!visibility private
+      def assoc(key)
+        to_map.assoc(key.to_s)
+      end
+
+      # @!visibility private
+      def clear
+        replace({})
+      end
+
+      # @!visibility private
+      def dig(key, *keys)
+        to_map.dig(key.to_s, *keys)
+      end
+
+      # @!visibility private
+      def compact!
+        to_h.compact!&.then { |r| replace(r) }
+      end
+
+      # @!visibility private
+      def delete_if(&block)
+        raise NotImplementedError unless block
+
+        replace(to_h.delete_if(&block))
+      end
+
+      # @!visibility private
+      def keep_if(&block)
+        select!(&block)
+        self
+      end
+
+      # @!visibility private
+      def select!(&block)
+        raise NotImplementedError unless block
+
+        to_h.select!(&block)&.then { |r| replace(r) }
+      end
+      alias_method :filter!, :select!
+
+      # @!visibility private
+      def reject!(&block)
+        raise NotImplementedError unless block
+
+        to_h.reject!(&block)&.then { |r| replace(r) }
+      end
+
+      # @!visibility private
+      def fetch_values(*keys, &block)
+        to_map.fetch_values(*keys.map(&:to_s), &block)
+      end
+
+      # @!visibility private
+      def transform_keys!(*args, &block)
+        replace(transform_keys(*args, &block))
+      end
+
+      # @!visibility private
+      def transform_values!(&block)
+        raise NotImplementedError unless block
+
+        replace(transform_values(&block))
+      end
+
+      # @!visibility private
+      def values_at(*keys)
+        to_map.values_at(*keys.map(&:to_s))
+      end
+
+      # @!visibility private
+      def compare_by_identity
+        raise NotImplementedError
+      end
+
+      # @!visibility private
+      def default=(*)
+        raise NotImplementedError
+      end
+
+      # @!visibility private
+      def default_proc=(*)
+        raise NotImplementedError
+      end
+
+      # @!visibility private
+      def default(*)
+        nil
+      end
+
+      # @!visibility private
+      def default_proc
+        nil
+      end
+
+      # @!visibility private
+      def to_proc
+        ->(k) { self[k] }
+      end
+    end
+  end
+end

data/lib/openhab/core/events/abstract_event.rb

@@ -12,6 +12,17 @@ module OpenHAB
 
         # @return [String]
         alias_method :inspect, :to_s
+
+        #
+        # Returns the event payload as a Hash.
+        #
+        # @return [Hash, nil] The payload object parsed by JSON. The keys are symbolized.
+        #   `nil` when the payload is empty.
+        #
+        def payload
+          require "json"
+          @payload ||= JSON.parse(get_payload, symbolize_names: true) unless get_payload.empty?
+        end
       end
     end
   end

data/lib/openhab/core/events/timer_event.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      # @deprecated OH3.4 this guard is not needed on OH4
+      if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
+        java_import org.openhab.core.automation.events.TimerEvent
+
+        #
+        # Adds methods to core openHAB TimerEvent to make it more natural in Ruby
+        #
+        # This event can be triggered by a `DateTimeTrigger`, `cron`, or `TimeOfDay` trigger.
+        #
+        # @since openHAB 4.0
+        #
+        class TimerEvent < AbstractEvent
+          #
+          # @!attribute [r] cron_expression
+          # @return [String, nil] The cron expression that triggered this event.
+          #   `nil` when this event wasn't triggered by a cron trigger.
+          #
+          def cron_expression
+            payload&.[](:cronExpression)
+          end
+
+          #
+          # @!attribute [r] item
+          # @return [Item, nil] The DateTime item that triggered this event.
+          #   `nil` when this event wasn't triggered by a DateTimeItem trigger.
+          #
+          def item
+            payload&.[](:itemName)&.then { |item_name| EntityLookup.lookup_item(item_name) }
+          end
+
+          #
+          # @!attribute [r] time
+          # @return [LocalTime, nil] The configured time for this TimeOfDay trigger event.
+          #   `nil` when this event wasn't triggered by a TimeOfDay trigger.
+          #
+          def time
+            payload&.[](:time)&.then { |time| LocalTime.parse(time) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/items/group_function.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.items.GroupFunction
+
+      #
+      # Adds `#to_s` and `#inspect` to group function.
+      #
+      # @example
+      #   # Group:SWITCH:OR(ON,OFF) Switches
+      #   logger.info "The Switches group function is: #{Switches.function}" # => "OR"
+      #   logger.info "The Switches group function: #{Switches.function.inspect}" # => "OR(ON,OFF)"
+      #
+      module GroupFunction
+        #
+        # Returns the group function as an uppercase string
+        # @return [String]
+        #
+        def to_s
+          self.class.simple_name.upcase
+        end
+
+        #
+        # Returns the group function and its parameters as a string
+        # @return [String]
+        #
+        def inspect
+          params = parameters.map(&:inspect).join(",")
+          params = "(#{params})" unless params.empty?
+          "#{self}#{params}"
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/items/group_item.rb

@@ -143,16 +143,22 @@ module OpenHAB
           base_item.format_type(command)
         end
 
+        %w[color contact date_time dimmer image location number player rollershutter string switch].each do |type|
+          type_class = type.gsub(/(^[a-z]|_[a-z])/) { |letter| letter[-1].upcase }
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{type}_item?                      # def date_time_item?
+              base_item&.is_a?(#{type_class}Item)  #   base_item&.is_a?(DateTimeItem)
+            end                                    # end
+          RUBY
+        end
+
         private
 
         # Add base type and function details
         def type_details
           r = ""
           r += ":#{base_item.type}#{base_item.__send__(:type_details)}" if base_item
-          if function && (fn = function.class.java_class.simple_name.upcase) != "EQUALITY"
-            r += ":#{fn}"
-            r += "(#{function.parameters.map(&:inspect).join(",")})" unless function.parameters.empty?
-          end
+          r += ":#{function.inspect}" if function && function.to_s != "EQUALITY"
           r
         end
 

data/lib/openhab/core/items/item.rb

@@ -18,6 +18,22 @@ module OpenHAB
           def ===(other)
             other.is_a?(self)
           end
+
+          private
+
+          # @!macro def_type_predicate
+          #   @!method $1_item?
+          #   Check if the item is a $1 item.
+          #   @note If the item is a group item, it will also return true if the base item is a $1 item.
+          #   @return [true,false]
+          def def_type_predicate(type)
+            type_class = type.to_s.gsub(/(^[a-z]|_[a-z])/) { |letter| letter[-1].upcase }
+            class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{type}_item?           # def date_time_item?
+                is_a?(#{type_class}Item)  #   is_a?(DateTimeItem)
+              end                         # end
+            RUBY
+          end
         end
 
         # @!attribute [r] name
@@ -270,6 +286,21 @@ module OpenHAB
           Provider.registry.provider_for(self)
         end
 
+        def_type_predicate(:color)
+        def_type_predicate(:contact)
+        def_type_predicate(:date_time)
+        # @note Color items are also considered dimmer items.
+        def_type_predicate(:dimmer)
+        def_type_predicate(:group)
+        def_type_predicate(:image)
+        def_type_predicate(:location)
+        def_type_predicate(:number)
+        def_type_predicate(:player)
+        def_type_predicate(:rollershutter)
+        def_type_predicate(:string)
+        # @note Color and dimmer items are also considered switch items.
+        def_type_predicate(:switch)
+
         private
 
         # Allows sub-classes to append additional details to the type in an inspect string