Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 470 lines (353 sloc) 17.523 kB
be1862e P6 Synopsis : ws changes - to help BOMers, added leading blank line t…
Darren_Duncan authored
1
0a9cc7d S16, IO.pod, springs forth from the quantum foam.
markstos authored
2 =encoding utf8
3
04840a3 [Spec] treat all authors equally
lwall authored
4 =head1 TITLE
0a9cc7d S16, IO.pod, springs forth from the quantum foam.
markstos authored
5
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
6 Synopsis 16: I/O
0a9cc7d S16, IO.pod, springs forth from the quantum foam.
markstos authored
7
04840a3 [Spec] treat all authors equally
lwall authored
8 =head1 VERSION
9
10 Created: 12 Sep 2006
11
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
12 Last Modified: 5 Nov 2014
13 Version: 28
0a9cc7d S16, IO.pod, springs forth from the quantum foam.
markstos authored
14
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
15 Many of these functions will work as in Perl 5, except we're trying to rationalize everything into roles. For
a74e144 More IO and Functions whackage
lwall authored
16 now you can assume most of the important functions will automatically
17 be in the * namespace. However, with IO operations in particular,
18 many of them are really methods on an IO handle, and if there is a
19 corresponding global function, it's merely an exported version of
20 the method.
0a9cc7d S16, IO.pod, springs forth from the quantum foam.
markstos authored
21
1bfbfe1 Did some work on users and groups
wayland authored
22 =head1 IO
23
24 =head2 Overridable IO handles
62be922 kill DEF* variants
lwall authored
25
26 In Perl 6, there are the I<standard> IO handles, and any number of overriding
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
27 inner filehandles for the same symbol.
62be922 kill DEF* variants
lwall authored
28
29 The I<standard> handles are our old familiar friends (with new names).
30 Standard input changed from STDIN to C<$*IN>, standard output changed
31 from STDOUT to C<$*OUT>, and standard error changed from STDERR to
32 C<$*ERR>. In Perl 6 these symbols represent more of a concept than
33 a given filehandle, since the meaning is contextually determined.
34 The process's version of these handles live in the C<PROCESS::>
35 namespace, which is more global than the per-interpreter C<GLOBAL::>
36 namespace.
37
38 When no explicit filehandle is used, the standard IO operators are
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
39 defined in terms of the dynamic variables. So the C<say> function
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
40 prints to C<$*OUT>, while C<note> prints to C<$*ERR>. The C<lines()>
b40f6ae Kill prefix:<=> very, very dead.
lwall authored
41 term inputs from C<$*ARGFILES> which defaults to C<$*IN> in the absence of any
42 filenames. So any given dynamic scope (interpreter,
62be922 kill DEF* variants
lwall authored
43 thread, function or method call) may redefine the current meaning of
44 any of those filehandles within the dynamic scope of itself and of
45 its called routines.
46
47 So to put it another way, when you write something like
48
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
49 say "Howdy, world!"
62be922 kill DEF* variants
lwall authored
50
51 the C<say> function looks for the current meaning of C<$*OUT>, and
52 takes the closest definition it can find in its callers. If none
53 of the callers have overridden the definition, it looks in the
54 interpreter's C<GLOBAL> namespace. If the interpreter hasn't overridden
55 the meaning, it takes the meaning from C<PROCESS>. In essence, any
56 dynamic scope in Perl 6 is allowed to do IO redirection much like
57 a Unix shell does with its subprocesses, albeit with a different
58 syntax:
59
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
60 {
61 my $*OUT will leave *.close = open $newfile, :w;
62 say "Written to $newfile";
63 }
64 # stdout reverts to outer scope's definition, and closed the file
ee7470e S02: Moved comment about standard file handles to S16.
wayland authored
65
0ba7481 @lizmat Some minor movement, tweaks
lizmat authored
66 In short:
67
68 default handle
69 routine for sub form purpose
70 ======= =========== =======
71 print $*OUT string-based writing
72 say $*OUT string-based writing
73 get $*ARGFILES read a line (Str)
74 lines $*ARGFILES read all lines (Str)
75 words $*ARGFILES read all words (Str)
76 read binary reading (Buf)
77 write binary writing (Buf)
78
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
79 =head2 Path Names and the .IO coercer
e89ba9e S16: Referred to other documents
wayland authored
80
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
81 Path names are just strings (C<Str>). Methods that return path names, will
82 just return strings. As soon as you need to do manipulation on the path name
83 (e.g. to find out its C<basename> or C<extension>), you can create an
84 C<IO::Path> object out of the string by applying the C<.IO> coercer:
e89ba9e S16: Referred to other documents
wayland authored
85
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
86 my $path = $filename.IO;
660fca2 [S02,S16,S32/IO] Added special quoting that creates IO::FSNode objects.
wayland authored
87
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
88 Then you can use any of the C<IO::Path> methods, such as C<open>:
660fca2 [S02,S16,S32/IO] Added special quoting that creates IO::FSNode objects.
wayland authored
89
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
90 my $handle = $newfile.IO.open(:w);
411322d [S02] Changed :io to :p and :path
wayland authored
91
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
92 Note that the C<open()> sub, is just really syntactic sugar for the above:
660fca2 [S02,S16,S32/IO] Added special quoting that creates IO::FSNode objects.
wayland authored
93
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
94 my $handle = open $newfile, :w;
660fca2 [S02,S16,S32/IO] Added special quoting that creates IO::FSNode objects.
wayland authored
95
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
96 =head2 $*SPEC
660fca2 [S02,S16,S32/IO] Added special quoting that creates IO::FSNode objects.
wayland authored
97
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
98 The current system's path semantics are encapsulated in C<$*SPEC> dynamic
e315952 @Util Fix typos.
Util authored
99 variable. It adheres to the C<IO::Spec> interface, and is automatically
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
100 initialized for the current environment. But like any dynamic variable,
101 can be overridden in a scope:
660fca2 [S02,S16,S32/IO] Added special quoting that creates IO::FSNode objects.
wayland authored
102
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
103 { # Win32 path semantics in here
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
104 my $*SPEC = IO::Spec::Win32;
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
105 ... # your code
106 }
107 # original path semantics here again
411322d [S02] Changed :io to :p and :path
wayland authored
108
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
109 Please note that it does B<not> need to be an instantiated object: the standard
110 C<IO::Spec> subclasses only provide class methods, and therefore do not need an
111 instantiated object. But that could be different for a very specific
112 third-party implementation of an C<IO::Spec> class.
113
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
114 =head2 $*CWD and chdir()
411322d [S02] Changed :io to :p and :path
wayland authored
115
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
116 The dynamic variable $*CWD is an C<IO::Dir> object representing the current
117 working directory. It is normally set with the C<chdir()> function, which will
118 check whether the specified path exists as a directory and is accessible
119 (C<-x>).
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
120
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
121 chdir($dir); # sets $*CWD of scope, usually PROCESS::<$CWD>
411322d [S02] Changed :io to :p and :path
wayland authored
122
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
123 The C<chdir()> function returns a C<X::IO::Chdir> Failure if the path does
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
124 not exist, or is not a directory, or is not accessible. Otherwise
125 returns a newly created C<IO::Dir> object (which will be C<True>).
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
126
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
127 Please note that the path in C<$*CWD> does not have any bearing on what the
128 underlying operating system's concept of a "current directory". It is simply
129 the path that will prepended before any implicit or explicit relative paths,
130 and the default path that will be used when executing a sub-process.
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
131
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
132 To be changing C<$*CWD> just for a given scope, you can use C<indir()>:
133
134 indir $dir, {
135 ... your code in $dir ...
136 };
137 ... your code in $*CWD again ...
138
139 or you can use C<chdir()> with a temporary C<$*CWD>:
140
141 {
142 temp $*CWD = chddir($dir);
143 ... your code in $dir ...
144 }
145 ... your code in $*CWD again ...
146
147 =head2 $*TMPDIR and tmpdir()
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
148
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
149 The dynamic variable C<$*TMPDIR> is an C<IO::Dir> object which points to the
150 system's directory for temporary files. It can be set with the C<tmpdir()>
151 function which will check whether the specified path exists as a directory and
152 has complete access (C<+rwx>).
cd1ca78 @lizmat Eradicate chtmpdir/chhomedir in favour of chdir
lizmat authored
153
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
154 tmpdir($dir); # sets $*TMPDIR of scope, usually PROCESS::<$TMPDIR>
155
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
156 To set a locally scoped version of C<$*TMPDIR>, you can use C<tmpdir()> with
157 a temporary C<$*TMPDIR>:
411322d [S02] Changed :io to :p and :path
wayland authored
158
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
159 {
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
160 temp $*TMPDIR = $tmpdir($dir);
161 ... your code with $*TMPDIR being $dir ...
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
162 }
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
163 ... your code in original $*TMPDIR again ...
0227f5c S32/IO: Mention that Path can be used as an array of path elements
wayland authored
164
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
165 It will return a newly created C<IO::Dir> object (which is C<True>) or an
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
166 appropriate C<Failure>.
0227f5c S32/IO: Mention that Path can be used as an array of path elements
wayland authored
167
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
168 The initialization of C<$*TMPDIR> at startup is set depending on the OS you're
169 on.
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
170
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
171 =head2 $*HOME and homedir()
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
172
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
173 The dynamic variable C<$*HOME> is an C<IO::Dir> object which points to the
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
174 user's home directory. It can be set with the C<homedir()> function
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
175 which will check whether the specified path exists as a directory and is
176 completely accessible (C<+rwx>).
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
177
178 homedir($dir); # sets $*HOME of scope, usually PROCESS::<$HOME>
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
179
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
180 To set a locally scoped version of C<$*HOME>, you can use C<homedir()> with a
181 temporary C<$*HOME>:
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
182
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
183 {
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
184 temp $*HOME = homedir($dir);
185 ... your code with $*HOME being $dir ...
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
186 }
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
187 ... your code in original $*HOME again ...
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
188
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
189 It will return a newly created C<IO::Dir> object (which is C<True>) or an
37874f2 @lizmat Re-introduce tmpdir() and homedir(), update chdir()
lizmat authored
190 appropriate C<Failure>.
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
191
1d0834c @lizmat Remove :test parameter from chdir/tmpdir/homedir
lizmat authored
192 The initialization of C<$*HOME> at startup is set depending on the OS you're on.
411322d [S02] Changed :io to :p and :path
wayland authored
193
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
194 =head2 System dependent path semantics and IO::Spec
411322d [S02] Changed :io to :p and :path
wayland authored
195
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
196 Each time an C<IO::Path> object is created, the current C<$*SPEC> will be
197 encapsulated in the object, to be used for all path related operations.
411322d [S02] Changed :io to :p and :path
wayland authored
198
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
199 Of course, it is also possible to specify a specify a specific system's
200 path semantics module when creating an C<IO::Path> object with the C<:SPEC>
201 named parameter:
411322d [S02] Changed :io to :p and :path
wayland authored
202
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
203 my $SPEC = IO::Spec::Win32;
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
204 my $path = $fileonNTFS.IO(:$SPEC);
411322d [S02] Changed :io to :p and :path
wayland authored
205
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
206 or:
411322d [S02] Changed :io to :p and :path
wayland authored
207
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
208 my $path = $fileonNTFS.IO(:SPEC<Win32>); # auto-expand to IO::Spec::Win32
411322d [S02] Changed :io to :p and :path
wayland authored
209
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
210 =head2 Functions and Classes
a3a09fa [S32/IO] put in canonpath and realpath, as promised
wayland authored
211
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
212 The functions and classes that define most of the functionality for IO are
213 more thoroughly defined in S32-setting-library/IO.pod. The main functions
214 used are listed in S29 with references to S32-setting-library/IO.pod.
215 An overview:
660fca2 [S02,S16,S32/IO] Added special quoting that creates IO::FSNode objects.
wayland authored
216
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
217 =head3 Functions
0227f5c S32/IO: Mention that Path can be used as an array of path elements
wayland authored
218
0c34759 @lizmat Forget chmod() + some cosmetics
lizmat authored
219 print(@text) # print text on $*OUT
220 say(@text) # print text + newline on $*OUT
221 note(@text) # print text + newline on $*ERR
222 dd($a,$b,$c) # tiny data dumper on $*ERR
223 $line = prompt($message) # print message on $*OUT, obtain next line
1de2507 [Spec/S16-io] Tidied up some formatting and escaped the brackets in %…
carlin authored
224
0c34759 @lizmat Forget chmod() + some cosmetics
lizmat authored
225 $handle = open($path) # open a file, return IO::Handle
1284b5c [S16] Documented $*CWD which was mentioned once in S28
wayland authored
226
9b61e9b @lizmat s/Str/IO::Path/ as spotted by pmichaud++
lizmat authored
227 @paths = dir # paths (as IO::Path) in $*CWD
228 @paths = dir($dir) # paths (as IO::Path) in $dir
1de2507 [Spec/S16-io] Tidied up some formatting and escaped the brackets in %…
carlin authored
229
0c34759 @lizmat Forget chmod() + some cosmetics
lizmat authored
230 $contents = slurp($handle) # read all that's left of an opened filehandle
231 $contents = slurp($filename) # read all from given filename
1284b5c [S16] Documented $*CWD which was mentioned once in S28
wayland authored
232
0c34759 @lizmat Forget chmod() + some cosmetics
lizmat authored
233 spurt($handle,$contents) # write $contents to $handle
234 spurt($filename,$contents) # write $contents to $filename
ced138f @labster add $*TMPDIR to S16; update S28 to distinguish IO::Handle/IO::Path
labster authored
235
0c34759 @lizmat Forget chmod() + some cosmetics
lizmat authored
236 mkdir($dir) # create a directory
237 rmdir($dir) # remove a directory
a6c0bb7 @lizmat Add mkpath()
lizmat authored
238 mkpath($path) # create directory and parents as appropriate
ced138f @labster add $*TMPDIR to S16; update S28 to distinguish IO::Handle/IO::Path
labster authored
239
0c34759 @lizmat Forget chmod() + some cosmetics
lizmat authored
240 chdir($dir) # set $*CWD
a5df488 @lizmat Add indir/tmpdir/homedir to overview
lizmat authored
241 temp $*CWD = chdir($dir) # set $*CWD for the current scope
242
243 indir($dir, { ... }) # execute code with temporary $*CWD
244 ...
245 };
246
247 tmpdir($dir) # set $*TMPDIR
248 temp $*TMPDIR = tmpdir($dir) # set $*TMPDIR for the current scope
249
250 homedir($dir) # set $*HOME
251 temp $*HOME = homedir($dir) # set $*HOME for the current scope
0ba7481 @lizmat Some minor movement, tweaks
lizmat authored
252
812d1ac @lizmat Add IO::Path.slurp + some cosmetics
lizmat authored
253 copy($from,$to) # copy a file
0c34759 @lizmat Forget chmod() + some cosmetics
lizmat authored
254 rename($from,$to) # rename (move) a file on same physical storage
255 move($from,$to) # move (rename) a file to other storage
812d1ac @lizmat Add IO::Path.slurp + some cosmetics
lizmat authored
256 unlink(*@files) # remove one or more files
257 chmod($permission,*@files) # change permissions of one or more files
affd391 Replaced iterators with NameServices role, based on an idea of ruoso+…
wayland authored
258
0c34759 @lizmat Forget chmod() + some cosmetics
lizmat authored
259 link($target,$source) # create a hard-link to a file
260 symlink($target,$source) # create a symbolic link to a file
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
261
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
262 =head3 IO::Spec Class
1bfbfe1 Did some work on users and groups
wayland authored
263
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
264 The C<IO::Spec> itself only has one method: C<select>. It takes an OS
265 descriptive name (usually something like what C<$*DISTRO.name> gives) and
266 returns the type object of the appropriate C<IO::Spec> subclass.
267
268 my $*SPEC = IO::Spec.select("MSWin32"); # gives IO::Spec::Win32
269
270 Such a subclass should provide at least the following methods (in alphabetical
271 order):
272
273 abs2rel convert an absolute path into a relative one
274 canonpath return a canonical version of the given path
275 catdir concatenate directories
276 catpath create a path from volume/directories/filename
277 curdir the path to the current directory (usually '.')
785ccf7 @lizmat Added curupdir
lizmat authored
278 curupdir test for matching curdir|updir
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
279 devnull the path to the bit bucket (on Unixy systems '/dev/null')
abb19a5 @lizmat Add "extension"
lizmat authored
280 extension the extension of the path
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
281 is-absolute whether the path is absolute
282 join create a path from hash with volume/directories/filename
283 PATH %ENV<PATH> interpreted as paths
284 rel2abs convert a relative path into an absolute one
285 rootdir the path to the root directory (on Unixy systems '/')
7ddb1f4 @lizmat Fix alphabetical ordero
lizmat authored
286 split split a path into volume/directories/filename in hash
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
287 splitdir split directories
288 splitpath split a path into volume/directories/filename as Parcel
289 tmpdir path of the first writeable directory for temporary files
290 updir the path to the path directory (usually '..')
291
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
292 =head3 IO::Path Class
1bfbfe1 Did some work on users and groups
wayland authored
293
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
294 class IO::Path is Cool { }
1bfbfe1 Did some work on users and groups
wayland authored
295
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
296 The official way to create an C<IO::Path> object is with the C<new> method.
297 Apart from the C<path> positional, it also takes optional C<:SPEC> and
298 C<CWD> named parameters. The C<.IO> coercer (which takes the same parameters
299 as C<.new>) is the syntactic sugar that will most likely be used most often.
300
148469c @lizmat Elaborate a bit on IO::Path.all
lizmat authored
301 my $io = $filename.IO; # current $*SPEC/$*CWD
302 my $io = $filename.IO(:SPEC(*$SPEC)); # specific IO::SPEC
303 my $io = $filename.IO(:SPEC(*$SPEC), :CWD($*CWD));
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
304
305 which would be the same as:
306
148469c @lizmat Elaborate a bit on IO::Path.all
lizmat authored
307 my $io = IO::Path.new($filename);
308 my $io = IO::Path.new($filename, :SPEC(*$SPEC));
309 my $io = IO::Path.new($filename, :SPEC(*$SPEC), :CWD($*CWD));
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
310
311 If you only have filename components to start with, you can also create an
312 C<IO::Path> object with the C<:volume>, C<:directory> and C<:basename> named
313 parameters:
314
148469c @lizmat Elaborate a bit on IO::Path.all
lizmat authored
315 my $io = IO::Path.new( :$volume, :$directory, :$basename );
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
316
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
317 The following file test methods are provided:
318
319 r is readable by effective uid/gid
320 w is writable by effective uid/gid
321 x is executable by effective uid/gid
322 o is owned by effective uid
323
324 R is readable by real uid/gid
325 W is writable by real uid/gid
326 X is executable by real uid/gid
327 O is owned by real uid
328
329 e exists
330 s Size of the $!path of $io in bytes
331 z has zero size (an empty file)
332
333 f is a plain file
334 d is a directory
335 l is a symbolic link
5741ebe @lizmat Remove islink/readlink, add L (readlink) file test
lizmat authored
336 L path of symbolic link (readlink)
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
337 p is a named pipe (FIFO)
338 S is a socket
339 b is a block special file
340 c is a character special file
341
342 u has setuid bit set
343 g has setgid bit set
344 k has sticky bit set
345
346 To allow for easy chaining of file tests, there is an C<.all> method that can
347 be fed the tests to be tried as a C<Parcel> of strings. The value returned
348 will be the first non-True value, or the final True value.
349
148469c @lizmat Elaborate a bit on IO::Path.all
lizmat authored
350 say "rwx" if $io.all: <r w x>;
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
351
148469c @lizmat Elaborate a bit on IO::Path.all
lizmat authored
352 if $io.all(<f r w x s>) -> $size {
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
353 say "plain file with rwx of $size bytes";
354 }
355
148469c @lizmat Elaborate a bit on IO::Path.all
lizmat authored
356 This is mostly handy when passing file tests as parameters between routines
357 and methods. From a performance point of view, direct use of the methods,
358 like:
359
360 if $io.f && $io.r && $io.w && $io.x && $io.s -> $size {
361 say "plain file with rwx of $size bytes";
362 }
363
364 or the smart match method:
365
366 given $io {
367 when :f :r :w :x {
368 say "plain file with rwx of $_.s() bytes";
369 }
370 }
371
372 is probably faster.
373
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
374 These other methods are also provided (in alphabetical order):
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
375
376 absolute the absolute, canonical path
12f5bf6 @lizmat Small rearranging
lizmat authored
377 accessed last access time (if available)
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
378 basename the basename of the path
12f5bf6 @lizmat Small rearranging
lizmat authored
379 changed last (metadata) changed time
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
380 chdir change $*CWD if directory
381 child append basename to path, return new object for that
382 chmod change attributes of path
383 copy create a copy of file
f75e1a3 @lizmat IO::Path.contents is ambiguous, use .dir instead
lizmat authored
384 dir files in path (if dir)
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
385 directory the directory part of the absolute path
abb19a5 @lizmat Add "extension"
lizmat authored
386 extension the extension of the file
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
387 is-absolute is the (original) path absolute
388 is-relative is the (original) path relative
389 lines contents of file as lines
390 mkdir create directory
12f5bf6 @lizmat Small rearranging
lizmat authored
391 modified last modified time
626b042 @lizmat Added some stragglers
lizmat authored
392 move move (rename) to other storage
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
393 open attempt to open file, return IO::Handle
394 parent remove last portion of path, return new object for that
8da8c15 @lizmat Introduce pipe() for opening a pipe
lizmat authored
395 pipe attempt to open a pipe, return IO::Pipe
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
396 pred previous logical path, return new object for that
397 relative the relative path against CWD
626b042 @lizmat Added some stragglers
lizmat authored
398 rename rename (move) to other name
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
399 resolve follow symlinks to the real path, return new object for that
400 rmdir remove directory if empty directory
812d1ac @lizmat Add IO::Path.slurp + some cosmetics
lizmat authored
401 slurp obtain the contents of the file
5b8d701 @lizmat Minor tweaks, had forgotten .spurt
lizmat authored
402 SPEC the :SPEC at instantiation time
403 spurt set the contents of the file
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
404 succ next logical path, return new object for that
405 unlink remove file
406 volume the volume of the path (if any)
407 words contents of file as words
408
083a1a2 @lizmat First part of S16 rewrite
lizmat authored
409 =head3 IO::Handle Class
1bfbfe1 Did some work on users and groups
wayland authored
410
5b8d701 @lizmat Minor tweaks, had forgotten .spurt
lizmat authored
411 class IO::Handle does IO { }
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
412
5b8d701 @lizmat Minor tweaks, had forgotten .spurt
lizmat authored
413 The C<IO::Handle> object is usually B<not> directly instantiated, but
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
414 with C<open()> or C<IO::Path.open>. Nonetheless, you B<can> create an
415 C<IO::Handle> object with just a path:
416
417 my $handle = IO::Handle.new($filename);
418 my $handle = IO::Handle.new($filename, :SPEC(*$SPEC));
419 my $handle = IO::Handle.new($filename, :SPEC(*$SPEC), :CWD($*CWD));
420
421 This does not interact with anything at all and will appear as if the file
422 has been C<.close>d. The C<.open> method does interact with the file system:
423
424 $handle.open; # same as $handle = $filename.IO.open
425
426 It either returns True, or a C<Failure> with additional information.
427
428 The other methods of the C<IO::Handle> class are only valid B<after> the
e315952 @Util Fix typos.
Util authored
429 C<.open> has been called successfully:
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
430
431 close close file handle, flush buffers
432 encoding set/return encoding of file handle
433 eof file pointer reached end of file
434 fileno file descriptor (usually a native integer)
435 flush flush buffers
436 get get next line from file
437 getc get next character from file
5b8d701 @lizmat Minor tweaks, had forgotten .spurt
lizmat authored
438 ins number of lines read
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
439 IO return new IO::Path of path of file
440 lines return rest of contents of file as lines
441 opened is the file open?
5b8d701 @lizmat Minor tweaks, had forgotten .spurt
lizmat authored
442 p the handle is a pipe
594cb70 @lizmat Eradicate IO::FileTestable role
lizmat authored
443 path the IO::Path of path of file, handles file tests
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
444 print write characters to file
445 read read bytes from file
446 say write characters + newline to file
447 seek move file pointer to given position
448 slurp return rest of contents of file
5b8d701 @lizmat Minor tweaks, had forgotten .spurt
lizmat authored
449 spurt write / append contents to file
e1d9ceb @lizmat Final part of S16 rewrite
lizmat authored
450 t is the file a TTY (as a person looking?)
451 tell return position of file pointer
452 words return rest of contents of file as words
453 write write bytes to file
454
455 =head3 Interplay between Roles and Classes
456
457 These classes and roles may cache and share pertinent information for better
458 performance.
1bfbfe1 Did some work on users and groups
wayland authored
459
3d64f1a @lucasbuchala Move AUTHORS sections to end of file
lucasbuchala authored
460 =head1 AUTHORS
461
462 Largely, the authors of the related Perl 5 docs.
463 Larry Wall <larry@wall.org>
464 Mark Stosberg <mark@summersault.com>
465 Tim Nelson <wayland@wayland.id.au>
466 Daniel Ruoso <daniel@ruoso.com>
467 Elizabeth Mattijsen <liz@dijkmat.nl>
468
18e0b14 [spec] minor touch-ups to better format the pod for perl5's perldoc t…
s1n authored
469 =for vim:set expandtab sw=4:
Something went wrong with that request. Please try again.