* irc.awk Documentation -*- mode: outline -*-
irc.awk is an IRC library written for GNU AWK.
*** irc_setup(host, port, nick, autojoin, user, realname, passwd)
This function must be called for initializing the library.
The first three arguments "host", "port" and "nick" are the only
necessary ones, and designate what host to connect to, via what port
and using what name. Port may contain the string "ssl" if the library
should connect to the port 6697 via an encrypted connection.
"autojoin" should be a string of channels the bit is to automatically
join, each separated by a white space. Alternatively, a preceding "!"
indicates that the bot is to join all channels it is invited into.
"user" and "realname" set the IRC user and real name.
"passwd" is used when the server requires a password to connect.
*** irc_join(chan, passwd)
Make the bot join "chan". Optionally, "passwd" may be passed if a
password is necessary.
*** irc_send(to, msg)
Send a PRIVMGS "msg" to user "to".
Send a PRIVMSG to the actor/channel that triggered the current event.
*** irc_quit(quitmsg, _msg, _len)
Terminate the current connection with message "quitmsg". The variables
_msg and _len are local variables that shouldn't set.
*** READ(pat, to)
True when the message body of the current even matches
"pat". Optionally the argument "to" ensures what channel this message
was directed at.
*** FROM(pat, to)
True when the current event was triggered by a user matching PAT.
Optionally the argument "to" ensures what channel this message was
*** JOINED(pat, to)
True when a user joined and their nick matches PAT. Optionally the
argument "to" ensures what channel this message was directed at.
True when the bot was mentioned. Optionally the argument "to" ensures
what channel this message was directed at.
If true, the bot joins every channel it is invited into. This is the
same behaviour as when irc_setup's "autojoin" parameter starts with an
A 2D "matrix" with metadata on all the channels. The first level
indexes channel names, the second level indexes attributes.
Currently the only attribute implemented is "topic".
Event-specific variable indicating in what channel an event took
Event-specific variable indicating who triggered the current event.
Event-specific variable containing the PRIVMSG message body, or a
false value if there is no message
Event-specific variable containing the "event" message body, such as
the reason a user left a channel.
Same function as MSG, just for NOTICE events.
Event-specific variable containing the channel name a user has been
Event-specific variable that is non-nil, when someone just joined a
Event-specific variable that is non-nil, when someone just parted a
Event-specific variable that is non-nil, when someone just quit a
Event-specific variable that is non-nil, when someone just kicked
from a channel.
** Internal variables and functions
All non-public parts of irc.awk are prefixed with "__irc_". While
accessible, they shouldn't be used/manipulated, as irc.awk neither
guarantees consistency between future and past versions, nor does it
expect these to be changed.
** Calling a irc.awk-based script
irc.awk handles an event on every new line. If one wants a bot to
continue for as long as possible, all that has to be done is to pipe
the output of "yes" into the standard input of the script:
$ yes | awk -f irc.awk -f bot.awk