The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
File-Marker-0.14
River stage zero No dependents
2 ++
/ File::Marker

NAME

File::Marker - Set and jump between named position markers on a filehandle

VERSION

version 0.14

SYNOPSIS

 use File::Marker;

 my $fh = File::Marker->new( 'datafile.txt' );

 my $line1 = <$fh>;           # read a line
 $fh->set_marker( 'line2' );  # mark the current position
 my @rest = <$fh>;            # slurp the remainder
 $fh->goto_marker( 'line2' ); # jump back to the marked position
 my $line2 = <$fh>;           # read another line

DESCRIPTION

File::Marker allows users to set named markers for the current position in a filehandle and then later jump back to a marked position. A File::Marker object is a subclass of IO::File, providing full filehandle object functionality.

File::Marker automatically sets a special, reserved marker, 'LAST', when it jumps to a marker, allowing an easy return to a former position.

This module was written as a demonstration of the inside-out object technique for the NY Perl Seminar group. It is intended for teaching purposes and has not been tested in production code.

USAGE

new

 my $fh = new();
 my $fh = new( @args );

Creates and returns a File::Marker object. If arguments are provided, they are passed to open() before the object is returned. This mimics the behavior of IO::File.

open

 $fh->open( FILENAME [,MODE [,PERMS]] )
 $fh->open( FILENAME, IOLAYERS )

Opens a file for use with the File::Marker object. Arguments are passed directly to IO::File->open(). See IO::File for details. Returns true if successful and dies on failure.

set_marker

 $fh->set_marker( $marker_name );

Creates a named marker corresponding to the current position in the file. Dies if the filehandle is closed, if the position cannot be determined, or if the reserved marker name 'LAST' is used. Using the same name as an existing marker will overwrite the existing marker position.

goto_marker

 $fh->goto_marker( $marker_name );

Seeks to the position in the file corresponding to the given marker name. Dies if the filehandle is closed, if the marker name is unknown, or if the seek fails.

The reserved marker name 'LAST' corresponds to the location in the file prior to the most recent call to goto_marker on the object. For example:

 # starts at location X in the file
 $fh->goto_marker( 'one' );  # seek to location Y marked by 'one'
 $fh->goto_marker( 'LAST' ); # seek back to X
 $fh->goto_marker( 'LAST' ); # seek back to Y

If there have been no prior calls to goto_marker, 'LAST' will seek to the beginning of the file.

markers

 @list = $fh->markers();

Returns a list of markers that have been set on the object, including 'LAST'.

save_markers

 $fh->save_markers( $marker_filename );

Saves the current list of markers (excluding 'LAST') to the given filename.

load_markers

 $fh = File::Marker->new( 'datafile.txt' );
 $fh->load_markers( $marker_filename );

Loads markers from a previously-saved external file. Will overwrite any

LIMITATIONS

As with all inside-out objects, File::Marker is only thread-safe (including Win32 pseudo-forks) for Perl 5.8 or better, which supports the CLONE subroutine.

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/File-Marker/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/dagolden/File-Marker

  git clone https://github.com/dagolden/File-Marker.git

AUTHOR

David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2013 by David Golden.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004