thermodynambot
version 005
by b0at
public domain


See INSTALL for installation instructions.

See the comments in _thermodynambot.conf for full example entries.

See http://silenceisdefeat.org/~b0at/xchat/thermodynambot/
for the latest version.


User commands:
	TDB or THERMODYNAMBOT (no args)
		reload config
	TDBTEST <...>
		test an entry with arbitrary data (see /help TDBTEST)
	TDBECHO <...>
		same as tdbtest, but echos out command rather than 
		executing it (see /help TDBECHO)


Basic entry:
	[method:pattern]
	+in: locations
	-in: locations (optional)
	+from: users
	-from: users (optional)
	+mode: modes (optional)
	-mode: modes (optional)
	command: xchat command


method
	One of:
	
	regex
		A regular expression. see perlre, perlretut, perlrequick
		in perldoc (or perldoc.com). Use (?i) to enable case in-
		sensitivity. use ^ at the beginning of the pattern to
		anchor it to the start of the message, $ at the end to 
		anchor to the end of the message.
		
		Captures (in parentheses) are saved and accessible with
		the %1-%9 and %$ macros.
		
		example: [regex:(?i)foo$]
	
	text
		Wildcard-filtered text (see wildcards, below). It matches
		anywhere in the message.
		
		example: [text:bar *]
	
	line
		Wildcard-filtered text anchored to the beginning and end
		of the message. It must match the entire line to trigger.
	
		example: [line:!baz *]
		
wildcards
	One of * (zero or more characters) or ? (exactly one character).
	The contents of the message matched by wildcards are captured
	and saved in the %1-%9 and %$ macros.

+in/-in (or +where/-where, if that makes more sense to you)
	Require or exclude locations (wildcards allowed), which are 
	comma-separated lists. Any of the following may be combined.
	
	channels
		example: +in: #foob??
		example: +in: *
		         -in: #butnotthischannel
	
	networks with channels
		example: +in: efnet:*, mynet:#mychan
	
	private messages
		example: +in: private
		example: +in: efnet:private, *
	
	actions (require channels to be specified as well)
		example: +in: *, action
		example: +in: #mychan, action
	
+from/-from
	Require or exclude users (wildcards allowed), comma-sep lists.
	You may shorten just nicks to 'nick!' and just addresses to
	'@address'. Any of the following may be combined.
	
	example: +from: foo*!*bar@baz
	example: +from: *
				-from: bob!, @*bob.com
	example: +from: *!bill@*.bill.net
	
	Optionally, you may use a regular expression. Prefix any mask
	in the list with an ampersand ('&').
	
	example: +from: *
	         -from: &([^!]+)!~\1@.+

+mode/-mode
	Require or exclude users with specific modes (no wildcards).
	Use 'none' to select users with no mode. Note that only the
	visible mode will match (eg a user with +o and +v will only 
	have a prefix with the oper char, eg @). Arbitrary-length and
	charcter modes are supported if the network and xchat support
	them.
	
	example: -mode: none
	example: +mode: @,%,+

command
	An xchat command to execute. Any number of commands are allowed.
	Especially handy for this is exec [-o], which could even be used
	to modify tdb's own configuration file.
	
	The command is executed in the context of the event. That means 
	that responses go in the right place.
	
	Some macros of the form %. are expanded in commands:
		%n		user's nick name
		%u		user's user name (ident)
		%a		user's address
		%c		channel where event took place (or their nick if in private)
		%o		user's mode in the channel (empty if private)
		%w		network name (or server name)
		%m		own nick name
		%d		current local date
		%y		current gmt date
				(in '%Y/%m/%d' format from strftime)
		%t		current local time 
		%z		current gmt (zulu) time
				(in '%H:%M:%S' format from strftime)
		%s		full text
		%1 to %9 
				capture or wildcard match (or empty)
		%$		last capture, if any (otherwise empty)
     
		%%		single percent sign %
     
     Color codes (%B, %C, %U, %V for reverse, %O for reset) are 
			interpreted correctly. They must be upper case.

     Unmatched macros are removed. eg, '%q' expands to '' --
     	to output '%q' use '%%q'
     	
	If an entry may be triggered by a public (channel) or a private
	event, then use 'msg %c' to respond rather than just 'say', which
	would print the response to the channel even if it was supposed
	to go to the other party privately.
	
	example: command: say %n (actually %u@%a) triggered this event.
	example: command: exec -o /path/to/program
	example: command: exec -o perl -lwe 'some_great_one-liner();'


2004/11/15