NAME

Devel::LineName - give names to source code lines

SYNOPSIS

  my %Line;
  use Devel::LineName linename => \%Line;

  eval {
      die "oops";   use linename 'foo';
  };

  $@ eq "oops at $0 line $Line{foo}.\n" or die "message wrong";

DESCRIPTION

Allows you to give symbolic names to lines in Perl source code.

This is useful mainly for testing things that deal with line numbers. For example, suppose you're testing a function that dies with a stack backtrace, such as "confess" in Carp. You might do something like:

  use Test::More tests => 1;

  eval {
      outer_sub()
  };

  is $@, <<END;
  woo at $0 line 19
      main::inner_sub() called at $0 line 15
      main::outer_sub() called at $0 line 4
      eval {...} called at $0 line 3
  END

  sub outer_sub {
      inner_sub();
  }

  sub inner_sub {
      confess "woo";
  }

This works, but you can't see that the line numbers are correct at a glance, you have to count lines. I prefer to give meaningful names to the lines of interest:

  use Test::More tests => 1;

  my %Line;
  use Devel::LineName linename => \%Line;

  eval {                use linename 'eval';
      outer_sub();      use linename 'outer_call';
  };

  is $@, <<END;
  woo at $0 line $Line{confess}
      main::inner_sub() called at $0 line $Line{inner_call}
      main::outer_sub() called at $0 line $Line{outer_call}
      eval {...} called at $0 line $Line{eval}
  END

  sub outer_sub {
      inner_sub();      use linename 'inner_call';
  }

  sub inner_sub {
      confess "woo";    use linename 'confess';
  }

IMPORTING

When you use() this module, you must pass a pair of arguments to the use() call. The first sets the name of the line naming pragma that will be created, and the second must be a reference to the hash in which line numbers are to be placed.

The line naming pragma must consist of word characters only. Your choice of line naming pragma is a compromise between clarity and brevity. I like to use linename when there's room, but if space is short then line or even just l may be better. Be sure not the use the name of an existing Perl pragma or module.

NAMING LINES

To name a line, you add a call to the line naming pragma to the end of the line. The argument is the name to be given to the line.

You can specify a line offset as a second argument; these three examples are all equivalent:

  # normal use
  foo();  use linename 'foo';

  # name the line below
  use linename 'foo', +1;
  foo();

  # name the line above
  foo();
  use linename 'foo', -1;

AUTHOR

Nick Cleaton, <nick@cleaton.net>

COPYRIGHT AND LICENSE

Copyright (C) 2010-2015 by Nick Cleaton

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.