openhab-scripting 5.7.1 → 5.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 951ad54507dbf4b297d59534c124c21bbf6f6b7a02e4c3fa967a5290aac9968e
-  data.tar.gz: d4b33c4b8cdf237c6bdc1c2b99b87459f913f2d787423f261677d469d9629df3
+  metadata.gz: 6f531c0d4e77bbee531e574b759f56e458d4eacde89520b8cf9f810dd46e61d9
+  data.tar.gz: 7724b5709c56fb80f095c14930fd3077a2019111731865f1956f4b080a8039ab
 SHA512:
-  metadata.gz: f26471513aca95dcb0266ffca7176ee57980cbea404c8290c095642c4851954e4d870232507cbea34c6b6c4a940da84d6681944ee039199c3fcc766bdd64a598
-  data.tar.gz: 0c6e9e9cf72ee4a1935c399c235256144b0c6fbbb7bc0eb3f07a81405f3e52cc0193a1856ec910212f963c37208cb29191bbe90d143bf822bfc2c987828de47d
+  metadata.gz: 11237012154342229a7b1a4b24a2e5e8f81833d758e81614b067c4a1187a598e5fbc45cfd300312ef0f039130a039e6df7c75f59e08e458d0bdf7761e2a85f8d
+  data.tar.gz: 3bd394f5d950d2ab5a0016a4219d7d1ac0cb9f4fbdca541d4f41c9e59406c01a1d0df242334cc95a4cf1668f546e1f0fc7aa03cd835f71384e4a3de4cace8304

data/lib/openhab/core/emulate_hash.rb

@@ -103,7 +103,12 @@ module OpenHAB
       def merge!(*others, &block)
         return self if others.empty?
 
-        replace(merge(*others, &block))
+        # don't call replace here so we don't touch other keys
+        others.shift.merge(*others, &block).each do |key, value|
+          value = yield key, self[key], value if key?(key) && block
+          store(key, value)
+        end
+        self
       end
       alias_method :update, :merge!
 

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

@@ -106,6 +106,9 @@ module OpenHAB
           alias_method :to_s, :inspect
         end
 
+        # @!attribute [r] function
+        # @return [GroupFunction] Returns the function of this GroupItem
+
         # Override because we want to send them to the base item if possible
         %i[command update].each do |method|
           define_method(method) do |command|
@@ -152,6 +155,19 @@ module OpenHAB
           RUBY
         end
 
+        #
+        # Compares all attributes of the item with another item.
+        #
+        # @param other [Item] The item to compare with
+        # @return [true,false] true if all attributes are equal, false otherwise
+        #
+        # @!visibility private
+        def config_eql?(other)
+          return false unless super
+
+          base_item&.type == other.base_item&.type && function&.inspect == other.function&.inspect
+        end
+
         private
 
         # Add base type and function details

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

@@ -264,12 +264,17 @@ module OpenHAB
         #
         # @return [Array<Thing>] An array of things or an empty array
         def things
-          registry = Things::Links::Provider.registry
-          channels = registry.get_bound_channels(name).to_a
-          channels.map(&:thing_uid).uniq.map { |tuid| EntityLookup.lookup_thing(tuid) }.compact
+          Things::Links::Provider.registry.get_bound_things(name).map { |thing| Things::Proxy.new(thing) }
         end
         alias_method :all_linked_things, :things
 
+        # Returns all of the item's links (channels and link configurations).
+        #
+        # @return [Array<ItemChannelLink>] An array of ItemChannelLink or an empty array
+        def links
+          Things::Links::Provider.registry.get_links(name)
+        end
+
         # @return [String]
         def inspect
           s = "#<OpenHAB::Core::Items::#{type}Item#{type_details} #{name} #{label.inspect} state=#{raw_state.inspect}"
@@ -281,11 +286,28 @@ module OpenHAB
           "#{s}>"
         end
 
-        # @return [org.openhab.core.common.registry.Provider]
+        # @return [org.openhab.core.common.registry.Provider, nil]
         def provider
           Provider.registry.provider_for(self)
         end
 
+        #
+        # Compares all attributes except metadata and channels/links of the item with another item.
+        #
+        # @param other [Item] The item to compare with
+        # @return [true,false] true if all attributes are equal, false otherwise
+        #
+        # @!visibility private
+        def config_eql?(other)
+          # GenericItem#equals checks whether other has the same name and class
+          return false unless equals(other)
+
+          %i[label category tags group_names].all? do |method|
+            # Don't use #send here. It is defined in GenericItem for sending commands
+            public_send(method) == other.public_send(method)
+          end
+        end
+
         def_type_predicate(:color)
         def_type_predicate(:contact)
         def_type_predicate(:date_time)

data/lib/openhab/core/items/metadata/hash.rb

@@ -13,6 +13,11 @@ module OpenHAB
         #
         # All keys are converted to strings.
         #
+        # As a special case, a #== comparison can be done against a [value, config] array.
+        # @example
+        #   MyItem.metadata[:namespace] = "value", { key: "value" }
+        #   MyItem.metadata[:namespace] == ["value", { "key" => "value" }] #=> true
+        #
         # @!attribute [rw] value
         #   @return [String] The main value for the metadata namespace.
         # @!attribute [r] namespace
@@ -88,7 +93,7 @@ module OpenHAB
             return unless attached?
 
             javaify
-            provider.update(@metadata)
+            provider!.update(@metadata)
           end
 
           # @!visibility private
@@ -96,12 +101,12 @@ module OpenHAB
             return unless attached?
 
             javaify
-            (p = provider).get(uid) ? p.update(@metadata) : p.add(@metadata)
+            (p = provider!).get(uid) ? p.update(@metadata) : p.add(@metadata)
           end
 
           # @!visibility private
           def remove
-            provider.remove(uid)
+            provider!.remove(uid)
           end
 
           # @!visibility private
@@ -149,6 +154,8 @@ module OpenHAB
               return configuration == other.configuration
             elsif value.empty? && other.respond_to?(:to_hash)
               return configuration == other.to_hash
+            elsif other.is_a?(Array)
+              return other == [value, configuration]
             end
             false
           end
@@ -213,12 +220,17 @@ module OpenHAB
             [value, to_h].inspect
           end
 
+          # @return [org.openhab.core.common.registry.Provider, nil]
+          def provider
+            Provider.registry.provider_for(uid)
+          end
+
           #
           # @raise [FrozenError] if the provider is not a
           #   {org.openhab.core.common.registry.ManagedProvider ManagedProvider} that can be updated.
           # @return [org.openhab.core.common.registry.ManagedProvider]
           #
-          def provider
+          def provider!
             preferred_provider = Provider.current(
               Thread.current[:openhab_providers]&.dig(:metadata_items, uid.item_name) ||
                 Thread.current[:openhab_providers]&.dig(:metadata_namespaces, uid.namespace),
@@ -226,10 +238,10 @@ module OpenHAB
             )
 
             if attached?
-              provider = Provider.registry.provider_for(uid)
+              provider = self.provider
               return preferred_provider unless provider
 
-              unless provider.is_a?(org.openhab.core.common.registry.ManagedProvider)
+              unless provider.is_a?(ManagedProvider)
                 raise FrozenError, "Cannot modify metadata from provider #{provider.inspect} for #{uid}."
               end
 

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

@@ -48,6 +48,11 @@ module OpenHAB
           super
         end
 
+        # @!visibility private
+        def config_eql?(other)
+          super && dimension == other.dimension
+        end
+
         protected
 
         # Adds the unit dimension

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

@@ -45,13 +45,19 @@ module OpenHAB
         # Enter the Item Builder DSL.
         #
         # @param (see Core::Provider.current)
+        # @param update [true, false]  Update existing items with the same name.
+        #   When false, an error will be raised if an item with the same name already exists.
         # @yield Block executed in the context of a {DSL::Items::Builder}
         # @return [Object] The return value of the block.
+        # @raise [ArgumentError] if an item with the same name already exists and `update` is false.
+        # @raise [FrozenError] if `update` is true but the existing item with the same name
+        #   wasn't created by the current provider.
         #
         # @see DSL::Items::Builder
         #
-        def build(preferred_provider = nil, &block)
-          DSL::Items::BaseBuilderDSL.new(preferred_provider).instance_eval_with_dummy_items(&block)
+        def build(preferred_provider = nil, update: true, &block)
+          DSL::Items::BaseBuilderDSL.new(preferred_provider, update: update)
+                                    .instance_eval_with_dummy_items(&block)
         end
 
         #

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

@@ -311,9 +311,14 @@ module OpenHAB
               synonyms = Array.wrap(synonyms).map { |s| s.to_s.strip }
 
               tags.map do |name, parent|
-                parent = lookup(parent) unless parent.is_a?(SemanticTag)
+                unless parent.is_a?(SemanticTag)
+                  parent_tag = lookup(parent)
+                  raise ArgumentError, "Unknown parent: #{parent}" unless parent_tag
+
+                  parent = parent_tag
+                end
+
                 next if lookup(name)
-                next unless parent
 
                 new_tag = org.openhab.core.semantics.SemanticTagImpl.new("#{parent.uid}_#{name}",
                                                                          label,
@@ -323,6 +328,44 @@ module OpenHAB
                 lookup(name)
               end.compact
             end
+
+            #
+            # Removes custom semantic tags.
+            #
+            # @param [SemanticTag, String, Symbol] tags Custom Semantic Tags to remove.
+            #   The built in Semantic Tags cannot be removed.
+            # @param [true, false] recursive Remove all children of the given tags.
+            #
+            # @return [Array<SemanticTag>] An array of tags successfully removed.
+            # @raise [ArgumentError] if any of the tags have children
+            # @raise [FrozenError] if any of the tags are not custom tags
+            #
+            # @since openHAB 4.0
+            #
+            def remove(*tags, recursive: false)
+              tags.flat_map do |tag|
+                tag = lookup(tag) unless tag.is_a?(SemanticTag)
+                next unless tag
+
+                provider = Provider.registry.provider_for(tag)
+                unless provider.is_a?(ManagedProvider)
+                  raise FrozenError, "Cannot remove item #{tag} from non-managed provider #{provider.inspect}"
+                end
+
+                children = []
+                Provider.registry.providers.grep(ManagedProvider).each do |managed_provider|
+                  managed_provider.all.each do |existing_tag|
+                    next unless existing_tag.parent_uid == tag.uid
+                    raise ArgumentError, "Cannot remove #{tag} because it has children" unless recursive
+
+                    children += remove(existing_tag, recursive: recursive)
+                  end
+                end
+
+                remove_const(tag.name) if provider.remove(tag.uid) && const_defined?(tag.name)
+                [tag] + children
+              end.compact
+            end
           end
         end
 

data/lib/openhab/core/registry.rb

@@ -20,12 +20,20 @@ module OpenHAB
       def provider_for(key)
         elementReadLock.lock
         if key.is_a?(org.openhab.core.common.registry.Identifiable)
-          element = key
-        else
-          return nil unless (element = identifierToElement[key])
-        end
+          return unless (provider = elementToProvider[key])
+
+          # The HashMap lookup above uses java's hashCode() which has been overridden
+          # by GenericItem and ThingImpl to return object's uid, e.g. item's name, thing uid
+          # so it will return a provider even for an unmanaged object having the same uid
+          # as an existing managed object.
 
-        elementToProvider[element]
+          # So take an extra step to verify that the provider really holds the given instance.
+          # by using equal? to compare the object's identity.
+          # Only ManagedProviders have a #get method to look up the object by uid.
+          provider if !provider.is_a?(ManagedProvider) || provider.get(key.uid).equal?(key)
+        elsif (element = identifierToElement[key])
+          elementToProvider[element]
+        end
       ensure
         elementReadLock.unlock
       end

data/lib/openhab/core/sitemaps/provider.rb

@@ -57,6 +57,7 @@ module OpenHAB
         #
         # Enter the Sitemap Builder DSL.
         #
+        # @param update [true, false]  When true, existing sitemaps with the same name will be updated.
         # @yield Block executed in the context of a {DSL::Sitemaps::Builder}
         # @return [void]
         #
@@ -82,8 +83,8 @@ module OpenHAB
         #     end
         #   end
         #
-        def build(&block)
-          DSL::Sitemaps::Builder.new(self).instance_eval(&block)
+        def build(update: true, &block)
+          DSL::Sitemaps::Builder.new(self, update: update).instance_eval(&block)
         end
         # rubocop:enable Layout/LineLength
 
@@ -123,7 +124,7 @@ module OpenHAB
           @listeners.each { |l| l.model_changed(element.name, org.openhab.core.model.core.EventType::REMOVED) }
         end
 
-        def notify_listeners_about_updated_element(element)
+        def notify_listeners_about_updated_element(_old_element, element)
           @listeners.each { |l| l.model_changed(element.name, org.openhab.core.model.core.EventType::MODIFIED) }
         end
       end

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/links/provider.rb

@@ -24,13 +24,11 @@ module OpenHAB
             end
 
             # @!visibility private
-            def link(item, channel, config = {})
+            def create_link(item, channel, config = {})
               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)
-              link = org.openhab.core.thing.link.ItemChannelLink.new(item.name, channel, config)
-
-              current.add(link)
+              org.openhab.core.thing.link.ItemChannelLink.new(item.name, channel, config)
             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/registry.rb

@@ -39,11 +39,17 @@ module OpenHAB
         #
         # Enter the Thing Builder DSL.
         # @param (see Core::Provider.current)
+        # @param update [true, false]
+        #   When true, existing things with the same name will be redefined if they're different.
+        #   When false, an error will be raised if a thing with the same uid already exists.
         # @yield Block executed in the context of a {DSL::Things::Builder}.
         # @return [Object] The result of the block.
+        # @raise [ArgumentError] if a thing with the same uid already exists and `update` is false.
+        # @raise [FrozenError] if `update` is true but the existing thing with the same uid
+        #   wasn't created by the current provider.
         #
-        def build(preferred_provider = nil, &block)
-          DSL::Things::Builder.new(preferred_provider).instance_eval(&block)
+        def build(preferred_provider = nil, update: true, &block)
+          DSL::Things::Builder.new(preferred_provider, update: update).instance_eval(&block)
         end
 
         #

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

@@ -35,7 +35,7 @@ module OpenHAB
       #   @return [org.openhab.core.thing.ThingStatus]
       #
       # @!attribute [r] channels
-      #   @return [ChannelArray]
+      #   @return [ChannelsArray]
       #
       # @!attribute [r] uid
       #   Return the UID.
@@ -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
@@ -174,6 +178,11 @@ module OpenHAB
           uid.to_s
         end
 
+        # @return [org.openhab.core.common.registry.Provider, nil]
+        def provider
+          Provider.registry.provider_for(uid)
+        end
+
         #
         # Fetches the actions available for this thing.
         #
@@ -192,6 +201,18 @@ module OpenHAB
           $actions.get(scope || uid.binding_id, uid.to_s)
         end
 
+        #
+        # Compares all attributes of the thing with another thing.
+        #
+        # @param other [Thing] The thing to compare with
+        # @return [true,false] true if all attributes are equal, false otherwise
+        #
+        def config_eql?(other)
+          # @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
+
         #
         # Delegate missing methods to the thing's default actions scope.
         #

data/lib/openhab/core/types/point_type.rb

@@ -80,19 +80,19 @@ module OpenHAB
         # @!attribute [r] latitude
         # @return [QuantityType]
         def latitude
-          QuantityType.new(raw_latitude.to_big_decimal, SIUnits::DEGREE_ANGLE)
+          QuantityType.new(raw_latitude.to_big_decimal, Units::DEGREE_ANGLE)
         end
 
         # @!attribute [r] longitude
         # @return [QuantityType]
         def longitude
-          QuantityType.new(raw_longitude.to_big_decimal, SIUnits::DEGREE_ANGLE)
+          QuantityType.new(raw_longitude.to_big_decimal, Units::DEGREE_ANGLE)
         end
 
         # @!attribute [r] altitude
         # @return [QuantityType]
         def altitude
-          QuantityType.new(raw_altitude.to_big_decimal, Units::METRE)
+          QuantityType.new(raw_altitude.to_big_decimal, SIUnits::METRE)
         end
 
         #

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

@@ -118,23 +118,68 @@ module OpenHAB
         class ProviderWrapper
           attr_reader :provider
 
-          def initialize(provider)
+          def initialize(provider, update:)
             @provider = provider
+            @update = update
           end
 
           # @!visibility private
           def add(builder)
-            item = builder.build
-            provider.add(item)
+            if DSL.items.key?(builder.name)
+              raise ArgumentError, "Item #{builder.name} already exists" unless @update
+
+              # Use provider.get because openHAB's ManagedProvider does not support the #[] method.
+              unless (old_item = provider.get(builder.name))
+                raise FrozenError, "Item #{builder.name} is managed by #{DSL.items[builder.name].provider}"
+              end
+
+              item = builder.build
+              if item.config_eql?(old_item)
+                logger.debug { "Not replacing existing item #{item.uid} because it is identical" }
+                item = old_item
+              else
+                logger.debug { "Replacing existing item #{item.uid} because it is not identical" }
+                provider.update(item)
+              end
+              item.metadata.merge!(builder.metadata)
+              item.metadata
+                  .reject { |namespace, _| builder.metadata.key?(namespace) }
+                  .each do |namespace, metadata|
+                item.metadata.delete(namespace) if metadata.provider == Core::Items::Metadata::Provider.current
+              end
+            else
+              item = builder.build
+              item.metadata.merge!(builder.metadata)
+              provider.add(item)
+            end
+
+            item.update(builder.state) unless builder.state.nil?
+
             # make sure to add the item to the registry before linking it
-            builder.channels.each do |(channel, config)|
+            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?(":") &&
                  (group = builder.groups.find { |g| g.is_a?(GroupItemBuilder) && g.thing })
                 thing = group.thing
                 channel = "#{thing}:#{channel}"
               end
-              Core::Things::Links::Provider.link(item, channel, config)
+
+              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
+            end
+
+            # remove links not in the new item
+            provider.all.each do |link|
+              provider.remove(link.uid) if link.item_name == item.name && !channel_uids.include?(link.linked_uid)
             end
+
             item
           end
         end
@@ -143,13 +188,15 @@ module OpenHAB
         # @return [org.openhab.core.items.ItemProvider]
         attr_reader :provider
 
-        def initialize(provider)
-          @provider = ProviderWrapper.new(Core::Items::Provider.current(provider))
+        def initialize(provider, update:)
+          @provider = ProviderWrapper.new(Core::Items::Provider.current(provider), update: update)
         end
       end
 
       # The ItemBuilder DSL allows you to customize an Item
       class ItemBuilder
+        include Core::EntityLookup
+
         # The type of this item
         # @example
         #   type #=> :switch
@@ -181,7 +228,7 @@ module OpenHAB
         # @return [String, nil]
         attr_accessor :format
         # The icon to be associated with the item
-        # @return [Symbol, nil]
+        # @return [Symbol, String, nil]
         attr_accessor :icon
         # Groups to which this item should be added
         # @return [Array<String, GroupItem>]
@@ -237,10 +284,11 @@ module OpenHAB
           end
         end
 
-        # @param dimension [Symbol, nil] The unit dimension for a {NumberItem} (see {ItemBuilder#dimension})
+        # @param dimension [Symbol, String, nil] The unit dimension for a {NumberItem} (see {ItemBuilder#dimension})
+        #   Note the dimension must be properly capitalized.
         # @param unit [Symbol, String, nil] The unit for a {NumberItem} (see {ItemBuilder#unit})
         # @param format [String, nil] The formatting pattern for the item's state (see {ItemBuilder#format})
-        # @param icon [Symbol, nil] The icon to be associated with the item (see {ItemBuilder#icon})
+        # @param icon [Symbol, String, nil] The icon to be associated with the item (see {ItemBuilder#icon})
         # @param group [String,
         #   GroupItem,
         #   GroupItemBuilder,
@@ -259,9 +307,10 @@ module OpenHAB
         #        Fluent alias for `tag`.
         # @param autoupdate [true, false, nil] Autoupdate setting (see {ItemBuilder#autoupdate})
         # @param thing [String, Core::Things::Thing, Core::Things::ThingUID, nil]
-        #   A Thing to be used as the base for the channel
-        # @param channel [String, Core::Things::ChannelUID, nil] Channel to link the item to
-        # @param expire [String] An expiration specification.
+        #   A Thing to be used as the base for the channel.
+        # @param channel [String, Symbol, Core::Things::ChannelUID, Core::Things::Channel, nil]
+        #   Channel to link the item to (see {ItemBuilder#channel}).
+        # @param expire [String] An expiration specification (see {ItemBuilder#expire}).
         # @param alexa [String, Symbol, Array<(String, Hash<String, Object>)>, nil]
         #   Alexa metadata (see {ItemBuilder#alexa})
         # @param ga [String, Symbol, Array<(String, Hash<String, Object>)>, nil]
@@ -292,7 +341,16 @@ module OpenHAB
                        metadata: nil,
                        state: nil)
           raise ArgumentError, "`name` cannot be nil" if name.nil?
-          raise ArgumentError, "`dimension` can only be specified with NumberItem" if dimension && type != :number
+
+          if dimension
+            raise ArgumentError, "`dimension` can only be specified with NumberItem" unless type == :number
+
+            begin
+              org.openhab.core.types.util.UnitUtils.parse_dimension(dimension.to_s)
+            rescue java.lang.IllegalArgumentException
+              raise ArgumentError, "Invalid dimension '#{dimension}'"
+            end
+          end
 
           name = name.name if name.respond_to?(:name)
           if provider.is_a?(GroupItemBuilder)
@@ -413,6 +471,8 @@ module OpenHAB
         #
         # Add a channel link to this item.
         #
+        # @param channel [String, Symbol, Core::Things::ChannelUID, Core::Things::Channel]
+        #   Channel to link the item to. When thing is set, this can be a relative channel name.
         # @param config [Hash] Additional configuration, such as profile
         # @return [void]
         #
@@ -423,16 +483,27 @@ module OpenHAB
         #     end
         #   end
         #
+        # @example Relative channel name
+        #   items.build do
+        #     switch_item Bedroom_Light, thing: "mqtt:topic:bedroom-light", channel: :power
+        #   end
+        #
         def channel(channel, config = {})
+          channel = channel.to_s
           channel = "#{@thing}:#{channel}" if @thing && !channel.include?(":")
           @channels << [channel, config]
         end
 
         #
-        # @!method expire(command: nil, state: nil)
+        # @!method expire(duration, command: nil, state: nil, ignore_state_updates: nil, ignore_commands: nil)
         #
         # Configure item expiration
         #
+        # @param duration [String, Duration, nil] Duration after which the command or state should be applied
+        # @param command [String, nil] Command to send on expiration
+        # @param state [String, nil] State to set on expiration
+        # @param ignore_state_updates [true, false] When true, state updates will not reset the expire timer
+        # @param ignore_commands [true, false] When true, commands will not reset the expire timer
         # @return [void]
         #
         # @example Get the current expire setting
@@ -448,7 +519,12 @@ module OpenHAB
         #   expire 5.minutes, state: NULL
         # @example Send a command on expiration
         #   expire 5.minutes, command: OFF
-        def expire(*args, command: nil, state: nil)
+        # @example Specify the duration and command in the same string
+        #   expire "5h,command=OFF"
+        # @example Set the expire configuration
+        #   expire 5.minutes, ignore_state_updates: true
+        #
+        def expire(*args, command: nil, state: nil, ignore_state_updates: nil, ignore_commands: nil)
           unless (0..2).cover?(args.length)
             raise ArgumentError,
                   "wrong number of arguments (given #{args.length}, expected 0..2)"
@@ -463,9 +539,14 @@ module OpenHAB
 
           duration = duration.to_s[2..].downcase if duration.is_a?(Duration)
           state = "'#{state}'" if state.respond_to?(:to_str) && type == :string
-          @expire = duration
-          @expire += ",state=#{state}" if state
-          @expire += ",command=#{command}" if command
+
+          value = duration
+          value += ",state=#{state}" if state
+          value += ",command=#{command}" if command
+
+          config = { ignoreStateUpdates: ignore_state_updates, ignoreCommands: ignore_commands }
+          config.compact!
+          @expire = [value, config]
         end
 
         # @!attribute [w] unit
@@ -513,12 +594,10 @@ module OpenHAB
           tags.each do |tag|
             item.add_tag(tag)
           end
-          item.metadata.merge!(metadata)
-          item.metadata["autoupdate"] = autoupdate.to_s unless autoupdate.nil?
-          item.metadata["expire"] = expire if expire
-          item.metadata["stateDescription"] = { "pattern" => format } if format
-          item.metadata["unit"] = unit if unit
-          item.state = item.format_update(state) unless state.nil?
+          metadata["autoupdate"] = autoupdate.to_s unless autoupdate.nil?
+          metadata["expire"] = expire if expire
+          metadata["stateDescription"] = { "pattern" => format } if format
+          metadata["unit"] = unit if unit
           item
         end
 
@@ -567,7 +646,7 @@ module OpenHAB
 
           class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{m}(*args, groups: nil, **kwargs)  # def dimmer_item(*args, groups: nil, **kwargs)
-              groups ||= []                         #   groups ||= []
+              groups = Array.wrap(groups)           #   groups = Array.wrap(groups)
               groups << self                        #   groups << self
               super                                 #   super
             end                                     # end

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

@@ -12,8 +12,9 @@ module OpenHAB
       # Base sitemap builder DSL
       class Builder
         # @!visibility private
-        def initialize(provider)
+        def initialize(provider, update:)
           @provider = provider
+          @update = update
         end
 
         # (see SitemapBuilder#initialize)
@@ -23,8 +24,12 @@ module OpenHAB
         def sitemap(name, label = nil, icon: nil, &block)
           sitemap = SitemapBuilder.new(name, label, icon: icon)
           sitemap.instance_eval_with_dummy_items(&block) if block
-          @provider.add(sitemap.build)
-          sitemap
+          sitemap = sitemap.build
+          if @update && @provider.get(sitemap.uid)
+            @provider.update(sitemap)
+          else
+            @provider.add(sitemap)
+          end
         end
       end
 

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

@@ -22,7 +22,7 @@ module OpenHAB
       #     payloadNotAvailable: "offline"
       #   }
       #   things.build do
-      #     thing("mqtt:topic:my-switch", "My Switch", bridge: "mqtt:bridge:mosquitto", config: thing_config) do
+      #     thing("mqtt:topic:my-switch", "My Switch", bridge: "mqtt:broker:mosquitto", config: thing_config) do
       #       channel("switch1", "switch", config: {
       #         stateTopic: "stat/my-switch/switch1/state", commandTopic: "cmnd/my-switch/switch1/command"
       #       })
@@ -40,8 +40,9 @@ module OpenHAB
         # @return [org.openhab.core.thing.ManagedThingProvider]
         attr_reader :provider
 
-        def initialize(provider)
+        def initialize(provider, update: false)
           @provider = Core::Things::Provider.current(provider)
+          @update = update
         end
 
         # Create a new Bridge
@@ -61,10 +62,27 @@ module OpenHAB
         def build(klass, *args, **kwargs, &block)
           builder = klass.new(*args, **kwargs)
           builder.instance_eval(&block) if block
-          thing = provider.add(builder.build)
-          thing = Core::Things::Proxy.new(thing)
+          thing = builder.build
+
+          if DSL.things.key?(thing.uid)
+            raise ArgumentError, "Thing #{thing.uid} already exists" unless @update
+
+            unless (old_thing = provider.get(thing.uid))
+              raise FrozenError, "Thing #{thing.uid} is managed by #{thing.provider}"
+            end
+
+            if thing.config_eql?(old_thing)
+              logger.debug { "Not replacing existing thing #{thing.uid}" }
+              thing = old_thing
+            else
+              provider.update(thing)
+            end
+          else
+            provider.add(thing)
+          end
           thing.enable(enabled: builder.enabled) unless builder.enabled.nil?
-          thing
+
+          Core::Things::Proxy.new(thing)
         end
       end
 
@@ -176,10 +194,11 @@ module OpenHAB
 
         # Add an explicitly configured channel to this item
         # @see ChannelBuilder#initialize
+        # @return [Core::Things::Channel]
         def channel(*args, **kwargs, &block)
           channel = ChannelBuilder.new(*args, thing: self, **kwargs)
           channel.instance_eval(&block) if block
-          @channels << channel.build
+          channel.build.tap { |c| @channels << c }
         end
 
         # @!visibility private
@@ -195,6 +214,7 @@ module OpenHAB
           builder = org.openhab.core.thing.binding.builder.ThingBuilder
                        .create(thing_type_uid, uid)
                        .with_label(label)
+                       .with_location(location)
                        .with_configuration(configuration)
                        .with_bridge(bridge_uid)
                        .with_channels(channels)
@@ -209,9 +229,7 @@ module OpenHAB
             builder.with_properties(thing_type.properties)
           end
 
-          thing = builder.build
-          Core::Things.manager.set_enabled(uid, enabled) unless enabled.nil?
-          thing
+          builder.build
         end
 
         private
@@ -239,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
@@ -251,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
@@ -274,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
@@ -282,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.7.1"
+    VERSION = "5.9.0"
   end
 end

data/lib/openhab/log.rb

@@ -2,6 +2,8 @@
 
 require "forwardable"
 
+$ctx ||= nil
+
 module OpenHAB
   # rubocop:disable Layout/LineLength
 
@@ -83,8 +85,8 @@ module OpenHAB
         when String
           name = object
         when :main
-          name = "#{Logger::PREFIX}.#{rules_file.tr_s(":", "_")
-                                   .gsub(/[^A-Za-z0-9_.-]/, "")}"
+          name = "#{Logger::PREFIX}.#{rules_file.tr_s(":", "_").gsub(/[^A-Za-z0-9_.-]/, "")}"
+          name = "#{name}.#{$ctx["ruleUID"]}" if $ctx&.key?("ruleUID")
           return @loggers[name] ||= BiLogger.new(Logger.new(name))
         end
 

data/lib/openhab/rspec/helpers.rb

@@ -231,14 +231,6 @@ module OpenHAB
 
         rs = OSGi.service("org.openhab.core.service.ReadyService")
 
-        # Add a fake automation:scriptEngineFactories to satisfy startlevel 30
-        begin
-          sef_marker = org.openhab.core.automation.module.script.internal.ScriptEngineFactoryBundleTracker::READY_MARKER
-          rs.mark_ready(sef_marker)
-        rescue NameError
-          # @deprecated OH3.4 NOOP - the ScriptEngineFactoryBundleTracker doesn't exist in OH3
-        end
-
         # wait for the rule engine
         filter = org.openhab.core.service.ReadyMarkerFilter.new
                     .with_type(org.openhab.core.service.StartLevelService::STARTLEVEL_MARKER_TYPE)

data/lib/openhab/rspec/karaf.rb

@@ -327,6 +327,7 @@ module OpenHAB
         org.openhab.core.io.monitor
         org.openhab.core.io.rest
         org.openhab.core.io.rest.sse
+        org.eclipse.jetty.http2.hpack
       ].freeze
       private_constant :ALLOWED_BUNDLES
 
@@ -742,6 +743,8 @@ module OpenHAB
 
         startlevels = File.read(config_file)
         startlevels.sub!(",rules:refresh,rules:dslprovider", "")
+        startlevels.sub!(",automation:scriptEngineFactories", "") # since OH4
+        startlevels.sub!("dsl:rules,", "") # since OH41-snapshot
 
         target_file = "#{oh_userdata}/services.cfg"
         target_file_contents = File.read(target_file) if File.exist?(target_file)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.7.1
+  version: 5.9.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-18 00:00:00.000000000 Z
+date: 2023-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler