treequel 1.0.0

data/lib/treequel/mixins.rb

@@ -0,0 +1,325 @@
+#!/usr/bin/ruby
+
+require 'rbconfig'
+require 'erb'
+require 'etc'
+require 'logger'
+
+require 'treequel'
+
+
+#--
+# A collection of mixins shared between Treequel classes. Stolen mostly from ThingFish.
+#
+module Treequel # :nodoc:
+
+	# A collection of various delegation code-generators that can be used to define
+	# delegation through other methods, to instance variables, etc.
+	module Delegation
+
+		#######
+		private
+		#######
+
+		### Make the body of a delegator method that will delegate to the +name+ method
+		### of the object returned by the +delegate+ method.
+		def make_method_delegator( delegate, name )
+			error_frame = caller(4)[0]
+			file, line = error_frame.split( ':', 2 )
+
+			# Ruby can't parse obj.method=(*args), so we have to special-case setters...
+			if name.to_s =~ /(\w+)=$/
+				name = $1
+				code = <<-END_CODE
+				lambda {|*args| self.#{delegate}.#{name} = *args }
+				END_CODE
+			else
+				code = <<-END_CODE
+				lambda {|*args| self.#{delegate}.#{name}(*args) }
+				END_CODE
+			end
+
+			return eval( code, nil, file, line.to_i )
+		end
+
+
+		### Make the body of a delegator method that will delegate calls to the +name+
+		### method to the given +ivar+.
+		def make_ivar_delegator( ivar, name )
+			error_frame = caller(4)[0]
+			file, line = error_frame.split( ':', 2 )
+
+			# Ruby can't parse obj.method=(*args), so we have to special-case setters...
+			if name.to_s =~ /(\w+)=$/
+				name = $1
+				code = <<-END_CODE
+				lambda {|*args| #{ivar}.#{name} = *args }
+				END_CODE
+			else
+				code = <<-END_CODE
+				lambda {|*args| #{ivar}.#{name}(*args) }
+				END_CODE
+			end
+
+			return eval( code, nil, file, line.to_i )
+		end
+
+
+		###############
+		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
+
+
+	end # module Delegation
+
+
+	# 
+	# Add logging to a Treequel class. Including classes get #log and #log_debug methods.
+	# 
+	# == Version
+	#
+	#  $Id$
+	#
+	# == Authors
+	#
+	# * Michael Granger <ged@FaerieMUD.org>
+	#
+	# :include: LICENSE
+	#
+	# --
+	#
+	# Please see the file LICENSE in the 'docs' directory for licensing details.
+	#
+	module Loggable
+
+		LEVEL = {
+			:debug => Logger::DEBUG,
+			:info  => Logger::INFO,
+			:warn  => Logger::WARN,
+			:error => Logger::ERROR,
+			:fatal => Logger::FATAL,
+		  }
+
+		### A logging proxy class that wraps calls to the logger into calls that include
+		### the name of the calling class.
+		class ClassNameProxy # :nodoc:
+
+			### Create a new proxy for the given +klass+.
+			def initialize( klass, force_debug=false )
+				@classname   = klass.name
+				@force_debug = force_debug
+			end
+
+			### Delegate calls the global logger with the class name as the 'progname' 
+			### argument.
+			def method_missing( sym, msg=nil, &block )
+				return super unless LEVEL.key?( sym )
+				sym = :debug if @force_debug
+				Treequel.logger.add( LEVEL[sym], msg, @classname, &block )
+			end
+		end # ClassNameProxy
+
+		#########
+		protected
+		#########
+
+		### Copy constructor -- clear the original's log proxy.
+		def initialize_copy( original )
+			@log_proxy = @log_debug_proxy = nil
+			super
+		end
+
+		### Return the proxied logger.
+		def log
+			@log_proxy ||= ClassNameProxy.new( self.class )
+		end
+
+		### Return a proxied "debug" logger that ignores other level specification.
+		def log_debug
+			@log_debug_proxy ||= ClassNameProxy.new( self.class, true )
+		end
+	end # module Loggable
+
+
+	### A collection of utilities for working with Hashes.
+	module HashUtilities
+
+		###############
+		module_function
+		###############
+
+		### Return a version of the given +hash+ with its keys transformed
+		### into Strings from whatever they were before.
+		def stringify_keys( hash )
+			newhash = {}
+
+			hash.each do |key,val|
+				if val.is_a?( Hash )
+					newhash[ key.to_s ] = stringify_keys( val )
+				else
+					newhash[ key.to_s ] = val
+				end
+			end
+
+			return newhash
+		end
+
+
+		### Return a duplicate of the given +hash+ with its identifier-like keys
+		### transformed into symbols from whatever they were before.
+		def symbolify_keys( hash )
+			newhash = {}
+
+			hash.each do |key,val|
+				keysym = key.to_s.dup.untaint.to_sym
+
+				if val.is_a?( Hash )
+					newhash[ keysym ] = symbolify_keys( val )
+				else
+					newhash[ keysym ] = val
+				end
+			end
+
+			return newhash
+		end
+		alias_method :internify_keys, :symbolify_keys
+
+
+		# Recursive hash-merge function
+		def merge_recursively( key, oldval, newval )
+			case oldval
+			when Hash
+				case newval
+				when Hash
+					oldval.merge( newval, &method(:merge_recursively) )
+				else
+					newval
+				end
+
+			when Array
+				case newval
+				when Array
+					oldval | newval
+				else
+					newval
+				end
+
+			else
+				newval
+			end
+		end
+
+	end # HashUtilities
+
+
+	### A collection of utilities for working with Arrays.
+	module ArrayUtilities
+
+		###############
+		module_function
+		###############
+
+		### Return a version of the given +array+ with any Symbols contained in it turned into
+		### Strings.
+		def stringify_array( array )
+			return array.collect do |item|
+				case item
+				when Symbol
+					item.to_s
+				when Array
+					stringify_array( item )
+				else
+					item
+				end
+			end
+		end
+
+
+		### Return a version of the given +array+ with any Strings contained in it turned into
+		### Symbols.
+		def symbolify_array( array )
+			return array.collect do |item|
+				case item
+				when String
+					item.to_sym
+				when Array
+					symbolify_array( item )
+				else
+					item
+				end
+			end
+		end
+
+	end # module ArrayUtilities
+
+
+	### A collection of attribute declaration functions
+	module AttributeDeclarations
+
+		###############
+		module_function
+		###############
+
+		### Declare predicate accessors for the attributes associated with the specified
+		### +symbols+.
+		def predicate_attr( *symbols )
+			symbols.each do |attrname|
+				define_method( "#{attrname}?" ) do
+					instance_variable_get( "@#{attrname}" ) ? true : false
+				end
+				define_method( "#{attrname}=" ) do |newval|
+					instance_variable_set( "@#{attrname}", newval ? true : false )
+				end
+				alias_method "is_#{attrname}?", "#{attrname}?"
+			end
+		end
+
+	end # module AttributeDeclarations
+
+end # module Treequel
+
+# vim: set nosta noet ts=4 sw=4:
+

data/lib/treequel/schema.rb

@@ -0,0 +1,245 @@
+#!/usr/bin/env ruby
+
+require 'ldap'
+require 'ldap/schema'
+
+require 'treequel'
+require 'treequel/constants'
+require 'treequel/mixins'
+
+
+# This is an object that is used to parse and query a directory's schema
+# 
+# == 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::Schema
+	include Treequel::Loggable,
+	        Treequel::Constants::Patterns
+
+	require 'treequel/schema/objectclass'
+	require 'treequel/schema/attributetype'
+	require 'treequel/schema/matchingrule'
+	require 'treequel/schema/matchingruleuse'
+	require 'treequel/schema/ldapsyntax'
+
+
+	#################################################################
+	###	C L A S S   M E T H O D S
+	#################################################################
+
+	### Parse the given +oidstring+ into an Array of OIDs, with Strings for numeric OIDs and
+	### Symbols for aliases.
+	def self::parse_oids( oidstring )
+		return [] unless oidstring
+
+		unless /^ #{OIDS} $/x.match( oidstring.strip )
+			raise Treequel::ParseError, "couldn't find an OIDLIST in %p" % [ oidstring ]
+		end
+
+		oids = $MATCH
+		# Treequel.logger.debug "  found OIDs: %p" % [ oids ]
+
+		# If it's an OIDLIST, strip off leading and trailing parens and whitespace, then split 
+		# on ' $ ' and parse each OID
+		if oids.include?( '$' )
+			parse_oid = self.method( :parse_oid )
+			return $MATCH[1..-2].strip.split( /#{WSP} #{DOLLAR} #{WSP}/x ).collect( &parse_oid )
+
+		else
+			return [ self.parse_oid(oids) ]
+
+		end
+
+	end
+
+
+	### Parse a single OID into either a numeric OID string or a Symbol.
+	def self::parse_oid( oidstring )
+		if oidstring =~ NUMERICOID
+			return oidstring.untaint
+		else
+			return oidstring.untaint.to_sym
+		end
+	end
+
+
+	### Parse the given short +names+ string (a 'qdescrs' in the BNF) into an Array of zero or
+	### more Strings.
+	def self::parse_names( names )
+		# Treequel.logger.debug "  parsing NAME attribute from: %p" % [ names ]
+
+		# Unspecified
+		if names.nil?
+			# Treequel.logger.debug "    no NAME attribute"
+			return []
+
+		# Multi-value
+		elsif names =~ /#{LPAREN} #{WSP} (#{QDESCRLIST}) #{WSP} #{RPAREN}/x
+			# Treequel.logger.debug "    parsing a NAME list from %p" % [ $1 ]
+			return $1.scan( QDESCR ).collect {|qd| qd[1..-2].untaint.to_sym }
+
+		# Single-value
+		else
+			# Return the name without the quotes
+			# Treequel.logger.debug "    dequoting a single NAME"
+			return [ names[1..-2].untaint.to_sym ]
+		end
+	end
+
+
+	### Return a new string which is +desc+ with quotes stripped and any escaped characters 
+	### un-escaped.
+	def self::unquote_desc( desc )
+		return nil if desc.nil?
+		return desc.gsub( QQ, "'" ).gsub( QS, '\\' )[ 1..-2 ]
+	end
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Create a new Treequel::Schema from the specified +hash+. The +hash+ should be of the same
+	### form as the one returned by LDAP::Conn.schema, i.e., a Hash of Arrays associated with the
+	### keys "objectClasses", "ldapSyntaxes", "matchingRuleUse", "attributeTypes", and 
+	### "matchingRules".
+	def initialize( hash )
+		@object_classes     = self.parse_objectclasses( hash['objectClasses'] )
+		@attribute_types    = self.parse_attribute_types( hash['attributeTypes'] )
+		@ldap_syntaxes      = self.parse_ldap_syntaxes( hash['ldapSyntaxes'] )
+		@matching_rules     = self.parse_matching_rules( hash['matchingRules'] )
+		@matching_rule_uses = self.parse_matching_rule_uses( hash['matchingRuleUse'] )
+	end
+
+
+	######
+	public
+	######
+
+	# The Hash of Treequel::Schema::ObjectClass objects, keyed by OID and any associated NAME 
+	# attributes (as Symbols), that describes the objectClasses in the directory's schema.
+	attr_reader :object_classes
+
+	# The hash of Treequel::Schema::AttributeType objects, keyed by OID and any associated NAME
+	# attributes (as Symbols), that describe the attributeTypes in the directory's schema.
+	attr_reader :attribute_types
+
+	# The hash of Treequel::Schema::LDAPSyntax objects, keyed by OID, that describe the 
+	# syntaxes in the directory's schema.
+	attr_reader :ldap_syntaxes
+
+	# The hash of Treequel::Schema::MatchingRule objects, keyed by OID and any associated NAME
+	# attributes (as Symbols), that describe the matchingRules int he directory's schema.
+	attr_reader :matching_rules
+
+	# The hash of Treequel::Schema::MatchingRuleUse objects, keyed by OID and any associated NAME
+	# attributes (as Symbols), that describe the attributes to which a matchingRule can be applied.
+	attr_reader :matching_rule_uses
+
+
+	### Return a human-readable representation of the object suitable for debugging.
+	def inspect
+		ivar_descs = self.instance_variables.sort.collect do |ivar|
+			len = self.instance_variable_get( ivar ).length
+			"%d %s" % [ len, ivar.gsub(/_/, ' ')[1..-1] ]
+		end
+		return %{#<%s:0x%0x %s>} % [
+			self.class.name,
+			self.object_id / 2,
+			ivar_descs.join(', '),
+		]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Parse the given objectClass +descriptions+ into Treequel::Schema::ObjectClass objects, and
+	### 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|
+			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 }
+
+			hash
+		end
+	end
+
+
+	### Parse the given attributeType +descriptions+ into Treequel::Schema::AttributeType objects
+	### 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|
+			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 }
+
+			hash
+		end
+	end
+
+
+	### 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|
+			syntax = Treequel::Schema::LDAPSyntax.parse( self, desc ) or
+				raise Treequel::Error, "couldn't create an LDAPSyntax from %p" % [ desc ]
+
+			hash[ syntax.oid ] = syntax
+			hash
+		end
+	end
+
+
+	### Parse the given matchingRule +descriptions+ into Treequel::Schema::MatchingRule objects
+	### 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|
+			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 }
+
+			hash
+		end
+	end
+
+
+	### Parse the given matchingRuleUse +descriptions+ into Treequel::Schema::MatchingRuleUse objects
+	### 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|
+			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 }
+
+			hash
+		end
+	end
+
+
+end # class Treequel::Schema
+