openhab-jrubyscripting 5.0.0.rc9 → 5.0.0.rc11

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
 
     #
@@ -335,6 +374,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
     #
@@ -624,7 +790,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 +869,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/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

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/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/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

data/lib/openhab/yard/html_helper.rb

@@ -1,17 +1,62 @@
 # frozen_string_literal: true
 
+require "nokogiri"
+
 module OpenHAB
   module YARD
     # @!visibility private
     module HtmlHelper
+      def base_url
+        if serializer.is_a?(::YARD::Server::DocServerSerializer)
+          abs_url(base_path(router.docs_prefix), "")
+        else
+          u = url_for("")
+          u = "#{u}/" if !u.empty? && u[-1] != "/"
+          u
+        end
+      end
+
+      def url_for_search_index
+        if serializer.is_a?(::YARD::Server::DocServerSerializer)
+          url_for_list("index")
+        else
+          url_for("index.json")
+        end
+      end
+
       def html_markup_markdown(text)
-        result = super
+        result = super(text)
 
+        html = Nokogiri::HTML5.fragment(result)
         # re-link files in docs/*.md. They're written so they work on github without any
         # processing
-        result.gsub!(%r{<a href="(?:[A-Za-z0-9_/-]+/)*([A-Za-z0-9_-]+).md(#[A-Za-z0-9_/-]+)?"},
-                     "<a href=\"file.\\1.html\\2\"")
-        result
+        unless serializer.is_a?(::YARD::Server::DocServerSerializer)
+          html.css("a[href!='']").each do |link|
+            uri = URI.parse(link["href"])
+            next unless uri.relative? && File.extname(uri.path) == ".md"
+
+            basename = File.basename(uri.path, ".md")
+            uri.path = "file.#{basename}.html"
+            link["href"] = uri.to_s
+          end
+        end
+
+        # wtf commonmarker, you don't generate anchors?!
+        html.css("h1, h2, h3, h4, h5, h6").each do |header|
+          next if header["id"]
+
+          id = header.text.strip.downcase.delete(%(.?"')).tr(" ", "-")
+          header["id"] = id
+          header.prepend_child(%(<a href="##{id}" class="header-anchor">#</a>))
+        end
+
+        html.to_s
+      end
+
+      def link_url(url, title = nil, params = {})
+        params.merge!(@link_attrs) if defined?(@link_attrs) && @link_attrs
+        params[:class] = params.delete(:classes).join(" ") if params[:classes]
+        super
       end
 
       # have to completely replace this method. only change is the regex splitting
@@ -28,17 +73,6 @@ module OpenHAB
         list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
       end
       # 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)
-        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