view release on metacpan or  search on metacpan

lib/Apache2/SSI/Notes.pm  view on Meta::CPAN

=head1 NAME

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

=head1 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' );

=head1 VERSION

    v0.1.3

=head1 DESCRIPTION

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

The interface is loosely mimicking L<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 C<note> function would work only for values set and retrieved inside the Apache/mod_perl2 framework, but with L<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, L<Apache2::SSI::Notes> uses shared memory (see L<perlipc>) with L<Apache2::SSI::SharedMem> that does the heavy work.

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

=head1 METHODS

=head2 new

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

=over 4

=item C<debug>

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

=item C<size>

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

=back

An object will be returned if it successfully initiated, or undef() upon error, which can then be retrieved with C<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 );

=head2 add

This is an alias for set.

=head2 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.

=head2 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] );
        }
    });

=head2 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