NAME

Message::Stack - Deal with a "stack" of messages

VERSION

version 0.20

SYNOPSIS

    my $stack = Message::Stack->new;

    $stack->add(Message::Stack::Message->new(
      msgid     => 'something_happened',
      level     => 'error',
      scope     => 'login_formm',
      subject   => 'username',
      text      => 'Something happened!'
    ));
    # Or... for those that want to type less
    $stack->add({
      msgid     => 'something_else_happened',
      level     => 'error',
      scope     => 'login_form',
      subject   => 'password',
      text      => 'Something else happened!'
    });

    ...
    my $errors = $stack->for_level($error);
    # Or
    my $login_form_errors = $stack->for_scope('login_form');
    $login_form_errors->for_subject('username');
    print "Username has ".$login_form_errors->count." errors.\n";

DESCRIPTION

Message::Stack provides a mechanism for storing messages until they can be consumed. A stack is used to retain order of occurrence. Each message may have a id, level, scope, subject and text. Consult the documentation for Message::Stack::Message for an explanation of these attributes.

This is not a logging mechanism. The original use was to store various errors or messages that occur during processing for later display in a web application. The messages are added via add.

NOTES

Note About msgid

msgid used to be id. It was renamed to be a bit more description. All the methods that existed for id still exist and the id attribute is now aliased to msgid. In other words if you create an object using id then the msgid methods and the id methods will work, and vice versa.

SERIALIZATION

This module uses MooseX::Storage::Deferred to facilitate easy serialization. Consult the documentation for MooseX::Storage::Deferred options, but the gist is:

  my $json = $stack->freeze({ format => 'JSON' });
  ...
  my $stack = Message::Stack->thaw($json, { format => 'JSON' });

ATTRIBUTES

messages

Returns the full arrayref of messages for this stack.

METHODS

count

Returns the number of messages in the stack.

first_message

Returns the first message (if there is one, else undef)

get_message ($index)

Get the message at the supplied index.

has_messages

Returns true if there are messages in the stack, else false

last_message

Returns the last message (if there is one, else undef)

reset

Clear all messages, resetting this stack.

add ($message)

Adds the supplied message to the stack. $message may be either a Message::Stack::Message object or a hashref with similar keys.

for_msgid ($msgid)

Returns a new Message::Stack containing only the message objects with the supplied msgid. If there are no messages for that level then the stack returned will have no messages.

for_level ($level)

Returns a new Message::Stack containing only the message objects with the supplied level. If there are no messages for that level then the stack returned will have no messages.

for_scope ($scope)

Returns a new Message::Stack containing only the message objects with the supplied scope. If there are no messages for that scope then the stack returned will have no messages.

for_subject ($subject)

Returns a new Message::Stack containing only the message objects with the supplied subject. If there are no messages for that subject then the stack returned will have no messages.

has_msgid ($msgid)

Returns true if there are messages with the supplied msgid.

has_level ($level)

Returns true if there are messages with the supplied level.

has_scope ($scope)

Returns true if there are messages with the supplied scope.

has_subject ($subject)

Returns true if there are messages with the supplied subject.

search (CODEREF)

Returns a Message::Stack containing messages that return true when passed to the coderef argument.

  $stack->search( sub { $_[0]->id eq 'someid' } )

reset_scope($scope)

Clears the stack of all messages of scope $scope.

reset_level($level)

Clears the stack of all messages of level $level.

reset_msgid($msgid)

Clears the stack of all messages of msgid $msgid.

reset_subject($subject)

Clears the stack of all messages of subject $subject.

CONTRIBUTORS

Jay Shirley

Stevan Little

Justin Hunter

Jon Wright

Mike Eldridge

Andrew Nelson

AUTHOR

Cory G Watson <gphat@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Cory G Watson.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Message::Stack

perl -MCPAN -e shell
install Message::Stack