openhab-scripting 5.18.1 → 5.19.1

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

@@ -57,6 +57,126 @@ module OpenHAB
           uid.to_s
         end
 
+        # @!attribute item_name [r]
+        # Return the name of the item this channel is linked to. If a channel is linked to more than one item,
+        # this method only returns the first item.
+        #
+        # @return [String, nil]
+        def item_name
+          item_names.first
+        end
+
+        # @!attribute item_names [r]
+        # Return the names of all of the items this channel is linked to.
+        #
+        # @return [Array<String>]
+        def item_names
+          Things::Links::Provider.registry.get_linked_item_names(uid)
+        end
+
+        # @!attribute item [r]
+        # Return the item this channel is linked to. If a channel is linked to more than one item,
+        # this method only returns the first item.
+        #
+        # @return [Items::Item, nil]
+        def item
+          items.first
+        end
+
+        # @!attribute items [r]
+        # Return all of the items this channel is linked to.
+        #
+        # @return [Array<Items::Item>]
+        def items
+          Things::Links::Provider.registry.get_linked_items(uid).map { |item| Items::Proxy.new(item) }
+        end
+
+        #
+        # @!attribute links [r]
+        # Returns all of the channel's links (items and link configurations).
+        #
+        # @return [Items::ItemChannelLinks] An array of ItemChannelLink or an empty array
+        #
+        # @example Get the configuration of the first link
+        #   things["mqtt:topic:livingroom-light"].channel["power"].links.first.configuration
+        #
+        # @example Remove all managed links
+        #   things["mqtt:topic:livingroom-light"].channel["power"].links.clear
+        #
+        # @see link
+        # @see unlink
+        #
+        def links
+          Items::ItemChannelLinks.new(uid, Things::Links::Provider.registry.get_links(uid))
+        end
+
+        #
+        # @return [ItemChannelLink, nil]
+        #
+        # @overload link
+        #   Returns the channel's link. If an channel is linked to more than one item,
+        #   this method only returns the first link.
+        #
+        #   @return [Things::ItemChannelLink, nil]
+        #
+        # @overload link(item, config = {})
+        #
+        #   Links the channel to an item.
+        #
+        #   @param [String, Items::Item] item The item to link to.
+        #   @param [Hash] config The configuration for the link.
+        #
+        #   @return [Things::ItemChannelLink] The created link.
+        #
+        #   @example Link a channel to an item
+        #     things["mqtt:topic:livingroom-light"].channels["power"].link(LivingRoom_Light_Power)
+        #
+        #   @example Specify a link configuration
+        #     things["mqtt:topic:outdoor-thermometer"].channels["temperature"].link(
+        #       High_Temperature_Alert,
+        #       profile: "system:hysteresis",
+        #       lower: "29 °C",
+        #       upper: "30 °C")
+        #
+        #   @see links
+        #   @see unlink
+        #
+        def link(item = nil, config = nil)
+          return Things::Links::Provider.registry.get_links(uid).first if item.nil? && config.nil?
+
+          config ||= {}
+          Core::Things::Links::Provider.create_link(item, self, 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 an item from managed link providers.
+        #
+        # @param [String, Items::Item] item The item 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(item)
+          link_to_delete = Things::Links::Provider.create_link(item, self, {})
+          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
+
         # @deprecated OH3.4 this whole section is not needed in OH4+. Also see Thing#config_eql?
         if Core.version < Core::V4_0
           # @!visibility private

data/lib/openhab/core/things/links/provider.rb

@@ -28,7 +28,8 @@ module OpenHAB
               config = Configuration.new(config.transform_keys(&:to_s))
               channel = ChannelUID.new(channel) if channel.is_a?(String)
               channel = channel.uid if channel.is_a?(Channel)
-              org.openhab.core.thing.link.ItemChannelLink.new(item.name, channel, config)
+              item = item.name if item.is_a?(Item)
+              org.openhab.core.thing.link.ItemChannelLink.new(item, channel, config)
             end
           end
 

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

@@ -992,9 +992,14 @@ module OpenHAB
         #
         # Creates a channel linked trigger
         #
+        # @param [Item, String, nil] item The item to create a trigger for. If nil, all items are matched.
+        # @param [Core::Things::Channel, Core::Things::ChannelUID, String, nil] channel
+        #   The channel to create a trigger for. If nil, all channels are matched.
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
+        # @since openHAB 4.0 Support for filtering with item and channel was added
+        #
         # @example
         #    rule "channel linked" do
         #      channel_linked
@@ -1002,9 +1007,10 @@ module OpenHAB
         #        logger.info("#{event.link.item.name} linked to #{event.link.channel_uid}.")
         #      end
         #    end
-        def channel_linked(attach: nil)
-          @ruby_triggers << [:channel_linked]
-          event("openhab/links/*/added", types: "ItemChannelLinkAddedEvent", attach: attach)
+        def channel_linked(item: nil, channel: nil, attach: nil)
+          pattern = (item.nil? && channel.nil?) ? "*" : "#{item || "*"}-#{channel || "*"}"
+          @ruby_triggers << [:channel_linked, pattern]
+          event("openhab/links/#{pattern}/added", types: "ItemChannelLinkAddedEvent", attach: attach)
         end
 
         #
@@ -1013,9 +1019,14 @@ module OpenHAB
         # Note that the item or the thing it's linked to may no longer exist,
         # so if you try to access those objects they'll be nil.
         #
+        # @param [Item, String, nil] item The item to create a trigger for. If nil, all items are matched.
+        # @param [Core::Things::Channel, Core::Things::ChannelUID, String, nil] channel
+        #   The channel to create a trigger for. If nil, all channels are matched.
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
+        # @since openHAB 4.0 Support for filtering with item and channel was added
+        #
         # @example
         #    rule "channel unlinked" do
         #      channel_unlinked
@@ -1023,9 +1034,10 @@ module OpenHAB
         #        logger.info("#{event.link.item_name} unlinked from #{event.link.channel_uid}.")
         #      end
         #    end
-        def channel_unlinked(attach: nil)
-          @ruby_triggers << [:channel_linked]
-          event("openhab/links/*/removed", types: "ItemChannelLinkRemovedEvent", attach: attach)
+        def channel_unlinked(item: nil, channel: nil, attach: nil)
+          pattern = (item.nil? && channel.nil?) ? "*" : "#{item || "*"}-#{channel || "*"}"
+          @ruby_triggers << [:channel_unlinked, pattern]
+          event("openhab/links/#{pattern}/removed", types: "ItemChannelLinkRemovedEvent", attach: attach)
         end
 
         #
@@ -1556,9 +1568,12 @@ module OpenHAB
         #
         # Creates an item added trigger
         #
+        # @param [String, nil] pattern The pattern to match items against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
+        # @since openHAB 4.0 Support for pattern filter was added
+        #
         # @example
         #    rule "item added" do
         #      item_added
@@ -1566,17 +1581,20 @@ module OpenHAB
         #        logger.info("#{event.item.name} added.")
         #      end
         #    end
-        def item_added(attach: nil)
-          @ruby_triggers << [:item_added]
-          event("openhab/items/*/added", types: "ItemAddedEvent", attach: attach)
+        def item_added(pattern = "*", attach: nil)
+          @ruby_triggers << [:item_added, pattern]
+          event("openhab/items/#{pattern}/added", types: "ItemAddedEvent", attach: attach)
         end
 
         #
         # Creates an item removed trigger
         #
+        # @param [String, nil] pattern The pattern to match items against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
+        # @since openHAB 4.0 Support for pattern filter was added
+        #
         # @example
         #    rule "item removed" do
         #      item_removed
@@ -1584,14 +1602,15 @@ module OpenHAB
         #        logger.info("#{event.item.name} removed.")
         #      end
         #    end
-        def item_removed(attach: nil)
-          @ruby_triggers << [:item_removed]
-          event("openhab/items/*/removed", types: "ItemRemovedEvent", attach: attach)
+        def item_removed(pattern = "*", attach: nil)
+          @ruby_triggers << [:item_removed, pattern]
+          event("openhab/items/#{pattern}/removed", types: "ItemRemovedEvent", attach: attach)
         end
 
         #
         # Creates an item updated trigger
         #
+        # @param [String, nil] pattern The pattern to match items against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
@@ -1603,17 +1622,20 @@ module OpenHAB
         #     end
         #   end
         #
-        def item_updated(attach: nil)
-          @ruby_triggers << [:item_updated]
-          event("openhab/items/*/updated", types: "ItemUpdatedEvent", attach: attach)
+        def item_updated(pattern = "*", attach: nil)
+          @ruby_triggers << [:item_updated, pattern]
+          event("openhab/items/#{pattern}/updated", types: "ItemUpdatedEvent", attach: attach)
         end
 
         #
         # Creates a thing added trigger
         #
+        # @param [String, nil] pattern The pattern to match things against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
+        # @since openHAB 4.0 Support for pattern filter was added
+        #
         # @example
         #    rule "thing added" do
         #      thing_added
@@ -1621,17 +1643,20 @@ module OpenHAB
         #        logger.info("#{event.thing.uid} added.")
         #      end
         #    end
-        def thing_added(attach: nil)
-          @ruby_triggers << [:thing_added]
-          event("openhab/things/*/added", types: "ThingAddedEvent", attach: attach)
+        def thing_added(pattern = "*", attach: nil)
+          @ruby_triggers << [:thing_added, pattern]
+          event("openhab/things/#{pattern}/added", types: "ThingAddedEvent", attach: attach)
         end
 
         #
         # Creates a thing removed trigger
         #
+        # @param [String, nil] pattern The pattern to match things against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
+        # @since openHAB 4.0 Support for pattern filter was added
+        #
         # @example
         #    rule "thing removed" do
         #      thing_removed
@@ -1639,17 +1664,20 @@ module OpenHAB
         #        logger.info("#{event.thing.uid} removed.")
         #      end
         #    end
-        def thing_removed(attach: nil)
-          @ruby_triggers << [:thing_removed]
-          event("openhab/things/*/removed", types: "ThingRemovedEvent", attach: attach)
+        def thing_removed(pattern = "*", attach: nil)
+          @ruby_triggers << [:thing_removed, pattern]
+          event("openhab/things/#{pattern}/removed", types: "ThingRemovedEvent", attach: attach)
         end
 
         #
         # Creates a thing updated trigger
         #
+        # @param [String, nil] pattern The pattern to match things against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
+        # @since openHAB 4.0 Support for pattern filter was added
+        #
         # @example
         #   rule "thing updated" do
         #     thing_updated
@@ -1658,9 +1686,9 @@ module OpenHAB
         #     end
         #   end
         #
-        def thing_updated(attach: nil)
-          @ruby_triggers << [:thing_updated]
-          event("openhab/things/*/updated", types: "ThingUpdatedEvent", attach: attach)
+        def thing_updated(pattern = "*", attach: nil)
+          @ruby_triggers << [:thing_updated, pattern]
+          event("openhab/things/#{pattern}/updated", types: "ThingUpdatedEvent", attach: attach)
         end
 
         #

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

@@ -737,7 +737,12 @@ module OpenHAB
         def build
           widget = super
           buttons.each do |button|
-            button_object = SitemapBuilder.factory.create_button
+            button_object = if SitemapBuilder.factory.respond_to?(:create_button_definition)
+                              SitemapBuilder.factory.create_button_definition
+                            else
+                              # @deprecated OH 4.1 in OH 4.2 this clause is not needed
+                              SitemapBuilder.factory.create_button
+                            end
             button_object.row = button[0]
             button_object.column = button[1]
             button_object.cmd = button[2]

data/lib/openhab/dsl/version.rb

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

data/lib/openhab/rspec/mocks/persistence_service.rb

@@ -28,7 +28,7 @@ module OpenHAB
           end
         end
 
-        module HistoricState
+        module PersistedState
           def timestamp
             # PersistenceExtensions uses an anonymous class to wrap the current
             # state if that happens to be an answer. Except it calls
@@ -41,7 +41,7 @@ module OpenHAB
             super
           end
         end
-        Core::Items::Persistence::HistoricState.prepend(HistoricState)
+        Core::Items::Persistence::PersistedState.prepend(PersistedState)
 
         attr_reader :id
 
@@ -54,14 +54,18 @@ module OpenHAB
           @data = Hash.new { |h, k| h[k] = [] }
         end
 
-        def store(item, date = nil, state = nil)
-          date = nil if date.is_a?(String) # alias overload
+        def store(item, date = nil, state = nil, item_alias = nil)
+          if date.is_a?(String) # alias overload
+            item_alias = date
+            date = nil
+          end
           state ||= item.state
           date ||= ZonedDateTime.now
+          item_alias ||= item.name
 
           new_item = HistoricItem.new(date, state, item.name)
 
-          item_history = @data[item.name]
+          item_history = @data[item_alias]
 
           insert_index = item_history.bsearch_index do |i|
             i.timestamp.compare_to(date).positive?
@@ -79,6 +83,7 @@ module OpenHAB
             historic_item = item_history.delete_at(index)
             @data.delete(historic_item.name) if item_history.empty?
           end
+          true
         end
 
         def query(filter)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.18.1
+  version: 5.19.1
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-04-06 00:00:00.000000000 Z
+date: 2024-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -485,7 +485,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.7
+rubygems_version: 3.5.10
 signing_key: 
 specification_version: 4
 summary: JRuby Helper Libraries for openHAB Scripting