NAME

Scalar::Footnote - Attach hidden scalars to references

SYNOPSIS

use Scalar::Footnote qw( set_footnote get_footnote remove_footnote );

my $ref = [];

# attach invisible footnote to $ref:
set_footnote( $ref, 'footnote' );

# get it back:
$footnote = get_footnote( $ref );

# remove it:
$footnote = remove_footnote( $ref );

# or you can do things OO-stylee:
$obj->Scalar::Footnote::set_footnote( $a_value );
$note = Scalar::Footnote::get_footnote( $obj );
$note = $obj->Scalar::Footnote::get_footnote;
$note = $obj->Scalar::Footnote::remove_footnote;

DESCRIPTION

Scalar::Footnote lets you attach a scalar to an object (or any kind of reference, really). This scalar footnote is invisible from Perl for all intents and purposes, so for example, if you try dumping an object that has a footnote attached then you won't see it:

my $ref = [qw( foo bar )];
set_footnote( $ref, { a => 'footnote' } );
print Dumper( $ref );

prints:

$VAR1 = [
          'foo',
          'bar'
        ];

If you destroy the $ref and you don't hold a copy of the footnote, it also gets destroyed:

my $ref = {};
set_footnote( $ref, MyFootnote->new );
$ref = undef; # footnote gets destroyed

As with most subs in Perl, set_footnote() makes a copy of the footnote scalar you give it (earlier versions didn't).

What Are Footnotes Attached To?

Footnotes are attached to the referenced value of the $ref you pass in (not the variable $ref itself). So in the following:

my $ref1;
{
    my $ref2 = {};
    $ref1    = $ref2;
    set_footnote( $ref2, ['a footnote'] );
}
print get_footnote( $ref1 );

The footnote is attached to the anonymous hashref, {}, not $ref2. That's why you can still access it through $ref1 after $ref2 goes out of scope.

What Can I Attach Footnotes To?

Pretty much any kind of reference -- scalar refs, hash refs, array refs, and code refs have been tested.

What Can I Use As A Footnote?

Pretty much any kind of scalar. Constants, scalar refs, hash refs, array refs, and code refs have been tested.

CAVEATS

Watch out for circular references - Scalar::Util's weaken() is your friend, as is Data::Structure::Util's has_circular_ref() and curcular_off().

FUNCTIONS

$ref = set_footnote( $ref, $footnote )

Attaches $footnote to $ref (which must be a reference), and overwrites any footnotes that were previously attached. Dies if $ref is not a reference, or if there was an error. Returns the $ref on success.

$footnote = get_footnote( $ref )

Gets the footnote attached to $ref (which must be a reference). Dies if $ref is not a reference, or if there was an error. Returns the $footnote, or undef if no footnote was attached.

$footnote = remove_footnote( $ref )

Removes the footnote attached to $ref (which must be a reference). Dies if $ref is not a reference, or if there was an error. Returns the removed $footnote, or undef if no footnote was attached.

AUTHORS

M. Friebe, original concept.

Converted to Pixie by Piers Cawley (changed the magic type, module name, stole the idea).

Converted to Scalar::Footnote by Steve Purkis <spurkis@cpan.org>, updated to store a copy of the footnote.

SEE ALSO

Scalar::Util, Data::Structure::Util