This document describes events available on various objects in use when working
with IRC::Client.
- Message Objects (
IRC::Client::Messageand subclasses)- Message Object Hierarchy
- Methods and Attributes
IRC::Client::MessageIRC::Client::Message::JoinIRC::Client::Message::NickIRC::Client::Message::NumericIRC::Client::Message::PartIRC::Client::Message::PingIRC::Client::Message::QuitIRC::Client::Message::UnknownIRC::Client::Message::ModeIRC::Client::Message::Mode::ChannelIRC::Client::Message::Mode::MeIRC::Client::Message::NoticeIRC::Client::Message::Notice::ChannelIRC::Client::Message::Notice::MeIRC::Client::Message::PrivmsgIRC::Client::Message::Privmsg::ChannelIRC::Client::Message::Privmsg::Me
- Server Object (
IRC::Client::Server) - Client Object (
IRC::Client) - Up Next
All event handlers (except for special irc-started) receive one positional
argument that does IRC::Client::Message role and is refered to as
the Message Object throughout the documentation. The actual received
message object depends on the event the event handler is subscribed to.
See event reference to learn which message objects
an event can receive.
All message objects reside in the IRC::Client::Message package and
follow the following hierarchy, with children having all the methods
and attributes of their parents.
IRC::Client::Message
│
├───IRC::Client::Message::Join
├───IRC::Client::Message::Nick
├───IRC::Client::Message::Numeric
├───IRC::Client::Message::Part
├───IRC::Client::Message::Ping
├───IRC::Client::Message::Quit
├───IRC::Client::Message::Unknown
│
├───IRC::Client::Message::Mode
│ ├───IRC::Client::Message::Mode::Channel
│ └───IRC::Client::Message::Mode::Me
│
├───IRC::Client::Message::Notice
│ ├───IRC::Client::Message::Notice::Channel
│ └───IRC::Client::Message::Notice::Me
│
└───IRC::Client::Message::Privmsg
├───IRC::Client::Message::Privmsg::Channel
└───IRC::Client::Message::Privmsg::Me
Subclasses inherit all the methods and attributes of their parents (see
hierarchy chart above). Some event handlers can receive more than one
type of a message object. In many cases, the type can be differentiated
with a safe-method-call operator (.?):
method irc-privmsg ($e) {
if $e.?channel {
say '$e is a IRC::Client::Message::Privmsg::Channel';
}
else {
say '$e is a IRC::Client::Message::Privmsg::Me';
}
}Object is never sent to event handlers and merely provides commonality to its subclasses.
Contains the IRC::Client object.
Contains the nick of the sender of the message.
Contains the username of the sender of the message.
Contains the host of the sender of the message.
Contains the usermask of the sender of the message. That is
string constructed as nick!username@host
The IRC command responsible for this event, such as PRIVMSG or 001.
The IRC::Client::Server object from which the event originates.
A possibly-empty list of arguments, received for the IRC command that triggered the event.
(affects stringification of message objects). Returns a string
constructed from ":$!usermask $!command $!args[]", but is overriden to
a different value by some message objects.
Contains the channel name of the channel that was joined
Contains the new nick switched to (.nick attribute contains the old one).
Does not offer any object-specific methods. Use the .command attribute
to find out the actual 3-digit IRC command that triggered the event.
Contains the channel name of the channel that was parted. Use .args
attribute to get any potential parting messages.
Included in the docs for completeness only. Used internally. Not sent
to any event handlers and irc-ping is not a valid event.
Takes no arguments. Replies to the server with appropriate PONG IRC command.
Does not offer any object-specific methods. Use .args
attribute to get any potential quit messages.
Overrides the default stringification string to
"❚⚠❚ :$.usermask $.command $.args[]"
Object is never sent to event handlers and merely provides commonality to its subclasses.
Contains the modes set by the IRC command that triggered the event. When
modes are set on the channel, contains a string with the sign of the mode
(+ or -) and the value if the mode letter(s) itself.
Contains the channel on which the modes were set.
Contains an array with the nicks on which the mode was set.
Does not offer any object-specific methods.
Object is never sent to event handlers and merely provides commonality to its subclasses.
Writable attribute. Contains the text of the message. For addressed commands,
the nick will be stripped. Use .args method to get full, original text,
which will be the second value in the list.
Writable Bool attribute. Automatically gets set to True by the
.reply method. If set to True, indicates to the Client Object that
the event handler's value must not be used as a reply to the message.
Overrides stringification of the message object to be the value of the
.text attribute.
Contains the channel to which the message was sent.
$e.reply: "Hello, World!";
$e.reply: "Hello, World!", :where<#raku>;
$e.reply: "Hello, World!", :where<Zoffix>;Replies to the sender of the message using the NOTICE IRC command. The
optional :where argument specifies a channel or nick
where to send the message and defaults to the channel in which the message
originated.
$e.reply: "Hello, World!";
$e.reply: "Hello, World!", :where<Zoffix>;
$e.reply: "Hello, World!", :where<#raku>;Replies to the sender of the message using the NOTICE IRC command. The
optional :where argument specifies a nick or channel
where to send the message and defaults to the nick from which the message
originated.
Object is never sent to event handlers and merely provides commonality to its subclasses.
Writable attribute. Contains the text of the message. For addressed commands,
the nick will be stripped. Use .args method to get full, original text,
which will be the second value in the list.
Writable Bool attribute. Automatically gets set to True by the
.reply method. If set to True, indicates to the Client Object that
the event handler's value must not be used as a reply to the message.
Overrides stringification of the message object to be the value of the
.text attribute.
Contains the channel to which the message was sent.
$e.reply: "Hello, World!";
$e.reply: "Hello, World!", :where<#raku>;
$e.reply: "Hello, World!", :where<Zoffix>;Replies to the sender of the message using the PRIVMSG IRC command. The
optional :where argument specifies a channel or nick
where to send the message and defaults to the channel in which the message
originated.
$e.reply: "Hello, World!";
$e.reply: "Hello, World!", :where<Zoffix>;
$e.reply: "Hello, World!", :where<#raku>;Replies to the sender of the message using the PRIVMSG IRC command. The
optional :where argument specifies a nick or channel
where to send the message and defaults to the nick from which the message
originated.
The Server Object represents one of the IRC servers the client is connected
to. It's returned by the .server attribute of the Message Object and
can be passed to various Client Object methods to indicate to which server
a command should be sent to.
Client Object's %.servers attribute contains all of the IRC::Client::Server
objects with their keys as labels and values as objects themselves.
Each IRC::Client::Server object has a label that was given to it during
the creation of IRC::Client object. IRC::Client::Server objects stringify
to the value of their labels and methods that can take an
IRC::Client::Server object can also take a Str with the label of that server
instead.
The label of this server.
A list of Str or Pair containing all the channels the client is in on this
server. Pairs represent channels with channel passwords, where the key is
the channel and the value is its password.
A list of nicks the client uses on this server. If one nick is taken, next one in the list will be attempted to be used.
A list of aliases on this server.
The host of the server.
The port of the server.
The password of the server.
Our username on this server.
Our hostname on this server.
The "real name" of our client.
Affects stringification of the object and makes it stringify to the value
of .label attribute.
The following attributes are writable, however, they are written to by the internals and the behaviour when writing to them directly is undefined.
Writable attribute. Our currently-used nick. Will be one of the nicks returned
by .nicks.
Writable Bool attribute. Indicates whether we're currently in a state
where the server considers us connected. This defaults to False, then is set
to True when the server sends us 001 IRC command and set back to False
when the socket connection breaks.
Writable Bool attribute. Set to True when .quit method is called
on the Client Object and is used by the socket herder to determine whether
or not the socket connection was cut intentionally.
Writable IO::Socket::Async attribute. Contains an object representing
the socket connected to the server, although it may already be closed.
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.
$.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.
my $irc = IRC::Client.new:
:debug
:host<irc.freenode.net>
:6667port
:password<s3cret>
:channels<#perl #raku #rust-lang>
:nick<MahBot>
:alias('foo', /b.r/)
:username<MahBot>
:userhost<localhost>
:userreal('Mah awesome bot!')
:servers(
freenode => %(),
local => %( :host<localhost> ),
)
: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('#rakubot', '#zofbot', '#myown' => 's3cret')A list of Str or Pair containing the channels to join.
Pairs represent channels with channel passwords, where the key is
the channel and the value is its password.
Defaults to: #raku
Takes an Int. When set to a positive number, causes debug output to be
generated. Install optional
[Terminal::ANSIColor]https://modules.raku.org/repo/Terminal::ANSIColor] to
make output colourful. Debug levels:
0—no debug output1—basic debug output2—also include list of emitted events3—also includeirc-allin the list of emitted events
Defaults to: 0
Takes a list of Callables. 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.
The hostname of the IRC server to connect to.
Defaults to: localhost
A list of nicknames to use. If set to just one value will automatically
generate three additional nicknames that have underscores appended
(e.g. RakuBot, RakuBot_, RakuBot__, RakuBot___).
If one of the given nicks is in use, the client will attempt to use the next one in the list.
Defaults to: RakuBot
:alias('foo', /b.r/)A list of Str or Regex objects that in the context of
irc-addressed, irc-to-me, and irc-mentioned events will be used
as alternative nicks. In other words, specifying 'bot' as alias will allow
you to address the bot using bot nick, regardless of the actual nick the
bot is currently using.
Defaults to: empty list
The server password to use. On some networks (like Freenode), the server password also functions as NickServ's password. By default not specified.
Takes a list of instantiated objects or type objects that implement the functionality of the system. See basics tutorial and event reference for more information on how to implement plugin classes.
By default not specified.
The port of the IRC server to connect to. Takes an Int between 0 and 65535.
Defaults to: 6667
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.
If :servers is not specified, then a server will be created with the
label _ (underscore).
By default not specified.
The IRC username to use. Defaults to: RakuIRC
The hostname of your client. Defaults to: localhost and can probably
be left as is, unless you're having issues connecting.
The "real name" of your client. Defaults to: Raku IRC Client
$.irc.nick: 'MahBot', :$server;
$.irc.nick: <MahBot MahBot2 MahBot3 MahBot4 MahBot5>, :$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.
$.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.
$.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.
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.
$.irc.send: :where<Zoffix> :text<Hello!>;
$.irc.send: :where<#raku> :text('I ♥ Raku!');
$.irc.send: :where<Senpai> :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
Read Big Picture behaviour next.