openhab-scripting 4.47.0 → 5.0.0

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "timecop"
+
+module OpenHAB
+  module RSpec
+    module Mocks
+      class Timer < Core::Timer
+        # @!visibility private
+        module MockedZonedDateTime
+          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
+          end
+        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
+          def parse_time(*args)
+            if args.length == 1
+              arg = args.first
+              if arg.is_a?(Time) ||
+                 (defined?(DateTime) && arg.is_a?(DateTime)) ||
+                 (defined?(Date) && arg.is_a?(Date))
+                return super
+              elsif arg.respond_to?(:to_zoned_date_time)
+                return arg.to_zoned_date_time.to_time
+              elsif arg.is_a?(java.time.temporal.TemporalAmount)
+                return (ZonedDateTime.now + arg).to_time
+              end
+            end
+
+            super
+          end
+        end
+        Timecop::TimeStackItem.prepend(TimeCopStackItem)
+
+        attr_reader :execution_time, :id, :block
+
+        def initialize(time, id:, thread_locals:, block:) # rubocop:disable Lint/MissingSuper
+          @time = time
+          @id = id
+          @block = block
+          @thread_locals = thread_locals
+          reschedule!(time)
+        end
+
+        def reschedule!(time = nil)
+          Thread.current[:openhab_rescheduled_timer] = true if Thread.current[:openhab_rescheduled_timer] == self
+          @execution_time = new_execution_time(time || @time)
+          @executed = false
+
+          DSL::TimerManager.instance.add(self)
+
+          self
+        end
+
+        def execute
+          raise "Timer already cancelled" if cancelled?
+          raise "Timer already executed" if terminated?
+
+          @executed = true
+          super
+        end
+
+        def cancel
+          return false if terminated? || cancelled?
+
+          DSL::TimerManager.instance.delete(self)
+          cancel!
+          true
+        end
+
+        def cancel!
+          @execution_time = nil
+          true
+        end
+
+        def cancelled?
+          @execution_time.nil?
+        end
+
+        def terminated?
+          @executed || cancelled?
+        end
+
+        def running?
+          false
+        end
+
+        def active?
+          !terminated?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      # rubocop:disable Lint/UnusedMethodArgument
+      # redefine these to do nothing so that rules won't fail
+
+      module_function
+
+      def notify(msg, email: nil)
+        logger.debug("notify: #{msg}")
+      end
+
+      class Voice
+        class << self
+          def say(text, voice: nil, sink: nil, volume: nil)
+            logger.debug("say: #{text}")
+          end
+        end
+      end
+
+      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
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      class Proxy
+        class << self
+          def reset_cache
+            @proxies.clear
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Things
+      class Proxy
+        @proxies = {}
+
+        class << self
+          # ensure each item only has a single proxy, so that
+          # expect(item).to receive(:method) works
+          def new(thing)
+            return super unless defined?(::RSpec) && ::RSpec.current_example&.example_group&.consistent_proxies?
+
+            @proxies.fetch(thing.uid.to_s) do
+              @proxies[thing.uid.to_s] = super
+            end
+          end
+
+          def reset_cache
+            @proxies = {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/rspec/shell.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module RSpec
+    # based on https://stackoverflow.com/questions/1197224/source-shell-script-into-environment-within-a-ruby-script#19826329
+    # @!visibility private
+    module Shell
+      module_function
+
+      # Read in the bash environment, after an optional command.
+      #   Returns Array of key/value pairs.
+      def shell_env(cmd = nil)
+        cmd = "#{cmd} > /dev/null; " if cmd
+        env = `#{cmd}printenv -0`
+        env.split("\0").map { |l| l.split("=", 2) }
+      end
+
+      # Source a given file, and compare environment before and after.
+      #   Returns Hash of any keys that have changed.
+      def shell_source(file)
+        (shell_env(". #{File.realpath(file)}") - shell_env).to_h
+      end
+
+      # Find variables changed as a result of sourcing the given file,
+      #   and update in ENV.
+      def source_env_from(file)
+        shell_source(file).each { |k, v| ENV[k] = v }
+      end
+    end
+  end
+end

data/lib/openhab/rspec/suspend_rules.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module RSpec
+    # @!visibility private
+    module SuspendRules
+      # I'd prefer to prepend a module, but I can't because of
+      # https://github.com/jruby/jruby/issues/6966#issuecomment-1172983776
+      class ::OpenHAB::DSL::Rules::AutomationRule # rubocop:disable Style/ClassAndModuleChildren
+        def execute(mod = nil, inputs = nil)
+          if SuspendRules.suspended?
+            logger.trace("Skipping execution of #{uid} because rules are suspended.")
+            return
+          end
+          execute!(mod, inputs)
+        end
+      end
+      # private_constant :AutomationRule
+      # DSL::Rules::AutomationRule.prepend(AutomationRule)
+
+      module DSL
+        def after(*, **)
+          return if SuspendRules.suspended?
+
+          super
+        end
+      end
+      private_constant :DSL
+      OpenHAB::DSL.prepend(DSL)
+
+      @suspended = false
+
+      class << self
+        # @!visibility private
+        def suspend_rules
+          old_suspended = @suspended
+          @suspended = true
+          yield
+        ensure
+          @suspended = old_suspended
+        end
+
+        # @!visibility private
+        def suspended?
+          @suspended
+        end
+      end
+    end
+  end
+end

data/lib/openhab/rspec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+unless RUBY_ENGINE == "jruby" &&
+       Gem::Version.new(RUBY_ENGINE_VERSION) >= Gem::Version.new("9.3.8.0")
+  raise Gem::RubyVersionMismatch, "openhab-scripting requires JRuby 9.3.8.0 or newer"
+end
+
+require "jruby"
+
+require "diff/lcs"
+
+require "openhab/log"
+
+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/cli/stats.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module YARD
+    module CLI
+      module Stats
+        ::YARD::CLI::Stats.prepend(self)
+
+        def stats_for_constants
+          objs = all_objects.select { |m| m.type == :constant }
+          undoc = objs.find_all do |m|
+            # allow constants that are simple aliases
+            # to not have additional documentation
+            m.docstring.blank? && m.target.nil?
+          end
+          @undoc_list |= undoc if @undoc_list
+
+          output "Constants", objs.size, undoc.size
+        end
+      end
+    end
+  end
+end

data/lib/openhab/yard/code_objects/group_object.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+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
+
+        alias_method :to_s, :full_name
+      end
+    end
+  end
+end

data/lib/openhab/yard/code_objects/java/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module YARD
+  module CodeObjects
+    module Java
+      #
+      # Represents a java.lang.Class
+      #
+      # Which might be a class, an enum, or an interface
+      module Base
+        module ClassMethods
+          def new(name)
+            super(:root, name)
+          end
+        end
+
+        def self.included(klass)
+          klass.singleton_class.include(ClassMethods)
+        end
+
+        def visibility
+          :private
+        end
+
+        def simple_name
+          name.to_s.split(".").last
+        end
+      end
+    end
+  end
+end

data/lib/openhab/yard/code_objects/java/class_object.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module YARD
+  module CodeObjects
+    module Java
+      class ClassObject < CodeObjects::ClassObject
+        include Base
+      end
+    end
+  end
+end

data/lib/openhab/yard/code_objects/java/field_object.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module YARD
+  module CodeObjects
+    module Java
+      class FieldObject < CodeObjects::ConstantObject
+        include Base
+
+        def type
+          :constant
+        end
+      end
+    end
+  end
+end

data/lib/openhab/yard/code_objects/java/interface_object.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module YARD
+  module CodeObjects
+    module Java
+      class InterfaceObject < CodeObjects::ModuleObject
+        include Base
+
+        def type
+          :module
+        end
+      end
+    end
+  end
+end

data/lib/openhab/yard/code_objects/java/package_object.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module YARD
+  module CodeObjects
+    module Java
+      class PackageObject < CodeObjects::ClassObject
+        include Base
+      end
+    end
+  end
+end

data/lib/openhab/yard/code_objects/java/proxy.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module YARD
+  module CodeObjects
+    module Java
+      module Proxy
+        CodeObjects::Proxy.prepend(self)
+
+        def initialize(namespace, name, type = nil)
+          if name.match?(/^([a-zA-Z_$][a-zA-Z\d_$]*\.)+/)
+            @namespace = Registry.root
+            @name = name.to_sym
+            @obj = nil
+            @imethod = nil
+            self.type = type
+            return
+          end
+          super
+        end
+      end
+    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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module YARD
+  module Handlers
+    module JRuby
+      module Base
+        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
+            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") || {}
+
+            href_base = javadocs.find { |package, _href| klass == package || klass.start_with?("#{package}.") }&.last
+            return unless href_base
+
+            inferred_type = CodeObjects::Java::FieldObject if is_field
+            inferred_type = CodeObjects::Java::PackageObject if is_package
+            if inferred_type.nil?
+              docstring = Docstring.parser.parse(comments || statement&.comments).to_docstring
+              inferred_type = if docstring.has_tag?(:interface)
+                                CodeObjects::Java::InterfaceObject
+                              else
+                                CodeObjects::Java::ClassObject
+                              end
+            end
+
+            inferred_type.new(klass) do |o|
+              o.source = statement if statement
+              suffix = "/package-summary" if is_package
+              field = "##{components.pop}" if is_field
+              link = "#{href_base}#{components.join("/")}#{suffix}.html#{field}"
+              o.docstring.add_tag(Tags::Tag.new(:see, klass, nil, link)) unless o.docstring.has_tag?(:see)
+            end
+          end
+        end
+
+        def infer_java_class(statement, inferred_type = nil, comments = nil)
+          return unless statement.is_a?(Parser::Ruby::AstNode)
+          return unless statement.type == :call
+
+          Base.infer_java_class(statement.source, inferred_type, comments, statement)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module YARD
+  module Handlers
+    module JRuby
+      module ClassHandler
+        include Base
+
+        Ruby::ClassHandler.prepend(self)
+
+        def parse_superclass(superclass)
+          infer_java_class(superclass, CodeObjects::Java::ClassObject)&.then { |k| return k }
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module YARD
+  module Handlers
+    module JRuby
+      module ConstantHandler
+        include Base
+
+        Ruby::ConstantHandler.prepend(self)
+
+        def process_constant(statement)
+          infer_java_class(statement[1], nil, statement.comments)
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module YARD
+  module Handlers
+    module JRuby
+      class JavaImportHandler < Ruby::Base
+        include Base
+
+        handles method_call(:java_import)
+
+        process do
+          statement.parameters(false).each do |klass|
+            # first we auto-create the CodeObject for the class
+            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
+                       o.value = klass.source
+                     }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module YARD
+  module Handlers
+    module JRuby
+      module MixinHandler
+        include Base
+
+        Ruby::MixinHandler.prepend(self)
+
+        def process_mixin(mixin)
+          if infer_java_class(mixin, CodeObjects::Java::InterfaceObject)
+            # make the Ruby::MixinHandler accept that this is a ref
+            def mixin.ref?
+              true
+            end
+          end
+          super
+        end
+      end
+    end
+  end
+end