


picoirc(n)       Simple embeddable IRC interface       picoirc(n)


______________________________________________________________________________

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 compo-
              nent parts. Returns a list of  server,  port  and  channel.  The
              default port is 6667 and there is no default channel.




irc                            0.5                              1





picoirc(n)       Simple embeddable IRC interface       picoirc(n)


       ::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.  How-
              ever,  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 mes-
              sage 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.



irc                            0.5                              2





picoirc(n)       Simple embeddable IRC interface       picoirc(n)


              NOTE: channel is often empty for these messages as nick  activi-
              ties  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





















irc                            0.5                              3


