hlirc is a High-Level IRC interface. It's modular and tries to implement most basic IRC features without undertaking too much. Instead it provides a few features for module interoperability making it easy to implement even low-level IRC features as modules and use them in other modules.
Please refer to the tests directory (
t) for a more practical approach to
It's an object (actually namespace) which maintains a single connection to an IRC server and contains modules implementing most of its behaviour.
Creates a new IRC object. It has several methods.
$irc config key ?value?
Set or get a global (i.e. not module-level) configuration value.
$irc module-eval name body
Evaluates some code in the namespace of a module. If the module name isn't
loaded yet then it is loaded upon evaluating
module-eval. Then the code is
executed in the module's namespace.
You can use it to create temporary modules too. Just make name an empty
string and enter the module's body. Note however that temporary modules can't
module except for
$irc log level text
Logs a message.
Disconnects from the server.
Disconnects then destroys the IRC object along with all loaded modules.
Returns true if the IRC object is currently connected.
There's also a way for modules to implement new commands which can be called
later using the IRC object. E.g.
connect is actually implemented in the
connection module's command which makes the IRC object connect to hostname and port specified in the module's config.
::hlirc::define-module name body
Defines a module. Module is basically a namespace and works just as you expect a TCL namespace to work. body can have a few special commands to configure the module in several ways. The following commands (mostly module subcommands) are valid only inside define-module body:
module require dependency
The dependency will always be loaded before this module. All messages will be processed by the dependency first before being handed to this module.
This command can be called anywhere inside a module, not just in its toplevel. It returns the full path to a module's own personal directory it can use for storing persistent data etc
module log level text
Logs a message with the module name.
module config key default comment
Defines a configuration value. It will be stored in the configuration file along with the comment. This command has another form which can be called anywhere:
module config key ?value?
It sets or returns (if value is omitted) the module's configuration value.
module wizard body
Defines a wizard to configure this module. It's just a Tcl script which will be
run during bot initial start to set the configuration values. A few commands
only available inside
query question ?default? ?predicate? ?error?
It displays question and waits for user input. predicate is then applied to user input and if it yields a false value the error message is displayed and the user is allowed to enter another value.
It's the interface to hlirc's command parser. To declare a command bot's users can execute on the channel use this command inside the module body:
command name help body
body is a Tcl script which will be executed when a user calls this command. It has one special command to parse the arguments:
match matchspecs body
If the command arguments match the matchsecs the body is executed with
specified arguments bound to local variables. If the arguments don't match the
body is skipped.
match returns true if the arguments match and false
machspecs is a list of matchspecs. Each matchspec can be one of the following:
- A name. The next argument is bound to a ariable with this name.
- A list starting with var. The list's second element should be a variable name. Processed exactly as the previous matchspec.
- A list starting with literal. The list's second ite should be a string which is expected to be at this point in the list of arguments. If there's no such string the match imediately fails.
- A list starting with optliteral. The second element is a string which may be at this point in the argument list.
- A list starting with optvar. Processed like var except if the arguments are already exhausted its value would be the list's third argument.
- A list starting with rest. The second item is a variable name to bind the list of remaining arguments to.
- A list with a single item end. It checks that all arguments are processed. If there are more arguments left the match fails.
There are two types of procedures which receive special treatment.
If a procedure name begins with
cmd- then it implements an extension method
for the IRC object this modules is loaded into.
If a procedure name begins with
do- then it implements an event handler.
Event names are the same as IRC message names and a few extra: connected and
Module built-in commands
Returns the IRC object this module is loaded into. Can be used to call methods or extension methods.
Works like Tcl 8.6's yield but remembers parsed IRC message and implements
timeout. Always use this instead of
yield inside handlers or commands.
A few of the commands can be called only inside a message handler. That is
command or a
CTCP action text.
Who sent the IRC message.
Message's target. Usually its first argument.
Return an additional argument or all of them if index is omitted.