oracular (3) File::LoadLines.3pm.gz

NAME

       File::LoadLines - Load lines from files and network

SYNOPSIS

           use File::LoadLines;
           my @lines = loadlines("mydata.txt");

           use File::LoadLines qw(loadblob);
           my $img = loadblob("https://img.shields.io/badge/Language-Perl-blue");

DESCRIPTION

       File::LoadLines provides an easy way to load the contents of a text file into an array of lines. It is
       intended for small to moderate size files like config files that are often produced by weird tools (and
       users).

       It will transparently fetch data from the network if the provided file name is a URL.

       File::LoadLines automatically handles ASCII, Latin-1 and UTF-8 text.  When the file has a BOM, it handles
       UTF-8, UTF-16 LE and BE, and UTF-32 LE and BE.

       Recognized line terminators are NL (Unix, Linux), CRLF (DOS, Windows) and CR (Mac)

       Function loadblob(), exported on depand, fetches the content and returns it without processing,
       equivalent to File::Slurp and ilk.

EXPORT

       By default the function loadlines() is exported.

FUNCTIONS

   loadlines
           @lines = loadlines("mydata.txt");
           @lines = loadlines("mydata.txt", $options);

       The file is opened, read, decoded and split into lines that are returned in the result array. Line
       terminators are removed.

       In scalar context, returns an array reference.

       The first argument may be the name of a file, an opened file handle, or a reference to a string that
       contains the data.  The name of a file on disk may start with "file://", this is ignored.  If the name
       starts with "http:" or "https:" the data will be retrieved using LWP.  Data URLs
       <https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs> like
       "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==" are also supported.

       The second argument can be used to influence the behaviour.  It is a hash reference of option settings.

       Note that loadlines() is a slurper, it reads the whole file into memory and, for splitting, requires
       temporarily memory for twice the size of the file.

       split
           Enabled by default.

           The data is split into lines and returned as an array (in list context) or as an array reference (in
           scalar context).

           If set to zero, the data is not split into lines but returned as a single string.

       chomp
           Enabled by default.

           Line terminators are removed from the resultant lines.

           If set to zero, the line terminators are not removed.

       encoding
           If specified, loadlines() will use this encoding to decode the file data if it cannot automatically
           detect the encoding.

           If you pass an options hash, File::LoadLines will set "encoding" to the encoding it detected and used
           for this file data.

       blob
           If specified, the data read is not touched but returned exactly as read.

           "blob" overrules "split" and "chomp".

       fail
           If specified, it should be either "hard" or "soft".

           If "hard", read errors are signalled using croak exceptions.  This is the default.

           If set to "soft", loadlines() will return an empty result and set the error message in the options
           hash with key "error".

   loadblob
           use File::LoadLines qw(loadblob);
           $rawdata = loadblob("raw.dat");
           $rawdata = loadblob("raw.dat", $options);

       This is equivalent to calling loadlines() with "blob=>1" in the options.

SEE ALSO

       There are currently no other modules that handle BOM detection and line splitting.

       I have a faint hope that future versions of Perl and Raku will deal with this transparently, but I fear
       the worst.

HINTS

       When you have raw file data (e.g. from a zip), you can use loadlines() to decode and unpack:

           open( my $data, '<', \$contents );
           $lines = loadlines( $data, $options );

       There is no hard requirement on LWP. If you want to use transparent fetching of data over the network
       please make sure LWP::UserAgent is available.

AUTHOR

       Johan Vromans, "<JV at cpan.org>"

SUPPORT AND DOCUMENTATION

       Development of this module takes place on GitHub: https://github.com/sciurius/perl-File-LoadLines.

       You can find documentation for this module with the perldoc command.

           perldoc File::LoadLines

       Please report any bugs or feature requests using the issue tracker on GitHub.

COPYRIGHT & LICENSE

       Copyright 2018,2020,2024 Johan Vromans, all rights reserved.

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