openhab-jrubyscripting 5.0.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd7a4eed6a2398fd34734d9b3dc15a8f5e2bcc74f7309aede27be29501c21698
+  data.tar.gz: a1f70554ada415e7de0325ea259ac9edcad48355ef6000a4877057fa06b343ce
+SHA512:
+  metadata.gz: f27aa8940df9441a5318c32d1c0d84f15fdd70b2336cf95dd09383b73b97d14bbc7c924ba3e3df24f48d5f289d410ec1d6d0df9f99a40141ac34d88152e9a76a
+  data.tar.gz: c369de38091c4486a492b88ef990537b5a4cc667becca6be5a99a56227a8a2b0339b14e9ce1e11e6e73b56d8b055d3876917916ee7ec52b66c5b23e85b33a95b

data/lib/openhab/core/actions.rb

@@ -0,0 +1,163 @@
+# 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
+    # * Voice
+    # * Things
+    # * Ephemeris
+    # * Exec
+    # * HTTP
+    # * Ping
+    #
+    # 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.
+    #
+    # 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|
+        java_import service.action_class.ruby_class
+        logger.trace("Loaded ACTION: #{service.action_class}")
+      end
+      # Import common actions
+      %w[Exec HTTP Ping].each { |action| java_import "org.openhab.core.model.script.actions.#{action}" }
+
+      module_function
+
+      #
+      # Send notification to an email or broadcast
+      #
+      # @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 icon [String, Symbol, nil]
+      # @param severity [String, Symbol, nil]
+      #
+      # @return [void]
+      #
+      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"
+        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
+
+      #
+      # 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/entity_lookup.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    #
+    # Manages access to OpenHAB entities
+    #
+    # You can access OpenHAB items and things directly using their name, anywhere `EntityLookup` is available.
+    #
+    # @note Thing UIDs are separated by a colon `:`. Since it is not a valid symbol for an identifier,
+    #   it must be replaced with an underscore `_`. So to access `astro:sun:home`, use `astro_sun_home`
+    #   as an alternative to `things["astro:sun:home"]`
+    #
+    # @see OpenHAB::DSL.items items[]
+    # @see OpenHAB::DSL.things things[]
+    #
+    # @example Accessing Items and Groups
+    #   gAll_Lights       # Access the gAll_Lights group. It is the same as items["gAll_Lights"]
+    #   Kitchen_Light.on  # The OpenHAB object for the Kitchen_Light item and send an ON command
+    #
+    # @example Accessing Things
+    #   smtp_mail_local.send_mail('me@example.com', 'Subject', 'Dear Person, ...')
+    #   # Is equivalent to:
+    #   things['smtp:mail:local'].send_mail('me@example.com', 'Subject', 'Dear Person, ...')
+    #
+    module EntityLookup
+      #
+      # Automatically looks up OpenHAB items and things in appropriate registries
+      #
+      # @return [GenericItem, Things::Thing, nil]
+      #
+      def method_missing(method, *args, &block)
+        logger.trace("method missing, performing OpenHab Lookup for: #{method}")
+        EntityLookup.lookup_entity(method) || super
+      end
+
+      # @!visibility private
+      def respond_to_missing?(method_name, _include_private = false)
+        logger.trace("Checking if OpenHAB entities exist for #{method_name}")
+        method_name = method_name.to_s if method_name.is_a?(Symbol)
+
+        method_name == "scriptLoaded" ||
+          method_name == "scriptUnloaded" ||
+          EntityLookup.lookup_entity(method_name) ||
+          super
+      end
+
+      #
+      # Looks up an OpenHAB entity
+      #  items are checked first, then things
+      #
+      # @!visibility private
+      #
+      # @param [String] name of entity to lookup in item or thing registry
+      #
+      # @return [GenericItem, Things::Thing, nil]
+      #
+      def self.lookup_entity(name)
+        lookup_item(name) || lookup_thing_const(name)
+      end
+
+      #
+      # Looks up a Thing in the OpenHAB registry
+      #
+      # @!visibility private
+      #
+      # @param [String] uid name of Thing to lookup in Thing registry
+      #
+      # @return [Things::Thing, nil]
+      #
+      def self.lookup_thing(uid)
+        logger.trace("Looking up thing '#{uid}'")
+        uid = uid.to_s if uid.is_a?(Symbol)
+
+        uid = generate_thing_uid(uid) unless uid.is_a?(org.openhab.core.thing.ThingUID)
+        thing = $things.get(uid)
+        return unless thing
+
+        logger.trace("Retrieved Thing(#{thing}) from registry for uid: #{uid}")
+        Things::Proxy.new(thing)
+      end
+
+      #
+      # Looks up a Thing in the OpenHAB registry replacing `_` with `:`
+      #
+      # @!visibility private
+      #
+      # @param [String] name of Thing to lookup in Thing registry
+      #
+      # @return [Things::Thing, nil]
+      #
+      def self.lookup_thing_const(name)
+        name = name.to_s if name.is_a?(Symbol)
+
+        if name.is_a?(String)
+          # Thing UIDs have at least 3 segments, separated by `_`
+          return if name.count("_") < 2
+
+          # Convert from _ syntax to :
+          name = name.tr("_", ":")
+        end
+        lookup_thing(name)
+      end
+
+      #
+      # Lookup OpenHAB items in item registry
+      #
+      # @!visibility private
+      #
+      # @param [String] name of item to lookup
+      #
+      # @return [GenericItem, nil]
+      #
+      def self.lookup_item(name)
+        logger.trace("Looking up item '#{name}'")
+        name = name.to_s if name.is_a?(Symbol)
+        item = $ir.get(name)
+        Items::Proxy.new(item) unless item.nil?
+      end
+
+      #
+      # Returns a ThingUID given a string like object
+      #
+      # @!visibility private
+      #
+      # @return [Things::ThingUID]
+      #
+      def self.generate_thing_uid(uid)
+        org.openhab.core.thing.ThingUID.new(*uid.split(":"))
+      end
+    end
+  end
+end
+
+#
+# Implements const_missing to return OpenHAB items or things if mapping to missing name if they exist
+#
+# @param [String] name Capital string that was not set as a constant and to be looked up
+#
+# @return [Object] OpenHAB Item or Thing if their name exist in OpenHAB item and thing regestries
+#
+def Object.const_missing(name)
+  OpenHAB::Core::EntityLookup.lookup_entity(name) || super
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.events.AbstractEvent
+
+      # Add attachments event data.
+      class AbstractEvent
+        # @return [Object]
+        attr_accessor :attachment
+
+        alias_method :inspect, :to_s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      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
+        # @return [GenericItem] 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/events/item_command_event.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "item_event"
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.ItemCommandEvent
+
+      # Adds methods to core OpenHAB ItemCommandEvent to make it more natural in Ruby
+      class ItemCommandEvent < ItemEvent
+        # @!attribute [r] command
+        # @return [Type] The command sent to the item.
+        alias_method :command, :item_command
+
+        # @!method refresh?
+        #   Check if `self == REFRESH`
+        #   @return [true,false]
+
+        # @!method on?
+        #   Check if `self == ON`
+        #   @return [true,false]
+
+        # @!method off?
+        #   Check if `self == OFF`
+        #   @return [true,false]
+
+        # @!method up?
+        #   Check if `self == UP`
+        #   @return [true,false]
+
+        # @!method down?
+        #   Check if `self == DOWN`
+        #   @return [true,false]
+
+        # @!method stop?
+        #   Check if `self == STOP`
+        #   @return [true,false]
+
+        # @!method move?
+        #   Check if `self == MOVE`
+        #   @return [true,false]
+
+        # @!method increase?
+        #   Check if `self == INCREASE`
+        #   @return [true,false]
+
+        # @!method decrease?
+        #   Check if `self == DECREASE`
+        #   @return [true,false]
+
+        # @!method play?
+        #   Check if `self == PLAY`
+        #   @return [true,false]
+
+        # @!method pause?
+        #   Check if `self == PAUSE`
+        #   @return [true,false]
+
+        # @!method rewind?
+        #   Check if `self == REWIND`
+        #   @return [true,false]
+
+        # @!method fast_forward?
+        #   Check if `self == FASTFORWARD`
+        #   @return [true,false]
+
+        # @!method next?
+        #   Check if `self == NEXT`
+        #   @return [true,false]
+
+        # @!method previous?
+        #   Check if `self == PREVIOUS`
+        #   @return [true,false]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.ItemEvent
+
+      #
+      # Adds methods to core OpenHAB ItemEvent to make it more natural in Ruby
+      #
+      class ItemEvent < AbstractEvent
+        #
+        # @!attribute [r] item
+        # @return [GenericItem] The item that triggered this event.
+        #
+        def item
+          EntityLookup.lookup_item(item_name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "item_state_event"
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.ItemStateChangedEvent
+
+      #
+      # Adds methods to core OpenHAB ItemStateChangedEvent to make it more natural in Ruby
+      #
+      class ItemStateChangedEvent < ItemEvent
+        include ItemState
+
+        #
+        # Check if state was == UNDEF
+        #
+        # @return [true,false] True if the state is UNDEF, false otherwise
+        #
+        def was_undef?
+          old_item_state == UNDEF
+        end
+
+        #
+        # Check if state was == NULL
+        #
+        # @return [true,false] True if the state is NULL, false otherwise
+        def was_null?
+          old_item_state == NULL
+        end
+
+        #
+        # Check if state was defined (not UNDEF or NULL)
+        #
+        # @return [true,false] True if state is not UNDEF or NULL
+        #
+        def was?
+          !old_item_state.is_a?(UnDefType)
+        end
+
+        #
+        # @!attribute [r] was
+        # @return [State, nil] The state of the item if it was not {UNDEF} or {NULL}, `nil` otherwise.
+        #
+        def was
+          old_item_state if was?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.ItemStateEvent
+
+      # Helpers common to {ItemStateEvent} and {ItemStateChangedEvent}.
+      module ItemState
+        #
+        # Check if the state == UNDEF
+        #
+        # @return [true,false] True if the state is UNDEF, false otherwise
+        #
+        def undef?
+          item_state == UNDEF
+        end
+
+        #
+        # Check if the state == NULL
+        #
+        # @return [true,false] True if the state is NULL, false otherwise
+        def null?
+          item_state == NULL
+        end
+
+        #
+        # Check if the state is defined (not UNDEF or NULL)
+        #
+        # @return [true,false] True if state is not UNDEF or NULL
+        #
+        def state?
+          !item_state.is_a?(UnDefType)
+        end
+
+        #
+        # @!attribute [r] state
+        # @return [State, nil] The state of the item if it is not {UNDEF} or {NULL}, `nil` otherwise.
+        #
+        def state
+          item_state if state?
+        end
+      end
+
+      # {AbstractEvent} sent when an item's state is updated (regardless of if it changed or not).
+      class ItemStateEvent < ItemEvent
+        include ItemState
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      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]
+        alias_method :uid, :UID
+
+        # @!method 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]
+        alias_method :bridge_uid, :bridgeUID
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.thing.events.ThingStatusInfoChangedEvent,
+                  org.openhab.core.thing.events.ThingStatusInfoEvent
+
+      # The {AbstractEvent} sent when a {Things::Thing}'s status has changed.
+      class ThingStatusInfoChangedEvent < AbstractEvent
+        # @!attribute [r] uid
+        # @return [Things::ThingUID] The UID of the [Things::Thing] that triggered this event.
+        alias_method :uid, :get_thing_uid
+        # @!attribute [r] was
+        # @return [Things::ThingStatusInfo] The thing's prior status.
+        alias_method :was, :get_old_status_info
+        # @!attribute [r] status
+        # @return [Things::ThingStatusInfo] The thing's status.
+        alias_method :status, :status_info
+
+        #
+        # @!attribute [r] thing
+        # @return [Things::Thing] The thing that triggered this event.
+        #
+        def thing
+          EntityLookup.lookup_thing(uid)
+        end
+      end
+
+      # The {AbstractEvent} sent when a {Things::Thing}'s status is set.
+      class ThingStatusInfoEvent < AbstractEvent
+        #
+        # @!attribute [r] uid
+        # @return [Things::ThingUID] The UID of the [Things::Thing] that triggered this event.
+        #
+        alias_method :uid, :get_thing_uid
+        #
+        # @!attribute [r] status
+        # @return [Things::ThingStatusInfo] The thing's status.
+        #
+        alias_method :status, :status_info
+
+        #
+        # @!attribute [r] thing
+        # @return [Things::Thing] The thing that triggered this event.
+        #
+        def thing
+          EntityLookup.lookup_thing(uid)
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/events.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    # Contains objects sent to event handlers containing context around the
+    # triggered event.
+    module Events
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      class << self
+        # @!visibility private
+        def prepend_accepted_data_types
+          concrete_item_classes.each do |k|
+            k.prepend(AcceptedDataTypes)
+          end
+        end
+      end
+
+      module AcceptedDataTypes
+        # @see GenericItem#accepted_command_types
+        def accepted_command_types
+          super.map { |k| k.is_a?(java.lang.Class) ? k.ruby_class : k }
+        end
+
+        # @see GenericItem#accepted_data_types
+        def accepted_data_types
+          super.map { |k| k.is_a?(java.lang.Class) ? k.ruby_class : k }
+        end
+      end
+      private_constant :AcceptedDataTypes
+    end
+  end
+end