openhab-scripting 5.19.1 → 5.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 509b0ee1752d832802d1193b4291ccf2d1a8f28d38452d900b7b8bf5862917d8
-  data.tar.gz: c26c325f46def04c214d611ac85977b065eb4fed3f326de075431d93ec9baca5
+  metadata.gz: 04fb1ca1c7f49ca0f821111edd4c1d178066d6d0c55ce0d574efc7bf1307aa36
+  data.tar.gz: aa5005277edc1667540d6c87aee158e5dcd02095ce6633303eacaa5343ecc1b1
 SHA512:
-  metadata.gz: 612d74470204eaef6f6e2f80c42220a3a111b3b2a65b86d727f4990627ea1f734605fd50f25640dda8dad11cc22771ba73ef299e419c7e7e3e10fdb53b760d2d
-  data.tar.gz: 82bbfccf67b8895b3781504cd217b84928bca4e675223885d861865b41addbfe7259f036748d764bfec78212e01339cac26d7eb9ea908765d51a5af28fab7972
+  metadata.gz: e3c2c463868f6c9ec8f452bc8d1e0c0a5dc4c0f34243eceb4ad6661d9e52deafc04cddad3a4332c51fe039f246d0133b245f1c885b9e892f79e913f38f6c6619
+  data.tar.gz: b6e03f118796c8af22d2a6922fba92368954ba3fd15c13029b6d627c5dc9cd5f1f27507f77990545176f8bd67af588e987b780393e76090f3c49b4a663351168

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "generic_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.CallItem
+
+      #
+      #  A {CallItem} identifies a telephone call by its origin and destination.
+      #
+      # @!attribute [r] state
+      #   @return [StringListType, nil]
+      #
+      class CallItem < GenericItem
+        # @!visibility private
+        def format_type(command)
+          return command if command.is_a?(Types::StringListType)
+          return Types::StringListType.new(command.to_ary.map(&:to_s)) if command.respond_to?(:to_ary)
+
+          super
+        end
+      end
+    end
+  end
+end
+
+# @!parse CallItem = OpenHAB::Core::Items::CallItem

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

@@ -134,7 +134,9 @@ module OpenHAB
         #
         # The similar method `command!`, however, will always send the command regardless of the item's state.
         #
-        # @param [Command] command command to send to the item
+        # @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}.
         # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
         #   otherwise the item.
         #
@@ -143,6 +145,17 @@ module OpenHAB
         # @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)
           command = format_command(command)
           logger.trace "Sending Command #{command} to #{name}"
@@ -165,10 +178,27 @@ module OpenHAB
         #
         # Send an update to this item
         #
-        # @param [State] state
+        # @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}"

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

@@ -427,6 +427,7 @@ module OpenHAB
           end
         end
 
+        def_type_predicate(:call)
         def_type_predicate(:color)
         def_type_predicate(:contact)
         def_type_predicate(:date_time)

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

@@ -27,8 +27,7 @@ module OpenHAB
       #
       # @example Comparison using Quantity
       #   # Because Power_Usage has a unit, the return value
-      #   # from average_since is a QuantityType which can be
-      #   # compared against a string with quantity
+      #   # from average_since is a QuantityType
       #   if Power_Usage.average_since(15.minutes.ago) > 5 | "kW"
       #     logger.info("The power usage exceeded its 15 min average)
       #   end
@@ -429,7 +428,7 @@ module OpenHAB
         # @overload persist(timestamp, state, service = nil)
         #   Persists a state at a given timestamp
         #   @param [#to_zoned_date_time] timestamp The timestamp for the given state to be stored
-        #   @param [Types::State] state The state to be stored
+        #   @param [Types::State, #to_s] state The state to be stored
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [void]
         #   @since openHAB 4.2
@@ -508,7 +507,20 @@ module OpenHAB
         #   @see last_update
         #   @since openHAB 4.2
 
-        %i[last_update next_update].each do |method|
+        # @!method last_change(service = nil)
+        #   Returns the time the item was last changed.
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [ZonedDateTime, nil] The timestamp of the last update
+        #   @since openHAB 4.2
+
+        # @!method next_change(service = nil)
+        #   Returns the first future change time of the item.
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [ZonedDateTime, nil] The timestamp of the next update
+        #   @see last_update
+        #   @since openHAB 4.2
+
+        %i[last_update next_update last_change next_change].each do |method|
           # @deprecated OH 4.1 remove this guard when dropping OH 4.1
           next unless Actions::PersistenceExtensions.respond_to?(method)
 

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

@@ -80,7 +80,10 @@ module OpenHAB
         # @param value [#to_zoned_date_time, #to_time, #to_str, #to_d, nil]
         #
         def initialize(value = nil)
-          if value.respond_to?(:to_zoned_date_time)
+          if value.nil?
+            super()
+            return
+          elsif value.respond_to?(:to_zoned_date_time)
             super(value.to_zoned_date_time)
             return
           elsif value.respond_to?(:to_time)

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      StringListType = org.openhab.core.library.types.StringListType
+
+      # {StringListType} can be used for items that are dealing with telephony functionality.
+      #
+      # The entries can be accessed like an array.
+      #
+      # @example
+      #   string_list = StringListType.new("a", "b", "c")
+      #   logger.info "first entry: #{string_list.first}" # => "a"
+      #   logger.info "second entry: #{string_list[1]}" # => "b"
+      #   logger.info "last entry: #{string_list.last}" # => "c"
+      #   logger.info "length: #{string_list.size}" # => 3
+      #
+      class StringListType
+        extend Forwardable
+
+        field_reader :typeDetails
+
+        # @!parse include Command, State
+
+        # @!visibility private
+        def inspect
+          "#<OpenHAB::Core::Types::StringListType #{to_a.inspect}>"
+        end
+
+        # @return [Array<String>] the values as an array
+        def to_a
+          typeDetails.to_a
+        end
+
+        # @!visibility private
+        def ==(other)
+          return super if other.is_a?(StringListType)
+          return to_a == other.to_a if other.respond_to?(:to_a)
+
+          super
+        end
+
+        # any method that exists on Array gets forwarded to states
+        delegate (Array.instance_methods - instance_methods) => :to_a
+      end
+    end
+  end
+end
+
+# @!parse StringListType = OpenHAB::Core::Types::StringListType

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

@@ -18,7 +18,7 @@ module OpenHAB
       # @since openHAB 4.1
       #
       # @example
-      #   time_series = TimeSeries.new # defaults to :add policy
+      #   time_series = TimeSeries.new # defaults to :replace policy
       #                           .add(Time.at(2), DecimalType.new(2))
       #                           .add(Time.at(1), DecimalType.new(1))
       #                           .add(Time.at(3), DecimalType.new(3))

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

@@ -55,6 +55,8 @@ module OpenHAB
           end
         end
 
+        # @return [CallItem]
+        def_item_method(:call)
         # @return [ColorItem]
         def_item_method(:color)
         # @return [ContactItem]

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

@@ -1283,6 +1283,8 @@ module OpenHAB
         # @param [Object] attach Object to be attached to the trigger
         # @return [void]
         #
+        # @see at
+        #
         # @example
         #   rule "Daily" do
         #     every :day, at: '5:15'
@@ -1297,7 +1299,13 @@ module OpenHAB
         #     run { Light.on }
         #   end
         #
-        # @example
+        # @example Trigger at the time portion of a DateTime Item
+        #   rule "Every day at sunset" do
+        #     every :day, at: Sunset_Time
+        #     run { logger.info "It's getting dark" }
+        #   end
+        #
+        # @example Specific day of the week
         #   rule "Weekly" do
         #     every :monday, at: '5:15'
         #     run do
@@ -1305,7 +1313,7 @@ module OpenHAB
         #     end
         #   end
         #
-        # @example
+        # @example Symbolic interval
         #   rule "Often" do
         #     every :minute
         #     run do
@@ -1321,7 +1329,7 @@ module OpenHAB
         #     end
         #   end
         #
-        # @example
+        # @example Duration interval
         #   rule "Often" do
         #     every 5.minutes
         #     run do
@@ -1329,18 +1337,12 @@ module OpenHAB
         #     end
         #   end
         #
-        # @example
+        # @example MonthDay
         #   rule 'Every 14th of Feb at 2pm' do
         #     every '02-14', at: '2pm'
         #     run { logger.info "Happy Valentine's Day!" }
         #   end
         #
-        # @example
-        #   rule "Every day at sunset" do
-        #     every :day, at: Sunset_Time
-        #     run { logger.info "It's getting dark" }
-        #   end
-        #
         def every(value, at: nil, attach: nil)
           return every(java.time.MonthDay.parse(value), at: at, attach: attach) if value.is_a?(String)
 
@@ -1735,6 +1737,8 @@ module OpenHAB
         # @param [Item, String, Symbol] item The item (or its name)
         # @return [void]
         #
+        # @see every
+        #
         # @example
         #   rule "say hello when the kids get home from school" do
         #     at HomeFromSchool_Time

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

@@ -288,7 +288,8 @@ module OpenHAB
         # If an array is given:
         # - Scalar elements define the command, and the label is the same as the command.
         # - Array elements contain the command, label, and optional third element for the icon.
-        # - Hash elements contain the command, label, and optional icon defined by the corresponding keys.
+        # - Hash elements contain the `command`, `release` (optional), `label`, and `icon` (optional)
+        #   defined by the corresponding keys.
         #
         # @since openHAB 4.1 added support for icons
         #
@@ -314,6 +315,12 @@ module OpenHAB
         #     {command: "auto", label: "Auto"} # no icon
         #   ]
         #
+        # @example Since openHAB 4.2, `release` is also supported in the array of hashes
+        #   # when `release` is specified, `command` will be sent on press and `release` on release
+        #   switch mappings: [
+        #     {label: "On", command: ON, release: OFF, icon: "f7:power"}
+        #   ]
+        #
         # @return [Hash, Array, nil]
         # @see LinkableWidgetBuilder#switch
         # @see https://www.openhab.org/docs/ui/sitemaps.html#mappings
@@ -334,8 +341,9 @@ module OpenHAB
           widget = super
           mappings&.each do |cmd, label, icon|
             mapping = SitemapBuilder.factory.create_mapping
-            cmd, label, icon = cmd.values_at(:command, :label, :icon) if cmd.is_a?(Hash)
+            cmd, release_cmd, label, icon = cmd.values_at(:command, :release, :label, :icon) if cmd.is_a?(Hash)
             mapping.cmd = cmd.to_s
+            mapping.release_cmd = release_cmd.to_s unless release_cmd.nil?
             mapping.label = label&.to_s || cmd.to_s
             # @deprecated OH 4.1 the if check is not needed in OH4.1+
             mapping.icon = icon if icon
@@ -395,32 +403,44 @@ module OpenHAB
         # @return [true, false, nil]
         # @note This parameter only works on Android
         attr_writer :switch
+        # Only send the command when the slider is released
+        # @return [true, false, nil]
+        attr_writer :release_only
 
         # (see SetpointBuilder#initialize)
-        # @!method initialize(item: nil, label: nil, icon: nil, static_icon: nil, range: nil, step: nil, switch: nil, frequency: nil, label_color: nil, value_color: nil, icon_color: nil, visibility: nil)
+        # @!method initialize(item: nil, label: nil, icon: nil, static_icon: nil, range: nil, step: nil, switch: nil, frequency: nil, release_only: nil, label_color: nil, value_color: nil, icon_color: nil, visibility: nil)
         # @param switch [true, false, nil]
         #   A short press on the item toggles the item on or off (see {SliderBuilder#switch=})
         # @param frequency [Numeric, nil]
         #   How often to send requests (in seconds) (see {SliderBuilder#frequency})
+        # @param release_only [true, false, nil]
+        #   Only send the command when the slider is released (see {SliderBuilder#release_only=})
         # @!visibility private
-        def initialize(type, builder_proxy, switch: nil, frequency: nil, **kwargs, &block)
+        def initialize(type, builder_proxy, switch: nil, frequency: nil, release_only: nil, **kwargs, &block)
           super(type, builder_proxy, **kwargs, &block)
 
           @switch = switch
           @frequency = frequency
-          @switch_enabled = nil
+          @release_only = release_only
         end
 
         # (see #switch=)
         def switch?
-          @switch_enabled
+          @switch
+        end
+
+        # (see #release_only=)
+        def release_only?
+          @release_only
         end
 
         # @!visibility private
         def build
           widget = super
-          widget.switch_enabled = switch?
+          widget.switch_enabled = switch? unless @switch.nil?
           widget.send_frequency = (frequency * 1000).to_i if frequency
+          # @deprecated OH 4.1 remove the version check when dropping OH 4.1 support
+          widget.release_only = release_only? if OpenHAB::Core.version >= OpenHAB::Core::V4_2 && !@release_only.nil?
           widget
         end
       end
@@ -936,6 +956,7 @@ module OpenHAB
         #              step: nil,
         #              switch: nil,
         #              frequency: nil,
+        #              release_only: nil,
         #              label_color: nil,
         #              value_color: nil,
         #              icon_color: nil,

data/lib/openhab/dsl/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.19.1
+  version: 5.20.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-21 00:00:00.000000000 Z
+date: 2024-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -263,6 +263,7 @@ files:
 - lib/openhab/core/events/timer_event.rb
 - lib/openhab/core/items.rb
 - lib/openhab/core/items/accepted_data_types.rb
+- lib/openhab/core/items/call_item.rb
 - lib/openhab/core/items/color_item.rb
 - lib/openhab/core/items/contact_item.rb
 - lib/openhab/core/items/date_time_item.rb
@@ -348,6 +349,7 @@ files:
 - lib/openhab/core/types/refresh_type.rb
 - lib/openhab/core/types/rewind_fastforward_type.rb
 - lib/openhab/core/types/stop_move_type.rb
+- lib/openhab/core/types/string_list_type.rb
 - lib/openhab/core/types/string_type.rb
 - lib/openhab/core/types/time_series.rb
 - lib/openhab/core/types/type.rb
@@ -485,7 +487,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.10
+rubygems_version: 3.5.14
 signing_key: 
 specification_version: 4
 summary: JRuby Helper Libraries for openHAB Scripting