Scalar::Footnote::Functions - under-the-hood functions for Scalar::Footnote
# 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;
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!
Scalar::Footnote
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).
Footnotes are attached to the referenced value of the $ref you pass in (not the variable $ref itself). So in the following:
$ref
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.
{}
Pretty much any kind of reference -- scalar refs, hash refs, array refs, and code refs have been tested.
Pretty much any kind of scalar. Constants, scalar refs, hash refs, array refs, and code refs have been tested.
Watch out for circular references - Scalar::Util's weaken() is your friend, as is Data::Structure::Util's has_circular_ref() and curcular_off().
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.
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.
undef
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.
Attempts to clone objects using Clone dies with:
Don't know how to handle magic of type \37777777633 at ...
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.
Scalar::Util, Data::Structure::Util
To install Scalar::Footnote, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Scalar::Footnote
CPAN shell
perl -MCPAN -e shell install Scalar::Footnote
For more information on module installation, please visit the detailed CPAN module installation guide.