openhab-scripting 4.46.2 → 5.0.0

data/lib/openhab/core/entity_lookup.rb

@@ -1,105 +1,187 @@
 # frozen_string_literal: true
 
-require 'openhab/log/logger'
-require_relative 'item_proxy'
-
-# Automation lookup and injection of OpenHab entities
+require "ruby2_keywords"
 
 module OpenHAB
   module Core
     #
-    # Manages access to OpenHAB entities
+    # 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
-      include OpenHAB::Log
+      # @!visibility private
+      module ClassMethods
+        # @!attribute [w] create_dummy_items
+        # @return [true,false]
+        def create_dummy_items=(value)
+          @create_dummy_items = value
+        end
 
-      #
-      # Automatically looks up OpenHAB items and things in appropriate registries
-      #
-      # @param [method] method Name of item to lookup
-      # @param [<Type>] args method arguments
-      # @param [<Type>] block supplied to missing method
-      #
-      # @return [Object] Item or Thing if found in registry
-      #
-      def method_missing(method, *args, &block)
-        logger.trace("method missing, performing OpenHab Lookup for: #{method}")
-        EntityLookup.lookup_entity(method) || super
-      end
+        # @return [Boolean] if dummy items should be created in this context
+        def create_dummy_items?
+          defined?(@create_dummy_items) && @create_dummy_items
+        end
 
-      #
-      # Checks if this method responds to the missing method
-      #
-      # @param [String] method_name Name of the method to check
-      # @param [Boolean] _include_private boolean if private methods should be checked
-      #
-      # @return [Boolean] true if this object will respond to the supplied method, false otherwise
-      #
-      def respond_to_missing?(method_name, _include_private = false)
-        logger.trace("Checking if OpenHAB entites exist for #{method_name}")
-        method_name = method_name.to_s if method_name.is_a? Symbol
+        # @!visibility private
+        def inherited(klass)
+          super
+
+          EntityLookup.included(klass)
+        end
 
-        method_name == 'scriptLoaded' ||
-          method_name == 'scriptUnloaded' ||
-          EntityLookup.lookup_entity(method_name) ||
+        # @!visibility private
+        def included(klass)
           super
+
+          EntityLookup.included(klass)
+        end
       end
 
-      #
-      # Looks up an OpenHAB entity
-      #  items are checked first, then things
-      #
-      # @param [String] name of entity to lookup in item or thing registry
-      #
-      # @return [Thing,Item] if found, nil otherwise
-      #
-      def self.lookup_entity(name)
-        lookup_item(name) || lookup_thing(name)
+      # @!visibility private
+      def self.included(klass)
+        klass.singleton_class.prepend(ClassMethods)
+        klass.ancestors.each do |ancestor|
+          next unless ancestor.singleton_class.ancestors.include?(ClassMethods)
+          next if ancestor.create_dummy_items?.nil?
+
+          klass.create_dummy_items = ancestor.create_dummy_items?
+          break
+        end
       end
 
       #
-      # Looks up a Thing in the OpenHAB registry replacing '_' with ':'
-      #
-      # @param [String] name of Thing to lookup in Thing registry
+      # Automatically looks up openHAB items and things in appropriate registries
       #
-      # @return [Thing] if found, nil otherwise
+      # @return [Item, Things::Thing, nil]
       #
-      def self.lookup_thing(name)
-        logger.trace("Looking up thing(#{name})")
-        # Convert from : syntax to underscore
-        name = name.to_s if name.is_a? Symbol
+      ruby2_keywords def method_missing(method, *args)
+        return super unless args.empty? && !block_given?
 
-        # Thing UIDs have at least 3 segements
-        return if name.count('_') < 3
+        logger.trace("method missing, performing openHAB Lookup for: #{method}")
+        EntityLookup.lookup_entity(method,
+                                   create_dummy_items: self.class.respond_to?(:create_dummy_items?) &&
+                                     self.class.create_dummy_items?) || super
+      end
 
-        name = name.tr('_', ':')
-        $things.get(org.openhab.core.thing.ThingUID.new(name))
+      # @!visibility private
+      def respond_to_missing?(method, *)
+        logger.trace("Checking if openHAB entities exist for #{method}")
+        EntityLookup.lookup_entity(method) || super
       end
 
-      #
-      # Lookup OpenHAB items in item registry
-      #
-      # @param [String] name of item to lookup
-      #
-      # @return [Item] OpenHAB item if registry contains a matching item, nil othewise
-      #
-      def self.lookup_item(name)
-        logger.trace("Looking up item(#{name})")
-        name = name.to_s if name.is_a? Symbol
-        item = $ir.get(name)
-        ItemProxy.new(item) unless item.nil?
+      # @!visibility private
+      def instance_eval_with_dummy_items(&block)
+        DSL::ThreadLocal.thread_local(openhab_create_dummy_items: self.class.create_dummy_items?) do
+          instance_eval(&block)
+        end
+      end
+
+      class << self
+        #
+        # 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
+        # @param [true, false] create_dummy_items If a dummy {Item} should be created if an actual item can't be found
+        #
+        # @return [Item, Things::Thing, nil]
+        #
+        def lookup_entity(name, create_dummy_items: false)
+          # make sure we have a nil return
+          create_dummy_items = nil if create_dummy_items == false
+          lookup_item(name) || lookup_thing_const(name) || (create_dummy_items && Items::Proxy.new(name.to_sym))
+        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 lookup_thing(uid)
+          logger.trace("Looking up thing '#{uid}'")
+          uid = uid.to_s if uid.is_a?(Symbol)
+
+          uid = Things::ThingUID.new(uid) unless uid.is_a?(Things::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 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 [Item, nil]
+        #
+        def 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
       end
     end
   end
 end
 
 #
-# Implements const_missing to return OpenHAB items or things if mapping to missing name if they exist
+# 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
+# @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
+  OpenHAB::Core::EntityLookup.lookup_entity(name,
+                                            create_dummy_items: Thread.current[:openhab_create_dummy_items]) || super
 end

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

@@ -0,0 +1,18 @@
+# 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
+
+        # @return [String]
+        alias_method :inspect, :to_s
+      end
+    end
+  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

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
+
+      # {AbstractEvent} sent when an item receives a command.
+      class ItemCommandEvent < ItemEvent
+        # @!attribute [r] command
+        # @return [Command] The command sent to the item.
+        alias_method :command, :item_command
+
+        # @!method refresh?
+        #   Check if {#command} is {REFRESH}
+        #   @return [true, false]
+
+        # @!method on?
+        #   Check if {#command} is (implicitly convertible to) {ON}
+        #   @return [true, false]
+
+        # @!method off?
+        #   Check if {#command} is (implicitly convertible to) {OFF}
+        #   @return [true, false]
+
+        # @!method up?
+        #   Check if {#command} is (implicitly convertible to) {UP}
+        #   @return [true, false]
+
+        # @!method down?
+        #   Check if {#command} is (implicitly convertible to) {DOWN}
+        #   @return [true, false]
+
+        # @!method stop?
+        #   Check if {#command} is {STOP}
+        #   @return [true, false]
+
+        # @!method move?
+        #   Check if {#command} is {MOVE}
+        #   @return [true, false]
+
+        # @!method increase?
+        #   Check if {#command} is {INCREASE}
+        #   @return [true, false]
+
+        # @!method decrease?
+        #   Check if {#command} is {DECREASE}
+        #   @return [true, false]
+
+        # @!method play?
+        #   Check if {#command} is {PLAY}
+        #   @return [true, false]
+
+        # @!method pause?
+        #   Check if {#command} is {PAUSE}
+        #   @return [true, false]
+
+        # @!method rewind?
+        #   Check if {#command} is {REWIND}
+        #   @return [true, false]
+
+        # @!method fast_forward?
+        #   Check if {#command} is {FASTFORWARD}
+        #   @return [true, false]
+
+        # @!method next?
+        #   Check if {#command} is {NEXT}
+        #   @return [true, false]
+
+        # @!method previous?
+        #   Check if {#command} is {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 [Item] 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,75 @@
+# frozen_string_literal: true
+
+require_relative "item_state_event"
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.ItemStateChangedEvent
+
+      #
+      # {AbstractEvent} sent when an item's state has changed.
+      #
+      class ItemStateChangedEvent < ItemEvent
+        include ItemState
+
+        # @!method was_undef?
+        #   Check if {#was} is {UNDEF}
+        #   @return [true, false]
+
+        # @!method was_null?
+        #   Check if {#was} is {NULL}
+        #   @return [true, false]
+
+        # @!method was_on?
+        #   Check if {#was} is (implicitly convertible to) {ON}
+        #   @return [true, false]
+
+        # @!method was_off?
+        #   Check if {#was} is (implicitly convertible to) {OFF}
+        #   @return [true, false]
+
+        # @!method was_up?
+        #   Check if {#was} is (implicitly convertible to) {UP}
+        #   @return [true, false]
+
+        # @!method was_down?
+        #   Check if {#was} is (implicitly convertible to) {DOWN}
+        #   @return [true, false]
+
+        # @!method was_open?
+        #   Check if {#was} is (implicitly convertible to) {OPEN}
+        #   @return [true, false]
+
+        # @!method was_closed?
+        #   Check if {#was} is (implicitly convertible to) {CLOSED}
+        #   @return [true, false]
+
+        # @!method was_playing?
+        #   Check if {#was} is {PLAY}
+        #   @return [true, false]
+
+        # @!method was_paused?
+        #   Check if {#was} is {PAUSE}
+        #   @return [true, false]
+
+        #
+        # Check if state was defined (not {UNDEF} or {NULL})
+        #
+        # @return [true,false]
+        #
+        def was?
+          !old_item_state.is_a?(UnDefType)
+        end
+
+        #
+        # @!attribute [r] was
+        # @return [State, nil] the prior 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,79 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.ItemStateEvent
+
+      #
+      # Helpers common to {ItemStateEvent} and {ItemStateChangedEvent}.
+      #
+      # Methods that refer to implicit conversion mean that for example
+      # a PercentType of 100% will be `true` for {#on?}, etc.
+      #
+      module ItemState
+        # @!method undef?
+        #   Check if {#state} is {UNDEF}
+        #   @return [true, false]
+
+        # @!method null?
+        #   Check if {#state} is {NULL}
+        #   @return [true, false]
+
+        # @!method on?
+        #   Check if {#state} is (implicitly convertible to) {ON}
+        #   @return [true, false]
+
+        # @!method off?
+        #   Check if {#state} is (implicitly convertible to) {OFF}
+        #   @return [true, false]
+
+        # @!method up?
+        #   Check if {#state} is (implicitly convertible to) {UP}
+        #   @return [true, false]
+
+        # @!method down?
+        #   Check if {#state} is (implicitly convertible to) {DOWN}
+        #   @return [true, false]
+
+        # @!method open?
+        #   Check if {#state} is (implicitly convertible to) {OPEN}
+        #   @return [true, false]
+
+        # @!method closed?
+        #   Check if {#state} is (implicitly convertible to) {CLOSED}
+        #   @return [true, false]
+
+        # @!method playing?
+        #   Check if {#state} is {PLAY}
+        #   @return [true, false]
+
+        # @!method paused?
+        #   Check if {#state} is {PAUSE}
+        #   @return [true, false]
+
+        #
+        # Check if {#state} is defined (not {UNDEF} or {NULL})
+        #
+        # @return [true, false]
+        #
+        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_status_info_event.rb

@@ -0,0 +1,55 @@
+# 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 Thing's} status has changed.
+      #
+      class ThingStatusInfoChangedEvent < AbstractEvent
+        # @!attribute [r] uid
+        # @return [Things::ThingUID] The UID of the {Things::Thing Thing} that triggered this event.
+        alias_method :uid, :get_thing_uid
+        # @!attribute [r] was
+        # @return [org.openhab.core.thing.ThingStatusInfo] The thing's prior status.
+        alias_method :was, :get_old_status_info
+        # @!attribute [r] status
+        # @return [org.openhab.core.thing.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 Thing} that triggered this event.
+        #
+        alias_method :uid, :get_thing_uid
+        #
+        # @!attribute [r] status
+        # @return [org.openhab.core.thing.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