Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kentnl/data-handle

A Very simple interface to the __DATA__ file handle.
https://github.com/kentnl/data-handle

Last synced: 4 days ago
JSON representation

A Very simple interface to the __DATA__ file handle.

Awesome Lists containing this project

README 

        
# NAME



Data::Handle - A Very simple interface to the \_\_DATA\_\_  file handle.



# VERSION



version 1.000002



# 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](https://metacpan.org/pod/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 



# COPYRIGHT AND LICENSE



This software is copyright (c) 2017 by Kent Fredric .



This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.