openhab-scripting 4.46.2 → 5.0.0

data/lib/openhab/core/types/un_def_type.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      UnDefType = org.openhab.core.types.UnDefType
+
+      # There are situations when item states do not have any defined value.
+      # This might be because they have not been initialized yet (never
+      # received an state update so far) or because their state is ambiguous
+      # (e.g. a group item with members whose states do not match will be
+      # {NULL}).
+      class UnDefType # rubocop:disable Lint/EmptyClass
+        # @!parse include State
+
+        # @!constant NULL
+        #   Null State
+        # @!constant UNDEF
+        #   Undef State
+
+        # @!method null?
+        #   Check if `self` == {NULL}
+        #   @return [true,false]
+
+        # @!method undef?
+        #   Check if `self` == {UNDEF}
+        #   @return [true,false]
+      end
+    end
+  end
+end
+
+# @!parse
+#   UnDefType = OpenHAB::Core::Types::UnDefType
+#   NULL = OpenHAB::Core::Types::UnDefType::NULL
+#   UNDEF = OpenHAB::Core::Types::UnDefType::UNDEF

data/lib/openhab/core/types/up_down_type.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      UpDownType = org.openhab.core.library.types.UpDownType
+
+      #
+      # Implements the {UP} and {DOWN} commands.
+      #
+      # Also, {PercentType} can be converted to {UpDownType}
+      # for more semantic comparisons. `0` is {UP}, `100` is
+      # {DOWN}, and anything in-between is neither.
+      #
+      class UpDownType
+        # @!parse include Command, State
+
+        # @!constant UP
+        #   Up Command/State
+        # @!constant DOWN
+        #   Down Command/State
+
+        # @!method up?
+        #   Check if `self == UP`
+        #   @return [true,false]
+
+        # @!method down?
+        #   Check if `self == DOWN`
+        #   @return [true,false]
+
+        #
+        # Invert the type
+        #
+        # @return [UpDownType] {UP} if {down?}, {DOWN} if {up?}
+        #
+        def !
+          return UP if down?
+          return DOWN if up?
+        end
+      end
+    end
+  end
+end
+
+# @!parse
+#   UpDownType = OpenHAB::Core::Types::UpDownType
+#   UP = OpenHAB::Core::Types::UpDownType::UP
+#   DOWN = OpenHAB::Core::Types::UpDownType::DOWN

data/lib/openhab/core/types.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+Dir[File.expand_path("types/*.rb", __dir__)].sort.each do |f|
+  require f
+end
+
+module OpenHAB
+  module Core
+    #
+    # Contains the core types that openHAB uses as {State}s for items, and
+    # {Command}s to be sent to control them.
+    #
+    # Types are the specific data types that commands and states are. They can be
+    # sent to items, be the current state of an item, or be the `command`, `state`,
+    # and `was` field of various
+    # {group::OpenHAB::DSL::Rules::BuilderDSL::Triggers triggers}.
+    # Some types have additional useful methods.
+    #
+    module Types
+      # Hash taking a Enum value, and returning two symbols of
+      # predicates to be defined for it. the first is the "command" form,
+      # which should be defined on ItemCommandEvent, and on the Type itself.
+      # the second is "state" form, which should be defined on the applicable
+      # Item, and on the Type itself.
+      # @!visibility private
+      PREDICATE_ALIASES = Hash.new { |_h, k| [:"#{k.downcase}?"] * 2 }
+                              .merge({
+                                       "PLAY" => %i[play? playing?],
+                                       "PAUSE" => %i[pause? paused?],
+                                       "REWIND" => %i[rewind? rewinding?],
+                                       "FASTFORWARD" => %i[fast_forward? fast_forwarding?]
+                                     }).freeze
+
+      # Hash taking a Enum value, and returning an array of symbols
+      # of the command to define for it
+      # @!visibility private
+      COMMAND_ALIASES = Hash.new { |_h, k| k.downcase.to_sym }
+                            .merge({
+                                     "FASTFORWARD" => :fast_forward
+                                   }).freeze
+
+      constants.map { |c| const_get(c) }
+               .grep(Module)
+               .select { |k| k < java.lang.Enum }
+               .each do |klass|
+        # make sure == from Type is inherited
+        klass.remove_method(:==)
+
+        # dynamically define predicate methods
+        klass.values.each do |value| # rubocop:disable Style/HashEachMethods this isn't a Ruby hash
+          # include all the aliases that we define for items both command and
+          # state aliases (since types can be interrogated as an incoming
+          # command, or as the state of an item)
+          command = :"#{Types::COMMAND_ALIASES[value.to_s]}?"
+          states = Types::PREDICATE_ALIASES[value.to_s]
+
+          ([command] | states).each do |method|
+            logger.trace("Defining #{klass}##{method} for #{value}")
+            klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{method}                                                 # def on?
+                as(#{value.class.java_class.simple_name}).equal?(#{value})  #   as(OnOffType).equal?(ON)
+              end                                                           # end
+            RUBY
+          end
+
+          method = states.last
+          Events::ItemState.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{method}                                                            # def on?
+              item_state.as(#{value.class.java_class.simple_name}).equal?(#{value})  #   item_state.as(OnOffType).equal?(ON)
+            end                                                                      # end
+          RUBY
+
+          Events::ItemStateChangedEvent.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def was_#{method}                                                            # def was_on?
+              old_item_state.as(#{value.class.java_class.simple_name}).equal?(#{value})  #   old_item_state.as(OnOffType).equal?(ON)
+            end                                                                          # end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/openhab/{dsl → core}/uid.rb

@@ -1,16 +1,15 @@
 # frozen_string_literal: true
 
 module OpenHAB
-  module DSL
+  module Core
     java_import org.openhab.core.common.AbstractUID
-    java_import org.openhab.core.thing.ThingTypeUID
 
-    # Adds methods to core OpenHAB AbstractUID to make it more natural in Ruby
+    # Adds methods to core openHAB AbstractUID to make it more natural in Ruby
     class AbstractUID
       # implicit conversion to string
-      alias to_str to_s
+      alias_method :to_str, :to_s
       # inspect result is just the string representation
-      alias inspect to_s
+      alias_method :inspect, :to_s
 
       # compares if equal to `other`, including string conversion
       # @return [true, false]
@@ -21,24 +20,6 @@ module OpenHAB
       end
     end
 
-    # Adds methods to core OpenHAB ThingUID to make it more natural in Ruby
-    class ThingUID
-      # Returns the id of the binding this thing belongs to
-      # @return [String]
-      def binding_id
-        get_segment(0)
-      end
-    end
-
-    # Adds methods to core OpenHAB ThingTypeUID to make it more natural in Ruby
-    class ThingTypeUID
-      # Returns the id of the binding this thing type belongs to
-      # @return [String]
-      def binding_id
-        get_segment(0)
-      end
-    end
-
     # have to remove == from all descendant classes so that they'll inherit
     # the new implementation
     [org.openhab.core.items.MetadataKey,

data/lib/openhab/core/value_cache.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+OpenHAB::Core.import_preset("cache")
+unless defined?($sharedCache)
+  $sharedCache = nil
+  return
+end
+
+module OpenHAB
+  module Core
+    # @interface
+    java_import org.openhab.core.automation.module.script.rulesupport.shared.ValueCache
+
+    #
+    # ValueCache is the interface used to access a
+    # {OpenHAB::DSL.shared_cache shared cache} available between scripts and/or
+    # rule executions.
+    #
+    # While ValueCache looks somewhat like a Hash, it does not support
+    # iteration of the contained elements. So it's limited to strictly storing,
+    # fetching, or removing known elements.
+    #
+    # Shared caches are _not_ persisted between openHAB restarts. And in fact,
+    # if all scripts are unloaded that reference a particular key, that key is
+    # removed.
+    #
+    # @note Only the {OpenHAB::DSL.shared_cache sharedCache} is exposed in Ruby.
+    #   For a private cache, simply use an instance variable. See
+    #   {file:docs/ruby-basics.md#variables Instance Variables}.
+    #
+    # @note Because every script or UI rule gets it own JRuby engine instance,
+    #   you cannot rely on being able to access Ruby objects between them. Only
+    #   objects that implement a Java interface that's part of Java or openHAB
+    #   Core (such as Hash implements {java.util.Map}, or other basic
+    #   datatypes) can be reliably stored and accessed from the shared cache.
+    #   Likewise, you can use the cache to access data from other scripting
+    #   languages, but they'll be all but useless in Ruby. It's best to stick
+    #   to simple data types. If you're having troubles, serializing to_json
+    #   before storing may help.
+    #
+    # @see https://www.openhab.org/docs/configuration/jsr223.html#cache-preset openHAB Cache Preset
+    #
+    # @example
+    #   shared_cache.compute_if_absent(:execution_count) { 0 }
+    #   shared_cache[:execution_count] += 1
+    #
+    module ValueCache
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-5B-5D Hash#[]
+      def [](key)
+        get(key.to_s)
+      end
+
+      #
+      # Compute and store new value for key if the key is absent. This method is atomic.
+      #
+      # @param [String] key
+      # @yieldreturn [Object] new value
+      # @return [Object] new value or current value
+      #
+      def compute_if_absent(key, &block)
+        get(key.to_s, &block)
+      end
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-5B-5D-3D Hash#[]=
+      def []=(key, value)
+        put(key.to_s, value)
+      end
+      alias_method :store, :[]
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-delete Hash#delete
+      def delete(key)
+        key = key.to_s
+        if block_given?
+          fetch(key) do
+            return yield(key)
+          end
+        end
+        remove(key)
+      end
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-fetch Hash#fetch
+      #
+      # @example
+      #   shared_cache.fetch(:key_from_another_script) # raises NoKeyError
+      #
+      def fetch(key, *default_value)
+        if default_value.length > 1
+          raise ArgumentError,
+                "wrong number of arguments (given #{default_value.length + 1}, expected 0..1)"
+        end
+
+        key = key.to_s
+        if default_value.empty?
+          if block_given?
+            get(key) do
+              return yield(key)
+            end
+          else
+            get(key) do
+              raise KeyError.new("key not found: #{key.inspect}", key: key)
+            end
+          end
+        else
+          get(key) { return default_value.first }
+        end
+      end
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-assoc Hash#assoc
+      def assoc(key)
+        [key, fetch(key) do
+          # return nil directly, without storing a value to the cache
+          return nil
+        end]
+      end
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-dig Hash#dig
+      def dig(key, *identifiers)
+        r = fetch(key) { return nil }
+        r&.dig(*identifiers)
+      end
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-fetch_values Hash#fetch_values
+      def fetch_values(*keys, &block)
+        result = []
+        keys.each do |key|
+          if block
+            result << fetch(key, &block)
+          else
+            has_value = true
+            value = fetch(key) { has_value = false }
+            result << value if has_value
+          end
+        end
+        result
+      end
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-key-3F Hash#key?
+      def key?(key)
+        !!fetch(key) { return false }
+      end
+      alias_method :has_key?, :key?
+      alias_method :include?, :key?
+      alias_method :member?, :key?
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-merge-21 Hash#merge!
+      def merge!(*other_hashes)
+        other_hashes.each do |hash|
+          hash.each do |(k, v)|
+            k = k.to_s
+            if block_given?
+              dup = true
+              old_value = fetch(k) do
+                dup = false
+              end
+              self[k] = dup ? yield(k, old_value, v) : v
+            else
+              self[k] = v
+            end
+          end
+        end
+        self
+      end
+      alias_method :update, :merge!
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-slice Hash#slice
+      def slice(*keys)
+        result = {}
+        keys.each do |k|
+          k = k.to_s
+          result[k] = self[k] if key?(k)
+        end
+        result
+      end
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-to_proc Hash#to_proc
+      def to_proc
+        @to_proc ||= ->(k) { self[k] }
+      end
+
+      # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-values_at Hash#values_at
+      def values_at(*keys)
+        keys.map do |k|
+          self[k]
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  # Contains classes and modules that wrap actual openHAB objects
+  module Core
+    # The openHAB Version. >= 3.4.0 is required.
+    # @return [String]
+    VERSION = org.openhab.core.OpenHAB.version.freeze
+
+    raise "`openhab-scripting` requires openHAB >= 3.4.0" unless Gem::Version.new(VERSION) >= Gem::Version.new("3.4.0")
+
+    # @return [Integer] Number of seconds to wait between checks for automation manager
+    CHECK_DELAY = 10
+    private_constant :CHECK_DELAY
+    class << self
+      #
+      # Wait until openHAB engine ready to process
+      #
+      # @return [void]
+      #
+      # @!visibility private
+      def wait_till_openhab_ready
+        logger.trace("Checking readiness of openHAB")
+        until automation_manager
+          logger.trace("Automation manager not loaded, checking again in #{CHECK_DELAY} seconds.")
+          sleep CHECK_DELAY
+        end
+        logger.trace "Automation manager instantiated, openHAB ready for rule processing."
+      end
+
+      #
+      # @!attribute [r] config_folder
+      # @return [Pathname] The configuration folder path.
+      #
+      def config_folder
+        Pathname.new(org.openhab.core.OpenHAB.config_folder)
+      end
+
+      #
+      # @!attribute [r] automation_manager
+      # @return [org.openhab.core.automation.module.script.rulesupport.shared.ScriptedAutomationManager]
+      #   The openHAB Automation manager.
+      #
+      def automation_manager
+        $se.get("automationManager")
+      end
+
+      #
+      # Imports a specific script extension preset into the global namespace
+      #
+      # @param [String] preset
+      # @return [void]
+      #
+      def import_preset(preset)
+        import_scope_values($se.import_preset(preset))
+      end
+
+      #
+      # Imports all default script extension presets into the global namespace
+      #
+      # @!visibility private
+      # @return [void]
+      #
+      def import_default_presets
+        $se.default_presets.each { |preset| import_preset(preset) }
+      end
+
+      #
+      # Imports concrete scope values into the global namespace
+      #
+      # @param [java.util.Map<String, Object>] scope_values
+      # @!visibility private
+      # @return [void]
+      #
+      def import_scope_values(scope_values)
+        scope_values.for_each do |key, value|
+          # convert Java classes to Ruby classes
+          value = value.ruby_class if value.is_a?(java.lang.Class) # rubocop:disable Lint/UselessAssignment
+          # variables are globals; constants go into the global namespace
+          key = case key[0]
+                when "a".."z" then "$#{key}"
+                when "A".."Z" then "::#{key}"
+                end
+          eval("#{key} = value unless defined?(#{key})", nil, __FILE__, __LINE__) # rubocop:disable Security/Eval
+        end
+      end
+    end
+
+    import_default_presets unless defined?($ir)
+  end
+end
+
+# several classes rely on this, so force it to load earlier
+require_relative "core/provider"
+
+Dir[File.expand_path("core/**/*.rb", __dir__)].sort.each do |f|
+  require f
+end

data/lib/openhab/core_ext/between.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module CoreExt
+    # Extensions that apply to both Date and Time classes
+    module Between
+      #
+      # Checks whether the the object falls between the given range.
+      #
+      # @overload between?(min, max)
+      #   @param [Object] min The minimum value to check, inclusive
+      #   @param [Object] max The maximum value to check, inclusive
+      #   @return [true,false]
+      #
+      # @overload between?(range)
+      #   @param [Range] range A range to check
+      #   @return [true,false]
+      #
+      def between?(min, max = nil)
+        range = if max
+                  Range.new(min, max, false)
+                else
+                  raise ArgumentError, "Expecting a range when given a single argument" unless min.is_a?(Range)
+
+                  min
+                end
+
+        OpenHAB::DSL.between(range).cover?(self)
+      end
+    end
+  end
+end

data/lib/openhab/core_ext/ephemeris.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module CoreExt
+    #
+    # Forwards ephemeris helper methods to `#to_zoned_date_time` provided by
+    # the mixed-in class.
+    #
+    # @note openHAB's built-in holiday definitions are based on _bank_
+    #   holidays, so may give some unexpected results. For example, 2022-12-25
+    #   is _not_ Christmas in England because it lands on a Sunday that year,
+    #   so Christmas is considered to be 2022-12-26. See
+    #   [the source](https://github.com/svendiedrichsen/jollyday/tree/master/src/main/resources/holidays)
+    #   for exact definitions. You can always provide your own holiday
+    #   definitions with {OpenHAB::DSL.holiday_file holiday_file} or
+    #   {OpenHAB::DSL.holiday_file! holiday_file!}.
+    #
+    # @see https://www.openhab.org/docs/configuration/actions.html#ephemeris Ephemeris Action
+    # @see Core::Actions::Ephemeris.holiday_name Ephemeris.holiday_name
+    #
+    module Ephemeris
+      # (see Java::ZonedDateTime#holiday)
+      def holiday(holiday_file = nil)
+        to_zoned_date_time.holiday(holiday_file)
+      end
+
+      # (see Java::ZonedDateTime#holiday?)
+      def holiday?(holiday_file = nil)
+        to_zoned_date_time.holiday?(holiday_file)
+      end
+
+      # (see Java::ZonedDateTime#next_holiday)
+      def next_holiday(holiday_file = nil)
+        to_zoned_date_time.next_holiday(holiday_file)
+      end
+
+      # (see Java::ZonedDateTime#weekend?)
+      def weekend?
+        to_zoned_date_time.weekend?
+      end
+
+      # (see Java::ZonedDateTime#in_dayset?)
+      def in_dayset?(set)
+        to_zoned_date_time.in_dayset?(set)
+      end
+
+      # (see Java::ZonedDateTime#days_until)
+      def days_until(holiday, holiday_file = nil)
+        to_zoned_date_time.days_until(holiday, holiday_file)
+      end
+    end
+  end
+end

data/lib/openhab/core_ext/java/class.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module CoreExt
+    module Java
+      Class = java.lang.Class
+
+      # Extensions to Class
+      class Class
+        #
+        # `self`, all superclasses and interfaces, recursively.
+        #
+        # @return [Array<Class>]
+        #
+        def ancestors
+          ([self] +
+            Array(superclass&.ancestors) +
+            interfaces.flat_map(&:ancestors)).uniq
+        end
+
+        #
+        # `self`, all superclasses and interfaces, recursively.
+        #
+        # @return [Array<java.lang.reflect.Type>]
+        #
+        def generic_ancestors
+          ancestors.flat_map do |klass|
+            Array(klass.generic_superclass) + klass.generic_interfaces
+          end.uniq
+        end
+      end
+    end
+  end
+end