1picoirc(n) Simple embeddable IRC interface picoirc(n)
2______________________________________________________________________________
6
8 picoirc - Small and simple embeddable IRC client.
9
11 package require Tcl 8.6
12 package require picoirc ?0.13.0?
14 ::picoirc::connect callback nick ?password? url
16 ::picoirc::post context channel message
18______________________________________________________________________________
20
22 This package provides a general purpose minimal IRC client suitable for
23 embedding in other applications. All communication with the parent ap‐
24 plication is done via an application provided callback procedure. Each
25 connection has its own state so you can hook up multiple servers in a
26 single application instance.
27 To initiate an IRC connection you must call picoirc::connect with a
29 callback procedure, a nick-name to use on IRC and the IRC URL that de‐
30 scribes the connection. This will return a variable name that is the
31 irc connection context. See CALLBACK for details.
32 This package is a fairly simple IRC client. If you need something with
34 more capability investigate the irc package.
35
37 ::picoirc::connect callback nick ?password? url
38 Creates a new irc connection to the server specified by url and
39 login using the nick as the username and optionally password.
40 If the url starts with ircs:// then a TLS connection is created.
41 The callback must be as specified in CALLBACK. Returns a pack‐
42 age-specific variable that is used when calling other commands
43 in this package.
44 Note: For connecting via TLS the Tcl module tls must be already
46 loaded, otherwise an error is raised.
47 # must be loaded for TLS
50 package require tls
51 # default arguments
52 tls::init -autoservername true -command workaround \
53 -require 1 -cadir /etc/ssl/certs -tls1 0 -tls1.1 0
54 # avoid annoying bgerror, errors are already catched internally
55 proc workaround {state args} {
56 if {$state == "verify"} {
57 return [lindex $args 3]
58 }
59 }
60 ::picoirc::post context channel message
63 This should be called to process user input and send it to the
64 server. If message is multiline then each line will be processed
65 and sent individually. A number of commands are recognised when
66 prefixed with a forward-slash (/). Such commands are converted
67 to IRC command sequences and then sent. If channel is empty then
68 all raw output to the server is handled. The default action is
69 to write the message to the irc socket. However, before this
70 happens the callback is called with "debug write". This permits
71 the application author to inspect the raw IRC data and if de‐
72 sired to return a break error code to halt further processing.
73 In this way the application can override the default send via
74 the callback procedure.
75
77 The callback must look like:
78 proc Callback {context state args} {
81 }
82 where context is the irc context variable name (in case you need to
84 pass it back to a picoirc procedure). state is one of a number of
85 states as described below.
86 init called just before the socket is created
88 connect
90 called once we have connected, before we join any channels
91 close called when the socket gets closed, before the context is
93 deleted. If an error occurs before we get connected the only ar‐
94 gument will be the socket error message.
95 userlist channel nicklist
97 called to notify the application of an updated userlist. This is
98 generated when the output of the NAMES irc command is seen. The
99 package collects the entire output which can span a number of
100 output lines from the server and calls this callback when they
101 have all been received.
102 userinfo nick info
104 called as a response of WHOIS command. nick is the user the com‐
105 mand was targeted for. info is the dictionary containing de‐
106 tailed information about that user: name, host, channels and
107 userinfo. userinfo typically contains name and version of
108 user's IRC client.
109 chat target nick message type
111 called when a message arrives. target is the identity that the
112 message was targetted for. This can be the logged in nick or a
113 channel name. nick is the name of the sender of the message.
114 message is the message text. type is set to "ACTION" if the mes‐
115 sage was sent as a CTCP ACTION. type is set to "NOTICE" if the
116 message was sent as a NOTICE command, in that case target is
117 empty if it matches current user nick or it's "*", in later case
118 empty target means that notice comes from server.
119 mode nick target flags
121 called when mode of user or channel changes. nick is the name of
122 the user who requested a change, can be empty if it's the
123 server. target is the identity that has its mode changed. flags
124 are the changes in mode.
125 system channel message
127 called when a system message is received
128 topic channel topic
130 called when the channel topic string is seen. topic is the text
131 of the channel topic.
132 traffic action channel nick ?newnick?
134 called when users join, leave or change names. action is either
135 entered, left or nickchange and nick is the user doing the ac‐
136 tion. newnick is the new name if action is nickchange.
137 NOTE: channel is often empty for these messages as nick activi‐
139 ties are global for the irc server. You will have to manage the
140 nick for all connected channels yourself.
141 version
143 This is called to request a version string to use to override
144 the internal version. If implemented, you should return as colon
145 delimited string as
146 Appname:Appversion:LibraryVersion
148 For example, the default is
150 PicoIRC:[package provide picoirc]:Tcl [info patchlevel]
152 debug type raw
154 called when data is either being read or written to the network
155 socket. type is set to read when reading data and write if the
156 data is to be written. raw is the unprocessed IRC protocol data.
157 In both cases the application can return a break error code to
159 interrupt further processing of the raw data. If this is a read
160 operation then the package will not handle this line. If the op‐
161 eration is write then the package will not send the data. This
162 callback is intended for debugging protocol issues but could be
163 used to redirect all input and output if desired.
164
166 rfc 1459
167
169 chat, irc
170
172 Networking
173tcllib 0.13.0 picoirc(n)