treequel 1.6.0 → 1.7.0

data/lib/treequel/branchset.rb

@@ -185,10 +185,8 @@ class Treequel::Branchset
 
 
 	### If given another Branchset or a BranchCollection, return a BranchCollection that includes
-	### them both. If given anything else, execute the search and return 
-	### @param [Treequel::Branchset, Treequel::Branch] other  the branchset or branch to combine 
-	###                                                       with
-	### @return [Treequel::BranchCollection, Array<Treequel::Branch>]
+	### them both. If given anything else, execute the search and return the results plus
+	### +other+ in an Array.
 	def +( other )
 		if other.is_a?( Treequel::BranchCollection ) || other.is_a?( Treequel::Branchset )
 			return Treequel::BranchCollection.new( self, other )
@@ -199,8 +197,6 @@ class Treequel::Branchset
 
 
 	### Return the results of executing the search without the +other_object+.
-	### @param [#dn] other_object  the object to omit from the results; must respond_to #dn.
-	### @return [Array<Treequel::Branch>]
 	def -( other_object )
 		other_dn = other_object.dn
 		return self.reject {|branch| branch.dn.downcase == other_dn.downcase }
@@ -224,17 +220,24 @@ class Treequel::Branchset
 	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.search( self.scope, self.filter,
+	### Fetch the first +n+ entries which matches the current criteria and return them as 
+	### instances of the object that is set as the +branch+ (e.g., Treequel::Branch). If +n+ is
+	### +nil+, returns just the first object in the Array.
+	def first( n=nil )
+		results = 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
+			:limit => n || 1
+		  )
+
+		if n
+			return results.first( n )
+		else
+			return results.first
+		end
 	end
 
 
@@ -307,10 +310,7 @@ class Treequel::Branchset
 	end
 
 
-	### Add an alternate filter to an existing filter by ORing them.
-	### @param filterspec  the filter spec to OR with the existing filter
-	### @raises [Treequel::InvalidOperation]  if there is no existing filter
-	### @see Treequel::Filter.new  for specifics on what +filterspec+ can be
+	### Add an alternate filter to an existing filter by ORing it with +filterspec+.
 	def or( *filterspec )
 		opts = self.options
 		existing_filter = self.filter
@@ -324,6 +324,14 @@ class Treequel::Branchset
 	end
 
 
+	### Add a clause made from a negated +filterspec+ to an existing filter.
+	def not( *filterspec )
+		self.log.debug "cloning %p with negated filterspec: %p" % [ self, filterspec ]
+		notfilter = Treequel::Filter.new( :not, *filterspec )
+		return self.clone( :filter => self.filter + notfilter )
+	end
+
+
 	### If called with no argument, returns the current scope of the Branchset. If 
 	### called with an argument (which should be one of the keys of 
 	### Treequel::Constants::SCOPE), returns a clone of the receiving Branchset
@@ -427,7 +435,6 @@ class Treequel::Branchset
 
 	### Return a clone of the receiving Branchset that will perform its search from
 	### +other_dn+ instead of its own.
-	### @param [String, #dn]  other_dn  the new base DN of the search
 	def from( other_dn )
 		newset = self.clone
 		other_dn = other_dn.dn if other_dn.respond_to?( :dn )

data/lib/treequel/control.rb

@@ -8,13 +8,15 @@ require 'treequel'
 
 # Virtual interface methods for Control modules.
 #
-# @abstract To make a concrete derivative, include this module in a module that
-#   implements either {#get_client_controls} or {#get_server_controls} and #each. 
-#   Your implementation of #each should +super+ with a block that does the 
-#   necessary extraction of the result controls and yields back to the original
-#   block.
+# == Subclassing
+# To make a concrete derivative, include this module in a module that
+# implements either #get_client_controls or #get_server_controls and #each. 
+# Your implementation of #each should +super+ with a block that does the 
+# necessary extraction of the result controls and yields back to the original
+# block.
 # 
-# @example
+# == Examples
+#
 #   module Treequel::MyControl
 #       include Treequel::Control
 #   

data/lib/treequel/controls/contentsync.rb

@@ -34,8 +34,8 @@ require 'treequel/constants'
 #       # 
 #   end
 # 
-# @see http://deveiate.org/projects/Treequel/ticket/6  Ticket: Add support for 
-#      the RFC4533 Content Sync operation
+# See http://deveiate.org/projects/Treequel/ticket/6  Ticket: Add support for 
+# the RFC4533 Content Sync operation.
 # 
 module Treequel::ContentSyncControl
 	include Treequel::Control,

data/lib/treequel/controls/pagedresults.rb

@@ -63,10 +63,7 @@ module Treequel::PagedResultsControl
 	attr_accessor :paged_results_cookie
 
 
-	### Clone the Branchset with a paged results control.
-	### @param [Fixnum] setsize  The size of each result set. If this is nil or 0, removes 
-	###                          paging from the Branchset.
-	### @return [Treequel::Branchset]  a clone of the receiver with paging set to +setsize+
+	### Clone the Branchset with a paged results control with paging set to +setsize+.
 	def with_paged_results( setsize=DEFAULT_PAGE_SIZE )
 		self.log.warn "This control will likely not work in ruby-ldap versions " +
 			" <= 0.9.9. See http://code.google.com/p/ruby-activeldap/issues/" +
@@ -87,7 +84,6 @@ module Treequel::PagedResultsControl
 
 
 	### Clone the Branchset without paging and return it.
-	### @return [Treequel::Branchset]  a clone of the receiver, stripped of its paging
 	def without_paging
 		copy = self.clone
 		copy.without_paging!
@@ -96,7 +92,6 @@ module Treequel::PagedResultsControl
 
 
 	### Remove any paging control associated with the receiving Branchset.
-	### @return [void]
 	def without_paging!
 		self.paged_results_cookie = nil
 		self.paged_results_setsize = nil
@@ -105,7 +100,6 @@ module Treequel::PagedResultsControl
 
 	### Returns +true+ if the first page of results has been fetched and there are
 	### more pages remaining.
-	### @return [Boolean]
 	def has_more_results?
 		return true unless self.done_paging?
 	end
@@ -113,7 +107,6 @@ module Treequel::PagedResultsControl
 
 	### Returns +true+ if results have yet to be fetched, or if they have all been 
 	### fetched.
-	### @return [Boolean]
 	def done_paging?
 		return self.paged_results_cookie == ''
 	end
@@ -121,7 +114,6 @@ module Treequel::PagedResultsControl
 
 	### Override the Enumerable method to update the cookie value each time a page 
 	### is fetched.
-	### @yieldparam [Treequel::Branch] branch  the branch that's a result of the search.
 	def each( &block )
 		super do |branch|
 			if paged_control = branch.controls.find {|control| control.oid == OID }
@@ -145,7 +137,6 @@ module Treequel::PagedResultsControl
 
 	### Treequel::Control API -- Get the set of server controls currently configured for 
 	### the receiver.
-	### @return [Array<LDAP::Control>]  the configured controls
 	def get_server_controls
 		controls = super
 		if pagesize = self.paged_results_setsize && self.paged_results_setsize.nonzero?

data/lib/treequel/directory.rb

@@ -105,21 +105,20 @@ class Treequel::Directory
 	### Create a new Treequel::Directory with the given +options+. Options is a hash with one
 	### or more of the following key-value pairs:
 	### 
-	### @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 (nil)
+	### [+:host+]
+	###    The LDAP host to connect to (default: 'localhost').
+	### [+:port+]
+	###    The port number to connect to (default: LDAP::LDAP_PORT).
+	### [+:connect_type+]
+	###    The type of connection to establish; :tls, :ssl, or :plain. Defaults to +:tls+.
+	### [+:base_dn+]
 	###    The base DN of the directory; defaults to the first naming context of
 	###    the directory's root DSE.
-	### @option options [String] :bind_dn (nil)
+	### [+:bind_dn+]
 	###    The DN of the user to bind as; if unset, binds anonymously.
-	### @option options [String] :pass (nil)
+	### [+:pass+]
 	###    The password to use when binding.
-	### @option options [CLass] :results_class (Treequel::Branch)
+	### [+:results_class+]
 	###    The class to instantiate by default for entries fetched from the Directory.
 	def initialize( options={} )
 		options                = DEFAULT_OPTIONS.merge( options )
@@ -171,31 +170,24 @@ class Treequel::Directory
 
 
 	# The host to connect to.
-	# @return [String]
 	attr_accessor :host
 
 	# The port to connect to.
-	# @return [Fixnum]
 	attr_accessor :port
 
 	# The type of connection to establish
-	# @return [Symbol]
 	attr_accessor :connect_type
 
 	# The Class to instantiate when wrapping results fetched from the Directory.
-	# @return [Class]
 	attr_accessor :results_class
 
 	# The base DN of the directory
-	# @return [String]
 	attr_accessor :base_dn
 
 	# The control modules that are registered with the directory
-	# @return [Array<Module>]
 	attr_reader :registered_controls
 
 	# The DN of the user the directory is bound as
-	# @return [String]
 	attr_reader :bound_user
 
 
@@ -206,14 +198,12 @@ class Treequel::Directory
 
 
 	### Fetch the Branch for the base node of the directory.
-	### @return [Treequel::Branch]
 	def base
 		return @base ||= self.results_class.new( self, self.base_dn )
 	end
 
 
 	### Returns a string that describes the directory
-	### @return [String]
 	def to_s
 		return "%s:%d (%s, %s, %s)" % [
 			self.host,
@@ -226,7 +216,6 @@ class Treequel::Directory
 
 
 	### Return a human-readable representation of the object suitable for debugging
-	### @return [String]
 	def inspect
 		return %{#<%s:0x%0x %s:%d (%s) base_dn=%p, bound as=%s, schema=%s>} % [
 			self.class.name,
@@ -243,7 +232,6 @@ class Treequel::Directory
 
 	### Return the LDAP::Conn object associated with this directory, creating it with the
 	### current options if necessary.
-	### @return [LDAP::Conn, LDAP::SSLConn]
 	def conn
 		return @conn ||= self.connect
 	end
@@ -252,15 +240,12 @@ class Treequel::Directory
 	### Returns +true+ if a connection has been established. This does not necessarily mean
 	### that the connection is still valid, it just means it successfully established one
 	### at some point.
-	### @return [Boolean]
 	def connected?
 		return @conn ? true : false
 	end
 
 
 	### Drop the existing connection and establish a new one.
-	### @return [Boolean]  +true+ if the connection was re-established
-	### @raise [RuntimeError]  if the re-connection failed
 	def reconnect
 		self.log.info "Reconnecting to %s..." % [ self.uri ]
 		@conn = self.connect
@@ -276,7 +261,6 @@ class Treequel::Directory
 
 
 	### Return the URI object that corresponds to the directory.
-	### @return [URI::LDAP]
 	def uri
 		uri_parts = {
 			:scheme => self.connect_type == :ssl ? 'ldaps' : 'ldap',
@@ -290,11 +274,6 @@ class Treequel::Directory
 
 
 	### Bind as the specified +user_dn+ and +password+.
-	### 
-	### @param [String, #dn] user_dn  the DN of the user to bind as
-	### @param [String] password      the password to bind with
-	### 
-	### @return [void]
 	def bind( user_dn, password )
 		user_dn = user_dn.dn if user_dn.respond_to?( :dn )
 
@@ -307,10 +286,6 @@ class Treequel::Directory
 
 	### Execute the provided +block+ after binding as +user_dn+ with the given +password+. After
 	### the block returns, the original binding (if any) will be restored.
-	### 
-	### @param (see #bind)
-	### 
-	### @return [void]
 	def bound_as( user_dn, password )
 		raise LocalJumpError, "no block given" unless block_given?
 		previous_bind_dn = @bound_user
@@ -324,7 +299,6 @@ class Treequel::Directory
 
 
 	### Returns +true+ if the directory's connection is already bound to the directory.
-	### @return [Boolean]
 	def bound?
 		return self.conn.bound?
 	end
@@ -332,7 +306,6 @@ class Treequel::Directory
 
 
 	### Ensure that the the receiver's connection is unbound.
-	### @return [void]
 	def unbind
 		if @conn.bound?
 			old_conn = @conn
@@ -343,7 +316,6 @@ class Treequel::Directory
 
 
 	### Return the RDN string to the given +dn+ from the base of the directory.
-	### @param [#to_s] dn  the DN of the entry
 	def rdn_to( dn )
 		base_re = Regexp.new( ',' + Regexp.quote(self.base_dn) + '$' )
 		return dn.to_s.sub( base_re, '' )
@@ -352,8 +324,6 @@ class Treequel::Directory
 
 	### Given a Treequel::Branch object, find its corresponding LDAP::Entry and return
 	### it.
-	### 
-	### @param [Treequel::Branch] branch  the branch to look up
 	def get_entry( branch )
 		self.log.debug "Looking up entry for %p" % [ branch.dn ]
 		return self.conn.search_ext2( branch.dn, SCOPE[:base], '(objectClass=*)' ).first
@@ -366,8 +336,6 @@ class Treequel::Directory
 	### Given a Treequel::Branch object, find its corresponding LDAP::Entry and return
 	### it with its operational attributes (http://tools.ietf.org/html/rfc4512#section-3.4)
 	### included.
-	### 
-	### @param [Treequel::Branch] branch  the branch to look up
 	def get_extended_entry( branch )
 		self.log.debug "Looking up entry (with operational attributes) for %p" % [ branch.dn ]
 		return self.conn.search_ext2( branch.dn, SCOPE[:base], '(objectClass=*)', %w[* +] ).first
@@ -388,51 +356,46 @@ class Treequel::Directory
 	end
 
 
-	### Perform a +scope+ search at +base+ using the specified +filter+.
-	### 
-	### @param [String, #dn] base  The base DN of the search.
-	### @param [Symbol] scope      The scope to use in the search; can be one of 
-	###                            +:onelevel+, +:base+, or +:subtree+. 
-	### @param [#to_s] filter      The search filter (RFC4515), either as a String 
-	###                            or something that stringifies to an filter string.
-	### @param [Hash] options      Search options.
+	### Perform a +scope+ search at +base+ using the specified +filter+. The scope can be one of 
+	### +:onelevel+, +:base+, or +:subtree+. The search filter should be a RFC4515-style filter 
+	### either as a String or something that stringifies to one (e.g., a Treequel::Filter). The
+	### available search options are:
 	### 
-	### @option options [Class] :results_class (Treequel::Branch)
+	### [+:results_class+]
 	###    The Class to use when wrapping results; if not specified, defaults to the class 
 	###    of +base+ if it responds to #new_from_entry, or the directory object's 
 	###    #results_class if it does not.
-	### @option options [Array<String, Symbol>] :selectattrs (['*'])
+	### [+:selectattrs+]
 	###    The attributes to return from the search; defaults to '*', which means to
 	###    return all non-operational attributes. Specifying '+' will cause the search
 	###    to include operational parameters as well.
-	### @option options [Boolean] :attrsonly (false)
+	### [+:attrsonly+]
 	###    If +true, the LDAP::Entry objects returned from the search won't have attribute values.
 	###    This has no real effect on Treequel::Branches, but is provided in case other 
-	###    +results_class+ classes need it.
-	### @option options [Array<LDAP::Control>] :server_controls (nil)
-	###    Any server controls that should be sent with the search.
-	### @option options [Array<LDAP::Control>] :client_controls (nil)
-	###    Any client controls that should be applied to the search.
-	### @option options [Fixnum] :timeout_s (0)
+	###    +results_class+ classes need it. Defaults to +false+.
+	### [+:server_controls+]
+	###    Any server controls that should be sent with the search as an Array of LDAP::Control
+	###    objects.
+	### [+:client_controls+]
+	###    Any client controls that should be applied to the search as an Array of LDAP::Control
+	###    objects.
+	### [+:timeout_s+]
 	###    The number of seconds (in addition to :timeout_us) after which the search request should 
 	###    be aborted.
-	### @option options [Fixnum] :timeout_us (0)
+	### [+:timeout_us+]
 	###    The number of microseconds (in addition to :timeout_s) after which the search request 
 	###    should be aborted.
-	### @option options [Fixnum] :limit
+	### [+:limit+]
 	###    The maximum number of results to return from the server.
-	### @option options [Array<String>] :sort_attribute
+	### [+:sort_attribute+]
 	###    An Array of String attribute names to sort by. 
-	### @option options [Proc] :sort_func
+	### [+:sort_func+]
 	###    A function that will provide sorting.
 	### 
-	### @return [Array] the array of results, each of which is wrapped in the
-	###    options[:results_class]. If a block is given, it acts like a filter:
-	###    the return vaule from the block is returned instead.
+	### Returns the array of results, each of which is wrapped in the options[:results_class]. 
+	### If a block is given, it acts like a filter: it's called once for each result, and the 
+	### array of return values from the block is returned instead.
 	### 
-	### @yield [branch]  an optional block, which will receive the results one at a time
-	### @yieldparam [Treequel::Branch] branch  the resulting entry, wrapped in 
-	###    the options[:results_class].
 	def search( base, scope=:subtree, filter='(objectClass=*)', options={} )
 		collectclass = nil
 
@@ -451,13 +414,13 @@ class Treequel::Directory
 			self.normalize_search_parameters( base, scope, filter, options )
 
 		# Unwrap the search options from the hash in the correct order
-		self.log.debug {
+		self.log.debug do
 			attrlist = SEARCH_PARAMETER_ORDER.inject([]) do |list, param|
 				list << "%s: %p" % [ param, searchopts[param] ]
 			end
 			"searching with base: %p, scope: %p, filter: %p, %s" %
 				[ base_dn, scope, filter, attrlist.join(', ') ]
-		}
+		end
 		parameters = searchopts.values_at( *SEARCH_PARAMETER_ORDER )
 
 		# Wrap each result in the class derived from the 'base' argument
@@ -515,11 +478,8 @@ class Treequel::Directory
 	end
 
 
-	### Create the entry for the given +branch+, setting its attributes to +newattrs+.
-	### @param [Treequel::Branch, #to_s] branch   the branch to create (or a DN string)
-	### @param [Hash, Array<LDAP::Mod>] newattrs  the attributes to create the entry with. This
-	###                                   can be either a Hash of attributes, or an Array of
-	###                                   LDAP::Mod objects.
+	### Create the entry for the given +branch+, setting its attributes to +newattrs+, which
+	### can be either a Hash of attributes, or an Array of LDAP::Mod objects.
 	def create( branch, newattrs={} )
 		newattrs = normalize_attributes( newattrs ) if newattrs.is_a?( Hash )
 		self.conn.add( branch.to_s, newattrs )
@@ -556,7 +516,6 @@ class Treequel::Directory
 	### argument(e.g., Proc, Method, Hash); the argument is the raw value String returned 
 	### from the LDAP entry, and it should return the converted value. Adding a mapping 
 	### with a nil +conversion+ effectively clears it.
-	### @see #convert_to_object
 	def add_attribute_conversion( oid, conversion=nil )
 		conversion = Proc.new if block_given?
 		@attribute_conversions[ oid ] = conversion
@@ -567,7 +526,6 @@ class Treequel::Directory
 	### responds to #[] with an object argument(e.g., Proc, Method, Hash); the argument is 
 	### the Ruby object that's being set as a value in an LDAP entry, and it should return the 
 	### raw LDAP string. Adding a mapping with a nil +conversion+ effectively clears it.
-	### @see #convert_to_attribute
 	def add_object_conversion( oid, conversion=nil )
 		conversion = Proc.new if block_given?
 		@object_conversions[ oid ] = conversion

data/lib/treequel/exceptions.rb

@@ -30,7 +30,6 @@ module Treequel
 	class ValidationFailed < Treequel::ModelError
 
 		### Create a new Treequel::ValidationFailed exception with the given +errors+.
-		### @param [Treequel::Model::Errors, String] errors  the validaton errors
 		def initialize( errors )
 			if errors.respond_to?( :full_messages )
 				@errors = errors
@@ -44,7 +43,7 @@ module Treequel
 		public
 		######
 
-		# @return [Treequel::Model::Errors] the validation errors
+		# the validation errors
 		attr_reader :errors
 
 	end # class ValidationFailed

data/lib/treequel/filter.rb

@@ -64,8 +64,6 @@ class Treequel::Filter
 
 
 		### Append operator: add the +other+ filter to the list.
-		### @param [Treequel::Filter] other  the new filter to add
-		### @return [Treequel::Filter::FilterList]  self (for chaining)
 		def <<( other )
 			@filters << other
 			return self
@@ -75,7 +73,7 @@ class Treequel::Filter
 
 
 	### An abstract class for filter components.
-	### @abstract Subclass and override {#to_s} to implement a custom Component class.
+	### Subclass and override #to_s to implement a custom Component class.
 	class Component
 		include Treequel::Loggable
 
@@ -150,7 +148,6 @@ class Treequel::Filter
 		end
 
 		### Add an additional filter to the list of requirements
-		### @param [Treequel::Filter] filter  the new requirement
 		def add_requirement( filter )
 			@filterlist << filter
 		end
@@ -176,7 +173,6 @@ class Treequel::Filter
 		end
 
 		### Add an additional filter to the list of alternatives
-		### @param [Treequel::Filter] filter  the new alternative
 		def add_alternation( filter )
 			@filterlist << filter
 		end
@@ -712,7 +708,7 @@ class Treequel::Filter
 	end
 
 
-	### AND two filters together
+	### Return a new Filter that is the AND filter of the receiver with +other_filter+.
 	def &( other_filter )
 		return other_filter if self.promiscuous?
 		return self.dup if other_filter.promiscuous?
@@ -721,8 +717,7 @@ class Treequel::Filter
 	alias_method :+, :&
 
 
-	### OR two filters together
-	### @param [Treequel::Filter] other_filter
+	### Return a new Filter that is the OR filter of the receiver with +other_filter+.
 	def |( other_filter )
 		return other_filter if self.promiscuous?
 		return self.dup if other_filter.promiscuous?

data/lib/treequel/mixins.rb

@@ -22,7 +22,6 @@ module Treequel
 		### Define the given +delegated_methods+ as delegators to the like-named method
 		### of the return value of the +delegate_method+.
 		### 
-		### @example
 		###    class MyClass
 		###      extend Treequel::Delegation
 		###      
@@ -122,10 +121,8 @@ module Treequel
 		module_function
 		###############
 
-		### Normalize the given key
-		### @param [String] key  the key to normalize
-		### @return a downcased Symbol stripped of any invalid characters, and 
-		###         with '-' characters converted to '_'.
+		### Normalize the given key, returning a downcased Symbol stripped of any invalid 
+		### characters, and with '-' characters converted to '_'.
 		def normalize_key( key )
 			return key if key.to_s =~ Treequel::Constants::Patterns::NUMERICOID
 			return key.to_s.downcase.
@@ -135,7 +132,6 @@ module Treequel
 		end
 
 		### Return a copy of +hash+ with all of its keys normalized by #normalize_key.
-		### @param [Hash] hash  the Hash to normalize
 		def normalize_hash( hash )
 			hash = hash.dup
 			hash.keys.each do |key|
@@ -155,7 +151,6 @@ module Treequel
 
 		### A logging proxy class that wraps calls to the logger into calls that include
 		### the name of the calling class.
-		### @private
 		class ClassNameProxy
 
 			### Create a new proxy for the given +klass+.

data/lib/treequel/model/errors.rb

@@ -48,22 +48,19 @@ class Treequel::Model::Errors < ::Hash
 
 
 	### Adds an error for the given +subject+.
-	### @param [Symbol, #to_sym] subject    the subject of the error
-	### @param [String] message             the description of the error condition
 	def add( subject, message )
 		self[ subject ] << message
 	end
 
 
 	### Get the number of errors that have been registered.
-	### @Return [Fixnum]  the number of errors
 	def count
 		return self.values.inject( 0 ) {|num, val| num + val.length }
 	end
 
 
     ### Get an Array of messages describing errors which have occurred.
-    ### @example
+    ### 
     ###   errors.full_messages
     ###   # => ['cn is not valid',
     ###   #     'uid is not at least 2 letters']