1Perl6::Slurp(3)       User Contributed Perl Documentation      Perl6::Slurp(3)
2
3
4

NAME

6       Perl6::Slurp - Implements the Perl 6 'slurp' built-in
7

SYNOPSIS

9           use Perl6::Slurp;
10
11           # Slurp a file by name...
12
13           $file_contents = slurp 'filename';
14           $file_contents = slurp '<filename';
15           $file_contents = slurp '<', 'filename';
16           $file_contents = slurp '+<', 'filename';
17
18
19           # Slurp a file via an (already open!) handle...
20
21           $file_contents = slurp \*STDIN;
22           $file_contents = slurp $filehandle;
23           $file_contents = slurp IO::File->new('filename');
24
25
26           # Slurp a string...
27
28           $str_contents = slurp \$string;
29           $str_contents = slurp '<', \$string;
30
31
32           # Slurp a pipe (not on Windows, alas)...
33
34           $str_contents = slurp 'tail -20 $filename |';
35           $str_contents = slurp '-|', 'tail', -20, $filename;
36
37
38           # Slurp with no source slurps from whatever $_ indicates...
39
40           for (@files) {
41               $contents .= slurp;
42           }
43
44           # ...or from the entire ARGV list, if $_ is undefined...
45
46           $_ = undef;
47           $ARGV_contents = slurp;
48
49
50           # Specify I/O layers as part of mode...
51
52           $file_contents = slurp '<:raw', $file;
53           $file_contents = slurp '<:utf8', $file;
54           $file_contents = slurp '<:raw :utf8', $file;
55
56
57           # Specify I/O layers as separate options...
58
59           $file_contents = slurp $file, {raw=>1};
60           $file_contents = slurp $file, {utf8=>1};
61           $file_contents = slurp $file, {raw=>1}, {utf8=>1};
62           $file_contents = slurp $file, [raw=>1, utf8=>1];
63
64
65           # Specify input record separator...
66
67           $file_contents = slurp $file, {irs=>"\n\n"};
68           $file_contents = slurp '<', $file, {irs=>"\n\n"};
69           $file_contents = slurp {irs=>"\n\n"}, $file;
70
71
72           # Input record separator can be regex...
73
74           $file_contents = slurp $file, {irs=>qr/\n+/};
75           $file_contents = slurp '<', $file, {irs=>qr/\n+|\t{2,}};
76
77
78           # Specify autochomping...
79
80           $file_contents = slurp $file, {chomp=>1};
81           $file_contents = slurp {chomp=>1}, $file;
82           $file_contents = slurp $file, {chomp=>1, irs=>"\n\n"};
83           $file_contents = slurp $file, {chomp=>1, irs=>qr/\n+/};
84
85
86           # Specify autochomping that replaces irs
87           # with another string...
88
89           $file_contents = slurp $file, {irs=>"\n\n", chomp=>"\n"};
90           $file_contents = slurp $file, {chomp=>"\n\n"}, {irs=>qr/\n+/};
91
92
93           # Specify autochomping that replaces
94           # irs with a dynamically computed string...
95
96           my $n = 1;
97           $file_contents = slurp $file, {chomp=>sub{ "\n#line ".$n++."\n"};
98
99
100           # Slurp in a list context...
101
102           @lines = slurp 'filename';
103           @lines = slurp $filehandle;
104           @lines = slurp \$string;
105           @lines = slurp '<:utf8', 'filename', {irs=>"\x{2020}", chomp=>"\n"};
106

DESCRIPTION

108       "slurp" takes:
109
110       ·   a filename,
111
112       ·   a filehandle,
113
114       ·   a typeglob reference,
115
116       ·   an IO::File object, or
117
118       ·   a scalar reference,
119
120       converts it to an input stream (using "open()" if necessary), and reads
121       in the entire stream. If "slurp" fails to set up or read the stream, it
122       throws an exception.
123
124       If no data source is specified "slurp" uses the value of $_ as the
125       source. If $_ is undefined, "slurp" uses the @ARGV list, and magically
126       slurps the contents of all the sources listed in @ARGV.  Note that the
127       same magic is also applied if you explicitly slurp <*ARGV>, so the
128       following three input operations:
129
130           $contents = join "", <ARGV>;
131
132           $contents = slurp \*ARGV;
133
134           $/ = undef;
135           $contents = slurp;
136
137       are identical in effect.
138
139       In a scalar context "slurp" returns the stream contents as a single
140       string.  If the stream is at EOF, it returns an empty string.  In a
141       list context, it splits the contents after the appropriate input record
142       separator and returns the resulting list of strings.
143
144       You can set the input record separator ("{ irs => $your_irs_here}") for
145       the input operation. The separator can be specified as a string or a
146       regex. Note that an explicit input record separator has no input-
147       terminating effect in a scalar context; "slurp" always reads in the
148       entire input stream, whatever the 'irs' value.
149
150       In a list context, changing the separator can change how the input is
151       broken up within the list that is returned.
152
153       If an input record separator is not explicitly specified, "slurp"
154       defaults to "\n" (not to the current value of $/ – since Perl 6 doesn't
155       have a $/);
156
157       You can also tell "slurp" to automagically "chomp" the input as it is
158       read in, by specifying: ("{ chomp => 1 }")
159
160       Better still, you can tell "slurp" to automagically "chomp" the input
161       and replace what it chomps with another string, by specifying:
162       ("{ chomp => "another string" }")
163
164       You can also tell "slurp" to compute the replacement string on-the-fly
165       by specifying a subroutine as the "chomp" value:
166       ("{ chomp => sub{...} }"). This subroutine is passed the string being
167       chomped off, so for example you could squeeze single newlines to a
168       single space and multiple consecutive newlines to a two newlines with:
169
170           sub squeeze {
171               my ($removed) = @_;
172               if ($removed =~ tr/\n/\n/ == 1) { return " " }
173               else                            { return "\n\n"; }
174           }
175
176           print slurp(\*DATA, {irs=>qr/[ \t]*\n+/, chomp=>\&squeeze}), "\n";
177
178       Which would transform:
179
180           This is the
181           first paragraph
182
183
184           This is the
185           second
186           paragraph
187
188           This, the
189           third
190
191
192
193
194           This one is
195           the
196           very
197           last
198
199       to:
200
201           This is the first paragraph
202
203           This is the second paragraph
204
205           This, the third
206
207           This one is the very last
208
209       Autochomping works in both scalar and list contexts. In scalar contexts
210       every instance of the input record separator will be removed (or
211       replaced) within the returned string. In list context, each list item
212       returned with its terminating separator removed (or replaced).
213
214       You can specify I/O layers, either using the Perl 5 notation:
215
216           slurp "<:layer1 :layer2 :etc", $filename;
217
218       or as an array of options:
219
220           slurp $filename, [layer1=>1, layer2=>1, etc=>1];
221           slurp [layer1=>1, layer2=>1, etc=>1], $filename;
222
223       or as individual options (each of which must be in a separate hash):
224
225           slurp $filename, {layer1=>1}, {layer2=>1}, {etc=>1};
226           slurp {layer1=>1}, {layer2=>1}, {etc=>1}, $filename;
227
228       (...which, of course, would look much cooler in Perl 6:
229
230           # Perl 6 only :-(
231
232           slurp $filename, :layer1 :layer2 :etc;
233           slurp :layer1 :layer2 :etc, $filename;
234
235       )
236
237       A common mistake is to put all the options together in one hash:
238
239           slurp $filename, {layer1=>1, layer2=>1, etc=>1};
240
241       This is almost always a disaster, since the order of I/O layers is
242       usually critical, and placing them all in one hash effectively
243       randomizes that order.  Use an array instead:
244
245           slurp $filename, [layer1=>1, layer2=>1, etc=>1];
246

WARNINGS

248       The syntax and semantics of Perl 6 is still being finalized and
249       consequently is at any time subject to change. That means the same
250       caveat applies to this module.
251
252       When called with a filename or piped shell command, "slurp()" uses
253       Perl's built- in "open()" to access the file. This means that it is
254       subject to the same platform-specific limitations as "open()".  For
255       example, slurping from piped shell commands may not work under Windows.
256

DEPENDENCIES

258       Requires: Perl 5.8.0
259

AUTHOR

261       Damian Conway (damian@conway.org)
262

264        Copyright (c) 2003-2012, Damian Conway. All Rights Reserved.
265        This module is free software. It may be used, redistributed
266           and/or modified under the same terms as Perl itself.
267
268
269
270perl v5.28.0                      2014-02-22                   Perl6::Slurp(3)
Impressum