openhab-scripting 5.19.1 → 5.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 509b0ee1752d832802d1193b4291ccf2d1a8f28d38452d900b7b8bf5862917d8
-  data.tar.gz: c26c325f46def04c214d611ac85977b065eb4fed3f326de075431d93ec9baca5
+  metadata.gz: 756e126e160f646932df226702f4174537f335211766d9eba33c2d44cf1c1c70
+  data.tar.gz: 6afda8cddcc7a0fd916fe061a2eb2dab4621d46cdcef75138b4c524db05b669d
 SHA512:
-  metadata.gz: 612d74470204eaef6f6e2f80c42220a3a111b3b2a65b86d727f4990627ea1f734605fd50f25640dda8dad11cc22771ba73ef299e419c7e7e3e10fdb53b760d2d
-  data.tar.gz: 82bbfccf67b8895b3781504cd217b84928bca4e675223885d861865b41addbfe7259f036748d764bfec78212e01339cac26d7eb9ea908765d51a5af28fab7972
+  metadata.gz: c57f40667e47bacb3c2a2cc62f6fce829413cf832502e1f743cb82fbbc0e5a962800907b27261bea5513020612a8f7652378a7817aa6b0d924c88220ccca7328
+  data.tar.gz: 769878c8db809e0ed1815605551fc964de147329209e89517cab012a782b84e8a21e46fa445f3167723eea4f2454bd290a767991e39cfdb6495c742c874d295e

data/lib/openhab/core/actions.rb

@@ -51,31 +51,85 @@ module OpenHAB
       module_function
 
       #
-      # Send a notification.
+      # Send a notification using
+      # {https://next.openhab.org/addons/integrations/openhabcloud/#cloud-notification-actions
+      # openHAB Cloud Notification Action}.
       #
       # @param msg [String] The message to send.
-      # @param email [String, nil] The email address to send to. If `nil`,
-      #   the message will be broadcast.
-      # @param icon [String, Symbol, nil]
-      # @param severity [String, Symbol, nil]
+      # @param email [String, nil] The email address to send to. If `nil`, the message will be broadcast.
+      # @param icon [String, Symbol, nil] The icon name
+      #   (as described in {https://next.openhab.org/docs/configuration/items.html#icons Items}).
+      # @param severity [String, Symbol, nil] A description of the severity of the incident.
+      # @param title [String, nil] The title of the notification.
+      #   When `nil`, it defaults to `openHAB` inside the Android and iOS apps.
+      # @param on_click [String, nil] The action to be performed when the user clicks on the notification.
+      #   Specified using the {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax action syntax}.
+      # @param attachment [String, nil] The URL of the media attachment to be displayed with the notification.
+      #   This URL must be reachable by the push notification client.
+      # @param buttons [Array<String>, Hash<String, String>, nil] Buttons to include in the notification.
+      #   - In array form, each element is specified as `Title=$action`, where `$action` follows the
+      #   {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax action syntax}.
+      #   - In hash form, the keys are the button titles and the values are the actions.
+      #
+      #   The maximum number of buttons is 3.
       # @return [void]
       #
+      # @note The parameters `title`, `on_click`, `attachment`, and `buttons` were added in openHAB 4.2.
+      #
+      # @see https://www.openhab.org/addons/integrations/openhabcloud/
+      #
       # @example Send a broadcast notification via openHAB Cloud
-      #   rule 'Send an alert' do
+      #   rule "Send an alert" do
       #     changed Alarm_Triggered, to: ON
-      #     run { notify 'Red Alert!' }
+      #     run { notify "Red Alert!" }
+      #   end
+      #
+      # @example Provide action buttons in a notification
+      #   rule "Doorbell" do
+      #     changed Doorbell, to: ON
+      #     run do
+      #       notify "Someone pressed the doorbell!",
+      #         title: "Doorbell",
+      #         attachment: "http://myserver.local/cameras/frontdoor.jpg",
+      #         buttons: {
+      #           "Show Camera" => "ui:/basicui/app?w=0001&sitemap=cameras",
+      #           "Unlock Door" => "command:FrontDoor_Lock:OFF"
+      #         }
+      #     end
       #   end
       #
-      def notify(msg, email: nil, icon: nil, severity: nil)
+      def notify(
+        msg,
+        email: nil,
+        icon: nil,
+        severity: nil,
+        title: nil,
+        on_click: nil,
+        attachment: nil,
+        buttons: nil
+      )
         unless Actions.const_defined?(:NotificationAction)
           raise NotImplementedError, "NotificationAction is not available. Please install the openHAB Cloud addon."
         end
 
+        args = []
         if email
-          NotificationAction.send_notification(email.to_s, msg.to_s, icon&.to_s, severity&.to_s)
+          args.push(:send_notification, email)
         else
-          NotificationAction.send_broadcast_notification(msg.to_s, icon&.to_s, severity&.to_s)
+          args.push(:send_broadcast_notification)
         end
+        args.push(msg.to_s, icon&.to_s, severity&.to_s)
+
+        # @!deprecated OH 4.1
+        if Core.version >= Core::V4_2
+          buttons ||= []
+          buttons = buttons.map { |title, action| "#{title}=#{action}" } if buttons.is_a?(Hash)
+          raise ArgumentError, "buttons must contain (0..3) elements." unless (0..3).cover?(buttons.size)
+
+          args.push(title&.to_s, on_click&.to_s, attachment&.to_s, buttons[0]&.to_s, buttons[1]&.to_s, buttons[2]&.to_s)
+        end
+
+        NotificationAction.__send__(*args)
       end
     end
   end

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/string_type.rb

@@ -56,8 +56,7 @@ module OpenHAB
         #
         # Coerce object to a StringType
         #
-        # @param [String] other object to coerce to a
-        #   DateTimeType
+        # @param [String] other object to coerce to a StringType
         #
         # @return [[StringType, StringType], nil]
         #

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/core_ext/ruby/time.rb

@@ -92,6 +92,11 @@ class Time
     to_java(java.time.ZonedDateTime)
   end
 
+  # @return [java.time.Instant]
+  def to_instant
+    to_java(java.time.Instant)
+  end
+
   #
   # Converts to a {ZonedDateTime} if `other`
   # is also convertible to a ZonedDateTime.

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.21.0"
   end
 end

data/lib/openhab/rspec/openhab/core/actions.rb

@@ -5,10 +5,37 @@ module OpenHAB
     module Actions
       # redefine these to do nothing so that rules won't fail
 
-      module_function
+      class NotificationAction
+        class << self
+          def send_notification(
+            email,
+            msg,
+            icon,
+            severity,
+            title = nil,
+            on_click = nil,
+            attachment = nil,
+            button1 = nil,
+            button2 = nil,
+            button3 = nil
+          )
+            logger.debug("send_notification: #{email}, #{msg}, #{icon}, #{severity}, #{title}, #{on_click}, #{attachment}, #{button1}, #{button2}, #{button3}") # rubocop:disable Layout/LineLength
+          end
 
-      def notify(msg, email: nil)
-        logger.debug("notify: #{msg}")
+          def send_broadcast_notification(
+            msg,
+            icon,
+            severity,
+            title = nil,
+            on_click = nil,
+            attachment = nil,
+            button1 = nil,
+            button2 = nil,
+            button3 = nil
+          )
+            logger.debug("send_broadcast_notification: #{msg}, #{icon}, #{severity}, #{title}, #{on_click}, #{attachment}, #{button1}, #{button2}, #{button3}") # rubocop:disable Layout/LineLength
+          end
+        end
       end
 
       class Voice

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.19.1
+  version: 5.21.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-28 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