From 1380a1c294aee79ed64302dbbe8e9ad05872f0c3 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 29 Jul 2016 15:56:18 -0400 Subject: Document IRC::Client methods --- docs/03-method-reference.md | 211 ++++++++++++++++++++++++++++++++++++++- docs/04-big-picture-behaviour.md | 3 + lib/IRC/Client.pm6 | 2 +- 3 files changed, 214 insertions(+), 2 deletions(-) create mode 100644 docs/04-big-picture-behaviour.md diff --git a/docs/03-method-reference.md b/docs/03-method-reference.md index 85e86e4..9221474 100644 --- a/docs/03-method-reference.md +++ b/docs/03-method-reference.md @@ -413,6 +413,215 @@ the socket connected to the server, although it may already be closed. --- ## Client Object (`IRC::Client`) + +The Client Object is the heart of this module. The `IRC::Client` you instantiate +and `.run`. The running Client Object is available to your plugins via +`.irc` attribute that you can obtain by doing the `IRC::Client::Plugin` role +or via `.irc` attribute on Message Objects your event handler receives. + +The client object's method let you control the client: e.g. joining or parting +channels, changing nicks, banning users, or sending text messages. + +### Methods and Attributes + +#### `.join` + +```perl6 + $.irc.join: <#foo #bar #ber>, :$server; +``` + +Causes the client join the provided channels. +If `:server` named argument is given, will operate only on that server; +otherwise operates on all connected servers. + +#### `.new` + +```perl6 +my $irc = IRC::Client.new: + :debug + :host + :6667port + :password + :channels<#perl #perl6 #rust-lang> + :nick + :username + :userhost + :userreal('Mah awesome bot!') + :servers( + freenode => %(), + local => %( :host ), + ) + :plugins( + class { method irc-to-me ($ where /42/) { 'The answer to universe!' } } + ) + :filters( + -> $text where .lines > 5 or .chars > 300 { "Text is too big!!!" } + ) +``` + +Instantiates a new `IRC::Client` object. Takes the following named arguments: + +##### `:channels` + +A list of IRC channels to join. **Defaults to:** `#perl6` + +##### `:debug` + +Takes an `Int`. When set to a positive number, causes debug output to be +generated. Install optional +[Terminal::ANSIColor]https://modules.perl6.org/repo/Terminal::ANSIColor] to +make output colourful. Debug levels: + +* `0`—no debug output +* `1`—basic debug output +* `2`—also include list of emitted events +* `3`—also include `irc-all` in the list of emitted events + +**Defaults to:** `0` + +##### `:filters` + +Takes a list of `Callable`s. Will attempt to call them for replies to +`PRIVMSG` and `NOTICE` events if the signatures accept `($text)` or +`($text, :$where)` calls, where `$text` is the reply text and `:$where` is +a named argument of the destination of the reply (either a user or a channel +name). + +Callables with `:$where` in the signature must return two values: the new +text to reply with and the location. Otherwise, just one value needs to +be returned: the new text to reply with. + +**By default** not specified. + +##### `:host` + +The hostname of the IRC server to connect to. +**Defaults to:** `localhost` + +##### `:nick` + +A list of nicknames to use. If set to just one value will automatically +generate three additional nicknames that have underscores appended +(e.g. `P6Bot`, `P6Bot_`, `P6Bot__`, `P6Bot___`). + +If one of the given nicks is in use, the client will attempt to use the +next one in the list. + +**Defaults to:** `P6Bot` + +##### `:password` + +The server password to use. On some networks (like Freenode), the server +password also functions as NickServ's password. +**By default** not specified. + +##### `:plugins` + +Takes a list of instantiated objects or type objects that implement the +functionality of the system. See [basics tutorial](01-basics.md) and +[event reference](02-event-reference.md) for more information on how +to implement plugin classes. + +**By default** not specified. + +##### `:port` + +The port of the IRC server to connect to. Takes an `Int` between 0 and 65535. +**Defaults to:** `6667` + +##### `:servers` + +Takes an `Assosiative` with keys as labels of servers and values with +server-specific configuration. Valid keys in the configuration are +`:host`, `:port`, `:password`, `:channels`, `:nick`, `:username`, +`:userhost`, and `:userreal`. They take the same values as same-named arguments +of the `IRC::Client.new` method and if any key is omitted, the value +of the `.new`'s argument will be used. + +##### `:username` + +The IRC username to use. **Defaults to:** `Perl6IRC` + +##### `:userhost` + +The hostname of your client. **Defaults to:** `localhost` and can probably +be left as is, unless you're having issues connecting. + +##### `:userreal` + +The "real name" of your client. **Defaults to:** `Perl6 IRC Client` + +---- + +#### `.nick` + +```perl6 + $.irc.nick: 'MahBot', :$server; + $.irc.nick: , :$server; +``` + +Causes the client to change its nick to the one provided and uses this +as new value of `.current-nick` and `.nick` attributes of the appropriate +`IRC::Client::Server` object. If only one nick +is given, another 3 nicks will be automatically generated by appending +a number of underscores. Will automatically retry nicks further in the list +if the currently attempted one is already in use. + +If `:server` named argument is given, will operate only on that server; + otherwise operates on all connected servers. + +#### `.part` + +```perl6 + $.irc.part: <#foo #bar #ber>, :$server; +``` + +Causes the client part the provided channels. +If `:server` named argument is given, will operate only on that server; +otherwise operates on all connected servers. + +#### `.quit` + +```perl6 + $.irc.quit; + $.irc.quit: :$server; +``` + +Causes the client to quit the IRC server. +If `:server` named argument is given, will operate only on that server; +otherwise operates on all connected servers. + +#### `.run` + +Takes no arguments. Runs the IRC client, causing it to connect to servers +and do all of its stuff. Returns only if all of the servers the client connects +to have been explicitly `.quit` from. + +#### `.send` + +```perl6 + $.irc.send: :where :text; + $.irc.send: :where<#perl6> :text('I ♥ Perl 6!'); + $.irc.send: :where :text('Notice me!') :notice :$server; +``` + +Sends a `:text` message to `:where`, using either a `PRIVMSG` or `NOTICE`. +The `:where` can be either a user's nick or a channel name. If `:notice` +argument is set to a `True` value will use `NOTICE` otherwise will use +`PRIVMSG` (if you just want to send text to channel like you'd normally +do when talking with regular IRC clients, that'd be the `PRIVMSG` messages). + +If `:server` named argument is given, will operate only on that server; +otherwise operates on all connected servers. + +**NOTE:** calls to `.send` when server is not connected yet will be +**semi-silently ignored** (only debug output will mention that they were +ignored). This is done on purpose, to prevent `.send` calls from interfering +with the connection negotiation during server reconnects. Although not +free from race conditions, you can mitigate this issue by checking the +`.is-connected` attribute on the appropriate `IRC::Client::Server` object +before attempting the `.send` + ## Up Next -Read [the method reference](03-method-reference.md) next. +Read [Big Picture behaviour](04-big-picture-behaviour) next. diff --git a/docs/04-big-picture-behaviour.md b/docs/04-big-picture-behaviour.md new file mode 100644 index 0000000..17513c4 --- /dev/null +++ b/docs/04-big-picture-behaviour.md @@ -0,0 +1,3 @@ +[[back to main docs]](../README.md#documentation-map) + +# Big-Picture Behaviour diff --git a/lib/IRC/Client.pm6 b/lib/IRC/Client.pm6 index bd9685e..6b442da 100644 --- a/lib/IRC/Client.pm6 +++ b/lib/IRC/Client.pm6 @@ -34,7 +34,7 @@ submethod BUILD ( Int:D :$port where 0 <= $_ <= 65535 = 6667, Str :$password, Str:D :$host = 'localhost', - :$nick = ['P6Bot', 'P6Bot_', 'P6Bot__'], + :$nick = ['P6Bot'], Str:D :$username = 'Perl6IRC', Str:D :$userhost = 'localhost', Str:D :$userreal = 'Perl6 IRC Client', -- cgit v1.1