From c97eb34b64788602713fcc77d3c18ab17b629318 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:10:03 -0500 Subject: Some docs --- DESIGN-NOTES.md | 2 + README.md | 117 ++++++++++++++++++++++--------------- examples/bot.pl6 | 2 +- lib/IRC/Client.pm6 | 16 ++--- lib/IRC/Client/Plugin/Debugger.pm6 | 2 +- 5 files changed, 83 insertions(+), 56 deletions(-) diff --git a/DESIGN-NOTES.md b/DESIGN-NOTES.md index 84b93a7..eaed28b 100644 --- a/DESIGN-NOTES.md +++ b/DESIGN-NOTES.md @@ -1,5 +1,7 @@ ## Just some notes jotted down while reading RFCs +This is only for my own use and is not meant to be of any use to anyone else. + #### RFC 1459 http://irchelp.org/irchelp/rfc/rfc.html diff --git a/README.md b/README.md index 5810376..67cb299 100644 --- a/README.md +++ b/README.md @@ -187,6 +187,27 @@ working order of any IRC client. **Defaults to:** Takes no arguments. Starts the IRC client. Exits when the connection to the IRC server ends. +# METHODS FOR PLUGINS + +You can make use of these `IRC::Client` methods in your plugins: + +## `.ssay` + +```perl6 + $irc.ssay("Foo bar!"); +``` +Sends a message to the server, automatically appending `\r\n`. Mnemonic: +**s**erver **say**. + + +## `.privmsg` + +```perl6 + $irc.privmsg( 'Zoffix', 'Hallo!' ); +``` +Sends a `PRIVMSG` message specified in the second argument +to the user/channel specified as the first argument. + # INCLUDED PLUGINS Currently, this distribution comes with two IRC Client plugins: @@ -260,7 +281,7 @@ class. Specifies that plugin handled the message and the plugin chain processing should stop immediatelly. Plugins later in the chain won't know this message ever came. Unless you explicitly return -[`IRC_NOT_HANDLED`](#IRC_NOT_HANDLED) constant, IRC::Client will assume +[`IRC_NOT_HANDLED`](#irc_not_handled) constant, IRC::Client will assume `IRC_HANDLED` was returned. ### `IRC_NOT_HANDLED` @@ -272,75 +293,79 @@ Returning this constant indicates to IRC::Client that your plugin did not "handle" the message and it should be propagated further down the plugin chain for other plugins to handle. +## Subscribing to IRC events +### Standard IRC commands ```perl6 - unit class IRC::Client::Plugin::Foo:ver<1.001001>; - - multi method msg () { True } - multi method msg ($irc, $msg) { - $irc.privmsg( Zoffix => Dump $msg, :indent(4) ); - } - - multi method interval () { 6 } - multi method interval ($irc) { - $irc.privmsg( - $irc.channels[0], "5 seconds passed. Time is now " ~ now - ); - } + method irc-privmsg ($irc, $e) { ... } + method irc-notice ($irc, $e) { ... } ``` +To subscribe to an IRC event, simply declare a method named `irc-COMMAND`, +where `COMMAND` is the IRC command you want to handle. The method takes +two positional arguments: an `IRC::Client` object and the parsed IRC +message. -Above is a sample plugin. You can choose to respond either to server -messages or do things at a specific interval. +You'll likely generate a response based on the content of the parsed message +and use one of the [METHODS FOR PLUGINS](#methods-for-plugins) to send that +response. -### Responding to server messages +## Special Events ```perl6 - multi method msg () { True } - multi method msg ($irc, $msg) { - $irc.privmsg( Zoffix => Dump $msg, :indent(4) ); - } + method irc-all-events ($irc, $e) { ... } + method irc-privmsg-me ($irc, $e) { ... } + method irc-notice-me ($irc, $e) { ... } + ... # all other handlers for standard IRC commands + method irc-unhandled ($irc, $e) { ... } ``` +In addition to the [standard IRC commands](#standard-irc-commands), you can +register several special cases. They're handled in the event chain in the order +shown above. That is, if a plugin returns [`IRC_HANDLED`](#irc_handled) after +processing, say, [`irc-all-events`](#irc-all-events) event, its +[`irc-notice-me`](#irc-notice-me) handler won't be triggered, even if it would +otherwise. -If your plugin can resond to server messages, declare two multi methods -`msg` as seen above. The one without parameters needs to return `True` -(or `False`, if your plugin does not respond to messages). The second -gets the `IRC::Client` object as the first argument and the parsed message -as the second argument. +The available special events are as follows: -### Acting in intervals +### `irc-all-events` ```perl6 - multi method interval () { 6 } - multi method interval ($irc) { - $irc.privmsg( - $irc.channels[0], "5 seconds passed. Time is now " ~ now - ); - } + method irc-all-events ($irc, $e) { ... } ``` -Your plugin can also repsond in intervals. Declare an `interval` multi -that takes no arguments and returns an interval in seconds that your -action should happen in (return `0` if your plugin does not handle intervals). -The other multi method `interval` takes the `IRC::Client` as the argument. +Triggered for all IRC commands received, regardless of their content. As this +method will be triggered before any others, you can use this to +pre-process the message, for example. ***WARNING:*** **since +[`IRC_HANDLED` constant](#irc_handled) is returned by default, if you do not +explicitly return [`IRC_NOT_HANDLED`](#irc_not_handled), your client will +stop handling ALL other messages +*** -## Methods for plugins +### `irc-privmsg-me` -You can make use of these `IRC::Client` methods in your plugins: +```perl6 + method irc-privmsg-me ($irc, $e) { ... } +``` +Triggered when the IRC `PRIVMSG` command is received, where the receipient +is the client (as opposed to some channel). -### `.ssay` +### `irc-notice-me` ```perl6 - $irc.ssay("Foo bar!"); + method irc-notice-me ($irc, $e) { ... } ``` -Sends a message to the server, automatically appending `\r\n`. +Triggered when the IRC `NOTICE` command is received, where the receipient +is the client (as opposed to some channel). -### `.privmsg` +### `irc-unhandled` ```perl6 - $irc.privmsg( Zoffix => "Hallo!" ); + method irc-unhandled ($irc, $e) { ... } ``` -Sends a `PRIVMSG` message specified in the second argument -to the user/channel specified as the first argument. + +This is the same as [`irc-all-events`](#irc-all-events), except it's triggered +**after** all other events were tried. This method can be used to catch +any unhandled events. # REPOSITORY diff --git a/examples/bot.pl6 b/examples/bot.pl6 index 20bcb39..76c9fbb 100644 --- a/examples/bot.pl6 +++ b/examples/bot.pl6 @@ -4,7 +4,7 @@ use IRC::Client; use IRC::Client::Plugin::Debugger; my $irc = IRC::Client.new( - :host('localhost'), + :host('10.10.11.12'), :debug, plugins => [ IRC::Client::Plugin::Debugger.new diff --git a/lib/IRC/Client.pm6 b/lib/IRC/Client.pm6 index 7b1c7e5..c781ef1 100644 --- a/lib/IRC/Client.pm6 +++ b/lib/IRC/Client.pm6 @@ -34,10 +34,15 @@ class IRC::Client:ver<1.002001> { EVENTS: for @$events -> $e { $e = {}; + for @!plugs.grep(*.^can: 'irc-all-events') -> $p { + my $res = $p.all-events(self, $e); + next EVENTS unless $res === IRC_NOT_HANDLED; + } + if ( $e eq 'PRIVMSG' and $e[0] eq $!nick ) { - for @!plugs.grep(*.^can: 'privmsg-me') -> $p { + for @!plugs.grep(*.^can: 'irc-privmsg-me') -> $p { my $res = $p.privmsg-me(self, $e); next EVENTS unless $res === IRC_NOT_HANDLED; } @@ -46,24 +51,19 @@ class IRC::Client:ver<1.002001> { if ( $e eq 'NOTICE' and $e[0] eq $!nick ) { - for @!plugs.grep(*.^can: 'notice-me') -> $p { + for @!plugs.grep(*.^can: 'irc-notice-me') -> $p { my $res = $p.notice-me(self, $e); next EVENTS unless $res === IRC_NOT_HANDLED; } } - for @!plugs.grep(*.^can: 'all-events') -> $p { - my $res = $p.all-events(self, $e); - next EVENTS unless $res === IRC_NOT_HANDLED; - } - my $cmd = 'irc-' ~ $e.lc; for @!plugs.grep(*.^can: $cmd) -> $p { my $res = $p."$cmd"(self, $e); next EVENTS unless $res === IRC_NOT_HANDLED; } - for @!plugs.grep(*.^can: 'unhandled') -> $p { + for @!plugs.grep(*.^can: 'irc-unhandled') -> $p { my $res = $p.unhandled(self, $e); next EVENTS unless $res === IRC_NOT_HANDLED; } diff --git a/lib/IRC/Client/Plugin/Debugger.pm6 b/lib/IRC/Client/Plugin/Debugger.pm6 index 17cf697..131bb35 100644 --- a/lib/IRC/Client/Plugin/Debugger.pm6 +++ b/lib/IRC/Client/Plugin/Debugger.pm6 @@ -2,7 +2,7 @@ use Data::Dump; use IRC::Client::Plugin; unit class IRC::Client::Plugin::Debugger:ver<1.002001> is IRC::Client::Plugin; -method all-events ($irc, $e) { +method irc-all-events ($irc, $e) { say Dump $e, :indent(4); return IRC_NOT_HANDLED; } -- cgit v1.1