openhab-scripting 4.1.4 → 4.2.0

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'openhab/dsl/items/comparable_item'
+
+module OpenHAB
+  module DSL
+    module Items
+      # Mixin for implementing type coercieon, equality, and arithmetic for
+      # number-like items
+      module NumericItem
+        include Comparable
+        include ComparableItem
+
+        # apply meta-programming methods to including class
+        def self.included(klass)
+          klass.extend Forwardable
+          klass.delegate %i[+ - * / % | positive? negative? to_d to_f to_i to_int zero?] => :state
+          # remove the JRuby default == so that we can inherit the Ruby method
+          klass.remove_method :==
+        end
+
+        #
+        # Check if NumericItem is truthy? as per defined by library
+        #
+        # @return [Boolean] True if item is not in state +UNDEF+ or +NULL+ and value is not zero.
+        #
+        def truthy?
+          state && !state.zero?
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a NumericType
+        #
+        # @param [Types::NumericType, Numeric] other object to coerce to a
+        #   DateTimeType
+        #
+        # @return [[Types::NumericType, Types::NumericType]]
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} as a request from #{other.class}")
+          return [other, nil] unless state?
+          return [other, state] if other.is_a?(Types::NumericType) || other.respond_to?(:to_d)
+
+          raise TypeError, "can't convert #{other.class} into #{self.class}"
+        end
+
+        # strip trailing zeros from commands
+        # @!visibility private
+        def format_type(command)
+          # DecimalType and PercentType we want to make sure we don't have extra zeros
+          if command.instance_of?(Types::DecimalType) || command.instance_of?(Types::PercentType)
+            return command.to_big_decimal.strip_trailing_zeros.to_plain_string
+          end
+          # BigDecimal types have trailing zeros stripped
+          return command.to_java.strip_trailing_zeros.to_plain_string if command.is_a?(BigDecimal)
+
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Items
+      #
+      # Persistence extension for Items
+      #
+      module Persistence
+        java_import Java::OrgOpenhabCoreTypesUtil::UnitUtils
+
+        # A wrapper for OpenHAB's HistoricItem that returns the state directly
+        class HistoricState < SimpleDelegator
+          attr_reader :timestamp, :state
+
+          def initialize(state, timestamp)
+            @state = state
+            @timestamp = timestamp
+            super(@state)
+          end
+        end
+
+        # All persistence methods that could return a QuantityType
+        QUANTITY_METHODS = %i[average_since
+                              delta_since
+                              deviation_since
+                              sum_since
+                              variance_since].freeze
+
+        # All persistence methods that require a timestamp
+        PERSISTENCE_METHODS = (QUANTITY_METHODS +
+                              %i[changed_since
+                                 evolution_rate
+                                 historic_state
+                                 maximum_since
+                                 minimum_since
+                                 updated_since]).freeze
+        private_constant :QUANTITY_METHODS, :PERSISTENCE_METHODS
+
+        %i[persist last_update].each do |method|
+          define_method(method) do |service = nil|
+            service ||= persistence_service
+            PersistenceExtensions.public_send(method, self, service&.to_s)
+          end
+        end
+
+        #
+        # Return the previous state of the item
+        #
+        # @param skip_equal [Boolean] if true, skips equal state values and
+        #        searches the first state not equal the current state
+        # @param service [String] the name of the PersistenceService to use
+        #
+        # @return the previous state or nil if no previous state could be found,
+        #         or if the default persistence service is not configured or
+        #         does not refer to a valid service
+        #
+        def previous_state(service = nil, skip_equal: false)
+          service ||= persistence_service
+          result = PersistenceExtensions.previous_state(self, skip_equal, service&.to_s)
+          HistoricState.new(quantify(result.state), result.timestamp)
+        end
+
+        PERSISTENCE_METHODS.each do |method|
+          define_method(method) do |timestamp, service = nil|
+            service ||= persistence_service
+            result = PersistenceExtensions.public_send(method, self, to_zdt(timestamp), service&.to_s)
+            if result.is_a? Java::OrgOpenhabCorePersistence::HistoricItem
+              return HistoricState.new(quantify(result.state), result.timestamp)
+            end
+
+            QUANTITY_METHODS.include?(method) ? quantify(result) : result
+          end
+        end
+
+        private
+
+        #
+        # Convert timestamp to ZonedDateTime if it's a TemporalAmount
+        #
+        # @param [Object] timestamp to convert
+        #
+        # @return [ZonedDateTime]
+        #
+        def to_zdt(timestamp)
+          if timestamp.is_a? Java::JavaTimeTemporal::TemporalAmount
+            logger.trace("Converting #{timestamp} (#{timestamp.class}) to ZonedDateTime")
+            Java::JavaTime::ZonedDateTime.now.minus(timestamp)
+          else
+            timestamp
+          end
+        end
+
+        #
+        # Convert value to QuantityType if it is a DecimalType and a unit is defined
+        #
+        # @param [Object] value The value to convert
+        #
+        # @return [Object] QuantityType or the original value
+        #
+        def quantify(value)
+          if value.is_a?(Types::DecimalType) && state_description&.pattern
+            item_unit = UnitUtils.parse_unit(state_description.pattern)
+            logger.trace("Unitizing #{value} with unit #{item_unit}")
+            Types::QuantityType.new(value.to_big_decimal, item_unit)
+          else
+            value
+          end
+        end
+
+        #
+        # Get the specified persistence service from the current thread local variable
+        #
+        # @return [Object] Persistence service name as String or Symbol, or nil if not set
+        #
+        def persistence_service
+          Thread.current.thread_variable_get(:persistence_service)
+        end
+      end
+    end
+  end
+end

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

@@ -1,48 +1,57 @@
 # frozen_string_literal: true
 
-require 'forwardable'
-require 'java'
-require 'openhab/dsl/items/item_command'
-require 'openhab/dsl/items/item_delegate'
-
 module OpenHAB
   module DSL
     module Items
-      #
-      # Delegator to OpenHAB Player Item
-      #
-      class PlayerItem
-        extend OpenHAB::DSL::Items::ItemCommand
-        extend OpenHAB::DSL::Items::ItemDelegate
-        extend Forwardable
-
-        def_item_delegator :@player_item
-
-        item_type Java::OrgOpenhabCoreLibraryItems::PlayerItem, :play? => :playing?,
-                                                                :pause? => :paused?,
-                                                                :rewind? => :rewinding?,
-                                                                :fastforward? => :fastforwarding?
-
-        # rubocop: disable Style/Alias
-        # Disabled because 'alias' does not work with the dynamically defined methods
-        alias_method :fast_forward, :fastforward
-        alias_method :fast_forwarding?, :fastforwarding?
-        # rubocop: enable Style/Alias
-
-        #
-        # Creates a new PlayerItem
-        #
-        # @param [Java::OrgOpenhabCoreLibraryItems::PlayerItem] player_item
-        #   The OpenHAB PlayerItem to delegate to
-        #
-        def initialize(player_item)
-          logger.trace("Wrapping #{player_item}")
-          @player_item = player_item
-
-          item_missing_delegate { @player_item }
-
-          super()
-        end
+      java_import org.openhab.core.library.items.PlayerItem
+
+      # Adds methods to core OpenHAB NumberItem type to make it more natural in
+      # Ruby
+      class PlayerItem < GenericItem
+        remove_method :==
+
+        # @!method play?
+        #   Check if the item state == +PLAYING+
+        #   @return [Boolean]
+
+        # @deprecated
+        # @!parse alias play? playing?
+
+        # @!method paused?
+        #   Check if the item state == +PAUSED+
+        #   @return [Boolean]
+
+        # @!method rewinding?
+        #   Check if the item state == +REWIND+
+        #   @return [Boolean]
+
+        # @!method fast_forwarding?
+        #   Check if the item state == +FASTFORWARD+
+        #   @return [Boolean]
+
+        # @!method play
+        #   Send the +PLAY+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method pause
+        #   Send the +PAUSE+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method rewind
+        #   Send the +REWIND+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method fast_forward
+        #   Send the +FASTFORWARD+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method next
+        #   Send the +NEXT+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method previous
+        #   Send the +PREVIOUS+ command to the item
+        #   @return [PlayerItem] +self+
       end
     end
   end

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

@@ -1,94 +1,42 @@
 # frozen_string_literal: true
 
-require 'forwardable'
-require 'java'
-require 'openhab/dsl/items/item_command'
-require 'openhab/dsl/items/item_delegate'
+require_relative 'numeric_item'
 
 module OpenHAB
   module DSL
     module Items
-      #
-      # Delegator to OpenHAB Rollershutter Item
-      #
-      class RollershutterItem < Numeric
-        extend Forwardable
-        extend OpenHAB::DSL::Items::ItemCommand
-        extend OpenHAB::DSL::Items::ItemDelegate
-        include Comparable
+      java_import org.openhab.core.library.items.RollershutterItem
 
-        def_item_delegator :@rollershutter_item
+      # Adds methods to core OpenHAB RollershutterItem type to make it more natural in
+      # Ruby
+      class RollershutterItem < GenericItem
+        include NumericItem
 
-        item_type Java::OrgOpenhabCoreLibraryItems::RollershutterItem
+        alias position state
 
-        #
-        # Creates a new RollershutterItem
-        #
-        # @param [Java::OrgOpenhabCoreLibraryItems::RollershutterItem] rollershutter_item
-        #   The OpenHAB RollershutterItem to delegate to
-        #
-        def initialize(rollershutter_item)
-          logger.trace("Wrapping #{rollershutter_item}")
-          @rollershutter_item = rollershutter_item
+        # @!method up?
+        #   Check if the item state == +UP+
+        #   @return [Boolean]
 
-          item_missing_delegate { @rollershutter_item }
-          item_missing_delegate { position }
+        # @!method down?
+        #   Check if the item state == +DOWN+
+        #   @return [Boolean]
 
-          super()
-        end
+        # @!method up
+        #   Send the +UP+ command to the item
+        #   @return [RollershutterItem] +self+
 
-        #
-        # Returns the rollershutter's position
-        #
-        # @return [Java::OrgOpenhabCoreLibraryTypes::PercentType] the position of the rollershutter
-        #
-        def position
-          state&.as(PercentType)
-        end
+        # @!method down
+        #   Send the +DOWN+ command to the item
+        #   @return [RollershutterItem] +self+
 
-        #
-        # Compare the rollershutter's position against another object
-        #
-        # @param [Object] other object to compare against
-        #
-        # @return [Integer] -1, 0 or 1 depending on the result of the comparison
-        #
-        def <=>(other)
-          return nil unless state?
+        # @!method stop
+        #   Send the +STOP+ command to the item
+        #   @return [RollershutterItem] +self+
 
-          case other
-          when PercentType, Java::OrgOpenhabCoreLibraryTypes::DecimalType then position.compare_to(other)
-          when Numeric then position.int_value <=> other
-          when RollershutterItem then position.compare_to(other.position)
-          when UpDownType then state.as(UpDownType) == other
-          end
-        end
-
-        #
-        # Coerce self into other to enable calculations
-        #
-        # @param [Numeric] other Other numeric to coerce into
-        #
-        # @return [Array<Numeric>] an array of other and self coerced into other's type
-        #
-        def coerce(other)
-          raise ArgumentError, "Cannot coerce to #{other.class}" unless other.is_a? Numeric
-
-          case other
-          when Integer then [other, position&.int_value]
-          when Float then [other, position&.float_value]
-          end
-        end
-
-        #
-        # Define math operations
-        #
-        %i[+ - * / %].each do |operator|
-          define_method(operator) do |other|
-            right, left = coerce(other)
-            left&.send(operator, right)
-          end
-        end
+        # @!method move
+        #   Send the +MOVE+ command to the item
+        #   @return [RollershutterItem] +self+
       end
     end
   end

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

@@ -1,63 +1,36 @@
 # frozen_string_literal: true
 
-require 'bigdecimal'
 require 'forwardable'
-require 'java'
-require 'openhab/dsl/items/item_delegate'
+
+require 'openhab/dsl/items/comparable_item'
 
 module OpenHAB
   module DSL
     module Items
-      #
-      # Delegator to OpenHAB String Item
-      #
-      class StringItem
+      java_import org.openhab.core.library.items.StringItem
+
+      # Adds methods to core OpenHAB StringItem type to make it more natural in
+      # Ruby
+      class StringItem < GenericItem
         extend Forwardable
-        extend OpenHAB::DSL::Items::ItemCommand
         include Comparable
-        extend OpenHAB::DSL::Items::ItemDelegate
+        include ComparableItem
+
+        remove_method :==
 
         # @return [Regex] Regular expression matching blank strings
         BLANK_RE = /\A[[:space:]]*\z/.freeze
         private_constant :BLANK_RE
 
-        def_item_delegator :@string_item
-
-        item_type Java::OrgOpenhabCoreLibraryItems::StringItem
-
-        #
-        # Create a new StringItem
-        #
-        # @param [Java::Org::openhab::core::library::items::StringItem] string_item OpenHAB string item to delegate to
-        #
-        def initialize(string_item)
-          @string_item = string_item
-
-          item_missing_delegate { @string_item }
-          item_missing_delegate { @string_item.state&.to_full_string&.to_s }
-
-          super()
-        end
-
-        #
-        # Convert the StringItem into a String
-        #
-        # @return [String] String representation of the StringItem or
-        #   nil if underlying OpenHAB StringItem does not have a state
-        #
-        def to_str
-          @string_item.state&.to_full_string&.to_s
-        end
-
         #
         # Detect if the string is blank (not set or only whitespace)
         #
         # @return [Boolean] True if string item is not set or contains only whitespace, false otherwise
         #
         def blank?
-          return true unless @string_item.state?
+          return true unless state?
 
-          @string_item.state.to_full_string.to_s.empty? || BLANK_RE.match?(self)
+          state.empty? || BLANK_RE.match?(self)
         end
 
         #
@@ -66,27 +39,12 @@ module OpenHAB
         # @return [Boolean] True if item is not in state UNDEF or NULL and value is not blank
         #
         def truthy?
-          @string_item.state? && blank? == false
+          state? && !blank?
         end
 
-        #
-        # Compare StringItem to supplied object
-        #
-        # @param [Object] other object to compare to
-        #
-        # @return [Integer] -1,0,1 or nil depending on value supplied,
-        #   nil comparison to supplied object is not possible.
-        #
-        def <=>(other)
-          case other
-          when StringItem
-            @string_item.state <=> other.state
-          when String
-            @string_item.state.to_s <=> other
-          else
-            @string_item.state <=> other
-          end
-        end
+        # any method that exists on String gets forwarded to state (which will forward as
+        # necessary)
+        delegate (String.instance_methods - instance_methods) => :state
       end
     end
   end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Patches OpenHAB items
+    #
+    module Items
+      java_import org.openhab.core.library.items.SwitchItem
+
+      # Alias class names for easy is_a? comparisons
+      ::Switch = SwitchItem
+
+      # Adds methods to core OpenHAB SwitchItem type to make it more natural in
+      # Ruby
+      class SwitchItem < GenericItem
+        remove_method :==
+
+        def truthy?
+          on?
+        end
+
+        #
+        # Send a command to invert the state of the switch
+        #
+        # @return [Types::OnOffType] Inverted state
+        #
+        def toggle
+          command(!self)
+        end
+
+        #
+        # Return the inverted state of the switch: +ON+ if the switch is +OFF+,
+        # +UNDEF+ or +NULL+; +OFF+ if the switch is +ON+
+        #
+        # @return [Types::OnOffType] Inverted state
+        #
+        def !
+          return !state if state?
+
+          ON
+        end
+
+        # @!method on?
+        #   Check if the item state == +ON+
+        #   @return [Boolean]
+
+        # @!method off?
+        #   Check if the item state == +OFF+
+        #   @return [Boolean]
+
+        # @!method on
+        #   Send the +ON+ command to the item
+        #   @return [SwitchItem] +self+
+
+        # @!method off
+        #   Send the +OFF+ command to the item
+        #   @return [SwitchItem] +self+
+      end
+    end
+  end
+end

data/lib/openhab/dsl/lazy_array.rb

@@ -2,7 +2,7 @@
 
 module OpenHAB
   module DSL
-    # common base class for array-like collections that have lookup
+    # Common base class for array-like collections that have lookup
     # methods to avoid instantiating the elements if you only use
     # the lookup method
     #
@@ -11,7 +11,7 @@ module OpenHAB
     module LazyArray
       include Enumerable
 
-      # Calls the given block once for each Thing, passing that Thing as a
+      # Calls the given block once for each object, passing that object as a
       # parameter. Returns self.
       #
       # If no block is given, an Enumerator is returned.
@@ -20,20 +20,22 @@ module OpenHAB
         self
       end
 
-      # implicitly convertible to array
+      # Implicitly convertible to array
+      #
+      # @return [Array]
+      #
       def to_ary
         to_a
       end
 
-      # delegate any other methods to the actual array
-      # exclude mutating methods though
+      # Delegate any other methods to the actual array, exclude mutating methods
       def method_missing(method, *args, &block)
         return to_a.send(method, *args, &block) if method[-1] != '!' && Array.instance_methods.include?(method)
 
         super
       end
 
-      # advertise that methods exist that would be delegated to Array
+      # @!visibility private
       def respond_to_missing?(method, include_private = false)
         return true if method[-1] != '!' && Array.instance_methods.include?(method.to_sym)
 

data/lib/openhab/dsl/monkey_patch/events/events.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'openhab/dsl/monkey_patch/events/item_state'
 require 'openhab/dsl/monkey_patch/events/item_event'
+require 'openhab/dsl/monkey_patch/events/item_state'
 require 'openhab/dsl/monkey_patch/events/item_state_changed'
-require 'openhab/dsl/monkey_patch/events/thing_status_info'
 require 'openhab/dsl/monkey_patch/events/item_command'
+require 'openhab/dsl/monkey_patch/events/thing_status_info'