NAME

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

VERSION

version 1.000000

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 favors 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) 2014 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.