treequel 1.0.1 → 1.0.4

data/lib/treequel/exceptions.rb

@@ -3,18 +3,6 @@
 require 'treequel'
 
 
-# A collection of exceptions for Treequel.
-# 
-# == Authors
-# 
-# * Michael Granger <ged@FaerieMUD.org>
-# 
-# :include: LICENSE
-#
-#--
-#
-# Please see the file LICENSE in the base directory for licensing details.
-#
 module Treequel
 
 	### The base Treequel exception type
@@ -27,6 +15,17 @@ module Treequel
 	### arguments given to Treequel::Filter.new
 	class ExpressionError < Treequel::Error; end
 
+	### Generic exception type for Controls.
+	class ControlError < Treequel::Error; end
+
+	### Exception type for a requested Control type that is nonexistent or
+	### unsupported on the current server.
+	class UnsupportedControl < Treequel::ControlError; end
+
+	### Exception raised from Treequel::Model due to misconfiguration or
+	### other problem.
+	class ModelError < Treequel::Error; end
+
 end # module Treequel
 
 

data/lib/treequel/filter.rb

@@ -36,18 +36,6 @@ require 'treequel/sequel_integration'
 #   matchingrule = MatchingRuleId from Section 4.1.9 of [1]
 #   value      = AttributeValue from Section 4.1.6 of [1]
 # 
-# 
-# == 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::Filter
 	include Treequel::Loggable,
 	        Treequel::Constants::Patterns
@@ -78,6 +66,7 @@ class Treequel::Filter
 
 
 	### An abstract class for filter components.
+	### @abstract Subclass and override {#to_s} to implement a custom Component class.
 	class Component
 		include Treequel::Loggable
 

data/lib/treequel/mixins.rb

@@ -6,17 +6,64 @@ require 'etc'
 require 'logger'
 
 require 'treequel'
+require 'treequel/constants'
 
 
-#--
-# A collection of mixins shared between Treequel classes. Stolen mostly from ThingFish.
-#
-module Treequel # :nodoc:
+module Treequel
 
 	# A collection of various delegation code-generators that can be used to define
 	# delegation through other methods, to instance variables, etc.
 	module Delegation
 
+		###############
+		module_function
+		###############
+
+		### 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
+		###      
+		###      # Delegate the #bound?, #err, and #result2error methods to the connection
+		###      # object returned by the #connection method. This allows the connection
+		###      # to still be loaded on demand/overridden/etc.
+		###      def_method_delegators :connection, :bound?, :err, :result2error
+		###      
+		###      def connection
+		###        @connection ||= self.connect
+		###      end
+		###    end
+		### 
+		def def_method_delegators( delegate_method, *delegated_methods )
+			delegated_methods.each do |name|
+				body = make_method_delegator( delegate_method, name )
+				define_method( name, &body )
+			end
+		end
+
+
+		### Define the given +delegated_methods+ as delegators to the like-named method
+		### of the specified +ivar+. This is pretty much identical with how 'Forwardable'
+		### from the stdlib does delegation, but it's reimplemented here for consistency.
+		### 
+		###    class MyClass
+		###      extend Treequel::Delegation
+		###      
+		###      # Delegate the #each method to the @collection ivar
+		###      def_ivar_delegators :@collection, :each
+		###      
+		###    end
+		### 
+		def def_ivar_delegators( ivar, *delegated_methods )
+			delegated_methods.each do |name|
+				body = make_ivar_delegator( ivar, name )
+				define_method( name, &body )
+			end
+		end
+
+
 		#######
 		private
 		#######
@@ -64,59 +111,46 @@ module Treequel # :nodoc:
 			return eval( code, nil, file, line.to_i )
 		end
 
+	end # module Delegation
+
+
+	# A collection of key-normalization functions for various artifacts in LDAP like
+	# attribute names, objectclass OIDs, etc.
+	module Normalization
 
 		###############
 		module_function
 		###############
 
-		### 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
-		###      
-		###      # Delegate the #bound?, #err, and #result2error methods to the connection
-		###      # object returned by the #connection method. This allows the connection
-		###      # to still be loaded on demand/overridden/etc.
-		###      def_method_delegators :connection, :bound?, :err, :result2error
-		###      
-		###      def connection
-		###        @connection ||= self.connect
-		###      end
-		###    end
-		### 
-		def def_method_delegators( delegate_method, *delegated_methods )
-			delegated_methods.each do |name|
-				body = make_method_delegator( delegate_method, name )
-				define_method( name, &body )
-			end
+		### 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 '_'.
+		def normalize_key( key )
+			return key if key.to_s =~ Treequel::Constants::Patterns::NUMERICOID
+			return key.to_s.downcase.
+				gsub( /[^[:alnum:]\-_]/, '' ).
+				gsub( '-', '_' ).
+				to_sym
 		end
 
-
-		### Define the given +delegated_methods+ as delegators to the like-named method
-		### of the specified +ivar+. This is pretty much identical with how 'Forwardable'
-		### from the stdlib does delegation, but it's reimplemented here for consistency.
-		### 
-		###    class MyClass
-		###      extend Treequel::Delegation
-		###      
-		###      # Delegate the #each method to the @collection ivar
-		###      def_ivar_delegators :@collection, :each
-		###      
-		###    end
-		### 
-		def def_ivar_delegators( ivar, *delegated_methods )
-			delegated_methods.each do |name|
-				body = make_ivar_delegator( ivar, name )
-				define_method( name, &body )
+		### 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|
+				nkey = normalize_key( key )
+				hash[ nkey ] = hash.delete( key ) if key != nkey
 			end
+
+			return hash
 		end
 
 
-	end # module Delegation
+	end # Normalization
 
 
-	# Add logging to a Treequel class. Including classes get #log and #log_debug methods.
+	### Add logging to a Treequel class. Including classes get #log and #log_debug methods.
 	module Loggable
 
 		LEVEL = {
@@ -129,7 +163,8 @@ module Treequel # :nodoc:
 
 		### A logging proxy class that wraps calls to the logger into calls that include
 		### the name of the calling class.
-		class ClassNameProxy # :nodoc:
+		### @private
+		class ClassNameProxy
 
 			### Create a new proxy for the given +klass+.
 			def initialize( klass, force_debug=false )
@@ -292,7 +327,8 @@ module Treequel # :nodoc:
 		def predicate_attr( *symbols )
 			symbols.each do |attrname|
 				define_method( "#{attrname}?" ) do
-					instance_variable_get( "@#{attrname}" ) ? true : false
+					instance_variable_defined?( "@#{attrname}" ) &&
+						instance_variable_get( "@#{attrname}" ) ? true : false
 				end
 				define_method( "#{attrname}=" ) do |newval|
 					instance_variable_set( "@#{attrname}", newval ? true : false )
@@ -341,7 +377,7 @@ module Treequel # :nodoc:
 			return '' unless /(?:vt10[03]|xterm(?:-color)?|linux|screen)/i =~ ENV['TERM']
 			attributes = ANSI_ATTRIBUTES.values_at( *attributes ).compact.join(';')
 
-			if attributes.empty? 
+			if attributes.empty?
 				return ''
 			else
 				return "\e[%sm" % attributes

data/lib/treequel/monkeypatches.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+
+require 'ldap'
+require 'ldap/control'
+
+require 'treequel'
+
+### Extensions to LDAP::Control to make them grok ==.
+module Treequel::LDAPControlExtensions
+
+	### Returns +true+ if the +other+ LDAP::Control is equivalent to the receiver.
+	def ==( other )
+		return ( other.class == self.class ) &&
+			other.oid == self.oid &&
+			other.value == self.value &&
+			other.iscritical == self.iscritical
+	end
+
+end # module Treequel::LDAPControlExtensions
+
+
+# Include Treequel-specific extensions as a mixin.
+# @private
+class LDAP::Control
+	include Treequel::LDAPControlExtensions
+end
+
+
+

data/lib/treequel/schema.rb

@@ -25,6 +25,7 @@ class Treequel::Schema
 	include Treequel::Loggable,
 	        Treequel::Constants::Patterns
 
+	require 'treequel/schema/table'
 	require 'treequel/schema/objectclass'
 	require 'treequel/schema/attributetype'
 	require 'treequel/schema/matchingrule'
@@ -168,14 +169,14 @@ class Treequel::Schema
 	### return them as a Hash keyed both by numeric OID and by each of its NAME attributes (if it
 	### has any).
 	def parse_objectclasses( descriptions )
-		return descriptions.inject( {} ) do |hash, desc|
+		return descriptions.inject( Treequel::Schema::Table.new ) do |table, desc|
 			oc = Treequel::Schema::ObjectClass.parse( self, desc ) or
 				raise Treequel::Error, "couldn't create an objectClass from %p" % [ desc ]
 
-			hash[ oc.oid ] = oc
-			oc.names.inject( hash ) {|h, name| h[name] = oc; h }
+			table[ oc.oid ] = oc
+			oc.names.inject( table ) {|h, name| h[name] = oc; h }
 
-			hash
+			table
 		end
 	end
 
@@ -184,14 +185,14 @@ class Treequel::Schema
 	### and return them as a Hash keyed both by numeric OID and by each of its NAME attributes 
 	### (if it has any).
 	def parse_attribute_types( descriptions )
-		return descriptions.inject( {} ) do |hash, desc|
+		return descriptions.inject( Treequel::Schema::Table.new ) do |table, desc|
 			attrtype = Treequel::Schema::AttributeType.parse( self, desc ) or
 				raise Treequel::Error, "couldn't create an attributeType from %p" % [ desc ]
 
-			hash[ attrtype.oid ] = attrtype
-			attrtype.names.inject( hash ) {|h, name| h[name] = attrtype; h }
+			table[ attrtype.oid ] = attrtype
+			attrtype.names.inject( table ) {|h, name| h[name] = attrtype; h }
 
-			hash
+			table
 		end
 	end
 
@@ -199,12 +200,13 @@ class Treequel::Schema
 	### Parse the given LDAP syntax +descriptions+ into Treequel::Schema::LDAPSyntax objects and
 	### return them as a Hash keyed by numeric OID.
 	def parse_ldap_syntaxes( descriptions )
-		return descriptions.inject( {} ) do |hash, desc|
+		descriptions ||= []
+		return descriptions.inject( Treequel::Schema::Table.new ) do |table, desc|
 			syntax = Treequel::Schema::LDAPSyntax.parse( self, desc ) or
 				raise Treequel::Error, "couldn't create an LDAPSyntax from %p" % [ desc ]
 
-			hash[ syntax.oid ] = syntax
-			hash
+			table[ syntax.oid ] = syntax
+			table
 		end
 	end
 
@@ -213,14 +215,15 @@ class Treequel::Schema
 	### and return them as a Hash keyed both by numeric OID and by each of its NAME attributes 
 	### (if it has any).
 	def parse_matching_rules( descriptions )
-		return descriptions.inject( {} ) do |hash, desc|
+		descriptions ||= []
+		return descriptions.inject( Treequel::Schema::Table.new ) do |table, desc|
 			rule = Treequel::Schema::MatchingRule.parse( self, desc ) or
 				raise Treequel::Error, "couldn't create an matchingRule from %p" % [ desc ]
 
-			hash[ rule.oid ] = rule
-			rule.names.inject( hash ) {|h, name| h[name] = rule; h }
+			table[ rule.oid ] = rule
+			rule.names.inject( table ) {|h, name| h[name] = rule; h }
 
-			hash
+			table
 		end
 	end
 
@@ -229,14 +232,15 @@ class Treequel::Schema
 	### and return them as a Hash keyed both by numeric OID and by each of its NAME attributes 
 	### (if it has any).
 	def parse_matching_rule_uses( descriptions )
-		return descriptions.inject( {} ) do |hash, desc|
+		descriptions ||= []
+		return descriptions.inject( Treequel::Schema::Table.new ) do |table, desc|
 			ruleuse = Treequel::Schema::MatchingRuleUse.parse( self, desc ) or
 				raise Treequel::Error, "couldn't create an matchingRuleUse from %p" % [ desc ]
 
-			hash[ ruleuse.oid ] = ruleuse
-			ruleuse.names.inject( hash ) {|h, name| h[name] = ruleuse; h }
+			table[ ruleuse.oid ] = ruleuse
+			ruleuse.names.inject( table ) {|h, name| h[name] = ruleuse; h }
 
-			hash
+			table
 		end
 	end
 

data/lib/treequel/schema/attributetype.rb

@@ -23,6 +23,7 @@ require 'treequel/exceptions'
 #
 class Treequel::Schema::AttributeType
 	include Treequel::Loggable,
+	        Treequel::Normalization,
 	        Treequel::Constants::Patterns
 
 	extend Treequel::AttributeDeclarations
@@ -157,6 +158,20 @@ class Treequel::Schema::AttributeType
 	end
 
 
+	### Return the attributeType's names after normalizing them.
+	def normalized_names
+		return self.names.collect {|name| normalize_key(name) }
+	end
+
+
+	### Returns +true+ if the specified +name+ is one of the attribute's names
+	### after normalization of both.
+	def valid_name?( name )
+		normname = normalize_key( name )
+		return self.normalized_names.include?( normname )
+	end
+
+
 	### Return the Treequel::Schema::AttributeType instance that corresponds to 
 	### the receiver's superior type. If the attributeType doesn't have a SUP
 	### attribute, this method returns +nil+.
@@ -236,14 +251,29 @@ class Treequel::Schema::AttributeType
 	protected
 	#########
 
+	OID_SPLIT_PATTERN = /
+		^
+		#{SQUOTE}?
+		(#{OID})					# OID = $1
+		#{SQUOTE}?
+		(?:
+			#{LCURLY}
+			(#{LEN})				# Length = $2
+			#{RCURLY}
+		)?$
+	/x
+
 	### Split a numeric OID with an optional length qualifier into a numeric OID and length. If
 	### no length qualifier is present, it will be nil.
+	### NOTE: Modified to support ActiveDirectory schemas, which have both quoted numeric OIDs 
+	### and descriptors as syntax OIDs.
 	def split_syntax_oid( noidlen )
-		unless noidlen =~ /^(#{NUMERICOID}) (?:#{LCURLY} (#{LEN}) #{RCURLY})?$/x
-			raise Treequel::ParseError, "invalid numeric syntax OID with length: %p" % [ noidlen ]
+		unless noidlen =~ OID_SPLIT_PATTERN
+			raise Treequel::ParseError, "invalid syntax OID: %p" % [ noidlen ]
 		end
 
-		oid, len = $1, $2
+		oidstring, len = $1, $2
+		oid = Treequel::Schema.parse_oid( oidstring )
 
 		return oid, len ? Integer(len) : nil
 	end

data/lib/treequel/schema/ldapsyntax.rb

@@ -9,17 +9,6 @@ require 'treequel/exceptions'
 
 
 # This is a class for representing ldapSyntax declarations in a Treequel::Schema.
-# 
-# == Authors
-# 
-# * Michael Granger <ged@FaerieMUD.org>
-# 
-# :include: LICENSE
-#
-#--
-#
-# Please see the file LICENSE in the base directory for licensing details.
-#
 class Treequel::Schema::LDAPSyntax
 	include Treequel::Loggable,
 	        Treequel::Constants::Patterns