openhab-scripting 5.30.1 → 5.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93b780d352d981919615e78e687910eb11ee024c6c567a6294db4538ddd8712a
-  data.tar.gz: dbdcb9b48ee07a0d626bf8aa5ef6da60273d330395c89647dd5a360b28bc3f1c
+  metadata.gz: c429ef46e5d646b8f63faf413faba1e687c3b02eac385044c85c863e70c9fda1
+  data.tar.gz: 4b8f584ce037d55980f4277e35d9ebcf3a7b2a5b1ad14dce3b2c721d453c2af6
 SHA512:
-  metadata.gz: 12c20ab4f52a6fac707f62d004c5eb9268ca6a00a9d9490f96892530091a7da6bc812d5b729b3041a51c1567690269b91dd77e31325a826b15ba3e2d32f5a53a
-  data.tar.gz: 718e2af872273b04125d64edce10d248883654388a14ca126c12fdcdaef68ebc25032466fa0bb20963b491fccb753406c668acdb1499ec9ac1567baeb02b10ff
+  metadata.gz: d2d281ff53a48073de43d5c9e60c77a3a8b3f5abdb09ece70efdd9f55fa72e3f70a30a27474e01ec671a0c2328261d36d15ad7726a0327daa071bb8f819362f3
+  data.tar.gz: 5f897a7f16b1d20f9acc401af93b8b15b3cc8ffe7d02e67255db53ea0d5466300689f98344c11f42d362cb09f11880b85ce41f171b9921de67abee840a6e7d12

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

@@ -308,7 +308,7 @@ module OpenHAB
         end
 
         # @!attribute [rw] category
-        # The item's category.
+        # The item's category (icon).
         # @return [String]
         def category=(value)
           modify do
@@ -319,6 +319,8 @@ module OpenHAB
             set_category(value)
           end
         end
+        alias_method :icon, :category
+        alias_method :icon=, :category=
 
         # @!attribute [rw] tags
         #   The item's tags

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

@@ -53,6 +53,30 @@ module OpenHAB
           super && dimension == other.dimension
         end
 
+        # @!attribute [r] range
+        # Returns the range of values allowed for this item, as defined by its
+        # state description.
+        #
+        # If this item has a {#unit}, it will be applied to the result, returning
+        # a range of {QuantityType} instead of BigDecimal.
+        # @return [Range, nil]
+        # @note State descriptions can be provided by bindings, defined in
+        #   metadata, or theoretically come from other sources.
+        def range
+          return unless (sd = state_description)
+
+          # check if we have a unit, even if the item's metadata doesn't declare
+          # it properly
+          unit = self.unit || ((s = state) && s.is_a?(QuantityType) && s.unit)
+          min = sd.minimum&.to_d
+          max = sd.maximum&.to_d
+          return nil unless min || max
+
+          min |= unit if min && unit
+          max |= unit if max && unit
+          min..max
+        end
+
         protected
 
         # Adds the unit dimension

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

@@ -97,6 +97,35 @@ module OpenHAB
           __getobj__.members
         end
 
+        # Several methods can just return nil when it's a dummy item
+        # This helps when you're doing something like `items.locations.select {}`
+        # when items are getting created and removed in a concurrent thread to
+        # not have errors because an item disappeared
+        %i[
+          equipment
+          equipment?
+          equipment_type
+          location
+          location?
+          location_type
+          member_of?
+          point?
+          point_type
+          property_type
+          semantic?
+          semantic_type
+          tagged?
+        ].each do |m|
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{m}(*args)              # def equipment(*args)
+              target = __getobj__        #   target = __getobj__
+              return nil if target.nil?  #   return nil if target.nil?
+                                         #
+              target.#{m}(*args)         #   target.equipment(*args)
+            end                          # end
+          RUBY
+        end
+
         # @return [String]
         def to_s
           return name if __getobj__.nil?

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

@@ -12,6 +12,11 @@ module OpenHAB
       # {HSBType} is a complex type with constituents for hue, saturation and
       #  brightness and can be used for color items.
       class HSBType < PercentType
+        if OpenHAB::Core.version >= OpenHAB::Core::V4_0
+          java_import org.openhab.core.util.ColorUtil
+          private_constant :ColorUtil
+        end
+
         # @!constant BLACK
         #   @return [HSBType]
         # @!constant WHITE
@@ -96,6 +101,14 @@ module OpenHAB
 
             super(*args)
           end
+
+          # Create HSBType from a color temperature
+          # @param cct [QuantityType, Number] The color temperature (assumed in Kelvin, if not a QuantityType)
+          # @return [HSBType]
+          # @since openHAB 4.3
+          def from_cct(cct)
+            from_xy(*ColorUtil.kelvin_to_xy((cct | "K").double_value))
+          end
         end
 
         #
@@ -175,6 +188,82 @@ module OpenHAB
         # @!method to_xy
         #   Convert to the xyY values representing this object's color in CIE XY color model
         #   @return [[PercentType, PercentType, PercentType]]
+
+        # @!attribute [r] cct
+        # @return [QuantityType] The correlated color temperature in Kelvin
+        # @since openHAB 4.3
+        # @see https://en.wikipedia.org/wiki/Planckian_locus Planckian Locus
+        def cct
+          ColorUtil.xy_to_kelvin(to_xy[0..1].map { |x| x.double_value / 100 }) | "K"
+        end
+
+        # @!attribute [r] duv
+        #   The distance that this color is from the planckian locus
+        #
+        # @return [Float] The delta u, v
+        #
+        # @see planckian?
+        # @see planckian_cct
+        # @see https://en.wikipedia.org/wiki/Planckian_locus Planckian Locus
+        # @since openHAB 4.3
+        def duv
+          ColorUtil.xy_to_duv(to_xy[0..1].map { |x| x.double_value / 100 })
+        end
+
+        # Checks if this color is within a certain tolerance of the planckian locus ("white")
+        #
+        # @param [Float] duv_tolerance The maximum allowed distance from the planckian locus
+        # @param [Numeric, PercentType] maximum_saturation The maximum allowed saturation.
+        #   Some colors (bright green for example) may be close to the planckian locus,
+        #   but you don't want to treat them as "white" because they are very saturated.
+        # @return [true, false]
+        #
+        # @note The parameters and defaults for this method are subject to change in future
+        #   releases of this library, and should be considered beta. For now, the default
+        #   parameters should be sufficient to detect most colors that Apple's HomeKit color
+        #   temperature color chooser uses as planckian, without detecting most other "real"
+        #   colors as planckian.
+        # @see duv
+        # @see planckian_cct
+        # @see https://en.wikipedia.org/wiki/Planckian_locus Planckian Locus
+        # @since openHAB 4.3
+        def planckian?(duv_tolerance: 0.015, maximum_saturation: 75)
+          duv.abs < duv_tolerance && saturation < maximum_saturation
+        end
+        alias_method :white_cct?, :planckian?
+
+        # Returns the color temperature of this color _if_ it is within a certain tolerance
+        # of the planckian locus ("white"), otherwise returns `nil`.
+        #
+        # @param [Range, NumberItem] range An allowed range to additionally restrict
+        #   if the CCT should be returned. A NumberItem that represents a CCT channel
+        #   may be provided, and {NumberItem#range NumberItem#range} will be used instead. If the range
+        #   does not have units (is {QuantityType}), it is interpreted as being in Kelvin.
+        # @return [QuantityType, nil] The color temperature in Kelvin
+        #   (unless the range is in mireds; then it will be in mireds)
+        #
+        # @note Additional parameters are forwarded to {#planckian?}
+        # @see planckian?
+        # @see https://en.wikipedia.org/wiki/Planckian_locus Planckian Locus
+        # @since openHAB 4.3
+        def planckian_cct(range: nil, **kwargs)
+          return unless planckian?(**kwargs)
+
+          range = range.range if range.is_a?(NumberItem)
+          cct = self.cct
+          if range
+            range_type = range.begin || range.end
+            if !range_type.is_a?(QuantityType)
+              range = Range.new(range.begin | "K", range.end | "K")
+            elsif range_type.unit == Units::MIRED
+              cct |= Units::MIRED
+            end
+          end
+          return nil if range && !range.cover?(cct)
+
+          cct
+        end
+        alias_method :white_cct, :planckian_cct
       end
     end
   end

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

@@ -222,6 +222,24 @@ module OpenHAB
         #
         # @return [String, nil]
         attr_accessor :format
+        # The valid range for a number item
+        # @return [Range, nil]
+        attr_accessor :range
+        # The step size for a number item
+        # @return [Number, nil]
+        attr_accessor :step
+        # If the item is read-only, and does not accept commands
+        # @return [true, false, nil]
+        attr_accessor :read_only
+        alias_method :read_only?, :read_only
+        # A list of valid commands
+        # If a hash, keys are commands, and values are labels
+        # @return [Hash, Array, nil]
+        attr_accessor :command_options
+        # A list of valid states
+        # If a hash, keys are commands, and values are labels
+        # @return [Hash, Array, nil]
+        attr_accessor :state_options
         # The icon to be associated with the item
         # @return [Symbol, String, nil]
         attr_accessor :icon
@@ -321,6 +339,11 @@ module OpenHAB
                        dimension: nil,
                        unit: nil,
                        format: nil,
+                       range: nil,
+                       step: nil,
+                       read_only: nil,
+                       command_options: nil,
+                       state_options: nil,
                        icon: nil,
                        group: nil,
                        groups: nil,
@@ -358,6 +381,11 @@ module OpenHAB
           @label = label
           @dimension = dimension
           @format = format
+          @range = range
+          @step = step
+          @read_only = read_only
+          @command_options = command_options
+          @state_options = state_options
           self.unit = unit
           @icon = icon
           @groups = []
@@ -554,8 +582,9 @@ module OpenHAB
         def unit=(unit)
           @unit = unit
 
-          self.dimension ||= unit && org.openhab.core.types.util.UnitUtils.parse_unit(unit)&.then do |u|
-            org.openhab.core.types.util.UnitUtils.get_dimension_name(u)
+          if (openhab_unit = unit && org.openhab.core.types.util.UnitUtils.parse_unit(unit))
+            self.dimension ||= "Temperature" if openhab_unit == Units::MIRED
+            self.dimension ||= org.openhab.core.types.util.UnitUtils.get_dimension_name(openhab_unit)
           end
           self.format ||= unit && (if Gem::Version.new(Core::VERSION) >= Gem::Version.new("4.0.0.M3")
                                      "%s %unit%"
@@ -591,7 +620,35 @@ module OpenHAB
           end
           metadata["autoupdate"] = autoupdate.to_s unless autoupdate.nil?
           metadata["expire"] = expire if expire
-          metadata["stateDescription"] = { "pattern" => format } if format
+          if format || range || step || !read_only.nil? || state_options
+            sd = {}
+            sd["pattern"] = format if format
+            sd["min"] = range.begin&.to_d if range&.begin
+            sd["max"] = range.end&.to_d if range&.end
+            sd["step"] = step if step
+            sd["readOnly"] = read_only unless read_only.nil?
+            if state_options
+              sd["options"] = if state_options.respond_to?(:to_hash)
+                                state_options.to_hash.map { |k, v| "#{k}=#{v}" }.join(",")
+                              elsif state_options.respond_to?(:to_ary)
+                                state_options.to_ary.join(",")
+                              else
+                                state_options.to_s
+                              end
+            end
+
+            metadata["stateDescription"] = sd
+          end
+          if command_options
+            options = if command_options.respond_to?(:to_hash)
+                        command_options.to_hash.map { |k, v| "#{k}=#{v}" }.join(",")
+                      elsif command_options.respond_to?(:to_ary)
+                        command_options.to_ary.join(",")
+                      else
+                        command_options.to_s
+                      end
+            metadata["commandDescription"] = { "options" => options }
+          end
           metadata["unit"] = unit if unit
           item
         end

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

@@ -689,6 +689,33 @@ module OpenHAB
         end
       end
 
+      # Builds a `Colortemperaturepicker` element
+      # @since openHAB 4.3
+      # @see org.openhab.core.model.sitemap.sitemap.Colortemperaturepicker
+      class ColortemperaturepickerBuilder < WidgetBuilder
+        # Allowed range of the value
+        # @return [Range, nil]
+        attr_accessor :range
+
+        # (see WidgetBuilder#initialize)
+        # @!method initialize(item: nil, label: nil, icon: nil, static_icon: nil, range: nil, label_color: nil, value_color: nil, icon_color: nil, visibility: nil)
+        # @param range [Range, nil] Allowed range of the value (see {ColortemperaturepickerBuilder#range})
+        # @!visibility private
+        def initialize(type, builder_proxy, range: nil, **kwargs, &block)
+          super(type, builder_proxy, **kwargs, &block)
+
+          @range = range
+        end
+
+        # @!visibility private
+        def build
+          widget = super
+          widget.min_value = range&.begin&.to_d
+          widget.max_value = range&.end&.to_d
+          widget
+        end
+      end
+
       # Builds a `Mapview` element
       # @see https://www.openhab.org/docs/ui/sitemaps.html#element-type-mapview
       # @see org.openhab.core.model.sitemap.sitemap.Mapview
@@ -1084,6 +1111,23 @@ module OpenHAB
         #                   visibility: nil)
         #   end
         #
+        #   # (see ColortemperaturepickerBuilder#initialize)
+        #   # Create a new `Colortemperaturepicker` element.
+        #   # @since openHAB 4.3
+        #   # @yield Block executed in the context of a {ColortemperaturepickerBuilder}
+        #   # @return [ColortemperaturepickerBuilder]
+        #   # @!visibility public
+        #   def colortemperaturepicker(item: nil,
+        #                              label: nil,
+        #                              icon: nil,
+        #                              static_icon: nil,
+        #                              range: nil,
+        #                              label_color: nil,
+        #                              value_color: nil,
+        #                              icon_color: nil,
+        #                              visibility: nil)
+        #   end
+        #
         #   # (see DefaultBuilder#initialize)
         #   # Create a new `Default` element.
         #   # @yield Block executed in the context of a {DefaultBuilder}
@@ -1116,6 +1160,7 @@ module OpenHAB
            buttongrid
            setpoint
            colorpicker
+           colortemperaturepicker
            default].each do |method|
           class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{method}(*args, **kwargs, &block)                         # def frame(*args, **kwargs, &block)

data/lib/openhab/dsl/version.rb

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

data/lib/openhab/log.rb

@@ -114,7 +114,7 @@ module OpenHAB
       # @!visibility private
       def top_level_file
         caller_locations.find { |caller| caller.base_label == "<main>" }
-                        .then { |caller| cleanup_path(caller.path) }
+                        &.then { |caller| cleanup_path(caller.path) }
       end
 
       private
@@ -376,9 +376,10 @@ module OpenHAB
         return @file_logger unless (rule_uid = Thread.current[:openhab_rule_uid])
 
         rule_type = Thread.current[:openhab_rule_type]
+        top_level_file = Log.top_level_file&.then { |file| "#{file}." }
         full_id = "#{rule_type}:#{rule_uid}"
 
-        self.class.rule_loggers[full_id] ||= Logger.new("#{Logger::PREFIX}.#{Log.top_level_file}.#{rule_type}.#{rule_uid
+        self.class.rule_loggers[full_id] ||= Logger.new("#{Logger::PREFIX}.#{top_level_file}#{rule_type}.#{rule_uid
             .gsub(/[^A-Za-z0-9_.:-]/, "")}")
       end
 

data/lib/openhab/yard/html_helper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "nokogiri"
+require "uri"
 
 module OpenHAB
   module YARD

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.30.1
+  version: 5.32.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-03 00:00:00.000000000 Z
+date: 2024-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler