---
name: "picoirc"
section: "3tcl"
platform: "linux"
package: "tcllib"
version: "2.0+dfsg-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/picoirc"
---

# picoirc(3tcl)

Small and simple embeddable IRC client.

```

```

## NAME

picoirc - Small and simple embeddable IRC client.

## SYNOPSIS

package require **Tcl 8.6 9**

package require **picoirc ?0.14.0?**

**::picoirc::connect** *callback* *nick* ?*password*? *url*

**::picoirc::post** *context* *channel* *message*

```

```

## DESCRIPTION

This package provides a general purpose minimal IRC client suitable for embedding in other applications. All communication with the parent application is done via an application provided callback procedure. Each connection has its own state so you can hook up multiple servers in a single application instance.

To initiate an IRC connection you must call **picoirc::connect** with a callback procedure, a nick-name to use on IRC and the IRC URL that describes the connection. This will return a variable name that is the irc connection context. See **CALLBACK** for details.

This package is a fairly simple IRC client. If you need something with more capability investigate the **irc** package.

## COMMANDS

- **::picoirc::connect** *callback* *nick* ?*password*? *url*

  Creates a new irc connection to the server specified by *url* and login using the *nick* as the username and optionally *password*.  If the *url* starts with *ircs://* then a TLS connection is created. The *callback* must be as specified in **CALLBACK**.  Returns a package-specific variable that is used when calling other commands in this package.

  *Note:* For connecting via TLS the Tcl module *tls* must be already loaded, otherwise an error is raised.

  ```
  # must be loaded for TLS
  package require tls
  # default arguments
  tls::init -autoservername true -command workaround \
      -require 1 -cadir /etc/ssl/certs -tls1 0 -tls1.1 0
  # avoid annoying bgerror, errors are already catched internally
  proc workaround {state args} {
      if {$state == "verify"} {
          return [lindex $args 3]
      }
  }
  ```

- **::picoirc::post** *context* *channel* *message*

  This should be called to process user input and send it to the server. If *message* is multiline then each line will be processed and sent individually. A number of commands are recognised when prefixed with a forward-slash (/). Such commands are converted to IRC command sequences and then sent. If *channel* is empty then all raw output to the server is handled. The default action is to write the *message* to the irc socket. However, before this happens the callback is called with "debug write". This permits the application author to inspect the raw IRC data and if desired to return a break error code to halt further processing. In this way the application can override the default send via the callback procedure.

## CALLBACK

The callback must look like:

```
proc Callback {context state args} {
}
```

where context is the irc context variable name (in case you need to pass it back to a picoirc procedure). state is one of a number of states as described below.

- **init**

  called just before the socket is created

- **connect**

  called once we have connected, before we join any channels

- **close**

  called when the socket gets closed, before the context is deleted. If an error occurs before we get connected the only argument will be the socket error message.

- **userlist** *channel* *nicklist*

  called to notify the application of an updated userlist. This is generated when the output of the NAMES irc command is seen. The package collects the entire output which can span a number of output lines from the server and calls this callback when they have all been received.

- **userinfo** *nick* *info*

  called as a response of WHOIS command. *nick* is the user the command was targeted for. *info* is the dictionary containing detailed information about that user: name, host, channels and userinfo. userinfo typically contains name and version of user's IRC client.

- **chat** *target* *nick* *message* *type*

  called when a message arrives. *target* is the identity that the message was targetted for. This can be the logged in nick or a channel name. *nick* is the name of the sender of the message. *message* is the message text. *type* is set to "ACTION" if the message was sent as a CTCP ACTION. *type* is set to "NOTICE" if the message was sent as a NOTICE command, in that case *target* is empty if it matches current user nick or it's "\*", in later case empty *target* means that notice comes from server.

- **mode** *nick* *target* *flags*

  called when mode of user or channel changes. *nick* is the name of the user who requested a change, can be empty if it's the server. *target* is the identity that has its mode changed. *flags* are the changes in mode.

- **system** *channel* *message*

  called when a system message is received

- **topic** *channel* *topic*

  called when the channel topic string is seen. *topic* is the text of the channel topic.

- **traffic** *action* *channel* *nick* ?*newnick*?

  called when users join, leave or change names. *action* is either entered, left or nickchange and *nick* is the user doing the action. *newnick* is the new name if *action* is nickchange.

  *NOTE*: *channel* is often empty for these messages as nick activities are global for the irc server. You will have to manage the nick for all connected channels yourself.

- **version**

  This is called to request a version string to use to override the internal version. If implemented, you should return as colon delimited string as

  Appname:Appversion:LibraryVersion

  For example, the default is

  PicoIRC:\[package provide picoirc\]:Tcl \[info patchlevel\]

- **debug** *type* *raw*

  called when data is either being read or written to the network socket. *type* is set to **read** when reading data and **write** if the data is to be written. *raw* is the unprocessed IRC protocol data.

  In both cases the application can return a break error code to interrupt further processing of the raw data. If this is a **read** operation then the package will not handle this line. If the operation is **write** then the package will not send the data. This callback is intended for debugging protocol issues but could be used to redirect all input and output if desired.

## SEE ALSO

rfc 1459

## KEYWORDS

chat, irc

## CATEGORY

Networking