1picoirc(n) Simple embeddable IRC interface picoirc(n)
2______________________________________________________________________________
6
8 picoirc - Small and simple embeddable IRC client.
9
11 package require Tcl
12 package require picoirc ?0.5.2?
14 ::picoirc::connect callback nick url
16 ::picoirc::post context channel message
18 ::picoirc::splituri uri
20 ::picoirc::send context line
22______________________________________________________________________________
24
26 This package provides a general purpose minimal IRC client suitable for
27 embedding in other applications. All communication with the parent
28 application is done via an application provided callback procedure.
29 Each connection has its own state so you can hook up multiple servers
30 in a single application instance.
31 To initiate an IRC connection you must call picoirc::connect with a
33 callback procedure, a nick-name to use on IRC and the IRC URL that
34 describes the connection. This will return a variable name that is the
35 irc connection context. See CALLBACK for details.
36 This package is a fairly simple IRC client. If you need something with
38 more capability investigate the irc package.
39
41 ::picoirc::connect callback nick url
42 Create a new irc connection to the server specified by url and
43 login using the nick as the username. The callback must be as
44 specified in CALLBACK. Returns a package-specific variable that
45 is used when calling other commands in this package.
46 ::picoirc::post context channel message
48 This should be called to process user input and send it to the
49 server. A number of commands are recognised when prefixed with a
50 forward-slash (/). Such commands are converted to IRC command
51 sequences and then sent.
52 ::picoirc::splituri uri
54 Splits an IRC scheme uniform resource indicator into its compo‐
55 nent parts. Returns a list of server, port and channel. The
56 default port is 6667 and there is no default channel.
57 ::picoirc::send context line
59 This command is where all raw output to the server is handled.
60 The default action is to write the line to the irc socket. How‐
61 ever, before this happens the callback is called with "debug
62 write". This permits the application author to inspect the raw
63 IRC data and if desired to return a break error code to halt
64 further processing. In this way the application can override the
65 default send via the callback procedure.
66
68 The callback must look like:
69 proc Callback {context state args} {
72 }
73 where context is the irc context variable name (in case you need to
75 pass it back to a picoirc procedure). state is one of a number of
76 states as described below.
77 init called just before the socket is created
79 connect
81 called once we have connected, before we join any channels
82 close called when the socket gets closed, before the context is
84 deleted. If an error occurs before we get connected the only
85 argument will be the socket error message.
86 userlist channel nicklist
88 called to notify the application of an updated userlist. This is
89 generated when the output of the NAMES irc command is seen. The
90 package collects the entire output which can span a number of
91 output lines from the server and calls this callback when they
92 have all been received.
93 chat target nick message type
95 called when a message arrives. target is the identity that the
96 message was targetted for. This can be the logged in nick or a
97 channel name. nick is the name of the sender of the message.
98 message is the message text. type is set to "ACTION" if the mes‐
99 sage was sent as a CTCP ACTION
100 system channel message
102 called when a system message is received
103 topic channel topic
105 called when the channel topic string is seen. topic is the text
106 of the channel topic.
107 traffic action channel nick ?newnick?
109 called when users join, leave or change names. action is either
110 entered, left or nickchange and nick is the user doing the
111 action. newnick is the new name if action is nickchange.
112 NOTE: channel is often empty for these messages as nick activi‐
114 ties are global for the irc server. You will have to manage the
115 nick for all connected channels yourself.
116 version
118 This is called to request a version string to use to override
119 the internal version. If implemented, you should return as colon
120 delimited string as
121 Appname:Appversion:LibraryVersion
123 For example, the default is
125 PicoIRC:[package provide picoirc]:Tcl [info patchlevel]
127 debug type raw
129 called when data is either being read or written to the network
130 socket. type is set to read when reading data and write if the
131 data is to be written. raw is the unprocessed IRC protocol data.
132 In both cases the application can return a break error code to
134 interrupt further processing of the raw data. If this is a read
135 operation then the package will not handle this line. If the
136 operation is write then the package will not send the data. This
137 callback is intended for debugging protocol issues but could be
138 used to redirect all input and output if desired.
139
141 rfc 1459
142
144 chat, irc
145
147 Networking
148tcllib 0.5.2 picoirc(n)