---
toc: false
---

[//000000001]: # (irc \- )
[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown')
[//000000003]: # (irc\(tclircc\) 0\.0\.1  "")

# NAME

irc \- Library irc\.tcl

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [Getting a channel](#section2)

      - [__irc::connect__ *hostname* *port*
        ?*usetls*?](#subsection1)

      - [__irc::enroll__ *chan* ?*meta*?](#subsection2)

  - [Listening to it](#section3)

      - [__irc::listen__ *subcommand* *chan*](#subsection3)

      - [__irc::listener__ *subcommand* *chan*
        ?*arg*\.\.\.?](#subsection4)

      - [__irc::handler__ *subcommand* *chan*
        ?*arg*\.\.\.?](#subsection5)

      - [__irc::is__ *type* *value*](#subsection6)

# <a name='synopsis'></a>SYNOPSIS

[__irc::listen__ __on__ *chan*](#1)  
[__irc::listen__ __off__ *chan*](#2)  
[__irc::listener__ __add__ *chan* ?__\-thread__? *patlist* *script*](#3)  
[__irc::listener__ __remove__ *chan* *id*](#4)  

# <a name='description'></a>DESCRIPTION

This is a to\-spec IRCv3 client library\. It is designed to be freely extracted\.

# <a name='section2'></a>Getting a channel

"irc\.tcl" provides 2 ways to connect to an IRC server\.

## <a name='subsection1'></a>__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,
instead of the builtin __socket__ command\. If unset, __socket__ will be
used\.

__Channel metadata__ is initialized with *proto*, *hostname*, *port*,
and *uri* set\.

## <a name='subsection2'></a>__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 command is exposed for the
use\-case where an IRC channel might have a more bespoke acquisition process than
a simple socket connection\.

*meta* is the initial state of the __channel metadata__\.

# <a name='section3'></a>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
against incoming messages\.

## <a name='subsection3'></a>__irc::listen__ *subcommand* *chan*

Enable or disable the __fileevent__ script for the dispatch system\.

  - <a name='1'></a>__irc::listen__ __on__ *chan*

    Apply the __fileevent__ wrapper to *chan*\. Returns the previous
    __fileevent__ wrapper\.

  - <a name='2'></a>__irc::listen__ __off__ *chan*

    Remove the __fileevent__ wrapper from *chan*\. Errors if the channel
    does not currently have the irc handler set\.

## <a name='subsection4'></a>__irc::listener__ *subcommand* *chan* ?*arg*\.\.\.?

Configure __listener__\-type event handlers\.

__listener__\-type handlers are scripts, executed in either a sub\-interpreter
or a seperate thread\. Interpreter listeners should yield themselves with
__after__ during long operations, and never block for extended periods\. If
that is infeasible, threaded listeners are recommended\.

__listener__\-type scripts are spawned with the variable __dispatch__ set
to the channel they are to recieve dispatches over\. Each line will be a
__dict__ with contents as described in __Event Dispatch Contents__\.
Interpreters are given access to the __Dispatch\-aliased IRC commands__,
while threads are given the variable __parent__, the ID of the main thread\.

When a listener is removed, it will recieve a message of just __end__\. It
should perform necessary cleanup quickly, as the application is likely exiting\.
Threads may simply __thread::release__ themselves, while interps may call
the provided __selfdestruct__\.

  - <a name='3'></a>__irc::listener__ __add__ *chan* ?__\-thread__? *patlist* *script*

    Registers *script* as a __listener__\-type handler on *chan*, using
    *patlist* as the __Message Pattern List__\. Returns an id that can be
    passed to __irc::listener__ __remove__ or __irc::patlist__\.

    If __\-thread__ is passed, it will be created as a threaded listener,
    otherwise it will be created in a sub\-interpreter\.

  - <a name='4'></a>__irc::listener__ __remove__ *chan* *id*

    Unregisters the listener identified by *id* from *chan*\.

    Ignores requests for nonexistent handlers or handlers of the wrong type\.

## <a name='subsection5'></a>__irc::handler__ *subcommand* *chan* ?*arg*\.\.\.?

## <a name='subsection6'></a>__irc::is__ *type* *value*

Validation helper\.