openhab-jrubyscripting 5.0.0.rc10 → 5.0.0.rc12

data/lib/openhab/dsl.rb

@@ -37,6 +37,13 @@ module OpenHAB
       public_class_method(*mod.private_instance_methods)
     end
 
+    class << self
+      # @!visibility private
+      attr_reader :debouncers
+    end
+
+    @debouncers = java.util.concurrent.ConcurrentHashMap.new
+
     module_function
 
     # @!group Rule Creation
@@ -53,6 +60,8 @@ module OpenHAB
 
     # @!group Rule Support
 
+    # rubocop:disable Layout/LineLength
+
     #
     # Defines a new profile that can be applied to item channel links.
     #
@@ -79,8 +88,8 @@ module OpenHAB
     # @see org.openhab.thing.Profile
     # @see org.openhab.thing.StateProfile
     #
-    # @example
-    #   profile(:veto_closing_shades) do |event, item:, command: nil|
+    # @example Vetoing a command
+    #   profile(:veto_closing_shades) do |event, item:, command:|
     #     next false if command&.down?
     #
     #     true
@@ -94,9 +103,37 @@ module OpenHAB
     #   # can also be referenced from an `.items` file:
     #   # Rollershutter MyShade { channel="thing:rollershutter"[profile="ruby:veto_closing_shades"] }
     #
+    # @example Overriding units from a binding
+    #   profile(:set_uom) do |event, configuration:, state:, command:|
+    #     unless configuration["unit"]
+    #       logger.warn("Unit configuration not provided for set_uom profile")
+    #        next true
+    #     end
+    #
+    #     case event
+    #     when :state_from_handler
+    #       next true unless state.is_a?(DecimalType) || state.is_a?(QuantityType) # what is it then?!
+    #
+    #       state = state.to_d if state.is_a?(QuantityType) # ignore the units if QuantityType was given
+    #       callback.send_update(state | configuration["unit"])
+    #       false
+    #     when :command_from_item
+    #       # strip the unit from the command, as the binding likely can't handle it
+    #       next true unless command.is_a?(QuantityType)
+    #
+    #       callback.send_command(DecimalType.new(command.to_d))
+    #       false
+    #     else
+    #       true # pass other events through as normal
+    #     end
+    #   end
+    #   # can also be referenced from an `.items` file:
+    #   # Number:Temperature MyTempWithNonUnitValueFromBinding "I prefer Celsius [%d °C]" { channel="something_that_returns_F"[profile="ruby:set_uom", unit="°F"] }
+    #
     def profile(id, &block)
       raise ArgumentError, "Block is required" unless block
 
+      id = id.to_s
       uid = org.openhab.core.thing.profiles.ProfileTypeUID.new("ruby", id)
 
       ThreadLocal.thread_local(openhab_rule_type: "profile", openhab_rule_uid: id) do
@@ -104,6 +141,8 @@ module OpenHAB
       end
     end
 
+    # rubocop:enable Layout/LineLength
+
     # @!group Object Access
 
     #
@@ -113,8 +152,6 @@ module OpenHAB
     #
     # @see Core::ValueCache ValueCache
     #
-    # @since openHAB 3.4.0
-    #
     def shared_cache
       $sharedCache
     end
@@ -335,6 +372,133 @@ module OpenHAB
       Range.new(start, finish, range.exclude_end?)
     end
 
+    #
+    # Limits the frequency of calls to the given block within a given amount of time.
+    #
+    # It can be useful to throttle certain actions even when a rule is triggered too often.
+    # This can be used to debounce triggers in a UI rule.
+    #
+    # @param (see Debouncer#initialize)
+    # @param [Object] id ID to associate with this debouncer.
+    # @param [Block] block The block to be debounced.
+    #
+    # @return [void]
+    #
+    # @example Run at most once per second even when being called more frequently
+    #   (1..100).each do
+    #     debounce for: 1.second do
+    #       logger.info "This will not be logged more frequently than every 1 second"
+    #     end
+    #     sleep 0.1
+    #   end
+    #
+    # @see Debouncer Debouncer class
+    # @see Rules::BuilderDSL#debounce debounce rule guard
+    #
+    # @!visibility private
+    def debounce(for:, leading: false, idle_time: nil, id: nil, &block)
+      interval = binding.local_variable_get(:for)
+      id ||= block.source_location
+      DSL.debouncers.compute(id) do |_key, debouncer|
+        debouncer ||= Debouncer.new(for: interval, leading: leading, idle_time: idle_time)
+        debouncer.call(&block)
+        debouncer
+      end
+    end
+
+    #
+    # Waits until calls to this method have stopped firing for a period of time
+    # before executing the block.
+    #
+    # This method acts as a guard for the given block to ensure that it doesn't get executed
+    # too frequently. The debounce_for method can be called as frequently as possible.
+    # The given block, however, will only be executed once the `debounce_time` has passed
+    # since the last call to debounce_for.
+    #
+    # This method can be used from within a UI rule as well as from a file-based rule.
+    #
+    # @param (see Rules::BuilderDSL#debounce_for)
+    # @param [Object] id ID to associate with this call.
+    # @param [Block] block The block to be debounced.
+    #
+    # @return [void]
+    #
+    # @example Run a block of code only after an item has stopped changing
+    #   # This can be placed inside a UI rule with an Item Change trigger for
+    #   # a Door contact sensor.
+    #   # If the door state has stopped changing state for 10 minutes,
+    #   # execute the block.
+    #   debounce_for(10.minutes) do
+    #     if DoorState.open?
+    #       Voice.say("The door has been left open!")
+    #     end
+    #   end
+    #
+    # @see Rules::BuilderDSL#debounce_for Rule builder's debounce_for for a detailed description
+    #
+    def debounce_for(debounce_time, id: nil, &block)
+      idle_time = debounce_time.is_a?(Range) ? debounce_time.begin : debounce_time
+      debounce(for: debounce_time, idle_time: idle_time, id: id, &block)
+    end
+
+    #
+    # Rate-limits block executions by delaying calls and only executing the last
+    # call within the given duration.
+    #
+    # When throttle_for is called, it will hold from executing the block and start
+    # a fixed timer for the given duration. Should more calls occur during
+    # this time, keep holding and once the wait time is over, execute the block.
+    #
+    # {throttle_for} will execute the block after it had waited for the given duration,
+    # regardless of how frequently `throttle_for` was called.
+    # In contrast, {debounce_for} will wait until there is a minimum interval
+    # between two triggers.
+    #
+    # {throttle_for} is ideal in situations where regular status updates need to be made
+    # for frequently changing values. It is also useful when a rule responds to triggers
+    # from multiple related items that are updated at around the same time. Instead of
+    # executing the rule multiple times, {throttle_for} will wait for a pre-set amount
+    # of time since the first group of triggers occurred before executing the rule.
+    #
+    # @param (see Rules::BuilderDSL#throttle_for)
+    # @param [Object] id ID to associate with this call.
+    # @param [Block] block The block to be throttled.
+    #
+    # @return [void]
+    #
+    # @see Rules::BuilderDSL#debounce_for Rule builder's debounce_for for a detailed description
+    # @see Rules::BuilderDSL#throttle_for
+    #
+    def throttle_for(duration, id: nil, &block)
+      debounce(for: duration, id: id, &block)
+    end
+
+    #
+    # Limit how often the given block executes to the specified interval.
+    #
+    # {only_every} will execute the given block but prevents further executions
+    # until the given interval has passed. In contrast, {throttle_for} will not
+    # execute the block immediately, and will wait until the end of the interval.
+    #
+    # @param (see Rules::BuilderDSL#only_every)
+    # @param [Object] id ID to associate with this call.
+    # @param [Block] block The block to be throttled.
+    #
+    # @return [void]
+    #
+    # @example Prevent door bell from ringing repeatedly
+    #   # This can be called from a UI rule.
+    #   # For file based rule, use the `only_every` rule guard
+    #   only_every(30.seconds) do { Audio.play_sound("doorbell.mp3") }
+    #
+    # @see Rules::BuilderDSL#debounce_for Rule builder's debounce_for for a detailed description
+    # @see Rules::BuilderDSL#only_every
+    #
+    def only_every(interval, id: nil, &block)
+      interval = 1.send(interval) if %i[second minute hour day].include?(interval)
+      debounce(for: interval, leading: true, id: id, &block)
+    end
+
     #
     # Store states of supplied items
     #
@@ -357,9 +521,6 @@ module OpenHAB
     #   end # the states will be restored here
     #
     def store_states(*items)
-      items = items.flatten.map do |item|
-        item.respond_to?(:__getobj__) ? item.__getobj__ : item
-      end
       states = Core::Items::StateStorage.from_items(*items)
       if block_given?
         yield
@@ -438,18 +599,39 @@ module OpenHAB
     #     Item1.average_since(12.hours)
     #   end
     #
-    # @see OpenHAB::Core::Items::Persistence
-    #
-    # @param [Object] service service either as a String or a Symbol
+    # @param [Object] service Persistence service either as a String or a Symbol
     # @yield [] Block executed in context of the supplied persistence service
     # @return [Object] The return value from the block.
     #
+    # @see persistence!
+    # @see OpenHAB::Core::Items::Persistence
+    #
     def persistence(service)
-      old = Thread.current[:openhab_persistence_service]
-      Thread.current[:openhab_persistence_service] = service
+      old = persistence!(service)
       yield
     ensure
-      Thread.current[:openhab_persistence_service] = old
+      persistence!(old)
+    end
+
+    #
+    # Permanently sets the default persistence service for the current thread
+    #
+    # @note This method is only intended for use at the top level of rule
+    #   scripts. If it's used within library methods, or hap-hazardly within
+    #   rules, things can get very confusing because the prior state won't be
+    #   properly restored.
+    #
+    # @param [Object] service Persistence service either as a String or a Symbol. When nil, use
+    #   the system's default persistence service.
+    # @return [Object,nil] The previous persistence service settings, or nil when using the system's default.
+    #
+    # @see persistence
+    # @see OpenHAB::Core::Items::Persistence
+    #
+    def persistence!(service = nil)
+      old = Thread.current[:openhab_persistence_service]
+      Thread.current[:openhab_persistence_service] = service
+      old
     end
 
     #
@@ -624,7 +806,7 @@ module OpenHAB
     #
     # @overload provider!(things: nil, items: nil, metadata: nil, links: nil, **metadata_items)
     #
-    # @param [Core::Provider, org.openhab.core.registry.common.ManagedProvider, :persistent, :transient, Proc] providers
+    # @param [Core::Provider, org.openhab.core.common.registry.ManagedProvider, :persistent, :transient, Proc] providers
     #   An explicit provider to use. If it's a {Core::Provider}, the type will be inferred automatically.
     #   Otherwise it's applied to all types.
     # @param [Hash] providers_by_type
@@ -703,6 +885,61 @@ module OpenHAB
       old_providers
     end
 
+    #
+    # @see CoreExt::Ephemeris
+    #
+    # @overload holiday_file(file)
+    #
+    #   Sets a thread local variable to use a specific holiday file
+    #   for {CoreExt::Ephemeris ephemeris calls} inside the block.
+    #
+    #   @param [String, nil] file Path to a file defining holidays;
+    #     `nil` to reset to default.
+    #   @yield [] Block executed in context of the supplied holiday file
+    #   @return [Object] The return value from the block.
+    #
+    #   @example Set a specific holiday configuration file temporarily
+    #     holiday_file("/home/cody/holidays.xml") do
+    #       Time.now.next_holiday
+    #     end
+    #
+    #   @see holiday_file!
+    #
+    # @overload holiday_file
+    #
+    #   Returns the current thread local value for the holiday file.
+    #
+    #   @return [String, nil] the current holiday file
+    #
+    def holiday_file(*args)
+      raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 0..1)" if args.length > 1
+
+      old = Thread.current[:openhab_holiday_file]
+      return old if args.empty?
+
+      holiday_file!(args.first)
+      yield
+    ensure
+      holiday_file!(old)
+    end
+
+    #
+    # Sets a thread local variable to set the default holiday file.
+    #
+    # @see https://github.com/svendiedrichsen/jollyday/tree/master/src/main/resources/holidays Example data files from the source
+    #
+    # @example
+    #   holiday_file!("/home/cody/holidays.xml")
+    #   Time.now.next_holiday
+    #
+    # @param [String, nil] file Path to a file defining holidays;
+    #   `nil` to reset to default.
+    # @return [Symbol, nil] the new holiday file
+    #
+    def holiday_file!(file = nil)
+      Thread.current[:openhab_holiday_file] = file
+    end
+
     # @!visibility private
     def try_parse_time_like(string)
       return string unless string.is_a?(String)

data/lib/openhab/rspec/helpers.rb

@@ -265,12 +265,13 @@ module OpenHAB
       # @return [void]
       #
       def load_rules
-        automation_path = "#{org.openhab.core.OpenHAB.config_folder}/automation/ruby"
+        automation_paths = Array(::RSpec.configuration.openhab_automation_search_paths)
+
         lib_dirs = rubylib_dirs.map { |d| File.join(d, "") }
         lib_dirs << File.join(gem_home, "")
 
         SuspendRules.suspend_rules do
-          files = Dir["#{automation_path}/**/*.rb"]
+          files = automation_paths.map { |p| Dir["#{p}/**/*.rb"] }.flatten
           files.reject! do |f|
             lib_dirs.any? { |l| f.start_with?(l) }
           end

data/lib/openhab/rspec/hooks.rb

@@ -32,6 +32,11 @@ module OpenHAB
         config.include ExampleGroup
 
         config.before(:suite) do
+          if config.mock_framework.framework_name == :rspec
+            require_relative "mocks/instance_method_stasher"
+            require_relative "mocks/space"
+          end
+
           Helpers.autorequires unless Configuration.private_confdir
           Helpers.send(:set_up_autoupdates)
           Helpers.load_transforms
@@ -86,8 +91,6 @@ module OpenHAB
         end
 
         config.after do
-          Core::Items::Proxy.reset_cache
-          Core::Things::Proxy.reset_cache
           @profile_factory.unregister
           timers.cancel_all
           # timers and rules have already been canceled, so we can safely just
@@ -97,6 +100,7 @@ module OpenHAB
           restore_autoupdate_items
           Mocks::PersistenceService.instance.reset
           Hooks.cache_script_extension.sharedCache.clear if DSL.shared_cache
+          DSL.persistence!(nil)
         end
       end
     end

data/lib/openhab/rspec/karaf.rb

@@ -280,6 +280,13 @@ module OpenHAB
             props = cfg.properties || java.util.Hashtable.new
             props.put("default", "default")
             cfg.update(props)
+
+            # configure ephemeris with basic values
+            cfg = ca.get_configuration("org.openhab.ephemeris", nil)
+            props = cfg.properties || java.util.Hashtable.new
+            props.put("country", "us")
+            props.put("dayset-weekend", %w[SATURDAY SUNDAY])
+            cfg.update(props)
           end
           wait_for_service("org.openhab.core.automation.RuleManager") do |re|
             require_relative "mocks/synchronous_executor"

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module RSpec
+    module Mocks
+      module InstanceMethodStasher
+        ::RSpec::Mocks::InstanceMethodStasher.prepend(self)
+
+        # Disable "singleton on non-persistent Java type"
+        # it doesn't matter during specs
+        def initialize(*)
+          original_verbose = $VERBOSE
+          $VERBOSE = nil
+
+          super
+        ensure
+          $VERBOSE = original_verbose
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module RSpec
+    module Mocks
+      module Space
+        ::RSpec::Mocks::Space.prepend(self)
+
+        #
+        # When setting expectations on {Items::Proxy proxies}, set them against the item
+        # themselves, so that it will catch calls against `self` from within the instance.
+        #
+        def proxy_for(object)
+          return super unless ::RSpec.current_example&.example_group&.consistent_proxies?
+
+          object = object.__getobj__ if object.is_a?(Core::Items::Proxy)
+
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -17,6 +17,39 @@ module OpenHAB
         end
         ZonedDateTime.singleton_class.prepend(MockedZonedDateTime)
 
+        # @!visibility private
+        module MockedLocalDate
+          def now
+            mocked_time_stack_item = Timecop.top_stack_item
+            return super unless mocked_time_stack_item
+
+            mocked_time_stack_item.time.to_zoned_date_time.to_local_date
+          end
+        end
+        LocalDate.singleton_class.prepend(MockedLocalDate)
+
+        # @!visibility private
+        module MockedLocalTime
+          def now
+            mocked_time_stack_item = Timecop.top_stack_item
+            return super unless mocked_time_stack_item
+
+            mocked_time_stack_item.time.to_zoned_date_time.to_local_time
+          end
+        end
+        LocalTime.singleton_class.prepend(MockedLocalTime)
+
+        # @!visibility private
+        module MockedMonthDay
+          def now
+            mocked_time_stack_item = Timecop.top_stack_item
+            return super unless mocked_time_stack_item
+
+            mocked_time_stack_item.time.to_zoned_date_time.to_month_day
+          end
+        end
+        MonthDay.singleton_class.prepend(MockedMonthDay)
+
         # extend Timecop to support Java time classes
         # @!visibility private
         module TimeCopStackItem

data/lib/openhab/rspec/openhab/core/actions.rb

@@ -12,12 +12,24 @@ module OpenHAB
         logger.debug("notify: #{msg}")
       end
 
-      def say(text, voice: nil, sink: nil, volume: nil)
-        logger.debug("say: #{text}")
+      class Voice
+        class << self
+          def say(text, voice: nil, sink: nil, volume: nil)
+            logger.debug("say: #{text}")
+          end
+        end
       end
 
-      def play_sound(filename, sink: nil, volume: nil)
-        logger.debug("play_sound: #{filename}")
+      class Audio
+        class << self
+          def play_sound(filename, sink: nil, volume: nil)
+            logger.debug("play_sound: #{filename}")
+          end
+
+          def play_stream(url, sink: nil)
+            logger.debug("play_stream: #{url}")
+          end
+        end
       end
 
       # rubocop:enable Lint/UnusedMethodArgument

data/lib/openhab/rspec/openhab/core/items/proxy.rb

@@ -4,21 +4,9 @@ module OpenHAB
   module Core
     module Items
       class Proxy
-        @proxies = {}
-
         class << self
-          # ensure each item only has a single proxy, so that
-          # expect(item).to receive(:method) works
-          def new(item)
-            return super unless defined?(::RSpec) && ::RSpec.current_example&.example_group&.consistent_proxies?
-
-            @proxies.fetch(item.name) do
-              @proxies[item.name] = super
-            end
-          end
-
           def reset_cache
-            @proxies = {}
+            @proxies.clear
           end
         end
       end

data/lib/openhab/rspec/suspend_rules.rb

@@ -12,20 +12,7 @@ module OpenHAB
             logger.trace("Skipping execution of #{uid} because rules are suspended.")
             return
           end
-
-          # super
-          ::OpenHAB::DSL::ThreadLocal.thread_local(**@thread_locals) do
-            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
-              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?
-
-            @run_context.send(:logger).log_exception(e)
-          end
+          execute!(mod, inputs)
         end
       end
       # private_constant :AutomationRule

data/lib/openhab/rspec.rb

@@ -15,3 +15,12 @@ require_relative "rspec/configuration"
 require_relative "rspec/helpers"
 require_relative "rspec/karaf"
 require_relative "rspec/hooks"
+
+return unless defined?(RSpec)
+
+RSpec.configure do |c|
+  c.add_setting :openhab_automation_search_paths, default: [
+    "#{org.openhab.core.OpenHAB.config_folder}/automation/ruby",
+    "#{org.openhab.core.OpenHAB.config_folder}/automation/jsr223"
+  ]
+end

data/lib/openhab/yard/base_helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module YARD
+    # @!visibility private
+    module BaseHelper
+      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/code_objects/group_object.rb

@@ -4,13 +4,19 @@ module OpenHAB
   module YARD
     module CodeObjects
       class GroupObject < ::YARD::CodeObjects::Base
+        attr_reader :full_name
+
+        def initialize(namespace, name)
+          @full_name = name
+          name = name.delete(%(.?"')).tr(" ", "-")
+          super
+        end
+
         def path
           "group#{sep}#{super}"
         end
 
-        def to_s
-          name
-        end
+        alias_method :to_s, :full_name
       end
     end
   end

data/lib/openhab/yard/coderay.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "coderay"
+
+module OpenHAB
+  module YARD
+    module CodeRay
+      module HtmlHelper
+        ::CodeRay::Scanners.list.each do |scanner|
+          define_method("html_syntax_highlight_#{scanner}") do |source|
+            ::CodeRay.scan(source, scanner).html
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/yard/handlers/jruby/base.rb

@@ -7,9 +7,18 @@ module YARD
         class << self
           def infer_java_class(klass, inferred_type = nil, comments = nil, statement = nil)
             components = klass.split(".")
+            components.pop if components.last == "freeze"
+
             class_first_char = components.last[0]
             is_field = components.last == components.last.upcase
-            is_package = !is_field && class_first_char != class_first_char.upcase
+            container_first_char = components[-2]&.[](0)
+            is_method = container_first_char &&
+                        class_first_char != class_first_char.upcase &&
+                        container_first_char == container_first_char.upcase
+            is_package = !is_method && !is_field && class_first_char != class_first_char.upcase
+
+            # methods aren't supported right now
+            return if is_method
 
             javadocs = YARD::Config.options.dig(:jruby, "javadocs") || {}
 

data/lib/openhab/yard/handlers/jruby/java_import_handler.rb

@@ -14,6 +14,9 @@ module YARD
             obj = infer_java_class(klass)
             next unless obj
 
+            # don't overwrite an already-extant object with the same name
+            next if ::YARD::Registry.at("#{namespace.path}::#{obj.simple_name}")
+
             # then we create a new constant in the current namespace
             register CodeObjects::ConstantObject.new(namespace, obj.simple_name) { |o|
                        o.source = statement