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

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 to the author.

AUTHOR
    David A. Golden (DAGOLDEN)

    dagolden@cpan.org

    http://dagolden.com/

COPYRIGHT
    Copyright (c) 2005 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.

