From 05647bd1f2312cc756f71152252a6349e86f43c5 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sun, 13 Dec 2015 19:14:23 -0500 Subject: update docs --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index b2bcad9..0568858 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ IRC::Client - Extendable Internet Relay Chat client # SYNOPSIS +## Client script + ```perl6 use IRC::Client; use IRC::Client::Plugin::Debugger; @@ -17,6 +19,49 @@ IRC::Client - Extendable Internet Relay Chat client ).run; ``` +## Custom plugins + +### Basic response to an IRC command: + +The plugin chain handling the message will stop after this plugin. + +``` +unit class IRC::Client::Plugin::PingPong is IRC::Client::Plugin; +method irc-ping ($irc, $msg) { $irc.ssay("PONG {$irc.nick} $msg[0]") } +``` + +### More involved handling + +On startup, start sending message `I'm an annoying bot` to all channels +every five seconds. We also subscribe to all events and print some debugging +info. By returning a special constant, we tell other plugins to continue +processing the data. + +``` +use IRC::Client::Plugin; # import constants +unit class IRC::Client::Plugin::Debugger is IRC::Client::Plugin; + +method register($irc) { + Supply.interval( 5, 5 ).tap({ + $irc.privmsg($_, "I'm an annoying bot!") + for $irc.channels; + }) +} + +method all-events ($irc, $e) { + say "We've got a private message" + if $e eq 'PRIVMSG' and $e[0] eq $irc.nick; + + # Store arbitrary data in the `pipe` for other plugins to use + $e = True + if $e eq 'PRIVMSG'; + + say $e, :indent(4); + return IRC_NOT_HANDLED; +} + +``` + # DESCRIPTION ***Note: this is a preview dev release. Things might change and new things -- cgit v1.1 From 512990b82b7129e9438d4a83b0a6a1d26a164285 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 08:40:04 -0500 Subject: some docs --- README.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 83 insertions(+), 17 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 0568858..5810376 100644 --- a/README.md +++ b/README.md @@ -187,11 +187,92 @@ working order of any IRC client. **Defaults to:** Takes no arguments. Starts the IRC client. Exits when the connection to the IRC server ends. -# PLUGINS +# INCLUDED PLUGINS Currently, this distribution comes with two IRC Client plugins: -## Writing your own +## IRC::Client::Plugin::Debugger + +```perl6 + use IRC::Client; + use IRC::Client::Plugin::Debugger; + + IRC::Client.new( + :host('localhost'), + :debug, + plugins => [ IRC::Client::Plugin::Debugger.new ] + ).run; +``` + +When run, it will pretty-print all of the events received by the client. It +does not stop plugin processing loop after handling a message. + +## IRC::Client::Plugin::PingPong + +```perl6 + use IRC::Client; + IRC::Client.new.run; # automatically included in plugins-essential +``` + +This plugin makes IRC::Client respond to server's C messages and is +included in the [`plugins-essential`](#plugins-essential) by default. + +# EXTENDING IRC::Client / WRITING YOUR OWN PLUGINS + +## Overview of the plugin system + +The core IRC::Client receives and parses IRC protocol messages from the +server that it then passes through a plugin chain. The plugins declared in +[`plugins-essential`](#plugins-essential) are executed first, followed by +plugins in [`plugins`](#plugins). The order is the same as the order specified +in those two lists. + +A plugin can return a [special constant](#return-value-constants) that +indicates it handled the message and the plugin chain processing should stop. + +To subscribe to handle a particular IRC command, a plugin simply declares a +method `irc-COMMAND`, where `COMMAND` is the name of the IRC command the +plugin wishes to handle. There are also a couple of +[special events](#special-events) the plugin can subscribe to, such as +intialization during start up or when the client receives a private message +or notice. + +## Return value constants + +```perl6 + use IRC::Client::Plugin; + unit class IRC::Client::Plugin::Foo is IRC::Client::Plugin; + ... +``` + +To make the constants available in your class, simply `use` IRC::Client::Plugin +class. + +### `IRC_HANDLED` + +```perl6 + # Returned by default + method irc-ping ($irc, $e) { $irc.ssay("PONG {$irc.nick} $e[0]") } + + # Explicit return + method irc-privmsg ($irc, $e) { return IRC_HANDLED; } +``` +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_HANDLED` was returned. + +### `IRC_NOT_HANDLED` + +```perl6 + return IRC_NOT_HANDLED; +``` +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. + + ```perl6 unit class IRC::Client::Plugin::Foo:ver<1.001001>; @@ -261,21 +342,6 @@ Sends a message to the server, automatically appending `\r\n`. Sends a `PRIVMSG` message specified in the second argument to the user/channel specified as the first argument. -## Included Plugins - -### `IRC::Client::Plugin::Debugger` - - plugins => [IRC::Client::Plugin::Debugger.new] - -Including this plugin will pretty-print parsed IRC messages on STDOUT. - -### `IRC::Client::Plugin::PingPong` - - plugins-essential => [IRC::Client::Plugin::PingPong.new] - -This plugin responds to server's `PING` requests and is automatically -included in the `plugins-essential` by default. - # REPOSITORY Fork this module on GitHub: -- cgit v1.1 From c97eb34b64788602713fcc77d3c18ab17b629318 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:10:03 -0500 Subject: Some docs --- README.md | 117 ++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 71 insertions(+), 46 deletions(-) (limited to 'README.md') 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 -- cgit v1.1 From af537ca94aa97565dea47c6fc3d176627e7ea4cc Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:24:01 -0500 Subject: Moar docs --- README.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 114 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 67cb299..1b9fd84 100644 --- a/README.md +++ b/README.md @@ -300,11 +300,12 @@ plugin chain for other plugins to handle. ```perl6 method irc-privmsg ($irc, $e) { ... } method irc-notice ($irc, $e) { ... } + method irc-353 ($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. +To subscribe to an IRC event, simply declare a method named `irc-command`, +where `command` is the IRC command you want to handle, in **lower case**. +The method takes two positional arguments: an `IRC::Client` object and +the [parsed IRC message](#contents-of-the-parsed-irc-message). 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 @@ -367,6 +368,115 @@ 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. +## Contents of the parsed IRC message + +```perl6 + # method irc-366 ($irc, $e) { ... } + { + command => "366".Str, + params => [ + "Perl6IRC".Str, + "#perl6bot".Str, + "End of NAMES list".Str, + ], + pipe => { }, + who => { + host => "irc.example.net".Str, + }, + } + + # method irc-join ($irc, $e) { ... } + { + command => "JOIN".Str, + params => [ + "#perl6bot".Str, + ], + pipe => { }, + who => { + host => "localhost".Str, + nick => "ZoffixW".Str, + user => "~ZoffixW".Str, + }, + } + + # method irc-privmsg ($irc, $e) { ... } + { + command => "PRIVMSG".Str, + params => [ + "#perl6bot".Str, + "Perl6IRC, hello!".Str, + ], + pipe => { }, + who => { + host => "localhost".Str, + nick => "ZoffixW".Str, + user => "~ZoffixW".Str, + }, + } + + # method irc-notice-me ($irc, $e) { ... } + { + command => "NOTICE".Str, + params => [ + "Perl6IRC".Str, + "you there?".Str, + ], + pipe => { }, + who => { + host => "localhost".Str, + nick => "ZoffixW".Str, + user => "~ZoffixW".Str, + }, + } +``` + +The second argument to event handlers is the parsed IRC message that is a +hash with the following keys: + +### `command` + +```perl6 + command => "NOTICE".Str, +``` +Contains the IRC command this message represents. + +### `params` + +```perl6 + params => [ + "Perl6IRC".Str, + "you there?".Str, + ], +``` +Constains the array of parameters for the IRC command. + +### pipe + +```perl6 + pipe => { }, +``` +This is a special key that can be used for communication between plugins. +While any plugin can modify any key of the parsed command's hash, the provided +`pipe` hash is simply a means to provide some standard, agreed-upon name +of a key to pass information around. + +### who + +```perl6 + #fdss + who => { + host => "localhost".Str, + nick => "ZoffixW".Str, + user => "~ZoffixW".Str, + }, + + who => { + host => "irc.example.net".Str, + }, +``` +A hash containing information on who sent the message. Messages sent by the +server do not have `nick`/`user` keys specified. + # REPOSITORY Fork this module on GitHub: -- cgit v1.1 From 3730baef0b8beba8750fc37908eb404d6b7b08fa Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:26:00 -0500 Subject: Mention bleed branch --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 1b9fd84..feeb982 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,13 @@ This modules lets you create in Perl 6. The plugin system lets you work on the behaviour, without worrying about IRC layer. +# BLEED BRANCH + +The master branch of this repository contains the latest working version +of the module. To get the bleeding-edge version, you can install from the +[bleed branch](https://github.com/zoffixznet/perl6-IRC-Client/tree/bleed), but +that code is not always guaranteed to be in working order. + # METHODS ## `new` -- cgit v1.1 From 92e69fbe171fea012c4e374d332768f1ef2f4173 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:27:05 -0500 Subject: Add TOC --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index feeb982..809b418 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,56 @@ IRC::Client - Extendable Internet Relay Chat client ).run; ``` +# TABLE OF CONTENTS +- [NAME](#name) +- [SYNOPSIS](#synopsis) + - [Client script](#client-script) + - [Custom plugins](#custom-plugins) + - [Basic response to an IRC command:](#basic-response-to-an-irc-command) + - [More involved handling](#more-involved-handling) +- [DESCRIPTION](#description) +- [BLEED BRANCH](#bleed-branch) +- [METHODS](#methods) + - [`new`](#new) + - [`debug`](#debug) + - [`host`](#host) + - [`port`](#port) + - [`nick`](#nick) + - [`username`](#username) + - [`userhost`](#userhost) + - [`userreal`](#userreal) + - [`channels`](#channels) + - [`plugins`](#plugins) + - [`plugins-essential`](#plugins-essential) + - [`run`](#run) +- [METHODS FOR PLUGINS](#methods-for-plugins) + - [`.ssay`](#ssay) + - [`.privmsg`](#privmsg) +- [INCLUDED PLUGINS](#included-plugins) + - [IRC::Client::Plugin::Debugger](#ircclientplugindebugger) + - [IRC::Client::Plugin::PingPong](#ircclientpluginpingpong) +- [EXTENDING IRC::Client / WRITING YOUR OWN PLUGINS](#extending-ircclient--writing-your-own-plugins) + - [Overview of the plugin system](#overview-of-the-plugin-system) + - [Return value constants](#return-value-constants) + - [`IRC_HANDLED`](#irc_handled) + - [`IRC_NOT_HANDLED`](#irc_not_handled) + - [Subscribing to IRC events](#subscribing-to-irc-events) + - [Standard IRC commands](#standard-irc-commands) + - [Special Events](#special-events) + - [`irc-all-events`](#irc-all-events) + - [`irc-privmsg-me`](#irc-privmsg-me) + - [`irc-notice-me`](#irc-notice-me) + - [`irc-unhandled`](#irc-unhandled) + - [Contents of the parsed IRC message](#contents-of-the-parsed-irc-message) + - [`command`](#command) + - [`params`](#params) + - [pipe](#pipe) + - [who](#who) +- [REPOSITORY](#repository) +- [BUGS](#bugs) +- [AUTHOR](#author) +- [LICENSE](#license) + ## Custom plugins ### Basic response to an IRC command: -- cgit v1.1 From 90217bd857f1aed87e892921b7f8e5296086af40 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:27:34 -0500 Subject: Formatting fixes --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 809b418..a61c5c9 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,8 @@ IRC::Client - Extendable Internet Relay Chat client - [Contents of the parsed IRC message](#contents-of-the-parsed-irc-message) - [`command`](#command) - [`params`](#params) - - [pipe](#pipe) - - [who](#who) + - [`pipe`](#pipe) + - [`who`](#who) - [REPOSITORY](#repository) - [BUGS](#bugs) - [AUTHOR](#author) @@ -507,7 +507,7 @@ Contains the IRC command this message represents. ``` Constains the array of parameters for the IRC command. -### pipe +### `pipe` ```perl6 pipe => { }, @@ -517,7 +517,7 @@ While any plugin can modify any key of the parsed command's hash, the provided `pipe` hash is simply a means to provide some standard, agreed-upon name of a key to pass information around. -### who +### `who` ```perl6 #fdss -- cgit v1.1 From 90b0541926acb6ef39cb0ad5c854687662f32d0a Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:28:29 -0500 Subject: Fix synopsis --- README.md | 86 +++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 43 insertions(+), 43 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index a61c5c9..e32dec8 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,49 @@ IRC::Client - Extendable Internet Relay Chat client ).run; ``` +## Custom plugins + +### Basic response to an IRC command: + +The plugin chain handling the message will stop after this plugin. + +``` +unit class IRC::Client::Plugin::PingPong is IRC::Client::Plugin; +method irc-ping ($irc, $msg) { $irc.ssay("PONG {$irc.nick} $msg[0]") } +``` + +### More involved handling + +On startup, start sending message `I'm an annoying bot` to all channels +every five seconds. We also subscribe to all events and print some debugging +info. By returning a special constant, we tell other plugins to continue +processing the data. + +``` +use IRC::Client::Plugin; # import constants +unit class IRC::Client::Plugin::Debugger is IRC::Client::Plugin; + +method register($irc) { + Supply.interval( 5, 5 ).tap({ + $irc.privmsg($_, "I'm an annoying bot!") + for $irc.channels; + }) +} + +method all-events ($irc, $e) { + say "We've got a private message" + if $e eq 'PRIVMSG' and $e[0] eq $irc.nick; + + # Store arbitrary data in the `pipe` for other plugins to use + $e = True + if $e eq 'PRIVMSG'; + + say $e, :indent(4); + return IRC_NOT_HANDLED; +} + +``` + # TABLE OF CONTENTS - [NAME](#name) - [SYNOPSIS](#synopsis) @@ -69,49 +112,6 @@ IRC::Client - Extendable Internet Relay Chat client - [AUTHOR](#author) - [LICENSE](#license) -## Custom plugins - -### Basic response to an IRC command: - -The plugin chain handling the message will stop after this plugin. - -``` -unit class IRC::Client::Plugin::PingPong is IRC::Client::Plugin; -method irc-ping ($irc, $msg) { $irc.ssay("PONG {$irc.nick} $msg[0]") } -``` - -### More involved handling - -On startup, start sending message `I'm an annoying bot` to all channels -every five seconds. We also subscribe to all events and print some debugging -info. By returning a special constant, we tell other plugins to continue -processing the data. - -``` -use IRC::Client::Plugin; # import constants -unit class IRC::Client::Plugin::Debugger is IRC::Client::Plugin; - -method register($irc) { - Supply.interval( 5, 5 ).tap({ - $irc.privmsg($_, "I'm an annoying bot!") - for $irc.channels; - }) -} - -method all-events ($irc, $e) { - say "We've got a private message" - if $e eq 'PRIVMSG' and $e[0] eq $irc.nick; - - # Store arbitrary data in the `pipe` for other plugins to use - $e = True - if $e eq 'PRIVMSG'; - - say $e, :indent(4); - return IRC_NOT_HANDLED; -} - -``` - # DESCRIPTION ***Note: this is a preview dev release. Things might change and new things -- cgit v1.1 From 60ce4c8fab7770317de3ef83f87f0dba438777b3 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:28:57 -0500 Subject: Indicate we"re running P6 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index e32dec8..d99a834 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ IRC::Client - Extendable Internet Relay Chat client The plugin chain handling the message will stop after this plugin. -``` +```perl6 unit class IRC::Client::Plugin::PingPong is IRC::Client::Plugin; method irc-ping ($irc, $msg) { $irc.ssay("PONG {$irc.nick} $msg[0]") } ``` @@ -37,7 +37,7 @@ every five seconds. We also subscribe to all events and print some debugging info. By returning a special constant, we tell other plugins to continue processing the data. -``` +```perl6 use IRC::Client::Plugin; # import constants unit class IRC::Client::Plugin::Debugger is IRC::Client::Plugin; -- cgit v1.1 From b237e80bf44419a64d8ba43bf44e428563f2ac6e Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:31:27 -0500 Subject: add Author name --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index d99a834..78d3a7e 100644 --- a/README.md +++ b/README.md @@ -546,7 +546,7 @@ https://github.com/zoffixznet/perl6-IRC-Client/issues # AUTHOR -http://zoffix.com/ +Zoffix Znet (http://zoffix.com/) # LICENSE -- cgit v1.1 From c3ac49e463440b318fa70cfddaed3f91c6797556 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:43:30 -0500 Subject: Add irc-start-up and irc-connected methods. Toss irc-register --- README.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 78d3a7e..37840c9 100644 --- a/README.md +++ b/README.md @@ -371,6 +371,9 @@ response. ## Special Events ```perl6 + method irc-start-up ($irc) { ... } # once per client run + method irc-connected ($irc) { ... } # once per server connection + method irc-all-events ($irc, $e) { ... } method irc-privmsg-me ($irc, $e) { ... } method irc-notice-me ($irc, $e) { ... } @@ -379,13 +382,38 @@ response. ``` 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 +shown above (except for [`irc-start-up`](#irc-start-up) and +[`irc-connected`](#irc-connected) that do not offect command-triggered events). +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. The available special events are as follows: +### `irc-start-up` + +```perl6 + method irc-start-up ($irc) { ... } +``` +Passed IRC::Client object as the only argument. Triggered right when the +IRC::Client is [`.run`](#run), which means most of +[METHODS FOR PLUGINS](#methods-for-plugins) **cannot** be used, as no connection +has been made yet. This event will be issued only once per [`.run`](#run) +and the method's return value is discarded. + +### `irc-connected` + +```perl6 + method irc-connected ($irc) { ... } +``` +Passed IRC::Client object as the only argument. Triggered right when we +get a connection to the server, identify with it and issue `JOIN` commands +to enter the channels. Note that at this point it is not guaranteed that the +client is already in all the channels it's meant to join. +This event will be issued only once per connection to the server +and the method's return value is discarded. + ### `irc-all-events` ```perl6 @@ -404,7 +432,7 @@ stop handling ALL other messages ```perl6 method irc-privmsg-me ($irc, $e) { ... } ``` -Triggered when the IRC `PRIVMSG` command is received, where the receipient +Triggered when the IRC `PRIVMSG` command is received, where the recipient is the client (as opposed to some channel). ### `irc-notice-me` @@ -412,7 +440,7 @@ is the client (as opposed to some channel). ```perl6 method irc-notice-me ($irc, $e) { ... } ``` -Triggered when the IRC `NOTICE` command is received, where the receipient +Triggered when the IRC `NOTICE` command is received, where the recipient is the client (as opposed to some channel). ### `irc-unhandled` -- cgit v1.1 From ebb509e5b106fdf24640b11f32e776f033a314e8 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:45:27 -0500 Subject: Update TOC --- README.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 37840c9..75fd4ce 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,7 @@ method all-events ($irc, $e) { - [Custom plugins](#custom-plugins) - [Basic response to an IRC command:](#basic-response-to-an-irc-command) - [More involved handling](#more-involved-handling) +- [TABLE OF CONTENTS](#table-of-contents) - [DESCRIPTION](#description) - [BLEED BRANCH](#bleed-branch) - [METHODS](#methods) @@ -98,6 +99,8 @@ method all-events ($irc, $e) { - [Subscribing to IRC events](#subscribing-to-irc-events) - [Standard IRC commands](#standard-irc-commands) - [Special Events](#special-events) + - [`irc-start-up`](#irc-start-up) + - [`irc-connected`](#irc-connected) - [`irc-all-events`](#irc-all-events) - [`irc-privmsg-me`](#irc-privmsg-me) - [`irc-notice-me`](#irc-notice-me) -- cgit v1.1 From 3ef85d79fec87c063aeb00a605fd8d40d2ec5cb4 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:48:38 -0500 Subject: Use a better example --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 75fd4ce..77ab9d5 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,10 @@ IRC::Client - Extendable Internet Relay Chat client use IRC::Client::Plugin::Debugger; IRC::Client.new( - :host('localhost'), - :debug, - plugins => [ IRC::Client::Plugin::Debugger.new ] + :host('localhost') + :channels<#perl6bot #zofbot> + :debug + :plugins( IRC::Client::Plugin::Debugger.new ) ).run; ``` -- cgit v1.1 From ebdb216d4d47e1ab061e3719fe3af01856d2486f Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Mon, 21 Dec 2015 09:53:40 -0500 Subject: Use a more idomatic example --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 77ab9d5..328bfe1 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ IRC::Client - Extendable Internet Relay Chat client use IRC::Client::Plugin::Debugger; IRC::Client.new( - :host('localhost') + :host :channels<#perl6bot #zofbot> :debug :plugins( IRC::Client::Plugin::Debugger.new ) -- cgit v1.1