treequel 1.0.0 → 1.0.1

data/bin/treequel

@@ -1,30 +1,108 @@
 #!/usr/bin/env ruby
 
 require 'rubygems'
-require 'readline'
+
+require 'abbrev'
+require 'columnize'
+require 'digest/sha1'
 require 'logger'
+require 'open3'
+require 'optparse'
+require 'ostruct'
+require 'pathname'
+require 'readline'
 require 'shellwords'
 require 'tempfile'
-require 'digest/sha1'
-require 'abbrev'
+require 'terminfo'
+require 'termios'
+require 'uri'
+
 require 'treequel'
 require 'treequel/mixins'
 require 'treequel/constants'
 
 
-class Shell
-	include Treequel::Loggable,
-	        Treequel::Constants::Patterns
+### Monkeypatch for resetting an OpenStruct's state.
+class OpenStruct
+
+	### Clear all defined fields and values.
+	def clear
+		@table.clear
+	end
+
+end
+
+
+# The Treequel shell.
+class Treequel::Shell
+	include Readline,
+	        Treequel::Loggable,
+	        Treequel::ANSIColorUtilities,
+	        Treequel::Constants::Patterns,
+	        Treequel::HashUtilities
+
+	# Prompt text for #prompt_for_multiple_values
+	MULTILINE_PROMPT = <<-'EOF'
+	Enter one or more values for '%s'.
+	A blank line finishes input.
+	EOF
+
+	# Some ANSI codes for fancier stuff
+	CLEAR_TO_EOL       = "\e[K"
+	CLEAR_CURRENT_LINE = "\e[2K"
+
+	# Log levels
+	LOG_LEVELS = {
+		'debug' => Logger::DEBUG,
+		'info'  => Logger::INFO,
+		'warn'  => Logger::WARN,
+		'error' => Logger::ERROR,
+		'fatal' => Logger::FATAL,
+	}.freeze
+	LOG_LEVEL_NAMES = LOG_LEVELS.invert.freeze
+
+	# Command option parsers
+	OPTION_PARSERS = {}
+
+	# Path to the default history file
+	HISTORY_FILE = Pathname( "~/.treequel.history" )
 
+	# Number of items to store in history by default
+	DEFAULT_HISTORY_SIZE = 100
+
+
+	#################################################################
+	###	C L A S S   M E T H O D S
+	#################################################################
+
+	### Create an option parser from the specified +block+ for the given +command+ and register
+	### it. Many thanks to apeiros and dominikh on #Ruby-Pro for the ideas behind this.
+	def self::set_options( command, &block )
+	    options = OpenStruct.new
+		oparser = OptionParser.new( "Help for #{command}" ) do |o|
+			yield( o, options )
+		end
+		oparser.default_argv = []
+
+		OPTION_PARSERS[command.to_sym] = [oparser, options]
+	end
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
 
 	### Create a new shell that will traverse the directory at the specified +uri+.
 	def initialize( uri )
 		Treequel.logger.level = Logger::WARN
+		Treequel.logger.formatter = Treequel::ColorLogFormatter.new( Treequel.logger )
 
 		@uri        = uri
 		@quit       = false
 		@dir        = Treequel.directory( @uri )
 		@currbranch = @dir
+		@columns    = TermInfo.screen_width
+		@rows       = TermInfo.screen_height
 
 		@commands = self.find_commands
 		@completions = @commands.abbrev
@@ -34,41 +112,83 @@ class Shell
 
 	### The command loop: run the shell until the user wants to quit
 	def run
-		$stderr.puts "Connected to %s" % [ @uri ]
+		@original_tty_settings = IO.read( '|-' ) or exec 'stty', '-g'
+		message "Connected to %s" % [ @uri ]
 
+		# Set up the completion callback
 		self.setup_completion
 
+		# Load saved command-line history
+		self.read_history
+
+		# Run until something sets the quit flag
 		until @quit
-			input = Readline.readline( @currbranch.dn + '> ', true )
+			$stderr.puts
+			prompt = make_prompt_string( @currbranch.dn + '> ' )
+			input = Readline.readline( prompt, true )
 			self.log.debug "Input is: %p" % [ input ]
 
 			# EOL makes the shell quit
 			if input.nil?
+				self.log.debug "EOL: setting quit flag"
 				@quit = true
 
+			# Blank input -- just reprompt
 			elsif input == ''
 				self.log.debug "No command. Re-displaying the prompt."
 
 			# Parse everything else into command + everything else
 			else
-				command, *args = Shellwords.shellwords( input )
-
-				begin
-					if meth = @command_table[ command ]
-						meth.call( *args )
-					else
-						self.handle_missing_command( command )
-					end
-				rescue => err
-					$stderr.puts "Error: %s" % [ err.message ]
-					err.backtrace.each do |frame|
-						self.log.debug "  " + frame
-					end
-				end
+				self.log.debug "Dispatching input: %p" % [ input ]
+				self.dispatch_cmd( input )
+			end
+		end
+
+		message "\nSaving history...\n"
+		self.save_history
+
+		message "done."
+	ensure
+		system( 'stty', @original_tty_settings.chomp )
+	end
+
+
+	### Parse the specified +input+ into a command, options, and arguments and dispatch them
+	### to the appropriate command method.
+	def dispatch_cmd( input )
+		command, *args = Shellwords.shellwords( input )
+
+		# If it's a valid command, run it
+		if meth = @command_table[ command ]
+			full_command = @completions[ command ].to_sym
+
+			# If there's a registered optionparser for the command, use it to 
+			# split out options and arguments, then pass those to the command.
+			if OPTION_PARSERS.key?( full_command )
+				oparser, options = OPTION_PARSERS[ full_command ]
+				self.log.debug "Got an option-parser for #{full_command}."
+
+				cmdargs = oparser.parse( args )
+				self.log.debug "  options=%p, args=%p" % [ options, cmdargs ]
+				meth.call( options, *cmdargs )
+
+				options.clear
+
+			# ...otherwise just call it with all the args.
+			else
+				meth.call( *args )
 			end
+
+		# ...otherwise call the fallback handler
+		else
+			self.handle_missing_cmd( command )
 		end
 
-		$stderr.puts "done."
+	rescue => err
+		error_message( err.class.name, err.message )
+		err.backtrace.each do |frame|
+			self.log.debug "  " + frame
+		end
 	end
 
 
@@ -80,33 +200,110 @@ class Shell
 	def setup_completion
 		Readline.completion_proc = self.method( :completion_callback ).to_proc
 		Readline.completer_word_break_characters = ''
+		Readline.basic_word_break_characters = ''
+	end
+
+
+	### Read command line history from HISTORY_FILE
+	def read_history
+		histfile = HISTORY_FILE.expand_path
+
+		if histfile.exist?
+			lines = histfile.readlines.collect {|line| line.chomp }
+			self.log.debug "Read %d saved history commands from %s." % [ lines.nitems, histfile ]
+			Readline::HISTORY.push( *lines )
+		else
+			self.log.debug "History file '%s' was empty or non-existant." % [ histfile ]
+		end
+	end
+
+
+	### Save command line history to HISTORY_FILE
+	def save_history
+		histfile = HISTORY_FILE.expand_path
+
+		lines = Readline::HISTORY.to_a.reverse.uniq.reverse
+		lines = lines[ -DEFAULT_HISTORY_SIZE, DEFAULT_HISTORY_SIZE ] if
+			lines.nitems > DEFAULT_HISTORY_SIZE
+
+		self.log.debug "Saving %d history lines to %s." % [ lines.length, histfile ]
+
+		histfile.open( File::WRONLY|File::CREAT|File::TRUNC ) do |ofh|
+			ofh.puts( *lines )
+		end
 	end
 
 
 	### Handle completion requests from Readline.
 	def completion_callback( input )
-		if command = @completions[ input ]
-			return []
+		self.log.debug "Input completion: %p" % [ input ]
+		parts = Shellwords.shellwords( input )
+
+		# If there aren't any arguments, it's command completion
+		if parts.length == 1
+			# One completion means it's an unambiguous match, so just complete it.
+			possible_completions = @commands.grep( /^#{Regexp.quote(input)}/ ).sort
+			self.log.debug "  possible completions: %p" % [ possible_completions ]
+			return possible_completions
+		else
+			incomplete = parts.pop
+			self.log.debug "  the incomplete bit is: %p" % [ incomplete ]
+			possible_completions = @currbranch.children.
+				collect {|br| br.rdn }.grep( /^#{Regexp.quote(incomplete)}/i ).sort
+
+			possible_completions.map! do |lastpart|
+				parts.join( ' ' ) + ' ' + lastpart
+			end
+
+			self.log.debug "  possible (argument) completions: %p" % [ possible_completions ]
+			return possible_completions
+		end
+	end
+
+
+	#################################################################
+	###	C O M M A N D S
+	#################################################################
+
+	### Show the completions hash
+	def show_completions_command
+		message "Completions:", @completions.inspect
+	end
+
+
+	### Show help text for the specified command, or a list of all available commands 
+	### if none is specified.
+	def help_command( *args )
+		if args.empty?
+			$stderr.puts
+			message colorize( "Available commands", :bold, :white ),
+				*columnize(@commands)
+		else
+			cmd = args.shift.to_sym
+			if OPTION_PARSERS.key?( cmd )
+				oparser, _ = OPTION_PARSERS[ cmd ]
+				self.log.debug "Setting summary width to: %p" % [ @columns ]
+				oparser.summary_width = @columns
+				output = oparser.to_s.sub( /^(.*?)\n/ ) do |match|
+					colorize( :bold, :white ) { match }
+				end
+
+				$stderr.puts
+				message( output )
+			else
+				error_message( "No help for '#{cmd}'" )
+			end
 		end
 	end
 
 
 	### Quit the shell.
 	def quit_command( *args )
-		$stderr.puts "Okay, exiting."
+		message "Okay, exiting."
 		@quit = true
 	end
 
 
-	LOG_LEVELS = {
-		'debug' => Logger::DEBUG,
-		'info'  => Logger::INFO,
-		'warn'  => Logger::WARN,
-		'error' => Logger::ERROR,
-		'fatal' => Logger::FATAL,
-	}.freeze
-	LOG_LEVEL_NAMES = LOG_LEVELS.invert.freeze
-
 	### Set the logging level (if invoked with an argument) or display the current
 	### level (with no argument).
 	def log_command( *args )
@@ -114,46 +311,135 @@ class Shell
 		if newlevel
 			if LOG_LEVELS.key?( newlevel )
 				Treequel.logger.level = LOG_LEVELS[ newlevel ]
-				$stderr.puts "Set log level to: %s" % [ newlevel ]
+				message "Set log level to: %s" % [ newlevel ]
 			else
 				levelnames = LOG_LEVEL_NAMES.keys.sort.join(', ')
 				raise "Invalid log level %p: valid values are:\n   %s" % [ newlevel, levelnames ]
 			end
 		else
-			$stderr.puts "Log level is currently: %s" %
+			message "Log level is currently: %s" %
 				[ LOG_LEVEL_NAMES[Treequel.logger.level] ]
 		end
 	end
 
 
-	### Show the completions hash
-	def show_completions_command
-		$stderr.puts "Completions:",
-			@completions.inspect
+	### Display LDIF for the specified RDNs.
+	def cat_command( *args )
+		args.each do |rdn|
+			branch = @currbranch.get_child( rdn )
+			message( format_ldif(branch.to_ldif) )
+		end
 	end
 
 
-	### Display LDIF for the specified RDNs.
-	def cat_command( *args )
+	### Display YAML for the specified RDNs.
+	def yaml_command( *args )
 		args.each do |rdn|
-			branch = rdn.split( /\s*,\s*/ ).inject( @currbranch ) do |branch, dnpair|
-				attribute, value = dnpair.split( /\s*=\s*/, 2 )
-				branch.send( attribute, value )
+			branch = @currbranch.get_child( rdn )
+			message( branch_as_yaml(branch) )
+		end
+	end
+
+
+	### List the children of the branch specified by the given +rdn+, or the current branch if none
+	### are specified.
+	def ls_command( options, *args )
+		targets = []
+
+		# No argument, just use the current branch
+		if args.empty?
+			targets << @currbranch
+
+		# Otherwise, list each one specified
+		else
+			args.each do |rdn|
+				if branch = @currbranch.get_child( rdn )
+					targets << branch
+				else
+					error_message( "cannot access #{rdn}: no such entry" )
+				end
 			end
+		end
+
+		# Fetch each branch's children, sort them, format them in columns, and highlight them
+		targets.each do |branch|
+			if options.longform
+				message self.make_longform_ls_output( branch, options )
+			else
+				message self.make_shortform_ls_output( branch, options )
+			end
+		end
+	end
+	set_options :ls do |oparser, options|
+		oparser.banner = "ls [OPTIONS] [DNs]"
 
-			$stdout.puts( branch.to_ldif )
+		oparser.on( "-l", "--long", FalseClass, "List in long format." ) do 
+			options.longform = true
 		end
+
 	end
 
 
-	### List the children of the current branch.
-	def ls_command( *args )
-		$stdout.puts *@currbranch.children.collect {|b| b.rdn }.sort
+	### Generate long-form output lines for the 'ls' command for the given +branch+.
+	def make_longform_ls_output( branch, options )
+		rows = []
+		children = branch.children
+		rows << colorize( :underscore, :cyan ) { "total %d" % [children.length] }
+
+		# Calcuate column widths
+		oclen = children.map do |branch|
+			branch.include_operational_attrs = true
+			branch[:structuralObjectClass].length
+		end.max
+		moddnlen = children.map do |branch|
+			branch[:modifiersName].length
+		end.max
+
+		children.
+			sort_by {|branch| branch.rdn.downcase }.
+			each do |branch|
+				# -rw-r--r--   2 mgranger staff   979 2009-07-27 11:55 Rakefile.local
+				# 
+				# modifiersName: cn=admin,dc=laika,dc=com
+				# hasSubordinates: TRUE
+				# modifyTimestamp: 20090520232650Z
+				# structuralObjectClass: organizationalUnit
+				rows << "%#{oclen}s  %#{moddnlen}s  %s  %s%s" % [
+					branch[:structuralObjectClass],
+					branch[:modifiersName],
+					branch[:modifyTimestamp].strftime('%Y-%m-%d %H:%M'),
+					format_rdn( branch.rdn ),
+					branch[:hasSubordinates] ? '/' : ''
+				]
+			end
+
+		return rows
+	end
+
+
+	### Generate short-form 'ls' output for the given +branch+ and return it.
+	def make_shortform_ls_output( branch, options )
+		entries = branch.children.
+			collect {|b| b.rdn }.
+			sort_by {|rdn| rdn.downcase }
+		return columnize( entries ).
+			collect do |row|
+				row.gsub( /#{ATTRIBUTE_TYPE}=\s*\S+/ ) do |rdn|
+					format_rdn( rdn )
+				end
+			end
 	end
 
 
 	### Change the current working DN to +rdn+.
-	def cdn_command( rdn, *args )
+	def cdn_command( rdn=nil, *args )
+		if rdn.nil?
+			@currbranch = @dir.base
+			return
+		end
+
+		return self.parent_command if rdn == '..'
+
 		raise "invalid RDN %p" % [ rdn ] unless RELATIVE_DISTINGUISHED_NAME.match( rdn )
 
 		pairs = rdn.split( /\s*,\s*/ )
@@ -176,27 +462,131 @@ class Shell
 
 
 	### Edit the entry specified by +rdn+.
-	def edit_command( rdn, *args )
-		branch = @currbranch.get_child( rdn )
+	#def edit_command( options, rdn )
+	#	branch = @currbranch.get_child( rdn )
+	#	entryhash = nil
+	#
+	#	if options.newentry
+	#		raise "#{branch.dn} already exists." if branch.exists?
+	#		object_classes = prompt_for_multiple_values( "Entry objectClasses:" )
+	#		entryhash = branch.valid_attributes_hash( *object_classes )
+	#		newhash = edit_in_yaml( entryhash )
+	#		args = object_classes + [newhash]
+	#		branch.create( *args )
+	#	else
+	#		raise "#{branch.dn}: no such entry. Did you mean to create it with -n?" unless
+	#		 	branch.exists?
+	#		entryhash = branch.entry
+	#		newhash = edit_in_yaml( entryhash )
+	#		branch.merge( entryhash )
+	#	end
+	#
+	#	message "Saved #{rdn}."
+	#end
+	#set_options :edit do |oparser, options|
+	#	oparser.banner = "edit [OPTIONS] DN"
+	#
+	#	oparser.on( "-n", "--new", FalseClass, 
+	#		"Create a new entry instead of editing an existing one." ) do 
+	#		options.newentry = true
+	#	end
+	#
+	#end
+
+
+	### Convert the given +patterns+ to branchsets relative to the current branch and return
+	### them. This is used to map shell arguments like 'cn=*', 'Hosts', 'cn=dav*' into
+	### branchsets that will find matching entries.
+	def convert_to_branchsets( *patterns )
+		self.log.debug "Turning %d patterns into branchsets." % [ patterns.length ]
+		return patterns.collect do |pat|
+			key, val = pat.split( /\s*=\s*/, 2 )
+			self.log.debug "  making a filter out of %p => %p" % [ key, val ]
+			@currbranch.filter( key => val )
+		end
+	end
+
+
+	### Remove the entry specified by +rdn+.
+	def rm_command( options, *rdns )
+		branchsets = self.convert_to_branchsets( *rdns )
+		coll = Treequel::BranchCollection.new( *branchsets )
+
+		branches = coll.all
+
+		msg = "About to delete the following entries:\n" +
+			branches.collect {|br| "  #{br.dn}" }.join("\n")
+
+		ask_for_confirmation( msg ) do
+			branches.each do |branch|
+				branch.delete
+				message "Deleted #{branch.dn}." 
+			end
+		end
+	end
+	set_options :rm do |oparser, options|
+		oparser.banner = "rm [DNs]"
+	end
+
+
+	### Find entries that match the given filter_clauses.
+	def grep_command( options, *filter_clauses )
+		branchset = filter_clauses.inject( @currbranch ) do |branch, clause|
+			branch.filter( clause )
+		end
 
-		fn = Digest::SHA1.hexdigest( rdn )
-		tf = Tempfile.new( fn )
-		if branch.exists?
-			tf.print(  )
+		message "Searching for entries that match '#{branchset.to_s}'"
+
+		entries = branchset.all
+		output = columnize( entries ).
+			collect do |row|
+				row.gsub( /#{ATTRIBUTE_TYPE}=\s*\S+/ ) do |rdn|
+					format_rdn( rdn )
+				end
+			end
+		message( output )
+	end
+	set_options :grep do |oparser, options|
+		oparser.banner = "grep [OPTIONS] FILTER"
+	end
+
+
+	### Bind as a user.
+	def bind_command( options, *args )
+		binddn = (args.first || prompt( "Bind DN/UID" )) or
+			raise "Cancelled."
+		password = prompt_for_password()
+
+		# Try to turn a non-DN into a DN
+		user = nil
+		if binddn.index( '=' )
+			user = Treequel::Branch.new( @dir, binddn )
+		else
+			user = @dir.filter( :uid => binddn ).first
+		end
+		raise "No user found for %p" % [ binddn ] unless user.exists?
+
+		@dir.bind( user, password )
+		message "Bound as #{user}"
+	end
+	set_options :bind do |oparser, options|
+		oparser.banner = "bind [BIND_DN or UID]"
+		oparser.separator "If you don't specify a BIND_DN, you will be prompted for it."
 	end
 
 
 	### Handle a command from the user that doesn't exist.
-	def handle_missing_command( *args )
+	def handle_missing_cmd( *args )
 		command = args.shift || '(testing?)'
-		$stderr.puts "Unknown command %p" % [ command ]
-		$stderr.puts "Known commands: ", '  ' + @commands.join(', ')
+		message "Unknown command %p" % [ command ]
+		message "Known commands: ", '  ' + @commands.join(', ')
 	end
 
 
 	### Find methods that implement commands and return them in a sorted Array.
 	def find_commands
 		return self.methods.
+			collect {|mname| mname.to_s }.
 			grep( /^(\w+)_command$/ ).
 			collect {|mname| mname[/^(\w+)_command$/, 1] }.
 			sort
@@ -207,6 +597,51 @@ class Shell
 	private
 	#######
 
+	### Dump the specified +object+ to a file as YAML, invoke an editor on it, then undump the 
+	### result. If the file has changed, return the updated object, else returns +nil+.
+	def edit_in_yaml( object )
+		yaml = branch_as_yaml( object )
+		filename = Digest::SHA1.hexdigest( yaml )
+		tempfile = Tempfile.new( filename )
+
+		message "Object as YAML is: ", yaml
+		tempfile.print( yaml )
+		tempfile.close
+
+		new_yaml = edit( tempfile.path )
+
+		if new_yaml == yaml
+			message "Unchanged."
+			return nil
+		else
+			return YAML.load( new_yaml )
+		end
+	end
+
+
+	### Return the specified Treequel::Branch object as YAML. If +include_operational+ is true,
+	### include the entry's operational attributes.
+	def branch_as_yaml( object, include_operational=false )
+		object.include_operational_attrs = include_operational
+
+		# Make sure the displayed entry has the MUST attributes
+		entryhash = stringify_keys( object.must_attributes_hash )
+		entryhash.merge!( object.entry )
+		dn = entryhash.delete( 'dn' )
+		
+		yaml = entryhash.to_yaml
+		yaml[ 5, 0 ] = "# #{dn}\n"
+		
+		# Make comments out of MAY attributes that are unset
+		mayhash = stringify_keys( object.may_attributes_hash )
+		self.log.debug "MAY hash is: %p" % [ mayhash ]
+		mayhash.delete_if {|attrname,val| entryhash.key?(attrname) }
+		yaml << mayhash.to_yaml[5..-1].gsub( /\n\n/, "\n" ).gsub( /^/, '# ' )
+
+		return yaml
+	end
+
+
 	### Create a command table that maps command abbreviations to the Method object that
 	### implements it.
 	def make_command_table( commands )
@@ -219,11 +654,327 @@ class Shell
 		return table
 	end
 
-end
+
+	### Return the specified args as a string, quoting any that have a space.
+	def quotelist( *args )
+		return args.flatten.collect {|part| part =~ /\s/ ? part.inspect : part}
+	end
 
 
-if __FILE__ == $0
-	ldapuri = URI( ARGV.shift || 'ldap://localhost' )
-	Shell.new( ldapuri ).run
-end
+	### Run the specified command +cmd+ with system(), failing if the execution
+	### fails.
+	def run_command( *cmd )
+		cmd.flatten!
+
+		if cmd.length > 1
+			self.log.debug( quotelist(*cmd) )
+		else
+			self.log.debug( cmd )
+		end
+
+		if $dryrun
+			self.log.error "(dry run mode)"
+		else
+			system( *cmd )
+			unless $?.success?
+				raise "Command failed: [%s]" % [cmd.join(' ')]
+			end
+		end
+	end
+
+
+	### Run the given +cmd+ with the specified +args+ without interpolation by the shell and
+	### return anything written to its STDOUT.
+	def read_command_output( cmd, *args )
+		self.log.debug "Reading output from: %s" % [ cmd, quotelist(cmd, *args) ]
+		output = IO.read( '|-' ) or exec cmd, *args
+		return output
+	end
+
+
+	### Run a subordinate Rake process with the same options and the specified +targets+.
+	def rake( *targets )
+		opts = ARGV.select {|arg| arg[0,1] == '-' }
+		args = opts + targets.map {|t| t.to_s }
+		run 'rake', '-N', *args
+	end
+
+
+	### Open a pipe to a process running the given +cmd+ and call the given block with it.
+	def pipeto( *cmd )
+		$DEBUG = true
+
+		cmd.flatten!
+		self.log.info( "Opening a pipe to: ", cmd.collect {|part| part =~ /\s/ ? part.inspect : part} ) 
+		if $dryrun
+			message "(dry run mode)"
+		else
+			open( '|-', 'w+' ) do |io|
+
+				# Parent
+				if io
+					yield( io )
+
+				# Child
+				else
+					exec( *cmd )
+					raise "Command failed: [%s]" % [cmd.join(' ')]
+				end
+			end
+		end
+	end
+
+
+	### Return the fully-qualified path to the specified +program+ in the PATH.
+	def which( program )
+		ENV['PATH'].split(/:/).
+			collect {|dir| Pathname.new(dir) + program }.
+			find {|path| path.exist? && path.executable? }
+	end
+
+
+	### Output the specified message +parts+.
+	def message( *parts )
+		$stderr.puts( *parts )
+	end
+
+
+	### Output the specified <tt>msg</tt> as an ANSI-colored error message
+	### (white on red).
+	def error_message( msg, details='' )
+		$stderr.puts colorize( 'bold', 'white', 'on_red' ) { msg } + ' ' + details
+	end
+	alias :error :error_message
+
+
+	### Highlight and embed a prompt control character in the given +string+ and return it.
+	def make_prompt_string( string )
+		return CLEAR_CURRENT_LINE + colorize( 'bold', 'yellow' ) { string + ' ' }
+	end
+
+
+	### Output the specified <tt>prompt_string</tt> as a prompt (in green) and
+	### return the user's input with leading and trailing spaces removed.  If a
+	### test is provided, the prompt will repeat until the test returns true.
+	### An optional failure message can also be passed in.
+	def prompt( prompt_string, failure_msg="Try again." ) # :yields: response
+		prompt_string.chomp!
+		prompt_string << ":" unless /\W$/.match( prompt_string )
+		response = nil
+
+		begin
+			prompt = make_prompt_string( prompt_string )
+			response = readline( prompt ) || ''
+			response.strip!
+			if block_given? && ! yield( response ) 
+				error_message( failure_msg + "\n\n" )
+				response = nil
+			end
+		end while response.nil?
+
+		return response
+	end
+
+
+	### Prompt the user with the given <tt>prompt_string</tt> via #prompt,
+	### substituting the given <tt>default</tt> if the user doesn't input
+	### anything.  If a test is provided, the prompt will repeat until the test
+	### returns true.  An optional failure message can also be passed in.
+	def prompt_with_default( prompt_string, default, failure_msg="Try again." )
+		response = nil
+
+		begin
+			default ||= '~'
+			response = prompt( "%s [%s]" % [ prompt_string, default ] )
+			response = default.to_s if !response.nil? && response.empty? 
+
+			self.log.debug "Validating response %p" % [ response ]
+
+			# the block is a validator.  We need to make sure that the user didn't
+			# enter '~', because if they did, it's nil and we should move on.  If
+			# they didn't, then call the block.
+			if block_given? && response != '~' && ! yield( response )
+				error_message( failure_msg + "\n\n" )
+				response = nil
+			end
+		end while response.nil?
+
+		return nil if response == '~'
+		return response
+	end
+
+
+	### Prompt for an array of values
+	def prompt_for_multiple_values( label, default=nil )
+	    message( MULTILINE_PROMPT % [label] )
+	    if default
+			message "Enter a single blank line to keep the default:\n  %p" % [ default ]
+		end
+
+	    results = []
+	    result = nil
+
+	    begin
+	        result = readline( make_prompt_string("> ") )
+			if result.nil? || result.empty?
+				results << default if default && results.empty?
+			else
+	        	results << result 
+			end
+	    end until result.nil? || result.empty?
+
+	    return results.flatten
+	end
+
+
+	### Turn echo and masking of input on/off. 
+	def noecho( masked=false )
+		rval = nil
+		term = Termios.getattr( $stdin )
+
+		begin
+			newt = term.dup
+			newt.c_lflag &= ~Termios::ECHO
+			newt.c_lflag &= ~Termios::ICANON if masked
+
+			Termios.tcsetattr( $stdin, Termios::TCSANOW, newt )
+
+			rval = yield
+		ensure
+			Termios.tcsetattr( $stdin, Termios::TCSANOW, term )
+		end
+
+		return rval
+	end
+
+
+	### Prompt the user for her password, turning off echo if the 'termios' module is
+	### available.
+	def prompt_for_password( prompt="Password: " )
+		rval = nil
+		noecho( true ) do
+			$stderr.print( prompt )
+			rval = ($stdin.gets || '').chomp
+		end
+		$stderr.puts
+		return rval
+	end
+
+
+	### Display a description of a potentially-dangerous task, and prompt
+	### for confirmation. If the user answers with anything that begins
+	### with 'y', yield to the block. If +abort_on_decline+ is +true+,
+	### any non-'y' answer will fail with an error message.
+	def ask_for_confirmation( description, abort_on_decline=true )
+		puts description
+
+		answer = prompt_with_default( "Continue?", 'n' ) do |input|
+			input =~ /^[yn]/i
+		end
+
+		if answer =~ /^y/i
+			return yield
+		elsif abort_on_decline
+			error "Aborted."
+			fail
+		end
+
+		return false
+	end
+	alias :prompt_for_confirmation :ask_for_confirmation
+
+
+	### Search line-by-line in the specified +file+ for the given +regexp+, returning the
+	### first match, or nil if no match was found. If the +regexp+ has any capture groups,
+	### those will be returned in an Array, else the whole matching line is returned.
+	def find_pattern_in_file( regexp, file )
+		rval = nil
+
+		File.open( file, 'r' ).each do |line|
+			if (( match = regexp.match(line) ))
+				rval = match.captures.empty? ? match[0] : match.captures
+				break
+			end
+		end
+
+		return rval
+	end
+
+
+	### Search line-by-line in the output of the specified +cmd+ for the given +regexp+,
+	### returning the first match, or nil if no match was found. If the +regexp+ has any 
+	### capture groups, those will be returned in an Array, else the whole matching line
+	### is returned.
+	def find_pattern_in_pipe( regexp, *cmd )
+		output = []
+
+		self.log.info( cmd.collect {|part| part =~ /\s/ ? part.inspect : part} ) 
+		Open3.popen3( *cmd ) do |stdin, stdout, stderr|
+			stdin.close
+
+			output << stdout.gets until stdout.eof?
+			output << stderr.gets until stderr.eof?
+		end
+
+		result = output.find { |line| regexp.match(line) } 
+		return $1 || result
+	end
+
+
+	### Invoke the user's editor on the given +filename+ and return the exit code
+	### from doing so.
+	def edit( filename )
+		editor = ENV['EDITOR'] || ENV['VISUAL'] || DEFAULT_EDITOR
+		system editor, filename.to_s
+		unless $?.success? || editor =~ /vim/i
+			raise "Editor exited with an error status (%d)" % [ $?.exitstatus ]
+		end
+		return File.read( filename )
+	end
+
+
+	### Make an easily-comparable version vector out of +ver+ and return it.
+	def vvec( ver )
+		return ver.split('.').collect {|char| char.to_i }.pack('N*')
+	end
+
+
+	### Return an ANSI-colored version of the given +rdn+ string.
+	def format_rdn( rdn )
+		rdn.split( /,/ ).collect do |rdn|
+			key, val = rdn.split( /\s*=\s*/, 2 )
+			colorize( :white ) { key } +
+				colorize( :bold, :black ) { '=' } +
+				colorize( :bold, :white ) { val }
+		end.join( colorize(',', :green) )
+	end
+
+
+	### Highlight LDIF and return it.
+	def format_ldif( ldif )
+		return ldif.gsub( /^(\S[^:]*)(::?)\s*(.*)$/ ) do
+			key, sep, val = $1, $2, $3
+			case sep
+			when '::'
+				colorize( :cyan ) { key } + ':: ' + colorize( :dark, :white ) { val }
+			when ':'
+				colorize( :bold, :cyan ) { key } + ': ' + colorize( :dark, :white ) { val }
+			else
+				key + sep + ' ' + val
+			end
+		end
+	end
+
+
+	### Return the specified +entries+ as an Array of span-sorted columns fit to the
+	### current terminal width.
+	def columnize( *entries )
+		return Columnize.columnize( entries.flatten, @columns, '  ' )
+	end
+
+end # class Treequel::Shell
+
+
+ldapuri = URI( ARGV.shift || 'ldap://localhost' )
+Treequel::Shell.new( ldapuri ).run