$Id: SCRIPT-FORMAT,v 1.3 2005/06/30 16:40:11 bbrazil Exp $
Config-file syntax for RegressIRC
Copyright Brian Brazil<bbrazil@netsoc.tcd.ie> 2005

Any line starting with a # is considered a comment and will be ignored. Lins
containing only whitespace are also ignored. The various classes of command are
sorted alphabetically below. Note that for evey class except 'recv', the line
will be printed when it is processed. 'replace' lines will be preceded by a #,
so that it won't be applied again if the output is run as a script.

Everything is case-sensitive. Virtually everything is lowercase.

Recv stops processing of lines until it gets the event it wants - beware that
if you have a few sends in a row, any events generated by them will be queued.

A line may be prefixed with 'label:'. Each label specifies a different
connection. The label 'sticks' until the next use of a label. The initial label
is set to 'default'.

***************
*Sample script*
***************

#This script is for hybrid7 on Debian Sarge, your ircd may vary
#implicit line
default: events ERRORS
echo Sample RegressIRC Script by Brian Brazil
#don't ask...
replace %SERVER% hybrid7.debian.local
replace %MYHOST% i.love.debian.org
replace %MYIDENT% regress

events + endofmotd
connect localhost 6667 regress regress
recv endofmotd End of /MOTD command.

events ERRORS join part topic disconnect namreply endofnames public
#assume #test already exists and contains @bbrazil
send join #test
recv join regress #test
recv topic #test Some old topic
recv namreply #test @bbrazil regress
recv endofnames #test End of /NAMES list.

sleep 5
send msg #test hi all
recv public bbrazil/#test lo regress
#we're being oped
recv mode bbrazil/#test +o regress
send topic #test Brand new topic
recv topic regress/#test Brand new topic

sleep 5

parallel: events + endofmotd disconnect
#connect line implicitly has a label of 'parallel'
connect localhost 6667 regress2 regress
recv endofmotd End of /MOTD command.
send quit bye bye all
recv disconnect (Quit: bye bye all)

default: send part #test
recv part regress #test
send quit bye bye all
recv disconnect (Quit: bye bye all)

end

*********
*connect*
*********

connect host port nickname username

Connects to a server with the given parameters. Username is the ident.

You can (presently) only connect to one server at a time. Running multiple
scripts in parallel is one way of getting around this.

The realname is always set to 'IRC regression tester' (or something similar).

Example
connect localhost 6667 bbrazil 

******
*echo*
******

echo message

Prints the line as-is when it comes to it.

Example:
echo Starting stage 2

*****
*end*
*****

end

Terminates execution. Your script should finish with an 'end', falling out the
bottom will egnerate an error.  Any input after an end will be ignored.

Example:
end

********
*events*
********

events event1 [event2] ...
events + event_to_add1 [event_to_add2] ...
events - event_to_remove1 [event_to_remove2] ...

Specifies what events we want to recv. The first form sets exactly which events
we want. The second and thrd add and remove events from the current events.
Valid values are any type of recv and the special value ERRORS.

Is initalised to the special value ERRORS which is all 4xx and 5xx which are in
Net::IRC::Event::_names, all normal values are in lowercase.

Example:
events ERRORS public msg
events - msg
events + mode 

******
*recv*
******

General form:
recv type [args]

Relating to nicknames/channel:
recv join nickname #channel
recv mode #channel +-mode		#set by server
recv mode nickname/#channel +-mode	#set by user
recv msg nickname message
recv nick oldnickname newnickname
recv notice nickname message
recv part nickname #channel
recv public nickname/#channel message	#normal chat
recv topic #channel the_topic
recv topic nickname/#channel the_topic
recv namreply #channel nickname_list

Special:
recv IGNOREARGS [type]			#Will recv anything, optionally of the given type

Other types of note: disconnect, endofmotd, endofnames
Args, messages and topics are arbritary text.
Error_type could be something like 'needmoreparams' or 'noprivileges'.


Recv waits for a event of the specified type and with the same args before
continuing to parse input. 


Exmaple:
recv notice NickServ Password accepted - you are now recognized
recv join regress #test
recv topic #test Isn't this a great topic?
recv namreply #test @bbrazil regress
recv endofnames #test End of /NAMES list.
recv public bbrazil/#test hello regress


*********
*replace*
*********

replace old [new]

Does a simple string replacement on a line. If new is not specified, it
replaces old with nothing. New may contain spaces.

This will not affect comments. All other input will undergo replacment
(including subsequent 'replace' lines).

Example:
replace %HOST% localhost
replace NAME Brian Brazil

******
*send*
******

General form:
send type [args]

send join #channel				#no support for keys yet
send kick #channel nickname [kick_message]	#message defaults to nickname
send mode #channel +-mode
send msg nickname message			#msg in recv
send msg #channel message			#public in recv
send raw args					#send raw to the server
send part #channel [part_message]		#defaults to 'Leaving'
send topic #channel new_topic
send quit [quit message]			#defaults to something, I forget what

Sends a command to the server. Raw can be used if a given command isn't
implemented, or you need more control.

Example:
send msg #test hi #test
send msg nickserv help identify
send kick #test lamer Be lame elsewhere
send raw rehash

*******
*sleep*
*******

sleep time

Halts execution for the specified time. Probably not a good idea to sleep too
long while connected to a server as the connection could timeout. Time is a
positive integer, in seconds.

Example:
sleep 10