NAME
    Data::Handle - A Very simple interface to the __DATA__ file handle.

VERSION
    version 0.01011703

SYNOPSIS
        package Foo;

        sub bar {
            my $handle = Data::Handle->new( __PACKAGE__ );
            while (<$handle>) {
                print $_;
            }
        }

        __DATA__
        Foo

DESCRIPTION
    This Package serves as a very *very* simple interface to a packages
    __DATA__ section.

    Its primary purposes is to make successive accesses viable without
    needing to scan the file manually for the __DATA__ marker.

    It does this mostly by recording the current position of the file handle
    on the first call to "->new", and then re-using that position on every
    successive "->new" call, which eliminates a bit of the logic for you.

    At present, it only does a simple heuristic ( backtracking ) to verify
    the current position is immediately at the start of a __DATA__ section,
    but we may improve on this one day.

METHODS
  new
        my $fh = Data::Handle->new( $targetpackage )

    Where $targetpackage is the package you want the __DATA__ section from.

WARNING
    At present, this module does you no favours if something else earlier
    has moved the file handle position past the __DATA__ section, or rewound
    it to the start of the file. This is an understood caveat, but nothing
    else seems to have a good way around this either. ( You can always
    rewind to the start of the file and use heuristics, but that is rather
    pesky ).

    Hopefully, if other people do decide to go moving your file pointer,
    they'll use this module to do it so you your code doesn't break.

USAGE
    "Data::Handle-"new()> returns a tied file-handle, and for all intents
    and purposes, it should behave as if somebody had copied __DATA__ to its
    own file, and then done "open $fh, '<' , $file" on it, for every
    instance of the Data::Handle.

    It also inherits from IO::File, so all the methods it has that make
    sense to use should probably work on this too, i.e.:

        my $handle = Data::Handle->new( __PACKAGE__ );
        my @lines = $handle->getlines();

    Also, all offsets are proxied in transit, so you can treat the
    file-handle as if byte 0 is the first byte of the data section.

        my $handle = Data::Handle->new( __PACKAGE__ );
        my @lines = $handle->getlines();
        seek $handle, 0, 0;
        local $/ = undef;
        my $line = scalar <$handle>; # SLURPED!

    Also, the current position of each handle instance is internally
    tracked, so you can have as many objects pointing to the same __DATA__
    section but have their read mechanism uninterrupted by any others.

        my $handlea  = Data::Handle->new( __PACKAGE__ );
        my $handleb  = Data::Handle->new( __PACKAGE__ );

        seek $handlea, 10, 0;
        seek $handleb, 15, 0;

        read $handlea, my $buf, 5;

        read $handleb, my $bufa, 1;
        read $handleb, my $bufb, 1;

         $bufa eq $bufb;

    Don't be fooled, it does this under the covers by a lot of "seek"/"tell"
    magic, but they shouldn't be a problem unless you are truly anal over
    speed.

CREDITS
    Thanks to LeoNerd and anno, from #perl on irc.freenode.org, they were
    most helpful in helping me grok the magic of "tie" that makes the
    simplicity of the interface possible.

    Thanks to Chas Owens and James Wright for their efforts with trying to
    get something simpler with fdup()ing the descriptor ( Sadly not working
    yet ).

AUTHOR
    Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Kent Fredric <kentnl@cpan.org>.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.