view release on metacpan or  search on metacpan

lib/Devel/FIXME.pm  view on Meta::CPAN

			%args = ( text => $_[0] );
		}
	} elsif (@_ % 2 == 0){ # if there's an even number of arguments, they are key value pairs
		%args = @_;
	} else { # if the argument list is anything else we complain
		croak "Invalid arguments";
	}
	
	
	my __PACKAGE__ $self = $pkg->fields::new();
	%$self = %args;

	# fill in some defaults
	$self->{package} ||= (caller(1))[0];
	$self->{file} ||= (caller(1))[1];
	$self->{line} ||= (caller(1))[2];

	# these are mainly for rules
	$self->{script} ||= $0;
	$self->{time} ||= localtime;

	$self;
}

sub import { # export \&FIXME to our caller, /and/ generate a message if there is one to generate
	my $pkg = $_[0];
	$pkg->init unless @_ > 1;
	if (@_ == 1 or @_ > 2 or (@_ == 2 and first { $_[1] eq $_ or $_[1] eq "&$_" } @EXPORT_OK, map { ":$_" } keys %EXPORT_TAGS)){
		shift;
		local $Exporter::ExportLevel = $Exporter::ExportLevel + 1;
		$pkg->Exporter::import(@_);
	} else {
		$pkg->init;
		goto \&FIXME;
	}
}

sub FIXME { # generate a method
	my $pkg = __PACKAGE__;
	$pkg = shift if UNIVERSAL::can($_[0],"isa") and $_[0]->isa(__PACKAGE__); # it's a method or function, we don't care
	$pkg->new(@_)->eval;
}
*msg = \&FIXME; # booya.

__PACKAGE__

__END__

=pod

=head1 NAME

Devel::FIXME - Semi intelligent, pending issue reminder system.

=head1 SYNOPSIS

	this($code)->isa("broken"); # FIXME this line has a bug

=head1 DESCRIPTION

Usually we're too busy to fix things like circular refs, edge cases and so
forth when we're spewing code into the editor. This is because concentration is
usually too valuable a resource to throw to waste over minor issues. But that
doesn't mean the issues don't exist. So usually we remind ourselves they do:

	... # FIXME I hope someone finds this comment


and then search through the source tree for occurrances of I<FIXME> every now
and then, say with C<grep -ri fixme src/>.

This pretty much works until your code base grows, and you have too many FIXMEs
to prioritise them, or even visually tell them apart.

This package's purpose is to provide reminders to FIXMEs (without the user
explicitly searching), and also controlling when, or which reminders will be
displayed.

=head1 DECLARATION INTERFACE

There are several ways to get your code fixed in the indeterminate future.

The first is a sort-of source filter like compile time fix, which does not
affect shipped code.

	$code; # FIXME broken

That's it. When L<Devel::FIXME> is loaded, it will emit warnings for such
comments in any file that was already loaded, and subsequently loaded files as
they are required. The most reasonable way to get it to work is to set the
environment variable I<PERL5OPT>, so that it contains C<-MDevel::FIXME>. When
perl is then started without taint mode on, the module will be loaded
automatically.

The regex for finding FIXMEs in a line of source is returned by the C<regex>
class method (thus it is overridable). It's quite crummy, really. It matches an
occurrance of a hash sign (C<#>), followed by optional white space and then
C<FIXME> or C<XXX>. After that any white space is skipped, and whatever comes
next is the fixme message.

Given some subclassing you could whip up a format for FIXME messages with
metadata such as priorities, or whatnot. See the implementation of C<readfile>.

The second interface is a compile time, somewhat more explicit way of emmitting
messages.

	use Devel::FIXME "broken";

This can be repeated for additional messages as needed. This is useful if you
want your FIXMEs to ruin deployment, so you're forced to get rid of them. Make
sure you run your final tests in a perl tree that doesn't have L<Devel::FIXME>
in it.

The third, and probably most problematic is a runtime, explicit way of emmitting
messages:

	use Devel::FIXME qw/FIXME/;
	$code; FIXME("broken");

This relies on FIXME to have been imported into the current namespace, which is
probably not always the case. Provided you know FIXME is loaded I<somewhere> in