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 documentation.


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 call module except for module require.

$irc log level text

Logs a message.

$irc disconnect

Disconnects from the server.

$irc destroy

Disconnects then destroys the IRC object along with all loaded modules.

$irc connected

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.

$irc connect

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.

module datadir

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 module wizard.

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 otherwise.

machspecs is a list of matchspecs. Each matchspec can be one of the following:

  1. A name. The next argument is bound to a ariable with this name.
  2. A list starting with var. The list's second element should be a variable name. Processed exactly as the previous matchspec.
  3. 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.
  4. A list starting with optliteral. The second element is a string which may be at this point in the argument list.
  5. A list starting with optvar. Processed like var except if the arguments are already exhausted its value would be the list's third argument.
  6. A list starting with rest. The second item is a variable name to bind the list of remaining arguments to.
  7. A list with a single item end. It checks that all arguments are processed. If there are more arguments left the match fails.

Special procs

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 eof.

Module built-in commands


Returns the IRC object this module is loaded into. Can be used to call methods or extension methods.

yield-irc ?timeout?

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 either a command or a do--proc except do-eof and do-connected.


CTCP action text.


IRC message.


Who sent the IRC message.


Message's target. Usually its first argument.

additional ?index?

Return an additional argument or all of them if index is omitted.