NAME

Apache2::SSI::Notes - Apache2 Server Side Include Notes

SYNOPSIS

    my $notes = Apache2::SSI::Notes->new(
        # 100K
        size => 102400,
        debug => 3,
    ) || die( Apache2::SSI::Notes->error );
    
    $notes->add( key => $val );
    
    $notes->clear;
    
    $notes->do(sub
    {
        # $_[0] = key
        # $_[1] = value
        $_[1] = Encode::decode( 'utf8', $_[1] );
    });
    
    # Or specify the keys to check
    $notes->do(sub
    {
        # $_[0] = key
        # $_[1] = value
        $_[1] = Encode::decode( 'utf8', $_[1] );
    }, qw( first_name last_name location ) );

    my $val = $notes-get( 'name' );

    # Get all as an hash reference
    my $hashref = $notes->get;

    $notes->set( name => 'John Doe' );

    # remove entry. This is different from $notes->set( name => undef() );
    # equivalent to delete( $hash->{name} );
    $notes->unset( 'name' );

VERSION

    v0.1.1

DESCRIPTION

Apache2::SSI::Notes provides a mean to share notes in and out of Apache/mod_perl2 environment.

The interface is loosely mimicking APR::Table on some, but not all, methods.

So you could have in your script, outside of Apache:

    $notes->set( API_ID => 1234567 );

And then, under mod_perl, in your file:

    <!--#if expr="note('API_ID')" -->

Normally, the note function would work only for values set and retrieved inside the Apache/mod_perl2 framework, but with Apache2::SSI::Notes, you can set a note, say, in a command line script and share it with your Server-Side Includes files.

To achieve this sharing of notes, Apache2::SSI::Notes uses shared memory (see perlipc) with Apache2::SSI::SharedMem that does the heavy work.

However, this only works when Apache2::SSI is in charge of parsing SSI files. Apache mod_includes module will not recognise notes stored outside of Apache/mod_perl framework.

METHODS

new

This instantiates a notes object. It takes the following parameters:

debug

A debug value will enable debugging output (equal or above 3 actually)

size

The fixed size of the memory allocation. It defaults to 524,288 bytes which is 512 Kb, which should be ample enough.

An object will be returned if it successfully initiated, or undef() upon error, which can then be retrieved with Apache2::SSI::Notes-error>. You should always check the return value of the methods used here for their definedness.

    my $notes = Apache2::SSI::Notes->new ||
        die( Apache2::SSI::Notes->error );

add

This is an alias for set.

clear

Empty all the notes. Beware that this will empty the notes for all the processes, since the notes are stored in a shared memory.

do

Provided with a callback as a code reference, and optionally an array of keys, and this will loop through all keys or the given keys if any, and call the callback passing it the key and its value.

For example:

    $notes->do(sub
    {
        my( $n, $v ) = @_;
        if( $n =~ /name/ )
        {
            $_[1] = Encode::decode( 'utf8', $_[1] );
        }
    });

get

Provided with a key and this retrieve its corresponding value, whatever that may be.

    my $val = $notes->get( 'name' );

If no key is provided, it returns all the notes as an hash reference.

    my $all = $notes->get;
    print( "API id is $all->{api}\n" );

Or maybe

    print( "API id is ", $notes->get->{api}, "\n" );

read_mem

Access the shared memory and return the hash reference stored.

If an error occurred, undef() is returned and an "error" in Module::Generic is set, which can be retrieved like:

    die( $notes->error );

Be careful however, that "get" may return undef() not because an error would have occurred, but because this is the value you would have previously set.

set

Provided with a key and value pair, and this will set its entry into the notes hash accordingly.

    $notes->set( name => 'John Doe' );

It returns the notes object to enable chaining.

shem

Returns the current value of the Apache2::SSI::SharedMem object.

You can also set an alternative value, but this is not advised unless you know what you are doing.

size

Sets or gets the shared memory block size.

This should really not be changed. If you do want to change it, you first need to remove the shared memory.

    $notes->shem->remove;

And then create a new Apache2::SSI::Notes object with a different size parameter value.

unset

Remove the notes entry for the given key.

    # No more name key:
    $notes->unset( 'name' );

It returns the notes object to enable chaining.

write_mem

Provided with data, and this will write the data to the shared memory.

CAVEAT

Apache2::SSI::Notes do not work under threaded perl

AUTHOR

Jacques Deguest <jack@deguest.jp>

CPAN ID: jdeguest

https://gitlab.com/jackdeguest/Apache2-SSI

SEE ALSO

mod_include, mod_perl(3), APR::Finfo, "stat" in perlfunc https://httpd.apache.org/docs/current/en/mod/mod_include.html, https://httpd.apache.org/docs/current/en/howto/ssi.html, https://httpd.apache.org/docs/current/en/expr.html https://perl.apache.org/docs/2.0/user/handlers/filters.html#C_PerlOutputFilterHandler_

COPYRIGHT & LICENSE

Copyright (c) 2020-2021 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.

cpanm Apache2::SSI

perl -MCPAN -e shell
install Apache2::SSI