NAME

Bot::Backbone::Message - Describes a message or response

VERSION

version 0.161950

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) 2016 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.