@@ 9,12 9,12 @@ message-parsing, message validation, channel management, event
dispatch, and various utilities listed below.
-## Getting a channel
+# Getting a channel
`irc.tcl` provides 2 ways to connect to an IRC server.
-### `irc::connect `*`hostname port ?usetls?`*
+## `irc::connect `*`hostname port ?usetls?`*
Connects to `hostname:port`, and sets up all the necessary state. If
usetls is set to true, the **`tls`** module will be used to connect,
@@ 22,7 22,7 @@ instead of the builtin **`socket`** command. If unset, **`socket`**
will be used.
-### `irc::enroll `*`chan ?meta?`*
+## `irc::enroll `*`chan ?meta?`*
Sets up the internal state necessary for `chan` to be
used as an IRC socket. It is called internally by **`irc::connect`**. This
@@ 30,29 30,29 @@ command is exposed for the use-case where an IRC channel might have a
more bespoke acquisition process than a simple socket connection.
-## Listening to it
+# Listening to it
`irc.tcl` provides an event dispatch system, via a **`fileevent`**
script registered on the IRC channel. Events are dispatched by matching
their [patterns](#message-pattern-lists) against incoming messages.
-### `irc::listen `*`subcommand chan`*
+## `irc::listen `*`subcommand chan`*
Enable or disable the **`fileevent`** script for the dispatch system.
-#### `irc::listen` `on `*`chan`*
+### `irc::listen` `on `*`chan`*
Apply the **`fileevent`** wrapper to `chan`. Returns the previous
**`fileevent`** wrapper.
-#### `irc::listen` `off `*`chan`*
+### `irc::listen` `off `*`chan`*
Remove the **`fileevent`** wrapper from `chan`. Errors if it is not the
irc wrapper.
-### `irc::listener `*`subcommand chan ?args ...?`*
+## `irc::listener `*`subcommand chan ?args ...?`*
Configure listener-type event handlers.
@@ 76,18 76,18 @@ should perform necessary cleanup quickly, and return, as the
application is likely exiting, and it may not be re-executed if it
yields.
-#### `irc::listener add `*`chan patlist script`*
+### `irc::listener add `*`chan patlist script`*
Registers `script` as a listener-type handler on `chan`, matching
`patlist` as [described below](#message-pattern-lists). Returns an id
that can be passed to **`irc::listener remove`** or **`irc::patlist`**.
-#### `irc::listener remove `*`chan id`*
+### `irc::listener remove `*`chan id`*
Unregisters the listener identified by `id` from `chan`.
-### `irc::handler `*`subcommand chan ?args ...?`*
+## `irc::handler `*`subcommand chan ?args ...?`*
Configure handler-type event handlers.
@@ 110,7 110,7 @@ When a handler is removed, if it has a stored interpreter, it will be
deleted. Applications with persistent state should take care to store
it to disk after each command, or use one of the other dispatch types.
-#### `irc::handler add `*`chan patlist script ?interp?`*
+### `irc::handler add `*`chan patlist script ?interp?`*
Registers `script` as a handler-type handler on `chan`, matching
`patlist` as [described below](#message-pattern-lists). Returns an id
@@ 122,12 122,12 @@ performed on internally created interpreters will be performed, once, on
the supplied interpreter, and `dispatch` will be set just before
executing `script`.
-#### `irc::extern remove `*`chan id`*
+### `irc::extern remove `*`chan id`*
Unregisters the extern handler identified by `id` from `chan`.
-### `irc::extern `*`subcommand chan ?args ...?`*
+## `irc::extern `*`subcommand chan ?args ...?`*
Configure extern-type event handlers.
@@ 144,19 144,19 @@ be written to it. The dispatch pipe is never closed by `irc.tcl`. The
reply pipe will be closed immediately. Ensure code that uses multiple
handlers accounts for this.
-#### `irc::handler add `*`chan patlist ochan ichan`*
+### `irc::handler add `*`chan patlist ochan ichan`*
Registers `ochan` and `ichan` as the dispatch and reply pipes of a
extern-type handler on `chan`, matching `patlist` as
[described below](#message-pattern-lists). Returns an id that can
be passed to **`irc::extern remove`** or **`irc::patlist`**.
-#### `irc::extern remove `*`chan id`*
+### `irc::extern remove `*`chan id`*
Unregisters the extern handler identified by `id` from `chan`.
-### `irc::patlist `*`chan id ?patlist?`*
+## `irc::patlist `*`chan id ?patlist?`*
Get or set the [message pattern list](message-pattern-list) for handler
`id` on `chan`. If `patlist` is supplied, it will override the current
@@ 164,7 164,7 @@ one and return `patlist`, otherwise it will return the current pattern
list.
-### Message Pattern Lists
+## Message Pattern Lists
Message pattern lists are lists of lists of **`string match`**
patterns. Messages are matched on the command and the first N-1 params,
@@ 173,7 173,7 @@ all match, the match succeeds. If a message is shorter than a pattern,
the match fails. If any of the message patterns in the message pattern
list for a handler match, the handler is called.
-#### Message Pattern List Examples:
+### Message Pattern List Examples:
```tcl
# pattern:
@@ 232,7 232,7 @@ PING foo
# matches
```
-### Event Dispatch Contents
+## Event Dispatch Contents
The event dispatch dictionary contains the following properties:
@@ 246,7 246,7 @@ The event dispatch dictionary contains the following properties:
- `params`: the params of the message
- `meta`: channel metadata, such as server hostname
-### Dispatch-aliased `irc` Comands
+## Dispatch-aliased `irc` Comands
In `listener` and `handlers`, the following commands are aliased: