openhab-scripting 4.1.3 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a66939406a04523ae992c37d0ec6c4d83ca5334e156d4211e883dd51085a282f
-  data.tar.gz: f93569799fdd9c01e3d678619655484f799d7a9c3dcab43222cc49e8051cc8cd
+  metadata.gz: a39d84f4797ad4d9807e581919e5a681e0b6ba52df5a64f395bc2409cb2d7f38
+  data.tar.gz: d56eb7cb6e9a3a50dd07407bed0a9be23f3b719b676c1e2d4bbf82685f049f73
 SHA512:
-  metadata.gz: 13c9f58823377f3297613a43803fbf6474e7b5d8a4225e42688485cdb15b147ca0116b10115dcb643a1fbdb6fadbb34fe34b038cd396e2fdc23ebfc6ea840354
-  data.tar.gz: b7969f401abb258512607c5b635e6e972c58217200c787a8a18ebeaad25cd866388db888185b3b1939dbdd617e0647011919e9557ecd6698aeafcdae6329cbfa
+  metadata.gz: 4bfda0871cefc7b2a0a95ea0d8528ab50111192727f4380f441c922eb5214573a59c9e0c7f39b9c13b26f9ee733607548445477f5b9a79ee7c1028cbbf064db6
+  data.tar.gz: 73002d6de64e98d48dd4f5b0a7ad0439c2bed9b15cdabfe36cffbf026930b0cdeac98da0b748e477362f28a19bdfdb2c0223749dbe6ae353ddc8a4e7b52341b6

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/actions.rb

@@ -9,7 +9,6 @@ module OpenHAB
     # Module to import and streamline access to OpenHAB actions
     #
     module Actions
-      java_import org.openhab.core.library.types.PercentType
       include OpenHAB::Log
 
       OpenHAB::Core::OSGI.services('org.openhab.core.model.script.engine.action.ActionService')&.each do |service|
@@ -83,7 +82,7 @@ module OpenHAB
       # @return [void]
       #
       def say(text, voice: nil, sink: nil, volume: nil)
-        volume = PercentType.new(volume&.to_i) unless volume.is_a?(PercentType) || volume.nil?
+        volume = Types::PercentType.new(volume) unless volume.is_a?(Types::PercentType) || volume.nil?
         Voice.say text, voice, sink, volume
       end
 
@@ -97,7 +96,7 @@ module OpenHAB
       # @return [void]
       #
       def play_sound(filename, sink: nil, volume: nil)
-        volume = PercentType.new(volume&.to_i) unless volume.is_a?(PercentType) || volume.nil?
+        volume = Types::PercentType.new(volume) unless volume.is_a?(Types::PercentType) || volume.nil?
         Audio.playSound sink, filename, volume
       end
     end

data/lib/openhab/dsl/dsl.rb

@@ -1,29 +1,24 @@
 # 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/rules/terse'
 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
@@ -40,6 +35,7 @@ module OpenHAB
       base.send :include, OpenHAB::DSL::Items
       base.send :include, OpenHAB::DSL::Persistence
       base.send :include, OpenHAB::DSL::Rules
+      base.send :include, OpenHAB::DSL::Rules::Terse
       base.send :include, OpenHAB::DSL::States
       base.send :include, OpenHAB::DSL::Things
       base.send :include, OpenHAB::DSL::Timers

data/lib/openhab/dsl/group.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-require 'java'
 require 'singleton'
 
-require 'openhab/core/entity_lookup'
-require 'openhab/dsl/items/group_item'
 require 'openhab/dsl/lazy_array'
 
 module OpenHAB
@@ -35,8 +32,7 @@ module OpenHAB
 
         # explicit conversion to array
         def to_a
-          items = $ir.items.grep(org.openhab.core.items.GroupItem) # rubocop:disable Style/GlobalVars
-          Core::EntityLookup.decorate_items(items)
+          $ir.items.grep(org.openhab.core.items.GroupItem) # rubocop:disable Style/GlobalVars
         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/ensure.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'generic_item'
+
+module OpenHAB
+  module DSL
+    module Items
+      # Functionality to implement +ensure+/+ensure_states+
+      module Ensure
+        # Contains the global +ensure_states+ method
+        module EnsureStates
+          # Global method that takes a block and for the duration of the block
+          # all commands sent will check if the item is in the command's state
+          # before sending the command.
+          #
+          # @example Turn on several switches only if they're not already on
+          #   ensure_states do
+          #     Switch1.on
+          #     Switch2.on
+          #   end
+          def ensure_states
+            old = Thread.current[:ensure_states]
+            Thread.current[:ensure_states] = true
+            yield
+          ensure
+            Thread.current[:ensure_states] = old
+          end
+          module_function :ensure_states
+        end
+
+        # Contains the +ensure+ method mixed into {GenericItem} and {GroupItem::GroupMembers}
+        module Ensurable
+          # Fluent method call that you can chain commands on to, that will
+          # then automatically ensure that the item is not in the command's
+          # state before sending the command.
+          #
+          # @example Turn switch on only if it's not on
+          #   MySwitch.ensure.on
+          # @example Turn on all switches in a group that aren't already on
+          #   MySwitchGroup.members.ensure.on
+          def ensure
+            GenericItemDelegate.new(self)
+          end
+        end
+
+        # Extensions for {Items::GenericItem} to implement {Ensure}'s
+        # functionality
+        module GenericItem
+          include Ensurable
+
+          # If +ensure_states+ is active (by block or chained method), then
+          # check if this item is in the command's state before actually
+          # sending the command
+          def command(command)
+            return super unless Thread.current[:ensure_states]
+            return if command == state
+
+            super
+          end
+          alias << command
+        end
+
+        # "anonymous" class that wraps any method call in +ensure_states+
+        # before forwarding to the wrapped object
+        # @!visibility private
+        class GenericItemDelegate
+          def initialize(item)
+            @item = item
+          end
+
+          # activate +ensure_states+ before forwarding to the wrapped object
+          def method_missing(method, *args, &block)
+            return super unless @item.respond_to?(method)
+
+            ensure_states do
+              @item.__send__(method, *args, &block)
+            end
+          end
+
+          # .
+          def respond_to_missing?(method, include_private = false)
+            @item.respond_to?(method, include_private) || super
+          end
+        end
+      end
+
+      GenericItem.prepend(Ensure::GenericItem)
+      GroupItem::GroupMembers.include(Ensure::Ensurable)
+    end
+  end
+end
+
+Object.include OpenHAB::DSL::Items::Ensure::EnsureStates

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'openhab/dsl/items/metadata'
+require 'openhab/dsl/items/persistence'
+
+require_relative 'item_equality'
+
+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
+        include ItemEquality
+
+        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
+
+        # @!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