GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Text::Locus(3) User Contributed Perl Documentation Text::Locus(3)

Text::Locus - text file locations

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;

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".

    $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.

    $locus->clone

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.

Returns $locus.

    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.

    $locus->union($locus2);

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 "file:line":

    $loc + "file:10"

or

    "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, "foo" becomes "bar", and "baz" becomes "quux".

    $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

Sergey Poznyakoff, <gray@gnu.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/>.

2021-02-13 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.