NAME
File::Marker - Set and jump between named position markers on a
filehandle
VERSION
This documentation refers to version 0.13.
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.
BUGS
Please report bugs or feature requests using the CPAN Request Tracker.
Bugs can be sent by email to "bug-File-Marker@rt.cpan.org" or submitted
using the web interface at
<http://rt.cpan.org/Public/Dist/Display.html?Name=File-Marker>
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.
AUTHOR
David A. Golden (DAGOLDEN)
dagolden@cpan.org
http://dagolden.com/
COPYRIGHT AND LICENSE
Copyright (c) 2005, 2006 by David A. Golden
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.