/ 
Scalar-Footnote-0.99_02
River stage zero No dependents
/ Scalar::Footnote::Functions

NAME

Scalar::Footnote::Functions - under-the-hood functions for Scalar::Footnote

SYNOPSIS

# Don't use this module directly!
# You should use the Scalar::Footnote API to access footnotes cleanly.

use Scalar::Footnote::Functions 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

This package contains all the under-the-hood XS code that does all the work for Scalar::Footnote. You should never use it directly -- if you start setting footnotes that aren't Scalar::Footnote objects (or sub-classes) then things might not work as you might expect... you have been warned!

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.

KNOWN BUGS

Attempts to clone objects using Clone dies with:

Don't know how to handle magic of type \37777777633 at ...

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