openhab-scripting 4.47.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0d253f88db8dde6ae683a6254556a6e2334a5ec16525933a9b9267c214f9876
-  data.tar.gz: 05d0a09395d4c05b96aa2fab929c277273c8259e3fb6a29000223790f81e5dd0
+  metadata.gz: a2826f669c876cc9b59863c2107bc8b1af62327d22c4551ef062f1b7bc97aabb
+  data.tar.gz: 61bd119ddc94019361d0150ed8bc1e92b5b42de9f610599f1305fbf04055cb14
 SHA512:
-  metadata.gz: 6f6e4741a565c54b2d8d76b5c46ad9069308466b9befa388b89dcd37e1dce54e3dc40a8a7eba019bd750c1073a5202f07ef7750f413de35748f797a628e6575e
-  data.tar.gz: 4d6e55b63e80d8db94fe6d51b16df1596335701f13f8badc4168893e4b3dd953a217f91ed424559cc7fe1873dc521907054c82e8e73d413b0944c88771d30428
+  metadata.gz: 0bf813e7b4aba75c75979c05fc317982dfb1ca94b0eae9de656ed342b1861b293ebb8912ed7935ba709b90506a169be6013b92278281ab4dafdb3205e215f927
+  data.tar.gz: 74a35427271bcae3fd179c3ffd1710f145457e8ae1010481b27310aa28bf710c359f784c6893ed630f2737f1f029c43b7c5f925ceed7cb119239c7cfe77a77e7

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      # @see https://www.openhab.org/docs/configuration/multimedia.html#actions-2 Audio Actions
+      class Audio
+        class << self
+          #
+          # Play an audio file via openHAB sound service, Audio.playSound()
+          #
+          # @param filename [String] The sound file to play
+          # @param sink [String] Specify a particular sink to output the speech
+          # @param volume [PercentType] Specify the volume for the speech
+          #
+          # @return [void]
+          #
+          # @example Play an audio file
+          #   rule 'Play an audio file' do
+          #     every :hour
+          #     run { Audio.play_sound "beep.mp3", volume: 100 }
+          #   end
+          #
+          def play_sound(filename, sink: nil, volume: nil)
+            volume = PercentType.new(volume) unless volume.is_a?(PercentType) || volume.nil?
+            playSound(sink&.to_s, filename.to_s, volume)
+          end
+
+          #
+          # Play an audio stream from an URL to the given sink(s). Set url to nil if streaming should be stopped
+          #
+          # @param [String] url The URL of the audio stream
+          # @param [String] sink The audio sink, or nil to use the default audio sink
+          #
+          # @return [void]
+          #
+          # @example Play an audio stream
+          #   Audio.play_stream 'example.com'
+          #
+          def play_stream(url, sink: nil)
+            playStream(sink&.to_s, url)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      # @see CoreExt::Ephemeris
+      class Ephemeris
+        class << self
+          #
+          # Human readable name of the given holiday
+          #
+          # @param [Symbol, #holiday, nil] holiday
+          # @return [String, nil]
+          #
+          # @example
+          #   Ephemeris.holiday_name(Date.today) # => "Christmas"
+          #   Ephemeris.holiday_name(:christmas) # => "Christmas"
+          #
+          def holiday_name(holiday)
+            holiday = holiday.holiday if holiday.respond_to?(:holiday)
+            return nil if holiday.nil?
+
+            ::Ephemeris.get_holiday_description(to_holiday_property_key(holiday))
+          end
+
+          private
+
+          def to_holiday_property_key(holiday)
+            holiday = holiday.to_s
+            return holiday.upcase unless holiday.include?(".")
+
+            religion, holiday = holiday.split(/\.([^.]*)$/)
+            :"#{religion}.#{holiday.upcase}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      # @see https://www.openhab.org/docs/configuration/actions.html#exec-actions Exec Actions
+      class Exec # rubocop:disable Lint/EmptyClass
+        # @!scope class
+
+        # @!method execute_command_line
+        #
+        # @return [void]
+        #
+        # @overload execute_command_line(command_line)
+        #
+        #   Executes a command on the command line without waiting for the
+        #   command to complete.
+        #
+        #   @param [String] command_line
+        #   @return [void]
+        #
+        #   @example Execute an external command
+        #     rule 'Run a command' do
+        #       every :day
+        #       run do
+        #         Exec.execute_command_line('/bin/true')
+        #       end
+        #     end
+        #
+        # @overload execute_command_line(timeout, command_line)
+        #
+        #   Executes a command on the command and waits timeout seconds for
+        #   the command to complete, returning the output from the command
+        #   as a String.
+        #
+        #   @param [Duration] timeout
+        #   @param [String] command_line
+        #   @return [String]
+        #
+        #   @example Execute an external command and process its results
+        #     rule 'Run a command' do
+        #       every :day
+        #       run do
+        #         TodaysHoliday_String.update(Exec.execute_command_line(5.seconds, '/home/cody/determine_holiday.rb')
+        #       end
+        #     end
+        #
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      # @see https://www.openhab.org/docs/configuration/actions.html#http-actions HTTP Actions
+      class HTTP
+        class << self
+          #
+          # Sends an HTTP GET request and returns the result as a String.
+          #
+          # @param [String] url
+          # @param [Hash<String, String>] headers
+          # @param [Duration, int, nil] timeout Timeout (in milliseconds, if given as an Integer)
+          # @return [String] the response body
+          # @return [nil] if an error occurred
+          #
+          def send_http_get_request(url, headers: {}, timeout: nil)
+            timeout ||= 5_000
+            timeout = timeout.to_millis if timeout.is_a?(Duration)
+
+            sendHttpGetRequest(url, headers, timeout)
+          end
+
+          #
+          # Sends an HTTP PUT request and returns the result as a String.
+          #
+          # @param [String] url
+          # @param [String] content_type
+          # @param [String] content
+          # @param [Hash<String, String>] headers
+          # @param [Duration, int, nil] timeout Timeout (in milliseconds, if given as an Integer)
+          # @return [String] the response body
+          # @return [nil] if an error occurred
+          #
+          def send_http_put_request(url, content_type = nil, content = nil, headers: {}, timeout: nil)
+            timeout ||= 1_000
+            timeout = timeout.to_millis if timeout.is_a?(Duration)
+
+            sendHttpPutRequest(url, content_type, content, headers, timeout)
+          end
+
+          #
+          # Sends an HTTP POST request and returns the result as a String.
+          #
+          # @param [String] url
+          # @param [String] content_type
+          # @param [String] content
+          # @param [Hash<String, String>] headers
+          # @param [Duration, int, nil] timeout Timeout (in milliseconds, if given as an Integer)
+          # @return [String] the response body
+          # @return [nil] if an error occurred
+          #
+          def send_http_post_request(url, content_type = nil, content = nil, headers: {}, timeout: nil)
+            timeout ||= 1_000
+            timeout = timeout.to_millis if timeout.is_a?(Duration)
+
+            sendHttpPostRequest(url, content_type, content, headers, timeout)
+          end
+
+          #
+          # Sends an HTTP DELETE request and returns the result as a String.
+          #
+          # @param [String] url
+          # @param [Hash<String, String>] headers
+          # @param [Duration, int, nil] timeout Timeout (in milliseconds, if given as an Integer)
+          # @return [String] the response body
+          # @return [nil] if an error occurred
+          #
+          def send_http_delete_request(url, headers: {}, timeout: nil)
+            timeout ||= 1_000
+            timeout = timeout.to_millis if timeout.is_a?(Duration)
+
+            sendHttpDeleteRequest(url, headers, timeout)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      # @see org.openhab.core.model.script.actions.Ping
+      class Ping
+        class << self
+          #
+          # Checks the vitality of host.
+          #
+          # If port is `nil`, a regular ping is issued. If other ports are
+          # specified we try to open a new Socket with the given timeout.
+          #
+          # @param [String] host
+          # @param [int, nil] port
+          # @param [Duration, Integer, nil] timeout Connect timeout (in milliseconds, if given as an Integer)
+          # @return [true, false]
+          #
+          def check_vitality(host, port = nil, timeout = nil)
+            port ||= 0
+            timeout ||= 0
+            timeout = timeout.to_millis if timeout.is_a?(Duration)
+            checkVitality(host, port, timeout)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      # @see org.openhab.core.transform.actions.Transformation
+      class Transformation
+        class << self
+          # @!visibility private
+          alias_method :raw_transform, :transform if instance_methods.include?(:transform)
+
+          #
+          # Applies a transformation of a given type with some function to a value.
+          #
+          # @param [String, Symbol] type The transformation type, e.g. REGEX
+          #   or MAP
+          # @param [String, Symbol] function The function to call. This value depends
+          #   on the transformation type
+          # @param [String] value The value to apply the transformation to
+          # @return [String] the transformed value, or the original value if an error occurred
+          #
+          # @example Run a transformation
+          #   transform(:map, "myfan.map", 0)
+          #
+          def transform(type, function, value)
+            raw_transform(type.to_s.upcase, function.to_s, value.to_s)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      # @see https://www.openhab.org/docs/configuration/multimedia.html#actions-3 Voice Actions
+      class Voice
+        class << self
+          # @!visibility private
+          alias_method :raw_say, :say if instance_methods.include?(:say)
+
+          #
+          # Say text via openHAB Text-To-Speech service, Voice.say()
+          #
+          # @param text [String] The text to say
+          # @param voice [String] Specify a particular voice to use
+          # @param sink [String] Specify a particular sink to output the speech
+          # @param volume [PercentType] Specify the volume for the speech
+          #
+          # @return [void]
+          #
+          # @example Run the TTS engine and output to the default audio sink.
+          #   rule 'Say the time every hour' do
+          #     every :hour
+          #     run { Voice.say "The time is #{TimeOfDay.now}" }
+          #   end
+          #
+          def say(text, voice: nil, sink: nil, volume: nil)
+            volume = PercentType.new(volume) unless volume.is_a?(PercentType) || volume.nil?
+            raw_say(text.to_s, voice&.to_s, sink&.to_s, volume)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/actions.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    #
+    # Access to global actions.
+    #
+    # All openHAB's actions including those provided by add-ons are available, notably:
+    # * {Audio}
+    # * {CoreExt::Ephemeris Ephemeris}
+    # * {Exec}
+    # * {HTTP}
+    # * {Items::Persistence PersistenceExtensions}
+    # * {Ping}
+    # * {Items::Semantics Semantics}
+    # * {Transformation}
+    # * {Voice}
+    #
+    # From add-ons, e.g.:
+    # * NotificationAction (from
+    #   [openHAB Cloud Connector](https://www.openhab.org/addons/integrations/openhabcloud/);
+    #   see {notify notify})
+    #
+    # Thing-specific actions can be accessed from the {Things::Thing Thing} object.
+    # See {Things::Thing#actions Thing#actions}.
+    #
+    module Actions
+      OSGi.services("org.openhab.core.model.script.engine.action.ActionService")&.each do |service|
+        action_class = service.action_class
+        module_name = action_class.simple_name
+        action = if action_class.interface?
+                   impl = OSGi.service(action_class)
+                   unless impl
+                     logger.error("Unable to find an implementation object for action service #{action_class}.")
+                     next
+                   end
+                   const_set(module_name, impl)
+                 else
+                   (java_import action_class.ruby_class).first
+                 end
+        logger.trace("Loaded ACTION: #{action_class}")
+        Object.const_set(module_name, action)
+      end
+
+      # Import common actions
+      %w[Exec HTTP Ping Transformation].each do |action|
+        klass = (java_import "org.openhab.core.model.script.actions.#{action}").first
+        Object.const_set(action, klass)
+      end
+
+      module_function
+
+      #
+      # Send a notification.
+      #
+      # @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]
+      # @return [void]
+      #
+      # @example Send a broadcast notification via openHAB Cloud
+      #   rule 'Send an alert' do
+      #     changed Alarm_Triggered, to: ON
+      #     run { notify 'Red Alert!' }
+      #   end
+      #
+      def notify(msg, email: nil, icon: nil, severity: nil)
+        unless Actions.const_defined?(:NotificationAction)
+          raise NotImplementedError, "NotificationAction is not available. Please install the openHAB Cloud addon."
+        end
+
+        if email
+          NotificationAction.send_notification(email.to_s, msg.to_s, icon&.to_s, severity&.to_s)
+        else
+          NotificationAction.send_broadcast_notification(msg.to_s, icon&.to_s, severity&.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/dependency_tracking.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+if defined?($dependencyListener)
+  require "jruby"
+
+  klass = Class.new(org.jruby.util.collections.StringArraySet) do
+    def initialize(other)
+      super(JRuby.runtime)
+      other.each { |feature| append(feature) }
+    end
+
+    def append(name)
+      $dependencyListener.accept(name)
+
+      super
+    end
+  end
+
+  JRuby.runtime.load_service.class.field_accessor :loadedFeatures
+  JRuby.runtime.load_service.loadedFeatures = klass.new(JRuby.runtime.load_service.loadedFeatures)
+
+  loaded_specs = Gem.loaded_specs
+  loaded_specs.each_key do |gem|
+    $dependencyListener.accept("gem:#{gem}")
+  end
+
+  def loaded_specs.[]=(gem, _spec)
+    super
+
+    $dependencyListener.accept("gem:#{gem}")
+  end
+else
+  logger.warn("Dependency listener not found; dependency tracking disabled.")
+end

data/lib/openhab/core/dto/item_channel_link.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module DTO
+      java_import org.openhab.core.thing.link.dto.ItemChannelLinkDTO
+
+      # Adds methods to core openHAB ItemChannelLinkDTO to make it more natural in Ruby
+      class ItemChannelLinkDTO
+        #
+        # @!attribute [r] item_name
+        # @return [String] The name of the item that was linked or unlinked.
+        #
+
+        #
+        # @!attribute [r] item
+        # @return [Item] The item that was linked or unlinked
+        #
+        def item
+          EntityLookup.lookup_item(itemName)
+        end
+
+        #
+        # @!attribute [r] channel_uid
+        # @return [Things::ChannelUID] The UID of the channel that was linked or unlinked.
+        #
+        def channel_uid
+          Things::ChannelUID.new(channelUID)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module DTO
+      java_import org.openhab.core.thing.dto.AbstractThingDTO
+
+      # Adds methods to core openHAB AbstractThingDTO to make it more natural in Ruby
+      class AbstractThingDTO
+        # @!attribute [r] uid
+        # The thing's UID
+        # @return [String]
+        alias_method :uid, :UID
+
+        # @!attribute [r] thing_type_uid
+        # The thing type's UID
+        # @return [String]
+        alias_method :thing_type_uid, :thingTypeUID
+
+        # @!attribute [r] bridge_uid
+        # The Bridge's UID
+        # @return [String, nil]
+        alias_method :bridge_uid, :bridgeUID
+      end
+    end
+  end
+end

data/lib/openhab/core/dto.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    # Contains data transfer objects that represent other openHAB objects
+    # when they need to be represented with simple classes, such as for JSON
+    # responses, or when being attached to events sent over the event bus.
+    module DTO
+    end
+  end
+end