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