openhab-jrubyscripting 5.0.0.rc11 → 5.0.0.rc.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc3911eb787dc73ea31109aa6d4d8c3896a1019b381a70030f152c668f0b8f2e
-  data.tar.gz: ebd2d7005e9f17827a4bf58d38b7fc2476a497cb428aab0270290c3c98461b80
+  metadata.gz: 8ef6b7b058463c4bbcbc500b23baf44e1ef8f3872c39f88f3819875523b9d350
+  data.tar.gz: f2c5511e9c61eb79a1464161d35ba239570e45172be44415784994688a789c67
 SHA512:
-  metadata.gz: df4c1df793cd44700467728c63df6ba9d12ecf7111fc7daf2b9a8f4953c68575082f9f4b87f70a42bfedcc9af70d4537e45b6fb2d8b78ac8e7e3f7cca22aaf4b
-  data.tar.gz: de1c8f5847bbbeb3eed3268ceedc2a61213b4f6ab269372a08bd4d8217f6b384a2c62b5ceb1f9de2777d264d0d6eb4e02fde6f245fa4fcc0dc03d068041a11bb
+  metadata.gz: 7b4aca0a4cb592c7bcb84c4c50772d359cfc704f4bccb31e3aa58a1e76be0e15de9276c0184bcd696aed1c05cb7361e0f4d74f892eb9347f0a43f54ac596ecdb
+  data.tar.gz: 1053d9bd85f8013bcfa37242f1354e333587884179f8600c4f48ad19c5d1aa8cfdbb7795a32b37147d83d1b11334cb993663e761c4a0c2cf9574b5ec1355586e

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

@@ -4,47 +4,47 @@ module OpenHAB
   module Core
     module Actions
       # @see https://www.openhab.org/docs/configuration/actions.html#exec-actions Exec Actions
-      class Exec
-        class << self # rubocop:disable Lint/EmptyClass
-          # @!method execute_command_line
-          #
-          # @return [void]
-          #
-          # @overload execute_command_line(command_line)
-          #
-          #   Executes a command on the command line without waiting for the
-          #   command to complete.
-          #
-          #   @param [String] command_line
-          #   @return [void]
-          #
-          #   @example Execute an external command
-          #     rule 'Run a command' do
-          #       every :day
-          #       run do
-          #         Exec.execute_command_line('/bin/true')
-          #       end
-          #     end
-          #
-          # @overload execute_command_line(timeout, command_line)
-          #
-          #   Executes a command on the command and waits timeout seconds for
-          #   the command to complete, returning the output from the command
-          #   as a String.
-          #
-          #   @param [Duration] timeout
-          #   @param [String] command_line
-          #   @return [String]
-          #
-          #   @example Execute an external command and process its results
-          #     rule 'Run a command' do
-          #       every :day
-          #       run do
-          #         TodaysHoliday_String.update(Exec.execute_command_line(5.seconds, '/home/cody/determine_holiday.rb')
-          #       end
-          #     end
-          #
-        end
+      class Exec # rubocop:disable Lint/EmptyClass
+        # @!scope class
+
+        # @!method execute_command_line
+        #
+        # @return [void]
+        #
+        # @overload execute_command_line(command_line)
+        #
+        #   Executes a command on the command line without waiting for the
+        #   command to complete.
+        #
+        #   @param [String] command_line
+        #   @return [void]
+        #
+        #   @example Execute an external command
+        #     rule 'Run a command' do
+        #       every :day
+        #       run do
+        #         Exec.execute_command_line('/bin/true')
+        #       end
+        #     end
+        #
+        # @overload execute_command_line(timeout, command_line)
+        #
+        #   Executes a command on the command and waits timeout seconds for
+        #   the command to complete, returning the output from the command
+        #   as a String.
+        #
+        #   @param [Duration] timeout
+        #   @param [String] command_line
+        #   @return [String]
+        #
+        #   @example Execute an external command and process its results
+        #     rule 'Run a command' do
+        #       every :day
+        #       run do
+        #         TodaysHoliday_String.update(Exec.execute_command_line(5.seconds, '/home/cody/determine_holiday.rb')
+        #       end
+        #     end
+        #
       end
     end
   end

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

@@ -7,7 +7,7 @@ module OpenHAB
       class Transformation
         class << self
           # @!visibility private
-          alias_method :transform_raw, :transform if instance_methods.include?(:say)
+          alias_method :raw_transform, :transform if instance_methods.include?(:transform)
 
           #
           # Applies a transformation of a given type with some function to a value.
@@ -20,10 +20,10 @@ module OpenHAB
           # @return [String] the transformed value, or the original value if an error occurred
           #
           # @example Run a transformation
-          #   Transformation.transform(:map, "myfan.map", 0)
+          #   transform(:map, "myfan.map", 0)
           #
           def transform(type, function, value)
-            transform_raw(type.to_s.upcase, function.to_s, value.to_s)
+            raw_transform(type.to_s.upcase, function.to_s, value.to_s)
           end
         end
       end

data/lib/openhab/core/actions.rb

@@ -43,7 +43,7 @@ module OpenHAB
       end
 
       # Import common actions
-      %w[Exec HTTP Ping].each do |action|
+      %w[Exec HTTP Ping Transformation].each do |action|
         klass = (java_import "org.openhab.core.model.script.actions.#{action}").first
         Object.const_set(action, klass)
       end

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

@@ -7,71 +7,71 @@ module OpenHAB
     module Events
       java_import org.openhab.core.items.events.ItemCommandEvent
 
-      # Adds methods to core openHAB ItemCommandEvent to make it more natural in Ruby
+      # {AbstractEvent} sent when an item receives a command.
       class ItemCommandEvent < ItemEvent
         # @!attribute [r] command
         # @return [Command] The command sent to the item.
         alias_method :command, :item_command
 
         # @!method refresh?
-        #   Check if `self == REFRESH`
-        #   @return [true,false]
+        #   Check if {#command} is {REFRESH}
+        #   @return [true, false]
 
         # @!method on?
-        #   Check if `self == ON`
-        #   @return [true,false]
+        #   Check if {#command} is (implicitly convertible to) {ON}
+        #   @return [true, false]
 
         # @!method off?
-        #   Check if `self == OFF`
-        #   @return [true,false]
+        #   Check if {#command} is (implicitly convertible to) {OFF}
+        #   @return [true, false]
 
         # @!method up?
-        #   Check if `self == UP`
-        #   @return [true,false]
+        #   Check if {#command} is (implicitly convertible to) {UP}
+        #   @return [true, false]
 
         # @!method down?
-        #   Check if `self == DOWN`
-        #   @return [true,false]
+        #   Check if {#command} is (implicitly convertible to) {DOWN}
+        #   @return [true, false]
 
         # @!method stop?
-        #   Check if `self == STOP`
-        #   @return [true,false]
+        #   Check if {#command} is {STOP}
+        #   @return [true, false]
 
         # @!method move?
-        #   Check if `self == MOVE`
-        #   @return [true,false]
+        #   Check if {#command} is {MOVE}
+        #   @return [true, false]
 
         # @!method increase?
-        #   Check if `self == INCREASE`
-        #   @return [true,false]
+        #   Check if {#command} is {INCREASE}
+        #   @return [true, false]
 
         # @!method decrease?
-        #   Check if `self == DECREASE`
-        #   @return [true,false]
+        #   Check if {#command} is {DECREASE}
+        #   @return [true, false]
 
         # @!method play?
-        #   Check if `self == PLAY`
-        #   @return [true,false]
+        #   Check if {#command} is {PLAY}
+        #   @return [true, false]
 
         # @!method pause?
-        #   Check if `self == PAUSE`
-        #   @return [true,false]
+        #   Check if {#command} is {PAUSE}
+        #   @return [true, false]
 
         # @!method rewind?
-        #   Check if `self == REWIND`
-        #   @return [true,false]
+        #   Check if {#command} is {REWIND}
+        #   @return [true, false]
 
         # @!method fast_forward?
-        #   Check if `self == FASTFORWARD`
-        #   @return [true,false]
+        #   Check if {#command} is {FASTFORWARD}
+        #   @return [true, false]
 
         # @!method next?
-        #   Check if `self == NEXT`
-        #   @return [true,false]
+        #   Check if {#command} is {NEXT}
+        #   @return [true, false]
 
         # @!method previous?
-        #   Check if `self == PREVIOUS`
-        #   @return [true,false]
+        #   Check if {#command} is {PREVIOUS}
+        #   @return [true, false]
       end
     end
   end

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

@@ -8,32 +8,55 @@ module OpenHAB
       java_import org.openhab.core.items.events.ItemStateChangedEvent
 
       #
-      # Adds methods to core openHAB ItemStateChangedEvent to make it more natural in Ruby
+      # {AbstractEvent} sent when an item's state has changed.
       #
       class ItemStateChangedEvent < ItemEvent
         include ItemState
 
-        #
-        # Check if state was == {UNDEF}
-        #
-        # @return [true,false] True if the state is {UNDEF}, false otherwise
-        #
-        def was_undef?
-          old_item_state == UNDEF
-        end
+        # @!method was_undef?
+        #   Check if {#was} is {UNDEF}
+        #   @return [true, false]
 
-        #
-        # Check if state was == {NULL}
-        #
-        # @return [true,false] True if the state is {NULL}, false otherwise
-        def was_null?
-          old_item_state == NULL
-        end
+        # @!method was_null?
+        #   Check if {#was} is {NULL}
+        #   @return [true, false]
+
+        # @!method was_on?
+        #   Check if {#was} is (implicitly convertible to) {ON}
+        #   @return [true, false]
+
+        # @!method was_off?
+        #   Check if {#was} is (implicitly convertible to) {OFF}
+        #   @return [true, false]
+
+        # @!method was_up?
+        #   Check if {#was} is (implicitly convertible to) {UP}
+        #   @return [true, false]
+
+        # @!method was_down?
+        #   Check if {#was} is (implicitly convertible to) {DOWN}
+        #   @return [true, false]
+
+        # @!method was_open?
+        #   Check if {#was} is (implicitly convertible to) {OPEN}
+        #   @return [true, false]
+
+        # @!method was_closed?
+        #   Check if {#was} is (implicitly convertible to) {CLOSED}
+        #   @return [true, false]
+
+        # @!method was_playing?
+        #   Check if {#was} is {PLAY}
+        #   @return [true, false]
+
+        # @!method was_paused?
+        #   Check if {#was} is {PAUSE}
+        #   @return [true, false]
 
         #
         # Check if state was defined (not {UNDEF} or {NULL})
         #
-        # @return [true,false] True if state is not {UNDEF} or {NULL}
+        # @return [true,false]
         #
         def was?
           !old_item_state.is_a?(UnDefType)
@@ -41,7 +64,7 @@ module OpenHAB
 
         #
         # @!attribute [r] was
-        # @return [State, nil] The state of the item if it was not {UNDEF} or {NULL}, `nil` otherwise.
+        # @return [State, nil] the prior state of the item if it was not {UNDEF} or {NULL}, `nil` otherwise.
         #
         def was
           old_item_state if was?

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

@@ -5,29 +5,57 @@ module OpenHAB
     module Events
       java_import org.openhab.core.items.events.ItemStateEvent
 
+      #
       # Helpers common to {ItemStateEvent} and {ItemStateChangedEvent}.
+      #
+      # Methods that refer to implicit conversion mean that for example
+      # a PercentType of 100% will be `true` for {#on?}, etc.
+      #
       module ItemState
-        #
-        # Check if the state == {UNDEF}
-        #
-        # @return [true,false] True if the state is {UNDEF}, false otherwise
-        #
-        def undef?
-          item_state == UNDEF
-        end
+        # @!method undef?
+        #   Check if {#state} is {UNDEF}
+        #   @return [true, false]
 
-        #
-        # Check if the state == {NULL}
-        #
-        # @return [true,false] True if the state is {NULL}, false otherwise
-        def null?
-          item_state == NULL
-        end
+        # @!method null?
+        #   Check if {#state} is {NULL}
+        #   @return [true, false]
+
+        # @!method on?
+        #   Check if {#state} is (implicitly convertible to) {ON}
+        #   @return [true, false]
+
+        # @!method off?
+        #   Check if {#state} is (implicitly convertible to) {OFF}
+        #   @return [true, false]
+
+        # @!method up?
+        #   Check if {#state} is (implicitly convertible to) {UP}
+        #   @return [true, false]
+
+        # @!method down?
+        #   Check if {#state} is (implicitly convertible to) {DOWN}
+        #   @return [true, false]
+
+        # @!method open?
+        #   Check if {#state} is (implicitly convertible to) {OPEN}
+        #   @return [true, false]
+
+        # @!method closed?
+        #   Check if {#state} is (implicitly convertible to) {CLOSED}
+        #   @return [true, false]
+
+        # @!method playing?
+        #   Check if {#state} is {PLAY}
+        #   @return [true, false]
+
+        # @!method paused?
+        #   Check if {#state} is {PAUSE}
+        #   @return [true, false]
 
         #
-        # Check if the state is defined (not {UNDEF} or {NULL})
+        # Check if {#state} is defined (not {UNDEF} or {NULL})
         #
-        # @return [true,false] True if state is not {UNDEF} or {NULL}
+        # @return [true, false]
         #
         def state?
           !item_state.is_a?(UnDefType)
@@ -35,7 +63,7 @@ module OpenHAB
 
         #
         # @!attribute [r] state
-        # @return [State, nil] The state of the item if it is not {UNDEF} or {NULL}, `nil` otherwise.
+        # @return [State, nil] the state of the item if it is not {UNDEF} or {NULL}, `nil` otherwise.
         #
         def state
           item_state if state?

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

@@ -45,9 +45,10 @@ module OpenHAB
         # Time types need formatted as ISO8601
         # @!visibility private
         def format_type(command)
-          return Types::DateTimeType.new(command) if command.is_a?(java.time.ZonedDateTime)
+          return command if command.is_a?(Types::DateTimeType)
+          return Types::DateTimeType.new(command.to_zoned_date_time) if command.respond_to?(:to_zoned_date_time)
+          return Types::DateTimeType.new(DSL.try_parse_time_like(command.to_str)) if command.respond_to?(:to_str)
 
-          command = command.iso8601 if command.respond_to?(:iso8601)
           super
         end
       end

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

@@ -71,6 +71,34 @@ module OpenHAB
           !raw_state.is_a?(Types::UnDefType)
         end
 
+        # @!attribute [r] formatted_state
+        #
+        # Format the item's state according to its state description
+        #
+        # This may include running a transformation.
+        #
+        # @return [String]
+        #
+        # @example
+        #   logger.info(Exterior_WindDirection.formatted_state) # => "NE (36°)"
+        #
+        def formatted_state
+          # use to_string, not to_s, to get the original openHAB toString(), instead of any overrides
+          # the JRuby library has defined
+          raw_state_string = raw_state.to_string
+
+          return raw_state_string unless (pattern = state_description&.pattern)
+
+          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
+
+          transformed_state_string
+        rescue org.openhab.core.transform.TransformationException
+          raw_state_string
+        end
+
         #
         # @!attribute [r] state
         # @return [State, nil]
@@ -153,7 +181,7 @@ module OpenHAB
           return state if state.is_a?(Types::State)
 
           state = state.to_s
-          org.openhab.core.types.TypeParser.parse_state(getAcceptedDataTypes, state) || state
+          org.openhab.core.types.TypeParser.parse_state(getAcceptedDataTypes, state) || StringType.new(state)
         end
 
         # formats a {Types::Type} to send to the event bus
@@ -163,9 +191,99 @@ module OpenHAB
           # make sure to use Type, because this method is used for both
           # #update and #command
           return type if type.is_a?(Types::Type)
+          return NULL if type.nil?
 
           type.to_s
         end
+
+        #
+        # Defers notifying openHAB of modifications to multiple attributes until the block is complete.
+        #
+        # @param [true, false] force When true, allow modifications to file-based items.
+        #   Normally a FrozenError is raised when attempting to modify file-based items, since
+        #   they will then be out-of-sync with the definition on disk. Advanced users may do this
+        #   knowingly and intentionally though, so an escape hatch is provided to allow runtime
+        #   modifications.
+        # @yield
+        # @return [Object] the block's return value
+        #
+        # @example Modify label and tags for an item
+        #   MySwitch.modify do
+        #     MySwitch.label = "New Label"
+        #     MySwitch.tags = :labeled
+        #   end
+        #
+        def modify(force: false)
+          raise ArgumentError, "you must pass a block to modify" unless block_given?
+          return yield if instance_variable_defined?(:@modifying) && @modifying
+
+          begin
+            provider = self.provider
+            if provider && !provider.is_a?(org.openhab.core.common.registry.ManagedProvider)
+              raise FrozenError, "Cannot modify item #{name} from provider #{provider.inspect}." unless force
+
+              provider = nil
+              logger.debug("Forcing modifications to non-managed item #{name}")
+            end
+            @modified = false
+            @modifying = true
+
+            r = yield
+
+            provider&.update(self) if @modified
+            r
+          ensure
+            @modifying = false
+          end
+        end
+
+        # @!attribute [rw] label
+        # The item's descriptive label.
+        # @return [String]
+        def label=(value)
+          modify do
+            next if label == value
+
+            @modified = true
+            set_label(value)
+          end
+        end
+
+        # @!attribute [rw] category
+        # The item's category.
+        # @return [String]
+        def category=(value)
+          modify do
+            value = value&.to_s
+            next if category == value
+
+            @modified = true
+            set_category(value)
+          end
+        end
+
+        # @!attribute [rw] tags
+        #   The item's tags
+        #   @return [Array<String>]
+        #   @overload tags
+        #     Returns the item's tags.
+        #     @return [Array<String>]
+        #   @overload tags=(values)
+        #     Sets the item's tags.
+        #
+        #     To remove all tags, assign an empty array or nil.
+        #     @param [Array<String,Symbol,Semantics::Tag>] values Tags to set.
+        #     @return [void]
+        def tags=(values)
+          modify do
+            values = DSL::Items::ItemBuilder.normalize_tags(*values)
+            next if values.to_set == tags.to_set
+
+            @modified = true
+            remove_all_tags
+            add_tags(values)
+          end
+        end
       end
     end
   end