openhab-scripting 5.8.0 → 5.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00dfdfae614d0fc89c09ddfe86b16c4d0b41e94bc1c2e73889eb359ff09ada3c
-  data.tar.gz: ecafc5d2f33cf0b0015ac9e8c59449a57488e4f18316bd584e8dfe028d5ec4c7
+  metadata.gz: acf8ae7ed285c32bb11070e6ae64c54b9687dae7883c272be4a9ad30f399ed8c
+  data.tar.gz: 8820ac3849f07734843d2863ff483fbde70bfe56c41981f2d48ec2e8c7bd73a8
 SHA512:
-  metadata.gz: eff4e5471afb074c92cd7d3fc01d9070a80db680ed79c4814dc8b88e14eb67c8f9215a77f80c6b1a9a5eb6f4e220b6ce5e38ba01f0287779821db918f81c0fef
-  data.tar.gz: f187e831d86e87fe4a2e91b311f8bdd3c4e046e9107054ff74c91cdf7644d4fa303d86d8abf3c5f80e8e8cb1762f5c436b89e3e841a86ef05af351c6f0d6abbb
+  metadata.gz: ab2e153c20c4d81b4b4b5b7d3025d1f49812099ea1040eba85b03f6fc8ce4217d84a3204e1c0917ed53c8386220b25da7d1da4bc367b51459ef74d67a52d7d44
+  data.tar.gz: 0bdc096799e02f344f7d24c218af6ed045840c9a87ab890e81a339896801c53c6e18a6dabafd060e2c18023b69da8fdb4df9d3d58fcab3917baba6274fe992eb

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

@@ -10,6 +10,9 @@ module OpenHAB
         # @return [Object]
         attr_accessor :attachment
 
+        # @return [Hash]
+        attr_accessor :inputs
+
         # @return [String]
         alias_method :inspect, :to_s
 

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

@@ -16,6 +16,25 @@ module OpenHAB
         def item
           EntityLookup.lookup_item(item_name)
         end
+
+        #
+        # @!attribute [r] group
+        #
+        # Returns the group item whose member had triggered this event.
+        #
+        # This is the equivalent of openHAB's `triggeringGroup`, and it is only available
+        # on a member-of-group trigger.
+        #
+        # @return [Item,nil] The group item whose member had triggered this event.
+        #   `nil` when the event wasn't triggered by a member-of-group trigger.
+        #
+        # @since openHAB 4.0 for file-based rules
+        # @since openHAB 4.1 for UI rules
+        #
+        def group
+          triggering_group = inputs&.[]("triggeringGroup") || $ctx&.[]("triggeringGroup")
+          Items::Proxy.new(triggering_group) if triggering_group
+        end
       end
     end
   end

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

@@ -251,6 +251,7 @@ module OpenHAB
           !(self.tags.to_a & tags).empty?
         end
 
+        # @!attribute thing [r]
         # Return the item's thing if this item is linked with a thing. If an item is linked to more than one thing,
         # this method only returns the first thing.
         #
@@ -260,6 +261,7 @@ module OpenHAB
         end
         alias_method :linked_thing, :thing
 
+        # @!attribute things [r]
         # Returns all of the item's linked things.
         #
         # @return [Array<Thing>] An array of things or an empty array
@@ -268,11 +270,80 @@ module OpenHAB
         end
         alias_method :all_linked_things, :things
 
+        #
+        # @!attribute links [r]
         # Returns all of the item's links (channels and link configurations).
         #
-        # @return [Array<ItemChannelLink>] An array of ItemChannelLink or an empty array
+        # @return [ItemChannelLinks] An array of ItemChannelLink or an empty array
+        #
+        # @example Get the configuration of the first link
+        #   LivingRoom_Light_Power.links.first.configuration
+        #
+        # @example Remove all managed links
+        #   LivingRoom_Light_Power.links.clear
+        #
+        # @see link
+        # @see unlink
+        #
         def links
-          Things::Links::Provider.registry.get_links(name)
+          ItemChannelLinks.new(self, Things::Links::Provider.registry.get_links(name))
+        end
+
+        #
+        # Links the item to a channel.
+        #
+        # @param [String, Things::Channel, Things::ChannelUID] channel The channel to link to.
+        # @param [Hash] config The configuration for the link.
+        #
+        # @return [Things::ItemChannelLink] The created link.
+        #
+        # @example Link an item to a channel
+        #   LivingRoom_Light_Power.link("mqtt:topic:livingroom-light:power")
+        #
+        # @example Link to a Thing's channel
+        #   LivingRoom_Light_Power.link(things["mqtt:topic:livingroom-light"].channels["power"])
+        #
+        # @example Specify a link configuration
+        #   High_Temperature_Alert.link(
+        #     "mqtt:topic:outdoor-thermometer:temperature",
+        #     profile: "system:hysteresis",
+        #     lower: "29 °C",
+        #     upper: "30 °C")
+        #
+        # @see links
+        # @see unlink
+        #
+        def link(channel, config = {})
+          Core::Things::Links::Provider.create_link(self, channel, config).tap do |new_link|
+            provider = Core::Things::Links::Provider.current
+            if !(current_link = provider.get(new_link.uid))
+              provider.add(new_link)
+            elsif current_link.configuration != config
+              provider.update(new_link)
+            end
+          end
+        end
+
+        #
+        # Removes a link to a channel from managed link providers.
+        #
+        # @param [String, Things::Channel, Things::ChannelUID] channel The channel to remove the link to.
+        #
+        # @return [Things::ItemChannelLink, nil] The removed link, if found.
+        # @raise [FrozenError] if the link is not managed by a managed link provider.
+        #
+        # @see link
+        # @see links
+        #
+        def unlink(channel)
+          link_to_delete = Things::Links::Provider.create_link(self, channel, {})
+          provider = Things::Links::Provider.registry.provider_for(link_to_delete.uid)
+          unless provider.is_a?(ManagedProvider)
+            raise FrozenError,
+                  "Cannot remove the link #{link_to_delete.uid} from non-managed provider #{provider.inspect}"
+          end
+
+          provider.remove(link_to_delete.uid)
         end
 
         # @return [String]
@@ -286,7 +357,8 @@ module OpenHAB
           "#{s}>"
         end
 
-        # @return [org.openhab.core.common.registry.Provider, nil]
+        # @!attribute provider [r]
+        # @return [org.openhab.core.common.registry.Provider, nil] Returns the provider for this item.
         def provider
           Provider.registry.provider_for(self)
         end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module OpenHAB
+  module Core
+    module Items
+      #
+      # A wrapper for {Item#links} delegated to Set<{org.openhab.core.thing.link.ItemChannelLink}>.
+      #
+      # Adds methods for clearing item's links to channels.
+      #
+      class ItemChannelLinks < SimpleDelegator
+        #
+        # @param [Item] item The item that the links belong to
+        # @param [Set<ItemChannelLink>] links The set of links to delegate to
+        #
+        # @!visibility private
+        def initialize(item, links)
+          super(links)
+          @item = item
+        end
+
+        #
+        # Removes all links to channels from managed link providers.
+        # @return [self]
+        #
+        def clear
+          Things::Links::Provider.registry.all.each do |link|
+            next unless link.item_name == @item.name
+
+            provider = Things::Links::Provider.registry.provider_for(link.uid)
+            if provider.is_a?(ManagedProvider)
+              provider.remove(link.uid)
+            else
+              logger.warn("Cannot remove the link #{link.uid} from non-managed provider #{provider.inspect}")
+            end
+          end
+          self
+        end
+      end
+    end
+  end
+end

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

@@ -311,6 +311,11 @@ module OpenHAB
               synonyms = Array.wrap(synonyms).map { |s| s.to_s.strip }
 
               tags.map do |name, parent|
+                if (existing_tag = lookup(name))
+                  logger.warn("Tag already exists: #{existing_tag.inspect}")
+                  next
+                end
+
                 unless parent.is_a?(SemanticTag)
                   parent_tag = lookup(parent)
                   raise ArgumentError, "Unknown parent: #{parent}" unless parent_tag
@@ -318,8 +323,6 @@ module OpenHAB
                   parent = parent_tag
                 end
 
-                next if lookup(name)
-
                 new_tag = org.openhab.core.semantics.SemanticTagImpl.new("#{parent.uid}_#{name}",
                                                                          label,
                                                                          description,

data/lib/openhab/core/things/channel.rb

@@ -32,9 +32,14 @@ module OpenHAB
         def inspect
           r = "#<OpenHAB::Core::Things::Channel #{uid}"
           r += " #{label.inspect}" if label
-          r += " auto_update_policy=#{auto_update_policy}" if auto_update_policy
+          r += " description=#{description.inspect}" if description
+          r += " kind=#{kind.inspect}"
+          r += " channel_type_uid=#{channel_type_uid.inspect}" if channel_type_uid
           r += " configuration=#{configuration.properties.to_h}" unless configuration.properties.empty?
           r += " properties=#{properties.to_h}" unless properties.empty?
+          r += " default_tags=#{default_tags.to_a}" unless default_tags.empty?
+          r += " auto_update_policy=#{auto_update_policy}" if auto_update_policy
+          r += " accepted_item_type=#{accepted_item_type}" if accepted_item_type
           "#{r}>"
         end
 
@@ -42,6 +47,34 @@ module OpenHAB
         def to_s
           uid.to_s
         end
+
+        # @deprecated OH3.4 this whole section is not needed in OH4+. Also see Thing#config_eql?
+        if Gem::Version.new(Core::VERSION) < Gem::Version.new("4.0.0")
+          # @!visibility private
+          module ChannelComparable
+            # @!visibility private
+            # This is only needed in OH3 because it is implemented in OH4 core
+            def ==(other)
+              return true if equal?(other)
+              return false unless other.is_a?(Channel)
+
+              %i[class
+                 uid
+                 label
+                 description
+                 kind
+                 channel_type_uid
+                 configuration
+                 properties
+                 default_tags
+                 auto_update_policy
+                 accepted_item_type].all? do |attr|
+                send(attr) == other.send(attr)
+              end
+            end
+          end
+          org.openhab.core.thing.binding.builder.ChannelBuilder.const_get(:ChannelImpl).prepend(ChannelComparable)
+        end
       end
     end
   end

data/lib/openhab/core/things/channel_uid.rb

@@ -42,8 +42,7 @@ module OpenHAB
         # @return [Array<Item>] An array of things or an empty array
         #
         def items
-          registry = OSGi.service("org.openhab.core.thing.link.ItemChannelLinkRegistry")
-          registry.get_linked_items(self).map { |i| Items::Proxy.new(i) }
+          Links::Provider.registry.get_linked_items(self).map { |i| Items::Proxy.new(i) }
         end
       end
     end

data/lib/openhab/core/things/item_channel_link.rb

@@ -26,6 +26,12 @@ module OpenHAB
           DSL.items[item_name]
         end
 
+        # @!attribute [r] channel
+        # @return [Channel]
+        def channel
+          DSL.things[linked_uid.thing_uid].channels[linked_uid.id]
+        end
+
         alias_method :channel_uid, :linked_uid
       end
     end

data/lib/openhab/core/things/profile_callback.rb

@@ -8,44 +8,37 @@ module OpenHAB
       # and channels.
       #
       module ProfileCallback
-        class << self
-          #
-          # Wraps the parent class's method to format non-Types.
-          #
-          # @!macro def_state_parsing_method
-          #   @!method $1($2)
-          #   @return [void]
-          # @!visibility private
-          def def_state_parsing_method(method, param_name)
-            class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              def #{method}(type)                                                             # def handle_command(type)
-                type = link.item.format_#{(param_name == :state) ? :update : param_name}(type)  #   type = link.item.format_command(type)
-                super(type)                                                                   #   super(type)
-              end                                                                             # end
-            RUBY
-          end
-        end
-
         #
         # Forward the given command to the respective thing handler.
         #
         # @param [Command] command
         #
-        def_state_parsing_method(:handle_command, :command)
+        def handle_command(command)
+          @dummy_channel_item ||= DSL::Items::ItemBuilder.item_factory.create_item(link.channel.accepted_item_type,
+                                                                                   "")
+          command = @dummy_channel_item.format_command(command)
+          super(command)
+        end
 
         #
         # Send a command to the framework.
         #
         # @param [Command] command
         #
-        def_state_parsing_method(:send_command, :command)
+        def send_command(command)
+          command = link.item.format_command(command)
+          super(command)
+        end
 
         #
         # Send a state update to the framework.
         #
         # @param [State] state
         #
-        def_state_parsing_method(:send_update, :state)
+        def send_update(state)
+          state = link.item.format_update(state)
+          super(state)
+        end
       end
     end
   end

data/lib/openhab/core/things/proxy.rb

@@ -29,7 +29,7 @@ module OpenHAB
         #
         # @return [Array] channels
         def channels
-          Thing::ChannelsArray.new(super.to_a)
+          Thing::ChannelsArray.new(self, super.to_a)
         end
 
         #

data/lib/openhab/core/things/thing.rb

@@ -64,13 +64,17 @@ module OpenHAB
         # Array wrapper class to allow searching a list of channels
         # by channel id
         class ChannelsArray < Array
+          def initialize(thing, array)
+            super(array)
+            @thing = thing
+          end
+
           # Allows indexing by both integer as an array or channel id acting like a hash.
-          # @param [Integer, String] index Numeric index or string channel id to search for.
+          # @param [Integer, String, ChannelUID] index
+          #   Numeric index, string channel id, or a {ChannelUID} to search for.
           def [](index)
-            if index.respond_to?(:to_str)
-              key = index.to_str
-              return find { |channel| channel.uid.id == key }
-            end
+            return @thing.get_channel(index) if index.is_a?(ChannelUID)
+            return @thing.get_channel(index.to_str) if index.respond_to?(:to_str)
 
             super
           end
@@ -204,7 +208,9 @@ module OpenHAB
         # @return [true,false] true if all attributes are equal, false otherwise
         #
         def config_eql?(other)
-          %i[uid label channels bridge_uid location configuration].all? { |method| send(method) == other.send(method) }
+          # @deprecated OH3.4 - in OH4, channels can be included in the array and do not need to be compared separately
+          channels.to_a == other.channels.to_a &&
+            %i[uid label bridge_uid location configuration].all? { |method| send(method) == other.send(method) }
         end
 
         #

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

@@ -156,7 +156,6 @@ module OpenHAB
             item.update(builder.state) unless builder.state.nil?
 
             # make sure to add the item to the registry before linking it
-            provider = Core::Things::Links::Provider.current
             channel_uids = builder.channels.to_set do |(channel, config)|
               # fill in partial channel names from group's thing id
               if !channel.include?(":") &&
@@ -165,17 +164,11 @@ module OpenHAB
                 channel = "#{thing}:#{channel}"
               end
 
-              new_link = Core::Things::Links::Provider.create_link(item, channel, config)
-              if !(current_link = provider.get(new_link.uid))
-                provider.add(new_link)
-              elsif current_link.configuration != config
-                provider.update(new_link)
-              end
-
-              new_link.linked_uid
+              item.link(channel, config).linked_uid
             end
 
             # remove links not in the new item
+            provider = Core::Things::Links::Provider.current
             provider.all.each do |link|
               provider.remove(link.uid) if link.item_name == item.name && !channel_uids.include?(link.linked_uid)
             end

data/lib/openhab/dsl/rules/automation_rule.rb

@@ -149,6 +149,8 @@ module OpenHAB
             end
 
             event.attachment = attachment
+            # events that are not from AbstractEvent do not have inputs
+            event.inputs = inputs if event.respond_to?(:inputs=)
             return event
           end
 

data/lib/openhab/dsl/things/builder.rb

@@ -257,7 +257,14 @@ module OpenHAB
       # The ChannelBuilder DSL allows you to customize a channel
       class ChannelBuilder
         attr_accessor :label
-        attr_reader :uid, :config, :type
+        attr_reader :uid,
+                    :config,
+                    :type,
+                    :default_tags,
+                    :properties,
+                    :description,
+                    :auto_update_policy,
+                    :accepted_item_type
 
         #
         # Constructor for ChannelBuilder
@@ -269,10 +276,27 @@ module OpenHAB
         # @param [String] label The channel label.
         # @param [thing] thing The thing associated with this channel.
         #   This parameter is not needed for the {ThingBuilder#channel} method.
+        # @param [String] description The channel description.
         # @param [String] group The group name.
         # @param [Hash] config Channel configuration. The keys can be strings or symbols.
+        # @param [Hash] properties The channel properties.
+        # @param [String,Symbol,Semantics::Tag,Array<String,Symbol,Semantics::Tag>] default_tags
+        #   The default tags for this channel.
+        # @param [:default, :recommend, :veto, org.openhab.core.thing.type.AutoUpdatePolicy] auto_update_policy
+        #   The channel's auto update policy.
+        # @param [String] accepted_item_type The accepted item type.
         #
-        def initialize(uid, type, label = nil, thing:, group: nil, config: {})
+        def initialize(uid,
+                       type,
+                       label = nil,
+                       thing:,
+                       description: nil,
+                       group: nil,
+                       config: nil,
+                       properties: nil,
+                       default_tags: nil,
+                       auto_update_policy: nil,
+                       accepted_item_type: nil)
           @thing = thing
 
           uid = uid.to_s
@@ -292,7 +316,14 @@ module OpenHAB
           end
           @type = type
           @label = label
-          @config = config.transform_keys(&:to_s)
+          @config = config&.transform_keys(&:to_s)
+          @default_tags = Items::ItemBuilder.normalize_tags(*Array.wrap(default_tags))
+          @properties = properties&.transform_keys(&:to_s)
+          @description = description
+          @accepted_item_type = accepted_item_type
+          return unless auto_update_policy
+
+          @auto_update_policy = org.openhab.core.thing.type.AutoUpdatePolicy.value_of(auto_update_policy.to_s.upcase)
         end
 
         # @!visibility private
@@ -300,7 +331,15 @@ module OpenHAB
           org.openhab.core.thing.binding.builder.ChannelBuilder.create(uid)
              .with_kind(kind)
              .with_type(type)
-             .with_configuration(Core::Configuration.new(config))
+             .tap do |builder|
+               builder.with_label(label) if label
+               builder.with_configuration(Core::Configuration.new(config)) if config && !config.empty?
+               builder.with_default_tags(Set.new(default_tags).to_java) unless default_tags.empty?
+               builder.with_properties(properties) if properties
+               builder.with_description(description) if description
+               builder.with_auto_update_policy(auto_update_policy) if auto_update_policy
+               builder.with_accepted_item_type(accepted_item_type) if accepted_item_type
+             end
              .build
         end
 

data/lib/openhab/dsl/version.rb

@@ -4,6 +4,6 @@ module OpenHAB
   module DSL
     # Version of openHAB helper libraries
     # @return [String]
-    VERSION = "5.8.0"
+    VERSION = "5.10.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.8.0
+  version: 5.10.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-07 00:00:00.000000000 Z
+date: 2023-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -409,6 +409,7 @@ files:
 - lib/openhab/core/items/group_item.rb
 - lib/openhab/core/items/image_item.rb
 - lib/openhab/core/items/item.rb
+- lib/openhab/core/items/item_channel_links.rb
 - lib/openhab/core/items/location_item.rb
 - lib/openhab/core/items/metadata.rb
 - lib/openhab/core/items/metadata/hash.rb