1 sirc, by orabidoo <roger.espel.llima@pobox.com>
2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4
5
6This is a simple (well, not so simple anymore *grin*) irc client,
7written in perl and C.
8
9It's divided in two parts, a dumb-mode (meaning, no full screen
10interface) client, dsirc, that can be used stand-alone, programmed in
11perl, and a separate split-screen front end in C, called ssfe.
12
13The main point of running this client is that you can get a reasonable
14ircII-like interface on an account with a properly installed perl
15interpreter, with the perl client taking about 60k (and it's usable on
16its own if you don't have access to a C compiler) and with the
17interface, once compiled, taking just another 30 or 40k. The two
18together, while lacking the huge complexity of ircII, make a very usable
19client. And if you know perl, you'll find you can do quite complicated
20and interesting things with sirc too :)
21
22
23
24## Files:
25
26README - this one
27README.socks - information about using sirc with a socks proxy
28ChangeLog - the list of changes in different versions
29PROGRAMMING - documentation for programming within sirc (scripting)
30install - installation script - will setup everything for you
31dsirc - the dumb-mode client itself
32n0thing.pl - a script for sirc
33sirc.help.gz - sirc's help file. sirc can read it in compressed (.gz)
34 format, so there is no need to gunzip it here
35ssfe.c - source code for the front end
36socks.pl - module with the socks proxy support
37sirc.1 - man page for sirc
38ssfe.1 - man page for ssfe
39
40
41## Installation:
42
43If you're reading this, we'll assume that you've already uncompressed
44the sirc.tar.gz file, and de-tared it, and you have all of these files a
45directory, and it is your current directory.
46
47Then just type ./install, and follow the instructions. In any case, if
48you don't know what to answer to something the installation script is
49asking you, just press Enter to use the default answer.
50
51Once your dsirc and ssfe are working, the files you need to run the
52client are:
53
54 dsirc - the client
55 n0thing.pl - the irc script, if you want it
56 sirc - little shell script to start the client
57 ssfe - the front end, if you want it
58 sircsock.ph - if the install script created it
59 getopts.pl - if it had to create it
60 socks.pl - if you want the socks proxy support
61 sirc.help.gz - if you want the online help
62
63This brings the client to around 150k with everything, or 100k with the
64client, the front-end and the help, or 65k with the dumb-mode client and
65the help, or 60k without the help.
66
67If you have enough disk space, you're encouraged to keep everything,
68including the doc files README and PROGRAMMING.
69
70For the client to work properly, the files "sirc.help.gz" and
71"sircsock.ph" and "getopts.pl" (if you have them) must be in the same
72directory as the main "dsirc" file.
73
74You never need to uncompress sirc.help.gz, as the client is smart enough
75to read it compressed.
76
77
78## Invoking the client:
79
80To run sirc: sirc [<options>] [<nick> [<server>]]
81
82Options are:
83
84 -d - dumb mode (don't use ssfe) : must be the first option
85 -p <number> - specify port number
86 -i <name> - specify IRCNAME
87 -n <nick> - specify nickname (sorta useless as an option, you can
88 specify that without the -n)
89 -s <server> - specify server (sorta useless as an option too)
90 -l <filename> - specify file to be loaded instead of ~/.sircrc.pl
91 -L <filename> - specify file to be loaded instead of ~/.sircrc
92 -H - specify virtual host IP to bind to
93 -q - don't load ~/.sircrc or ~/.sircrc.pl
94 -Q - don't load system sircrc or sircrc.pl
95 -R - run in restricted (secure) mode
96 -8 - run in 8-bit mode (do not translate iso-latin-1 to ASCII)
97
98
99Example:
100 sirc -i "my ircname" blurfer anarchy.tamu.edu
101
102To run dsirc directly without using the "sirc" shell-script:
103
104 [ssfe] [ssfe options] [perl] dsirc [<options>] [<nick> [<server>]]
105
106As usual, arguments between [] are optional.
107
108In restricted mode, sirc does not allow any access to files; the commands
109LOAD, EVAL, CD, SYSTEM, DCC GET, DCC SEND are disallowed, as well as
110running a .sircrc.pl and logging.
111
112You can specify options for ssfe's operation in the environment variable
113SSFE, since it's not possible to mix options for dsirc and for ssfe in
114the same command-line using the "sirc" script.
115
116So if you want beeps on by default, you should add the line
117"setenv SSFE '-beep'" to your .login, or the line
118"SSFE='-beep' ; export SSFE" to your .profile.
119
120
121In case dsirc (or whatever program you run in ssfe) gets stuck, remember
122the combination of keys that will cause ssfe to exit: ^x c (i.e.
123Control-X followed by C). When running in dumb mode, sirc can be
124interrupted by pressing ^c (Control-C).
125
126
127
128## Recognized shell variables:
129
130SIRCSERVER, IRCSERVER - server to use, optionally followed by a port
131 and a password, in the form server:port:pass;
132 overriden by -s or the second command-line
133 option; defaults to us.undernet.org
134
135SIRCPORT, IRCPORT - port to connect to if not specified in the
136 server, overriden by -p, defaults to 6667
137
138SIRCNAME, IRCNAME - information between ()'s in the /whois,
139 defaults to "sirc user"
140
141SIRCNICK, IRCNICK - nickname to use, defaults to your username
142
143SIRCRC - file to load instead of ~/.sircrc
144
145SIRCRCPL - file to load instead of ~/.sircrc.pl
146
147IRCFINGER - reply to CTCP FINGER, defaults to
148 "keep your fingers to yourself"
149
150USERINFO - reply to CTCP USERINFO, defaults to
151 "yep, i'm a user"
152
153SSFE - options for ssfe, if you're using it. set it
154 to "-beep" to have beep on, or to "-hold" to
155 have hold-mode on, or to "-prompt '> '" to
156 have "> " as a prompt, or any combination of
157 such options
158
159 this variable is read by the "sirc" script,
160 not by dsirc or ssfe itself
161
162SIRCHOST, IRCHOST, - which host IP to use, on machines with several
163LOCALHOST IP addresses
164
165
166## Using it:
167
168sirc has been designed to look a lot like ircII, while staying as simple
169and small as possible. A number of things which are usually defined as
170aliases with ircII are builtin with sirc, to make it more usable.
171
172sirc is undernet-friendly, /silence, /map, and even /rping and /uping
173are there.
174
175sirc's screen presentation of messages, talk lines, server lines,
176and sirc's own messages follows these conventions:
177
178 <nick> blah blah blah <- person spoke on a channel
179 <yournick> blah blah blah <- you spoke on a channel (your nick will
180 be underlined or colored)
181 * nick someaction <- person did a /me
182 * yournick someaction <- you did a /me (your nick will be underlined
183 or somehow colored)
184 [nick] blah blah blah <- you got a private message (the nick will
185 be in bold)
186 >nick< blah blah blah <- you sent a private message (the nick
187 will be in bold)
188 =nick= blah blah blah <- you got a message through a /dcc chat
189 (nick is in bold)
190 |nick| blah blah blah <- you sent a message through a /dcc chat
191 (nick is in bold)
192 -nick- blah blah blah <- you got a notice (nick in bold)
193 -> -nick- blah blah blah <- you sent a notice (no bold :p)
194 *> nick action <- you got a /describe (nick in bold)
195 *-> nick someaction <- you sent a /describe (nick in bold)
196
197 *** Something <- general line from the server or client
198 *E* Something <- there's been an error somewhere
199 *D* Something <- something about DCC
200 *H* Something <- you're getting help with /HELP
201 *(* Something <- you're being notified of someone's signoff
202 *)* Something <- you're being notified of someone's signon
203 *<* Something <- someone left the channel or signed off
204 *>* Something <- someone joined the channel
205 *N* Something <- someone changed nicks
206 *+* Something <- mode change
207 *I* Something <- invite-related lines
208 *T* Something <- channel topic-related lines
209 *L* Something <- logging-related lines
210 *?* Something <- unknown nick or channel
211
212
213Commands start with a / (no surprise here), and the standard set of
214commands is here:
215
216ADMIN, ALIAS, AWAY, BYE, CD, CLEAR, CONNECT, CTCP, DCC, DESCRIBE, DIE,
217EVAL, EXIT, HELP, IGNORE, INFO, INVITE, JOIN, KICK, KILL, LEAVE, LINKS,
218LIST, LOAD, LUSERS, MAP, ME, MODE, MOTD, MSG, NAMES, NICK, NOTE, NOTICE,
219NOTIFY, OPER, QUERY, PART, PING, QUERY, QUIT, QUOTE, RPING, SAY, SERVER,
220SET, SIGNOFF, SILENCE, SQUIT, STATS, TIME, TOPIC, TRACE, UPING,
221USERHOST, USERS, VERSION, WALLOPS, WHO, WHOIS, WHOWAS.
222
223For help on a command, inside sirc, type /help <name of the command>
224(once again, without the <>'s).
225
226Like with ircII, commands preceded with a ^ after the / will be silent,
227and commands preceded with an extra / will not expand aliases or do
228functions.
229
230In addition to the standard IRC commands, the following commands have
231been added to sirc, or made more user-friendly (most of these are
232inspired from popular ircII scripts):
233
234CL - short for CLEAR
235
236D [#chnl] nk1 nk2.. - deops a number of people in your the specified
237DEOP [#chnl] nicks channel (default = the current), grouping mode
238 changes 3 by 3
239
240DE nick action - short for DESCRIBE
241
242HOP - leaves your current channel
243
244IG [-][pattern] - short for IGNORE
245
246I nicks [#chnnel] - short for INVITE
247INV nicks [#chnnel] with I or INV as well as INVITE, you can specify
248 more than one nick, and the channel defaults to your
249 current channel
250
251J channel - short for JOIN
252 with J as well as JOIN, the trailing # is added
253 if not given; without arguments, it will join
254 the channel you were most recently invited to.
255
256K [#channel] reason - short for KICK
257 with K as well as with KICK, the channel defaults
258 to your current channel
259
260LL - same as WHO <#currentchannel>
261
262M nick mesg - short for MSG
263
264MO modes - short for MODE <#currentchannel>
265
266N [-][nick...] - short for NOTIFY
267
268NEXT - goes to the next channel, if you're on several
269
270NO nick mesg - short for NOTICE
271
272O [#chnl] nk1 nk2.. - ops a number of people in the specified channel
273OP [#chnl] nicks (default = the current channel), grouping mode
274 changes 3 by 3
275
276P nick|#channel - short for PING
277
278T [#chnnl] [topic] - short for TOPIC
279 with T as well as with TOPIC, the channel defaults
280 to your current channel
281
282UMODE - short for MODE <nickname>
283
284W [nick] - short for WHOIS, defaults to your own nick
285
286WI nick - asks for WHOIS info on nick's server, which gives
287 idle time, but takes longer to reply than /W
288
289
290Some commands are partly taken from ircII, but work in a different
291way:
292
293ALIAS [-]alias text - without arguments, shows the list of aliases;
294 with one argument, shows a given alias, or deletes
295 it the first character is a "-"
296 with two arguments, defines an alias
297
298 the main difference with ircII is that aliases
299 are not evaluated recursively, so something like
300 /alias blah foobar
301 /alias foobar ^msg orabidoo
302 will *not* msg orabidoo when you do /blah, because
303 evaluation is not recursive.
304
305 substitution of arguments is implemented, so $0
306 expands to the first argument, $1 the second, and
307 so on; putting a "-" after the number makes it
308 expand to that argument and all the following, so
309 $0- is all the arguments and $1- is all the
310 arguments but the first. $$ expands to a $, and
311 $some_variable_name expands to the contents of
312 that variable (see the file PROGRAMMING for the
313 list of sirc's variables).
314
315 these aliases are meant only as little time savers;
316 for anything more complicated, use functions.
317
318SET [-]var value - without arguments, shows the list of variables
319 with their values. with one argument, shows the
320 given variable. with a variable name prefixed with
321 a "-", unsets that variable. with two arguments,
322 sets a variable to a value.
323
324 see the list of SET variables below.
325
326DCC cmd nick [args] - deals with direct client connections; available
327 commands are:
328 /dcc chat nickname
329 /dcc rchat oldname newname <- rename a dcc chat
330 /dcc get nickname [file]
331 /dcc send nickname file
332 /dcc rename nickname [oldfilename] newfilename
333 /dcc close chat nickname
334 /dcc close get nickname [file]
335 /dcc close send nickname [file]
336 /dcc list
337 /dcc <- same as /dcc list
338
339EVAL code - evaluates perl code in sirc's context. useful for
340 little calculations and checks, as well as for
341 checking that your functions work. as it can be
342 used to mess with the client's internal variables,
343 use at your own risk.
344
345LOAD filename - loads a sirc script, which is actually a file of
346 perl code, into sirc's context. tilde-expansion is
347 done on the filename, which is searched for in all
348 the directories specified in the perl variable
349 @loadpath, which initially contains ~/.sirc, the
350 directory dsirc is installed in, and the current
351 directory.
352
353 see the file about programming.
354
355 an example script is provided, n0thing.pl, which
356 adds message logging, an auto-op list,
357 auto-rejoin, commands to handle bans, and more.
358
359 to try it out, inside sirc type /load n0thing.pl
360
361SYSTEM command - corresponds to ircII's "EXEC": executes an external
362 unix command. however, unlike ircII's exec, all
363 the ordinary irc functions are suspended while the
364 program is executing. this means that any /SYSTEM
365 lasting more than 1 or 2 minutes will get you
366 disconnected from IRC with a "ping timeout".
367
368 the program's output goes to the screen, and if it
369 reads from its standard input, your keyboard lines
370 are fed as input to the program.
371
372 in *NO* case should you /SYSTEM programs that use
373 a full-screen interface, like pine or tin.
374 use ^z (control-Z, which suspends sirc/ssfe) for this.
375
376 /SYSTEM is useful for commands that print
377 something and then exit immediately, such as
378 "ls", "date", "from", "uptime" ...
379
380 you can also use it to start programs such as "mail",
381 to read your mail from inside IRC, but if you stay
382 more than 1 or 2 minutes you're likely to get
383 disconnected from IRC when you're done with the mail.
384
385
386List of SETtable variables:
387
388CTCP off|none|noreply|noflood|on|all
389 - toggles the amount of CTCP support in the client.
390 "none" disables the processing of all CTCPs, even
391 CTCP action -- they will be shown like messages with
392 embedded ^A's. "noreply" and "off" are synonymous,
393 and disable all automatic CTCP replies. incoming
394 CTCPs are still processed, so you can take DCC CHATs
395 and see actions. "noflood" and "on" are synonymous;
396 this is the default value and will auto-reply to
397 those CTCPs that ask for it, up to 2 every 10 seconds.
398 "all" will process and reply to all CTCPs.
399
400 note that even in "all" mode, stacked CTCPs (more than
401 one in a single message) are not recognized. I have
402 yet to see those in actual use other than in floods.
403
404CTRL_T text - sets the text that the ^t key types; the default is
405 "/next", which switches to the next channel.
406
407EIGHT_BIT on|off - if set to off, accented iso-latin-1 characters are
408 translated into their non-accented equivalents.
409 otherwise they are passed, unmodified.
410
411FINGER text - used for replying to CTCP FINGERs.
412
413IRCNAME text - used as the ircname on the next server connection.
414
415LOADPATH path - Sets the path in which sirc looks for scripts to /load;
416 it is formatted as a list of pathnames separated by
417 colons, and ~'s are allowed.
418
419LOCALHOST - sets which IP address to use, on machines with
420 more than one (virtual hosts).
421
422LOG on|off - toggles logging on or off, or tells if it's on
423 or off. logging is just like with ircII except
424 that there are no log levels; if it's on, all that
425 goes to the screen goes to the logfile. this is
426 the same as the old /log command. if you log
427 into a .gz file, sirc automatically calls gzip to
428 log in compressed form.
429
430LOGFILE filename - sets the logfile. defaults to ~/sirc.log
431
432PRINTUH off|none|some|all|on
433 - toggles printing the user@host on messages, notices,
434 invites and the like. "off" and "none" are synonymous
435 and will only print user@host on JOINs. "some" will
436 print them in private messages and ctcps and a few
437 other useful places. "all" will print them everywhere.
438
439PRINTCHAN on|off - toggles printing the channel on public messages and
440 actions. by default this is off, and the channel is
441 not printed when it is the current channel.
442
443SENDAHEAD number - sets the amount by which the DCC SEND code will send
444 ahead of what is acknowledged. this is a hack to
445 speed up DCC transfers; a value of 0 switches back
446 to the old, slow DCC (like ircII's). the default
447 value (4096) is enough to speed it up quite a bit,
448 and something like 16386 will make it even faster.
449 setting it higher than what your kernel is willing
450 to buffer will result in your client blocking; sizes
451 of up to 16k should be quite safe.
452
453USERINFO text - used for replying to CTCP USERINFOs.
454
455
456Note that /LOADed scripts can add SET variables; in particular n0thing.pl
457implements all its toggles like that.
458
459
460## Config files:
461
462sirc loads up to four config files on startup: the system-wide
463sircrc.pl, your .sircrc.pl, the system-wide sircrc, and your .sircrc,
464in that order.
465
466System-wide config files are located in the same directory as dsirc.
467If you use the install program, the "sirc" shell-script puts this
468directory in the environment variable SIRCLIB before starting the perl
469client
470
471$SIRCLIB/sircrc and ~/.sircrc can contain commands that will be recognized
472as if the user had typed them right at the moment of connecting to the
473server.
474
475Commands in a sircrc need not start with an extra /, but they can start
476with a ^ if they are to be silent, or with two /'s if you don't want
477alias expansion. Lines starting with a # are ignored.
478
479These files is sourced at the moment of connecting to the server, after
480checking that the nick is not in use, so you can use "join", "notify"
481and similar commands from it without problems.
482
483Typical commands to put there would be in the vein of ^alias s msg someone
484
485You can specify a different name for this file, with the option -L.
486
487
488The files $SIRCLIB/sircrc.pl and ~/.sircrc.pl can contain perl code that
489will be sourced during initialization, and can define new functions
490programmed in perl, and install help for them, and also set hooks (the
491equivalent of ircII's /on's) and &load other perl scripts.
492
493This file is sourced before even connecting to the server.
494
495You can specify a different file name, instead of ~/.sircrc.pl, starting
496sirc with the -l option. This can be useful to load bots. See the file
497about programming.
498
499
500Sourcing ~/.sircrc and ~/.sircrc.pl will will be skipped if you start
501sirc with the -q option, unless alternate names were given with the -l
502or -L options.
503
504Sourcing of the two system-wide config files can be skipped with the
505option -Q.
506
507
508## Functions, hooks, bots:
509
510From /loaded scripts and .sircrc.pl, you can define new functions
511and give their implementation in perl, and define hooks to be
512triggered when certain conditions occur. You need to know perl for
513this, obviously.
514
515See the file about programming, and the example script n0thing.pl.
516
517
518## Using the split-screen front end (and having fun with it):
519
520When using ssfe, you have a command-line of about 510 characters,
521and a scrolling-region separated from it by a status bar, which
522shows your nick, user modes, away status, channel, channel modes,
523and query.
524
525The command-line editor recognizes the following editing keys:
526
527( ^key means Control-key )
528
529 ^\ - interrupt ssfe and whatever program it's running,
530 and exit back to the unix prompt
531 ^a - go to the beginning of the line
532 ^b, left arrow - move left a letter
533 ^c - interrupt: ignored by the front-end, can be used
534 to interrupt connecting to a server, with sirc
535 ^d - delete the character under the cursor
536 ^e - go to the end of the line
537 ^f, right arrow - move right a letter
538 ^h, del - erase the previous character
539 ^i, tab - go to next /msg in msg history
540 ^j, ^m, enter - send the line
541 ^k - erase from the cursor to the end of the line
542 ^l - redisplay the status bar and the command line
543 ^n, down arrow - go to the next line in command-line history
544 ^o - with sirc, type the last msg you got on the command
545 line
546 ^p, up arrow - go to the previous line in command-line history
547 ^t - with sirc, switch to the next channel you're on
548 ^u - erase command-line
549 ^v - insert the next character literally, even if it's
550 a ^something
551 ^x b - toggle beep on or off (off by default)
552 ^x c - exit the front end, back to the unix prompt
553 ^x y - set hold mode on
554 ^x h - toggle hold mode
555 ^x i - toggle irc-mode (^b^v^_ handling) on and off
556 ^x n - set hold mode off
557 ^y - yank the current line in the history without sending it
558 ^z - suspend ssfe and sirc and go back to the unix
559 prompt - you come back with 'fg'
560
561Note that to do effects on irc (bold, inverse, underlined), you need to
562type ^v^b to get a ^b character (since ^b would otherwise move your
563cursor to the left), and ^v^v to get a ^v character.
564
565If ssfe is in hold mode, it shows a (h) at the right end of the status
566bar, and it will ask you to press a key after each full screen of text.
567The little "h" turns into a "H" when ssfe is actually waiting for you to
568press a key. You can turn hold mode on and off with the ^x y and ^x n
569commands, toggle it with ^x h, and you can start ssfe in hold mode with
570the -hold command-line option.
571
572By default, ssfe will consider beeps non-printable characters and will
573display them as a G in inverse-video. You toggle beeps on and off
574with the ^x b keys, and you can start ssfe with the -beep command-line
575option to have beeps on.
576
577You can also use ssfe to run any other command-line based program than
578sirc in it, by specifying the name of the program as ssfe's first
579argument, instead of "sirc":
580
581 ssfe [<options for ssfe>] <program> [<program's options>]
582
583The options for ssfe can be:
584
585 -raw - disable word-wrap, and handling of control characters
586 -cooked - enable those, but not handle ^v^b^_
587 -irc - word-wrap, control chars and ^v^b^_ all as in irc
588 -hold - set hold mode
589 -beep - let beeps through in irc/cooked mode
590 -flow - keeps ^S/^Q as special characters, for terminals using
591 ^S/^Q flow-control
592 -print - print your own commands back on the scrolling window
593 -prompt <prompt> - set a prompt in the command-line (max 8 chars)
594
595The default mode is -cooked, but when the executed program is sirc, a
596little protocol between sirc and ssfe tells ssfe to switch to irc mode.
597This same protocol is used to pass information back and forth for the
598tab-key handler, the status line, and so on.
599
600The default prompt is none, or "> " if -print is specified.
601
602Examples:
603
604 ssfe -raw -print mail # read your mail with an irc interface!
605 ssfe -print -prompt '$ ' sh # a shell with an irc interface!!
606
607
608## What isn't there
609
610. windows (really really don't count on it)
611. multiple IRC connections
612. full redisplays and some sort of lastlog (don't count on it either)
613
614Support for all of these is planned in sirc 3.0, which will require perl 5.
615Don't ask me when that will actually exist (:
616
617
618## Acknowledgments:
619
620All the code used here is original (or reused from other programs I've
621done, mainly from my old bot in perl).
622
623Part of the help was inspired/lifted from ircII's help.
624Lots of ideas about the interface were directly inspired from ircII.
625
626More ideas have been suggested by users and beta-testers.
627
628Some bits of the interface are inspired from various ircII scripts,
629mainly my own zer0.
630
631Thanks to the following beta testers for bug reports and suggestions:
632
633slackie!agreb@pobox.com
634flarp!tmorgan@pobox.com
635mcj!mcj@acquiesce.org
636Chag!nmj3e@darwin.clas.virginia.edu
637nYtr0!gr1124@iutainfo.univ-lyon1.fr
638GG!choude@wolfe.eece.maine.edu
639THX-1138!fleuret@clipper.ens.fr
640
641
642## License:
643
644 This program is free software; you can redistribute it and/or modify
645 it under the terms of the GNU General Public License as published by
646 the Free Software Foundation.
647
648 This program is distributed in the hope that it will be useful,
649 but WITHOUT ANY WARRANTY; without even the implied warranty of
650 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
651 GNU General Public License for more details.
652
653 You should have received a copy of the GNU General Public License
654 along with this program; if not, write to the Free Software
655 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
656
657
658If you make improvements to sirc, please send me the modifications
659(context diffs appreciated) and they might make it to the next release.
660
661For bug reports, comments, questions, email roger.espel.llima@pobox.com
662
663You can always find the latest version of sirc at the following URL:
664http://www.eleves.ens.fr:8080/home/espel/sirc.html
665
666