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.

has_file

    if ($locus->has_file($file)) ...

Returns true if the filename $file is present in the locus.

filenames

    @list = $locus->filenames

Returns a list of file names from the locus. The list preserves the order in which filenames were added to the locus.

filelines

    @list = $locus->filelines($file)

Returns the list of lines in <$file> which are part of this 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

equals

    $bool = $locus->equals($other);

Returns true if $locus and $other are equal (i.e. refer to the same source file location).

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"

or

    "file:10" + $loc    

Two locus objects can be compared for equality using == or eq operators.

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;

will produce

     foo:22-24;bar:22
    

AUTHOR

Sergey Poznyakoff, <gray@gnu.org>

COPYRIGHT AND LICENSE

Copyright (C) 2018 by Sergey Poznyakoff

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see <http://www.gnu.org/licenses/>.

cpanm Text::Locus

perl -MCPAN -e shell
install Text::Locus