treequel 1.0.1 → 1.0.4

data/examples/ldap-rack-auth.rb

@@ -99,3 +99,5 @@ module LdapAuthentification
 		end
 
 	end # class BindAuth
+end
+

data/lib/treequel.rb

@@ -1,12 +1,19 @@
 #!/usr/bin/env ruby
 
+require 'ldap'
+require 'ldap/schema'
+require 'ldap/control'
+
 require 'logger'
+require 'pathname'
+
 require 'uri'
 require 'uri/ldap'
 
 
 ### Add an LDAPS URI type if none exists (ruby pre 1.8.7)
 unless URI.const_defined?( :LDAPS )
+	# @private
 	module URI
 		class LDAPS < LDAP
 			DEFAULT_PORT = 636
@@ -18,24 +25,52 @@ end
 
 # A library for interacting with LDAP modelled after Sequel.
 #
-# == Authors
-#
-# * Michael Granger <ged@FaerieMUD.org>
-# * Mahlon E. Smith <mahlon@martini.nu>
-#
-# :include: LICENSE
-#
-#--
-#
-# Please see the file LICENSE in the base directory for licensing details.
+# @version 1.0.4
+# 
+# @example
+#   # Connect to the directory at the specified URL
+#   dir = Treequel.directory( 'ldap://ldap.company.com/dc=company,dc=com' )
+#   
+#   # Get a list of email addresses of every person in the directory (as
+#   # long as people are under ou=people)
+#   dir.ou( :people ).filter( :mail ).map( :mail ).flatten
+#   
+#   # Get a list of all IP addresses for all hosts in any ou=hosts group
+#   # in the whole directory:
+#   dir.filter( :ou => :hosts ).collection.filter( :ipHostNumber ).
+#     map( :ipHostNumber ).flatten
+#   
+#   # Get all people in the directory in the form of a hash of names 
+#   # keyed by email addresses
+#   dir.ou( :people ).filter( :mail ).to_hash( :mail, :cn )
+#   
+# @author Michael Granger <ged@FaerieMUD.org>
+# @author Mahlon E. Smith <mahlon@martini.nu>
 #
+# @see LICENSE Please see the LICENSE file in the base directory for licensing 
+#      details.
+# 
 module Treequel
 
 	# Library version
-	VERSION = '1.0.1'
+	VERSION = '1.0.4'
 
 	# VCS revision
-	REVISION = %q$rev: ca660bd12f7f $
+	REVISION = %q$Revision: c8534439a5bc $
+
+	# Common paths for ldap.conf
+	COMMON_LDAP_CONF_PATHS = %w[
+		./ldaprc
+		~/.ldaprc
+		~/ldaprc
+		/etc/ldap/ldap.conf
+		/etc/openldap/ldap.conf
+		/etc/ldap.conf
+		/usr/local/etc/openldap/ldap.conf
+		/usr/local/etc/ldap.conf
+		/opt/local/etc/openldap/ldap.conf
+		/opt/local/etc/ldap.conf
+	]
 
 	# Load the logformatters and some other stuff first
 	require 'treequel/constants'
@@ -55,13 +90,14 @@ module Treequel
 
 
 	class << self
-		# The log formatter that will be used when the logging subsystem is reset
+		# @return [Logger::Formatter] the log formatter that will be used when the logging 
+		#    subsystem is reset
 		attr_accessor :default_log_formatter
 
-		# The logger that will be used when the logging subsystem is reset
+		# @return [Logger] the logger that will be used when the logging subsystem is reset
 		attr_accessor :default_logger
 
-		# The logger that's currently in effect
+		# @return [Logger] the logger that's currently in effect
 		attr_accessor :logger
 		alias_method :log, :logger
 		alias_method :log=, :logger=
@@ -69,6 +105,7 @@ module Treequel
 
 
 	### Reset the global logger object to the default
+	### @return [void]
 	def self::reset_logger
 		self.logger = self.default_logger
 		self.logger.level = Logger::WARN
@@ -83,14 +120,30 @@ module Treequel
 	end
 
 
-	### Return the library's version string
+	### Get the Treequel version.
+	### @return [String] the library's version
 	def self::version_string( include_buildnum=false )
 		vstring = "%s %s" % [ self.name, VERSION ]
-		vstring << " (build %s)" % [ REVISION ] if include_buildnum
+		vstring << " (build %s)" % [ REVISION[/: ([[:xdigit:]]+)/, 1] || '0' ] if include_buildnum
 		return vstring
 	end
 
+
 	### Create a Treequel::Directory object, either from a Hash of options or an LDAP URL.
+	### @overload directory( uri )
+	###   Create a Treequel::Directory object from an LDAP URI.
+	###   @param [URI, String] uri The URI of the directory to connect to, its base, the bind DN,
+	###                            etc.
+	### @overload directory( options )
+	###   @param [Hash] options the connection options
+	###   @option options [String] :host ('localhost')  The LDAP host to connect to
+	###   @option options [Fixnum] :port (LDAP::LDAP_PORT)  The port number to connect to
+	###   @option options [Symbol] :connect_type (:tls)  The type of connection to establish; :tls, 
+	###                                                  :ssl, or :plain.
+	###   @option options [String] :base_dn  The base DN of the directory.
+	###   @option options [String] :bind_dn  The DN of the user to bind as.
+	###   @option options [String] :pass     The password to use when binding.
+	### @return [Treequel::Directory] the configured Directory object
 	def self::directory( *args )
 		options = {}
 
@@ -101,7 +154,7 @@ module Treequel
 			when Hash
 				options.merge!( arg )
 			else
-				raise ArgumentError, "unknown directory option %p: expected URL or Hash"
+				raise ArgumentError, "unknown directory option %p: expected URL or Hash" % [ arg ]
 			end
 		end
 
@@ -109,20 +162,45 @@ module Treequel
 	end
 
 
+	### Read the configuration from the specified +configfile+ and/or values in ENV and return 
+	### a {Treequel::Directory} for the resulting configuration. Supports OpenLDAP and nss-style 
+	### configuration-file directives, and honors the various OpenLDAP environment variables; 
+	### see ldap.conf(5) for details.
+	### @param [String] configfile  the path to the configuration file to use
+	### @return [Treequel::Directory]  the configured Directory object
+	def self::directory_from_config( configfile=nil )
+		configfile ||= self.find_configfile or
+			raise ArgumentError, "No configfile specified, and no defaults present."
+
+		# Read options from ENV and the config file
+		fileopts    = self.read_opts_from_config( configfile )
+		envopts     = self.read_opts_from_environment
+
+		# Now merge all the options together with env > file > default
+		options = Treequel::Directory::DEFAULT_OPTIONS.merge( fileopts.merge(envopts) )
+
+		return Treequel::Directory.new( options )
+	end
+
+
 	### Make an options hash suitable for passing to Treequel::Directory.new from the
 	### given +uri+.
+	### @param [URI, String] uri  the URI to parse for options
+	### @return [Hash] the parsed options
 	def self::make_options_from_uri( uri )
 		uri = URI( uri ) unless uri.is_a?( URI )
 		raise ArgumentError, "not an LDAP URL: %p" % [ uri ] unless
 			uri.scheme =~ /ldaps?/
 		options = {}
 
+		# Use either the scheme or the port from the URI to set the port
 		if uri.port
 			options[:port] = uri.port
 		elsif uri.scheme == 'ldaps'
 			options[:port] = LDAP::LDAPS_PORT
 		end
 
+		# Set the connection type if the scheme dictates it
 		options[:connect_type] = :ssl if uri.scheme == 'ldaps'
 
 		options[:host]    = uri.host if uri.host
@@ -133,12 +211,137 @@ module Treequel
 		return options
 	end
 
+
+	### Find a valid ldap.conf config file by first looking in the LDAPCONF and LDAPRC environment 
+	### variables, then searching the list of default paths in Treequel::COMMON_LDAP_CONF_PATHS.
+	### @return [String] the first valid path, or nil if no valid configfile could be found
+	### @raise [RuntimeError] if LDAPCONF or LDAPRC contains an invalid or unreadable path
+	def self::find_configfile
+		# LDAPCONF may be set to the path of a configuration file. This path can
+		# be absolute or relative to the current working directory.
+		if configfile = ENV['LDAPCONF']
+			Treequel.log.info "Using LDAPCONF environment variable for path to ldap.conf"
+			configpath = Pathname( configfile ).expand_path
+			raise "Config file #{configfile}, specified in the LDAPCONF environment variable, " +
+				"does not exist or isn't readable." unless configpath.readable?
+			return configpath
+
+		# The LDAPRC, if defined, should be the basename of a file in the current working 
+		# directory or in the user's home directory.
+		elsif rcname = ENV['LDAPRC']
+			Treequel.log.info "Using LDAPRC environment variable for path to ldap.conf"
+			rcpath = Pathname( rcname ).expand_path
+			return rcpath if rcpath.readable?
+			rcpath = Pathname( "~" ).expand_path + rcname
+			return rcpath if rcpath.readable?
+
+			raise "Config file '#{rcname}', specified in the LDAPRC environment variable, does not " +
+				"exist or isn't readable."
+		else
+			Treequel.log.info "Searching common paths for ldap.conf"
+			return COMMON_LDAP_CONF_PATHS.collect {|path| Pathname(path) }.
+				find {|path| path.readable? }
+		end
+	end
+
+
+	### Read the ldap.conf-style configuration from +configfile+ and return it as a Hash.
+	### @param [String] configfile The path to the config file to read.
+	### @return [Hash] The hash of configuration values read from the file, in a form suitable for
+	###   passing to {Treequel::Directory#initialize}.
+	def self::read_opts_from_config( configfile )
+		Treequel.log.debug "Reading config options from %s..." % [ configfile ]
+		opts = {}
+
+		linecount = 0
+		IO.foreach( configfile ) do |line|
+			Treequel.log.debug "  line: %p" % [ line ]
+			linecount += 1
+			case line
+
+			# URI <ldap[si]://[name[:port]] ...>
+			# :TODO: Support multiple URIs somehow?
+			when /^\s*URI\s+(\S+)/i
+				Treequel.log.debug "  setting options from a URI: %p" % [ line ]
+				uriopts = self.make_options_from_uri( $1 )
+				opts.merge!( uriopts )
+
+			# BASE <base>
+			when /^\s*BASE\s+(\S+)/i
+				Treequel.log.debug "  setting default base DN: %p" % [ line ]
+				opts[:base_dn] = $1
+
+			# BINDDN <dn>
+			when /^\s*BINDDN\s+(\S+)/i
+				Treequel.log.debug "  setting bind DN: %p" % [ line ]
+				opts[:bind_dn] = $1
+
+			# bindpw <bindpw> (ldap_nss only)
+			when /^\s*bindpw\s+(\S+)/i
+				Treequel.log.debug "  setting bind password from line %s" % [ linecount ]
+				opts[:pass] = $1
+
+			# HOST <name[:port] ...>
+			when /^\s*HOST\s+(\S+)/i
+				Treequel.log.debug "  setting host: %p" % [ line ]
+				opts[:host] = $1
+
+			# PORT <port>
+			when /^\s*PORT\s+(\S+)/i
+				Treequel.log.debug "  setting port: %p" % [ line ]
+				opts[:port] = $1.to_i
+
+			# SSL <on|off|start_tls>
+			when /^\s*SSL\s+(on|off|start_tls)/i
+				mode = $1.downcase
+				case mode
+				when 'on'
+					Treequel.log.debug "  enabling plain SSL: %p" % [ line ]
+					opts[:port] = 636
+					opts[:connect_type] = :ssl
+				when 'off'
+					Treequel.log.debug "  disabling SSL: %p" % [ line ]
+					opts[:port] = 389
+					opts[:connect_type] = :plain
+				when 'start_tls'
+					Treequel.log.debug "  enabling TLS: %p" % [ line ]
+					opts[:port] = 389
+					opts[:connect_type] = :tls
+				else
+					Treequel.log.error "Unknown 'ssl' setting %p in %s line %d" %
+						[ mode, configfile, linecount ]
+				end
+
+			end
+		end
+
+		return opts
+	end
+
+
+	### Read OpenLDAP-style connection options from ENV and return them as a Hash.
+	### @return [Hash] The hash of configuration values read from the environment, in a form 
+	###   suitable for passing to {Treequel::Directory#initialize}.
+	def self::read_opts_from_environment
+		opts = {}
+
+		opts.merge!( self.make_options_from_uri(ENV['LDAPURI']) ) if ENV['LDAPURI']
+		opts[:host]    = ENV['LDAPHOST']      if ENV['LDAPHOST']
+		opts[:port]    = ENV['LDAPPORT'].to_i if ENV['LDAPPORT']
+		opts[:bind_dn] = ENV['LDAPBINDDN']    if ENV['LDAPBINDDN']
+		opts[:base_dn] = ENV['LDAPBASE']      if ENV['LDAPBASE']
+
+		return opts
+	end
+
+
 	# Now load the rest of the library
 	require 'treequel/exceptions'
 	require 'treequel/directory'
 	require 'treequel/branch'
 	require 'treequel/branchset'
 	require 'treequel/filter'
+	require 'treequel/monkeypatches'
 
 end # module Treequel
 

data/lib/treequel/branch.rb

@@ -13,41 +13,44 @@ require 'treequel/branchcollection'
 
 # The object in Treequel that wraps an entry. It knows how to construct other branches
 # for the entries below itself, and how to search for those entries.
-#
-# == Authors
-#
-# * Michael Granger <ged@FaerieMUD.org>
-# * Mahlon E. Smith <mahlon@martini.nu>
-#
-# :include: LICENSE
-#
-#--
-#
-# Please see the file LICENSE in the base directory for licensing details.
-#
 class Treequel::Branch
 	include Comparable,
 	        Treequel::Loggable,
-	        Treequel::Constants
+	        Treequel::Constants,
+	        Treequel::Constants::Patterns
 
 	extend Treequel::Delegation,
 	       Treequel::AttributeDeclarations
 
 
+	# The default width of LDIF output
+	DEFAULT_LDIF_WIDTH = 70
+
+	# The characters to use to fold an LDIF line (newline + a space)
+	LDIF_FOLD_SEPARATOR = "\n "
+
 
 	#################################################################
 	###	C L A S S   M E T H O D S
 	#################################################################
 
-	# Whether or not to include operational attributes when fetching the entry for branches.
+	# [Boolean] Whether or not to include operational attributes by default.
+	@include_operational_attrs = false
+
+	# Whether or not to include operational attributes when fetching the
+	# entry for branches.
 	class << self
 		extend Treequel::AttributeDeclarations
-		@include_operational_attrs = false
 		predicate_attr :include_operational_attrs
 	end
 
 
 	### Create a new Treequel::Branch from the given +entry+ hash from the specified +directory+.
+	### 
+	### @param [LDAP::Entry] entry  The raw entry object the Branch is wrapping.
+	### @param [Treequel::Directory] directory  The directory object the Branch is from.
+	### 
+	### @return [Treequel::Branch]  The new branch object.
 	def self::new_from_entry( entry, directory )
 		return self.new( directory, entry['dn'].first, entry )
 	end
@@ -57,10 +60,14 @@ class Treequel::Branch
 	###	I N S T A N C E   M E T H O D S
 	#################################################################
 
-	### Create a new Treequel::Branch with the given +directory+, +rdn_attribute+, +rdn_value+, and
-	### +base_dn+. If the optional +entry+ object is given, it will be used to fetch values from
-	### the directory; if it isn't provided, it will be fetched from the +directory+ the first
+	### Create a new Treequel::Branch with the given +directory+, +dn+, and an optional +entry+. 
+	### If the optional +entry+ object is given, it will be used to fetch values from the 
+	### directory; if it isn't provided, it will be fetched from the +directory+ the first
 	### time it is needed.
+	### 
+	### @param [Treequel::Directory] directory  The directory the Branch belongs to.
+	### @param [String] dn  The DN of the entry the Branch is wrapping.
+	### @param [LDAP::Entry, Hash] entry  The entry object if it's already been fetched.
 	def initialize( directory, dn, entry=nil )
 		raise ArgumentError, "invalid DN" unless dn.match( Patterns::DISTINGUISHED_NAME )
 		raise ArgumentError, "can't cast a %s to an LDAP::Entry" % [entry.class.name] unless
@@ -69,10 +76,9 @@ class Treequel::Branch
 		@directory = directory
 		@dn        = dn
 		@entry     = entry
+		@values    = {}
 
 		@include_operational_attrs = self.class.include_operational_attrs?
-
-		@values    = {}
 	end
 
 
@@ -83,11 +89,16 @@ class Treequel::Branch
 	# Delegate some other methods to a new Branchset via the #branchset method
 	def_method_delegators :branchset, :filter, :scope, :select, :limit, :timeout, :order
 
+	# Delegate some methods to the Branch's directory via its accessor
+	def_method_delegators :directory, :controls, :referrals
+
 
 	# The directory the branch's entry lives in
+	# @return [Treequel::Directory]
 	attr_reader :directory
 
-	# The DN of the branch
+	# The DN of the branch.
+	# @return [String]
 	attr_reader :dn
 	alias_method :to_s, :dn
 
@@ -96,7 +107,9 @@ class Treequel::Branch
 
 
 	### Change the DN the Branch uses to look up its entry.
-
+	### 
+	### @param [String] newdn  The new DN.
+	### @return [void]
 	def dn=( newdn )
 		self.clear_caches
 		@dn = newdn
@@ -104,6 +117,9 @@ class Treequel::Branch
 
 
 	### Enable or disable fetching of operational attributes (RC4512, section 3.4).
+	### 
+	### @param [Boolean] new_setting
+	### @return [void]
 	def include_operational_attrs=( new_setting )
 		self.clear_caches
 		@include_operational_attrs = new_setting ? true : false
@@ -111,6 +127,7 @@ class Treequel::Branch
 
 
 	### Return the attribute/s which make up this Branch's RDN.
+	### @return [Hash<Symbol => String>] The Branch's RDN attributes as a Hash.
 	def rdn_attributes
 		return make_rdn_hash( self.rdn )
 	end
@@ -119,41 +136,40 @@ class Treequel::Branch
 	### Return the LDAP::Entry associated with the receiver, fetching it from the
 	### directory if necessary. Returns +nil+ if the entry doesn't exist in the
 	### directory.
+	### 
+	### @return [LDAP::Entry]  The entry wrapped by the Branch.
 	def entry
-		unless @entry
-			if self.include_operational_attrs?
-				@entry = self.directory.get_extended_entry( self )
-			else
-				@entry = self.directory.get_entry( self )
-			end
-		end
-
-		return @entry
+		@entry ||= self.lookup_entry
 	end
 
 
 	### Returns <tt>true</tt> if there is an entry currently in the directory with the
 	### branch's DN.
+	### @return [Boolean]
 	def exists?
 		return self.entry ? true : false
 	end
 
 
 	### Return the RDN of the branch.
+	### @return [String]
 	def rdn
 		return self.split_dn( 2 ).first
 	end
 
 
-	### Return the receiver's DN as an Array of attribute=value pairs. If +limit+ is non-zero, 
-	### only the <code>limit-1</code> first pairs are split from the DN, and the remainder 
-	### will be returned as the last element.
+	### Return the receiver's DN as an Array of attribute=value pairs. 
+	### 
+	### @param [Fixnum] limit  If non-zero, only the <code>limit-1</code> first pairs 
+	###     are split from the DN, and the remainder will be returned as the last 
+	###     element.
 	def split_dn( limit=0 )
 		return self.dn.split( /\s*,\s*/, limit )
 	end
 
 
 	### Return the LDAP URI for this branch
+	### @return [URI]
 	def uri
 		uri = self.directory.uri
 		uri.dn = self.dn
@@ -162,6 +178,7 @@ class Treequel::Branch
 
 
 	### Return the DN of this entry's parent, or nil if it doesn't have one.
+	### @return [String]
 	def parent_dn
 		return nil if self.dn == self.directory.base_dn
 		return self.split_dn( 2 ).last
@@ -169,171 +186,44 @@ class Treequel::Branch
 
 
 	### Return the Branch's immediate parent node.
+	### @return [Treequel::Branch]
 	def parent
 		return self.class.new( self.directory, self.parent_dn )
 	end
 
 
+	### Perform a search with the specified +scope+, +filter+, and +parameters+ 
+	### using the receiver as the base.
+	### 
+	### @param scope      (see Trequel::Directory#search)
+	### @param filter     (see Trequel::Directory#search)
+	### @param parameters (see Trequel::Directory#search)
+	### @param block      (see Trequel::Directory#search)
+	### 
+	### @return [Array<Treequel::Branch>] the search results
+	def search( scope=:subtree, filter='(objectClass=*)', parameters={}, &block )
+		return self.directory.search( self, scope, filter, parameters, &block )
+	end
+
+
 	### Return the Branch's immediate children as Treeque::Branch objects.
+	### @return [Array<Treequel::Branch>]
 	def children
-		return self.directory.search( self, :one, '(objectClass=*)' )
+		return self.search( :one, '(objectClass=*)' )
 	end
 
 
 	### Return a Treequel::Branchset that will use the receiver as its base.
+	### @return [Treequel::Branchset]
 	def branchset
 		return Treequel::Branchset.new( self )
 	end
 
 
-	### Return Treequel::Schema::ObjectClass instances for each of the receiver's
-	### objectClass attributes. If any +additional_classes+ are given, 
-	### merge them with the current list of the current objectClasses for the lookup.
-	def object_classes( *additional_classes )
-		schema = self.directory.schema
-
-		object_classes = self[:objectClass] || []
-		object_classes |= additional_classes.collect {|str| str.to_sym }
-		object_classes << :top if object_classes.empty?
-
-		return object_classes.
-			collect {|oid| schema.object_classes[oid.to_sym] }.
-			uniq
-	end
-
-
-	### Return Treequel::Schema::AttributeType instances for each of the receiver's
-	### objectClass's MUST attributeTypes. If any +additional_object_classes+ are given, 
-	### include the MUST attributeTypes for them as well. This can be used to predict what
-	### attributes would need to be present for the entry to be saved if it added the
-	### +additional_object_classes+ to its own.
-	def must_attribute_types( *additional_object_classes )
-		types = []
-		oclasses = self.object_classes( *additional_object_classes )
-		self.log.debug "Gathering MUST attribute types for %d objectClasses" % [ oclasses.length ]
-		oclasses.each do |oc|
-			self.log.debug "  adding %p from %p" % [ oc.must, oc ]
-			types |= oc.must
-		end
-
-		return types
-	end
-
-
-	### Return OIDs (numeric OIDs as Strings, named OIDs as Symbols) for each of the receiver's
-	### objectClass's MUST attributeTypes. If any +additional_object_classes+ are given, 
-	### include the OIDs of the MUST attributes for them as well. This can be used to predict 
-	### what attributes would need to be present for the entry to be saved if it added the
-	### +additional_object_classes+ to its own.
-	def must_oids( *additional_object_classes )
-		return self.object_classes( *additional_object_classes ).
-			collect {|oc| oc.must_oids }.flatten.uniq.reject {|val| val == '' }
-	end
-
-
-	### Return a Hash of the attributes required by the Branch's objectClasses. If 
-	### any +additional_object_classes+ are given, include the attributes that would be
-	### necessary for the entry to be saved with them.
-	def must_attributes_hash( *additional_object_classes )
-		attrhash = {}
-
-		self.must_attribute_types( *additional_object_classes ).each do |attrtype|
-			self.log.debug "  adding attrtype %p to the MUST attributes hash" % [ attrtype ]
-
-			if attrtype.name == :objectClass
-				attrhash[ :objectClass ] = [:top] | additional_object_classes
-			elsif attrtype.single?
-				attrhash[ attrtype.name ] = ''
-			else
-				attrhash[ attrtype.name ] = ['']
-			end
-		end
-
-		return attrhash
-	end
-
-
-	### Return Treequel::Schema::AttributeType instances for each of the receiver's
-	### objectClass's MAY attributeTypes. If any +additional_object_classes+ are given, 
-	### include the MAY attributeTypes for them as well. This can be used to predict what
-	### optional attributes could be added to the entry if the +additional_object_classes+ 
-	### were added to it.
-	def may_attribute_types( *additional_object_classes )
-		return self.object_classes( *additional_object_classes ).
-			collect {|oc| oc.may }.flatten.uniq
-	end
-
-
-	### Return OIDs (numeric OIDs as Strings, named OIDs as Symbols) for each of the receiver's
-	### objectClass's MAY attributeTypes. If any +additional_object_classes+ are given, 
-	### include the OIDs of the MAY attributes for them as well. This can be used to predict 
-	### what optional attributes could be added to the entry if the +additional_object_classes+ 
-	### were added to it.
-	def may_oids( *additional_object_classes )
-		return self.object_classes( *additional_object_classes ).
-			collect {|oc| oc.may_oids }.flatten.uniq
-	end
-
-
-	### Return a Hash of the optional attributes allowed by the Branch's objectClasses. If 
-	### any +additional_object_classes+ are given, include the attributes that would be
-	### available for the entry if it had them.
-	def may_attributes_hash( *additional_object_classes )
-		entry = self.entry
-		attrhash = {}
-
-		self.may_attribute_types( *additional_object_classes ).each do |attrtype|
-			self.log.debug "  adding attrtype %p to the MAY attributes hash" % [ attrtype ]
-
-			if attrtype.single?
-				attrhash[ attrtype.name ] = nil
-			else
-				attrhash[ attrtype.name ] = []
-			end
-		end
-
-		attrhash[ :objectClass ] |= additional_object_classes
-		return attrhash
-	end
-
-
-	### Return Treequel::Schema::AttributeType instances for the set of all of the receiver's
-	### MUST and MAY attributeTypes.
-	def valid_attribute_types
-		return self.must_attribute_types | self.may_attribute_types
-	end
-
-
-	### Return a uniqified Array of OIDs (numeric OIDs as Strings, named OIDs as Symbols) for
-	### the set of all of the receiver's MUST and MAY attributeTypes.
-	def valid_attribute_oids
-		return self.must_oids | self.may_oids
-	end
-
-
-	### Return a Hash of all the attributes allowed by the Branch's objectClasses. If
-	### any +additional_object_classes+ are given, include the attributes that would be
-	### available for the entry if it had them.
-	def valid_attributes_hash( *additional_object_classes )
-		must = self.must_attributes_hash( *additional_object_classes )
-		may  = self.may_attributes_hash( *additional_object_classes )
-
-		return may.merge( must )
-	end
-
-
-	### Return +true+ if the specified +attrname+ is a valid attributeType given the
-	### receiver's current objectClasses.
-	def valid_attribute?( attroid )
-		attroid = attroid.to_sym if attroid.is_a?( String ) &&
-			attroid !~ NUMERICOID
-
-		return self.valid_attribute_types.any? { |a| a.names.include?( attroid ) }
-	end
-
-
 	### Returns a human-readable representation of the object suitable for
 	### debugging.
+	### 
+	### @return [String]
 	def inspect
 		return "#<%s:0x%0x %s @ %s entry=%p>" % [
 			self.class.name,
@@ -346,23 +236,23 @@ class Treequel::Branch
 
 
 	### Return the entry's DN as an RFC1781-style UFN (User-Friendly Name).
+	### @return [String]
 	def to_ufn
 		return LDAP.dn2ufn( self.dn )
 	end
 
 
 	### Return the Branch as an LDAP::LDIF::Entry.
-	def to_ldif
+	### @return [String]
+	def to_ldif( width=DEFAULT_LDIF_WIDTH )
 		ldif = "dn: %s\n" % [ self.dn ]
 
 		entry = self.entry || self.valid_attributes_hash
+		self.log.debug "  making LDIF from an entry: %p" % [ entry ]
 
 		entry.keys.reject {|k| k == 'dn' }.each do |attribute|
 			entry[ attribute ].each do |val|
-				# self.log.debug "  creating LDIF fragment for %p=%p" % [ attribute, val ]
-				frag = LDAP::LDIF.to_ldif( attribute, [val.dup] )
-				# self.log.debug "  LDIF fragment is: %p" % [ frag ]
-				ldif << frag
+				ldif << ldif_for_attr( attribute, val, width )
 			end
 		end
 
@@ -370,7 +260,40 @@ class Treequel::Branch
 	end
 
 
+	### Make LDIF for the given +attribute+ and its +values+, wrapping at the given
+	### +width+.
+	### 
+	### @param [String] attribute  the attribute
+	### @param [Array<String>] values  the values for the given +attribute+
+	### @param [Fixnum] width  the maximum width of the lines to return
+	def ldif_for_attr( attribute, values, width )
+		ldif = ''
+
+		Array( values ).each do |val|
+			line = "#{attribute}:"
+
+			if val =~ /^#{LDIF_SAFE_STRING}$/
+				line << ' ' << val.to_s
+			else
+				line << ': ' << [ val ].pack( 'm' ).chomp
+			end
+
+			# calculate how many times the line needs to be split, then add any 
+			# additional splits that need to be added because of the additional
+			# fold characters
+			splits  = ( line.length / width )
+			splits += ( splits * LDIF_FOLD_SEPARATOR.length ) / width
+			splits.times {|i| line[ width * (i+1), 0 ] = LDIF_FOLD_SEPARATOR }
+
+			ldif << line << "\n"
+		end
+
+		return ldif
+	end
+
+
 	### Fetch the value/s associated with the given +attrname+ from the underlying entry.
+	### @return [Array, String]
 	def []( attrname )
 		attrsym = attrname.to_sym
 
@@ -409,7 +332,21 @@ class Treequel::Branch
 	end
 
 
+	### Fetch one or more values from the entry.
+	### 
+	### @param [Array<Symbol, String>] attributes  The attributes to fetch values for.
+	### @return [Array<String>]  The values which correspond to +attributes+.
+	def values_at( *attributes )
+		return attributes.collect do |attribute|
+			self[ attribute ]
+		end
+	end
+
+
 	### Set attribute +attrname+ to a new +value+.
+	### 
+	### @param [Symbol, String] attrname  attribute name
+	### @param [Object] value  the attribute value
 	def []=( attrname, value )
 		value = [ value ] unless value.is_a?( Array )
 		self.log.debug "Modifying %s to %p" % [ attrname, value ]
@@ -420,6 +357,9 @@ class Treequel::Branch
 
 
 	### Make the changes to the entry specified by the given +attributes+.
+	### 
+	### @param attributes (see Treequel::Directory#modify)
+	### @return [TrueClass] if the merge succeeded
 	def merge( attributes )
 		self.directory.modify( self, attributes )
 		self.clear_caches
@@ -429,9 +369,34 @@ class Treequel::Branch
 	alias_method :modify, :merge
 
 
-	### Delete the entry associated with the branch from the directory.
-	def delete
-		self.directory.delete( self )
+	### Delete the specified attributes.
+	### 
+	### @param [Array<Hash, #to_s>] attributes  The attributes to delete, either as
+	###     attribute names (in which case all values of the attribute are deleted) or
+	###     Hashes of attributes and the Array of value/s which should be deleted.
+	### 
+	### @example Delete all 'description' attributes
+	###     branch.delete( :description )
+	### @example Delete the 'inetOrgPerson' and 'posixAccount' objectClasses from the entry
+	###     branch.delete( :objectClass => [:inetOrgPerson, :posixAccount] )
+	### @example Delete any blank 'description' or 'cn' attributes:
+	###     branch.delete( :description => '', :cn => '' )
+	### 
+	### @return [TrueClass] if the delete succeeded
+	def delete( *attributes )
+		self.log.debug "Deleting attributes: %p" % [ attributes ]
+		mods = attributes.flatten.collect do |attribute|
+			if attribute.is_a?( Hash )
+				attribute.collect do |key,vals|
+					vals = Array( vals ).collect {|val| val.to_s }
+					LDAP::Mod.new( LDAP::LDAP_MOD_DELETE, key.to_s, vals )
+				end
+			else
+				LDAP::Mod.new( LDAP::LDAP_MOD_DELETE, attribute.to_s, [] )
+			end
+		end.flatten
+
+		self.directory.modify( self, mods )
 		self.clear_caches
 
 		return true
@@ -440,6 +405,8 @@ class Treequel::Branch
 
 	### Create the entry for this Branch with the specified +attributes+. The +attributes+ should,
 	### at a minimum, contain the pair `:objectClass => :someStructuralObjectClass`.
+	### 
+	### @param [Hash<Symbol,String => Object>] attributes
 	def create( attributes={} )
 		self.directory.create( self, attributes )
 		return self
@@ -448,6 +415,10 @@ class Treequel::Branch
 
 	### Copy the entry for this Branch to a new entry with the given +newdn+ and merge in the
 	### specified +attributes+.
+	### 
+	### @param [String] newdn  the dn of the new entry
+	### @param [Hash<String, Symbol => Object>] attributes  merge attributes
+	### @return [Treequel::Branch] a Branch for the new entry
 	def copy( newdn, attributes={} )
 
 		# Fully-qualify RDNs
@@ -468,14 +439,20 @@ class Treequel::Branch
 	### Move the entry associated with this branch to a new entry indicated by +rdn+. If 
 	### any +attributes+ are given, also replace the corresponding attributes on the new
 	### entry with them.
-	def move( rdn, attributes={} )
+	### 
+	### @param [String] rdn  
+	### @param [Hash<String, Symbol => Object>] attributes 
+	def move( rdn )
 		self.log.debug "Asking the directory to move me to an entry called %p" % [ rdn ]
-		return self.directory.move( self, rdn, attributes )
+		return self.directory.move( self, rdn )
 	end
 
 
 	### Comparable interface: Returns -1 if other_branch is less than, 0 if other_branch is 
 	### equal to, and +1 if other_branch is greater than the receiving Branch.
+	### 
+	### @param [Treequel::Branch] other_branch
+	### @return [Fixnum]
 	def <=>( other_branch )
 		# Try the easy cases first
 		return nil unless other_branch.respond_to?( :dn ) &&
@@ -497,6 +474,9 @@ class Treequel::Branch
 
 	### Fetch a new Treequel::Branch object for the child of the receiver with the specified
 	### +rdn+.
+	### 
+	### @param [String] rdn  The RDN of the child to fetch.
+	### @return [Treequel::Branch]
 	def get_child( rdn )
 		newdn = [ rdn, self.dn ].join( ',' )
 		return self.class.new( self.directory, newdn )
@@ -505,41 +485,270 @@ class Treequel::Branch
 
 	### Addition operator: return a Treequel::BranchCollection that contains both the receiver
 	### and +other_branch+.
+	### 
+	### @param [Treequel::Branch] other_branch  
+	### @return [Treequel::BranchCollection]
 	def +( other_branch )
 		return Treequel::BranchCollection.new( self.branchset, other_branch.branchset )
 	end
 
 
+	### Return Treequel::Schema::ObjectClass instances for each of the receiver's
+	### objectClass attributes. If any +additional_classes+ are given, 
+	### merge them with the current list of the current objectClasses for the lookup.
+	### 
+	### @param [Array<String, Symbol>] additional_classes 
+	### @return [Array<Treequel::Schema::ObjectClass>]
+	def object_classes( *additional_classes )
+		schema = self.directory.schema
+
+		oc_oids = self[:objectClass] || []
+		oc_oids |= additional_classes.collect {|str| str.to_sym }
+		oc_oids << :top if oc_oids.empty?
+
+		oclasses = []
+		oc_oids.each do |oid|
+			oc = schema.object_classes[ oid.to_sym ] or
+				raise Treequel::Error, "schema doesn't have a %p objectClass" % [ oid ]
+			oclasses << oc
+		end
+
+		return oclasses.uniq
+	end
+
+
+	### Return Treequel::Schema::AttributeType instances for each of the receiver's
+	### objectClass's MUST attributeTypes. If any +additional_object_classes+ are given, 
+	### include the MUST attributeTypes for them as well. This can be used to predict what
+	### attributes would need to be present for the entry to be saved if it added the
+	### +additional_object_classes+ to its own.
+	### 
+	### @param [Array<String, Symbol>] additional_object_classes 
+	### @return [Array<Treequel::Schema::AttributeType>]
+	def must_attribute_types( *additional_object_classes )
+		types = []
+		oclasses = self.object_classes( *additional_object_classes )
+		self.log.debug "Gathering MUST attribute types for objectClasses: %p" % [ oclasses ]
+
+		oclasses.each do |oc|
+			self.log.debug "  adding %p from %p" % [ oc.must, oc ]
+			types |= oc.must
+		end
+
+		return types
+	end
+
+
+	### Return OIDs (numeric OIDs as Strings, named OIDs as Symbols) for each of the receiver's
+	### objectClass's MUST attributeTypes. If any +additional_object_classes+ are given, 
+	### include the OIDs of the MUST attributes for them as well. This can be used to predict 
+	### what attributes would need to be present for the entry to be saved if it added the
+	### +additional_object_classes+ to its own.
+	### 
+	### @param [Array<String, Symbol>] additional_object_classes 
+	### @return [Array<String, Symbol>] oid strings and symbols
+	def must_oids( *additional_object_classes )
+		return self.object_classes( *additional_object_classes ).
+			collect {|oc| oc.must_oids }.flatten.uniq.reject {|val| val == '' }
+	end
+
+
+	### Return a Hash of the attributes required by the Branch's objectClasses. If 
+	### any +additional_object_classes+ are given, include the attributes that would be
+	### necessary for the entry to be saved with them.
+	### 
+	### @param [Array<String, Symbol>] additional_object_classes 
+	### @return [Hash<String => String>]
+	def must_attributes_hash( *additional_object_classes )
+		attrhash = {}
+
+		self.must_attribute_types( *additional_object_classes ).each do |attrtype|
+			self.log.debug "  adding attrtype %p to the MUST attributes hash" % [ attrtype ]
+
+			if attrtype.name == :objectClass
+				attrhash[ :objectClass ] = [:top] | additional_object_classes
+			elsif attrtype.single?
+				attrhash[ attrtype.name ] = ''
+			else
+				attrhash[ attrtype.name ] = ['']
+			end
+		end
+
+		return attrhash
+	end
+
+
+	### Return Treequel::Schema::AttributeType instances for each of the receiver's
+	### objectClass's MAY attributeTypes. If any +additional_object_classes+ are given, 
+	### include the MAY attributeTypes for them as well. This can be used to predict what
+	### optional attributes could be added to the entry if the +additional_object_classes+ 
+	### were added to it.
+	### 
+	### @param [Array<String, Symbol>] additional_object_classes 
+	### @return [Array<Treequel::Schema::AttributeType>]
+	def may_attribute_types( *additional_object_classes )
+		return self.object_classes( *additional_object_classes ).
+			collect {|oc| oc.may }.flatten.uniq
+	end
+
+
+	### Return OIDs (numeric OIDs as Strings, named OIDs as Symbols) for each of the receiver's
+	### objectClass's MAY attributeTypes. If any +additional_object_classes+ are given, 
+	### include the OIDs of the MAY attributes for them as well. This can be used to predict 
+	### what optional attributes could be added to the entry if the +additional_object_classes+ 
+	### were added to it.
+	### 
+	### @param [Array<String, Symbol>] additional_object_classes 
+	### @return [Array<String, Symbol>]  oid strings and symbols
+	def may_oids( *additional_object_classes )
+		return self.object_classes( *additional_object_classes ).
+			collect {|oc| oc.may_oids }.flatten.uniq
+	end
+
+
+	### Return a Hash of the optional attributes allowed by the Branch's objectClasses. If 
+	### any +additional_object_classes+ are given, include the attributes that would be
+	### available for the entry if it had them.
+	### 
+	### @param [Array<String, Symbol>] additional_object_classes 
+	### @return [Hash<String => String>]
+	def may_attributes_hash( *additional_object_classes )
+		entry = self.entry
+		attrhash = {}
+
+		self.may_attribute_types( *additional_object_classes ).each do |attrtype|
+			self.log.debug "  adding attrtype %p to the MAY attributes hash" % [ attrtype ]
+
+			if attrtype.single?
+				attrhash[ attrtype.name ] = nil
+			else
+				attrhash[ attrtype.name ] = []
+			end
+		end
+
+		attrhash[ :objectClass ] |= additional_object_classes
+		return attrhash
+	end
+
+
+	### Return Treequel::Schema::AttributeType instances for the set of all of the receiver's
+	### MUST and MAY attributeTypes.
+	### 
+	### @return [Array<Treequel::Schema::AttributeType>]
+	def valid_attribute_types
+		return self.must_attribute_types | self.may_attribute_types
+	end
+
+
+	### Return a uniqified Array of OIDs (numeric OIDs as Strings, named OIDs as Symbols) for
+	### the set of all of the receiver's MUST and MAY attributeTypes.
+	### 
+	### @return [Array<String, Symbol>]
+	def valid_attribute_oids
+		return self.must_oids | self.may_oids
+	end
+
+
+	### If the given +attroid+ is a valid attributeType name or numeric OID, return the 
+	### AttributeType object that corresponds with it. If it isn't valid, return nil.
+	###
+	### @param [String,Symbol] attroid  a numeric OID (as a String) or a named OID (as a Symbol)
+	### @return [Treequel::Schema::AttributeType] the validated attributeType
+	def valid_attribute_type( attroid )
+		return self.valid_attribute_types.find {|attr_type| attr_type.valid_name?(attroid) }
+	end
+
+
+	### Return +true+ if the specified +attrname+ is a valid attributeType given the
+	### receiver's current objectClasses.
+	### 
+	### @param [String, Symbol] the OID (numeric or name) of the attribute in question
+	### @return [Boolean]
+	def valid_attribute?( attroid )
+		return !self.valid_attribute_type( attroid ).nil?
+	end
+
+
+	### Return a Hash of all the attributes allowed by the Branch's objectClasses. If
+	### any +additional_object_classes+ are given, include the attributes that would be
+	### available for the entry if it had them.
+	### 
+	### @param [Array<String, Symbol>] additional_object_classes 
+	### @return [Hash<String => String>]
+	def valid_attributes_hash( *additional_object_classes )
+		self.log.debug "Gathering a hash of all valid attributes:"
+		must = self.must_attributes_hash( *additional_object_classes )
+		self.log.debug "  MUST attributes: %p" % [ must ]
+		may  = self.may_attributes_hash( *additional_object_classes )
+		self.log.debug "  MAY attributes: %p" % [ may ]
+
+		return may.merge( must )
+	end
+
 
 	#########
 	protected
 	#########
 
-	### Proxy method: if the first argument matches a valid attribute in the directory's
-	### schema, return a new Branch for the RDN made by using the first two arguments as
-	### attribute and value, and the remaining hash as additional attributes.
+	### Proxy method: call #traverse_branch if +attribute+ is a valid attribute
+	### and +value+ isn't +nil+.
+	### @see Treequel::Branch#traverse_branch
+	def method_missing( attribute, value=nil, additional_attributes={} )
+		return super( attribute ) if value.nil?
+		return self.traverse_branch( attribute, value, additional_attributes )
+	end
+
+
+	### If +attribute+ matches a valid attribute type in the directory's
+	### schema, return a new Branch for the RDN of +attribute+ and +value+, and 
+	### +additional_attributes+ if it's a multi-value RDN.
+	###
+	### @param [Symbol] attribute            the RDN attribute of the child
+	### @param [String] value                the RDN valye of the child
+	### @param [Hash] additional_attributes  any additional RDN attributes
 	### 
-	### E.g.,
+	### @example
 	###   branch = Treequel::Branch.new( directory, 'ou=people,dc=acme,dc=com' )
 	###   branch.uid( :chester ).dn
 	###   # => 'uid=chester,ou=people,dc=acme,dc=com'
 	###   branch.uid( :chester, :employeeType => 'admin' ).dn
 	###   # => 'uid=chester+employeeType=admin,ou=people,dc=acme,dc=com'
-	def method_missing( attribute, value=nil, additional_attributes={} )
-		return super( attribute ) if value.nil?
+	### 
+	### @return [Treequel::Branch]  the Branch for the specified child
+	### @raise [NoMethodError] if the +attribute+ or any +additional_attributes+ are
+	###                        not valid attributeTypes.
+	def traverse_branch( attribute, value, additional_attributes={} )
 		valid_types = self.directory.schema.attribute_types
 
-		return super(attribute) unless
-			valid_types.key?( attribute ) &&
-			additional_attributes.keys.all? {|ex_attr| valid_types.key?(ex_attr) }
+		# Raise if either the primary attribute or any secondary attributes are invalid
+		if !valid_types.key?( attribute )
+			raise NoMethodError, "undefined method `%s' for %p" % [ attribute, self ]
+		elsif invalid = additional_attributes.keys.find {|ex_attr| !valid_types.key?(ex_attr) }
+			raise NoMethodError, "invalid secondary attribute `%s' for %p" %
+				[ invalid, self ]
+		end
 
+		# Make a normalized RDN from the arguments and return the Branch for it
 		rdn = rdn_from_pair_and_hash( attribute, value, additional_attributes )
-
 		return self.get_child( rdn )
 	end
 
 
+	### Fetch the entry from the Branch's directory.
+	def lookup_entry
+		self.log.debug "Looking up entry for %p" % [ self ]
+		if self.include_operational_attrs?
+			self.log.debug "  including operational attributes."
+			return self.directory.get_extended_entry( self )
+		else
+			self.log.debug "  not including operational attributes."
+			return self.directory.get_entry( self )
+		end
+	end
+
+
 	### Clear any cached values when the structural state of the object changes.
+	### @return [void]
 	def clear_caches
 		@entry = nil
 		@values.clear