package MagicStatus;
require 5.6.0;
use Tie::Scalar;
our @ISA = qw( Tie::Scalar );
(our $Version) = '$Revision: 1.2 $' =~ /([\d.]+)/;

sub mywarn {warn @_};

sub TIESCALAR 
{
    my $class   = shift;
	my $watch   = $_[0] || undef;
	my $val     = $_[1] || '';
    my $method  = $_[2] || \&mywarn;
    my $message = $_[3] || undef;
    my $self = { 
    	WATCH   => $watch, 
        VAL     => $val, 
        METHOD  => $method, 
        MESSAGE => $message,
    };
    return bless $self, $class;
}

sub FETCH { shift->{VAL} }

sub STORE 
{
    my $self   = shift;
    $self->{VAL} = shift;
	my $value = defined $self->{WATCH} ? $self->{WATCH} : 'undef' ;
	my $message;
    if( defined $self->{MESSAGE} ) 
    { 
    	$message = $self->{MESSAGE} 
    }
    else
    {
		$message = "MagicStatus(" . $value . ") at ". 
			(caller)[1] . ", " . 
			(caller)[0] . ", " . 
			(caller)[2] . "\n";
    }
	defined $self->{WATCH} 
		? $self->{VAL} eq $self->{WATCH} 
        	&& do{ &{ $self->{METHOD} }($message) }
		: defined $self->{VAL} 
        	|| do{ &{ $self->{METHOD} }($message) }
    ;
}

1;
__END__

=head1 NAME

MagicStatus - Scalar variable that B<warn>s on a specified value

=head1 SYNOPSIS

  use MagicStatus;

  my $oops = sub { print "oops!\n"; warn shift };

  tie my $status, 'MagicStatus', undef, 0, $oops, "look what i found!\n";
  # value to watch for is set to undef, 
  # initial value is set to 0, 
  # method is set to $oops
  # message is set to "look what i found!\n"

  $status = 1; 
  # status is now 1

  $status = system($command, @args);
  # status contains the return code from $comand

  $status = undef; 
  # warns with "oops!\nlook what i found!\n"

  $status = 'magic!';
  # status is now 'magic!'

=head1 DESCRIPTION

This module allows you to tie a scalar variable that will B<warn> when it is assigned a value you wish to watch. One use might be to track and debug the return status from a function.

=over 4

=item C<WATCH>

Use the WATCH hash key to specify the value to watch for. If the variable is set to this value, the METHOD coderef is called. If no value is specified for the WATCH key, it defaults to I<undef>.

=item C<VAL>

Use the VAL hash key to specify the initial value for the scalar variable. If no initial value is set, it defaults to I<''>. 

=item C<METHOD>

Use the METHOD hash key to specify a coderef to call if the WATCH value is encountered. If no value for the METHOD key is set, it defaults to B<\&mywarn>, which is a wrapper around B<warn>.

=item C<MESSAGE>

Use the MESSAGE hash key to specify a message to send to the METHOD coderef. If no value is set, it defaults to C<MagicStatus(WATCH) at FILE, FUNCTION, LINE> (where FILE is the filename, FUNCTION is the function name, and LINE is the line number where the WATCH value was set.

=back

=head1 BUGS

None known so far. Please let me know if you find any.

=head1 AUTHOR

particle

=head1 COPYRIGHT

Copyright 2002 particle. All rights reserved.

This library is free software, you may redistribute it and/or modify it under the same terms as Perl itself.

=head1 SEE ALSO 

perl(1), Tie::Scalar(3pm).

=cut