openhab-scripting 4.47.0 → 5.0.0

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+require "openhab/core/entity_lookup"
+require "openhab/core/lazy_array"
+require "openhab/dsl/items/builder"
+
+module OpenHAB
+  module Core
+    module Items
+      #
+      # Provides access to all openHAB {Item items}, and acts like an array.
+      #
+      class Registry
+        include LazyArray
+        include Singleton
+
+        # Fetches the named item from the the ItemRegistry
+        # @param [String] name
+        # @return [Item] Item from registry, nil if item missing or requested item is a Group Type
+        def [](name)
+          EntityLookup.lookup_item(name)
+        rescue org.openhab.core.items.ItemNotFoundException
+          nil
+        end
+
+        # Returns true if the given item name exists
+        # @param name [String] Item name to check
+        # @return [true,false] true if the item exists, false otherwise
+        def key?(name)
+          !$ir.getItems(name).empty?
+        end
+        alias_method :include?, :key?
+        # @deprecated
+        alias_method :has_key?, :key?
+
+        # Explicit conversion to array
+        # @return [Array]
+        def to_a
+          $ir.items.map { |item| Proxy.new(item) }
+        end
+
+        #
+        # Enter the Item Builder DSL.
+        #
+        # @param (see Core::Provider.current)
+        # @yield Block executed in the context of a {DSL::Items::Builder}
+        # @return [Object] The return value of the block.
+        #
+        # (see Items::Builder)
+        #
+        def build(preferred_provider = nil, &block)
+          DSL::Items::BaseBuilderDSL.new(preferred_provider).instance_eval_with_dummy_items(&block)
+        end
+
+        #
+        # Remove an item.
+        #
+        # The item must be a managed item (typically created by Ruby or in the UI).
+        #
+        # Any associated metadata or channel links are also removed.
+        #
+        # @param [String, Item] item_name
+        # @param recursive [true, false] Remove the item's members if it's a group
+        # @return [Item, nil] The removed item, if found.
+        def remove(item_name, recursive: false)
+          item_name = item_name.name if item_name.is_a?(Item)
+          provider = Provider.registry.provider_for(item_name)
+          unless provider.is_a?(ManagedProvider)
+            raise "Cannot remove item #{item_name} from non-managed provider #{provider.inspect}"
+          end
+
+          Metadata::Provider.registry.providers.grep(ManagedProvider).each do |managed_provider|
+            managed_provider.remove_item_metadata(item_name)
+          end
+
+          Things::Links::Provider.registry.providers.grep(ManagedProvider).each do |managed_provider|
+            managed_provider.remove_links_for_item(item_name)
+          end
+          provider.remove(item_name, recursive)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "generic_item"
+require_relative "numeric_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.RollershutterItem
+
+      #
+      # A {RollershutterItem} allows the control of roller shutters, i.e.
+      # moving them up, down, stopping or setting it to close to a certain
+      # percentage.
+      #
+      # @!attribute [r] state
+      #   @return [PercentType, UpDownType, nil]
+      #
+      # @example Roll up all Rollershutters in a group
+      #   Shutters.up
+      #
+      # @example Log a warning for all rollershutters that are not up
+      #   Shutters.reject(&:up?).each do |item|
+      #     logger.warn("#{item.name} is not rolled up!")
+      #   end
+      #
+      # @example Set rollershutter to a specified position
+      #   Example_Rollershutter << 40
+      class RollershutterItem < GenericItem
+        include NumericItem
+
+        # @!method up?
+        #   Check if the item state == {UP}
+        #   @return [true,false]
+
+        # @!method down?
+        #   Check if the item state == {DOWN}
+        #   @return [true,false]
+
+        # @!method up
+        #   Send the {UP} command to the item
+        #   @return [RollershutterItem] `self`
+
+        # @!method down
+        #   Send the {DOWN} command to the item
+        #   @return [RollershutterItem] `self`
+
+        # @!method stop
+        #   Send the {STOP} command to the item
+        #   @return [RollershutterItem] `self`
+
+        # @!method move
+        #   Send the {MOVE} command to the item
+        #   @return [RollershutterItem] `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 RollershutterItem = OpenHAB::Core::Items::RollershutterItem

data/lib/openhab/core/items/semantics/enumerable.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+#
+# Additions to Enumerable to allow easily filtering and commanding groups of items.
+#
+# @example Turn on all members of a group
+#   gOutsideLights.members.on
+#
+# @example Turn on all lights that are tagged `NightLights`
+#   items.tagged("NightLights").on
+#
+# @example Close all blinds in the same room when the TV is turned on
+#   rule "Close Blinds" do
+#     changed gTVPower.members, to: ON
+#     triggered do |item|
+#       item.location
+#           .equipments(Semantics::Blinds)
+#           .points(Semantics::OpenLevel)
+#           .down
+#     end
+#   end
+#
+# @example {OpenHAB::DSL::Items::Ensure::Ensurable Ensure} works on Enumerable
+#   gLights.members.ensure.on
+#   # or
+#   gLights.members.ensure << ON
+#
+# @example Send a command to a list of items
+#   [Light1, Light2, Light3].on
+#   # or
+#   [Light1, Light2, Light3].command(ON) # can't use <<, because that's already defined on Array
+#
+# @see OpenHAB::Core::Items::Semantics Semantics
+#
+
+module Enumerable
+  #
+  # @!group Filtering Methods
+  #   Methods to help filter the members of the Enumerable
+  #
+
+  # Returns a new array of items that have at least one of the given tags
+  #
+  # @param tags [String, Module]
+  # @return [Array<Item>]
+  def tagged(*tags)
+    select { |i| i.tagged?(*tags) }
+  end
+
+  # Returns a new array of items that do not have any of the given tags
+  # @param tags [String, Module]
+  # @return [Array<Item>]
+  def not_tagged(*tags)
+    reject { |i| i.tagged?(*tags) }
+  end
+
+  # Returns a new array of items that are a member of at least one of the given groups
+  # @param groups [String, GroupItem]
+  # @return [Array<Item>]
+  def member_of(*groups)
+    select { |i| i.member_of?(*groups) }
+  end
+
+  # Returns a new array of items that are not a member of any of the given groups
+  # @param groups [String, GroupItem]
+  # @return [Array<Item>]
+  def not_member_of(*groups)
+    reject { |i| i.member_of?(*groups) }
+  end
+
+  # Returns the group members of all group elements
+  # @return [Array<Item>]
+  def members
+    grep(OpenHAB::Core::Items::GroupItem).flat_map(&:members).uniq
+  end
+
+  # Returns all non-group members of all group elements, recursively
+  # @return [Array<Item>]
+  def all_members
+    grep(OpenHAB::Core::Items::GroupItem).flat_map(&:all_members).uniq
+  end
+
+  # Returns the groups of all elements
+  # @return [Array<GroupItem>]
+  def groups
+    flat_map(&:groups).uniq
+  end
+
+  # Returns all groups all elements are a part of, recursively
+  # @return [Array<GroupItem>]
+  def all_groups
+    flat_map(&:all_groups).uniq
+  end
+
+  # @!group Items State and Command Methods
+
+  # Send a command to every item in the collection
+  # @return [self, nil] nil when `ensure` is in effect and all the items were already in the same state,
+  #   otherwise self
+  def command(command)
+    self if count { |i| i.command(command) }.positive?
+  end
+
+  # Update the state of every item in the collection
+  # @return [self, nil] nil when `ensure` is in effect and all the items were already in the same state,
+  #   otherwise self
+  def update(state)
+    self if count { |i| i.update(state) }.positive?
+  end
+
+  # @!method refresh
+  #   Send the {REFRESH} command to every item in the collection
+  #   @return [self]
+
+  # @!method on
+  #   Send the {ON} command to every item in the collection
+  #   @return [self]
+
+  # @!method off
+  #   Send the {OFF} command to every item in the collection
+  #   @return [self]
+
+  # @!method up
+  #   Send the {UP} command to every item in the collection
+  #   @return [self]
+
+  # @!method down
+  #   Send the {DOWN} command to every item in the collection
+  #   @return [self]
+
+  # @!method stop
+  #   Send the {STOP} command to every item in the collection
+  #   @return [self]
+
+  # @!method move
+  #   Send the {MOVE} command to every item in the collection
+  #   @return [self]
+
+  # @!method increase
+  #   Send the {INCREASE} command to every item in the collection
+  #   @return [self]
+
+  # @!method decrease
+  #   Send the {DECREASE} command to every item in the collection
+  #   @return [self]
+
+  # @!method play
+  #   Send the {PLAY} command to every item in the collection
+  #   @return [self]
+
+  # @!method pause
+  #   Send the {PAUSE} command to every item in the collection
+  #   @return [self]
+
+  # @!method rewind
+  #   Send the {REWIND} command to every item in the collection
+  #   @return [self]
+
+  # @!method fast_forward
+  #   Send the {FASTFORWARD} command to every item in the collection
+  #   @return [self]
+
+  # @!method next
+  #   Send the {NEXT} command to every item in the collection
+  #   @return [self]
+
+  # @!method previous
+  #   Send the {PREVIOUS} command to every item in the collection
+  #   @return [self]
+
+  # @!visibility private
+  # can't use `include`, because Enumerable has already been included
+  # in other classes
+  def ensure
+    OpenHAB::DSL::Items::Ensure::ItemDelegate.new(self)
+  end
+end