File Coverage

blib/lib/Scalar/Footnote.pm

Criterion	Covered	Total	%
statement	68	68	100.0
branch	11	20	55.0
condition	4	7	57.1
subroutine	17	17	100.0
pod	9	13	69.2
total	109	125	87.2

=head1 NAME

Scalar::Footnote - Attach hidden scalars to references

=head1 SYNOPSIS

  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' );

=cut

package Scalar::Footnote;

use strict;
use warnings;

use Carp qw( carp croak confess );
use Scalar::Footnote::Functions qw( get_footnote set_footnote remove_footnote );

our $VERSION = '0.99_02';

sub new {
    my $class = shift;
    my $self  = bless {}, $class;
    $self->init( @_ );
    return $self;
}

sub init { return $_[0]; }

sub set_value_for {
    my $self = shift;
    my $key  = shift;
    $self->{"$key"} = shift;
    return $self;
}

sub get_value_for {
    my $self = shift;
    my $key  = shift;
    $self->{"$key"};
}

sub remove_value_for {
    my $self = shift;
    my $key  = shift;
    delete $self->{"$key"};
}

sub attach_to {
    my $self = shift;
    my $thing = shift;

    croak( "can't set footnote object: '$thing' is not a ref!" ) unless ref( $thing );

    set_footnote( $thing => $self );

    return $self;
}

#-------------------------------------------------------------------------------
# Class Methods
#-------------------------------------------------------------------------------

sub attach_new_footnote_object_to {
    my $class = shift;
    my $thing = shift;
    return Scalar::Footnote->new->attach_to( $thing );
}

sub get_footnote_object_for {
    my $class = shift;
    my $thing = shift;

    confess( "can't get footnote object: '$thing' is not a ref!" ) unless ref( $thing );

    my $note = get_footnote( $thing );

    return unless defined( $note );

    croak( "footnote object for '$thing' is not a Scalar::Footnote object (it's '$note')" )
      unless UNIVERSAL::isa( $note, 'Scalar::Footnote' );

    return $note;
}

sub get_or_create_footnote_object_for {
    my $class = shift;
    my $thing = shift;
    return $class->get_footnote_object_for( $thing ) ||
           $class->attach_new_footnote_object_to( $thing );
}

#-------------------------------------------------------------------------------
# Pseudo Class Methods
#-------------------------------------------------------------------------------

sub set {
    my $thing = shift;
    my $key   = shift;
    my $value = shift;

    croak( "can't set footnote for '$thing' - it's not a ref!" )
      unless ref( $thing );

    my $note = Scalar::Footnote->get_or_create_footnote_object_for( $thing );

    $note->set_value_for( $key => $value );

    return $thing;
}

sub get {
    my $thing = shift;
    my $key   = shift;

    croak( "can't get footnote for '$thing' - it's not a ref!" )
      unless ref( $thing );

    my $note = Scalar::Footnote->get_footnote_object_for( $thing ) || return;

    return $note->get_value_for( $key );
}

sub remove {
    my $thing = shift;
    my $key   = shift;

    croak( "can't remove footnote for '$thing' - it's not a ref!" )
      unless ref( $thing );

    my $note = Scalar::Footnote->get_footnote_object_for( $thing ) || return;

    return $note->remove_value_for( $key );
}

sub remove_all {
    my $thing = shift;

    croak( "can't remove all footnotes for '$thing' - it's not a ref!" )
      unless ref( $thing );

    my $note = remove_footnote( $thing );

    return unless defined( $note );

    carp( "footnote for '$thing' is not a Scalar::Footnote object (it's '$note')" )
      unless UNIVERSAL::isa( $note, 'Scalar::Footnote' );

    return $note;
}

1;

__END__