openhab-scripting 4.47.0 → 5.0.1

data/lib/openhab/core/events.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    # Contains objects sent to event handlers containing context around the
+    # triggered event.
+    module Events
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      class << self
+        # @!visibility private
+        def prepend_accepted_data_types
+          concrete_item_classes.each do |k|
+            k.prepend(AcceptedDataTypes)
+          end
+        end
+      end
+
+      module AcceptedDataTypes
+        # @see Item#accepted_command_types
+        def accepted_command_types
+          super.map { |k| k.is_a?(java.lang.Class) ? k.ruby_class : k }
+        end
+
+        # @see Item#accepted_data_types
+        def accepted_data_types
+          super.map { |k| k.is_a?(java.lang.Class) ? k.ruby_class : k }
+        end
+      end
+      private_constant :AcceptedDataTypes
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "dimmer_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.ColorItem
+
+      #
+      # {ColorItem} represents a color values, e.g. for LED lights.
+      #
+      # Note that it inherits from {DimmerItem}, so you can call {#on}, {#off},
+      # {#on?}, {#off?}, etc. on it. Its state type is an {HSBType},
+      # which is stored as Hue, Saturation, and Brightness, but has easy
+      # helpers for working with RGB values of various forms.
+      #
+      # @example Sending commands
+      #   HueBulb << "#ff0000" # send 'red' as a command
+      #   HueBulb.on
+      #   HueBulb.dim
+      #
+      # @example Inspect state
+      #   HueBulb.on? # => true
+      #   HueBulb.state.red # => 100%
+      #   HueBulb.state.hue # => 0 °
+      #   HueBulb.state.brightness # => 100%
+      #   HueBulb.state.to_rgb # => [100%, 0%, 0%]
+      #   HueBulb.state.rgb # => 16711680
+      #   HueBulb.state.to_hex # => "0xff0000"
+      #   HueBulb.state.on? # => true
+      #   HueBulb.state.red.to_byte # => 255
+      #   HueBulb.state.blue.to_byte # => 0
+      #
+      # @!attribute [r] state
+      #   @return [HSBType, nil]
+      #
+      class ColorItem < DimmerItem
+        # Make sure to do the String => HSBType conversion in Ruby,
+        # where we add support for hex
+        # @!visibility private
+        def format_type(type)
+          return Types::HSBType.new(type) if type.respond_to?(:to_str)
+
+          super
+        end
+      end
+    end
+  end
+end
+
+# @!parse ColorItem = OpenHAB::Core::Items::ColorItem

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "generic_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.ContactItem
+
+      #
+      #  A {ContactItem} can be used for sensors that return an "open" or
+      # "closed" as a state.
+      #
+      # This is useful for doors, windows, etc.
+      #
+      # @!attribute [r] state
+      #   @return [OpenClosedType, nil]
+      #
+      # @example
+      #   rule 'Log state of all doors on system startup' do
+      #     on_load
+      #     run do
+      #       Doors.each do |door|
+      #         case door.state
+      #         when OPEN then logger.info("#{door.name} is Open")
+      #         when CLOSED then logger.info("#{door.name} is Open")
+      #         else logger.info("#{door.name} is not initialized")
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      class ContactItem < GenericItem
+        # @!method open?
+        #   Check if the item state == {OPEN}
+        #   @return [true,false]
+        #
+        # @example Log open contacts
+        #   Contacts.select(&:open?).each { |contact| logger.info("Contact #{contact.name} is open")}
+
+        # @!method closed?
+        #   Check if the item state == {CLOSED}
+        #   @return [true,false]
+        #
+        # @example Log closed contacts
+        #   Contacts.select(&:closed?).each { |contact| logger.info("Contact #{contact.name} is closed")}
+      end
+    end
+  end
+end
+
+# @!parse ContactItem = OpenHAB::Core::Items::ContactItem

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "generic_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.DateTimeItem
+
+      #
+      # A DateTimeItem stores a timestamp including a valid time zone.
+      #
+      # @!attribute [r] state
+      #   @return [DateTimeType, nil]
+      #
+      # @example DateTime items can be updated and commanded with Ruby Time objects or Java ZonedDateTime objects
+      #   Example_DateTimeItem << Time.now
+      #   Example_DateTimeItem << ZonedDateTime.now
+      #
+      # @example Math operations (+ and -) are available to make calculations with time in a few different ways
+      #   Example_DateTimeItem.state + 600 # Number of seconds
+      #   Example_DateTimeItem.state - '01:15' # Subtracts 1h 15 min
+      #   Example_DateTimeItem.state + 2.hours # Use the helper library's duration methods
+      #
+      #   Example_DateTimeItem.state - Example_DateTimeItem2.state # Calculate the time difference, in seconds
+      #   Example_DateTimeItem.state - '2021-01-01 15:40' # Calculates time difference
+      #
+      # @example Comparisons between different time objects can be performed
+      #   Example_DateTimeItem.state == Example_DateTimeItem2.state # Equality, works across time zones
+      #   Example_DateTimeItem.state > Date.parse('2021-01-31') # After midnight jan 31st 2021
+      #   Example_DateTimeItem.state <= Time.now # Before or equal to now
+      #   Example_DateTimeItem.state < LocalTime::NOON # Before noon
+      #
+      # @example LocalTime ranges created also work
+      #   case Example_DateTimeItem.state
+      #   when LocalTime.parse('00:00')...LocalTime.parse('08:00')
+      #     logger.info('Example_DateTimeItem is between 00:00..08:00')
+      #   when LocalTime.parse('08:00')...LocalTime.parse('16:00')
+      #     logger.info('Example_DateTimeItem is between 08:00..16:00')
+      #   when LocalTime.parse('16:00')..LocalTime.parse'23:59')
+      #     logger.info('Example_DateTimeItem is between 16:00...23:59')
+      #   end
+      #
+      class DateTimeItem < GenericItem
+        # Time types need formatted as ISO8601
+        # @!visibility private
+        def format_type(command)
+          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)
+
+          super
+        end
+      end
+    end
+  end
+end
+
+# @!parse DateTimeItem = OpenHAB::Core::Items::DateTimeItem

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "numeric_item"
+require_relative "switch_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.DimmerItem
+
+      #
+      # A DimmerItem can be used as a switch (ON/OFF), but it also accepts
+      # percent values to reflect the dimmed state.
+      #
+      # @!attribute [r] state
+      #   @return [PercentType, nil]
+      #
+      # @example
+      #   DimmerOne << DimmerOne.state - 5
+      #   DimmerOne << 100 - DimmerOne.state
+      #
+      # @example Turn on all dimmers in group
+      #   Dimmers.members.each(&:on)
+      #
+      # @example Turn off all dimmers in group
+      #    Dimmers.members.each(&:off)
+      #
+      # @example Turn on switches that are off
+      #   Dimmers.select(&:off?).each(&:on)
+      #
+      # @example Turn off switches that are on
+      #   Dimmers.select(&:on?).each(&:off)
+      #
+      # @example Dimmers can be selected in an enumerable with grep.
+      #   items.grep(DimmerItem)
+      #        .each { |dimmer| logger.info("#{dimmer.name} is a Dimmer") }
+      #
+      # @example Dimmers can also be used in case statements with ranges.
+      #   items.grep(DimmerItem)
+      #        .each do |dimmer|
+      #     case dimmer.state
+      #     when (0..50)
+      #       logger.info("#{dimmer.name} is less than 50%")
+      #     when (51..100)
+      #       logger.info("#{dimmer.name} is greater than 50%")
+      #     end
+      #   end
+      #
+      # @example
+      #   rule 'Dim a switch on system startup over 100 seconds' do
+      #     on_load
+      #     100.times do
+      #       run { DimmerSwitch.dim }
+      #       delay 1.second
+      #     end
+      #   end
+      #
+      # @example
+      #   rule 'Dim a switch on system startup by 5, pausing every second' do
+      #     on_load
+      #     100.step(-5, 0) do |level|
+      #       run { DimmerSwitch << level }
+      #       delay 1.second
+      #     end
+      #   end
+      #
+      # @example
+      #   rule 'Turn off any dimmers curently on at midnight' do
+      #     every :day
+      #     run do
+      #       items.grep(DimmerItem)
+      #            .select(&:on?)
+      #            .each(&:off)
+      #       end
+      #   end
+      #
+      # @example
+      #   rule 'Turn off any dimmers set to less than 50 at midnight' do
+      #     every :day
+      #     run do
+      #       items.grep(DimmerItem)
+      #            .select { |i| (1...50).cover?(i.state) }
+      #            .each(&:off)
+      #       end
+      #   end
+      #
+      class DimmerItem < SwitchItem
+        include NumericItem
+
+        #
+        # Dim the dimmer
+        #
+        # @param [Integer] amount to dim by
+        #  If 1 is the amount, the DECREASE command is sent, otherwise the
+        #  current state - amount is sent as a command.
+        #
+        # @return [Integer] level target for dimmer
+        #
+        # @example
+        #   DimmerOne.dim
+        #   DimmerOne.dim(2)
+        #
+        def dim(amount = 1)
+          target = [state&.-(amount), 0].compact.max
+          command(target)
+          target
+        end
+
+        #
+        # Brighten the dimmer
+        #
+        # @param [Integer] amount to brighten by
+        #   If 1 is the amount, the INCREASE command is sent, otherwise the
+        # current state + amount is sent as a command.
+        #
+        # @return [Integer] level target for dimmer
+        #
+        # @example
+        #   DimmerOne.brighten
+        #   DimmerOne.brighten(2)
+        #
+        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`
+
+        # raw numbers translate directly to PercentType, not a DecimalType
+        # @!visibility private
+        def format_type(command)
+          return Types::PercentType.new(command) if command.is_a?(Numeric)
+
+          super
+        end
+      end
+    end
+  end
+end
+
+# @!parse DimmerItem = OpenHAB::Core::Items::DimmerItem

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

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.items.GenericItem
+
+      #
+      # The abstract base class for all items.
+      #
+      # @see org.openhab.core.items.GenericItem
+      #
+      class GenericItem
+        # @!parse include Item
+
+        # 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
+
+          # @!visibility private
+          #
+          # Override to support {Proxy}
+          #
+          # Item.=== isn't actually included (on the Ruby side) into
+          # {GenericItem}
+          #
+          def ===(other)
+            other.is_a?(self)
+          end
+        end
+        # rubocop:enable Naming/MethodName
+
+        # @!attribute [r] name
+        #   The item's name.
+        #   @return [String]
+
+        # @!attribute [r] label
+        #   The item's descriptive label.
+        #   @return [String, nil]
+
+        # @!visibility private
+        alias_method :hash, :hash_code
+
+        # @!attribute [r] raw_state
+        #
+        # Get the raw item state.
+        #
+        # The state of the item, including possibly {NULL} or {UNDEF}
+        #
+        # @return [State]
+        #
+        alias_method :raw_state, :state
+
+        #
+        # Check if the item has a state (not {UNDEF} or {NULL})
+        #
+        # @return [true, false]
+        #
+        def state?
+          !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]
+        #   openHAB item state if state is not {UNDEF} or {NULL}, nil otherwise.
+        #   This makes it easy to use with the
+        #   [Ruby safe navigation operator `&.`](https://docs.ruby-lang.org/en/master/syntax/calling_methods_rdoc.html#label-Safe+Navigation+Operator)
+        #   Use {#undef?} or {#null?} to check for those states.
+        #
+        def state
+          raw_state if state?
+        end
+
+        # @!method null?
+        #   Check if the item state == {NULL}
+        #   @return [true,false]
+
+        # @!method undef?
+        #   Check if the item state == {UNDEF}
+        #   @return [true,false]
+
+        #
+        # Send a command to this item
+        #
+        # When this method is chained after the {OpenHAB::DSL::Items::Ensure::Ensurable#ensure ensure}
+        # method, or issued inside an {OpenHAB::DSL.ensure_states ensure_states} block,
+        # the command will only be sent if the item is not already in the same state.
+        #
+        # @param [Command] command command to send to the item
+        # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
+        #   otherwise the item.
+        #
+        # @see DSL::Items::TimedCommand#command Timed Command
+        # @see OpenHAB::DSL.ensure_states ensure_states
+        # @see DSL::Items::Ensure::Ensurable#ensure ensure
+        #
+        def command(command)
+          command = format_command(command)
+          logger.trace "Sending Command #{command} to #{name}"
+          $events.send_command(self, command)
+          Proxy.new(self)
+        end
+
+        # not an alias to allow easier stubbing and overriding
+        def <<(command)
+          command(command)
+        end
+
+        # @!parse alias_method :<<, :command
+
+        # @!method refresh
+        #   Send the {REFRESH} command to the item
+        #   @return [Item] `self`
+
+        #
+        # Send an update to this item
+        #
+        # @param [State] state
+        # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
+        #   otherwise the item.
+        #
+        def update(state)
+          state = format_update(state)
+          logger.trace "Sending Update #{state} to #{name}"
+          $events.post_update(self, state)
+          Proxy.new(self)
+        end
+
+        # @!visibility private
+        def format_command(command)
+          command = format_type(command)
+          return command if command.is_a?(Types::Command)
+
+          command = command.to_s
+          org.openhab.core.types.TypeParser.parse_command(getAcceptedCommandTypes, command) || command
+        end
+
+        # @!visibility private
+        def format_update(state)
+          state = format_type(state)
+          return state if state.is_a?(Types::State)
+
+          state = state.to_s
+          org.openhab.core.types.TypeParser.parse_state(getAcceptedDataTypes, state) || StringType.new(state)
+        end
+
+        # formats a {Types::Type} to send to the event bus
+        # @!visibility private
+        def format_type(type)
+          # actual Type types can be sent directly without conversion
+          # 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
+end
+
+# @!parse GenericItem = OpenHAB::Core::Items::GenericItem