POE::Filter::IRCv3 - Fast IRCv3.2 parser for POE or stand-alone use
my $filter = POE::Filter::IRCv3->new(colonify => 1); # Raw lines parsed to hashes: my $array_of_refs = $filter->get( [ ':prefix COMMAND foo :bar', '@foo=bar;baz :prefix COMMAND foo :bar', ] ); # Hashes deparsed to raw lines: my $array_of_lines = $filter->put( [ { prefix => 'prefix', command => 'COMMAND', params => [ 'foo', 'bar' ], }, { prefix => 'prefix', command => 'COMMAND', params => [ 'foo', 'bar' ], tags => { foo => 'bar', baz => undef, }, }, ] ); # Stacked with a line filter, suitable for Wheel usage, etc: my $ircd = POE::Filter::IRCv3->new(colonify => 1); my $line = POE::Filter::Line->new( InputRegexp => '\015?\012', OutputLiteral => "\015\012", ); my $stacked = POE::Filter::Stackable->new( Filters => [ $line, $ircd ], ); # Functional parser interface: my $event = POE::Filter::IRCv3::parse_one_line( ':foo PRIVMSG #bar :baz quux' );
A POE::Filter for IRC traffic with support for IRCv3.2 message tags.
Does not rely on regular expressions for parsing. Benchmarks show this approach is generally faster on the most common IRC strings.
Like any proper POE::Filter, there are no POE-specific bits involved here -- the filter can be used stand-alone to parse lines of IRC traffic (also see IRC::Toolkit::Parser).
In fact, you do not need POE installed -- if POE::Filter is not available, it is left out of @ISA and the filter will continue working normally.
@ISA
Construct a new Filter; if the colonify option is true, the last parameter will always have a colon prepended. (This setting can also be retrieved or changed on-the-fly by calling colonify as a method, or changed for specific events by passing a colonify option via events passed to "put".)
Implement the interface described in POE::Filter.
See "get".
my $events = $filter->get( [ $line, $another, ... ] ); for my $event (@$events) { my $cmd = $event->{command}; ## See below for other keys available }
Takes an ARRAY of raw lines and returns an ARRAY of HASH-type references with the following keys:
The (uppercased) command or numeric.
An ARRAY containing the event parameters.
The sender prefix, if any.
A HASH of key => value pairs matching IRCv3.2 "message tags" -- see http://ircv3.atheme.org.
Note that a tag can be present, but have an undefined value.
my $lines = $filter->put( [ $hash, $another_hash, ... ] ); for my $line (@$lines) { ## Direct to socket, etc }
Takes an ARRAY of HASH-type references matching those described in "get" (documented above) and returns an ARRAY of raw IRC-formatted lines.
In addition to the keys described in "get", the colonify option can be specified for specific events. This controls whether or not the last parameter will be colon-prefixed even if it is a single word. (Yes, IRC is woefully inconsistent ...)
Specify as part of the event hash:
$filter->put([ { %event, colonify => 1 } ]);
Copy the filter object (with a cleared buffer).
Turn on/off debug output, which will display every input/output line (and possibly other data in the future).
This is enabled by default at construction time if the environment variable POE_FILTER_IRC_DEBUG is a true value.
POE_FILTER_IRC_DEBUG
If the filter is being used as a stand-alone IRC parser and speed is of the essence, you can skip method resolution & queue handling by calling the parse function directly using the fully-qualified name:
my $ev = POE::Filter::IRCv3::parse_one_line( $line );
The function takes a single line and returns a HASH whose structure is described in the documentation for "get", above.
If the given line cannot be parsed, the function returns false (rather than throwing an exception, as "get" would).
There is currently no functional interface to message string composition ("put").
Jon Portnoy <avenj@cobaltirc.org>
Licensed under the same terms as Perl.
Original implementations were derived from POE::Filter::IRCD, which is copyright Chris Williams and Jonathan Steinert. This codebase has diverged significantly.
Major thanks to the #ircv3 crew on irc.atheme.org, especially Aerdan and grawity, for various bits of inspiration.
#ircv3
Aerdan
grawity
IRC::Message::Object
POE::Filter
POE::Filter::IRCD
POE::Filter::Line
POE::Filter::Stackable
IRC::Toolkit
To install POE::Filter::IRCv3, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Filter::IRCv3
CPAN shell
perl -MCPAN -e shell install POE::Filter::IRCv3
For more information on module installation, please visit the detailed CPAN module installation guide.