The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Log::Shiras::Report::MetaMessage - Add data to messages for reports

SYNOPSIS

        use MooseX::ShortCut::BuildInstance qw( build_class );
        use Log::Shiras::Report;
        use Log::Shiras::Report::MetaMessage;
        use Data::Dumper;
        my      $message_class = build_class(
                        package => 'Test',
                        add_roles_in_sequence => [
                                'Log::Shiras::Report',
                                'Log::Shiras::Report::MetaMessage',
                        ],
                        add_methods =>{
                                add_line => sub{ 
                                        my( $self, $message ) = @_;
                                        print Dumper( $message->{message} );
                                        return 1;
                                },
                        }
                );
        my      $message_instance = $message_class->new( 
                        prepend =>[qw( lets go )],
                        postpend =>[qw( store package )],
                ); 
        $message_instance->add_line({ message =>[qw( to the )], package => 'here', });
        
        #######################################################################################
        # Synopsis output to this point
        # 01: $VAR1 = [
        # 02:           'lets',
        # 03:           'go',
        # 04:           'to',
        # 05:           'the',
        # 06:           'store',
        # 07:           'here'
        # 08:         ];
        #######################################################################################
        
        $message_instance->set_post_sub(
                sub{
                        my $message = $_[0];
                        my $new_ref;
                        for my $element ( @{$message->{message}} ){
                                push @$new_ref, uc( $element );
                        }
                        $message->{message} = $new_ref;
                }
        );
        $message_instance->add_line({ message =>[qw( from the )], package => 'here', });
        
        #######################################################################################
        # Synopsis output addition to this point
        # 01: $VAR1 = [
        # 02:           'LETS',
        # 03:           'GO',
        # 04:           'FROM',
        # 05:           'THE',
        # 06:           'STORE',
        # 07:           'HERE'
        # 08:         ];
        #######################################################################################
        
        $message_instance = $message_class->new(
                hashpend => {
                        locate_jenny => sub{
                                my $message = $_[0];
                                my $answer;
                                for my $person ( keys %{$message->{message}->[0]} ){
                                        if( $person eq 'Jenny' ){
                                                $answer = "$person lives in: $message->{message}->[0]->{$person}" ;
                                                last;
                                        }
                                }
                                return $answer;
                        }
                },
        );
        $message_instance->add_line({ message =>[{ 
                Frank => 'San Fransisco',
                Donna => 'Carbondale',
                Jenny => 'Portland' }], });
        
        #######################################################################################
        # Synopsis output addition to this point
        # 01: $VAR1 = [
        # 02:           {
        # 03:             'locate_jenny' => 'Jenny lives in: Portland',
        # 04:             'Donna' => 'Carbondale',
        # 05:             'Jenny' => 'Portland',
        # 06:             'Frank' => 'San Fransisco'
        # 07:           }
        # 08:         ];
        #######################################################################################
        
        $message_instance->set_pre_sub(
                sub{
                        my $message = $_[0];
                        my $lookup = {
                                        'San Fransisco' => 'CA',
                                        'Carbondale' => 'IL',
                                        'Portland' => 'OR',
                                };
                        for my $element ( keys %{$message->{message}->[0]} ){
                                $message->{message}->[0]->{$element} .=
                                        ', ' . $lookup->{$message->{message}->[0]->{$element}};
                        }
                } 
        );
        $message_instance->add_line({ message =>[{
                Frank => 'San Fransisco',
                Donna => 'Carbondale',
                Jenny => 'Portland' }], });
        
        #######################################################################################
        # Synopsis output addition to this point
        # 01: $VAR1 = [
        # 02:           {
        # 03:             'locate_jenny' => 'Jenny lives in: Portland, OR',
        # 04:             'Donna' => 'Carbondale, IL',
        # 05:             'Jenny' => 'Portland, OR',
        # 06:             'Frank' => 'San Fransisco, CA'
        # 07:           }
        # 08:         ];
        #######################################################################################
    

DESCRIPTION

This is Moose role that can be used by Log::Shiras::Report to massage the message prior to 'add_line' being implemented in the report. It uses the hook built in the to Report role for the method 'manage_message'.

There are five ways to affect the passed message ref. Each way is set up as an attribute of the class. Details of how each is implemented is explained in the Attributes section.

Warning

'hashpend' and 'prepend' - 'postpend' can conflict since 'hashpend' acts on the first message element as if it were a hashref and the next two act as if the message is a list. A good rule of thumb is to not use both sets together unless you really know what is going on.

Attributes

Data passed to ->new when creating an instance. For modification of these attributes after the instance is created see the attribute methods.

pre_sub

    Definition: This is a place to store a perl closure that will be passed the full $message_ref including meta data. The results of the closure are not used so any desired change should be done to the $message_ref itself since it is persistent. The action takes place before all the other attributes are implemented so the changes will NOT be available to process. See the example in the SYNOPSIS.

    Default: None

    Required: No

    Range: it must pass the is_CodeRef test

    attribute methods

      clear_pre_sub

        Description removes the stored attribute value

      has_pre_sub

        Description predicate for the attribute

      get_pre_sub

        Description returns the attribute value

      set_pre_sub( $closure )

        Description sets the attribute value

hashpend

    Definition: This will update the position %{$message_ref->{message}->[0]}. If that position is not a hash ref then. It will kill the process with Carp - confess. After it passes that test it will perform the following assuming the attribute is retrieved as $hashpend_ref and the entire message is passed as $message_ref;

            for my $element ( keys %$hashpend_ref ){
                    $message_ref->{message}->[0]->{$element} =
                            is_CodeRef( $hashpend_ref->{$element} ) ? 
                                    $hashpend_ref->{$element}->( $message_ref ) : 
                            exists $message_ref->{$hashpend_ref->{$element}} ? 
                                    $message_ref->{$hashpend_ref->{$element}} :
                                    $hashpend_ref->{$element} ;
            }
            

    This means that if the value of the $element is a closure then it will use the results of that and add that to the message sub-hashref. Otherwise it will attempt to pull the equivalent key from the $message meta-data and add it to the message sub-hashref or if all else fails just load the key value pair as it stands to the message sub-hashref.

    Default: None

    Required: No

    Range: it must be a hashref

    attribute methods

      clear_hashpend

        Description removes the stored attribute value

      has_hashpend

        Description predicate for the attribute

      get_all_hashpend

        Description returns the attribute value

      add_to_hashpend( $key = $value|$closure )>

        Description this adds to the attribute and can accept more than one $key => $value pair

      remove_from_hashpend( $key )

        Description removes the $key => $value pair associated with the passed $key from the hashpend. This can accept more than one key at a time.

prepend

    Definition: This will push elements to the beginning of the list @{$message_ref->{message}}. The elements are pushed in the reverse order that they are stored in this attribute meaning that they will wind up in the stored order in the message ref. The action assumes that the attribute is retrieved as $prepend_ref and the entire message is passed as $message_ref;

            for my $element ( reverse @$prepend_ref ){
                    unshift @{$message_ref->{message}}, (
                            exists $message_ref->{$element} ? $message_ref->{$element} :
                            $element );
            }
            

    Unlike the hashpend attribute it will not handle CodeRefs.

    Default: None

    Required: No

    Range: it must be an arrayref

    attribute methods

      clear_prepend

        Description removes the stored attribute value

      has_prepend

        Description predicate for the attribute

      get_all_prepend

        Description returns the attribute value

      add_to_prepend( $element )

        Description this adds to the end of the attribute and can accept more than one $element

postpend

    Definition: This will push elements to the end of the list @{$message_ref->{message}}. The elements are pushed in the order that they are stored in this attribute. The action below assumes that the attribute is retrieved as $postpend_ref and the entire message is passed as $message_ref;

            for my $element ( reverse @$postpend_ref ){
                    push @{$message_ref->{message}}, (
                            exists $message_ref->{$element} ? $message_ref->{$element} :
                            $element );
            }
            

    Unlike the hashpend attribute it will not handle CodeRefs.

    Default: None

    Required: No

    Range: it must be an arrayref

    attribute methods

      clear_postpend

        Description removes the stored attribute value

      has_postpend

        Description predicate for the attribute

      get_all_postpend

        Description returns the attribute value

      add_to_postpend( $element )

        Description this adds to the end of the attribute and can accept more than one $element

post_sub

    Definition: This is a place to store a perl closure that will be passed the full $message_ref including meta data. The results of the closure are not used so any desired change should be done to the $message_ref itself since it is persistent. The action takes place after all the other attributes are implemented so the changes will be available to process. See the example in the SYNOPSIS.

    Default: None

    Required: No

    Range: it must pass the is_CodeRef test

    attribute methods

      clear_post_sub

        Description removes the stored attribute value

      has_post_sub

        Description predicate for the attribute

      get_post_sub

        Description returns the attribute value

      set_post_sub( $closure )

        Description sets the attribute value

Methods

manage_message( $message_ref )

    Definition: This is a possible method called by Log::Shiras::Report with the intent of implementing the attributes on each message passed to a "reports" in Log::Shiras::Switchboard. Actions taken on that message vary from attribute to attribute and the specifics are explained in each. The attributes are implemented in this order.

            pre_sub -> hashpend -> prepend -> postpend -> post_sub
            

    Returns: the (updated) $message_ref

GLOBAL VARIABLES

$ENV{hide_warn}

The module will warn when debug lines are 'Unhide'n. In the case where the you don't want these notifications set this environmental variable to true.

SUPPORT

TODO

AUTHOR

Jed Lund
jandrew@cpan.org

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

DEPENDENCIES