openhab-scripting 4.1.1 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2210f9eb88b639bd2ca594cce368ec87ee7746595f7b2f9c04e7bd1ebdf10fc3
-  data.tar.gz: 9dae7f3f53574ba089c37c52e35e110c596a09deb3005ced5a267d18d64b1f3b
+  metadata.gz: 4ebe32d36d3366345d28b81bc71d9cd315d1d84feb4a4f1745c882209b1fdbe2
+  data.tar.gz: 95331e97286e86bc993eb979531c5e3f80bc203e752e97aa9f3a60698fd56274
 SHA512:
-  metadata.gz: be659fbac0f529674ffb4a38944e1f2365fa82a08bbc832edb0ad3a5f074ec683454980050758ba6810b52abaf42d8ab8f442d73276de4fe38d51a8984e7b61a
-  data.tar.gz: a58d4df593b831c3daf979b2d0094691e22d2be849a375c9bf7c0a30d78e9e4d71d36adfa85d918debd1a8e948ec9b6d7b57e933f9eb791cf9d769ee5ce02193
+  metadata.gz: e406fa7d011a733376bb5977293f44d20b893f1f990486f342c541f8d287c453736b75007ba586bfc5e6801638ac71bc6d294ad1b4a436a83247bee157150eb0
+  data.tar.gz: d4fad57e6ad4f71a969b8f8c6791c4240854a74800647a4bed770123221eb2491c251c2a28bcbcd1649225d348aadd91b0efc188adba16a56aa7115620224028

data/lib/openhab/core/entity_lookup.rb

@@ -3,13 +3,6 @@
 require 'pp'
 require 'java'
 require 'set'
-require 'openhab/dsl/group'
-require 'openhab/log/logger'
-require 'openhab/dsl/items/number_item'
-require 'openhab/dsl/items/string_item'
-require 'openhab/dsl/items/datetime_item'
-require 'openhab/dsl/items/rollershutter_item'
-require 'openhab/dsl/items/group_item'
 
 # Automation lookup and injection of OpenHab entities
 
@@ -68,52 +61,6 @@ module OpenHAB
         lookup_item(name) || lookup_thing(name)
       end
 
-      #
-      # Decorate items with Ruby wrappers
-      #
-      # @param [Array] items Array of items to decorate
-      #
-      # @return [Array] Array of decorated items
-      #
-      def self.decorate_items(*items)
-        items.flatten.map { |item| decorate_item(item) }
-      end
-
-      #
-      # Decorate item with Ruby wrappers
-      #
-      # @param [Object] item the item object to decorate
-      #
-      # @return [Object] the ruby wrapper for the item
-      #
-      # rubocop: disable Metrics/MethodLength
-      # rubocop: disable Metrics/CyclomaticComplexity
-      # Disabled line length and branch size - case dispatch pattern
-      def self.decorate_item(item)
-        logger.trace("Decorating #{item.class}")
-        case item
-        when Java::OrgOpenhabCoreItems::GroupItem
-          OpenHAB::DSL::Items::GroupItem.new(item)
-        when Java::OrgOpenhabCoreLibraryItems::NumberItem
-          OpenHAB::DSL::Items::NumberItem.new(item)
-        when Java::OrgOpenhabCoreLibraryItems::StringItem
-          OpenHAB::DSL::Items::StringItem.new(item)
-        when Java::OrgOpenhabCoreLibraryItems::DateTimeItem
-          OpenHAB::DSL::Items::DateTimeItem.new(item)
-        when Java::OrgOpenhabCoreLibraryItems::RollershutterItem
-          OpenHAB::DSL::Items::RollershutterItem.new(item)
-        when Java::OrgOpenhabCoreLibraryItems::PlayerItem
-          OpenHAB::DSL::Items::PlayerItem.new(item)
-        when Java::OrgOpenhabCoreLibraryItems::ImageItem
-          OpenHAB::DSL::Items::ImageItem.new(item)
-        else
-          logger.trace("Returning undecorated item #{item.class}")
-          item
-        end
-      end
-      # rubocop: enable Metrics/MethodLength
-      # rubocop: enable Metrics/CyclomaticComplexity
-
       #
       # Looks up a Thing in the OpenHAB registry replacing '_' with ':'
       #
@@ -145,10 +92,7 @@ module OpenHAB
       def self.lookup_item(name)
         logger.trace("Looking up item(#{name})")
         name = name.to_s if name.is_a? Symbol
-        # rubocop: disable Style/GlobalVars
-        item = $ir.get(name)
-        # rubocop: enable Style/GlobalVars
-        decorate_item(item)
+        $ir.get(name) # rubocop: disable Style/GlobalVars
       end
     end
   end

data/lib/openhab/dsl/dsl.rb

@@ -1,29 +1,23 @@
 # frozen_string_literal: true
 
-require 'java'
 require 'openhab/log/logger'
-require 'openhab/dsl/monkey_patch/events/events'
+
+# the order of these is important
+require 'openhab/dsl/types/types'
+require 'openhab/dsl/items/items'
 require 'openhab/dsl/monkey_patch/ruby/ruby'
-require 'openhab/dsl/monkey_patch/items/items'
-require 'openhab/dsl/monkey_patch/types/types'
+
+require 'openhab/dsl/monkey_patch/events/events'
 require 'openhab/dsl/monkey_patch/actions/actions'
 require 'openhab/dsl/rules/rule'
 require 'openhab/dsl/actions'
 require 'openhab/dsl/timers'
 require 'openhab/dsl/group'
 require 'openhab/dsl/things'
-require 'openhab/dsl/items/items'
-require 'openhab/dsl/items/datetime_item'
-require 'openhab/dsl/items/image_item'
-require 'openhab/dsl/items/number_item'
-require 'openhab/dsl/items/player_item'
-require 'openhab/dsl/items/group_item'
 require 'openhab/dsl/time_of_day'
 require 'openhab/dsl/gems'
 require 'openhab/dsl/persistence'
 require 'openhab/dsl/units'
-require 'openhab/dsl/types/datetime'
-require 'openhab/dsl/types/quantity'
 require 'openhab/dsl/states'
 
 module OpenHAB

data/lib/openhab/dsl/group.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-require 'delegate'
-require 'forwardable'
-require 'openhab/core/entity_lookup'
-require 'openhab/dsl/items/group_item'
+require 'singleton'
+
+require 'openhab/dsl/lazy_array'
 
 module OpenHAB
   module DSL
@@ -14,16 +13,26 @@ module OpenHAB
       #
       # Provide access to groups as a set
       #
-      class Groups < SimpleDelegator
+      class Groups
+        include LazyArray
+        include Singleton
+
         #
         # Get a OpenHAB Group by name
         # @param [String] name of the group to retrieve
         #
         # @return [Set] of OpenHAB Groups
         #
-        def[](name)
-          group = OpenHAB::Core::EntityLookup.lookup_item(name)
-          group.is_a?(OpenHAB::DSL::Items::GroupItem) ? group : nil
+        def [](name)
+          group = Core::EntityLookup.lookup_item(name)
+          group.is_a?(Items::GroupItem) ? group : nil
+        end
+        alias include? []
+        alias key? include?
+
+        # explicit conversion to array
+        def to_a
+          $ir.items.grep(org.openhab.core.items.GroupItem) # rubocop:disable Style/GlobalVars
         end
       end
 
@@ -33,9 +42,7 @@ module OpenHAB
       # @return [Set] of OpenHAB Groups
       #
       def groups
-        # rubocop: disable Style/GlobalVars
-        Groups.new(OpenHAB::Core::EntityLookup.decorate_items($ir.items.grep(Java::OrgOpenhabCoreItems::GroupItem)))
-        # rubocop: enable Style/GlobalVars
+        Groups.instance
       end
     end
   end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Items
+      # Mixin for implementing the comparison operator for Item types that
+      # support it
+      module ComparableItem
+        #
+        # Comparison
+        #
+        # @param [GenericItem, Types::Type, Object] other object to
+        #   compare to
+        #
+        #   If this item is +NULL+ or +UNDEF+, and +other+ is nil, they are
+        #   considered equal
+        #
+        #   If this item is +NULL+ or +UNDEF+, and other is a {GenericItem}, they
+        #   are only considered equal if the other item is in the exact same
+        #   state (i.e. +NULL+ != +UNDEF+)
+        #
+        #   Otherwise, the state of this item is compared with +other+
+        #
+        # @return [Integer, nil] -1, 0, +1 depending on whether +other+ is
+        #   less than, equal to, or greater than self
+        #
+        #   nil is returned if the two values are incomparable
+        #
+        def <=>(other)
+          logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
+          # if we're NULL or UNDEF, implement special logic
+          unless state?
+            # if comparing to nil, consider ourselves equal
+            return 0 if other.nil?
+            # if the other object is an Item, only consider equal if we're
+            # in the same _kind_ of UnDefType state
+            return raw_state == other.raw_state if other.is_a?(GenericItem) && !other.state?
+
+            # otherwise, it's a non-nil thing comparing to nil, which is undefined
+            return nil
+          end
+
+          # delegate to how the state compares to the other object
+          state <=> other
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Patches OpenHAB items
+    #
+    module Items
+      java_import org.openhab.core.library.items.ContactItem
+
+      # Alias class for ContactItem
+      ::Contact = ContactItem
+
+      # Adds methods to core OpenHAB ContactItem type to make it more natural
+      # in Ruby
+      class ContactItem < GenericItem
+        remove_method :==
+
+        #
+        # Return the inverted state of the contact: +CLOSED+ if the contact is
+        # +OPEN+, +UNDEF+ or +NULL+; +OPEN+ if the contact is +CLOSED+
+        #
+        # @return [Types::OpenClosedType] Inverted state
+        #
+        def !
+          return !state if state?
+
+          CLOSED
+        end
+
+        # @!method open?
+        #   Check if the item state == +OPEN+
+        #   @return [Boolean]
+
+        # @!method closed?
+        #   Check if the item state == +CLOSED+
+        #   @return [Boolean]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'time'
+
+require 'openhab/dsl/items/comparable_item'
+
+module OpenHAB
+  module DSL
+    module Items
+      java_import org.openhab.core.library.items.DateTimeItem
+
+      # Adds methods to core OpenHAB DateTimeItem type to make it more natural
+      # in Ruby
+      class DateTimeItem < GenericItem
+        extend Forwardable
+        include Comparable
+        include ComparableItem
+
+        # !@visibility private
+        def ==(other)
+          # need to check if we're referring to the same item before
+          # forwarding to <=> (and thus checking equality with state)
+          return true if equal?(other) || eql?(other)
+
+          super
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a DateTimeType
+        #
+        # @param [Types::DateTimeType, Time] other object to coerce to a
+        #   DateTimeType
+        #
+        # @return [[Types::DateTimeType, Types::DateTimeType]]
+        #
+        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::DateTimeType) || other.respond_to?(:to_time)
+
+          raise TypeError, "can't convert #{other.class} into #{self.class}"
+        end
+
+        # any method that exists on DateTimeType, Java's ZonedDateTime, or
+        # Ruby's Time class gets forwarded to state (which will forward as
+        # necessary)
+        delegate ((Types::DateTimeType.instance_methods +
+          java.time.ZonedDateTime.instance_methods +
+          Time.instance_methods) - instance_methods) => :state
+
+        # Time types need formatted as ISO8601
+        # @!visibility private
+        def format_type(command)
+          return command.iso8601 if command.respond_to?(:iso8601)
+
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'openhab/dsl/time_of_day'
+
+require_relative 'numeric_item'
+
+module OpenHAB
+  module DSL
+    #
+    # Patches OpenHAB items
+    #
+    module Items
+      java_import org.openhab.core.library.items.DimmerItem
+
+      # Alias class
+      ::Dimmer = DimmerItem
+
+      # Adds methods to core OpenHAB DimmerItem type to make it more natural in
+      # Ruby
+      class DimmerItem < SwitchItem
+        include NumericItem
+
+        #
+        # Dim the dimmer
+        #
+        # @param [Integer] amount to dim by
+        #
+        # @return [Integer] level target for dimmer
+        #
+        def dim(amount = 1)
+          target = [state&.-(amount), 0].compact.max
+          command(target)
+          target
+        end
+
+        #
+        # Brighten the dimmer
+        #
+        # @param [Integer] amount to brighten by
+        #
+        # @return [Integer] level target for dimmer
+        #
+        def brighten(amount = 1)
+          target = [state&.+(amount), 100].compact.min
+          command(target)
+          target
+        end
+
+        # @!method increase
+        #   Send the +INCREASE+ command to the item
+        #   @return [DimmerItem] +self+
+
+        # @!method decrease
+        #   Send the +DECREASE+ command to the item
+        #   @return [DimmerItem] +self+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'openhab/dsl/items/metadata'
+require 'openhab/dsl/items/persistence'
+
+module OpenHAB
+  module DSL
+    module Items
+      java_import org.openhab.core.items.GenericItem
+
+      # Adds methods to core OpenHAB DimmerItem type to make it more natural in
+      # Ruby
+      class GenericItem
+        include Log
+        prepend Metadata
+        prepend Persistence
+
+        # rubocop:disable Naming/MethodName these mimic Java fields, which are
+        # actually methods
+        class << self
+          # manually define this, since the Java side doesn't
+          # @!visibility private
+          def ACCEPTED_COMMAND_TYPES
+            [org.openhab.core.types.RefreshType.java_class].freeze
+          end
+
+          # manually define this, since the Java side doesn't
+          # @!visibility private
+          def ACCEPTED_DATA_TYPES
+            [org.openhab.core.types.UnDefType.java_class].freeze
+          end
+        end
+        # rubocop:enable Naming/MethodName
+
+        alias hash hash_code
+
+        # Get the raw item state.
+        #
+        # The state of the item, including possibly +NULL+ or +UNDEF+
+        #
+        # @return [Types::Type]
+        #
+        alias raw_state state
+
+        remove_method(:==)
+
+        #
+        # Send a command to this item
+        #
+        # @param [Types::Type] command to send to object
+        #
+        #
+        def command(command)
+          command = format_type_pre(command)
+          logger.trace "Sending Command #{command} to #{id}"
+          org.openhab.core.model.script.actions.BusEvent.sendCommand(self, command)
+          self
+        end
+        alias << command
+
+        #
+        # Send an update to this item
+        #
+        # @param [Types::Type] update the item
+        #
+        #
+        def update(update)
+          update = format_type_pre(update)
+          logger.trace "Sending Update #{update} to #{id}"
+          org.openhab.core.model.script.actions.BusEvent.postUpdate(self, update)
+          self
+        end
+
+        #
+        # Check if the item has a state (not +UNDEF+ or +NULL+)
+        #
+        # @return [Boolean]
+        #
+        def state?
+          !raw_state.is_a?(Types::UnDefType)
+        end
+
+        #
+        # Get the item state
+        #
+        # @return [Types::Type, nil]
+        #   OpenHAB item state if state is not +UNDEF+ or +NULL+, nil otherwise
+        #
+        def state
+          raw_state if state?
+        end
+
+        #
+        # Get an ID for the item, using the item label if set, otherwise item name
+        #
+        # @return [String] label if set otherwise name
+        #
+        def id
+          label || name
+        end
+
+        #
+        # Get the string representation of the state of the item
+        #
+        # @return [String] State of the item as a string
+        #
+        def to_s
+          raw_state.to_s # call the super state to include UNDEF/NULL
+        end
+
+        #
+        # Inspect the item
+        #
+        # @return [String] details of the item
+        #
+        def inspect
+          to_string
+        end
+
+        #
+        # Return all groups that this item is part of
+        #
+        # @return [Array<Group>] All groups that this item is part of
+        #
+        def groups
+          group_names.map { |name| Groups.groups[name] }
+        end
+
+        #
+        # Check equality without type conversion
+        #
+        # @return [Boolean] if the same Item is represented, without checking
+        #   state
+        def eql?(other)
+          other.instance_of?(self.class) && hash == other.hash
+        end
+
+        #
+        # Check equality, with type conversions
+        #
+        # @param [GenericItem, Types::Type, Object] other object to
+        #   compare to
+        #
+        #   If this item is +NULL+ or +UNDEF+, and +other+ is nil, they are
+        #   considered equal
+        #
+        #   If this item is +NULL+ or +UNDEF+, and other is a {GenericItem}, they
+        #   are only considered equal if the other item is in the exact same
+        #   state (i.e. +NULL+ != +UNDEF+)
+        #
+        #   Otherwise, the state of this item is compared with +other+
+        #
+        # @return [Boolean]
+        #
+        def ==(other)
+          logger.trace("(#{self.class}) #{self} == #{other} (#{other.class})")
+          return true if equal?(other) || eql?(other)
+          return true if !state? && other.nil?
+
+          return raw_state == other.raw_state if other.is_a?(GenericItem)
+
+          state == other
+        end
+
+        # @!method null?
+        #   Check if the item state == +NULL+
+        #   @return [Boolean]
+
+        # @!method undef?
+        #   Check if the item state == +UNDEF+
+        #   @return [Boolean]
+
+        # @!method refresh
+        #   Send the +REFRESH+ command to the item
+        #   @return [GenericItem] +self+
+
+        # formats a {Types::Type} to send to the event bus
+        # @!visibility private
+        def format_type(command)
+          # actual Type types can be sent directly without conversion
+          return command if command.is_a?(Types::Type)
+
+          command.to_s
+        end
+
+        private
+
+        # convert items to their state before formatting, so that subclasses
+        # only have to deal with Types
+        def format_type_pre(command)
+          command = command.state if command.is_a?(GenericItem)
+          format_type(command)
+        end
+      end
+    end
+  end
+end