treequel 1.0.1 → 1.0.4

data/lib/treequel/branchcollection.rb

@@ -29,17 +29,6 @@ require 'treequel/branch'
 # 
 # Note that you could accomplish most of what BranchCollection does
 # using filters, but some people might find this a bit more readable.
-# 
-# == Authors
-# 
-# * Michael Granger <ged@FaerieMUD.org>
-# 
-# :include: LICENSE
-#
-#--
-#
-# Please see the file LICENSE in the base directory for licensing details.
-#
 class Treequel::BranchCollection
 	include Enumerable,
 	        Treequel::Loggable,
@@ -52,12 +41,21 @@ class Treequel::BranchCollection
 	###	C L A S S   M E T H O D S
 	#################################################################
 
-	### Create a delegator that will return an instance of the receiver created with the results of
-	### iterating over the branchsets and calling the delegated method.
+	### Create a delegator that will return an instance of the receiver
+	### created with the results of iterating over the branchsets and calling
+	### the delegated method.
+	### @param [Array<Symbol>] symbols  The methods to define
 	def self::def_cloning_delegators( *symbols )
 		symbols.each do |methname|
 			# Create the method body
 			methodbody = Proc.new {|*args|
+
+				# Check to be sure the mutator version of the method is being called
+				arity = self.branchsets.first.method( methname ).arity
+				if arity.nonzero? && args.empty?
+					raise ArgumentError, "wrong number of arguments: (0 for %d)" % [ arity.abs ]
+				end
+
 				mutated_branchsets = self.branchsets.
 					collect {|bs| bs.send(methname, *args) }.flatten
 				self.class.new( *mutated_branchsets )
@@ -75,6 +73,8 @@ class Treequel::BranchCollection
 	#################################################################
 
 	### Create a new Treequel::BranchCollection that will operate on the given +branchsets+.
+	### @param [Array<Treequel::Branchset, #each>] branchsets  the objects that will be
+	###       combined in the BranchCollection.
 	def initialize( *branchsets )
 		@branchsets = branchsets.flatten.collect do |obj|
 			if obj.respond_to?( :each )
@@ -107,6 +107,7 @@ class Treequel::BranchCollection
 
 
 	### Return a human-readable string representation of the object suitable for debugging.
+	### @return [String]
 	def inspect
 		"#<%s:0x%0x %d branchsets: %p>" % [
 			self.class.name,
@@ -119,6 +120,7 @@ class Treequel::BranchCollection
 
 	### Iterate over the Treequel::Branches found by each member branchset, yielding each 
 	### one in turn.
+	### @yield [Treequel::Branch]
 	def each( &block )
 		raise LocalJumpError, "no block given" unless block
 		self.branchsets.each do |bs|
@@ -128,6 +130,7 @@ class Treequel::BranchCollection
 
 
 	### Return the first Treequel::Branch that is returned from the collection's branchsets.
+	### @return [Treequel::Branch]
 	def first
 		branch = nil
 
@@ -138,7 +141,16 @@ class Treequel::BranchCollection
 		return branch
 	end
 
+
+	### Return +true+ if none of the collection's branches match any entries.
+	### @return [Boolean]
+	def empty?
+		return self.branchsets.all? {|bs| bs.empty? } ? true : false
+	end
+
+
 	### Overridden to support Branchset#map
+	### @param (see Treequel::Branchset#map)
 	def map( attribute=nil, &block )
 		if attribute
 			if block

data/lib/treequel/branchset.rb

@@ -10,6 +10,7 @@ require 'treequel/constants'
 require 'treequel/branch'
 require 'treequel/filter'
 require 'treequel/sequel_integration'
+require 'treequel/control'
 
 
 # A branchset represents an abstract set of LDAP records returned by
@@ -41,21 +42,11 @@ require 'treequel/sequel_integration'
 # 
 # Branchsets are Enumerable objects, so they can be manipulated using any of the 
 # Enumerable methods, such as map, inject, etc.
-# 
-# == Authors
-# 
-# * Michael Granger <ged@FaerieMUD.org>
-# 
-# :include: LICENSE
-#
-#--
-#
-# Please see the file LICENSE in the base directory for licensing details.
-#
 class Treequel::Branchset
 	include Enumerable,
 	        Treequel::Loggable,
-	        Treequel::Constants
+	        Treequel::Constants,
+	        Treequel::Control
 
 	# The default scope to use when searching if none is specified
 	DEFAULT_SCOPE = :subtree
@@ -84,9 +75,13 @@ class Treequel::Branchset
 	### Create a new Branchset for a search from the DN of the specified +branch+ (a 
 	### Treequel::Branch), with the given +options+.
 	def initialize( branch, options={} )
-		super()
 		@branch = branch
 		@options = DEFAULT_OPTIONS.merge( options )
+
+		self.extend( *@branch.directory.registered_controls ) unless
+			@branch.directory.registered_controls.empty?
+
+		super()
 	end
 
 
@@ -103,6 +98,17 @@ class Treequel::Branchset
 	attr_accessor :branch
 
 
+	### Extend the Branchset with one or more modules. Overridden to also call the modules'
+	### initializers if they have them.
+	def extend( *modules )
+		super
+		modules.each do |mod|
+			mod.instance_method( :initialize ).bind( self ).call if
+				mod.private_instance_methods.map( &:to_sym ).include?( :initialize )
+		end
+	end
+
+
 	### Returns the DN of the Branchset's branch.
 	def base_dn
 		return self.branch.dn
@@ -166,7 +172,16 @@ class Treequel::Branchset
 
 	### Create a BranchCollection from the results of the Branchset and return it.
 	def collection
-		Treequel::BranchCollection.new( self.all )
+		return Treequel::BranchCollection.new( self.all )
+	end
+
+
+	### Create a BranchCollection from the receiver and the +other_branchset+ and return 
+	### it. 
+	### @param [Treequel::Branchset] other_branchset  the branchset to combine with
+	### @return [Treequel::BranchCollection]  the resulting collection object
+	def +( other_branchset )
+		return Treequel::BranchCollection.new( self, other_branchset )
 	end
 
 
@@ -174,29 +189,39 @@ class Treequel::Branchset
 	### as Treequel::Branch objects to the supplied block.
 	def each( &block )
 		raise LocalJumpError, "no block given" unless block
-		directory = self.branch.directory
 
-		directory.search( self.branch, self.scope, self.filter,
+		self.branch.search( self.scope, self.filter,
 			:selectattrs => self.select,
 			:timeout => self.timeout,
 			# :sortby => self.order,
 			:limit => self.limit,
+			:client_controls => self.get_client_controls,
+			:server_controls => self.get_server_controls,
 			&block
 		  )
 	end
 
+
 	### Fetch the first entry which matches the current criteria and return it as an instance of
 	### the object that is set as the +branch+ (e.g., Treequel::Branch).
 	def first
-		self.branch.directory.search( self.branch, self.scope, self.filter,
+		self.branch.search( self.scope, self.filter,
 			:selectattrs => self.select,
 			:timeout => self.timeout,
 			# :sortby => self.order,
+			:client_controls => self.get_client_controls,
+			:server_controls => self.get_server_controls,
 			:limit => 1
 		  ).first
 	end
 
 
+	### Return +true+ if no entries match the Branchset's current criteria.
+	def empty?
+		return self.first.nil? ? true : false
+	end
+
+
 	### Either maps entries which match the current criteria into an Array of the given 
 	### +attribute+, or falls back to the block form if no +attribute+ is specified. If both an
 	### +attribute+ and a +block+ are given, the +block+ is called once for each +attribute+ value
@@ -341,29 +366,6 @@ class Treequel::Branchset
 		newset.branch = branchclass.new( self.branch.directory, self.branch.dn )
 		return newset
 	end
-	
-
-	# Hiding this until we figure out how to do server-side ordering (i.e., 
-	# http://tools.ietf.org/html/rfc2891)
-
-	### Return a clone of the receiving Branchsest that will order its results by the
-	### +attributes+ specified.
-	def __order( attribute=:__default__ ) # :nodoc:
-		if attribute == :__default__
-			if block_given?
-				sort_func = Proc.new
-				return self.clone( :order => sort_func )
-			else
-				return self.options[:order]
-			end
-		elsif attribute.nil?
-			self.log.debug "cloning %p with no order" % [ self ]
-			return self.clone( :order => nil )
-		else
-			self.log.debug "cloning %p with new order: %p" % [ self, attribute ]
-			return self.clone( :order => attribute.to_sym )
-		end
-	end
 
 
 end # class Treequel::Branchset

data/lib/treequel/constants.rb

@@ -1,5 +1,6 @@
 #!/usr/bin/ruby
 
+require 'uri'
 require 'ldap'
 require 'treequel'
 
@@ -27,6 +28,118 @@ module Treequel::Constants
 		LDAP::LDAP_SCOPE_SUBTREE  => 'subtree',
 	}
 
+	### Names and OIDs of various controls, in OID order
+	CONTROL_OIDS = {
+		:valuesreturnfilter    => '1.2.826.0.1.334810.2.3',
+		:matchedvals           => '1.2.826.0.1.3344810.2.2',
+		:matchedvalues         => '1.2.826.0.1.3344810.2.3',
+
+		# MS Active Directory controls, from various MSDN references, most 
+		# notably: 
+		# http://msdn.microsoft.com/en-us/library/cc223320%28PROT.10%29.aspx
+		:paged                 => '1.2.840.113556.1.4.319',
+		:server_show_deleted   => '1.2.840.113556.1.4.417',
+		:sortrequest           => '1.2.840.113556.1.4.473',
+		:sortresult            => '1.2.840.113556.1.4.474',
+		:crossdom_move_target  => '1.2.840.113556.1.4.521',
+		:server_notification   => '1.2.840.113556.1.4.528',
+		:extended_dn           => '1.2.840.113556.1.4.529',
+		:referrals             => '1.2.840.113556.1.4.616',
+		:server_lazy_commit    => '1.2.840.113556.1.4.619',
+		:server_sd_flags       => '1.2.840.113556.1.4.801',
+		:incremental_values    => '1.2.840.113556.1.4.802',
+		:tree_delete           => '1.2.840.113556.1.4.805',
+		:server_dirsync        => '1.2.840.113556.1.4.841',
+		:get_stats             => '1.2.840.113556.1.4.970',
+		:verify_name           => '1.2.840.113556.1.4.1338',
+		:domain_scope          => '1.2.840.113556.1.4.1339',
+		:search_options        => '1.2.840.113556.1.4.1340',
+		:rodc_dcpromo          => '1.2.840.113556.1.4.1341',
+		:permissive_modify     => '1.2.840.113556.1.4.1413',
+		:asq                   => '1.2.840.113556.1.4.1504',
+		:fast_bind             => '1.2.840.113556.1.4.1781',
+		:quota_control         => '1.2.840.113556.1.4.1852',
+		:shutdown_notify       => '1.2.840.113556.1.4.1907',
+		:range_retrieval_noerr => '1.2.840.113556.1.4.1948',
+		:force_update          => '1.2.840.113556.1.4.1974',
+		:input_dn              => '1.2.840.113556.1.4.2026',
+
+		# RFC 4527
+		:preread               => '1.3.6.1.1.13.1',
+		:postread              => '1.3.6.1.1.13.2',
+
+		:assertion             => '1.3.6.1.1.12',
+
+		:passwordpolicy        => '1.3.6.1.4.1.42.2.27.8.5.1',
+
+		:ttl_refresh           => '1.3.6.1.4.1.1466.101.119.1',
+		:start_tls             => '1.3.6.1.4.1.1466.20037',
+
+		:sync                  => '1.3.6.1.4.1.4203.1.9.1.1',
+		:sync_state            => '1.3.6.1.4.1.4203.1.9.1.2',
+		:sync_done             => '1.3.6.1.4.1.4203.1.9.1.3',
+		:subentries            => '1.3.6.1.4.1.4203.1.10.1',
+
+		# OpenLDAP "devil made me do it" OID arc
+		:noop                  => "1.3.6.1.4.1.4203.666.5.2",
+		:no_subordinates       => "1.3.6.1.4.1.4203.666.5.11",
+		:relax                 => "1.3.6.1.4.1.4203.666.5.12",
+		:managedit             => "1.3.6.1.4.1.4203.666.5.12",
+		:slurp                 => "1.3.6.1.4.1.4203.666.5.13",
+		:valsort               => "1.3.6.1.4.1.4203.666.5.14",
+		:dontusecopy           => "1.3.6.1.4.1.4203.666.5.15",
+		:x_deref               => "1.3.6.1.4.1.4203.666.5.16",
+		:x_whatfailed          => "1.3.6.1.4.1.4203.666.5.17",
+		:x_chaining_behavior   => "1.3.6.1.4.1.4203.666.11.3",
+
+		# LDAP Duplicated Entry Control Extension
+		:dupent_request        => '2.16.840.1.113719.1.27.101.1',
+		:dupent_response       => '2.16.840.1.113719.1.27.101.2',
+		:dupent_entry          => '2.16.840.1.113719.1.27.101.3',
+
+		:managedsait           => '2.16.840.1.113730.3.4.2',
+		:persistentsearch      => '2.16.840.1.113730.3.4.3',
+		:pwexpired             => '2.16.840.1.113730.3.4.4',
+		:pwexpiring            => '2.16.840.1.113730.3.4.5',
+		:entrychange           => '2.16.840.1.113730.3.4.7',
+		:vlvrequest            => '2.16.840.1.113730.3.4.9',
+		:vlvresponse           => '2.16.840.1.113730.3.4.10',
+		:proxyauthentication   => '2.16.840.1.113730.3.4.18',
+
+	}.freeze
+	CONTROL_NAMES = CONTROL_OIDS.invert.freeze
+
+
+	### Names and OIDs of LDAP extensions, in OID order
+	EXTENSION_OIDS = {
+		# Borrowed from OpenLDAP's ldap.h
+		:cancel        => '1.3.6.1.1.8',                # RFC 3909
+		:turn          => '1.3.6.1.1.19',               # RFC 4531
+
+		:refresh       => '1.3.6.1.4.1.1466.101.119.1', # RFC 2589
+		:start_tls     => '1.3.6.1.4.1.1466.20037',     # RFC 4511
+
+		:modify_passwd => '1.3.6.1.4.1.4203.1.11.1',    # RFC 3062
+		:who_am_i      => '1.3.6.1.4.1.4203.1.11.3',    # RFC 4532
+	}.freeze
+	EXTENSION_NAMES = EXTENSION_OIDS.invert.freeze
+
+
+	### Names and OIDs of LDAP features, in OID order
+	FEATURE_OIDS = {
+		# Borrowed from OpenLDAP's ldap.h
+		:modify_increment       => '1.3.6.1.1.14',
+
+		:all_op_attrs           => '1.3.6.1.4.1.4203.1.5.1', # RFC 3673
+		:objectclass_attrs      => '1.3.6.1.4.1.4203.1.5.2',
+		:absolute_filters       => '1.3.6.1.4.1.4203.1.5.3',
+		:language_tag_options   => '1.3.6.1.4.1.4203.1.5.4',
+		:language_range_options => '1.3.6.1.4.1.4203.1.5.5',
+
+		:subordinate_scope      => '1.3.6.1.4.1.4203.666.8.1',
+	}.freeze
+	FEATURE_NAMES = FEATURE_OIDS.invert.freeze
+
 
 	### OIDs of RFC values
 	module OIDS
@@ -80,6 +193,16 @@ module Treequel::Constants
 	### A collection of Regexps to match various LDAP values
 	module Patterns
 
+		# Steal the URIREF regexp from the URI library. We have to look in
+		# both places to support both 1.9.1 and 1.8.x.
+		URI_REF = if URI::REGEXP.const_defined?( :PATTERN )
+				/#{URI::REGEXP::PATTERN::URI_REF}/
+			elsif URI::REGEXP.const_defined?( :URI_REF )
+				/#{URI::REGEXP::URI_REF}/
+			else
+				raise "Couldn't find the URI_REF constant in the URI library!"
+			end
+
 		# :stopdoc:
 
 		# Schema-parsing patterns based on the BNF in 
@@ -228,26 +351,34 @@ module Treequel::Constants
 		#	numericoid = number 1*( DOT number )
 		NUMERICOID = /#{NUMBER}(?: #{DOT} #{NUMBER} )+/x
 
+		# ActiveDirectory quotes its numeric OIDs (sometimes)
+		QUOTED_NUMERICOID = /#{SQUOTE} #{NUMERICOID} #{SQUOTE}/x
 
-		# Short names, also known as ¨iptors, are used as more readable
+		# Short names, also known as descriptors, are used as more readable
 		# aliases for object identifiers.  Short names are case insensitive and
 		# conform to the ABNF:
 
 		#	descr = keystring
 		DESCR = KEYSTRING
 
+		# ActiveDirectory quotes its descriptors (sometimes)
+		QUOTED_DESCR = / #{SQUOTE} #{DESCR} #{SQUOTE} /x
+
 		# Where either an object identifier or a short name may be specified,
 		# the following production is used:
 
 		#    oid = descr / numericoid
-		OID = / #{DESCR} | #{NUMERICOID} /x
+		# NOTE: Added QUOTED_NUMERICOID and QUOTED_DESCR to support ActiveDirectory
+		OID = / #{DESCR} | #{QUOTED_DESCR} | #{NUMERICOID} | #{QUOTED_NUMERICOID} /x
 
 
 		# len = number
 		LEN = NUMBER
 
 		# noidlen = numericoid [ LCURLY len RCURLY ]
-		NOIDLEN = /#{NUMERICOID} (?:#{LCURLY} #{LEN} #{RCURLY})?/x
+		# NOTE: I changed this from NUMERICOID to OID to support ActiveDirectory schema 
+		#       entries
+		NOIDLEN = /#{OID} (?:#{LCURLY} #{LEN} #{RCURLY})?/x
 
 		# oidlist = oid *( WSP DOLLAR WSP oid )
 		OIDLIST = /#{OID} (?: #{WSP} #{DOLLAR} #{WSP} #{OID} )*/x
@@ -595,6 +726,105 @@ module Treequel::Constants
 		}x
 
 
+		# 
+		# LDIF (RFC 2849)
+		# 
+
+		# attr-type-chars          = ALPHA / DIGIT / "-"
+		# opt-char                 = attr-type-chars
+		#   same as KEYCHAR
+		LDIF_ATTR_TYPE_CHARS = KEYCHAR
+		LDIF_OPT_CHAR = KEYCHAR
+
+		# option                   = 1*opt-char
+		LDIF_ATTRTYPE_OPTION = %r{ #{LDIF_OPT_CHAR}+ }x
+
+		# options                  = option / (option ";" options)
+		LDIF_ATTRTYPE_OPTIONS = %r{
+			#{LDIF_ATTRTYPE_OPTION}
+			(?: ; #{LDIF_ATTRTYPE_OPTION} )*
+		}x
+
+		# AttributeType            = ldap-oid / (ALPHA *(attr-type-chars))
+		LDIF_ATTRIBUTE_TYPE = %r{
+			#{NUMERICOID}
+			|
+			[#{ALPHA}] #{LDIF_ATTR_TYPE_CHARS}*
+		}x
+
+		# AttributeDescription     = AttributeType [";" options]
+		#                            ; Definition taken from [4]
+		LDIF_ATTRIBUTE_DESCRIPTION = %r{
+			#{LDIF_ATTRIBUTE_TYPE}
+			(?: ; #{LDIF_ATTRTYPE_OPTIONS} )?
+		}x
+
+		# SPACE                    = %x20  ; ASCII SP, space
+		# FILL                     = *SPACE
+		FILL = '\x20+'
+
+		# SAFE-CHAR                = %x01-09 / %x0B-0C / %x0E-7F
+		#                            ; any value <= 127 decimal except NUL, LF,
+		#                            ; and CR
+		LDIF_SAFE_CHAR = %r{[\x01-\x09\x0b-\x0c\x0e-\x7f]}
+
+		# SAFE-INIT-CHAR           = %x01-09 / %x0B-0C / %x0E-1F /
+		#                            %x21-39 / %x3B / %x3D-7F
+		#                            ; any value <= 127 except NUL, LF, CR,
+		#                            ; SPACE, colon (":", ASCII 58 decimal)
+		#                            ; and less-than ("<" , ASCII 60 decimal)
+		LDIF_SAFE_INIT_CHAR = %r{[\x01-\x09\x0B-\x0C\x0E-\x1F\x21-\x39\x3B\x3D-\x7F]}
+
+		# SAFE-STRING              = [SAFE-INIT-CHAR *SAFE-CHAR]
+		LDIF_SAFE_STRING = %r{
+			#{LDIF_SAFE_INIT_CHAR}
+			#{LDIF_SAFE_CHAR}*
+		}x
+
+
+		# BASE64-CHAR              = %x2B / %x2F / %x30-39 / %x3D / %x41-5A /
+		#                            %x61-7A
+		#                            ; +, /, 0-9, =, A-Z, and a-z
+		#                            ; as specified in [5]
+		BASE64_CHAR = %r{[\x2B\x2F\x30-\x39\x3D\x41-\x5A\x61-\x7A]}
+
+		# BASE64-STRING            = [*(BASE64-CHAR)]
+		BASE64_STRING = %r{ #{BASE64_CHAR}* }x
+
+		# SEP                      = (CR LF / LF)
+		SEP = %r{\r?\n}
+
+		# Any non-empty line, including comment lines, in an LDIF file
+		# MAY be folded by inserting a line separator (SEP) and a SPACE.
+		FOLD = %r{ #{SEP} #{SPACE} }x
+
+		# value-spec               = ":" (    FILL 0*1(SAFE-STRING) /
+		#                                 ":" FILL (BASE64-STRING) /
+		#                                 "<" FILL url)
+		LDIF_VALUE_SPEC = %r{
+			:
+			(
+				#{FILL} #{LDIF_SAFE_STRING}+ (?: #{FOLD} #{LDIF_SAFE_CHAR}* )*
+				|
+				: #{FILL} #{BASE64_STRING} (?: #{FOLD} #{BASE64_STRING} )*
+				|
+				< #{FILL} #{URI_REF}
+			)
+		}x
+
+		# attrval-spec             = AttributeDescription value-spec SEP
+		LDIF_ATTRVAL_SPEC = %r{
+			(#{LDIF_ATTRIBUTE_DESCRIPTION})
+			#{LDIF_VALUE_SPEC}
+			#{SEP}
+		}xm
+
+
+		# Freeze all the pattern constants so they don't get clobbered
+		constants.each do |const|
+			const_get( const ).freeze
+		end
+
 	end # module Patterns
 
 end # module Treequel::Constants