openhab-jrubyscripting 5.0.0.rc4 → 5.0.0.rc6

data/lib/openhab/dsl.rb

@@ -16,7 +16,7 @@ end
 require_relative "core_ext"
 
 #
-# Main OpenHAB Module
+# Main openHAB Module
 #
 module OpenHAB
   #
@@ -69,7 +69,7 @@ module OpenHAB
     #   The state being sent for `:state_from_item` and `:state_from_handler` events.
     # @yieldparam [Core::Things::ItemChannelLink] link
     #   The link between the item and the channel, including its configuration.
-    # @yieldparam [GenericItem] item The linked item.
+    # @yieldparam [Item] item The linked item.
     # @yieldparam [Core::Things::ChannelUID] channel_uid The linked channel.
     # @yieldparam [Hash] configuration The profile configuration.
     # @yieldparam [org.openhab.core.thing.profiles.ProfileContext] context The profile context.
@@ -106,6 +106,19 @@ module OpenHAB
 
     # @!group Object Access
 
+    #
+    # (see Core::ValueCache)
+    #
+    # @return [Core::ValueCache] the cache shared among all scripts and UI rules in all languages.
+    #
+    # @see Core::ValueCache ValueCache
+    #
+    # @since openHAB 3.4.0
+    #
+    def shared_cache
+      $sharedCache
+    end
+
     #
     # Fetches all rules from the rule registry.
     #
@@ -141,7 +154,7 @@ module OpenHAB
     #
     # @example
     #   rule 'search for a suitable item' do
-    #     on_start
+    #     on_load
     #     triggered do
     #       # Send ON to DimmerTest if it exists, otherwise send it to SwitchTest
     #       (items['DimmerTest'] || items['SwitchTest'])&.on
@@ -153,9 +166,9 @@ module OpenHAB
     end
 
     #
-    # Get all things known to OpenHAB
+    # Get all things known to openHAB
     #
-    # @return [Core::Things::Registry] all Thing objects known to OpenHAB
+    # @return [Core::Things::Registry] all Thing objects known to openHAB
     #
     # @example
     #   things.each { |thing| logger.info("Thing: #{thing.uid}")}
@@ -171,7 +184,7 @@ module OpenHAB
     end
 
     #
-    # Provides access to timers created by {after}
+    # Provides access to timers created by {after after}
     #
     # @return [TimerManager]
     def timers
@@ -186,7 +199,8 @@ module OpenHAB
     # ### Reentrant Timers
     #
     # Timers with an id are reentrant by id. Reentrant means that when the same id is encountered,
-    # the timer is rescheduled rather than creating a second new timer.
+    # the timer is rescheduled rather than creating a second new timer. Note that the timer will
+    # execute the block provided in the latest call.
     #
     # This removes the need for the usual boilerplate code to manually keep track of timer objects.
     #
@@ -194,7 +208,7 @@ module OpenHAB
     #
     # When a timer is cancelled, it will be removed from the object.
     #
-    # Be sure that your ids are unique. For example, if you're using {GenericItem items} as your
+    # Be sure that your ids are unique. For example, if you're using {Item items} as your
     # ids, you either need to be sure you don't use the same item for multiple logical contexts,
     # or you need to make your id more specific, by doing something like embedding the item in
     # array with a symbol of the timer's purpose, like `[:vacancy, item]`. But also note that
@@ -221,7 +235,7 @@ module OpenHAB
     #     logger.info("Timer Fired")
     #   end
     #
-    # @example Timers delegate methods to OpenHAB timer objects
+    # @example Timers delegate methods to openHAB timer objects
     #   after 1.second do |timer|
     #     logger.info("Timer is active? #{timer.active?}")
     #   end
@@ -267,9 +281,21 @@ module OpenHAB
     #   end
     #
     # @example Only create a new timer if it isn't already scheduled
-    #  after(1.minute, id: :foo, reschedule: false) do
-    #    logger.info("Timer fired")
-    #  end
+    #   after(1.minute, id: :foo, reschedule: false) do
+    #     logger.info("Timer fired")
+    #   end
+    #
+    # @example Reentrant timers will execute the block from the most recent call
+    #   # In the following example, if Item1 received a command, followed by Item2,
+    #   # the timer will execute the block referring to Item2.
+    #   rule "Execute The Most Recent Block" do
+    #     received_command Item1, Item2
+    #     run do |event|
+    #       after(10.minutes, id: :common_timer) do
+    #         logger.info "The latest command was received from #{event.item}"
+    #       end
+    #     end
+    #   end
     #
     def after(duration, id: nil, reschedule: true, &block)
       raise ArgumentError, "Block is required" unless block
@@ -299,6 +325,8 @@ module OpenHAB
     # @example Create a time range
     #   between('7am'..'12pm').cover?(LocalTime.now)
     #
+    # @see CoreExt::Between#between? #between?
+    #
     def between(range)
       raise ArgumentError, "Supplied object must be a range" unless range.is_a?(Range)
 
@@ -311,10 +339,10 @@ module OpenHAB
     # Store states of supplied items
     #
     # Takes one or more items and returns a map `{Item => State}` with the
-    # current state of each item. It is implemented by calling OpenHAB's
+    # current state of each item. It is implemented by calling openHAB's
     # [events.storeStates()](https://www.openhab.org/docs/configuration/actions.html#event-bus-actions).
     #
-    # @param [GenericItem] items Items to store states of.
+    # @param [Item] items Items to store states of.
     #
     # @return [Core::Items::StateStorage] item states
     #
@@ -601,7 +629,7 @@ module OpenHAB
     #   Otherwise it's applied to all types.
     # @param [Hash] providers_by_type
     #     A list of providers by type. Type can be `:items`, `:metadata`, `:things`, `:links`,
-    #     a {GenericItem} applying the provider to all metadata on that item, or a String or Symbol
+    #     an {Item} applying the provider to all metadata on that item, or a String or Symbol
     #     applying the provider to all metadata of that namespace.
     #
     #     The provider can be a {org.openhab.core.common.registry.Provider Provider}, `:persistent`,
@@ -665,7 +693,7 @@ module OpenHAB
           thread_providers[type] = provider
         when Symbol, String
           (thread_providers[:metadata_namespaces] ||= {})[type.to_s] = provider
-        when GenericItem
+        when Item
           (thread_providers[:metadata_items] ||= {})[type.name] = provider
         else
           raise ArgumentError, "#{type.inspect} is not provider type"
@@ -700,4 +728,4 @@ OpenHAB::Core::Items.import_into_global_namespace
 # Extend `main` with DSL methods
 singleton_class.include(OpenHAB::DSL)
 
-logger.debug "OpenHAB JRuby Scripting Library Version #{OpenHAB::DSL::VERSION} Loaded"
+logger.debug "openHAB JRuby Scripting Library Version #{OpenHAB::DSL::VERSION} Loaded"

data/lib/openhab/log.rb

@@ -6,7 +6,7 @@ module OpenHAB
   # rubocop:disable Layout/LineLength
 
   #
-  # Provides access to the OpenHAB logging facilities using Ruby logging methods
+  # Provides access to the openHAB logging facilities using Ruby logging methods
   #
   # Logging is available everywhere through the {#logger} object.
   #
@@ -26,7 +26,7 @@ module OpenHAB
   # @example The following entries are in a file named 'log_test.rb'
   #   rule 'foo' do
   #     run { logger.trace('Test logging at trace') } # 2020-12-03 18:05:20.903 [TRACE] [org.openhab.automation.jrubyscripting.foo] - Test logging at trace
-  #     on_start
+  #     on_load
   #   end
   #
   #
@@ -122,7 +122,7 @@ module OpenHAB
   end
 
   #
-  # Ruby Logger that forwards messages at appropriate levels to OpenHAB Logger
+  # Ruby Logger that forwards messages at appropriate levels to openHAB Logger
   #
   class Logger
     # The base prefix for all loggers from this gem.
@@ -150,7 +150,7 @@ module OpenHAB
     private_constant :JAVA_INTERNAL_CALL_REGEX
 
     class << self
-      # The root logger (all of OpenHAB)
+      # The root logger (all of openHAB)
       # @return [Logger]
       def root
         Log.logger(org.slf4j.Logger::ROOT_LOGGER_NAME)
@@ -299,7 +299,7 @@ module OpenHAB
     end
 
     #
-    # Log a message to the OpenHAB Logger
+    # Log a message to the openHAB Logger
     #
     # @param [Symbol] severity Severity to log message at
     # @param [Object] msg to log, if no msg supplied and a block is provided,

data/lib/openhab/rspec/configuration.rb

@@ -3,13 +3,13 @@
 module OpenHAB
   module RSpec
     #
-    # Contains configuration for how the OpenHAB instance should be set
+    # Contains configuration for how the openHAB instance should be set
     # up for the testing environment.
     #
     module Configuration
       class << self
         #
-        # Copy binding configuration from the root OpenHAB instance.
+        # Copy binding configuration from the root openHAB instance.
         #
         # Default `true`.
         # @return [true, false]
@@ -18,7 +18,7 @@ module OpenHAB
 
         #
         # Copy the JSONDB (managed thing and item configuration) from the root
-        # OpenHAB instance.
+        # openHAB instance.
         #
         # Default `true`.
         #
@@ -28,7 +28,7 @@ module OpenHAB
 
         #
         # Use a private (empty) confdir (scripts, rules, items, and things
-        # files), instead of sharing with the root OpenHAB instance.
+        # files), instead of sharing with the root openHAB instance.
         #
         # Default `false`.
         #
@@ -37,7 +37,7 @@ module OpenHAB
         attr_accessor :private_confdir
 
         #
-        # Use the root OpenHAB instance directly, rather than creating a
+        # Use the root openHAB instance directly, rather than creating a
         # private (but linked) instance.
         #
         # Default `false`.

data/lib/openhab/rspec/example_group.rb

@@ -94,7 +94,7 @@ module OpenHAB
         #     it "logs exceptions in rule execution" do
         #       expect(self.class.propagate_exceptions?).to be false
         #       rule do
-        #         on_start
+        #         on_load
         #         run { raise "exception is logged" }
         #       end
         #       expect(spec_log_lines).to include(match(/exception is logged/))

data/lib/openhab/rspec/helpers.rb

@@ -52,7 +52,7 @@ module OpenHAB
   module RSpec
     #
     # Provides helper methods for use in specs, to easily work with and adjust
-    # the OpenHAB environment.
+    # the openHAB environment.
     #
     # These methods are automatically available in RSpec spec blocks, as well
     # as other per-spec hooks like `before` and `after`. You can also call them
@@ -124,7 +124,7 @@ module OpenHAB
       #
       def time_travel_and_execute_timers(duration)
         if self.class.mock_timers?
-          Timecop.travel(duration)
+          Timecop.frozen? ? Timecop.freeze(duration) : Timecop.travel(duration)
           execute_timers
         else
           sleep duration
@@ -175,7 +175,7 @@ module OpenHAB
       end
 
       #
-      # Require all files configured to be autorequired with the jrubyscripting addon in OpenHAB.
+      # Require all files configured to be autorequired with the jrubyscripting addon in openHAB.
       #
       # This method is normally called by RSpec hooks.
       #
@@ -306,7 +306,7 @@ module OpenHAB
       end
 
       #
-      # Install an OpenHAB addon
+      # Install an openHAB addon
       #
       # @param [String] addon_id The addon id, such as "binding-mqtt"
       # @param [true,false] wait Wait until OSGi has confirmed the bundle is installed and running before returning.
@@ -348,7 +348,7 @@ module OpenHAB
         end
       end
 
-      # @return [String] The filename of the OpenHAB log.
+      # @return [String] The filename of the openHAB log.
       def log_file
         "#{java.lang.System.get_property("openhab.logdir", nil)}/openhab.log"
       end

data/lib/openhab/rspec/hooks.rb

@@ -3,7 +3,7 @@
 module OpenHAB
   #
   # This module contains helper methods, hooks, and infrastracture to
-  # boot OpenHAB inside of JRuby, and run RSpec (or other Ruby processes)
+  # boot openHAB inside of JRuby, and run RSpec (or other Ruby processes)
   # in that context.
   #
   # @see file:testing.md Testing Your Rules
@@ -11,6 +11,14 @@ module OpenHAB
   module RSpec
     Object.include Helpers if defined?(IRB)
 
+    # @!visibility private
+    module Hooks
+      class << self
+        attr_accessor :cache_script_extension
+      end
+      self.cache_script_extension = nil
+    end
+
     Helpers.launch_karaf(
       include_bindings: Configuration.include_bindings,
       include_jsondb: Configuration.include_jsondb,
@@ -28,6 +36,15 @@ module OpenHAB
           Helpers.send(:set_up_autoupdates)
           Helpers.load_transforms
           Helpers.load_rules
+
+          if DSL.shared_cache
+            Hooks.cache_script_extension = OSGi.service(
+              "org.openhab.core.automation.module.script.ScriptExtensionProvider",
+              filter:
+                "(component.name=org.openhab.core.automation.module.script.rulesupport.internal.CacheScriptExtension)"
+            )
+            Hooks.cache_script_extension.class.field_reader :sharedCache
+          end
         end
 
         config.before do
@@ -79,6 +96,7 @@ module OpenHAB
           Timecop.return
           restore_autoupdate_items
           Mocks::PersistenceService.instance.reset
+          Hooks.cache_script_extension.sharedCache.clear if DSL.shared_cache
         end
       end
     end

data/lib/openhab/rspec/karaf.rb

@@ -20,6 +20,14 @@ module OpenHAB
         def get(type)
           @manager.get(type, "jruby")
         end
+
+        def default_presets
+          @manager.default_presets
+        end
+
+        def import_preset(preset)
+          @manager.find_preset(preset, "rspec")
+        end
       end
       private_constant :ScriptExtensionManagerWrapper
 
@@ -73,7 +81,7 @@ module OpenHAB
         service = org.apache.karaf.instance.core.internal.InstanceServiceImpl.new
         settings = org.apache.karaf.instance.core.InstanceSettings.new(0, 0, 0, path, nil, nil, nil)
         root_instance = service.instances.find(&:root?)
-        raise ArgumentError "No root instance found to clone... has OpenHAB run yet?" unless root_instance
+        raise ArgumentError "No root instance found to clone... has openHAB run yet?" unless root_instance
 
         return if service.get_instance("rspec")
 
@@ -121,7 +129,7 @@ module OpenHAB
         launch_karaf
         at_exit do
           @main.destroy
-          # OSGi/OpenHAB leave a ton of threads around. Kill ourselves ASAP
+          # OSGi/openHAB leave a ton of threads around. Kill ourselves ASAP
           code = if $!.nil? || ($!.is_a?(SystemExit) && $!.success?)
                    0
                  elsif $!.is_a?(SystemExit)
@@ -351,8 +359,7 @@ module OpenHAB
       }.freeze
       private_constant :BLOCKED_COMPONENTS
 
-      START_LEVEL_OVERRIDES = {
-      }.freeze
+      START_LEVEL_OVERRIDES = {}.freeze
       private_constant :START_LEVEL_OVERRIDES
 
       def set_up_bundle_listener
@@ -567,21 +574,6 @@ module OpenHAB
         wait_for_service("org.openhab.core.automation.module.script.internal.ScriptExtensionManager") do |sem|
           # since we're not created by the ScriptEngineManager, this never gets set; manually set it
           $se = $scriptExtension = ScriptExtensionManagerWrapper.new(sem)
-          scope_values = sem.find_default_presets("rspec")
-          scope_values = scope_values.entry_set.to_a
-
-          scope_values.each do |entry|
-            key = entry.key
-            value = entry.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
 
@@ -732,7 +724,7 @@ module OpenHAB
         sls = OSGi.service("org.openhab.core.service.StartLevelService")
 
         unless sls
-          # try a different (hacky!) way to get it, since in OpenHAB 3.2.0 it's not exposed as a service
+          # try a different (hacky!) way to get it, since in openHAB 3.2.0 it's not exposed as a service
           scr = OSGi.service("org.osgi.service.component.runtime.ServiceComponentRuntime")
           scr.class.field_reader :componentRegistry
           cr = scr.componentRegistry
@@ -772,7 +764,7 @@ module OpenHAB
         File.write("#{oh_userdata}/etc/org.apache.karaf.features.xml", <<~XML)
           <?xml version="1.0" encoding="UTF-8"?>
           <featuresProcessing xmlns="http://karaf.apache.org/xmlns/features-processing/v1.0.0" xmlns:f="http://karaf.apache.org/xmlns/features/v1.6.0">
-              <!-- From OpenHAB 3.2.0 -->
+              <!-- From openHAB 3.2.0 -->
               <bundleReplacements>
                 <bundle originalUri="mvn:org.ops4j.pax.logging/pax-logging-api/[0,2.0.13)" replacement="mvn:org.ops4j.pax.logging/pax-logging-api/2.0.13" mode="maven" />
                 <bundle originalUri="mvn:org.ops4j.pax.logging/pax-logging-log4j2/[0,2.0.13)" replacement="mvn:org.ops4j.pax.logging/pax-logging-log4j2/2.0.13" mode="maven" />

data/lib/openhab/rspec/mocks/persistence_service.rb

@@ -19,6 +19,21 @@ module OpenHAB
           end
         end
 
+        module HistoricState
+          def timestamp
+            # PersistenceExtensions uses an anonymous class to wrap the current
+            # state if that happens to be an answer. Except it calls
+            # ZonedDateTime.now in Java land, bypassing Timecop.
+            # Detect that and make the call in Ruby
+            #
+            jc = @historic_item.class.java_class
+            return ZonedDateTime.now if jc.anonymous? && jc.enclosing_class == PersistenceExtensions.java_class
+
+            super
+          end
+        end
+        Core::Items::Persistence::HistoricState.prepend(HistoricState)
+
         attr_reader :id
 
         def initialize

data/lib/openhab/rspec/mocks/thing_handler.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Naming have to follow java interface names
+# rubocop:disable Naming/MethodName, Naming/AccessorMethodName
 
 require "singleton"
 
@@ -73,4 +73,4 @@ module OpenHAB
     end
   end
 end
-# rubocop:enable Naming
+# rubocop:enable Naming/MethodName, Naming/AccessorMethodName

data/lib/openhab/rspec/suspend_rules.rb

@@ -18,7 +18,8 @@ module OpenHAB
             logger.trace { "Execute called with mod (#{mod&.to_string}) and inputs (#{inputs.inspect})" }
             logger.trace { "Event details #{inputs["event"].inspect}" } if inputs&.key?("event")
             trigger_conditions(inputs).process(mod: mod, inputs: inputs) do
-              process_queue(create_queue(inputs), mod, inputs)
+              event = extract_event(inputs)
+              process_queue(create_queue(event), mod, event)
             end
           rescue Exception => e
             raise if defined?(::RSpec) && ::RSpec.current_example.example_group.propagate_exceptions?

data/lib/openhab/yard/base_helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module OpenHAB
+  module YARD
+    # @!visibility private
+    module BaseHelper
+      def preprocess(text)
+        html = Nokogiri::HTML5.fragment(text)
+
+        context = if ENV["ADDON"]
+                    :addon
+                  else
+                    :yard
+                  end
+
+        # process directives on which content is supposed to be included in this context
+        node = html.children.first
+        loop do
+          break unless node
+
+          next_node = node.next
+
+          if node.comment? && (directive = MarkdownDirective.new(node)).directive?
+            next_node = directive.process(context) || next_node
+          end
+          node = next_node
+        end
+
+        html.to_s
+      end
+
+      def link_object(obj, title = nil, *)
+        ::YARD::Handlers::JRuby::Base.infer_java_class(obj) if obj.is_a?(String)
+        obj = ::YARD::Registry.resolve(object, obj, true, true) if obj.is_a?(String)
+        if obj.is_a?(::YARD::CodeObjects::Java::Base) && (see = obj.docstring.tag(:see))
+          # link to the first see tag
+          return linkify(see.name, title&.to_s || see.text)
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/openhab/yard/html_helper.rb

@@ -16,8 +16,8 @@ module OpenHAB
 
       # have to completely replace this method. only change is the regex splitting
       # into parts now allows `.` as part of the identifier
-      # rubocop:disable Style
-      def format_types(typelist, brackets = true)
+      # rubocop:disable Style/NestedTernaryOperator, Style/StringConcatenation, Style/TernaryParentheses
+      def format_types(typelist, brackets = true) # rubocop:disable Style/OptionalBooleanParameter
         return unless typelist.is_a?(Array)
 
         list = typelist.map do |type|
@@ -27,7 +27,7 @@ module OpenHAB
         end
         list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
       end
-      # rubocop:enable Style
+      # rubocop:enable Style/NestedTernaryOperator, Style/StringConcatenation, Style/TernaryParentheses
 
       def link_object(obj, title = nil, *)
         ::YARD::Handlers::JRuby::Base.infer_java_class(obj) if obj.is_a?(String)

data/lib/openhab/yard/markdown_directive.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module OpenHAB
+  module YARD
+    # @!visibility private
+    class MarkdownDirective
+      attr_reader :comment, :context
+
+      def initialize(comment)
+        @comment = comment
+        @lines = comment.text.split("\n")
+        directive_text = @lines.first.strip
+
+        @multiline = @lines.length > 1
+        @directive = false
+        return unless (match = directive_text.match(%r{^<(/)?(!)?([a-z]+)-only>$}))
+
+        @closing = match[1]
+        @context = match[3].to_sym
+        @inverted = match[2]
+
+        if closing? && multiline?
+          log.warn "In file `#{file}':#{line}: Multiline closing directives are not allowed (#{directive_text})."
+          return
+        end
+        @directive = true
+      end
+
+      def directive?
+        @directive
+      end
+
+      def multiline?
+        @multiline
+      end
+
+      def closing?
+        @closing
+      end
+
+      def inverted?
+        @inverted
+      end
+
+      def match?(context)
+        result = context == self.context
+        result = !result if inverted?
+        result
+      end
+
+      def closing_directive
+        return nil if multiline?
+
+        unless instance_variable_defined?(:@closing_directive)
+          next_node = @comment.next
+          loop do
+            return @closing_directive = nil unless next_node
+
+            if next_node.comment?
+              directive = MarkdownDirective.new(next_node)
+              if directive.directive? &&
+                 directive.closing? &&
+                 directive.context == context &&
+                 directive.inverted? == inverted?
+                return @closing_directive = next_node
+              end
+            end
+
+            next_node = next_node.next
+          end
+        end
+        @closing_directive
+      end
+
+      def process(context)
+        return unless directive?
+        return if closing?
+
+        matched = match?(context)
+
+        # if it's a matched multiline, extract the contents and insert them directly,
+        # and remove the comment
+        if multiline?
+          result = comment.next
+          comment.before(Nokogiri::HTML5.fragment(@lines[1..].join("\n"))) if matched
+          comment.remove
+          return result
+        end
+
+        unless closing_directive
+          log.warn "In file `#{file}':#{line}: Unmatched directive <#{"!" if inverted?}#{context}-only>."
+          return
+        end
+
+        result = closing_directive.next
+
+        unless matched
+          # remove all nodes between the opening and closing directives
+          comment.next.remove while comment.next != closing_directive
+        end
+        # now remove the directives themselves
+        closing_directive.remove
+        comment.remove
+        result
+      end
+
+      def file
+        ((defined?(@file) && @file) ? @file.filename : object.file) || "(unknown)"
+      end
+
+      def line
+        return @line if instance_variable_defined?(@line)
+
+        @line = (if defined?(@file) && @file
+                   1
+                 else
+                   (object.docstring.line_range ? object.docstring.line_range.first : 1)
+                 end) + (match ? $`.count("\n") : 0)
+        @line += comment.line - 1
+      end
+    end
+  end
+end