NAME
Bot::Backbone::Message - Describes a message or response
VERSION
version 0.142220
SYNOPSIS
# E.g., passed in to dispatcher predicates
my $message = ...;
say $message->from->nickname, ' says, "', $message->text, '"';
my $chatroom = $message->group;ATTRIBUTES
chat
This is the Bot::Backbone::Service::Role::Chat chat engine where the message originated.
from
This is the Bot::Backbone::Identity representing the user sending the message.
to
This is undef or the Bot::Backbone::Identity representing hte user the message is directed toward. If sent to a room or if this is a broadcast message, this will be undef.
A message to a room may also be to a specific person, this may show that as well.
group
This is the name of the chat room.
volume
This is the volume of the message. It must be one of the following values:
- shout
-
This is a message sent across multiple chats and channels, typically a system message or administrator alert.
- spoken
-
This is a message stated to all the users within the chat. This is the normal volume level.
- whisper
-
This is a message stated to only a few users within the chat, usually just one, the recipient.
text
This is the message that was sent.
args
This is a list of "arguments" passed into the bot. Each arg is a Bot::Backbone::Message:Arg object, which is a simple Moose object with only two attributes: text and original. The text is the value of the argument and the original is the original piece of the message "text" for that value, which contains whitespace, quotation marks, etc.
flags
These are flags associated with the message. These may be used by dispatcher to make notes about how the message has been dispatched or identifying features of the message.
See add_flag, add_flags, remove_flag, remove_flags, has_flag, and has_flags.
bookmarks
When processing a dispatcher, the predicates consume parts of the message in the process. This allows us to keep a stack of pass message parts in case the predicate ultimately fails.
parameters
These are parameters assoeciated with the message created by the dispatcher predicates while processing the message.
is_group
Returns true if this message happened in a chat group/room/channel.
is_direct
Returns true if this message was sent directly to the receipient.
add_flag
add_flags
$message->add_flag('foo');
$message->add_flags(qw( bar baz ));Set a flag on this message.
remove_flag
remove_flags
$message->remove_flag('foo');
$message->remove_flags(qw( bar baz ));Unsets a flag on this message.
has_flag
has_flags
$message->has_flag('foo');
$message->has_flags(qw( bar baz ));Returns true if all the flags passed are set. Returns false if any of the flags named are not set.
is_to_me
Returns true of the message is to me.
set_bookmark
$message->set_bookmark;Avoid using this method. See "set_bookmark_do".
Saves the current message in the bookmarks stack.
restore_bookmark
$mesage->restore_bookmark;Avoid using this method. See "set_bookmark_do".
Restores the bookmark on the top of the bookmarks stack. The "to", "from", "group", "text", "parameters", and "args" are restored. All other attribute modifications will stick.
set_bookmark_do
$message->set_bookmark_do(sub {
...
});Saves the current message on the top of the stack using "set_bookmark". Then, it runs the given code. Afterwards, any modifications to the message will be restored to the original using "restore_bookmark".
match_next
my $value = $message->match_next('!command');
my $value = $message->metch_next(qr{!(?:this|that)});Given a regular expression or string, matches that against the next argument in the "args" and strips off the match. It returns the match if the match is successful or returns undef. If given a regular express, the match will not succeed unless it matches the entire argument (i.e., a ^ is added to the front and $ is added to the end).
match_next_original
my $value = $message->match_next_original(qr{.+});Given a regular expression, this will match that against the remaining unmatched text (not via "args", but via the unparsed "text"). A ^ at the front of the regex will be added to match against "text".
If there's a match, the matching text is returned.
reply
$message->reply($sender, 'blah blah blah');Sends a reply back to the entity sending the message or the group that sent it, using the chat service that created the message.
The first argument must be a Bot::Backbone::Service::Role::Sender or Bot::Backbone::Bot, which should be the service or bot sending the reply. The send policy set for that sender will be applied. You may pass undef or anything else as the sender, but a warning will be issued.
AUTHOR
Andrew Sterling Hanenkamp <hanenkamp@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Qubling Software LLC.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.