/ 
File-Navigate-1.0
River stage zero No dependents
/ File::Navigate

NAME

File::Navigate - Navigate freely inside a text file

DESCRIPTION

The module is a glorified wrapper for tell() and seek().

It aims to simplify the creation of logfile analysis tools by providing a facility to jump around freely inside the contents of large files without creating the need to slurp excessive amounts of data.

SYNOPSIS

use File::Navigate;
my $nav = File::Navigate->new('/var/log/messages');

# Read what's below the "cursor":
my $first = $nav->get;

# Advance the cursor before reading:
my $second = $nav->getnext;
my $third  = $nav->getnext;

# Advance the cursor by hand:
$nav->next;
my $fourth = $nav->get;

# Position the cursor onto an arbitrary line:
$nav->cursor(10);
my $tenth  = $nav->get;

# Reverse the cursor one line backward:
$nav->prev;
my $ninth  = $nav->get;

# Reverse the cursor before reading:
my $eigth  = $nav->getprev;

# Read an arbitrary line:
my $sixth  = $nav->get(6);

CLASS METHODS

new()

Open the file and create an index of the lines inside of it.

my $mapper = File::Navigate->new($filename);

OBJECT METHODS

count()

Returns the number of lines in the file ("wc -l")

my $lines = $nav->count;

cursor()

Returns the current cursor position and/or sets the cursor.

my $cursor = $nav->cursor();   # Query cursor position.
my $cursor = $nav->cursor(10); # Set cursor to line 10

get()

Gets the line at the cursor position or at the given position.

my $line = $nav->get();   # Get line at cursor
my $line = $nav->get(10); # Get line 10

next()

Advance the cursor position by one line. Returns the new cursor position. Returns undef if the cursor is already on the last line.

my $newcursor = $nav->next();

prev()

Reverse the cursor position by one line. Returns the new cursor position. Returns undef if the cursor is already on line 1.

my $newcursor = $nav->prev();

getnext()

Advance to the next line and return it. Returns undef if the cursor is already on the last line.

my $newcursor = $nav->getnext();

getprev()

Reverse to the previous line and return it: Returns undef if the cursor is already on line 1.

my $newcursor = $nav->getprev();

find()

Find lines containing given regex. Returns array with line numbers.

my @lines = @{$nav->find(qr/foo/)};

EXAMPLE

tac, the opposite of cat, in Perl using File::Navigate:

#!/usr/bin/perl -w
use strict;
use File::Navigate;

foreach my $file (reverse(@ARGV)){
        my $nav = File::Navigate->new($file);
        # Force cursor beyond last line
        $nav->cursor($nav->length()+1);
        print $nav->get()."\n" while $nav->prev();
}

BUGS

Seems to lack proper error handling.

LIMITATIONS

Works only on plain text files. Sockets, STDIO etc. are not supported.

PREREQUISITES

Tested on Perl 5.6.1.

STATUS

Mostly harmless.

AUTHOR

Martin Schmitt <mas at scsy dot de>