openhab-jrubyscripting 5.0.0.rc4 → 5.0.0.rc6

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://ruby-doc.org/core-3.1.2/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://ruby-doc.org/core-3.1.2/Hash.html#method-i-5B-5D-3D Hash#[]=
+      def []=(key, value)
+        put(key.to_s, value)
+      end
+      alias_method :store, :[]
+
+      # @see https://ruby-doc.org/core-3.1.2/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://ruby-doc.org/core-3.1.2/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://ruby-doc.org/core-3.1.2/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://ruby-doc.org/core-3.1.2/Hash.html#method-i-dig Hash#dig
+      def dig(key, *identifiers)
+        r = fetch(key) { return nil }
+        r&.dig(*identifiers)
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/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://ruby-doc.org/core-3.1.2/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://ruby-doc.org/core-3.1.2/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://ruby-doc.org/core-3.1.2/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://ruby-doc.org/core-3.1.2/Hash.html#method-i-to_proc Hash#to_proc
+      def to_proc
+        @to_proc ||= ->(k) { self[k] }
+      end
+
+      # @see https://ruby-doc.org/core-3.1.2/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

@@ -1,21 +1,14 @@
 # frozen_string_literal: true
 
-# 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
-
 module OpenHAB
-  # Contains classes and modules that wrap actual OpenHAB objects
+  # Contains classes and modules that wrap actual openHAB objects
   module Core
-    # The OpenHAB Version. >= 3.3.0 is required.
+    # The openHAB Version. >= 3.3.0 is required.
     # @return [String]
     VERSION = org.openhab.core.OpenHAB.version.freeze
 
     unless Gem::Version.new(VERSION) >= Gem::Version.new("3.3.0")
-      raise "`openhab-jrubyscripting` requires OpenHAB >= 3.3.0"
+      raise "`openhab-jrubyscripting` requires openHAB >= 3.3.0"
     end
 
     # @return [Integer] Number of seconds to wait between checks for automation manager
@@ -23,18 +16,18 @@ module OpenHAB
     private_constant :CHECK_DELAY
     class << self
       #
-      # Wait until OpenHAB engine ready to process
+      # Wait until openHAB engine ready to process
       #
       # @return [void]
       #
       # @!visibility private
       def wait_till_openhab_ready
-        logger.trace("Checking readiness of OpenHAB")
+        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."
+        logger.trace "Automation manager instantiated, openHAB ready for rule processing."
       end
 
       #
@@ -48,11 +41,60 @@ module OpenHAB
       #
       # @!attribute [r] automation_manager
       # @return [org.openhab.core.automation.module.script.rulesupport.shared.ScriptedAutomationManager]
-      #   The OpenHAB Automation manager.
+      #   The openHAB Automation manager.
       #
       def automation_manager
-        $scriptExtension.get("automationManager")
+        $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
   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/java/duration.rb

@@ -7,6 +7,7 @@ module OpenHAB
 
       # Extensions to Duration
       class Duration
+        include Between
         # @!parse include TemporalAmount
 
         alias_method :to_i, :seconds

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

@@ -10,6 +10,7 @@ module OpenHAB
       # Extensions to LocalDate
       class LocalDate
         include Time
+        include Between
 
         class << self # rubocop:disable Lint/EmptyClass
           # @!attribute [r] now

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

@@ -33,6 +33,7 @@ module OpenHAB
       #   end
       #
       class LocalTime
+        include Between
         # @!parse include Time
 
         # @!visibility private

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

@@ -9,8 +9,19 @@ module OpenHAB
 
       # Extensions to Month
       class Month
+        include Between
         # @!parse include Time
 
+        # @return [Month]
+        def +(other)
+          plus(other)
+        end
+
+        # @return [Month]
+        def -(other)
+          minus(other)
+        end
+
         #
         # Returns the next month
         #
@@ -49,7 +60,7 @@ module OpenHAB
         #   during conversion. {ZonedDateTime.now} is assumed if not given.
         # @return [ZonedDateTime]
         def to_zoned_date_time(context = nil)
-          to_local_date(context).to_zoned_date_time
+          to_local_date(context).to_zoned_date_time(context)
         end
       end
     end

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

@@ -9,6 +9,8 @@ module OpenHAB
 
       # Extensions to MonthDay
       class MonthDay
+        include Between
+
         class << self
           #
           # Parses strings in the form "M-d"

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

@@ -10,6 +10,7 @@ module OpenHAB
       # Extensions to ZonedDateTime
       class ZonedDateTime
         include Time
+        include Between
 
         class << self # rubocop:disable Lint/EmptyClass
           # @!attribute [r] now
@@ -91,11 +92,10 @@ module OpenHAB
           # compare instants, otherwise it will differ by timezone, which we don't want
           # (use eql? if you care about that)
           if other.respond_to?(:to_zoned_date_time)
-            return to_instant.compare_to(other.to_zoned_date_time(self).to_instant)
+            to_instant.compare_to(other.to_zoned_date_time(self).to_instant)
+          elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(self))
+            lhs <=> rhs
           end
-          return nil unless (lhs, rhs = other.coerce(self))
-
-          lhs <=> rhs
         end
 
         #

data/lib/openhab/core_ext/ruby/date.rb

@@ -4,6 +4,8 @@ require "date"
 
 # Extensions to Date
 class Date
+  include OpenHAB::CoreExt::Between
+
   #
   # Extends {#+} to allow adding a {java.time.temporal.TemporalAmount TemporalAmount}
   #
@@ -65,7 +67,7 @@ class Date
 
     return self <=> other.to_date(self) if other.is_a?(java.time.MonthDay)
 
-    if other.respond_to?(:coerce) && (lhs, rhs = coerce(self))
+    if other.respond_to?(:coerce) && (lhs, rhs = other.coerce(self))
       return lhs <=> rhs
     end
 

data/lib/openhab/core_ext/ruby/date_time.rb

@@ -10,6 +10,7 @@ require "forwardable"
 # Extensions to DateTime
 class DateTime < Date
   extend Forwardable
+  include OpenHAB::CoreExt::Between
 
   # (see Time#plus_with_temporal)
   def plus_with_temporal(other)

data/lib/openhab/core_ext/ruby/symbol.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Extensions to Symbol
+class Symbol
+  # Ruby 3.0 already has #name
+  alias_method :name, :to_s unless instance_methods.include?(:name)
+end

data/lib/openhab/core_ext/ruby/time.rb

@@ -5,6 +5,7 @@ require "forwardable"
 # Extensions to Time
 class Time
   extend Forwardable
+  include OpenHAB::CoreExt::Between
 
   #
   # @!method +(other)

data/lib/openhab/dsl/items/builder.rb

@@ -3,36 +3,40 @@
 module OpenHAB
   module DSL
     #
-    # Contains extensions to simplify working with [GenericItem]s.
+    # Contains extensions to simplify working with {Item Items}.
     #
     module Items
-      # An item builder allows you to dynamically create OpenHAB items at runtime.
+      # An item builder allows you to dynamically create openHAB items at runtime.
       # This can be useful either to create items as soon as the script loads,
       # or even later based on a rule executing.
       #
       # @example
       #   items.build do
-      #     switch_item "MySwitch", "My Switch"
-      #     switch_item "NotAutoupdating", autoupdate: false, channel: "mqtt:topic:1#light"
-      #     group_item "MyGroup" do
-      #       contact_item "ItemInGroup", channel: "binding:thing#channel"
+      #     switch_item MySwitch, "My Switch"
+      #     switch_item NotAutoupdating, autoupdate: false, channel: "mqtt:topic:1#light"
+      #     group_item MyGroup do
+      #       contact_item ItemInGroup, channel: "binding:thing#channel"
       #     end
       #     # passing `thing` to a group item will automatically use it as the base
       #     # for item channels
-      #     group_item "Equipment", tags: Semantics::HVAC, thing: "binding:thing"
-      #       string_item "Mode", tags: Semantics::Control, channel: "mode"
+      #     group_item Equipment, tags: Semantics::HVAC, thing: "binding:thing"
+      #       string_item Mode, tags: Semantics::Control, channel: "mode"
       #     end
       #   end
+      #
       module Builder
         include Core::EntityLookup
 
+        self.create_dummy_items = true
+
         class << self
           private
 
           # @!macro def_item_method
           #   @!method $1_item(name, label = nil, **kwargs)
           #   Create a new $1 item
-          #   @param name [String] The name for the new item
+          #   @param name [String, Symbol, Core::Items::Proxy] The name for the new item.
+          #     Note that you can use a string, a symbol, or even a literal constant name
           #   @param label [String] The item label
           #   @yieldparam [ItemBuilder] builder Item for further customization
           #   @see ItemBuilder#initialize ItemBuilder#initialize for additional arguments.
@@ -233,6 +237,7 @@ module OpenHAB
           raise ArgumentError, "`name` cannot be nil" if name.nil?
           raise ArgumentError, "`dimension` can only be specified with NumberItem" if dimension && type != :number
 
+          name = name.name if name.respond_to?(:name)
           if provider.is_a?(GroupItemBuilder)
             name = "#{provider.name_base}#{name}"
             label = "#{provider.label_base}#{label}".strip if label
@@ -365,7 +370,7 @@ module OpenHAB
         #
         # @example
         #   items.build do
-        #     date_time_item "Bedroom_Light_Updated" do
+        #     date_time_item Bedroom_Light_Updated do
         #       channel "hue:0210:1:bulb1:color", profile: "system:timestamp-update"
         #     end
         #   end
@@ -469,6 +474,8 @@ module OpenHAB
         include Builder
 
         Builder.public_instance_methods.each do |m|
+          next unless Builder.instance_method(m).owner == Builder
+
           class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{m}(*args, groups: nil, **kwargs)  # def dimmer_item(*args, groups: nil, **kwargs)
               groups ||= []                         #   groups ||= []

data/lib/openhab/dsl/items/ensure.rb

@@ -7,7 +7,7 @@ module OpenHAB
     module Items
       # Functionality to implement `ensure`/`ensure_states`
       module Ensure
-        # Contains the `ensure` method mixed into {GenericItem} and {GroupItem::Members}
+        # Contains the `ensure` method mixed into {Item} and {GroupItem::Members}
         module Ensurable
           # Fluent method call that you can chain commands on to, that will
           # then automatically ensure that the item is not in the command's
@@ -18,15 +18,15 @@ module OpenHAB
           # @example Turn on all switches in a group that aren't already on
           #   MySwitchGroup.members.ensure.on
           def ensure
-            GenericItemDelegate.new(self)
+            ItemDelegate.new(self)
           end
         end
 
-        # Extensions for {::GenericItem} to implement {Ensure}'s functionality
+        # Extensions for {::Item} to implement {Ensure}'s functionality
         #
         # @see OpenHAB::DSL.ensure ensure
         # @see OpenHAB::DSL.ensure_states ensure_states
-        module GenericItem
+        module Item
           include Ensurable
 
           Core::Items::GenericItem.prepend(self)
@@ -63,7 +63,7 @@ module OpenHAB
         # "anonymous" class that wraps any method call in `ensure_states`
         # before forwarding to the wrapped object
         # @!visibility private
-        class GenericItemDelegate
+        class ItemDelegate
           def initialize(item)
             @item = item
           end

data/lib/openhab/dsl/items/timed_command.rb

@@ -3,7 +3,7 @@
 module OpenHAB
   module DSL
     module Items
-      # Extensions for {GenericItem} to implement timed commands
+      # Extensions for {Item} to implement timed commands
       #
       # All items have an implicit timer associated with them, enabling to
       # easily set an item into a specific state for a specified duration and
@@ -28,7 +28,7 @@ module OpenHAB
         # Provides information about why the expiration block of a
         # {TimedCommand#command timed command} is being called.
         #
-        # @attr [GenericItem] item
+        # @attr [Item] item
         #   @!visibility private
         # @attr [Types::Type, Proc] on_expire
         #   @!visibility private
@@ -205,13 +205,13 @@ module OpenHAB
           #
           # Execute the rule
           #
-          # @param [Map] _mod map provided by OpenHAB rules engine
-          # @param [Map] inputs map provided by OpenHAB rules engine containing event and other information
+          # @param [java.util.Map] _mod map provided by openHAB rules engine
+          # @param [java.util.Map] inputs map provided by openHAB rules engine containing event and other information
           #
           def execute(_mod = nil, inputs = nil)
             ThreadLocal.thread_local(**@thread_locals) do
               @timed_command_details.mutex.synchronize do
-                logger.trace "Canceling implicit timer #{@timed_command_details.timer} for "\
+                logger.trace "Canceling implicit timer #{@timed_command_details.timer} for " \
                              "#{@timed_command_details.item.name}  because received event #{inputs}"
                 @timed_command_details.timer.cancel
                 DSL.rules.remove(@timed_command_details.rule_uid)