=head1 Net::IRC

Elegant. Simple. Probably compiles.

=head1 Synopsis

 use Net::IRC::Bot;
 use Net::IRC::Modules::Autoident;

 #Roles can let you break up large event handler modules into smaller ones.
 role ExtraAnnoying {
     has %enemies = ('bob', 'sam', 'chanserv') X=> 1;
     #Magical type constraints only let this event be called when $e.who is an enemy
     multi method said ($e where {.who<nick> ~~ %enemies}) {
         $e.msg($e.what); #Parrot back what was said;
     }
 }
 

 class AnnoyUsers does ExtraAnnoying {
     #Will be called when the bot gets a join event
     multi method joined ($e) {
          $e.msg("Hi there, {$e.who<nick>}!"); 
     }
 }

 
 Net::IRC::Bot.new(
 	nick     => 'KickMe',
 	server   => 'irc.freenode.net',
 	channels => <#bottest>,
 	
 	modules  => (
 		AnnoyUsers.new(), 
 		Autoident.new(password => 'nspassw0rd')
 	),
 ).run;

=head1 Description

Its an IRC Bot framework! Theres not much else to it.
It's currently in active development, but it is mostly stable until perl 6 implements
either threads or async I/O so it can work correctly as a bot (timed events and things
that block the runtime are not possible yet.)

The framework makes extensive use of the added features perl 6 provides, and is an 
excellent example of how concise and powerful the language is... With emphasis on 
concise:- The core code is only about 350 lines!

=head1 Methods and Attributes

Net::IRC::Bot only really has one needed method: run(). Everything else is setup using
parameters to new()

List of attributes + their defaults:

 $nick = "Rakudobot";
 @altnicks = $nick Z~ ("_","__",^10);
 $username = "Clunky";
 $realname = '$@%# yeah, perl 6!';
 
 $server = "irc.perl.org";
 $port = 6667;
 $password;
 @channels = [];
 
 @modules;
 
 $debug = False;


=head2 Callbacks

Callbacks are event handlers created by you, the bot maker. They are dispatched to by
name when an appropriate IRC event is fired.

There are currently six 'main' types of events: C<said>, C<acted>, C<joined>, 
C<noticed>, C<nickchanged> and C<connected>. They will be called with a 
Net::IRC::Event object containing every detail possible about the event. [Details to 
come soon]

For any event that doesn't fit into the above category, you will need to set up a raw
event handler. Raw handlers begin with 'irc_' and won't have their Event objects 
properly filled [TODO: List what will be filled]
The method C<irc_433> for example, will be called when ERR_NICKNAMEINUSE is thrown. 
C<irc_privmsg> will be just like C<said>, except it will be called first.


Untidy collection of event object contents for each handler:

said:
C<.who> said C<.what> in channel C<.where> (if it was a private message, C<.where> will be our 
nickname. If you dont want to check C<.state<nick\>> for equality then you can always test
if C<.where> starts with a hash)

nickchange:
C<.who> changed nick to C<.what>



=head2 Helper methods

Helper methods are kept in the Event that every callback is provided with. The current
three methods are C<.msg>, C<.act> and C<.send_ctcp>. [details on each to come soon]