openhab-jrubyscripting 5.0.0.rc9 → 5.0.0.rc11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b818f8062ce950e265819455075b42fd1cf2d1fc6270b57f547b3e93f19f0656
-  data.tar.gz: '08c396633d12172da0751719196247319731205b9ee6704ea4844bd3709321aa'
+  metadata.gz: bc3911eb787dc73ea31109aa6d4d8c3896a1019b381a70030f152c668f0b8f2e
+  data.tar.gz: ebd2d7005e9f17827a4bf58d38b7fc2476a497cb428aab0270290c3c98461b80
 SHA512:
-  metadata.gz: ac9760ebe37190c941c973a4526ec8b8a7a2b1584585f324f80c531849f879f7cb471bcbac1beae02f3412fb6822fbb7e50e343e6e015e5ddbb9f5b552712a70
-  data.tar.gz: bc0ec52bafce17c3f090984370d98695fa49bfc1799293d1d6f421764f7a8ecfbe814c6d2b7bd6b03f023c0daefa517f3595bebcd7c0af53d0ce53ee153d4360
+  metadata.gz: df4c1df793cd44700467728c63df6ba9d12ecf7111fc7daf2b9a8f4953c68575082f9f4b87f70a42bfedcc9af70d4537e45b6fb2d8b78ac8e7e3f7cca22aaf4b
+  data.tar.gz: de1c8f5847bbbeb3eed3268ceedc2a61213b4f6ab269372a08bd4d8217f6b384a2c62b5ceb1f9de2777d264d0d6eb4e02fde6f245fa4fcc0dc03d068041a11bb

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
+        class << self # rubocop:disable Lint/EmptyClass
+          # @!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
+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 :transform_raw, :transform if instance_methods.include?(:say)
+
+          #
+          # 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
+          #   Transformation.transform(:map, "myfan.map", 0)
+          #
+          def transform(type, function, value)
+            transform_raw(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

@@ -6,64 +6,24 @@ module OpenHAB
     # Access to global actions.
     #
     # All openHAB's actions including those provided by add-ons are available, notably:
-    # * Audio
-    # * Voice
-    # * Things
-    # * Ephemeris
-    # * Exec
-    # * HTTP
-    # * Ping
+    # * {Audio}
+    # * {CoreExt::Ephemeris Ephemeris}
+    # * {Exec}
+    # * {HTTP}
+    # * {Items::Persistence PersistenceExtensions}
+    # * {Ping}
+    # * {Items::Semantics Semantics}
+    # * {Transformation}
+    # * {Voice}
     #
     # From add-ons, e.g.:
-    # * Transformation
-    # * PersistenceExtensions (see {Items::Persistence})
-    # * NotificationAction (from [openHAB Cloud Connector](https://www.openhab.org/addons/integrations/openhabcloud/))
-    #
-    # Global actions are available as "global" methods on {OpenHAB::DSL}, or
-    # explicitly from this {Actions} module, or you can explicitly reference a
-    # specific action.
+    # * 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}.
     #
-    # @example Run the TTS engine and output to the default audio sink. For more information see [Voice](https://www.openhab.org/docs/configuration/multimedia.html#voice)
-    #   rule 'Say the time every hour' do
-    #     every :hour
-    #     run { say "The time is #{TimeOfDay.now}" }
-    #   end
-    #
-    #   rule 'Play an audio file' do
-    #     every :hour
-    #     run { play_sound "beep.mp3", volume: 100 }
-    #   end
-    #
-    #   play_stream 'example.com'
-    #
-    # @example Send a broadcast notification via the openHAB Cloud
-    #   rule 'Send an alert' do
-    #     changed Alarm_Triggered, to: ON
-    #     run { notify 'Red Alert!' }
-    #   end
-    #
-    # @example Execute an external command
-    #   rule 'Run a command' do
-    #     every :day
-    #     run do
-    #       execute_command_line('/bin/true')
-    #     end
-    #   end
-    #
-    # @example Execute an external command, referencing the Exec module directly
-    #   rule 'Run a command' do
-    #     every :day
-    #     run do
-    #       OpenHAB::Core::Actions::Exec::execute_command_line('/bin/true')
-    #     end
-    #   end
-    #
-    # @example Run a transformation
-    #   transform("MAP", "myfan.map", "0")
-    #
     module Actions
       OSGi.services("org.openhab.core.model.script.engine.action.ActionService")&.each do |service|
         action_class = service.action_class
@@ -91,18 +51,24 @@ module OpenHAB
       module_function
 
       #
-      # Send notification to an email or broadcast
+      # Send a notification.
       #
-      # @param msg [String] The notification message to send
-      # @param email [String, nil] The email address to send to. If nil, the message will be broadcast
+      # @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 NoMethodError, "NotificationAction is not available. Please install the openHAB cloud addon"
+          raise NotImplementedError, "NotificationAction is not available. Please install the openHAB Cloud addon."
         end
 
         if email
@@ -111,69 +77,6 @@ module OpenHAB
           NotificationAction.send_broadcast_notification(msg.to_s, icon&.to_s, severity&.to_s)
         end
       end
-
-      #
-      # 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]
-      #
-      def say(text, voice: nil, sink: nil, volume: nil)
-        volume = PercentType.new(volume) unless volume.is_a?(PercentType) || volume.nil?
-        Voice.say(text.to_s, voice&.to_s, sink&.to_s, volume)
-      end
-
-      #
-      # 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]
-      #
-      def play_sound(filename, sink: nil, volume: nil)
-        volume = PercentType.new(volume) unless volume.is_a?(PercentType) || volume.nil?
-        Audio.play_sound(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]
-      #
-      def play_stream(url, sink: nil)
-        Audio.play_stream(sink&.to_s, url)
-      end
-
-      #
-      # Delegate missing methods to any available global actions.
-      #
-      def method_missing(method, *args, &block)
-        Actions.constants.each do |constant|
-          mod = Actions.const_get(constant)
-          return mod.public_send(method, *args, &block) if mod.respond_to?(method)
-        end
-
-        super
-      end
-
-      # @!visibility private
-      def respond_to_missing?(method_name, _include_private = false)
-        Actions.constants.each do |constant|
-          mod = Actions.const_get(constant)
-          return true if mod.respond_to?(method_name)
-        end
-
-        super
-      end
     end
   end
 end

data/lib/openhab/core/{events → dto}/item_channel_link.rb

@@ -2,18 +2,15 @@
 
 module OpenHAB
   module Core
-    module Events
+    module DTO
       java_import org.openhab.core.thing.link.dto.ItemChannelLinkDTO
 
-      # Strictly speaking this class isn't an event, but it's accessed from an AbstractItemChannelLinkEvent
-
       # 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.
         #
-        alias_method :item_name, :itemName
 
         #
         # @!attribute [r] item

data/lib/openhab/core/{events → dto}/thing.rb

@@ -2,26 +2,24 @@
 
 module OpenHAB
   module Core
-    module Events
+    module DTO
       java_import org.openhab.core.thing.dto.AbstractThingDTO
 
-      # Strictly speaking this class isn't an event, but it's accessed from an AbstractThingRegistryEvent
-
       # Adds methods to core openHAB AbstractThingDTO to make it more natural in Ruby
       class AbstractThingDTO
-        # @!method uid
-        #   The thing's UID
-        #   @return [String]
+        # @!attribute [r] uid
+        # The thing's UID
+        # @return [String]
         alias_method :uid, :UID
 
-        # @!method thing_type_uid
-        #   The thing type's UID
-        #   @return [String]
+        # @!attribute [r] thing_type_uid
+        # The thing type's UID
+        # @return [String]
         alias_method :thing_type_uid, :thingTypeUID
 
-        # @!method bridge_uid
-        #   The bridge's UID
-        #   @return [String]
+        # @!attribute [r] bridge_uid
+        # The Bridge's UID
+        # @return [String, nil]
         alias_method :bridge_uid, :bridgeUID
       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

data/lib/openhab/core/entity_lookup.rb

@@ -36,7 +36,7 @@ module OpenHAB
 
         # @return [Boolean] if dummy items should be created in this context
         def create_dummy_items?
-          @create_dummy_items
+          defined?(@create_dummy_items) && @create_dummy_items
         end
 
         # @!visibility private

data/lib/openhab/core/events/abstract_event.rb

@@ -10,6 +10,7 @@ module OpenHAB
         # @return [Object]
         attr_accessor :attachment
 
+        # @return [String]
         alias_method :inspect, :to_s
       end
     end

data/lib/openhab/core/events/abstract_item_registry_event.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.AbstractItemRegistryEvent,
+                  org.openhab.core.items.events.ItemAddedEvent,
+                  org.openhab.core.items.events.ItemUpdatedEvent,
+                  org.openhab.core.items.events.ItemRemovedEvent
+
+      #
+      # The {AbstractEvent} sent when an {Item} is added, updated, or removed
+      # from its registry.
+      #
+      # @!attribute [r] item
+      #   @return [DTO::ItemDTO] The item that triggered this event.
+      #
+      class AbstractItemRegistryEvent < AbstractEvent; end
+
+      #
+      # The {AbstractEvent} sent with an `item_added` trigger.
+      #
+      class ItemAddedEvent < AbstractItemRegistryEvent; end
+
+      #
+      # The {AbstractEvent} sent with an `item_updated` trigger.
+      #
+      class ItemUpdatedEvent < AbstractItemRegistryEvent; end
+
+      #
+      # The {AbstractEvent} sent with an `item_removed` trigger.
+      #
+      class ItemRemovedEvent < AbstractItemRegistryEvent; end
+    end
+  end
+end

data/lib/openhab/core/events/abstract_thing_registry_event.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.thing.events.AbstractThingRegistryEvent,
+                  org.openhab.core.thing.events.ThingAddedEvent,
+                  org.openhab.core.thing.events.ThingUpdatedEvent,
+                  org.openhab.core.thing.events.ThingRemovedEvent
+
+      #
+      # The {AbstractEvent} sent when a {Things::Thing Thing} is added,
+      # updated, or removed from its registry.
+      #
+      #
+      # @!attribute [r] thing
+      #   @return [DTO::AbstractThingDTO] The thing that triggered this event.
+      #
+      class AbstractThingRegistryEvent < AbstractEvent; end
+
+      #
+      # The {AbstractEvent} sent with a
+      # {DSL::Rules::BuilderDSL#thing_added thing_added trigger}.
+      #
+      class ThingAddedEvent < AbstractThingRegistryEvent; end
+
+      #
+      # The {AbstractEvent} sent with a
+      # {DSL::Rules::BuilderDSL#thing_updated thing_updated trigger}.
+      #
+      class ThingUpdatedEvent < AbstractThingRegistryEvent; end
+
+      #
+      # The {AbstractEvent} sent with a
+      # {DSL::Rules::BuilderDSL#thing_removed thing_removed trigger}.
+      #
+      class ThingRemovedEvent < AbstractThingRegistryEvent; end
+    end
+  end
+end