Steve Purkis > Scalar-Footnote-0.99_02 > Scalar::Footnote::Functions

Download:
Scalar-Footnote-0.99_02.tar.gz

Dependencies

Annotate this POD

Module Version: 0.99_02   Source  

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

syntax highlighting: