===============
Hacking NetHirc
===============

So you've decided that the default NetHirc settings are not for
you.  If you know some Perl, this is not a problem at all, because
you can customize things.  Heck, even if you don't know Perl, you
can customize things.

Files referred to in this document can usually be found under
/usr/local/share/nethirc, or wherever you have your $NHIRCLIB
pointing to.

0. Formats

The easiest thing to customize (and perhaps the thing that made me
write NetHirc in the first place) is the messages that get displayed
for certain events.  I've provided a general-purpose formatting
subroutine that should explain itself.  Look at the "formats" file
and you can probably figure a lot out.  If not, well, here's a
short guide.

The formats file is a bunch of key-value pairs.  The key is a short
string describing when the format is to be used; the value is a
string to be formatted and mangled and otherwise bent to your will.
In the format string, you will often notice %X and sometimes an
occasional %D.  In short, this is how it all works:

	&ircformat('foo', $bar, $baz)

The ircformat sub will look for the 'foo' format.  If it is found,
it will substitute $bar for the first %X and $baz for the second
%X.  If any %D's are encountered, then the next argument will be
thrown out entirely, as the string is scanned left to right.  So
if we have:

	foo	Something %X something else %D icky icky %X

And we use the call to ircformat shown above, the resulting formatted
string will be something like:

	Something $bar something else  icky icky %X

When ircformat encounters the %D in the middle, it will throw $baz
out and then not really substitute anything in for the final %X,
since there's nothing left in the argument list.  In reality,
though, %D is a hack, and you should never use it, so you don't
need to worry about it. :-)

But what if you ask for a format that doesn't exist?  Well, that's
easy.  Treat the first argument as the format string, not the key
to find the format string.  So you can whip up formats on the fly,
should you feel inclined.

1. Commands

The file "commands.pl" has the code for the front-end commands,
and the "commands" file has another key-value-like structure that
dictates what bits of code should be called for a particular
command.

The commands file is easiest to explain via example.

	foo	
	bar
	baz	foo
	icky	foo
	poo
	yucky

The commands for foo, bar, poo, and yucky map directly to the
subroutines called do_foo, do_bar, etc.  The baz and icky commands
will invoke the do_foo subroutine.  Easy enough, no?  Here you have
an easy aliasing mechanism; the subroutines are completely decoupled
from the commands that invoke them, and you are free to change
names around as you wish.

The API for writing the actual code is very simple.  (I will assume
you already know how to deal with Net::IRC which is essentially an
event-driven system.)  Each subroutine is passed three parameters:
the Net::IRC::Connection object to which we are speaking, the name
by which we were invoked, and the rest of the line.  So if the user
types:

	/msg bob hiya there bob

Then you will see:

	@_ = ($conn, "msg", "bob hiya there bob");

The rest, as they say, is up to the programmer.

2. Handlers

Handlers get invoked whenever an IRC protocol message enters the
back end of the client.  The handler interface is carried across
transparently from Net::IRC's handler interface.  Whenever a handler
for a particular event gets invoked, the subroutine is passed the
Net::IRC::Connection and Net::IRC::Event objects (in that order).

Again, there is a file called "handlers" which follows the rules
of the commands file, and maps event names to handler subs.  The
only real difference is that the subs are named on_* instead of
do_*.  Rather unsurprisingly, there is a file called "handlers.pl"
that has the actual handler code in it.

3. Mode Changes

The messages that show up for mode changes are kept in their own
little key-value spaces, but the keys are the mode change characters
themselves.  NetHirc's default mode change handlers will expand
the "compressed" mode strings out and give messages for each logical
piece.  The rules for the formats are the same as those presented
above.  Mode changes you inflict upon yourself are influenced by
the "self_mode" file while all others are dependent on the
"channel_mode" file.

4. Random Silliness

The "complaints" file has various things that will be shouted at
you if you try to send a blank line to NetHirc.  This idea was
taken from an old icb client I found, and ported through the
HoserChat system.  It was such an amusing (and disarming) idea that
I decided to keep it here.  Unfortunately, ssfe catches blank lines
and refuses to send them, so if you run under ssfe you'll never
see the complaints.  Also, since the tty is only polled when
select(2) says it should be, select and the tty could very easily
clobber the empty-line complaints.  Oh well.

The "monsters" file contains all monsters (real and hallucinated)
that I could scum from the Nethack sources.  You are free to use
them where you think it would be amusing; right now, there is only
one piece of code that actually uses them.  If you get any good
ideas on this, let me know.

The "classes" file is a list of possible classes that a character
can have in Nethack.  You are secretly assigned one at random when
NetHirc starts up, and it is used in a couple of random places,
including sending a NOTICE to those who CTCP FINGER you.  Similarly,
you are also assigned a deity from the "deities" file.  I did not
force classes and deities to line up like they do in Nethack,
because I thought it would be more confusing and amusing that way.

The "disasters" file contains things that are NOTICEd back at people
who CTCP VERSION you.  I had to go around collecting these, instead
of ripping them directly out of the Nethack sources.  They're a
bit trickier to find, you know.

The "scrolls" file contains the pre-discovery names of all the
scrolls you can find in Nethack.  These names are only used in one
place at the moment.

The "ctcp" file lists all the CTCP requests that are supported by
NetHirc.  I recommand that you not hack this file unless you're
heavy into deception and security through obscurity.

5. The nhircrc

The system nhircrc file is installed by the install strcipt.  All
clients who have the appropriate directory in their $NHIRCLIB path
will get it.  If you have a file called ~/.nhircrc, it will be
sucked in before any other nhircrc files in your $NHIRCLIB path.

The format of the nhircrc is very similar to what you type at
NetHirc, without the leading command character (which is / by
poorly-chosen default).  These lines are passed almost unmolested
to the rest of NetHirc, with the following rules:
	
	Leading whitespace is stripped.

	Comments run from a '#' in the first position to the end
	of the line, and are ignored.

	Leading command characters are stripped.

	$NICK is replaced with your nick when the client starts up.

Other than that, act like you're typing straight at NetHirc and
you'll be fine.

6. Useful surprises

If I did my job right (and I think I did) you should never have to
restart NetHirc if you modify anything.  (With the exception of
the main NetHirc executable, of course.)  Though sometimes you just
want to be sure, and you'll restsart it anyway.  But theoretically,
at least, NetHirc should be fully dynamic. 

The dynamic nature of NetHirc is accessible via the /reload command,
which consults a tree-like map to determine what files to read
again.  The map is stored in the main NetHirc engine, should you
feel the need to modify it.  Most things, however, are probably
already covered.

7. Other randomness that doesn't fit

This is where the helpers.pl file comes in.  This file is for code
that's not really critical to anything, but is classifiable as
random utility subs.  For instance, the Yoda and Pig-Latin algorithms
are contained there.  The "pickrandom" sub could almost be there,
but it's used way too early on in the code.

$Id: HACKING,v 1.6 1999/08/15 21:42:54 tony Exp $
