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