NAME

IRC::Toolkit::Numerics - Modern IRC numeric responses

SYNOPSIS

use IRC::Toolkit::Numerics;

## Functional interface returns defaults:
my $rpl = name_from_numeric( '001' );                 # 'RPL_WELCOME'
my $num = numeric_from_name( 'RPL_USERSDONTMATCH' );  # '502'

## OO interface allows (re)mapping numerics:
my $numerics = IRC::Toolkit::Numerics->new;

$numerics->get_name_for( '001' );
$numerics->get_numeric_for( 'RPL_WELCOME' );

$numerics->associate_numeric( '486' => 'ERR_HTMDISABLED' );

DESCRIPTION

A pair of functions for translating IRC numerics into their "RPL" or "ERR" name and back again.

The included list attempts to be as complete as possible.

In cases where there is a conflict (typically between RFC2812, ircu, and hybrid/ratbox derivatives), modern ratbox labels are preferred, ratbox derivatives being the most prevalent across large networks.

In cases where that turns out not to be true, please send patches ;-)

Functional interface

name_from_numeric

Given a numeric, name_from_numeric returns its proper RPL name.

numeric_from_name

Given a RPL name, numeric_from_name returns its assigned command numeric.

Object interface

new

my $numerics = IRC::Toolkit::Numerics->new;

Construct a new instance.

associate_numeric

## A hybrid7 484 (overrides ratbox):
$numerics->associate_numeric( '484' => 'ERR_RESTRICTED' );

Add or remap a numeric.

get_name_for

## RPL_WELCOME:
my $name = $numerics->get_name_for('001');
## ERR_CHANNELISFULL:
$name = $numerics->get_name_for(471);

Retrieve the RPL/ERR label for a supplied numeric (or boolean false).

get_numeric_for

## 471:
my $thisnum = $numerics->get_numeric_for('ERR_CHANNELISFULL');

Retrieve the numeric for a supplied RPL/ERR label (or boolean false).

export

my $hash = IRC::Toolkit::Numerics->export;

Exports a List::Objects::WithUtils::Hash mapping numerics to RPL/ERR names.

If called on a blessed instance (rather than as a class method), numerics remapped via "associate_numeric" are included in the exported hash.

export_by_name

Like "export", but returns the reversed hash (mapping RPL/ERR names to numerics).

SUBCLASSING

It's possible for a subclass to override individual numerics (and otherwise default to the standard list) by providing a constructor that uses List::Objects::WithUtils to construct hash-type objects containing overrides:

package My::Numerics;
use List::Objects::WithUtils 'hash';
use parent 'IRC::Toolkit::Numerics';
sub new {
  bless +{
    over_num  => hash(304 => 'RPL_FOO'),
    over_name => hash(RPL_RPL => 304),
  }, $_[0]
}

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

Default numerics list is based on the AnyEvent::IRC list present in IRC::Utils and the numerics.h definitions from hybrid-7.2.3, oftc-hybrid-1.6.7, and ratbox-trunk.

Interface is based on IRC::Utils and helpful suggestions from <matthew@alphachat.org>