NAME

       picoirc - Small and simple embeddable IRC client.

SYNOPSIS

       package require Tcl

       package require picoirc  ?0.5?

       ::picoirc::connect callback nick url

       ::picoirc::post context channel message

       ::picoirc::splituri uri

       ::picoirc::send context line

________________________________________________________________________________________________________________

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 url
              Create a new irc connection to the server specified by  url  and  login  using  the  nick  as  the
              username.  The callback must be as specified in CALLBACK. Returns a package-specific variable that
              is used when calling other commands in this package.

       ::picoirc::post context channel message
              This should be called to process user input and send it to the server. A number  of  commands  are
              recognised  when  prefixed  with  a  forward-slash (/). Such commands are converted to IRC command
              sequences and then sent.

       ::picoirc::splituri uri
              Splits an IRC scheme uniform resource indicator into  its  component  parts.  Returns  a  list  of
              server, port and channel. The default port is 6667 and there is no default channel.

       ::picoirc::send context line
              This  command is where all raw output to the server is handled. The default action is to write the
              line 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.

       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

       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

tcllib                                                 0.5                                         picoirc(3tcl)