openhab-scripting 5.35.1 → 5.36.1

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

@@ -13,7 +13,7 @@ module OpenHAB
       class GenericItem
         # @!parse include Item
 
-        # rubocop:disable Naming/MethodName these mimic Java fields, which are
+        # rubocop:disable Naming/MethodName -- these mimic Java fields, which are
         # actually methods
         class << self
           # manually define this, since the Java side doesn't
@@ -38,24 +38,6 @@ module OpenHAB
           def ===(other)
             other.is_a?(self)
           end
-
-          # @!visibility private
-          def item_states_event_builder
-            @item_states_event_builder ||=
-              OpenHAB::OSGi.service("org.openhab.core.io.rest.sse.internal.SseItemStatesEventBuilder")&.tap do |builder|
-                m = builder.class.java_class.get_declared_method("getDisplayState", Item, java.util.Locale)
-                m.accessible = true
-                builder.instance_variable_set(:@getDisplayState, m)
-                # Disable "singleton on non-persistent Java type"
-                original_verbose = $VERBOSE
-                $VERBOSE = nil
-                def builder.get_display_state(item)
-                  @getDisplayState.invoke(self, item, nil)
-                end
-              ensure
-                $VERBOSE = original_verbose
-              end
-          end
         end
         # rubocop:enable Naming/MethodName
 
@@ -89,21 +71,6 @@ module OpenHAB
           !raw_state.is_a?(Types::UnDefType)
         end
 
-        # @!attribute [r] formatted_state
-        #
-        # Format the item's state according to its state description
-        #
-        # This may include running a transformation.
-        #
-        # @return [String] The formatted state
-        #
-        # @example
-        #   logger.info(Exterior_WindDirection.formatted_state) # => "NE (36°)"
-        #
-        def formatted_state
-          GenericItem.item_states_event_builder.get_display_state(self)
-        end
-
         #
         # @!attribute [r] state
         # @return [State, nil]
@@ -124,124 +91,6 @@ module OpenHAB
         #   Check if the item state == {UNDEF}
         #   @return [true,false]
 
-        #
-        # Send a command to this item
-        #
-        # When this method is chained after the {OpenHAB::DSL::Items::Ensure::Ensurable#ensure ensure}
-        # method, or issued inside an {OpenHAB::DSL.ensure_states ensure_states} block, or after
-        # {OpenHAB::DSL.ensure_states! ensure_states!} have been called,
-        # the command will only be sent if the item is not already in the same state.
-        #
-        # The similar method `command!`, however, will always send the command regardless of the item's state.
-        #
-        # @param [Command, #to_s] command command to send to the item.
-        #   When given a {Command} argument, it will be passed directly.
-        #   Otherwise, the result of `#to_s` will be parsed into a {Command}.
-        # @param [String, nil] source Optional string to identify what sent the event.
-        # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
-        #   otherwise the item.
-        #
-        # @see DSL::Items::TimedCommand#command Timed Command
-        # @see OpenHAB::DSL.ensure_states ensure_states
-        # @see OpenHAB::DSL.ensure_states! ensure_states!
-        # @see DSL::Items::Ensure::Ensurable#ensure ensure
-        #
-        # @example Sending a {Command} to an item
-        #   MySwitch.command(ON) # The preferred method is `MySwitch.on`
-        #   Garage_Door.command(DOWN) # The preferred method is `Garage_Door.down`
-        #   SetTemperature.command 20 | "°C"
-        #
-        # @example Sending a plain number to a {NumberItem}
-        #   SetTemperature.command(22.5) # if it accepts a DecimalType
-        #
-        # @example Sending a string to a dimensioned {NumberItem}
-        #   SetTemperature.command("22.5 °C") # The string will be parsed and converted to a QuantityType
-        #
-        def command(command, source: nil)
-          command = format_command(command)
-          logger.trace { "Sending Command #{command} to #{name}" }
-          if source
-            Events.publisher.post(Events::ItemEventFactory.create_command_event(name, command, source.to_s))
-          else
-            $events.send_command(self, command)
-          end
-          Proxy.new(self)
-        end
-        alias_method :command!, :command
-
-        # not an alias to allow easier stubbing and overriding
-        def <<(command)
-          command(command)
-        end
-
-        # @!parse alias_method :<<, :command
-
-        # @!method refresh
-        #   Send the {REFRESH} command to the item
-        #   @return [Item] `self`
-
-        #
-        # Send an update to this item
-        #
-        # @param [State, #to_s, nil] state the state to update the item.
-        #   When given a {State} argument, it will be passed directly.
-        #   Otherwise, the result of `#to_s` will be parsed into a {State} first.
-        #   If `nil` is passed, the item will be updated to {NULL}.
-        # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
-        #   otherwise the item.
-        #
-        # @example Updating to a {State}
-        #   DoorStatus.update(OPEN)
-        #   InsideTemperature.update 20 | "°C"
-        #
-        # @example Updating to {NULL}, the two following are equivalent:
-        #   DoorStatus.update(nil)
-        #   DoorStatus.update(NULL)
-        #
-        # @example Updating with a plain number
-        #   PeopleCount.update(5) # A plain NumberItem
-        #
-        # @example Updating with a string to a dimensioned {NumberItem}
-        #   InsideTemperature.update("22.5 °C") # The string will be parsed and converted to a QuantityType
-        #
-        def update(state)
-          state = format_update(state)
-          logger.trace { "Sending Update #{state} to #{name}" }
-          $events.post_update(self, state)
-          Proxy.new(self)
-        end
-        alias_method :update!, :update
-
-        # @!visibility private
-        def format_command(command)
-          command = format_type(command)
-          return command if command.is_a?(Types::Command)
-
-          command = command.to_s
-          org.openhab.core.types.TypeParser.parse_command(getAcceptedCommandTypes, command) || command
-        end
-
-        # @!visibility private
-        def format_update(state)
-          state = format_type(state)
-          return state if state.is_a?(Types::State)
-
-          state = state.to_s
-          org.openhab.core.types.TypeParser.parse_state(getAcceptedDataTypes, state) || StringType.new(state)
-        end
-
-        # formats a {Types::Type} to send to the event bus
-        # @!visibility private
-        def format_type(type)
-          # actual Type types can be sent directly without conversion
-          # make sure to use Type, because this method is used for both
-          # #update and #command
-          return type if type.is_a?(Types::Type)
-          return NULL if type.nil?
-
-          type.to_s
-        end
-
         #
         # @method time_series=(time_series)
         #   Set a new time series.
@@ -263,6 +112,7 @@ module OpenHAB
         #   knowingly and intentionally though, so an escape hatch is provided to allow runtime
         #   modifications.
         # @yield
+        # @yieldparam [Item] self The item
         # @return [Object] the block's return value
         #
         # @example Modify label and tags for an item
@@ -271,9 +121,19 @@ module OpenHAB
         #     MySwitch.tags = :labeled
         #   end
         #
+        # @example Using the block argument to access the item
+        #   MySwitch.modify do |item|
+        #     item.label = "New Label"
+        #     item.icon = :switch
+        #     item.tags = Semantics::Switch, Semantics::Light
+        #   end
+        #
         def modify(force: false)
           raise ArgumentError, "you must pass a block to modify" unless block_given?
-          return yield if instance_variable_defined?(:@modifying) && @modifying
+
+          proxied_self = Proxy.new(self)
+
+          return yield(proxied_self) if instance_variable_defined?(:@modifying) && @modifying
 
           begin
             provider = self.provider
@@ -286,7 +146,7 @@ module OpenHAB
             @modified = false
             @modifying = true
 
-            r = yield
+            r = yield(proxied_self)
 
             provider&.update(self) if @modified
             r

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

@@ -202,8 +202,8 @@ module OpenHAB
         # Command methods and predicate methods for GroupItem are performed here
         # instead of being statically defined in items.rb
         # because base_item is needed to determine the command/data types but is not available in the static context
-        ruby2_keywords def method_missing(method, *args, &block)
-          return base_item.__send__(method, *args, &block) if base_item&.respond_to?(method) # rubocop:disable Lint/RedundantSafeNavigation nil responds to :to_a
+        def method_missing(method, ...)
+          return base_item.__send__(method, ...) if base_item&.respond_to?(method) # rubocop:disable Lint/RedundantSafeNavigation -- nil responds to :to_a
 
           super
         end

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

@@ -41,11 +41,10 @@ module OpenHAB
         # @param [String] file location
         # @param [String] mime_type of image
         #
-        #
         def update_from_file(file, mime_type: nil)
           file_data = File.binread(file)
           mime_type ||= Marcel::MimeType.for(Pathname.new(file)) || Marcel::MimeType.for(file_data)
-          update_from_bytes(file_data, mime_type: mime_type)
+          update_from_bytes(file_data, mime_type:)
         end
 
         #
@@ -53,14 +52,13 @@ module OpenHAB
         #
         # @param [String] uri location of image
         #
-        #
         def update_from_url(uri)
           logger.trace { "Downloading image from #{uri}" }
           response = Net::HTTP.get_response(URI(uri))
           mime_type = response["content-type"]
           bytes = response.body
-          mime_type ||= detect_mime_from_bytes(bytes: bytes)
-          update_from_bytes(bytes, mime_type: mime_type)
+          mime_type ||= detect_mime_from_bytes(bytes:)
+          update_from_bytes(bytes, mime_type:)
         end
 
         #
@@ -69,27 +67,13 @@ module OpenHAB
         # @param [String] mime_type of image
         # @param [Object] bytes image data
         #
-        #
         def update_from_bytes(bytes, mime_type: nil)
-          mime_type ||= detect_mime_from_bytes(bytes: bytes)
-          base_64_image = encode_image(mime_type: mime_type, bytes: bytes)
-          update(base_64_image)
+          mime_type ||= detect_mime_from_bytes(bytes:)
+          update(RawType.new(bytes.to_java_bytes, mime_type))
         end
 
         private
 
-        #
-        # Encode image information in the format required by openHAB
-        #
-        # @param [String] mime_type for image
-        # @param [Object] bytes image data
-        #
-        # @return [String] openHAB image format with image data Base64 encoded
-        #
-        def encode_image(mime_type:, bytes:)
-          "data:#{mime_type};base64,#{Base64.strict_encode64(bytes)}"
-        end
-
         #
         # Detect the mime type based on bytes
         #

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

@@ -19,6 +19,24 @@ module OpenHAB
             other.is_a?(self)
           end
 
+          # @!visibility private
+          def item_states_event_builder
+            @item_states_event_builder ||=
+              OpenHAB::OSGi.service("org.openhab.core.io.rest.sse.internal.SseItemStatesEventBuilder")&.tap do |builder|
+                m = builder.class.java_class.get_declared_method("getDisplayState", Item, java.util.Locale)
+                m.accessible = true
+                builder.instance_variable_set(:@getDisplayState, m)
+                # Disable "singleton on non-persistent Java type"
+                original_verbose = $VERBOSE
+                $VERBOSE = nil
+                def builder.get_display_state(item)
+                  @getDisplayState.invoke(self, item, nil)
+                end
+              ensure
+                $VERBOSE = original_verbose
+              end
+          end
+
           private
 
           # @!macro def_type_predicate
@@ -46,6 +64,12 @@ module OpenHAB
         # @!attribute [r] accepted_data_types
         #   @return [Array<Class>] An array of {State}s that can be sent as commands to this item
 
+        # @!attribute [r] state_description
+        #   @return [Types::StateDescription, nil]
+
+        # @!attribute [r] command_description
+        #   @return [Types::CommandDescription, nil]
+
         #
         # The item's {GenericItem#label label} if one is defined, otherwise its {#name}.
         #
@@ -55,6 +79,139 @@ module OpenHAB
           label || name
         end
 
+        # @!attribute [r] formatted_state
+        #
+        # Format the item's state according to its state description
+        #
+        # This may include running a transformation.
+        #
+        # @return [String] The formatted state
+        #
+        # @example
+        #   logger.info(Exterior_WindDirection.formatted_state) # => "NE (36°)"
+        #
+        def formatted_state
+          Item.item_states_event_builder.get_display_state(self)
+        end
+
+        #
+        # Send a command to this item
+        #
+        # When this method is chained after the {OpenHAB::DSL::Items::Ensure::Ensurable#ensure ensure}
+        # method, or issued inside an {OpenHAB::DSL.ensure_states ensure_states} block, or after
+        # {OpenHAB::DSL.ensure_states! ensure_states!} have been called,
+        # the command will only be sent if the item is not already in the same state.
+        #
+        # The similar method `command!`, however, will always send the command regardless of the item's state.
+        #
+        # @param [Command, #to_s] command command to send to the item.
+        #   When given a {Command} argument, it will be passed directly.
+        #   Otherwise, the result of `#to_s` will be parsed into a {Command}.
+        # @param [String, nil] source Optional string to identify what sent the event.
+        # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
+        #   otherwise the item.
+        #
+        # @see DSL::Items::TimedCommand#command Timed Command
+        # @see OpenHAB::DSL.ensure_states ensure_states
+        # @see OpenHAB::DSL.ensure_states! ensure_states!
+        # @see DSL::Items::Ensure::Ensurable#ensure ensure
+        #
+        # @example Sending a {Command} to an item
+        #   MySwitch.command(ON) # The preferred method is `MySwitch.on`
+        #   Garage_Door.command(DOWN) # The preferred method is `Garage_Door.down`
+        #   SetTemperature.command 20 | "°C"
+        #
+        # @example Sending a plain number to a {NumberItem}
+        #   SetTemperature.command(22.5) # if it accepts a DecimalType
+        #
+        # @example Sending a string to a dimensioned {NumberItem}
+        #   SetTemperature.command("22.5 °C") # The string will be parsed and converted to a QuantityType
+        #
+        def command(command, source: nil)
+          command = format_command(command)
+          logger.trace { "Sending Command #{command} to #{name}" }
+          if source
+            Events.publisher.post(Events::ItemEventFactory.create_command_event(name, command, source.to_s))
+          else
+            $events.send_command(self, command)
+          end
+          Proxy.new(self)
+        end
+        alias_method :command!, :command
+
+        # not an alias to allow easier stubbing and overriding
+        def <<(command)
+          command(command)
+        end
+
+        # @!parse alias_method :<<, :command
+
+        # @!method refresh
+        #   Send the {REFRESH} command to the item
+        #   @return [Item] `self`
+
+        #
+        # Send an update to this item
+        #
+        # @param [State, #to_s, nil] state the state to update the item.
+        #   When given a {State} argument, it will be passed directly.
+        #   Otherwise, the result of `#to_s` will be parsed into a {State} first.
+        #   If `nil` is passed, the item will be updated to {NULL}.
+        # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
+        #   otherwise the item.
+        #
+        # @example Updating to a {State}
+        #   DoorStatus.update(OPEN)
+        #   InsideTemperature.update 20 | "°C"
+        #
+        # @example Updating to {NULL}, the two following are equivalent:
+        #   DoorStatus.update(nil)
+        #   DoorStatus.update(NULL)
+        #
+        # @example Updating with a plain number
+        #   PeopleCount.update(5) # A plain NumberItem
+        #
+        # @example Updating with a string to a dimensioned {NumberItem}
+        #   InsideTemperature.update("22.5 °C") # The string will be parsed and converted to a QuantityType
+        #
+        def update(state)
+          state = format_update(state)
+          logger.trace { "Sending Update #{state} to #{name}" }
+          $events.post_update(self, state)
+          Proxy.new(self)
+        end
+        alias_method :update!, :update
+
+        # @!visibility private
+        def format_command(command)
+          command = format_type(command)
+          return command if command.is_a?(Types::Command)
+
+          command = command.to_s
+          org.openhab.core.types.TypeParser.parse_command(getAcceptedCommandTypes, command) || command
+        end
+
+        # @!visibility private
+        def format_update(state)
+          state = format_type(state)
+          return state if state.is_a?(Types::State)
+
+          state = state.to_s
+          org.openhab.core.types.TypeParser.parse_state(getAcceptedDataTypes, state) || StringType.new(state)
+        end
+
+        # formats a {Types::Type} to send to the event bus
+        # @!visibility private
+        def format_type(type)
+          # actual Type types can be sent directly without conversion
+          # make sure to use Type, because this method is used for both
+          # #update and #command
+          return type if type.is_a?(Types::Type)
+          return NULL if type.nil?
+
+          type.to_s
+        end
+
         #
         # @!attribute [r] groups
         #
@@ -63,7 +220,7 @@ module OpenHAB
         # @return [Array<GroupItem>] All groups that this item is part of
         #
         def groups
-          group_names.map { |name| EntityLookup.lookup_item(name) }.compact
+          group_names.filter_map { |name| EntityLookup.lookup_item(name) }
         end
 
         #
@@ -79,7 +236,7 @@ module OpenHAB
           groups.map! do |group|
             group.is_a?(GroupItem) ? group.name : group
           end
-          !(group_names & groups).empty?
+          !!group_names.intersect?(groups)
         end
 
         #
@@ -239,16 +396,13 @@ module OpenHAB
         #
         def tagged?(*tags)
           tags.map! do |tag|
-            # @deprecated OH3.4
-            if tag.is_a?(Module)
-              tag.simple_name
-            elsif defined?(Semantics::SemanticTag) && tag.is_a?(Semantics::SemanticTag)
+            if tag.is_a?(Semantics::SemanticTag)
               tag.name
             else
               tag
             end
           end
-          !(self.tags.to_a & tags).empty?
+          !!self.tags.to_a.intersect?(tags)
         end
 
         # @!attribute thing [r]

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

@@ -62,7 +62,7 @@ module OpenHAB
       #   logger.info("Max power usage today: #{max}, at: #{max.timestamp})
       #
       module Persistence
-        GenericItem.prepend(self)
+        Item.prepend(self)
 
         #
         # A wrapper for {org.openhab.core.persistence.HistoricItem HistoricItem} that delegates to its state.
@@ -667,10 +667,10 @@ module OpenHAB
             method = method.to_s.dup
             suffix = method.delete_suffix!("?") && "?"
 
-            def_persistence_method("#{method}_since#{suffix}", quantify: quantify)
+            def_persistence_method("#{method}_since#{suffix}", quantify:)
             # @deprecated OH 4.1 remove if guard, keeping the content, when dropping OH 4.1
             if OpenHAB::Core.version >= OpenHAB::Core::V4_2
-              def_persistence_method("#{method}_until#{suffix}", quantify: quantify)
+              def_persistence_method("#{method}_until#{suffix}", quantify:)
             end
 
             method = "#{method}_between"
@@ -710,12 +710,10 @@ module OpenHAB
         def_persistence_methods(:minimum, quantify: true)
         def_persistence_methods(:updated?)
 
-        if OpenHAB::Core.version >= OpenHAB::Core::V4_0
-          def_persistence_methods(:get_all_states, quantify: true)
-          alias_method :all_states_since, :get_all_states_since
-          alias_method :all_states_until, :get_all_states_until if OpenHAB::Core.version >= OpenHAB::Core::V4_2
-          alias_method :all_states_between, :get_all_states_between
-        end
+        def_persistence_methods(:get_all_states, quantify: true)
+        alias_method :all_states_since, :get_all_states_since
+        alias_method :all_states_until, :get_all_states_until if OpenHAB::Core.version >= OpenHAB::Core::V4_2
+        alias_method :all_states_between, :get_all_states_between
 
         if OpenHAB::Core.version >= OpenHAB::Core::V4_2
           def_persistence_method(:persisted_state) # already quantified in core
@@ -791,7 +789,7 @@ module OpenHAB
           when org.openhab.core.persistence.HistoricItem
             PersistedState.new(result, quantify ? quantify(result.state) : nil)
           when java.util.Collection, Array
-            result.to_a.map { |historic_item| wrap_result(historic_item, quantify: quantify) }
+            result.to_a.map { |historic_item| wrap_result(historic_item, quantify:) }
           else
             return quantify(result) if quantify
 

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

@@ -27,7 +27,7 @@ module OpenHAB
         # @param [true, false] recursive
         # @return [Item, nil] The removed item, if found.
         #
-        def remove(item_name, recursive = false) # rubocop:disable Style/OptionalBooleanParameter matches Java method
+        def remove(item_name, recursive = false) # rubocop:disable Style/OptionalBooleanParameter -- matches Java method
           return nil unless @elements.key?(item_name)
 
           item = super(item_name)