treequel 1.0.0

data/Rakefile.local

@@ -0,0 +1,43 @@
+#!rake
+# coding: utf-8
+
+require 'pathname'
+require 'English'
+require 'pp'
+
+# Project-specific tasks
+
+#####################################################################
+###	T A S K S
+#####################################################################
+
+MANUAL_PAGES = Pathname.glob( MANUALDIR + '**/*.page' )
+
+task :local => :check_manual
+
+# Check the manual for laika references before committing
+Rake::Task[ 'checkin' ].prerequisites.unshift( 'check_manual' )
+
+desc "Check the manual for various problems and/or inconsistencies"
+task :check_manual => MANUAL_PAGES do
+	MANUAL_PAGES.each do |page|
+		lines = page.readlines
+		lines.each_with_index do |line, i|
+			if line =~ /\blaika\b/i
+				msg = [
+					'   ',
+					i.zero? ? "" : lines[ i - 1 ],
+					'   ',
+					$PREMATCH,
+					colorize( :bold, :yellow ) { $MATCH },
+					$POSTMATCH,
+					'   ',
+					lines[ i + 1 ]
+				].join
+				abort "Page #{page} has a LAIKA reference on line #{i + 1}:\n#{msg}"
+			end
+		end
+	end
+end
+
+

data/bin/treeirb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'irb'
+require 'irb/extend-command'
+require 'irb/cmd/nop'
+require 'treequel'
+
+
+uri = ARGV.shift or raise "usage: #$0 [LDAPURI]"
+$dir = Treequel.directory( uri )
+$stderr.puts "Directory is in $dir:", '  ' + $dir.inspect
+
+IRB.start( $0 )
+

data/bin/treequel

@@ -0,0 +1,229 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'readline'
+require 'logger'
+require 'shellwords'
+require 'tempfile'
+require 'digest/sha1'
+require 'abbrev'
+require 'treequel'
+require 'treequel/mixins'
+require 'treequel/constants'
+
+
+class Shell
+	include Treequel::Loggable,
+	        Treequel::Constants::Patterns
+
+
+	### Create a new shell that will traverse the directory at the specified +uri+.
+	def initialize( uri )
+		Treequel.logger.level = Logger::WARN
+
+		@uri        = uri
+		@quit       = false
+		@dir        = Treequel.directory( @uri )
+		@currbranch = @dir
+
+		@commands = self.find_commands
+		@completions = @commands.abbrev
+		@command_table = make_command_table( @commands )
+	end
+
+
+	### The command loop: run the shell until the user wants to quit
+	def run
+		$stderr.puts "Connected to %s" % [ @uri ]
+
+		self.setup_completion
+
+		until @quit
+			input = Readline.readline( @currbranch.dn + '> ', true )
+			self.log.debug "Input is: %p" % [ input ]
+
+			# EOL makes the shell quit
+			if input.nil?
+				@quit = true
+
+			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
+			end
+		end
+
+		$stderr.puts "done."
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Set up Readline completion
+	def setup_completion
+		Readline.completion_proc = self.method( :completion_callback ).to_proc
+		Readline.completer_word_break_characters = ''
+	end
+
+
+	### Handle completion requests from Readline.
+	def completion_callback( input )
+		if command = @completions[ input ]
+			return []
+		end
+	end
+
+
+	### Quit the shell.
+	def quit_command( *args )
+		$stderr.puts "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 )
+		newlevel = args.shift
+		if newlevel
+			if LOG_LEVELS.key?( newlevel )
+				Treequel.logger.level = LOG_LEVELS[ newlevel ]
+				$stderr.puts "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" %
+				[ LOG_LEVEL_NAMES[Treequel.logger.level] ]
+		end
+	end
+
+
+	### Show the completions hash
+	def show_completions_command
+		$stderr.puts "Completions:",
+			@completions.inspect
+	end
+
+
+	### Display LDIF for the specified RDNs.
+	def cat_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 )
+			end
+
+			$stdout.puts( branch.to_ldif )
+		end
+	end
+
+
+	### List the children of the current branch.
+	def ls_command( *args )
+		$stdout.puts *@currbranch.children.collect {|b| b.rdn }.sort
+	end
+
+
+	### Change the current working DN to +rdn+.
+	def cdn_command( rdn, *args )
+		raise "invalid RDN %p" % [ rdn ] unless RELATIVE_DISTINGUISHED_NAME.match( rdn )
+
+		pairs = rdn.split( /\s*,\s*/ )
+		pairs.each do |dnpair|
+			self.log.debug "  cd to %p" % [ dnpair ]
+			attribute, value = dnpair.split( /=/, 2 )
+			self.log.debug "  changing to %s( %p )" % [ attribute, value ]
+			@currbranch = @currbranch.send( attribute, value )
+		end
+	end
+
+
+	### Change the current working DN to the current entry's parent.
+	def parent_command( *args )
+		parent = @currbranch.parent or raise "%s is the root DN" % [ @currbranch.dn ]
+
+		self.log.debug "  changing to %s" % [ parent.dn ]
+		@currbranch = parent
+	end
+
+
+	### Edit the entry specified by +rdn+.
+	def edit_command( rdn, *args )
+		branch = @currbranch.get_child( rdn )
+
+		fn = Digest::SHA1.hexdigest( rdn )
+		tf = Tempfile.new( fn )
+		if branch.exists?
+			tf.print(  )
+	end
+
+
+	### Handle a command from the user that doesn't exist.
+	def handle_missing_command( *args )
+		command = args.shift || '(testing?)'
+		$stderr.puts "Unknown command %p" % [ command ]
+		$stderr.puts "Known commands: ", '  ' + @commands.join(', ')
+	end
+
+
+	### Find methods that implement commands and return them in a sorted Array.
+	def find_commands
+		return self.methods.
+			grep( /^(\w+)_command$/ ).
+			collect {|mname| mname[/^(\w+)_command$/, 1] }.
+			sort
+	end
+
+
+	#######
+	private
+	#######
+
+	### Create a command table that maps command abbreviations to the Method object that
+	### implements it.
+	def make_command_table( commands )
+		table = commands.abbrev
+		table.keys.each do |abbrev|
+			mname = table.delete( abbrev )
+			table[ abbrev ] = self.method( mname + '_command' )
+		end
+
+		return table
+	end
+
+end
+
+
+if __FILE__ == $0
+	ldapuri = URI( ARGV.shift || 'ldap://localhost' )
+	Shell.new( ldapuri ).run
+end
+

data/examples/company-directory.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'sinatra'
+require 'treequel'
+require 'pathname'
+
+# A barebones web-based company directory
+
+LDAP_URL = "ldap://ldap.yourcompany.com/dc=yourcompany,dc=com"
+
+configure do
+	# Borrow the CSS and images from the 'ldap-monitor' example
+	set :root, Pathname( __FILE__ ).dirname + 'ldap-monitor'
+end
+
+before do
+	$stderr.puts "Connecting to #{LDAP_URL}"
+	@ldap ||= Treequel.directory( LDAP_URL )
+end
+
+
+### GET /
+get '/' do
+
+	# Get every entry under ou=people that has an email address and sort them
+	# by last name, first name, and UID.
+	people = @ldap.ou( :people ).filter( :mail ).sort_by do |person|
+		[ person[:sn], person[:givenName], person[:uid] ]
+	end
+
+	erb :index,
+		:locals => {
+			:people => people
+		}
+end
+
+
+### GET /uid
+get '/:uid' do
+
+	# Look up the person associated with the given UID, returning NOT FOUND if
+	# there isn't any such entry
+	uid = params[:uid]
+	person = @ldap.ou( :people ).uid( uid )
+	halt 404, "No such person" unless person.exists?
+
+	erb :details,
+		:locals => {
+			:person => person
+		}
+end
+
+
+
+__END__
+
+@@layout
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+	<title>Company Directory</title>
+	<link rel="stylesheet" href="/css/master.css" type="text/css" media="screen" title="no title" charset="utf-8" />
+</head>
+
+<body>
+
+	<div id="content">
+	<h1>Company Directory</h1>
+
+	<%= yield %>
+
+	</div>
+
+	<div id="footer">Treequel Company Directory Example</div>
+</body>
+</html>
+
+
+@@index
+<table>
+<thead>
+	<tr>
+		<th class="odd">Name</th>
+		<th class="even">Email</th>
+		<th class="odd">Badge #</th>
+	</tr>
+</thead>
+<tbody>
+<% people.each_with_index do |person, i| %>
+<% rowclass = i.divmod(2).last.zero? ? "even" : "odd" %>
+	<tr class="<%= rowclass %>">
+		<td class="odd"><a href="/<%= person[:uid] %>"><%= person[:cn] %></p></td>
+		<td class="even"><a href="/<%= person[:uid] %>"><%= person[:mail] %></a></td>
+		<td class="odd"><%= person[:employeeNumber] %></td>
+	</tr>
+<% end %>
+</tbody>
+</table>
+
+@@details
+
+<h2>Details for <%= person[:cn] %> <%= person[:sn] %> 
+	&lt;<%= person[:mail] %>&gt;</h2>
+
+<pre>
+<%= person.to_ldif %>
+</pre>
+

data/examples/ldap-monitor.rb

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+
+BEGIN {
+	require 'pathname'
+	basedir = Pathname( __FILE__ ).dirname.parent
+	libdir = basedir + 'lib'
+
+	$LOAD_PATH.unshift( libdir.to_s )
+}
+
+require 'rubygems'
+require 'sinatra'
+require 'treequel'
+require 'erb'
+
+include ERB::Util
+
+# The real data is all in operational attributes, so fetch them by default
+Treequel::Branch.include_operational_attrs = true
+
+configure do
+	set :root, Pathname( __FILE__ ).dirname + 'ldap-monitor'
+end
+
+before do
+	@monitor ||= Treequel.directory( 'ldap://localhost/cn=Monitor',
+		:bind_dn => 'cn=admin,cn=Monitor', :pass => 'monitor' )
+end
+
+helpers do
+
+	### Return a string describing the amount of time in the given number of
+	### seconds in terms a human can understand easily.
+	def time_delta_string( start_time )
+		start = Time.parse( start_time ) or return "some time"
+		seconds = Time.now - start
+
+		return 'less than a minute' if seconds < 60
+
+		if seconds < 50 * 60
+			return "%d minute%s" % [seconds / 60, seconds/60 == 1 ? '' : 's']
+		end
+
+		return 'about an hour'					if seconds < 90 * MINUTES
+		return "%d hours" % [seconds / HOURS]	if seconds < 18 * HOURS
+		return 'one day' 						if seconds <  1 * DAYS
+		return 'about a day' 					if seconds <  2 * DAYS
+		return "%d days" % [seconds / DAYS] 	if seconds <  1 * WEEKS
+		return 'about a week' 					if seconds <  2 * WEEKS
+		return "%d weeks" % [seconds / WEEKS] 	if seconds <  3 * MONTHS
+		return "%d months" % [seconds / MONTHS] if seconds <  2 * YEARS
+		return "%d years" % [seconds / YEARS]
+	end
+
+end
+
+### GET /
+get '/' do
+	erb :index,
+		:locals => {
+			:server_info => @monitor.base['monitoredInfo'],
+			:datapoints  => @monitor.children,
+		}
+end
+
+
+# 
+# Subsystems
+# 
+
+get '/backends' do
+	subsystem = @monitor.cn( :backends )
+	backends = subsystem.
+		filter( :objectClass => :monitoredObject ).
+		select( :+, :* )
+
+	erb :backends,
+		:locals => {
+			:subsystem => subsystem,
+			:backends => backends,
+		}
+end
+
+
+get '/connections' do
+	subsystem = @monitor.cn( :connections )
+	connections = subsystem.
+		filter( :objectClass => :monitorConnection ).
+		select( :+, :* )
+
+	erb :connections,
+		:locals => {
+			:subsystem => subsystem,
+			:total => subsystem.cn( :total ),
+			:current => subsystem.cn( :current ),
+			:connections => connections.all,
+		}
+end
+
+
+get '/databases' do
+	subsystem = @monitor.cn( :databases )
+	databases = subsystem.
+		filter( :objectClass => :monitoredObject ).
+		select( :+, :* )
+
+	erb :databases,
+		:locals => {
+			:subsystem => subsystem,
+			:databases => databases,
+		}
+end
+
+
+get '/listeners' do
+	subsystem = @monitor.cn( :listeners )
+	listeners = subsystem.
+		filter( :objectClass => :monitoredObject ).
+		select( :+, :* )
+
+	erb :listeners,
+		:locals => {
+			:subsystem => subsystem,
+			:listeners => listeners,
+		}
+end
+
+
+### Fallback handler for subsystems
+get '/:subsystem' do
+	subsystem = @monitor.cn( params[:subsystem] )
+	contents = subsystem.
+		filter( :objectClass => :monitoredObject ).
+		select( :+, :* )
+
+	erb :dump_subsystem,
+		:locals => {
+			:subsystem => subsystem,
+			:contents => contents,
+		}
+end
+
+