openhab-scripting 5.5.0 → 5.6.1

data/lib/openhab/core/types/up_down_type.rb

@@ -37,7 +37,8 @@ module OpenHAB
         #
         def !
           return UP if down?
-          return DOWN if up?
+
+          DOWN if up?
         end
       end
     end

data/lib/openhab/core/value_cache.rb

@@ -28,7 +28,7 @@ module OpenHAB
     #   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,
+    # @note Because every script or UI rule gets its 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
@@ -107,10 +107,11 @@ module OpenHAB
 
       # @see https://docs.ruby-lang.org/en/master/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]
+        [key,
+         fetch(key) do
+           # return nil directly, without storing a value to the cache
+           return nil
+         end]
       end
 
       # @see https://docs.ruby-lang.org/en/master/Hash.html#method-i-dig Hash#dig

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

@@ -64,7 +64,8 @@ module OpenHAB
         #
         def coerce(other)
           return [other.seconds, self] if other.is_a?(Numeric)
-          return [other.to_i.seconds, self] if other.is_a?(Period)
+
+          [other.to_i.seconds, self] if other.is_a?(Period)
         end
 
         {

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

@@ -56,12 +56,14 @@ module OpenHAB
             return raw_parse(string, formatter) if formatter
 
             format = /(am|pm)$/i.match?(string) ? "h[:mm[:ss][.S]][ ]a" : "H[:mm[:ss][.S]]"
-            java_send(:parse, [java.lang.CharSequence, java.time.format.DateTimeFormatter],
-                      string, java.time.format.DateTimeFormatterBuilder.new
-                              .parse_case_insensitive
-                              .parse_lenient
-                              .append_pattern(format)
-                              .to_formatter(java.util.Locale::ENGLISH))
+            java_send(:parse,
+                      [java.lang.CharSequence, java.time.format.DateTimeFormatter],
+                      string,
+                      java.time.format.DateTimeFormatterBuilder.new
+                                                               .parse_case_insensitive
+                                                               .parse_lenient
+                                                               .append_pattern(format)
+                                                               .to_formatter(java.util.Locale::ENGLISH))
           end
         end
 

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

@@ -21,7 +21,8 @@ module OpenHAB
           #
           def parse(string)
             logger.trace("#{self.class}.parse #{string} (#{string.class})")
-            java_send(:parse, [java.lang.CharSequence, java.time.format.DateTimeFormatter],
+            java_send(:parse,
+                      [java.lang.CharSequence, java.time.format.DateTimeFormatter],
                       string.to_s,
                       java.time.format.DateTimeFormatter.ofPattern("[--]M-d"))
           end

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

@@ -47,7 +47,7 @@ module OpenHAB
         # @return [Array, nil]
         #
         def coerce(other)
-          return [other.seconds, to_i.seconds] if other.is_a?(Numeric)
+          [other.seconds, to_i.seconds] if other.is_a?(Numeric)
         end
 
         {

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

@@ -190,6 +190,7 @@ module OpenHAB
       # Integer already has #|, so we have to prepend it here
       ::Integer.prepend(QuantityTypeConversion)
       ::Numeric.include(Numeric)
+      java.math.BigDecimal.include(QuantityTypeConversion)
     end
   end
 end

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

@@ -230,9 +230,7 @@ module OpenHAB
             tags.compact.map do |tag|
               case tag
               when String then tag
-              when Symbol then tag.to_s
-              when old_semantics then tag.java_class.simple_name
-              when semantics then tag.name
+              when Symbol, semantics, old_semantics then tag.to_s
               else raise ArgumentError, "`#{tag}` must be a subclass of Semantics::Tag, a `Symbol`, or a `String`."
               end
             end
@@ -260,6 +258,8 @@ module OpenHAB
         # @param tags [String, Symbol, Semantics::Tag, Array<String, Symbol, Semantics::Tag>, nil]
         #        Fluent alias for `tag`.
         # @param autoupdate [true, false, nil] Autoupdate setting (see {ItemBuilder#autoupdate})
+        # @param thing [String, Core::Things::Thing, Core::Things::ThingUID, nil]
+        #   A Thing to be used as the base for the channel
         # @param channel [String, Core::Things::ChannelUID, nil] Channel to link the item to
         # @param expire [String] An expiration specification.
         # @param alexa [String, Symbol, Array<(String, Hash<String, Object>)>, nil]
@@ -270,7 +270,9 @@ module OpenHAB
         #   Homekit metadata (see {ItemBuilder#homekit})
         # @param metadata [Hash<String, Hash>] Generic metadata (see {ItemBuilder#metadata})
         # @param state [State] Initial state
-        def initialize(type, name = nil, label = nil,
+        def initialize(type,
+                       name = nil,
+                       label = nil,
                        provider:,
                        dimension: nil,
                        unit: nil,
@@ -281,6 +283,7 @@ module OpenHAB
                        tag: nil,
                        tags: nil,
                        autoupdate: nil,
+                       thing: nil,
                        channel: nil,
                        expire: nil,
                        alexa: nil,
@@ -310,6 +313,7 @@ module OpenHAB
           @metadata.merge!(metadata) if metadata
           @autoupdate = autoupdate
           @channels = []
+          @thing = thing
           @expire = nil
           if expire
             expire = Array(expire)
@@ -420,6 +424,7 @@ module OpenHAB
         #   end
         #
         def channel(channel, config = {})
+          channel = "#{@thing}:#{channel}" if @thing && !channel.include?(":")
           @channels << [channel, config]
         end
 
@@ -569,7 +574,7 @@ module OpenHAB
           RUBY
         end
 
-        FUNCTION_REGEX = /^([a-z]+)(?:\(([a-z]+)(?:,([a-z]+))*\))?/i.freeze
+        FUNCTION_REGEX = /^([a-z]+)(?:\((.*)\))?/i.freeze
         private_constant :FUNCTION_REGEX
 
         # The combiner function for this group
@@ -607,11 +612,13 @@ module OpenHAB
         def create_item
           base_item = super if type
           if function
+            require "csv"
+
             match = function.match(FUNCTION_REGEX)
 
             dto = org.openhab.core.items.dto.GroupFunctionDTO.new
             dto.name = match[1]
-            dto.params = match[2..]
+            dto.params = CSV.parse_line(match[2]) if match[2]
             function = org.openhab.core.items.dto.ItemDTOMapper.map_function(base_item, dto)
             Core::Items::GroupItem.new(name, base_item, function)
           else

data/lib/openhab/dsl/rules/automation_rule.rb

@@ -74,6 +74,10 @@ module OpenHAB
 
         # This method gets called in rspec's SuspendRules as well
         def execute!(mod, inputs)
+          # Store the context in a thread variable. It is accessed through DSL#method_missing
+          # which is triggered when the context variable is referenced inside the run block.
+          # It is added to @thread_locals so it is also available in #process_task below.
+          @thread_locals[:openhab_context] = extract_context(inputs)
           ThreadLocal.thread_local(**@thread_locals) do
             if logger.trace?
               logger.trace("Execute called with mod (#{mod&.to_string}) and inputs (#{inputs.inspect})")
@@ -84,10 +88,12 @@ module OpenHAB
               @debouncer.call { process_queue(create_queue(event), mod, event) }
             end
           rescue Exception => e
-            raise if defined?(::RSpec) && ::RSpec.current_example.example_group.propagate_exceptions?
+            raise if defined?(::RSpec) && ::RSpec.current_example&.example_group&.propagate_exceptions?
 
             @run_context.send(:logger).log_exception(e)
           end
+        ensure
+          @thread_locals.delete(:openhab_context)
         end
 
         def cleanup
@@ -157,6 +163,24 @@ module OpenHAB
           struct_class.new(**inputs)
         end
 
+        #
+        # Converts inputs into context hash
+        # @return [Hash] Context hash.
+        #
+        def extract_context(inputs)
+          return unless inputs
+
+          inputs.reject { |key, _| key.include?(".") }
+                .to_h do |key, value|
+                  [key.to_sym,
+                   if value.is_a?(Item) && !value.is_a?(Core::Items::Proxy)
+                     Core::Items::Proxy.new(value)
+                   else
+                     value
+                   end]
+                end
+        end
+
         #
         # Get the trigger_id for the trigger that caused the rule creation
         #
@@ -230,7 +254,7 @@ module OpenHAB
           ThreadLocal.thread_local(**@thread_locals) do
             case task
             when BuilderDSL::Run then process_run_task(event, task)
-            when BuilderDSL::Script then process_script_task(task)
+            when BuilderDSL::Script then process_script_task(event, task)
             when BuilderDSL::Trigger then process_trigger_task(event, task)
             when BuilderDSL::Otherwise then process_otherwise_task(event, task)
             end
@@ -294,9 +318,9 @@ module OpenHAB
         #
         # @param [Script] task to execute
         #
-        def process_script_task(task)
-          logger.trace { "Executing script '#{name}' run block" }
-          @run_context.instance_exec(&task.block)
+        def process_script_task(event, task)
+          logger.trace { "Executing script '#{name}' run block with event(#{event})" }
+          @run_context.instance_exec(event, &task.block)
         end
 
         #

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

@@ -70,7 +70,8 @@ module OpenHAB
             builder = BuilderDSL.new(binding || block.binding)
             builder.uid(id)
             builder.instance_exec(builder, &block)
-            builder.guard = Guard.new(run_context: builder.caller, only_if: builder.only_if,
+            builder.guard = Guard.new(run_context: builder.caller,
+                                      only_if: builder.only_if,
                                       not_if: builder.not_if)
 
             name ||= NameInference.infer_rule_name(builder)
@@ -1075,28 +1076,50 @@ module OpenHAB
         #
         # @overload cron(second: nil, minute: nil, hour: nil, dom: nil, month: nil, dow: nil, year: nil, attach: nil)
         #   The trigger can be created by specifying each field as keyword arguments.
-        #   Omitted fields will default to `*` or `?` as appropriate.
+        #
+        #   When certain fields were omitted:
+        #     - The more specific fields will default to `0` for `hour`, `minute`, and `second`,
+        #       to `MON` for `dow`, and to `1` for `dom` and `month`.
+        #     - The less specific fields will default to `*` or `?` as appropriate.
         #
         #   Each field is optional, but at least one must be specified.
         #
         #   The same rules for the standard
         #   [cron expression](https://www.quartz-scheduler.org/documentation/quartz-2.2.2/tutorials/tutorial-lesson-06.html)
         #   apply for each field. For example, multiple values can be separated
-        #   with a comma within a string.
-        #
-        #   @param [Integer, String, nil] second
-        #   @param [Integer, String, nil] minute
-        #   @param [Integer, String, nil] hour
-        #   @param [Integer, String, nil] dom
-        #   @param [Integer, String, nil] month
-        #   @param [Integer, String, nil] dow
-        #   @param [Integer, String, nil] year
+        #   with a comma within a string, and ranges can be specified with a dash or with
+        #   a Ruby Range.
+        #
+        #   @param [Integer, String, Range, nil] second
+        #   @param [Integer, String, Range, nil] minute
+        #   @param [Integer, String, Range, nil] hour
+        #   @param [Integer, String, Symbol, Range, nil] dom
+        #   @param [Integer, String, Symbol, Range, nil] month
+        #   @param [Integer, String, Symbol, Range, nil] dow
+        #   @param [Integer, String, Range, nil] year
         #   @param [Object] attach object to be attached to the trigger
-        #   @example
+        #
+        #   @example Using String values
         #     # Run every 3 minutes on Monday to Friday
         #     # equivalent to the cron expression "0 */3 * ? * MON-FRI *"
         #     rule "Using cron fields" do
-        #       cron second: 0, minute: "*/3", dow: "MON-FRI"
+        #       cron minute: "*/3", dow: "MON-FRI"
+        #       run { logger.info "Cron rule executed" }
+        #     end
+        #
+        #   @example Defaults for unspecified fields
+        #     # Run at midnight on the first day of January, February, and March
+        #     # equivalent to the cron expression "0 0 0 1 JAN-MAR ? *"
+        #     rule "Using cron fields" do
+        #       cron month: "JAN-MAR"
+        #       run { logger.info "Cron rule executed" }
+        #     end
+        #
+        #   @example Using Ruby Range values
+        #     # Run on the hour, every hour between 1pm and 5pm
+        #     # equivalent to the cron expression "0 0 13-17 ? * ? *"
+        #     rule "Using cron fields" do
+        #       cron hour: 13..17
         #       run { logger.info "Cron rule executed" }
         #     end
         #
@@ -1112,7 +1135,6 @@ module OpenHAB
 
           raise ArgumentError, "Missing cron expression or elements" unless expression
 
-          add_tag("Schedule")
           cron = Cron.new(rule_triggers: @rule_triggers)
           cron.trigger(config: { "cronExpression" => expression }, attach: attach)
         end
@@ -1211,7 +1233,6 @@ module OpenHAB
           if value == :day && at.is_a?(Item)
             raise ArgumentError, "Attachments are not supported with dynamic datetime triggers" unless attach.nil?
 
-            add_tag("Schedule")
             return trigger("timer.DateTimeTrigger", itemName: at.name, timeOnly: true)
           end
 
@@ -1561,8 +1582,12 @@ module OpenHAB
           # @deprecated OH3.4 - OH3 config uses eventXXX vs OH4 uses `topic`, `source`, and `types`
           # See https://github.com/openhab/openhab-core/pull/3299
           trigger("core.GenericEventTrigger",
-                  eventTopic: topic, eventSource: source, eventTypes: types, # @deprecated OH3.4
-                  topic: topic, source: source, types: types,
+                  eventTopic: topic,
+                  eventSource: source,
+                  eventTypes: types, # @deprecated OH3.4
+                  topic: topic,
+                  source: source,
+                  types: types,
                   attach: attach)
         end
 
@@ -1593,7 +1618,6 @@ module OpenHAB
         #
         def at(item)
           item = item.name if item.is_a?(Item)
-          add_tag("Schedule")
           trigger("timer.DateTimeTrigger", itemName: item.to_s)
         end
 
@@ -1834,10 +1858,11 @@ module OpenHAB
           types = [binding.local_variable_get(:for)].flatten
 
           WatchHandler::WatchTriggerHandlerFactory.instance # ensure it's registered
-          trigger(WatchHandler::WATCH_TRIGGER_MODULE_ID, path: path.to_s,
-                                                         types: types.map(&:to_s),
-                                                         glob: glob.to_s,
-                                                         attach: attach)
+          trigger(WatchHandler::WATCH_TRIGGER_MODULE_ID,
+                  path: path.to_s,
+                  types: types.map(&:to_s),
+                  glob: glob.to_s,
+                  attach: attach)
         end
 
         # @!endgroup

data/lib/openhab/dsl/rules/rule_triggers.rb

@@ -64,7 +64,7 @@ module OpenHAB
           org.openhab.core.automation.util.TriggerBuilder.create
              .with_id(uuid)
              .with_type_uid(type)
-             .with_configuration(org.openhab.core.config.core.Configuration.new(config))
+             .with_configuration(Core::Configuration.new(config))
              .build
         end
 

data/lib/openhab/dsl/rules/triggers/conditions/generic.rb

@@ -29,7 +29,7 @@ module OpenHAB
             # @param [Hash] inputs inputs from trigger
             # @return [true, false] if the conditions passed (and therefore the block was run)
             #
-            def process(mod:, inputs:) # rubocop:disable Lint/UnusedMethodArgument - mod is unused here but required
+            def process(mod:, inputs:)
               logger.trace("Checking #{inputs} against condition trigger #{self}")
               unless check_value(Conditions.old_state_from(inputs), @from) &&
                      check_value(Conditions.new_state_from(inputs), @to) &&

data/lib/openhab/dsl/rules/triggers/cron/cron.rb

@@ -12,7 +12,12 @@ module OpenHAB
         #
         class Cron < Trigger
           # Trigger ID for Cron Triggers
-          CRON_TRIGGER_MODULE_ID = "jsr223.jruby.CronTrigger"
+          CRON_TRIGGER_MODULE_ID = if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
+                                     "timer.GenericCronTrigger"
+                                   else
+                                     # @deprecated OH3.4 We need to use a custom CronTrigger handler
+                                     "jsr223.jruby.CronTrigger"
+                                   end
 
           #
           # Returns a default map for cron expressions that fires every second
@@ -21,16 +26,15 @@ module OpenHAB
           # @return [Hash] Map with symbols for :seconds, :minute, :hour, :dom, :month, :dow
           #   configured to fire every second
           #
-          CRON_EXPRESSION_MAP =
-            {
-              second: "*",
-              minute: "*",
-              hour: "*",
-              dom: "?",
-              month: "*",
-              dow: "?",
-              year: "*"
-            }.freeze
+          CRON_EXPRESSION_MAP = {
+            second: "*",
+            minute: "*",
+            hour: "*",
+            dom: "?",
+            month: "*",
+            dow: "?",
+            year: "*"
+          }.freeze
           private_constant :CRON_EXPRESSION_MAP
 
           # @return [Hash] Map of days of the week from symbols to to openHAB cron strings
@@ -47,7 +51,6 @@ module OpenHAB
 
           # @return [Hash] Converts the DAY_OF_WEEK_MAP to map used by Cron Expression
           DAY_OF_WEEK_EXPRESSION_MAP = DAY_OF_WEEK_MAP.transform_values { |v| CRON_EXPRESSION_MAP.merge(dow: v) }
-
           private_constant :DAY_OF_WEEK_EXPRESSION_MAP
 
           # @return [Hash] Create a set of cron expressions based on different time intervals
@@ -60,9 +63,12 @@ module OpenHAB
             month: CRON_EXPRESSION_MAP.merge(second: "0", minute: "0", hour: "0", dom: "1"),
             year: CRON_EXPRESSION_MAP.merge(second: "0", minute: "0", hour: "0", dom: "1", month: "1")
           }.merge(DAY_OF_WEEK_EXPRESSION_MAP).freeze
-
           private_constant :EXPRESSION_MAP
 
+          # @return [Hash] Translate cron field names to expression keys
+          FIELD_TO_EXPRESSION_KEY = Hash.new { |_, key| key }.merge({ dow: :week, dom: :day })
+          private_constant :FIELD_TO_EXPRESSION_KEY
+
           #
           # Create a cron map from a duration
           #
@@ -119,10 +125,28 @@ module OpenHAB
                     "unknown keyword#{"s" if extra_fields.size > 1}: #{extra_fields.map(&:inspect).join(", ")}"
             end
 
-            fields = fields.transform_values { |value| value.to_s.delete(" ") }
+            fields = fields.to_h do |key, value|
+              if value.is_a?(Range)
+                if value.exclude_end?
+                  raise ArgumentError,
+                        "Range must be inclusive for '#{key}'. Try '#{value.begin}..#{value.end}' instead"
+                end
+
+                unless value.begin && value.end
+                  raise ArgumentError,
+                        "Range must have a beginning and ending for '#{key}'"
+                end
+
+                [key, "#{value.begin.to_s.upcase}-#{value.end.to_s.upcase}".delete(" ")]
+              else
+                [key, value.to_s.delete(" ").upcase]
+              end
+            end
+            # convert fields' key dow->week, dom->day to look into EXPRESSION_MAP
+            fields_expression = fields.transform_keys { |key| FIELD_TO_EXPRESSION_KEY[key] }
             # find the first expression map that has a field from fields.
             # this ensure more-specific fields get set to 0, not *
-            base_key = EXPRESSION_MAP.keys.find { |field, _| fields.key?(field) }
+            base_key = EXPRESSION_MAP.keys.find { |field, _| fields_expression.key?(field) }
             base_expression = EXPRESSION_MAP[base_key]
             expression_map = base_expression.merge(fields)
 
@@ -186,7 +210,10 @@ module OpenHAB
           #
           #
           def trigger(config:, attach:)
-            CronHandler::CronTriggerHandlerFactory.instance # ensure it's registered
+            # @deprecated OH3.4 needs a custom CronTriggerHandlerFactory
+            if Gem::Version.new(OpenHAB::Core::VERSION) < Gem::Version.new("4.0.0")
+              CronHandler::CronTriggerHandlerFactory.instance # ensure it's registered
+            end
             append_trigger(type: CRON_TRIGGER_MODULE_ID, config: config, attach: attach)
           end
         end