[manpage_begin irc tclircc 0.0.1]
[titledesc {Library irc.tcl}]
[description]
[para]
This is a to-spec IRCv3 client library.
It is designed to be freely extracted.
[section {Getting a channel}]
[file irc.tcl] provides 2 ways to connect to an IRC server.
[subsection [concat [cmd irc::connect] [arg hostname] [arg port] [opt [arg usetls]]]]

Connects to [arg hostname]:[arg port], and sets up all the necessary state.
If [arg usetls] is set to true, the [package tls] module will be used to connect,
instead of the builtin [cmd socket] command. If unset, [cmd socket] will be used.

[para]
[sectref {Channel metadata}] is initialized with [arg proto], [arg hostname], [arg port], and [arg uri] set.
[subsection [concat [cmd irc::enroll] [arg chan] [opt [arg meta]]]]

Sets up the internal state necessary for chan to be used as an IRC socket.
It is called internally by [cmd irc::connect].
This command is exposed for the use-case where an IRC channel might have a more bespoke acquisition process than a simple socket connection.

[para]
[arg meta] is the initial state of the [sectref {channel metadata}].
[section {Listening to it}]
[file irc.tcl] provides an event dispatch system, via a [cmd fileevent] script registered on the IRC channel.
Events are dispatched by matching their patterns against incoming messages.
[subsection [concat [cmd irc::listen] [arg subcommand] [arg chan]]]
Enable or disable the [cmd fileevent] script for the dispatch system.

[list_begin definitions]
[call [cmd irc::listen] [const on] [arg chan]]
Apply the [cmd fileevent] wrapper to [arg chan].
Returns the previous [cmd fileevent] wrapper.
[call [cmd irc::listen] [const off] [arg chan]]
Remove the [cmd fileevent] wrapper from [arg chan].
Errors if the channel does not currently have the irc handler set.
[list_end]
[subsection [concat [cmd irc::listener] [arg subcommand] [arg chan] [opt [arg arg]...]]]
Configure [cmd listener]-type event handlers.
[para]
[cmd listener]-type handlers are scripts, executed in either a sub-interpreter or a seperate thread.
Interpreter listeners should yield themselves with [cmd after] during long operations, and never block for extended periods.
If that is infeasible, threaded listeners are recommended.
[para]
[cmd listener]-type scripts are spawned with the variable [var dispatch] set to the channel they are to recieve dispatches over.
Each line will be a [cmd dict] with contents as described in [sectref {Event Dispatch Contents}].
Interpreters are given access to the [sectref {Dispatch-aliased IRC commands}], while threads are given the variable [var parent], the ID of the main thread.
[para]
When a listener is removed, it will recieve a message of just [const end].
It should perform necessary cleanup quickly, as the application is likely exiting.
Threads may simply [cmd thread::release] themselves, while interps may call the provided [cmd selfdestruct].

[list_begin definitions]
[call [cmd irc::listener] [const add] [arg chan] [opt [option -thread]] [arg patlist] [arg script]]
Registers [arg script] as a [cmd listener]-type handler on [arg chan], using [arg patlist] as the [sectref {Message Pattern List}].
Returns an id that can be passed to [cmd irc::listener] [const remove] or [cmd irc::patlist].
[para]
If [option -thread] is passed, it will be created as a threaded listener, otherwise it will be created in a sub-interpreter.
[call [cmd irc::listener] [const remove] [arg chan] [arg id]]
Unregisters the listener identified by [arg id] from [arg chan].
[para]
Ignores requests for nonexistent handlers or handlers of the wrong type.
[list_end]
[subsection [concat [cmd irc::handler] [arg subcommand] [arg chan] [opt [arg arg]...]]]

[subsection [concat [cmd irc::is] [arg type] [arg value]]]
Validation helper.

[para]

[manpage_end]