NAME

App::Glacier::Config::Locus - source file location

SYNOPSIS

use App::Glacier::Config::Locus;

$locus = new App::Glacier::Config::Locus;

$locus = new App::Glacier::Config::Locus($file, $line);

$locus->add($file, $line);

$s = $locus->format;

$locus->fixup_names('old' => 'new');

$locus->fixup_lines();

DESCRIPTION

Provides support for manipulating source file locations.

$locus = new App::Glacier::Config::Locus($file, $line);

Creates a new locus object. Arguments are optional: either no arguments should be given, or both of them. If given, they indicate the source file name and line number this locus is to represent.

$locus->add($file, $line);

Adds new location to the locus. Use this for statements spanning several lines and/or files.

$s = $locus->format($msg);

Returns a string representation of the locus. The argument is optional. If given, its string representation will be concatenated to the formatted locus with a ": " in between. If multiple arguments are supplied, their string representations will be concatenated, separated by horizontal space characters. This is useful for formatting error messages.

If the locus contains multiple file locations, the method tries to compact them by representing contiguous line ranges as X-Y and outputting each file name once. Line ranges are separated by commas. File locations are separated by semicolons. E.g.:

    $locus = new App::Glacier::Config::Locus("foo", 1);
    $locus->add("foo", 2);
    $locus->add("foo", 3);
    $locus->add("foo", 5);
    $locus->add("bar", 2);
    $locus->add("bar", 7);
    print $locus->format("here it goes");

will produce the following:

    foo:1-3,5;bar:2,7: here it goes

$locus->fixup_names('foo' => 'bar', 'baz' => 'quux');

Replaces file names in the locations according to the arguments.

$locus->fixup_lines('foo' => 1, 'baz' => -2);

Offsets line numbers for each named file by the given number of lines. E.g.:

     $locus = new App::Glacier::Config::Locus("foo", 1);
     $locus->add("foo", 2);
     $locus->add("foo", 3);
     $locus->add("bar", 3);
     $locus->fixup_lines(foo => 1. bar => -1);
     print $locus->format;

will produce

     foo:2-4,bar:2

If given a single argument, the operation will affect all locations. E.g., adding the following to the example above:

     $locus->fixup_lines(10);
     print $locus->format;

will produce

     foo:22-24;bar:22
    

cpanm App::Glacier

perl -MCPAN -e shell
install App::Glacier