- OVERLOADED OPERATIONS
- COPYRIGHT AND LICENSE
Text::Locus - text file locations
$locus = new Text::Locus;
$locus = new Text::Locus($file, $line);
$s = $locus->format;
$locus->fixup_names('old' => 'new');
print "$locus: text\n";
$res = $locus1 + $locus2;
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:
$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.
Creates a new Text::Locus which is exact copy of $locus.
$locus->add($file, $line, [$line1 ...]);
Adds new location to the locus. Use this for statements spanning several lines and/or files.
if ($locus->has_file($file)) ...
Returns true if the filename $file is present in the locus.
@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.
@list = $locus->filelines($file)
Returns the list of lines in <$file> which are part of this locus.
Converts $locus to a union of $locus and $locus2.
$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
$bool = $locus->equals($other);
Returns true if $locus and $other are equal (i.e. refer to the same source file location).
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
$loc + "file:10"
"file:10" + $loc
Two locus objects can be compared for equality using == or eq operators.
$locus->fixup_names('foo' => 'bar', 'baz' => 'quux');
Replaces file names in $locus according to the arguments. In the example above,
$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;
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;
Sergey Poznyakoff, <firstname.lastname@example.org>
Copyright (C) 2018-2021 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/>.