1File::LoadLines(3)    User Contributed Perl Documentation   File::LoadLines(3)
2
3
4

NAME

6       File::LoadLines - Load lines from files and network
7

SYNOPSIS

9           use File::LoadLines;
10           my @lines = loadlines("mydata.txt");
11
12           use File::LoadLines qw(loadblob);
13           my $img = loadblob("https://img.shields.io/badge/Language-Perl-blue");
14

DESCRIPTION

16       File::LoadLines provides an easy way to load the contents of a text
17       file into an array of lines. It is intended for small to moderate size
18       files like config files that are often produced by weird tools (and
19       users).
20
21       It will transparantly fetch data from the network if the provided file
22       name is a URL.
23
24       File::LoadLines automatically handles ASCII, Latin-1 and UTF-8 text.
25       When the file has a BOM, it handles UTF-8, UTF-16 LE and BE, and UTF-32
26       LE and BE.
27
28       Recognized line terminators are NL (Unix, Linux), CRLF (DOS, Windows)
29       and CR (Mac)
30
31       Function loadblob(), exported on depand, fetches the content and
32       returns it without processing, equivalent to File::Slurp and ilk.
33

EXPORT

35       By default the function loadlines() is exported.
36

FUNCTIONS

38   loadlines
39           @lines = loadlines("mydata.txt");
40           @lines = loadlines("mydata.txt", $options);
41
42       The file is opened, read, decoded and split into lines that are
43       returned in the result array. Line terminators are removed.
44
45       In scalar context, returns an array reference.
46
47       The first argument may be the name of a file, an opened file handle, or
48       a reference to a string that contains the data. If the file name starts
49       with "http:" or "https:" the data will be retrieved using LWP.
50
51       The second argument can be used to influence the behaviour.  It is a
52       hash reference of option settings.
53
54       Note that loadlines() is a slurper, it reads the whole file into memory
55       and, for splitting, requires temporarily memory for twice the size of
56       the file.
57
58       split
59           Enabled by default.
60
61           The data is split into lines and returned as an array (in list
62           context) or as an array reference (in scalar context).
63
64           If set to zero, the data is not split into lines but returned as a
65           single string.
66
67       chomp
68           Enabled by default.
69
70           Line terminators are removed from the resultant lines.
71
72           If set to zero, the line terminators are not removed.
73
74       encoding
75           If specified, loadlines() will use this encoding to decode the file
76           data if it cannot automatically detect the encoding.
77
78           If you pass an options hash, File::LoadLines will set "encoding" to
79           the encoding it detected and used for this file data.
80
81       blob
82           If specified, the data read is not touched but returned exactly as
83           read.
84
85           "blob" overrules "split" and "chomp".
86
87       fail
88           If specified, it should be either "hard" or "soft".
89
90           If "hard", read errors are signalled using croak exceptions.  This
91           is the default.
92
93           If set to "soft", loadlines() will return an empty result and set
94           the error message in the options hash with key "error".
95
96   loadblob
97           use File::LoadLines qw(loadblob);
98           $rawdata = loadblob("raw.dat");
99           $rawdata = loadblob("raw.dat", $options);
100
101       This is equivalent to calling loadlines() with "blob=>1" in the
102       options.
103

SEE ALSO

105       There are currently no other modules that handle BOM detection and line
106       splitting.
107
108       I have a faint hope that future versions of Perl and Raku will deal
109       with this transparently, but I fear the worst.
110

HINTS

112       When you have raw file data (e.g. from a zip), you can use loadlines()
113       to decode and unpack:
114
115           open( my $data, '<', \$contents );
116           $lines = loadlines( $data, $options );
117
118       There is no hard requirement on LWP. If you want to use transparent
119       fetching of data over the network please make sure LWP::UserAgent is
120       available.
121

AUTHOR

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

SUPPORT AND DOCUMENTATION

126       Development of this module takes place on GitHub:
127       https://github.com/sciurius/perl-File-LoadLines.
128
129       You can find documentation for this module with the perldoc command.
130
131           perldoc File::LoadLines
132
133       Please report any bugs or feature requests using the issue tracker on
134       GitHub.
135

137       Copyright 2018,2020,2023 Johan Vromans, all rights reserved.
138
139       This program is free software; you can redistribute it and/or modify it
140       under the same terms as Perl itself.
141
142
143
144perl v5.38.0                      2023-11-20                File::LoadLines(3)
Impressum