class Net::LDAP::Entry
Objects of this class represent individual entries in an LDAP directory. User code generally does not instantiate this class. Net::LDAP#search
provides objects of this class to user code, either as block parameters or as return values.
In LDAP-land, an “entry” is a collection of attributes that are uniquely and globally identified by a DN (“Distinguished Name”). Attributes are identified by short, descriptive words or phrases. Although a directory is free to implement any attribute name, most of them follow rigorous standards so that the range of commonly-encountered attribute names is not large.
An attribute name is case-insensitive. Most directories also restrict the range of characters allowed in attribute names. To simplify handling attribute names, Net::LDAP::Entry
internally converts them to a standard format. Therefore, the methods which take attribute names can take Strings or Symbols, and work correctly regardless of case or capitalization.
An attribute consists of zero or more data items called values. An entry is the combination of a unique DN, a set of attribute names, and a (possibly-empty) array of values for each attribute.
Class Net::LDAP::Entry
provides convenience methods for dealing with LDAP entries. In addition to the methods documented below, you may access individual attributes of an entry simply by giving the attribute name as the name of a method call. For example:
ldap.search( ... ) do |entry| puts "Common name: #{entry.cn}" puts "Email addresses:" entry.mail.each {|ma| puts ma} end
If you use this technique to access an attribute that is not present in a particular Entry
object, a NoMethodError exception will be raised.
Public Class Methods
Canonicalizes an LDAP attribute name as a Symbol. The name is lowercased and, if present, a trailing equals sign is removed.
# File lib/net/ldap/entry.rb, line 84 def attribute_name(name) name = name.to_s.downcase name = name[0..-2] if name[-1] == ?= name.to_sym end
Converts a single LDIF entry string into an Entry
object. Useful for Marshal serialization. If a string with multiple LDIF entries is provided, an exception will be raised.
# File lib/net/ldap/entry.rb, line 68 def from_single_ldif_string(ldif) ds = Net::LDAP::Dataset.read_ldif(::StringIO.new(ldif)) return nil if ds.empty? raise Net::LDAP::EntryOverflowError, "Too many LDIF entries" unless ds.size == 1 entry = ds.to_entries.first return nil if entry.dn.nil? entry end
Public Instance Methods
# File lib/net/ldap/entry.rb, line 197 def ==(other) other.instance_of?(self.class) && @myhash == other.to_h end
Reads the array of values for the provided attribute. The attribute name is canonicalized prior to reading. Returns an empty array if the attribute does not exist.
# File lib/net/ldap/entry.rb, line 110 def [](name) name = self.class.attribute_name(name) @myhash[name] || [] end
Sets or replaces the array of values for the provided attribute. The attribute name is canonicalized prior to assignment.
When an attribute is set using this, that attribute is now made accessible through methods as well.
entry = Net::LDAP::Entry.new("dc=com") entry.foo # => NoMethodError entry["foo"] = 12345 # => [12345] entry.foo # => [12345]
# File lib/net/ldap/entry.rb, line 102 def []=(name, value) @myhash[self.class.attribute_name(name)] = Kernel::Array(value) end
Returns an array of the attribute names present in the Entry
.
# File lib/net/ldap/entry.rb, line 131 def attribute_names @myhash.keys end
Returns the first distinguished name (dn) of the Entry
as a String.
# File lib/net/ldap/entry.rb, line 125 def dn self[:dn].first.to_s end
Accesses each of the attributes present in the Entry
.
Calls a user-supplied block with each attribute in turn, passing two arguments to the block: a Symbol giving the name of the attribute, and a (possibly empty) Array of data values.
# File lib/net/ldap/entry.rb, line 148 def each # :yields: attribute-name, data-values-array return unless block_given? attribute_names.each do|a| attr_name, values = a, self[a] yield attr_name, values end end
Read the first value for the provided attribute. The attribute name is canonicalized prior to reading. Returns nil if the attribute does not exist.
# File lib/net/ldap/entry.rb, line 119 def first(name) self[name].first end
Creates a duplicate of the internal Hash containing the attributes of the entry.
# File lib/net/ldap/entry.rb, line 138 def to_h @myhash.dup end
Converts the Entry
to an LDIF-formatted String
# File lib/net/ldap/entry.rb, line 159 def to_ldif Net::LDAP::Dataset.from_entry(self).to_ldif_string end
Private Instance Methods
Returns true if the symbol ends with an equal sign.
# File lib/net/ldap/entry.rb, line 192 def setter?(sym) sym.to_s[-1] == ?= end
Given a valid attribute symbol, returns true.
# File lib/net/ldap/entry.rb, line 186 def valid_attribute?(attr_name) attribute_names.include?(attr_name) end