openhab-scripting 5.0.1 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68c866fadb2ec59386b79d7cf485f943291ca68670d473f5986ca8dc07880ff3
-  data.tar.gz: 9e8fb64b69836d4c09151182fe141abd3edf89335fef740da61c6d0dee568966
+  metadata.gz: b5064300df1e62e03270a15425080c31ce101bb688c8f91f9f0fa0393f7a1f4c
+  data.tar.gz: 8ff582399587b468ac80d525f55648ab997e2d866b7d6b2bf8fc9715171f138e
 SHA512:
-  metadata.gz: 1c8d424bc4c0a225e667d29db37feb0b401de28bc2034de483e67d0b437818645fff89db102a911a2612041058c38229cdafd6e4934159a5e9a19734e53ea5e0
-  data.tar.gz: ee0579104e4b8e33aa31de24c9a61d4a1d77e53250ca8ad3f2063f0bdd0efe81dcf1b69a75c9da5ab090e8f85a6a9f57979f11d0bad41e574f9987234fa5dbf9
+  metadata.gz: cd9c5fcfd966a435ac782e3c2cb00e0b7e10e3c3e22fb64c83ce674da9f1476a92c1072df8d44aab536f6ee774ed6ba0960160d09b554b5d9728e669855fdcfb
+  data.tar.gz: a88bd0a48d8740d04874fdc2a5ae7de454ed17d363bedb653ebc57cf818e2818d03675cdf47a033ac037400e5a0d3988b6ead3be4c63a816c01f12c3a1103d8c

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/dsl/version.rb

@@ -4,6 +4,6 @@ module OpenHAB
   module DSL
     # Version of openHAB helper libraries
     # @return [String]
-    VERSION = "5.0.1"
+    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
@@ -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/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.1
+  version: 5.1.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-05 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