openhab-scripting 5.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2826f669c876cc9b59863c2107bc8b1af62327d22c4551ef062f1b7bc97aabb
-  data.tar.gz: 61bd119ddc94019361d0150ed8bc1e92b5b42de9f610599f1305fbf04055cb14
+  metadata.gz: b5064300df1e62e03270a15425080c31ce101bb688c8f91f9f0fa0393f7a1f4c
+  data.tar.gz: 8ff582399587b468ac80d525f55648ab997e2d866b7d6b2bf8fc9715171f138e
 SHA512:
-  metadata.gz: 0bf813e7b4aba75c75979c05fc317982dfb1ca94b0eae9de656ed342b1861b293ebb8912ed7935ba709b90506a169be6013b92278281ab4dafdb3205e215f927
-  data.tar.gz: 74a35427271bcae3fd179c3ffd1710f145457e8ae1010481b27310aa28bf710c359f784c6893ed630f2737f1f029c43b7c5f925ceed7cb119239c7cfe77a77e7
+  metadata.gz: cd9c5fcfd966a435ac782e3c2cb00e0b7e10e3c3e22fb64c83ce674da9f1476a92c1072df8d44aab536f6ee774ed6ba0960160d09b554b5d9728e669855fdcfb
+  data.tar.gz: a88bd0a48d8740d04874fdc2a5ae7de454ed17d363bedb653ebc57cf818e2818d03675cdf47a033ac037400e5a0d3988b6ead3be4c63a816c01f12c3a1103d8c

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

@@ -23,7 +23,14 @@ module OpenHAB
           #
           def play_sound(filename, sink: nil, volume: nil)
             volume = PercentType.new(volume) unless volume.is_a?(PercentType) || volume.nil?
-            playSound(sink&.to_s, filename.to_s, volume)
+            # JRuby calls the wrong overloaded method when volume is given, but sink is nil
+            # will call playSound(String, String, float) instead of playSound(String, String, PercentType)
+            # and end up with argument type mismatched. So we need to give it a bit of help here.
+            if sink
+              playSound(sink.to_s, filename.to_s, volume)
+            else
+              playSound(filename.to_s, volume)
+            end
           end
 
           #

data/lib/openhab/core/events/item_state_updated_event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "item_state_event"
+
+module OpenHAB
+  module Core
+    module Events
+      begin
+        java_import org.openhab.core.items.events.ItemStateUpdatedEvent
+
+        #
+        # {AbstractEvent} sent when an item's state has updated.
+        #
+        class ItemStateUpdatedEvent < ItemEvent
+          include ItemState
+        end
+      rescue NameError
+        # @deprecated OH3.4 OH3 will raise an error ItemStateUpdatedEvent is only in OH4
+      end
+    end
+  end
+end

data/lib/openhab/core/items/generic_item.rb

@@ -77,7 +77,7 @@ module OpenHAB
         #
         # This may include running a transformation.
         #
-        # @return [String]
+        # @return [String] The formatted state
         #
         # @example
         #   logger.info(Exterior_WindDirection.formatted_state) # => "NE (36°)"
@@ -92,7 +92,9 @@ module OpenHAB
           transformed_state_string = org.openhab.core.transform.TransformationHelper.transform(OSGi.bundle_context,
                                                                                                pattern,
                                                                                                raw_state_string)
-          return state.format(pattern) if transformed_state_string.nil? || transformed_state_string == raw_state_string
+          if transformed_state_string.nil? || transformed_state_string == raw_state_string
+            return state&.format(pattern) || raw_state_string
+          end
 
           transformed_state_string
         rescue org.openhab.core.transform.TransformationException

data/lib/openhab/core/items/semantics.rb

@@ -60,6 +60,12 @@ module OpenHAB
       # and {#property_type}. They can even be used with
       # {DSL::Items::ItemBuilder#tag}.
       #
+      # The semantic constants in the `Semantics` module are enhanced with {TagClassMethods}
+      # to provide easy access to the tags' additional attributes: {TagClassMethods.label label},
+      # {TagClassMethods.synonyms synonyms}, and {TagClassMethods.description description}.
+      # For example, to get the synonyms for `Semantics::Lightbulb` in German:
+      # `Semantics::Lightbulb.synonyms(java.util.Locale::GERMAN)`
+      #
       # @see https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.semantics/model/SemanticTags.csv Semantic Tags Table
       #
       # @example Working with tags
@@ -156,6 +162,12 @@ module OpenHAB
       #   # All items tagged "SmartLightControl"
       #   items.tagged("SmartLightControl")
       #
+      # ## Adding Custom Semantic Tags
+      #
+      # openHAB 4 supports adding custom semantic tags to augment the standard set of tags to better suit
+      # your particular requirements.
+      #
+      # For more information, see {add}
       #
       module Semantics
         GenericItem.include(self)
@@ -188,15 +200,6 @@ module OpenHAB
         #   end
         #
 
-        # import all the semantics constants
-        [org.openhab.core.semantics.model.point.Points,
-         org.openhab.core.semantics.model.property.Properties,
-         org.openhab.core.semantics.model.equipment.Equipments,
-         org.openhab.core.semantics.model.location.Locations].each do |parent_tag|
-          parent_tag.stream.for_each do |tag|
-            const_set(tag.simple_name.to_sym, tag.ruby_class)
-          end
-        end
         # This is a marker interface for all semantic tag classes.
         # @interface
         Tag = org.openhab.core.semantics.Tag
@@ -390,6 +393,165 @@ module OpenHAB
           result.delete(self)
           result
         end
+
+        # @deprecated OH3.4 - this check is only needed for OH3.4
+        if org.openhab.core.semantics.SemanticTags.respond_to?(:add)
+
+          #
+          # Adds custom semantic tags.
+          #
+          # @return [Array<Tag>] An array of tags successfully added.
+          #
+          # @overload self.add(**tags)
+          #   Quickly add one or more semantic tags using the default label, empty synonyms and descriptions.
+          #
+          #   @param [kwargs] **tags Exactly one pair of `tag` => `parent` where tag is either a Symbol or a String
+          #     for the tag to be added, and parent is either a {Tag}, a symbol or a string of an existing tag.
+          #   @return [Array<Tag>] An array of tags successfully added.
+          #
+          #   @example Add one semantic tag `Balcony` whose parent is `Semantics::Outdoor` (Location)
+          #     Semantics.add(Balcony: Semantics::Outdoor)
+          #
+          #   @example Add multiple semantic tags
+          #     Semantics.add(Balcony: Semantics::Outdoor,
+          #                   SecretRoom: Semantics::Room,
+          #                   Motion: Semantics::Property)
+          #
+          # @overload self.add(label: nil, synonyms: "", description: "", **tags)
+          #   Add a custom semantic tag with extra details.
+          #
+          #   @example
+          #     Semantics.add(SecretRoom: Semantics::Room, label: "My Secret Room",
+          #       synonyms: "HidingPlace", description: "A room that requires a special trick to enter")
+          #
+          #   @param [String,nil] label Optional label. When nil, infer the label from the tag name,
+          #     converting `CamelCase` to `Camel Case`
+          #   @param [String,Array<String,Symbol>] synonyms An array of synonyms, or a string containing a
+          #     comma separated list of synonyms for this tag.
+          #   @param [String] description A longer description of the tag.
+          #   @param [kwargs] **tags Exactly one pair of `tag` => `parent` where tag is either a Symbol or a String
+          #     for the tag to be added, and parent is either a {Tag}, a symbol or a string of an existing tag.
+          #   @return [Array<Tag>] An array of tags successfully added.
+          #
+          def self.add(label: nil, synonyms: "", description: "", **tags)
+            raise "Tags must be specified" if tags.empty?
+            if (tags.length > 1) && !(label.nil? && synonyms.empty? && description.empty?)
+              raise "Additional options can only be specified when creating one tag"
+            end
+
+            synonyms = synonyms.map(&:to_s).map(&:strip).join(",") if synonyms.is_a?(Array)
+
+            tags.map do |name, parent|
+              parent_is_tag = parent.respond_to?(:java_class) && parent.java_class < Tag.java_class
+              parent = parent_is_tag ? parent.java_class : parent.to_s
+              name = name.to_s
+              org.openhab.core.semantics.SemanticTags.add(name, parent, label, synonyms, description)
+                                                    &.then { const_missing(name) }
+            end.compact
+          end
+        end
+
+        #
+        # Returns all available Semantic tags
+        #
+        # @return [Array<Tag>] an array containing all the Semantic tags
+        #
+        def self.tags
+          java.util.stream.Stream.of(
+            org.openhab.core.semantics.model.point.Points.stream,
+            org.openhab.core.semantics.model.property.Properties.stream,
+            org.openhab.core.semantics.model.equipment.Equipments.stream,
+            org.openhab.core.semantics.model.location.Locations.stream
+          ).flat_map(&:itself).map(&:ruby_class).iterator.to_a
+        end
+
+        #
+        # Finds the semantic tag using its name, label, or synonyms.
+        #
+        # @param [String,Symbol] id The tag name, label, or synonym to look up
+        # @param [java.util.Locale] locale The locale of the given label or synonym
+        #
+        # @return [Tag,nil] The semantic tag class if found, or nil if not found.
+        #
+        def self.lookup(id, locale = nil)
+          id = id.to_sym
+          return const_get(id) if constants.include?(id) || const_missing(id)
+
+          locale = java.util.Locale.default if locale.nil?
+          org.openhab.core.semantics.SemanticTags.get_by_label_or_synonym(id.to_s, locale).first&.ruby_class
+        end
+
+        #
+        # Automatically looks up new semantic classes and adds them as `constants`
+        #
+        # @return [Tag, nil]
+        #
+        # @!visibility private
+        def self.const_missing(sym)
+          logger.trace("const missing, performing Semantics Lookup for: #{sym}")
+          # @deprecated OH3.4 - the Property tag had an ID of "MeasurementProperty" in OH3.4. This was corrected in OH4.
+          sym = :MeasurementProperty if sym == :Property && Gem::Version.new(Core::VERSION) < Gem::Version.new("4.0.0")
+
+          org.openhab.core.semantics.SemanticTags.get_by_id(sym.to_s)
+            &.then do |tag|
+              tag = tag.ruby_class
+              tag.singleton_class.include(TagClassMethods)
+              const_set(sym, tag)
+            end
+        end
+
+        #
+        # Adds tag attributes to the semantic tag class
+        #
+        module TagClassMethods
+          # @!visibility private
+          java_import org.openhab.core.semantics.SemanticTags
+
+          #
+          # Returns the tag's label
+          #
+          # @param [java.util.Locale] locale The locale that the label should be in, if available.
+          #   When nil, the system's default locale is used.
+          #
+          # @return [String] The tag's label
+          #
+          def label(locale = nil)
+            SemanticTags.get_label(java_class, locale || java.util.Locale.default)
+          end
+
+          #
+          # Returns the tag's synonyms
+          #
+          # @param [java.util.Locale] locale The locale that the label should be in, if available.
+          #   When nil, the system's default locale is used.
+          #
+          # @return [Array<String>] The list of synonyms in the requested locale.
+          #
+          def synonyms(locale = nil)
+            unless SemanticTags.respond_to?(:get_synonyms) # @deprecated OH3.4
+              return java_class.get_annotation(org.openhab.core.semantics.TagInfo.java_class).synonyms
+                               .split(",").map(&:strip)
+            end
+
+            SemanticTags.get_synonyms(java_class, locale || java.util.Locale.default).to_a
+          end
+
+          #
+          # Returns the tag's description
+          #
+          # @param [java.util.Locale] locale The locale that the description should be in, if available.
+          #   When nil, the system's default locale is used.
+          #
+          # @return [String] The tag's description
+          #
+          def description(locale = nil)
+            unless SemanticTags.respond_to?(:get_description) # @deprecated OH3.4
+              return java_class.get_annotation(org.openhab.core.semantics.TagInfo.java_class).description
+            end
+
+            SemanticTags.get_description(java_class, locale || java.util.Locale.default)
+          end
+        end
       end
     end
   end
@@ -454,7 +616,8 @@ module Enumerable
     end
     unless point_or_property_types.all? do |tag|
              tag.is_a?(Module) &&
-             (tag < Semantics::Point || tag < Semantics::Property)
+             (tag < Semantics::Point ||
+              tag < Semantics::Property)
            end
       raise ArgumentError, "point_or_property_types must all be a subclass of Point or Property"
     end

data/lib/openhab/core/rules/registry.rb

@@ -70,6 +70,24 @@ module OpenHAB
 
           provider.remove(rule_uid)
         end
+
+        #
+        # Returns all Scenes (rules tagged with "Scene")
+        #
+        # @return [Array<Rule>] A list of all the scenes
+        #
+        def scenes
+          tagged("Scene")
+        end
+
+        #
+        # Returns all Scripts (rules tagged with "Script")
+        #
+        # @return [Array<Rule>] A list of all the scripts
+        #
+        def scripts
+          tagged("Script")
+        end
       end
     end
   end

data/lib/openhab/core/rules/rule.rb

@@ -11,6 +11,15 @@ module OpenHAB
       # met, enabling the core dynamic functionality of openHAB.
       #
       module Rule
+        # @!attribute [r] name
+        #   @return [String,nil] The rule's human-readable name
+
+        # @!attribute [r] description
+        #   @return [String,nil] The rule's description
+
+        # @!attribute [r] tags
+        #   @return [Array<Tag>] The rule's list of tags
+
         #
         # @!method visible?
         #   Check if visibility == `VISIBLE`
@@ -102,12 +111,27 @@ module OpenHAB
           info.nil? || info.status_detail == RuleStatusDetail::DISABLED
         end
 
+        #
+        # Checks if this rule has at least one of the given tags.
+        #
+        # (see Items::Item#tagged)
+        #
+        # @example Find rules tagged with "Halloween"
+        #   rules.tagged?("Halloweed")
+        #
+        def tagged?(*tags)
+          tags.map! do |tag|
+            tag.is_a?(::Module) ? tag.simple_name : tag # ::Module to distinguish against Rule::Module!
+          end
+          !(self.tags.to_a & tags).empty?
+        end
+
         #
         # @!attribute [r] status
-        # @return [RuleStatus nil]
+        # @return [RuleStatus, nil]
         #
         def status
-          Rules.manager.get_status(uid)
+          Rules.manager&.get_status(uid)
         end
 
         #
@@ -115,7 +139,7 @@ module OpenHAB
         # @return [RuleStatusInfo, nil]
         #
         def status_info
-          Rules.manager.get_status_info(uid)
+          Rules.manager&.get_status_info(uid)
         end
 
         # @return [String]

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

@@ -76,8 +76,10 @@ module OpenHAB
         # This method gets called in rspec's SuspendRules as well
         def execute!(mod, inputs)
           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")
+            if logger.trace?
+              logger.trace("Execute called with mod (#{mod&.to_string}) and inputs (#{inputs.inspect})")
+              logger.trace("Event details #{inputs["event"].inspect}") if inputs&.key?("event")
+            end
             trigger_conditions(inputs).process(mod: mod, inputs: inputs) do
               event = extract_event(inputs)
               @debouncer.call { process_queue(create_queue(event), mod, event) }

data/lib/openhab/dsl/version.rb

@@ -4,6 +4,6 @@ module OpenHAB
   module DSL
     # Version of openHAB helper libraries
     # @return [String]
-    VERSION = "5.0.0"
+    VERSION = "5.1.0"
   end
 end

data/lib/openhab/dsl.rb

@@ -127,7 +127,7 @@ module OpenHAB
     #       # 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))
+    #       callback.handle_command(DecimalType.new(command.to_d))
     #       false
     #     else
     #       true # pass other events through as normal
@@ -500,7 +500,7 @@ module OpenHAB
     # @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") }
+    #   only_every(30.seconds) { Audio.play_sound("doorbell.mp3") }
     #
     # @see Rules::BuilderDSL#debounce_for Rule builder's debounce_for for a detailed description
     # @see Rules::BuilderDSL#only_every
@@ -777,7 +777,7 @@ module OpenHAB
     # Sets the implicit provider(s) for operations inside the block.
     #
     # @param (see #provider!)
-    # @yield [] The block will be executed in the context of the specified unit(s).
+    # @yield [] The block will be executed using the specified provider(s).
     # @return [Object] the result of the block
     #
     # @example
@@ -793,11 +793,11 @@ module OpenHAB
     # @see provider!
     # @see OpenHAB::Core::Provider.current Provider.current for how the current provider is calculated
     #
-    def provider(*args, **kwargs)
+    def provider(*providers, **providers_by_type)
       raise ArgumentError, "You must give a block to set the provider for the duration of" unless block_given?
 
       begin
-        old_providers = provider!(*args, **kwargs)
+        old_providers = provider!(*providers, **providers_by_type)
         yield
       ensure
         Thread.current[:openhab_providers] = old_providers

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

@@ -127,7 +127,7 @@ module OpenHAB
             last_index = item_history.bsearch_index do |i|
               i.timestamp.compare_to(filter.end_date).positive?
             end
-            return if last_index.zero?
+            return if last_index&.zero?
 
             last_index ||= item_history.length
           end

data/lib/openhab/yard/html_helper.rb

@@ -45,7 +45,7 @@ module OpenHAB
         html.css("h1, h2, h3, h4, h5, h6").each do |header|
           next if header["id"]
 
-          id = header.text.strip.downcase.delete(%(.?"')).tr(" ", "-")
+          id = header.text.strip.downcase.delete(%(.?"')).gsub(/[ ,]+/, "-")
           header["id"] = id
           header.prepend_child(%(<a href="##{id}" class="header-anchor">#</a>))
         end

data/lib/openhab/yard/markdown_helper.rb

@@ -52,6 +52,9 @@ module OpenHAB
           end
         end
 
+        # Remove the "omit from toc" comments
+        result.gsub!(" <!-- omit from toc -->", "")
+
         # re-link files in docs/*.md. They're written so they work on github without any
         # processing
         result.gsub!(%r{\[([A-Za-z0-9,. ]+)\]\(([A-Za-z0-9./-]+)\)}) do |str|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-08 00:00:00.000000000 Z
+date: 2023-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -96,6 +96,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: gem-release
   requirement: !ruby/object:Gem::Requirement
@@ -110,6 +124,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: github_changelog_generator
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
 - !ruby/object:Gem::Dependency
   name: guard-rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -379,6 +407,7 @@ files:
 - lib/openhab/core/events/item_event.rb
 - lib/openhab/core/events/item_state_changed_event.rb
 - lib/openhab/core/events/item_state_event.rb
+- lib/openhab/core/events/item_state_updated_event.rb
 - lib/openhab/core/events/thing_status_info_event.rb
 - lib/openhab/core/items.rb
 - lib/openhab/core/items/accepted_data_types.rb