NAME

Text::Locus - text file locations

SYNOPSIS

use Text::Locus;

$locus = new Text::Locus;

$locus = new Text::Locus($file, $line);

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

$s = $locus->format;

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

$locus->fixup_lines(%hash);

print "$locus: text\n";

$res = $locus1 + $locus2;

DESCRIPTION

Text::Locus provides a class for representing locations in text files. A simple location consists of file name and line number. e.g. file:10. In its more complex form, the location represents a text fragment spanning several lines, such as file:10-45. Such a fragment need not be contiguous, a valid location can also look like this: file:10-35,40-48. Moreover, it can span multiple files as well: foo:10-35,40-48;bar:15,18.

CONSTRUCTOR

    $locus = new Text::Locus($file, $line, ...);

Creates a new locus object. Arguments are optional. If given, they indicate the source file name and line numbers this locus is to represent.

METHODS

clone

    $locus->clone

Creates a new Text::Locus which is exact copy of $locus.

add

    $locus->add($file, $line, [$line1 ...]);

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

Returns $locus.

union

    $locus->union($locus2);

Converts $locus to a union of $locus and $locus2.

format

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

Returns string representation of the locus. Argument, if supplied, will be prepended 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, format 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 Text::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

OVERLOADED OPERATIONS

When used in a string, the locus object formats itself. E.g. to print a diagnostic message one can write:

    print "$locus: some text\n";

In fact, this method is preferred over calling $locus->format.

Two objects can be added:

    $loc1 + $loc2

This will produce a new Text::Locus containing locations from both $loc1 and $loc2.

Moreover, a term can also be a string in the form file:line:

    $loc + "file:10"

    "file:10" + $loc

FIXUPS

fixup_names

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

Replaces file names in $locus according to the arguments. In the example above, foo becomes bar, and baz becomes quux.

fixup_lines

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

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

     $locus = new Text::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

Given a single argument, the operation affects all locations. E.g., adding the following to the example above:

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