           sirc, by orabidoo (roger.espel.llima@ens.fr)
	   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



This is a simple (well, not so simple anymore *grin*) irc client,
written in perl and C.

It's divided in two parts, a dumb-mode (meaning, no full screen
interface) client, dsirc, that can be used stand-alone, programmed in
perl, and a separate split-screen front end in C, called ssfe.

The main point of running this client is that you can get a reasonable
ircII-like interface on an account with a properly installed perl
interpreter, with the perl client taking about 55k (and it's usable on
its own if you don't have access to a C compiler) and with the
interface, once compiled, taking just another 30 or 40k. The two
together, while lacking the huge complexity of ircII, make a very usable
client. And if you know perl, you'll find you can do quite complicated
and interesting things with sirc too :)



## Files:

README		- this one
ChangeLog	- the list of changes in different versions
PROGRAMMING	- documentation for programming within sirc (scripting)
install		- installation script - will setup everything for you
dsirc		- the dumb-mode client itself
n0thing.pl      - a script for sirc
sirc.help.gz	- sirc's help file. sirc can read it in compressed (.gz)
		  format, so there is no need to gunzip it here
ssfe.c		- source code for the front end



## Installation:

If you're reading this, we'll assume that you've already uncompressed
the sirc.tar.gz file, and de-tared it, and you have all of these files
a directory ~/sirc, and it is your current directory. 

Then just type ./install, and follow the instructions. In any case, if 
you don't know what to answer to something the installation script is 
asking you, just press Enter to use the default answer.

Once your dsirc and ssfe are working, the files you need to run the
client are:

 dsirc		- the client
 n0thing.pl	- the irc script, if you want it
 sirc		- little shell script to start the client
 ssfe		- the front end, if you want it
 sircsock.ph    - include file for sirc
 getopts.pl	- if it had to create it
 sirc.help.gz	- if you want the online help

This brings the client to around 110k with everything, or 95k with the
client, the front-end and the help, or 60k with the dumb-mode client and
the help, or 55k without the help.

If you have enough disk space, you're encouraged to keep everything,
including the doc files README and PROGRAMMING.

For the client to work properly, the files "sirc.help.gz" and 
"sircsock.ph" and "getopts.pl" (if you have them) must be in the same 
directory as the main "dsirc" file.

You never need to uncompress sirc.help.gz, as the client is smart enough
to read it compressed.


## Invoking the client:

To run sirc: sirc [<options>] [<nick> [<server>]]

Options are:

  -d		- dumb mode (don't use ssfe) : must be the first option
  -p <number>	- specify port number
  -i <name>	- specify IRCNAME
  -n <nick>	- specify nickname (sorta useless as an option, you can
  		                    specify that without the -n)
  -s <server>	- specify server (sorta useless as an option too)
  -l <filename> - specify file to be loaded instead of ~/.sircrc.pl
  -q		- don't load ~/.sircrc
  -8		- run in 8-bit mode (do not translate iso-latin-1 to ASCII)


Example:
  sirc -i "isn't this a cute IRCNAME?" ItSMe irc-2.mit.edu

To run dsirc directly without using the "sirc" shell-script:

  [ssfe] [ssfe options] [perl] dsirc [<options>] [<nick> [<server>]]

As usual, arguments between [] are optional.

You can specify options for ssfe's operation in the environment variable
SSFE, since it's not possible to mix options for dsirc and for ssfe in
the same command-line using the "sirc" script.

So if you want beeps on by default, you should add the line
"setenv SSFE '-beep'" to your .login, or the line
"SSFE='-beep' ; export SSFE" to your .profile.


In case dsirc (or whatever program you run in ssfe) gets stuck, remember 
the combination of keys that will cause ssfe to exit: ^x c (i.e. 
Control-X followed by C). When running in dumb mode, sirc can be 
interrupted by pressing ^c (Control-C).



## Recognized shell variables:

SIRCSERVER, IRCSERVER	- server to use, optionally followed by a port
			  and a password, in the form server:port:pass; 
			  overriden by -s or the second command-line 
			  option; defaults to us.undernet.org

SIRCPORT, IRCPORT	- port to connect to if not specified in the
			  server, overriden by -p, defaults to 6667

SIRCNAME, IRCNAME	- information between ()'s in the /whois,
			  defaults to "sirc user"

SIRCNICK, IRCNICK	- nickname to use, defaults to your username

IRCFINGER		- reply to CTCP FINGER, defaults to
			  "keep your fingers to yourself"

USERINFO		- reply to CTCP USERINFO, defaults to
			  "yep, i'm a user"

SSFE			- options for ssfe, if you're using it. set it
			  to "-beep" to have beep on, or to "-hold" to 
			  have hold-mode on, or to "-prompt '> '" to 
			  have "> " as a prompt, or any combination of 
			  such options

			  this variable is read by the "sirc" script,
			  not by dsirc or ssfe itself

## Using it:

sirc has been designed to look a lot like ircII, while staying as simple 
and small as possible. A number of things which are usually defined as 
aliases with ircII are builtin with sirc, to make it more usable.

sirc is undernet-friendly, /silence, /map, and even /rping and /uping
are there :)

sirc's screen presentation of messages, talk lines, server lines,
and sirc's own messages follows these conventions:

  <nick> blah blah blah	     <- person spoke on a channel
  <yournick> blah blah blah  <- you spoke on a channel (your nick will
				be underlined or colored)
  * nick someaction	     <- person did a /me
  * yournick someaction      <- you did a /me (your nick will be underlined
				or somehow colored)
  [nick] blah blah blah	     <- you got a private message (the nick will
				be in bold)
  >nick< blah blah blah	     <- you sent a private message (the nick
				will be in bold)
  =nick= blah blah blah	     <- you got a message through a /dcc chat
				(nick is in bold)
  |nick| blah blah blah	     <- you sent a message through a /dcc chat
				(nick is in bold)
  -nick- blah blah blah	     <- you got a notice (nick in bold)
  -> -nick- blah blah blah   <- you sent a notice (no bold :p)
  *> nick action	     <- you got a /describe (nick in bold)
  *-> nick someaction	     <- you sent a /describe (nick in bold)

  *** Something		     <- general line from the server or client
  *E* Something		     <- there's been an error somewhere
  *D* Something		     <- something about DCC
  *H* Something		     <- you're getting help with /HELP
  *(* Something		     <- you're being notified of someone's signoff
  *)* Something		     <- you're being notified of someone's signon
  *<* Something		     <- someone left the channel or signed off
  *>* Something		     <- someone joined the channel
  *N* Something		     <- someone changed nicks
  *+* Something		     <- mode change
  *I* Something		     <- invite-related lines
  *T* Something		     <- channel topic-related lines
  *L* Something		     <- logging-related lines
  *?* Something		     <- unknown nick or channel


Commands start with a / (no surprise here), and the standard set of
commands is here:

ADMIN, ALIAS, AWAY, BYE, CD, CLEAR, CONNECT, CTCP, DCC, DESCRIBE, DIE,
EVAL, EXIT, HELP, IGNORE, INFO, INVITE, JOIN, KICK, KILL, LEAVE, LINKS,
LIST, LOAD, LUSERS, MAP, ME, MODE, MOTD, MSG, NAMES, NICK, NOTE, NOTICE,
NOTIFY, OPER, QUERY, PART, PING, QUERY, QUIT, QUOTE, RPING, SAY, SERVER,
SIGNOFF, SILENCE, SQUIT, STATS, TIME, TOPIC, TRACE, UPING, USERHOST,
USERS, VERSION, WALLOPS, WHO, WHOIS, WHOWAS.

For help on a command, inside sirc, type /help <name of the command>
(once again, without the <>'s).

Like with ircII, commands preceded with a ^ after the / will be silent, 
and commands preceded with an extra / will not expand aliases or do 
functions.

In addition to the standard IRC commands, the following commands have
been added to sirc, or made more user-friendly (most of these are
inspired from popular ircII scripts):

A msg               - sends a message to the person you last sent a msg to
	 	      (i.e. follows up on your last msg)

CL		    - short for CLEAR

D [#chnl] nk1 nk2.. - deops a number of people in your the specified
DEOP [#chnl] nicks    channel (default = the current), grouping mode
		      changes 3 by 3

DE nick action      - short for DESCRIBE

HOP                 - leaves your current channel

IG [-][pattern]	    - short for IGNORE

I nicks [#chnnel]   - short for INVITE
INV nicks [#chnnel]   with I or INV as well as INVITE, you can specify
		      more than one nick, and the channel defaults to your
		      current channel

J channel           - short for JOIN
                      with J as well as JOIN, the trailing # is added
		      if not given

K [#channel] reason - short for KICK
		      with K as well as with KICK, the channel defaults
		      to your current channel

LL                  - same as WHO <#currentchannel>

M nick mesg         - short for MSG

MO modes            - short for MODE <#currentchannel>

N [-][nick...]	    - short for NOTIFY

NEXT		    - goes to the next channel, if you're on several

NO nick mesg        - short for NOTICE

O [#chnl] nk1 nk2.. - ops a number of people in the specified channel
OP [#chnl] nicks      (default = the current channel), grouping mode
		      changes 3 by 3

P nick|#channel     - short for PING

T [#chnnl] [topic]  - short for TOPIC
                      with T as well as with TOPIC, the channel defaults
		      to your current channel

UMODE               - short for MODE <nickname>

W [nick]            - short for WHOIS, defaults to your own nick

WI nick             - asks for WHOIS info on nick's server, which gives
                      idle time, but takes longer to reply than /W


Some commands are partly taken from ircII, but work in a different
way:

ALIAS [-]alias text - without argumnts, shows the list of aliases;
		      with one argument, shows a given alias, or deletes
		      it the first character is a "-"
		      with two arguments, defines an alias

		      the main difference with ircII is that aliases
		      are not evaluated recursively, so something like
			/alias blah foobar
			/alias foobar ^msg orabidoo
		      will *not* msg orabidoo when you do /blah, because
		      evaluation is not recursive.

		      substitution of arguments is implemented, so $0 
		      expands to the first argument, $1 the second, and 
		      so on; putting a "-" after the number makes it 
		      expand to that argument and all the following, so 
		      $0- is all the arguments and $1- is all the
		      arguments but the first. $$ expands to a $, and
		      $some_variable_name expands to the contents of
		      that variable (see the file PROGRAMMING for the
		      list of sirc's variables).

		      these aliases are meant only as little timesavers;
		      for anything more complicated, use functions.

DCC cmd nick [args] - deals with direct client connections; available
		      commands are:
		      	/dcc chat nickname
			/dcc get nickname [file]
			/dcc send nickname file
			/dcc rename nickname [oldfilename] newfilename
			/dcc close chat nickname
			/dcc close get nickname [file]
			/dcc close send nickname [file]
			/dcc list
			/dcc		<- same as /dcc list

EVAL code           - evaluates perl code in sirc's context. useful for
		      little calculations and checks, as well as for
		      checking that your functions work. as it can be
		      used to mess with the client's internal variables,
		      use at your own risk.

LOAD filename       - loads a sirc script, which is actually a file of
		      perl code, into sirc's context. tilde-expansion is
		      done on the filename, which is searched for in all
		      the directories specified in the perl variable
		      @loadpath, which initially contains ~/.sirc, the
		      directory dsirc was started from, and the current
		      directory.

		      see the file about programming.

		      an example script is provided, n0thing.pl, which adds
		      message logging, an auto-op list, auto-rejoin,
		      commands to handle bans, and more.

		      to try it out, inside sirc type /load n0thing.pl

LOG [on/off]	    - toggles logging on or off, or tells if it's on
		      or off. logging is just like with ircII except
		      that there are no log levels; if it's on, all
		      that goes to the screen goes to the logfile.

LOGFILE [filename]  - sets the logfile, or tells the current logfile.

SYSTEM command	    - corresponds to ircII's "EXEC": executes an external
		      unix command. however, unlike ircII's exec, all
		      the ordinary irc functions are suspended while the
		      program is executing. this means that any /SYSTEM
		      lasting more than 1 or 2 minutes will get you
		      disconnected from IRC with a "ping timeout".

		      the program's output goes to the screen, and if it
		      reads from its standard input, your keyboard lines
		      are fed as input to the program.

		      in *NO* case should you /SYSTEM programs that use
		      a full-screen interface, like pine or tin.
		      use ^z (control-Z, which suspends sirc/ssfe) for this.

		      /SYSTEM is useful for commands that print
		      something and then exit immediately, such as
		      "ls", "date", "from", "uptime" ...

		      you can also use it to start programs such as "mail",
		      to read your mail from inside IRC, but if you stay
		      more than 1 or 2 minutes you're likely to get
		      disconnected from IRC when you're done with the mail.


## Config files:

~/.sircrc can contain commands that will be recognized as if the user
had typed them right at the moment of connecting to the server.

It will be skipped if you start sirc with the -q option.

Commands in ~/.sircrc need not start with an extra /, but they can
start with a ^ if they are to be silent, or with two /'s if you don't
want alias expansion.

This file is sourced at the moment of connecting to the server, after
checking that the nick is not in use, so you can use "join", "notify"
and similar commands from it without problems.

Typical commands to put there would be in the vein of ^alias s msg someone


The file ~/.sircrc.pl can contain perl code that will be sourced during
initialization, and can define new functions programmed in perl, and
install help for them, and also set hooks (the equivalent of ircII's
/on's).

This file is sourced before even connecting to the server.

You can specify a different file name, instead of ~/.sircrc.pl, starting
sirc with the -l option. This can be useful to load bots. See the file
about programming.


## Functions, hooks, bots:

From /loaded scripts and .sircrc.pl, you can define new functions
and give their implementation in perl, and define hooks to be
triggered when certain conditions occur. You need to know perl for
this, obviously.

See the file about programming, and the example script n0thing.pl.


## Using the split-screen front end (and having fun with it):

When using ssfe, you have a command-line of about 510 characters,
and a scrolling-region separated from it by a status bar, which
shows your nick, user modes, away status, channel, channel modes,
and query.

The command-line editor recognizes the following editing keys:

( ^key means Control-key )

  ^\		  - interrupt ssfe and whatever program it's running,
		    and exit back to the unix prompt
  ^a		  - go to the beginning of the line
  ^b, left arrow  - move left a letter
  ^c		  - interrupt: ignored by the front-end, can be used
  		    to interrupt connecting to a server, with sirc
  ^d		  - delete the character under the cursor
  ^e		  - go to the end of the line
  ^f, right arrow - move right a letter
  ^h, del	  - erase the previous character
  ^i, tab	  - go to next /msg in msg history
  ^j, ^m, enter   - send the line
  ^k		  - erase from the cursor to the end of the line
  ^l		  - redisplay the status bar and the command line
  ^n, down arrow  - go to the next line in command-line history
  ^o		  - with sirc, type the last msg you got on the command
  		    line
  ^p, up arrow	  - go to the previous line in command-line history
  ^t		  - with sirc, switch to the next channel you're on
  ^u		  - erase command-line
  ^v		  - insert the next character literally, even if it's
  		    a ^something
  ^x b		  - toggle beep on or off (off by default)
  ^x c		  - exit the front end, back to the unix prompt
  ^x y		  - set hold mode on
  ^x h		  - toggle hold mode
  ^x i		  - toggle irc-mode (^b^v^_ handling) on and off
  ^x n		  - set hold mode off
  ^y		  - yank the current line in the history without sending it
  ^z		  - suspend ssfe and sirc and go back to the unix
  		    prompt - you come back with 'fg'

Note that to do effects on irc (bold, inverse, underlined), you need to
type ^v^b to get a ^b character (since ^b would otherwise move your
cursor to the left), and ^v^v to get a ^v character.

If ssfe is in hold mode, it shows a (h) at the right end of the status
bar, and it will ask you to press a key after each full screen of text.
The little "h" turns into a "H" when ssfe is actually waiting for you to
press a key. You can turn hold mode on and off with the ^x y and ^x n
commmands, toggle it with ^x h, and you can start ssfe in hold mode with
the -hold command-line option.

By default, ssfe will consider beeps non-printable characters and will
display them as a G in inverse-video. You toggle beeps on and off
with the ^x b keys, and you can start ssfe with the -beep command-line
option to have beeps on.

You can also use ssfe to run any other command-line based program than
sirc in it, by specifying the name of the program as ssfe's first
argument, instead of "sirc":

   ssfe [<options for ssfe>] <program> [<program's options>]

The options for ssfe can be:

  -raw		   - disable word-wrap, and handling of control characters
  -cooked	   - enable those, but not handle ^v^b^_
  -irc		   - word-wrap, control chars and ^v^b^_ all as in irc
  -hold		   - set hold mode
  -beep		   - let beeps through in irc/cooked mode
  -print	   - print your own commands back on the scrolling window
  -prompt <prompt> - set a prompt in the command-line (max 8 chars)

The default mode is -cooked, but when the executed program is sirc, a
little protocol between sirc and ssfe tells ssfe to switch to irc mode.
This same protocol is used to pass information back and forth for the
tab-key handler, the status line, and so on.

The default prompt is none, or "> " if -print is specified.

Examples:

  ssfe -raw -print mail		# read your mail with an irc interface!
  ssfe -print -prompt '$ ' sh	# a shell with an irc interface!!


## What isn't there (but *might* be added someday):

. windows (really really don't count on it)
. full redisplays and some sort of lastlog (don't count on it either)


## Acknowledgemnts:

All the code used here is original (or reused from other programs
I've done, mainly from my bot in perl).

Part of the help was inspired/lifted from ircII's help.
Lots of ideas about the interface were directly inspired from ircII.

More ideas have been suggested by users and beta-testers.

Some bits of the interface are inspired from various ircII scripts,
mainly my own zer0.

Thanks to the following beta testers for bug reports and suggestions:

slackjaw!slackjaw@solar.sky.net
Chag!nmj3e@darwin.clas.virginia.edu
nYtr0!gr1124@iutainfo.univ-lyon1.fr
GG!choude@wolfe.eece.maine.edu
THX-1138!fleuret@clipper.ens.fr


## License:

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


If you make improvements to sirc, please send me the modifications 
(context diffs appreciated) and they might make it to the next release.

For bug reports, comments, questions, email roger.espel.llima@ens.fr

You can always find the latest version of sirc at the following URL:
http://www.eleves.ens.fr:8080/home/espel/sirc.html

