treequel 1.6.0 → 1.7.0

data/lib/treequel.rb

@@ -13,8 +13,7 @@ require 'uri/ldap'
 
 ### Add an LDAPS URI type if none exists (ruby pre 1.8.7)
 unless URI.const_defined?( :LDAPS )
-	# @private
-	module URI
+	module URI # :nodoc:
 		class LDAPS < LDAP
 			DEFAULT_PORT = 636
 		end
@@ -23,40 +22,14 @@ unless URI.const_defined?( :LDAPS )
 end
 
 
-# A library for interacting with LDAP modelled after Sequel.
-#
-# @version 1.5.3
-# 
-# @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.
-# 
+# A library for interacting with LDAP modelled after Sequel[http://sequel.rubyforge.org/].
 module Treequel
 
 	# Library version
-	VERSION = '1.6.0'
+	VERSION = '1.7.0'
 
 	# VCS revision
-	REVISION = %q$Revision: 2639d7f96151 $
+	REVISION = %q$Revision: c5b83ddad969 $
 
 	# Common paths for ldap.conf
 	COMMON_LDAP_CONF_PATHS = %w[
@@ -79,7 +52,18 @@ module Treequel
 	include Treequel::Constants
 
 
-	### Logging
+	### Get the Treequel version.
+	def self::version_string( include_buildnum=false )
+		vstring = "%s %s" % [ self.name, VERSION ]
+		vstring << " (build %s)" % [ REVISION[/: ([[:xdigit:]]+)/, 1] || '0' ] if include_buildnum
+		return vstring
+	end
+
+
+	#
+	# :section: Logging
+	#
+
 	# Log levels
 	LOG_LEVELS = {
 		'debug' => Logger::DEBUG,
@@ -100,14 +84,13 @@ module Treequel
 
 
 	class << self
-		# @return [Logger::Formatter] the log formatter that will be used when the logging 
-		#    subsystem is reset
+		# The log formatter that will be used when the logging subsystem is reset
 		attr_accessor :default_log_formatter
 
-		# @return [Logger] the logger that will be used when the logging subsystem is reset
+		# The logger that will be used when the logging subsystem is reset
 		attr_accessor :default_logger
 
-		# @return [Logger] the logger that's currently in effect
+		# The logger that's currently in effect
 		attr_accessor :logger
 		alias_method :log, :logger
 		alias_method :log=, :logger=
@@ -115,7 +98,6 @@ 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
@@ -130,30 +112,30 @@ module Treequel
 	end
 
 
-	### 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[/: ([[: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
+	#
+	# :section:
+	#
+
+	### :call-seq:
+	###    Treequel.directory( uri )
+	###    Treequel.directory( options )
+	###
+	### Create a Treequel::Directory object, either from an LDAP URL or a Hash of connection 
+	### options. The valid options are:
+	###
+	### [:host]
+	###   The LDAP host to connect to; default is 'localhost'.
+	### [:port]
+	###   The port number to connect to; defaults to 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.
+	### [:bind_dn]
+	###   The DN of the user to bind as.
+	### [:pass]
+	###   The password to use when binding.
+	###
 	def self::directory( *args )
 		options = {}
 
@@ -173,11 +155,9 @@ module Treequel
 
 
 	### 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 
+	### 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."
@@ -195,8 +175,6 @@ module Treequel
 
 	### 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
@@ -224,8 +202,6 @@ module Treequel
 
 	### 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.
@@ -255,10 +231,8 @@ module Treequel
 	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}.
+	### Read the ldap.conf-style configuration from +configfile+ and return it as a Hash suitable
+	### for passing to Treequel::Directory.new.
 	def self::read_opts_from_config( configfile )
 		Treequel.log.info "Reading config options from %s..." % [ configfile ]
 		opts = {}
@@ -329,9 +303,8 @@ module Treequel
 	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}.
+	### Read OpenLDAP-style connection options from ENV and return them as a Hash suitable for
+	### passing to Treequel::Directory.new.
 	def self::read_opts_from_environment
 		opts = {}
 

data/spec/treequel/branchset_spec.rb

@@ -213,6 +213,16 @@ describe Treequel::Branchset do
 			@branchset.first.should == :first_matching_branch
 		end
 
+		it "performs a search using the default filter, scope, and a limit of 5 when the first " +
+		   "five records are requested" do
+			params = @params.merge( :limit => 5 )
+			@branch.should_receive( :search ).
+				with( Treequel::Branchset::DEFAULT_SCOPE, @branchset.filter, params ).
+				and_return( [:branch1, :branch2, :branch3, :branch4, :branch5] )
+
+			@branchset.first( 5 ).should == [:branch1, :branch2, :branch3, :branch4, :branch5]
+		end
+
 		it "creates a new branchset cloned from itself with the specified filter" do
 			newset = @branchset.filter( :clothing, 'pants' )
 			newset.filter_string.should == '(clothing=pants)'
@@ -236,6 +246,19 @@ describe Treequel::Branchset do
 			}.to raise_exception( Treequel::ExpressionError, /no existing filter/i )
 		end
 
+
+		#
+		# not
+		#
+		it "can create a new branchset cloned from itself with a NOT clause added to an " +
+		   "existing filter" do
+			pantset = @branchset.filter( :clothing => 'pants' )
+			notsmallset = pantset.not( :size => 'small' )
+
+			notsmallset.filter_string.should == '(&(clothing=pants)(!(size=small)))'
+		end
+
+
 		# 
 		# #scope
 		# 
@@ -427,6 +450,7 @@ describe Treequel::Branchset do
 			newset.options[:select].should include( :+ )
 		end
 
+
 	end
 
 

data/spec/treequel/monkeypatches_spec.rb

@@ -75,11 +75,11 @@ describe Treequel::TimeExtensions do
 	before( :all ) do
 		# Make the local timezone PDT so offsets show up correctly
 		@real_tz = ENV['TZ']
-		ENV['TZ'] = 'US/Pacific'
+		ENV['TZ'] = ':GMT'
 	end
 
 	before( :each ) do
-		@time = Time.parse( "Fri Aug 20 08:21:35.1876455 -0700 2010" )
+		@time = Time.parse( "Fri Aug 20 08:21:35.1876455 -0000 2010" )
 	end
 
 	after( :all ) do
@@ -89,23 +89,23 @@ describe Treequel::TimeExtensions do
 	describe "RFC4517 LDAP Generalized Time method" do
 
 		it "returns the time in 'Generalized Time' format" do
-			@time.ldap_generalized.should == "20100820082135-0700"
+			@time.ldap_generalized.should == "20100820082135Z"
 		end
 
 		it "can include fractional seconds if the optional fractional digits argument is given" do
-			@time.ldap_generalized( 3 ).should == "20100820082135.187-0700"
+			@time.ldap_generalized( 3 ).should == "20100820082135.187Z"
 		end
 
 		it "doesn't include the decimal if fractional digits is specified but zero" do
-			@time.ldap_generalized( 0 ).should == "20100820082135-0700"
+			@time.ldap_generalized( 0 ).should == "20100820082135Z"
 		end
 
 		it "zero-fills any digits after six in the fractional digits" do
-			@time.ldap_generalized( 11 ).should == "20100820082135.18764500000-0700"
+			@time.ldap_generalized( 11 ).should == "20100820082135.18764500000Z"
 		end
 
 		it "uses 'Z' for the timezone of times in UTC" do
-			@time.utc.ldap_generalized.should == "20100820152135Z"
+			@time.utc.ldap_generalized.should == "20100820082135Z"
 		end
 
 	end
@@ -113,11 +113,11 @@ describe Treequel::TimeExtensions do
 	describe "RFC4517 UTC Time method" do
 
 		it "returns the time in 'UTC Time' format" do
-			@time.ldap_utc.should == "100820082135-0700"
+			@time.ldap_utc.should == "100820082135Z"
 		end
 
 		it "uses 'Z' for the timezone of times in UTC" do
-			@time.utc.ldap_utc.should == "100820152135Z"
+			@time.utc.ldap_utc.should == "100820082135Z"
 		end
 
 	end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treequel
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
   prerelease: 
 platform: ruby
 authors:
@@ -49,11 +49,11 @@ cert_chain:
   -----END CERTIFICATE-----
 
 '
-date: 2011-10-26 00:00:00.000000000Z
+date: 2011-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-ldap
-  requirement: &70303756869080 !ruby/object:Gem::Requirement
+  requirement: &70222008767240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -61,10 +61,10 @@ dependencies:
         version: '0.9'
   type: :runtime
   prerelease: false
-  version_requirements: *70303756869080
+  version_requirements: *70222008767240
 - !ruby/object:Gem::Dependency
   name: diff-lcs
-  requirement: &70303756867300 !ruby/object:Gem::Requirement
+  requirement: &70222008766820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -72,10 +72,10 @@ dependencies:
         version: '1.1'
   type: :runtime
   prerelease: false
-  version_requirements: *70303756867300
+  version_requirements: *70222008766820
 - !ruby/object:Gem::Dependency
   name: hoe-mercurial
-  requirement: &70303756866280 !ruby/object:Gem::Requirement
+  requirement: &70222008766400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -83,10 +83,10 @@ dependencies:
         version: 1.3.1
   type: :development
   prerelease: false
-  version_requirements: *70303756866280
+  version_requirements: *70222008766400
 - !ruby/object:Gem::Dependency
   name: hoe-manualgen
-  requirement: &70303756865680 !ruby/object:Gem::Requirement
+  requirement: &70222008782300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -94,10 +94,10 @@ dependencies:
         version: 0.2.0
   type: :development
   prerelease: false
-  version_requirements: *70303756865680
+  version_requirements: *70222008782300
 - !ruby/object:Gem::Dependency
   name: hoe-highline
-  requirement: &70303756865000 !ruby/object:Gem::Requirement
+  requirement: &70222008781880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -105,21 +105,21 @@ dependencies:
         version: 0.0.1
   type: :development
   prerelease: false
-  version_requirements: *70303756865000
+  version_requirements: *70222008781880
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70303756864220 !ruby/object:Gem::Requirement
+  requirement: &70222008781420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.6.0
+        version: '2.7'
   type: :development
   prerelease: false
-  version_requirements: *70303756864220
+  version_requirements: *70222008781420
 - !ruby/object:Gem::Dependency
   name: ruby-termios
-  requirement: &70303756863560 !ruby/object:Gem::Requirement
+  requirement: &70222008781000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -127,10 +127,10 @@ dependencies:
         version: '0.9'
   type: :development
   prerelease: false
-  version_requirements: *70303756863560
+  version_requirements: *70222008781000
 - !ruby/object:Gem::Dependency
   name: ruby-terminfo
-  requirement: &70303756862820 !ruby/object:Gem::Requirement
+  requirement: &70222008780580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -138,10 +138,10 @@ dependencies:
         version: '0.1'
   type: :development
   prerelease: false
-  version_requirements: *70303756862820
+  version_requirements: *70222008780580
 - !ruby/object:Gem::Dependency
   name: columnize
-  requirement: &70303756853520 !ruby/object:Gem::Requirement
+  requirement: &70222008780160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -149,10 +149,10 @@ dependencies:
         version: '0.3'
   type: :development
   prerelease: false
-  version_requirements: *70303756853520
+  version_requirements: *70222008780160
 - !ruby/object:Gem::Dependency
   name: sysexits
-  requirement: &70303756852880 !ruby/object:Gem::Requirement
+  requirement: &70222008779740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -160,10 +160,10 @@ dependencies:
         version: '1.0'
   type: :development
   prerelease: false
-  version_requirements: *70303756852880
+  version_requirements: *70222008779740
 - !ruby/object:Gem::Dependency
   name: sequel
-  requirement: &70303756852260 !ruby/object:Gem::Requirement
+  requirement: &70222008779320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -171,10 +171,10 @@ dependencies:
         version: '3.20'
   type: :development
   prerelease: false
-  version_requirements: *70303756852260
+  version_requirements: *70222008779320
 - !ruby/object:Gem::Dependency
   name: hoe
-  requirement: &70303756851700 !ruby/object:Gem::Requirement
+  requirement: &70222008778900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -182,7 +182,7 @@ dependencies:
         version: '2.12'
   type: :development
   prerelease: false
-  version_requirements: *70303756851700
+  version_requirements: *70222008778900
 description: ! "Treequel is an LDAP toolkit for Ruby. It is intended to allow quick,
   easy\naccess to LDAP directories in a manner consistent with LDAP's hierarchical,\nfree-form
   nature. \n\nIt's inspired by and modeled after [Sequel](http://sequel.rubyforge.org/),

metadata.gz.sig

@@ -1,3 +1 @@
-'qE��
-MfBݝ�]o�����4_^C��}���hnn/�N��kM	��=~���&���zEc��멻�'�D��}�yLtu�%�'�_�j�����5zF�����O��3��k��p�T���jC�s��5�Q_B�
o��>k0�IYE�2��������T��똖�
-^(���!n���
��M�s
+��