openhab-scripting 4.46.2 → 5.0.0

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "openhab/core/lazy_array"
+
+require_relative "generic_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.items.GroupItem
+
+      #
+      # A group behaves like a regular item, but also has {#members} which are
+      # nested items that can be enumerated.
+      #
+      # If the group has a particular type, the methods from that type are
+      # directly available.
+      #
+      #
+      # The examples all assume the following items exist.
+      # ```xtend
+      # Group House
+      # // Location perspective
+      # Group GroundFloor  (House)
+      # Group Livingroom   (GroundFloor)
+      # // Functional perspective
+      # Group Sensors      (House)
+      # Group Temperatures (Sensors)
+      #
+      # Number Livingroom_Temperature "Living Room temperature" (Livingroom, Temperatures)
+      # Number Bedroom_Temp "Bedroom temperature" (GroundFloor, Temperatures)
+      # Number Den_Temp "Den temperature" (GroundFloor, Temperatures)
+      # ```
+      #
+      # @!attribute [r] base_item
+      #   @return [Item, nil] A typed item if the group has a particular type.
+      #
+      # @example Operate on items in a group using enumerable methods
+      #   logger.info("Total Temperatures: #{Temperatures.members.count}")
+      #   # Total Temperatures: 3
+      #   logger.info("Temperatures: #{House.members.map(&:name).sort.join(', ')}")
+      #   # Temperatures: GroundFloor, Sensors
+      #
+      # @example Access to the methods and attributes like any item
+      #   logger.info("Group: #{Temperatures.name}" # Group: Temperatures'
+      #
+      # @example Operates on items in nested groups using enumerable methods
+      #   logger.info("House Count: #{House.all_members.count}")
+      #   # House Count: 7
+      #   logger.info("Items: #{House.all_members.grep_v(GroupItem).map(&:label).sort.join(', ')}")
+      #   # Items: Bedroom temperature, Den temperature, Living Room temperature
+      #
+      # @example Iterate through the direct members of the group
+      #   Temperatures.members.each do |item|
+      #     logger.info("#{item.label} is: #{item.state}")
+      #   end
+      #   # Living Room temperature is 22
+      #   # Bedroom temperature is 21
+      #   # Den temperature is 19
+      #
+      # @example
+      #   rule 'Turn off any switch that changes' do
+      #     changed Switches.members
+      #     triggered(&:off)
+      #   end
+      #
+      # @example Built in {Enumerable} functions can be applied to groups.
+      #   logger.info("Max is #{Temperatures.members.map(&:state).max}")
+      #   logger.info("Min is #{Temperatures.members.map(&:state).min}")
+      #
+      class GroupItem < GenericItem
+        #
+        # Class for indicating to triggers that a group trigger should be used
+        #
+        class Members
+          include LazyArray
+
+          # @return [GroupItem]
+          attr_reader :group
+
+          # @!visibility private
+          def initialize(group_item)
+            @group = group_item
+          end
+
+          # Explicit conversion to Array
+          #
+          # @return [Array]
+          def to_a
+            group.get_members.map { |i| Proxy.new(i) }
+          end
+
+          # Name of the group
+          #
+          # @return [String]
+          def name
+            group.name
+          end
+
+          # @return [String]
+          def inspect
+            r = "#<OpenHAB::Core::Items::GroupItems::Members #{name}"
+            r += " #{map(&:name).inspect}>" unless @group.__getobj__.nil?
+            "#{r}>"
+          end
+          alias_method :to_s, :inspect
+        end
+
+        # Override because we want to send them to the base item if possible
+        %i[command update].each do |method|
+          define_method(method) do |command|
+            return base_item.__send__(method, command) if base_item
+
+            super(command)
+          end
+        end
+
+        #
+        # @!attribute [r] members
+        # @return [Members] Get an Array-like object representing the members of the group
+        #
+        # @see Enumerable
+        #
+        def members
+          Members.new(Proxy.new(self))
+        end
+
+        #
+        # @!attribute [r] all_members
+        # @return [Array] Get all non-group members of the group recursively.
+        #
+        # @see Enumerable
+        #
+        def all_members
+          getAllMembers.map { |m| Proxy.new(m) }
+        end
+
+        # give the base item type a chance to format commands
+        # @!visibility private
+        def format_type(command)
+          return super unless base_item
+
+          base_item.format_type(command)
+        end
+
+        private
+
+        # Add base type and function details
+        def type_details
+          r = ""
+          r += ":#{base_item.type}#{base_item.__send__(:type_details)}" if base_item
+          if function && (fn = function.class.java_class.simple_name.upcase) != "EQUALITY"
+            r += ":#{fn}"
+            r += "(#{function.parameters.map(&:inspect).join(",")})" unless function.parameters.empty?
+          end
+          r
+        end
+
+        # Delegate missing methods to {base_item} if possible
+        def method_missing(method, *args, &block)
+          return base_item.__send__(method, *args, &block) if base_item&.respond_to?(method) # rubocop:disable Lint/RedundantSafeNavigation nil responds to :to_a
+
+          super
+        end
+
+        def respond_to_missing?(method, include_private = false)
+          return true if base_item&.respond_to?(method) # rubocop:disable Lint/RedundantSafeNavigation
+
+          super
+        end
+      end
+    end
+  end
+end
+
+# @!parse GroupItem = OpenHAB::Core::Items::GroupItem

data/lib/openhab/{dsl → core}/items/image_item.rb

@@ -1,17 +1,39 @@
 # frozen_string_literal: true
 
-require 'base64'
-require 'pathname'
-require 'net/http'
-require 'marcel'
+require "base64"
+require "pathname"
+require "net/http"
+require "marcel"
+
+require_relative "generic_item"
 
 module OpenHAB
-  module DSL
+  module Core
     module Items
       java_import org.openhab.core.library.items.ImageItem
 
-      # Adds methods to core OpenHAB ImageItem type to make it more natural in
-      # Ruby
+      #
+      # An {ImageItem} holds the binary image data as its state.
+      #
+      # @!attribute [r] state
+      #   @return [RawType, nil]
+      #
+      # @example Update from a base 64 encode image string
+      #   Image.update("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEUAAACnej3aAAAAAXRSTlMAQObYZgAAAApJREFUCNdjYAAAAAIAAeIhvDMAAAAASUVORK5CYII=")
+      #
+      # @example Update from image bytes and mime type
+      #   Image.update_from_bytes(File.binread(File.join(Dir.tmpdir,'1x1.png')), mime_type: 'image/png')
+      #
+      # @example Update from URL
+      #   Image.update_from_url('https://raw.githubusercontent.com/boc-tothefuture/openhab-jruby/main/features/assets/1x1.png')
+      #
+      # @example Update from File
+      #   Image.update_from_file('/tmp/1x1.png')
+      #
+      # @example Log image data
+      #   logger.info("Mime type: #{Image.state.mime_type}")
+      #   logger.info("Number of bytes: #{Image.state.bytes.length}")
+      #
       class ImageItem < GenericItem
         #
         # Update image from file
@@ -35,7 +57,7 @@ module OpenHAB
         def update_from_url(uri)
           logger.trace("Downloading image from #{uri}")
           response = Net::HTTP.get_response(URI(uri))
-          mime_type = response['content-type']
+          mime_type = response["content-type"]
           bytes = response.body
           mime_type ||= detect_mime_from_bytes(bytes: bytes)
           update_from_bytes(bytes, mime_type: mime_type)
@@ -54,33 +76,15 @@ module OpenHAB
           update(base_64_image)
         end
 
-        #
-        # Get the mime type for the image item
-        #
-        # @return [String] mime type for image, e.g. image/png
-        #
-        def mime_type
-          state&.mime_type
-        end
-
-        #
-        # Get the bytes of the image
-        #
-        # @return [Array] Bytes that comprise the image
-        #
-        def bytes
-          state&.get_bytes
-        end
-
         private
 
         #
-        # Encode image information in the format required by OpenHAB
+        # Encode image information in the format required by openHAB
         #
         # @param [String] mime_type for image
         # @param [Object] bytes image data
         #
-        # @return [String] OpenHAB image format with image data Base64 encoded
+        # @return [String] openHAB image format with image data Base64 encoded
         #
         def encode_image(mime_type:, bytes:)
           "data:#{mime_type};base64,#{Base64.strict_encode64(bytes)}"
@@ -94,10 +98,12 @@ module OpenHAB
         # @return [String] mime type if it can be detected, nil otherwise
         #
         def detect_mime_from_bytes(bytes:)
-          logger.trace('Detecting mime type from file image contents')
+          logger.trace("Detecting mime type from file image contents")
           Marcel::MimeType.for(bytes)
         end
       end
     end
   end
 end
+
+# @!parse ImageItem = OpenHAB::Core::Items::ImageItem

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

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      # @interface
+      java_import org.openhab.core.items.Item
+
+      #
+      # The core features of an openHAB item.
+      #
+      module Item
+        class << self
+          # @!visibility private
+          #
+          # Override to support {Proxy}
+          #
+          def ===(other)
+            other.is_a?(self)
+          end
+        end
+
+        # @!attribute [r] name
+        #   The item's name.
+        #   @return [String]
+
+        # @!attribute [r] accepted_command_types
+        #   @return [Array<Class>] An array of {Command}s that can be sent as commands to this item
+
+        # @!attribute [r] accepted_data_types
+        #   @return [Array<Class>] An array of {State}s that can be sent as commands to this item
+
+        #
+        # The item's {GenericItem#label label} if one is defined, otherwise its {#name}.
+        #
+        # @return [String]
+        #
+        def to_s
+          label || name
+        end
+
+        #
+        # @!attribute [r] groups
+        #
+        # Returns all groups that this item is part of
+        #
+        # @return [Array<GroupItem>] All groups that this item is part of
+        #
+        def groups
+          group_names.map { |name| EntityLookup.lookup_item(name) }.compact
+        end
+
+        #
+        # Checks if this item is a member of at least one of the given groups.
+        #
+        # @param groups [String, GroupItem] the group to check membership in
+        # @return [true, false]
+        #
+        # @example
+        #   event.item.member_of?(gFullOn)
+        #
+        def member_of?(*groups)
+          groups.map! do |group|
+            group.is_a?(GroupItem) ? group.name : group
+          end
+          !(group_names & groups).empty?
+        end
+
+        #
+        # @!attribute [r] all_groups
+        #
+        # Returns all groups that this item is a part of, as well as those groups' groups, recursively
+        #
+        # @return [Array<GroupItem>]
+        #
+        def all_groups
+          result = []
+          new_groups = Set.new(groups)
+
+          until new_groups.empty?
+            result.concat(new_groups.to_a)
+            new_groups.replace(new_groups.flat_map(&:groups))
+            # remove any groups we already have in the result to avoid loops
+            new_groups.subtract(result)
+          end
+
+          result
+        end
+
+        # rubocop:disable Layout/LineLength
+
+        # @!attribute [r] metadata
+        # @return [Metadata::NamespaceHash]
+        #
+        # Access to the item's metadata.
+        #
+        # Both the return value of this method as well as the individual
+        # namespaces can be treated as Hashes.
+        #
+        # Examples assume the following items:
+        #
+        # ```xtend
+        # Switch Item1 { namespace1="value" [ config1="foo", config2="bar" ] }
+        # String StringItem1
+        # ```
+        #
+        # @example Check namespace's existence
+        #   Item1.metadata["namespace"].nil?
+        #   Item1.metadata.key?("namespace")
+        #
+        # @example Access item's metadata value
+        #   Item1.metadata["namespace1"].value
+        #
+        # @example Access namespace1's configuration
+        #   Item1.metadata["namespace1"]["config1"]
+        #
+        # @example Safely search for the specified value - no errors are raised, only nil returned if a key in the chain doesn't exist
+        #   Item1.metadata.dig("namespace1", "config1") # => "foo"
+        #   Item1.metadata.dig("namespace2", "config1") # => nil
+        #
+        # @example Set item's metadata value, preserving its config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"].value = "new value"
+        #   # Item1's metadata after: {"namespace1"=>["new value", {"config1"=>"foo", "config2"=>"bar"]}}
+        #
+        # @example Set item's metadata config, preserving its value
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"].replace({ "scooby"=>"doo" })
+        #   # Item1's metadata after: {"namespace1"=>["value", {scooby="doo"}]}
+        #
+        # @example Set a namespace to a new value and config in one line
+        #   # Item1's metadata before: {"namespace1"=>"value", {"config1"=>"foo", "config2"=>"bar"}}
+        #   Item1.metadata["namespace1"] = "new value", { "scooby"=>"doo" }
+        #   # Item1's metadata after: {"namespace1"=>["new value", {scooby="doo"}]}
+        #
+        # @example Set item's metadata value and clear its previous config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"] = "new value"
+        #   # Item1's metadata after: {"namespace1"=>"value" }
+        #
+        # @example Set item's metadata config, set its value to nil, and wiping out previous config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"] = { "newconfig"=>"value" }
+        #   # Item1's metadata after: {"namespace1"=>{"config1"=>"foo", "config2"=>"bar"}}
+        #
+        # @example Update namespace1's specific configuration, preserving its value and other config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"]["config1"] = "doo"
+        #   # Item1's metadata will be: {"namespace1"=>["value", {"config1"=>"doo", "config2"=>"bar"}]}
+        #
+        # @example Add a new configuration to namespace1
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"]["config3"] = "boo"
+        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar", config3="boo"}]}
+        #
+        # @example Delete a config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"].delete("config2")
+        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo"}]}
+        #
+        # @example Add a namespace and set it to a value
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace2"] = "qx"
+        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace2"=>"qx"}
+        #
+        # @example Add a namespace and set it to a value and config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace2"] = "qx", { "config1"=>"doo" }
+        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace2"=>["qx", {"config1"=>"doo"}]}
+        #
+        # @example Enumerate Item1's namespaces
+        #   Item1.metadata.each { |namespace, metadata| logger.info("Item1's namespace: #{namespace}=#{metadata}") }
+        #
+        # @example Add metadata from a hash
+        #   Item1.metadata.merge!({"namespace1"=>{"foo", {"config1"=>"baz"} ], "namespace2"=>{"qux", {"config"=>"quu"} ]})
+        #
+        # @example Merge Item2's metadata into Item1's metadata
+        #   Item1.metadata.merge!(Item2.metadata)
+        #
+        # @example Delete a namespace
+        #   Item1.metadata.delete("namespace1")
+        #
+        # @example Delete all metadata of the item
+        #   Item1.metadata.clear
+        #
+        # @example Does this item have any metadata?
+        #   Item1.metadata.any?
+        #
+        # @example Store another item's state
+        #   StringItem1.update "TEST"
+        #   Item1.metadata["other_state"] = StringItem1.state
+        #
+        # @example Store event's state
+        #   rule "save event state" do
+        #     changed StringItem1
+        #     run { |event| Item1.metadata["last_event"] = event.was }
+        #   end
+        #
+        # @example If the namespace already exists: Update the value of a namespace but preserve its config; otherwise create a new namespace with the given value and nil config.
+        #   Item1.metadata["namespace"] = "value", Item1.metadata["namespace"]
+        #
+        # @example Copy another namespace
+        #   # Item1's metadata before: {"namespace2"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace"] = Item1.metadata["namespace2"]
+        #   # Item1's metadata after: {"namespace2"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #
+        def metadata
+          @metadata ||= Metadata::NamespaceHash.new(name)
+        end
+        # rubocop:enable Layout/LineLength
+
+        #
+        # Checks if this item has at least one of the given tags.
+        #
+        # @param tags [String, Module] the tag(s) to check
+        # @return [true, false]
+        #
+        # @example
+        #   event.item.tagged?("Setpoint")
+        #
+        def tagged?(*tags)
+          tags.map! do |tag|
+            tag.is_a?(Module) ? tag.simple_name : tag
+          end
+          !(self.tags.to_a & tags).empty?
+        end
+
+        # Return the item's thing if this item is linked with a thing. If an item is linked to more than one thing,
+        # this method only returns the first thing.
+        #
+        # @return [Thing] The thing associated with this item or nil
+        def thing
+          all_linked_things.first
+        end
+        alias_method :linked_thing, :thing
+
+        # Returns all of the item's linked things.
+        #
+        # @return [Array<Thing>] An array of things or an empty array
+        def things
+          registry = Things::Links::Provider.registry
+          channels = registry.get_bound_channels(name).to_a
+          channels.map(&:thing_uid).uniq.map { |tuid| EntityLookup.lookup_thing(tuid) }.compact
+        end
+        alias_method :all_linked_things, :things
+
+        # @return [String]
+        def inspect
+          s = "#<OpenHAB::Core::Items::#{type}Item#{type_details} #{name} #{label.inspect} state=#{raw_state.inspect}"
+          s += " category=#{category.inspect}" if category
+          s += " tags=#{tags.to_a.inspect}" unless tags.empty?
+          s += " groups=#{group_names}" unless group_names.empty?
+          meta = metadata.to_h
+          s += " metadata=#{meta.inspect}" unless meta.empty?
+          "#{s}>"
+        end
+
+        # @return [org.openhab.core.common.registry.Provider]
+        def provider
+          Provider.registry.provider_for(self)
+        end
+
+        private
+
+        # Allows sub-classes to append additional details to the type in an inspect string
+        # @return [String]
+        def type_details; end
+      end
+    end
+  end
+end
+
+# @!parse Item = OpenHAB::Core::Items::Item

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "generic_item"
+
+module OpenHAB
+  module Core
+    module Items
+      java_import org.openhab.core.library.items.LocationItem
+
+      #
+      # A LocationItem can be used to store GPS related information, addresses
+      # etc.
+      #
+      # This is useful for location awareness related functions
+      #
+      # @!attribute [r] state
+      #   @return [PointType, nil]
+      #
+      # @example Send point commands
+      #   Location << '30,20'   # latitude of 30, longitude of 20
+      #   Location << '30,20,80' # latitude of 30, longitude of 20, altitude of 80
+      #   Location << PointType.new('40,20')
+      #
+      # @example Determine the distance between two locations
+      #   logger.info "Distance from Location 1 to Location 2: #{Location1.state - Location2.state}"
+      #   logger.info "Distance from Location 1 to Location 2: #{Location1.state - PointType.new('40,20')}"
+      #
+      class LocationItem < GenericItem
+      end
+    end
+  end
+end
+
+# @!parse LocationItem = OpenHAB::Core::Items::LocationItem