Scalar::Footnote - Attach hidden scalars to references
use Data::Dumper; use Scalar::Footnote; my $obj = Foo->new; # attach invisible footnote to $obj: $obj->Scalar::Footnote::set( my_key => 'my footnote' ); print Dumper( $obj ); # get it back: my $note = $obj->Scalar::Footnote::get( 'my_key' ); print "footnote: $note\n"; # remove it: my $note = $obj->Scalar::Footnote::remove( 'my_key' );
Scalar::Footnote lets you attach scalar footnotes to an object (or any kind of reference, really) that are essentially invisible from Perl. For example, if you try dumping an object that has a footnote attached to it, you won't actually see the footnote:
Scalar::Footnote
my $obj = bless [qw( foo bar )], 'Foo'; $obj->Scalar::Footnote::set( 'Foo' => 'foo note' ); print Dumper( $obj );
prints:
$VAR1 = bless [ 'foo', 'bar' ], 'Foo';
You can of course still access the footnote with Scalar::Footnote::get.
To avoid overwriting footnotes other people have created, you have to specify a key to store your footnote under. You should pick something fairly unique, such as a namespace you're using:
$obj->Scalar::Footnote::set( 'My::Project' => 'foo note' );
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.
Footnotes go away when the reference they're attached to goes away, unless you hold a copy of the footnote elsewhere:
my $ref = {}; my $note = bless [qw( bar note )], 'Bar'; Scalar::Footnote::set( $ref, 'my footnote key' => $note ); $note = undef; # $note is still accessible via Scalar::Footnote::get $ref = undef; # $note is now destroyed
These are not quite class methods, but were intended to be used in an OO style.
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.
Removes all footnotes attached to $ref (which must be a reference). Dies if $ref is not a reference, or if there was an error. Returns the removed Scalar::Footnote object, or undef if no footnote was attached.
Returns the Scalar::Footnote object attached to $ref (which must be a reference) or undef if no footnote was attached. Dies if $ref is not a reference, or if there was an error.
Creates a new Scalar::Footnote object and attaches it to $ref (which must be a reference), overwriting any previous footnotes attached. Dies if $ref is not a reference, or if there was an error. Returns the new footnote object.
These can be used on Scalar::Footnote objects returned by any of the class methods above. They return the footnote object unless otherwise specified.
As in $footnotes{$key} = $val .
$footnotes{$key} = $val
As in $footnotes{$key} .
$footnotes{$key}
As in delete $footnotes{$key} .
delete $footnotes{$key}
Watch out for circular references - Scalar::Util's weaken() is your friend, as is Data::Structure::Util's has_circular_ref() and curcular_off().
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>, OO interface added, updated XS 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.