1Path::Tiny(3) User Contributed Perl Documentation Path::Tiny(3)
2
6 Path::Tiny - File path utility
7
9 version 0.144
10
12 use Path::Tiny;
13 # Creating Path::Tiny objects
15 my $dir = path("/tmp");
17 my $foo = path("foo.txt");
18 my $subdir = $dir->child("foo");
20 my $bar = $subdir->child("bar.txt");
21 # Stringifies as cleaned up path
23 my $file = path("./foo.txt");
25 print $file; # "foo.txt"
26 # Reading files
28 my $guts = $file->slurp;
30 $guts = $file->slurp_utf8;
31 my @lines = $file->lines;
33 @lines = $file->lines_utf8;
34 my ($head) = $file->lines( {count => 1} );
36 my ($tail) = $file->lines( {count => -1} );
37 # Writing files
39 $bar->spew( @data );
41 $bar->spew_utf8( @data );
42 # Reading directories
44 for ( $dir->children ) { ... }
46 my $iter = $dir->iterator;
48 while ( my $next = $iter->() ) { ... }
49
51 This module provides a small, fast utility for working with file paths.
52 It is friendlier to use than File::Spec and provides easy access to
53 functions from several other core file handling modules. It aims to be
54 smaller and faster than many alternatives on CPAN, while helping people
55 do many common things in consistent and less error-prone ways.
56 Path::Tiny does not try to work for anything except Unix-like and Win32
58 platforms. Even then, it might break if you try something particularly
59 obscure or tortuous. (Quick! What does this mean:
60 "///../../..//./././a//b/.././c/././"? And how does it differ on
61 Win32?)
62 All paths are forced to have Unix-style forward slashes. Stringifying
64 the object gives you back the path (after some clean up).
65 File input/output methods "flock" handles before reading or writing, as
67 appropriate (if supported by the platform and/or filesystem).
68 The *_utf8 methods ("slurp_utf8", "lines_utf8", etc.) operate in raw
70 mode. On Windows, that means they will not have CRLF translation from
71 the ":crlf" IO layer. Installing Unicode::UTF8 0.58 or later will
72 speed up *_utf8 situations in many cases and is highly recommended.
73 Alternatively, installing PerlIO::utf8_strict 0.003 or later will be
74 used in place of the default :encoding(UTF-8).
75 This module depends heavily on PerlIO layers for correct operation and
77 thus requires Perl 5.008001 or later.
78
80 path
81 $path = path("foo/bar");
82 $path = path("/tmp", "file.txt"); # list
83 $path = path("."); # cwd
84 Constructs a "Path::Tiny" object. It doesn't matter if you give a file
86 or directory path. It's still up to you to call directory-like methods
87 only on directories and file-like methods only on files. This function
88 is exported automatically by default.
89 The first argument must be defined and have non-zero length or an
91 exception will be thrown. This prevents subtle, dangerous errors with
92 code like "path( maybe_undef() )->remove_tree".
93 DEPRECATED: If and only if the first character of the first argument to
95 "path" is a tilde ('~'), then tilde replacement will be applied to the
96 first path segment. A single tilde will be replaced with glob('~') and
97 a tilde followed by a username will be replaced with output of
98 glob('~username'). No other method does tilde expansion on its
99 arguments. See "Tilde expansion (deprecated)" for more.
100 On Windows, if the path consists of a drive identifier without a path
102 component ("C:" or "D:"), it will be expanded to the absolute path of
103 the current directory on that volume using Cwd::getdcwd().
104 If called with a single "Path::Tiny" argument, the original is returned
106 unless the original is holding a temporary file or directory reference
107 in which case a stringified copy is made.
108 $path = path("foo/bar");
110 $temp = Path::Tiny->tempfile;
111 $p2 = path($path); # like $p2 = $path
113 $t2 = path($temp); # like $t2 = path( "$temp" )
114 This optimizes copies without proliferating references unexpectedly if
116 a copy is made by code outside your control.
117 Current API available since 0.017.
119 new
121 $path = Path::Tiny->new("foo/bar");
122 This is just like "path", but with method call overhead. (Why would
124 you do that?)
125 Current API available since 0.001.
127 cwd
129 $path = Path::Tiny->cwd; # path( Cwd::getcwd )
130 $path = cwd; # optional export
131 Gives you the absolute path to the current directory as a "Path::Tiny"
133 object. This is slightly faster than "path(".")->absolute".
134 "cwd" may be exported on request and used as a function instead of as a
136 method.
137 Current API available since 0.018.
139 rootdir
141 $path = Path::Tiny->rootdir; # /
142 $path = rootdir; # optional export
143 Gives you "File::Spec->rootdir" as a "Path::Tiny" object if you're too
145 picky for path("/").
146 "rootdir" may be exported on request and used as a function instead of
148 as a method.
149 Current API available since 0.018.
151 tempfile, tempdir
153 $temp = Path::Tiny->tempfile( @options );
154 $temp = Path::Tiny->tempdir( @options );
155 $temp = $dirpath->tempfile( @options );
156 $temp = $dirpath->tempdir( @options );
157 $temp = tempfile( @options ); # optional export
158 $temp = tempdir( @options ); # optional export
159 "tempfile" passes the options to "File::Temp->new" and returns a
161 "Path::Tiny" object with the file name. The "TMPDIR" option will be
162 enabled by default, but you can override that by passing "TMPDIR => 0"
163 along with the options. (If you use an absolute "TEMPLATE" option, you
164 will want to disable "TMPDIR".)
165 The resulting "File::Temp" object is cached. When the "Path::Tiny"
167 object is destroyed, the "File::Temp" object will be as well.
168 "File::Temp" annoyingly requires you to specify a custom template in
170 slightly different ways depending on which function or method you call,
171 but "Path::Tiny" lets you ignore that and can take either a leading
172 template or a "TEMPLATE" option and does the right thing.
173 $temp = Path::Tiny->tempfile( "customXXXXXXXX" ); # ok
175 $temp = Path::Tiny->tempfile( TEMPLATE => "customXXXXXXXX" ); # ok
176 The tempfile path object will be normalized to have an absolute path,
178 even if created in a relative directory using "DIR". If you want it to
179 have the "realpath" instead, pass a leading options hash like this:
180 $real_temp = tempfile({realpath => 1}, @options);
182 "tempdir" is just like "tempfile", except it calls "File::Temp->newdir"
184 instead.
185 Both "tempfile" and "tempdir" may be exported on request and used as
187 functions instead of as methods.
188 The methods can be called on an instances representing a directory. In
190 this case, the directory is used as the base to create the temporary
191 file/directory, setting the "DIR" option in File::Temp.
192 my $target_dir = path('/to/destination');
194 my $tempfile = $target_dir->tempfile('foobarXXXXXX');
195 $tempfile->spew('A lot of data...'); # not atomic
196 $tempfile->move($target_dir->child('foobar')); # hopefully atomic
197 In this case, any value set for option "DIR" is ignored.
199 Note: for tempfiles, the filehandles from File::Temp are closed and not
201 reused. This is not as secure as using File::Temp handles directly,
202 but is less prone to deadlocks or access problems on some platforms.
203 Think of what "Path::Tiny" gives you to be just a temporary file name
204 that gets cleaned up.
205 Note 2: if you don't want these cleaned up automatically when the
207 object is destroyed, File::Temp requires different options for
208 directories and files. Use "CLEANUP => 0" for directories and "UNLINK
209 => 0" for files.
210 Note 3: Don't lose the temporary object by chaining a method call
212 instead of storing it:
213 my $lost = tempdir()->child("foo"); # tempdir cleaned up right away
215 Note 4: The cached object may be accessed with the "cached_temp"
217 method. Keeping a reference to, or modifying the cached object may
218 break the behavior documented above and is not supported. Use at your
219 own risk.
220 Current API available since 0.119.
222
224 absolute
225 $abs = path("foo/bar")->absolute;
226 $abs = path("foo/bar")->absolute("/tmp");
227 Returns a new "Path::Tiny" object with an absolute path (or itself if
229 already absolute). If no argument is given, the current directory is
230 used as the absolute base path. If an argument is given, it will be
231 converted to an absolute path (if it is not already) and used as the
232 absolute base path.
233 This will not resolve upward directories ("foo/../bar") unless
235 "canonpath" in File::Spec would normally do so on your platform. If
236 you need them resolved, you must call the more expensive "realpath"
237 method instead.
238 On Windows, an absolute path without a volume component will have it
240 added based on the current drive.
241 Current API available since 0.101.
243 append, append_raw, append_utf8
245 path("foo.txt")->append(@data);
246 path("foo.txt")->append(\@data);
247 path("foo.txt")->append({binmode => ":raw"}, @data);
248 path("foo.txt")->append_raw(@data);
249 path("foo.txt")->append_utf8(@data);
250 Appends data to a file. The file is locked with "flock" prior to
252 writing and closed afterwards. An optional hash reference may be used
253 to pass options. Valid options are:
254 • "binmode": passed to binmode() on the handle used for writing.
256 • "truncate": truncates the file after locking and before appending
258 The "truncate" option is a way to replace the contents of a file in
260 place, unlike "spew" which writes to a temporary file and then replaces
261 the original (if it exists).
262 "append_raw" is like "append" with a "binmode" of ":unix" for a fast,
264 unbuffered, raw write.
265 "append_utf8" is like "append" with an unbuffered "binmode"
267 :unix:encoding(UTF-8) (or ":unix:utf8_strict" with
268 PerlIO::utf8_strict). If Unicode::UTF8 0.58+ is installed, an
269 unbuffered, raw append will be done instead on the data encoded with
270 "Unicode::UTF8".
271 Current API available since 0.060.
273 assert
275 $path = path("foo.txt")->assert( sub { $_->exists } );
276 Returns the invocant after asserting that a code reference argument
278 returns true. When the assertion code reference runs, it will have the
279 invocant object in the $_ variable. If it returns false, an exception
280 will be thrown. The assertion code reference may also throw its own
281 exception.
282 If no assertion is provided, the invocant is returned without error.
284 Current API available since 0.062.
286 basename
288 $name = path("foo/bar.txt")->basename; # bar.txt
289 $name = path("foo.txt")->basename('.txt'); # foo
290 $name = path("foo.txt")->basename(qr/.txt/); # foo
291 $name = path("foo.txt")->basename(@suffixes);
292 Returns the file portion or last directory portion of a path.
294 Given a list of suffixes as strings or regular expressions, any that
296 match at the end of the file portion or last directory portion will be
297 removed before the result is returned.
298 Current API available since 0.054.
300 canonpath
302 $canonical = path("foo/bar")->canonpath; # foo\bar on Windows
303 Returns a string with the canonical format of the path name for the
305 platform. In particular, this means directory separators will be "\"
306 on Windows.
307 Current API available since 0.001.
309 cached_temp
311 Returns the cached "File::Temp" or "File::Temp::Dir" object if the
312 "Path::Tiny" object was created with "/tempfile" or "/tempdir". If
313 there is no such object, this method throws.
314 WARNING: Keeping a reference to, or modifying the cached object may
316 break the behavior documented for temporary files and directories
317 created with "Path::Tiny" and is not supported. Use at your own risk.
318 Current API available since 0.101.
320 child
322 $file = path("/tmp")->child("foo.txt"); # "/tmp/foo.txt"
323 $file = path("/tmp")->child(@parts);
324 Returns a new "Path::Tiny" object relative to the original. Works like
326 "catfile" or "catdir" from File::Spec, but without caring about file or
327 directories.
328 WARNING: because the argument could contain ".." or refer to symlinks,
330 there is no guarantee that the new path refers to an actual descendent
331 of the original. If this is important to you, transform parent and
332 child with "realpath" and check them with "subsumes".
333 Current API available since 0.001.
335 children
337 @paths = path("/tmp")->children;
338 @paths = path("/tmp")->children( qr/\.txt\z/ );
339 Returns a list of "Path::Tiny" objects for all files and directories
341 within a directory. Excludes "." and ".." automatically.
342 If an optional "qr//" argument is provided, it only returns objects for
344 child names that match the given regular expression. Only the base
345 name is used for matching:
346 @paths = path("/tmp")->children( qr/^foo/ );
348 # matches children like the glob foo*
349 Current API available since 0.028.
351 chmod
353 path("foo.txt")->chmod(0777);
354 path("foo.txt")->chmod("0755");
355 path("foo.txt")->chmod("go-w");
356 path("foo.txt")->chmod("a=r,u+wx");
357 Sets file or directory permissions. The argument can be a numeric
359 mode, a octal string beginning with a "0" or a limited subset of the
360 symbolic mode use by /bin/chmod.
361 The symbolic mode must be a comma-delimited list of mode clauses.
363 Clauses must match "qr/\A([augo]+)([=+-])([rwx]+)\z/", which defines
364 "who", "op" and "perms" parameters for each clause. Unlike /bin/chmod,
365 all three parameters are required for each clause, multiple ops are not
366 allowed and permissions "stugoX" are not supported. (See File::chmod
367 for more complex needs.)
368 Current API available since 0.053.
370 copy
372 path("/tmp/foo.txt")->copy("/tmp/bar.txt");
373 Copies the current path to the given destination using File::Copy's
375 "copy" function. Upon success, returns the "Path::Tiny" object for the
376 newly copied file.
377 Current API available since 0.070.
379 digest
381 $obj = path("/tmp/foo.txt")->digest; # SHA-256
382 $obj = path("/tmp/foo.txt")->digest("MD5"); # user-selected
383 $obj = path("/tmp/foo.txt")->digest( { chunk_size => 1e6 }, "MD5" );
384 Returns a hexadecimal digest for a file. An optional hash reference of
386 options may be given. The only option is "chunk_size". If
387 "chunk_size" is given, that many bytes will be read at a time. If not
388 provided, the entire file will be slurped into memory to compute the
389 digest.
390 Any subsequent arguments are passed to the constructor for Digest to
392 select an algorithm. If no arguments are given, the default is
393 SHA-256.
394 Current API available since 0.056.
396 dirname (deprecated)
398 $name = path("/tmp/foo.txt")->dirname; # "/tmp/"
399 Returns the directory portion you would get from calling
401 "File::Spec->splitpath( $path->stringify )" or "." for a path without a
402 parent directory portion. Because File::Spec is inconsistent, the
403 result might or might not have a trailing slash. Because of this, this
404 method is deprecated.
405 A better, more consistently approach is likely
407 "$path->parent->stringify", which will not have a trailing slash except
408 for a root directory.
409 Deprecated in 0.056.
411 edit, edit_raw, edit_utf8
413 path("foo.txt")->edit( \&callback, $options );
414 path("foo.txt")->edit_utf8( \&callback );
415 path("foo.txt")->edit_raw( \&callback );
416 These are convenience methods that allow "editing" a file using a
418 single callback argument. They slurp the file using "slurp", place the
419 contents inside a localized $_ variable, call the callback function
420 (without arguments), and then write $_ (presumably mutated) back to the
421 file with "spew".
422 An optional hash reference may be used to pass options. The only
424 option is "binmode", which is passed to "slurp" and "spew".
425 "edit_utf8" and "edit_raw" act like their respective "slurp_*" and
427 "spew_*" methods.
428 Current API available since 0.077.
430 edit_lines, edit_lines_utf8, edit_lines_raw
432 path("foo.txt")->edit_lines( \&callback, $options );
433 path("foo.txt")->edit_lines_utf8( \&callback );
434 path("foo.txt")->edit_lines_raw( \&callback );
435 These are convenience methods that allow "editing" a file's lines using
437 a single callback argument. They iterate over the file: for each line,
438 the line is put into a localized $_ variable, the callback function is
439 executed (without arguments) and then $_ is written to a temporary
440 file. When iteration is finished, the temporary file is atomically
441 renamed over the original.
442 An optional hash reference may be used to pass options. The only
444 option is "binmode", which is passed to the method that open handles
445 for reading and writing.
446 "edit_lines_raw" is like "edit_lines" with a buffered "binmode" of
448 ":raw".
449 "edit_lines_utf8" is like "edit_lines" with a buffered "binmode"
451 :raw:encoding(UTF-8) (or ":raw:utf8_strict" with PerlIO::utf8_strict).
452 Current API available since 0.077.
454 exists, is_file, is_dir
456 if ( path("/tmp")->exists ) { ... } # -e
457 if ( path("/tmp")->is_dir ) { ... } # -d
458 if ( path("/tmp")->is_file ) { ... } # -e && ! -d
459 Implements file test operations, this means the file or directory
461 actually has to exist on the filesystem. Until then, it's just a path.
462 Note: "is_file" is not "-f" because "-f" is not the opposite of "-d".
464 "-f" means "plain file", excluding symlinks, devices, etc. that often
465 can be read just like files.
466 Use "-f" instead if you really mean to check for a plain file.
468 Current API available since 0.053.
470 filehandle
472 $fh = path("/tmp/foo.txt")->filehandle($mode, $binmode);
473 $fh = path("/tmp/foo.txt")->filehandle({ locked => 1 }, $mode, $binmode);
474 $fh = path("/tmp/foo.txt")->filehandle({ exclusive => 1 }, $mode, $binmode);
475 Returns an open file handle. The $mode argument must be a Perl-style
477 read/write mode string ("<" ,">", ">>", etc.). If a $binmode is given,
478 it is set during the "open" call.
479 An optional hash reference may be used to pass options.
481 The "locked" option governs file locking; if true, handles opened for
483 writing, appending or read-write are locked with "LOCK_EX"; otherwise,
484 they are locked with "LOCK_SH". When using "locked", ">" or "+>" modes
485 will delay truncation until after the lock is acquired.
486 The "exclusive" option causes the open() call to fail if the file
488 already exists. This corresponds to the O_EXCL flag to sysopen /
489 open(2). "exclusive" implies "locked" and will set it for you if you
490 forget it.
491 See "openr", "openw", "openrw", and "opena" for sugar.
493 Current API available since 0.066.
495 has_same_bytes
497 if ( path("foo.txt")->has_same_bytes("bar.txt") ) {
498 # ...
499 }
500 This method returns true if both the invocant and the argument can be
502 opened as file handles and the handles contain the same bytes. It
503 returns false if their contents differ. If either can't be opened as a
504 file (e.g. a directory or non-existent file), the method throws an
505 exception. If both can be opened and both have the same "realpath",
506 the method returns true without scanning any data.
507 Current API available since 0.125.
509 is_absolute, is_relative
511 if ( path("/tmp")->is_absolute ) { ... }
512 if ( path("/tmp")->is_relative ) { ... }
513 Booleans for whether the path appears absolute or relative.
515 Current API available since 0.001.
517 is_rootdir
519 while ( ! $path->is_rootdir ) {
520 $path = $path->parent;
521 ...
522 }
523 Boolean for whether the path is the root directory of the volume. I.e.
525 the "dirname" is "q[/]" and the "basename" is "q[]".
526 This works even on "MSWin32" with drives and UNC volumes:
528 path("C:/")->is_rootdir; # true
530 path("//server/share/")->is_rootdir; #true
531 Current API available since 0.038.
533 iterator
535 $iter = path("/tmp")->iterator( \%options );
536 Returns a code reference that walks a directory lazily. Each
538 invocation returns a "Path::Tiny" object or undef when the iterator is
539 exhausted.
540 $iter = path("/tmp")->iterator;
542 while ( $path = $iter->() ) {
543 ...
544 }
545 The current and parent directory entries ("." and "..") will not be
547 included.
548 If the "recurse" option is true, the iterator will walk the directory
550 recursively, breadth-first. If the "follow_symlinks" option is also
551 true, directory links will be followed recursively. There is no
552 protection against loops when following links. If a directory is not
553 readable, it will not be followed.
554 The default is the same as:
556 $iter = path("/tmp")->iterator( {
558 recurse => 0,
559 follow_symlinks => 0,
560 } );
561 For a more powerful, recursive iterator with built-in loop avoidance,
563 see Path::Iterator::Rule.
564 See also "visit".
566 Current API available since 0.016.
568 lines, lines_raw, lines_utf8
570 @contents = path("/tmp/foo.txt")->lines;
571 @contents = path("/tmp/foo.txt")->lines(\%options);
572 @contents = path("/tmp/foo.txt")->lines_raw;
573 @contents = path("/tmp/foo.txt")->lines_utf8;
574 @contents = path("/tmp/foo.txt")->lines( { chomp => 1, count => 4 } );
576 Returns a list of lines from a file. Optionally takes a hash-reference
578 of options. Valid options are "binmode", "count" and "chomp".
579 If "binmode" is provided, it will be set on the handle prior to
581 reading.
582 If a positive "count" is provided, that many lines will be returned
584 from the start of the file. If a negative "count" is provided, the
585 entire file will be read, but only abs(count) will be kept and
586 returned. If abs(count) exceeds the number of lines in the file, all
587 lines will be returned.
588 If "chomp" is set, any end-of-line character sequences ("CR", "CRLF",
590 or "LF") will be removed from the lines returned.
591 Because the return is a list, "lines" in scalar context will return the
593 number of lines (and throw away the data).
594 $number_of_lines = path("/tmp/foo.txt")->lines;
596 "lines_raw" is like "lines" with a "binmode" of ":raw". We use ":raw"
598 instead of ":unix" so PerlIO buffering can manage reading by line.
599 "lines_utf8" is like "lines" with a "binmode" of :raw:encoding(UTF-8)
601 (or ":raw:utf8_strict" with PerlIO::utf8_strict). If Unicode::UTF8
602 0.58+ is installed, a raw, unbuffered UTF-8 slurp will be done and then
603 the lines will be split. This is actually faster than relying on IO
604 layers, though a bit memory intensive. If memory use is a concern,
605 consider "openr_utf8" and iterating directly on the handle.
606 Current API available since 0.065.
608 mkdir
610 path("foo/bar/baz")->mkdir;
611 path("foo/bar/baz")->mkdir( \%options );
612 Like calling "make_path" from File::Path. An optional hash reference
614 is passed through to "make_path". Errors will be trapped and an
615 exception thrown. Returns the the path object to facilitate chaining.
616 NOTE: unlike Perl's builtin "mkdir", this will create intermediate
618 paths similar to the Unix "mkdir -p" command. It will not error if
619 applied to an existing directory.
620 Current API available since 0.125.
622 mkpath (deprecated)
624 Like calling "mkdir", but returns the list of directories created or an
625 empty list if the directories already exist, just like "make_path".
626 Deprecated in 0.125.
628 move
630 path("foo.txt")->move("bar.txt");
631 Moves the current path to the given destination using File::Copy's
633 "move" function. Upon success, returns the "Path::Tiny" object for the
634 newly moved file.
635 If the destination already exists and is a directory, and the source is
637 not a directory, then the source file will be renamed into the
638 directory specified by the destination.
639 If possible, move() will simply rename the file. Otherwise, it copies
641 the file to the new location and deletes the original. If an error
642 occurs during this copy-and-delete process, you may be left with a
643 (possibly partial) copy of the file under the destination name.
644 Current API available since 0.124. Prior versions used Perl's -built-in
646 (and less robust) rename function and did not return an object.
647 openr, openw, openrw, opena
649 $fh = path("foo.txt")->openr($binmode); # read
650 $fh = path("foo.txt")->openr_raw;
651 $fh = path("foo.txt")->openr_utf8;
652 $fh = path("foo.txt")->openw($binmode); # write
654 $fh = path("foo.txt")->openw_raw;
655 $fh = path("foo.txt")->openw_utf8;
656 $fh = path("foo.txt")->opena($binmode); # append
658 $fh = path("foo.txt")->opena_raw;
659 $fh = path("foo.txt")->opena_utf8;
660 $fh = path("foo.txt")->openrw($binmode); # read/write
662 $fh = path("foo.txt")->openrw_raw;
663 $fh = path("foo.txt")->openrw_utf8;
664 Returns a file handle opened in the specified mode. The "openr" style
666 methods take a single "binmode" argument. All of the "open*" methods
667 have "open*_raw" and "open*_utf8" equivalents that use buffered I/O
668 layers ":raw" and :raw:encoding(UTF-8) (or ":raw:utf8_strict" with
669 PerlIO::utf8_strict).
670 An optional hash reference may be used to pass options. The only
672 option is "locked". If true, handles opened for writing, appending or
673 read-write are locked with "LOCK_EX"; otherwise, they are locked for
674 "LOCK_SH".
675 $fh = path("foo.txt")->openrw_utf8( { locked => 1 } );
677 See "filehandle" for more on locking.
679 Current API available since 0.011.
681 parent
683 $parent = path("foo/bar/baz")->parent; # foo/bar
684 $parent = path("foo/wibble.txt")->parent; # foo
685 $parent = path("foo/bar/baz")->parent(2); # foo
687 Returns a "Path::Tiny" object corresponding to the parent directory of
689 the original directory or file. An optional positive integer argument
690 is the number of parent directories upwards to return. "parent" by
691 itself is equivalent to parent(1).
692 Current API available since 0.014.
694 realpath
696 $real = path("/baz/foo/../bar")->realpath;
697 $real = path("foo/../bar")->realpath;
698 Returns a new "Path::Tiny" object with all symbolic links and upward
700 directory parts resolved using Cwd's "realpath". Compared to
701 "absolute", this is more expensive as it must actually consult the
702 filesystem.
703 If the parent path can't be resolved (e.g. if it includes directories
705 that don't exist), an exception will be thrown:
706 $real = path("doesnt_exist/foo")->realpath; # dies
708 However, if the parent path exists and only the last component (e.g.
710 filename) doesn't exist, the realpath will be the realpath of the
711 parent plus the non-existent last component:
712 $real = path("./aasdlfasdlf")->realpath; # works
714 The underlying Cwd module usually worked this way on Unix, but died on
716 Windows (and some Unixes) if the full path didn't exist. As of version
717 0.064, it's safe to use anywhere.
718 Current API available since 0.001.
720 relative
722 $rel = path("/tmp/foo/bar")->relative("/tmp"); # foo/bar
723 Returns a "Path::Tiny" object with a path relative to a new base path
725 given as an argument. If no argument is given, the current directory
726 will be used as the new base path.
727 If either path is already relative, it will be made absolute based on
729 the current directly before determining the new relative path.
730 The algorithm is roughly as follows:
732 • If the original and new base path are on different volumes, an
734 exception will be thrown.
735 • If the original and new base are identical, the relative path is
737 ".".
738 • If the new base subsumes the original, the relative path is the
740 original path with the new base chopped off the front
741 • If the new base does not subsume the original, a common prefix path
743 is determined (possibly the root directory) and the relative path
744 will consist of updirs ("..") to reach the common prefix, followed
745 by the original path less the common prefix.
746 Unlike "File::Spec::abs2rel", in the last case above, the calculation
748 based on a common prefix takes into account symlinks that could affect
749 the updir process. Given an original path "/A/B" and a new base
750 "/A/C", (where "A", "B" and "C" could each have multiple path
751 components):
752 • Symlinks in "A" don't change the result unless the last component
754 of A is a symlink and the first component of "C" is an updir.
755 • Symlinks in "B" don't change the result and will exist in the
757 result as given.
758 • Symlinks and updirs in "C" must be resolved to actual paths, taking
760 into account the possibility that not all path components might
761 exist on the filesystem.
762 Current API available since 0.001. New algorithm (that accounts for
764 symlinks) available since 0.079.
765 remove
767 path("foo.txt")->remove;
768 This is just like "unlink", except for its error handling: if the path
770 does not exist, it returns false; if deleting the file fails, it throws
771 an exception.
772 Current API available since 0.012.
774 remove_tree
776 # directory
777 path("foo/bar/baz")->remove_tree;
778 path("foo/bar/baz")->remove_tree( \%options );
779 path("foo/bar/baz")->remove_tree( { safe => 0 } ); # force remove
780 Like calling "remove_tree" from File::Path, but defaults to "safe"
782 mode. An optional hash reference is passed through to "remove_tree".
783 Errors will be trapped and an exception thrown. Returns the number of
784 directories deleted, just like "remove_tree".
785 If you want to remove a directory only if it is empty, use the built-in
787 "rmdir" function instead.
788 rmdir path("foo/bar/baz/");
790 Current API available since 0.013.
792 sibling
794 $foo = path("/tmp/foo.txt");
795 $sib = $foo->sibling("bar.txt"); # /tmp/bar.txt
796 $sib = $foo->sibling("baz", "bam.txt"); # /tmp/baz/bam.txt
797 Returns a new "Path::Tiny" object relative to the parent of the
799 original. This is slightly more efficient than
800 "$path->parent->child(...)".
801 Current API available since 0.058.
803 size, size_human
805 my $p = path("foo"); # with size 1025 bytes
806 $p->size; # "1025"
808 $p->size_human; # "1.1 K"
809 $p->size_human( {format => "iec"} ); # "1.1 KiB"
810 Returns the size of a file. The "size" method is just a wrapper around
812 "-s".
813 The "size_human" method provides a human-readable string similar to "ls
815 -lh". Like "ls", it rounds upwards and provides one decimal place for
816 single-digit sizes and no decimal places for larger sizes. The only
817 available option is "format", which has three valid values:
818 • 'ls' (the default): base-2 sizes, with "ls" style single-letter
820 suffixes (K, M, etc.)
821 • 'iec': base-2 sizes, with IEC binary suffixes (KiB, MiB, etc.)
823 • 'si': base-10 sizes, with SI decimal suffixes (kB, MB, etc.)
825 If "-s" would return "undef", "size_human" returns the empty string.
827 Current API available since 0.122.
829 slurp, slurp_raw, slurp_utf8
831 $data = path("foo.txt")->slurp;
832 $data = path("foo.txt")->slurp( {binmode => ":raw"} );
833 $data = path("foo.txt")->slurp_raw;
834 $data = path("foo.txt")->slurp_utf8;
835 Reads file contents into a scalar. Takes an optional hash reference
837 which may be used to pass options. The only available option is
838 "binmode", which is passed to binmode() on the handle used for reading.
839 "slurp_raw" is like "slurp" with a "binmode" of ":unix" for a fast,
841 unbuffered, raw read.
842 "slurp_utf8" is like "slurp" with a "binmode" of :unix:encoding(UTF-8)
844 (or ":unix:utf8_strict" with PerlIO::utf8_strict). If Unicode::UTF8
845 0.58+ is installed, a unbuffered, raw slurp will be done instead and
846 the result decoded with "Unicode::UTF8". This is just as strict and is
847 roughly an order of magnitude faster than using :encoding(UTF-8).
848 Note: "slurp" and friends lock the filehandle before slurping. If you
850 plan to slurp from a file created with File::Temp, be sure to close
851 other handles or open without locking to avoid a deadlock:
852 my $tempfile = File::Temp->new(EXLOCK => 0);
854 my $guts = path($tempfile)->slurp;
855 Current API available since 0.004.
857 spew, spew_raw, spew_utf8
859 path("foo.txt")->spew(@data);
860 path("foo.txt")->spew(\@data);
861 path("foo.txt")->spew({binmode => ":raw"}, @data);
862 path("foo.txt")->spew_raw(@data);
863 path("foo.txt")->spew_utf8(@data);
864 Writes data to a file atomically. The file is written to a temporary
866 file in the same directory, then renamed over the original. An
867 optional hash reference may be used to pass options. The only option
868 is "binmode", which is passed to binmode() on the handle used for
869 writing.
870 "spew_raw" is like "spew" with a "binmode" of ":unix" for a fast,
872 unbuffered, raw write.
873 "spew_utf8" is like "spew" with a "binmode" of :unix:encoding(UTF-8)
875 (or ":unix:utf8_strict" with PerlIO::utf8_strict). If Unicode::UTF8
876 0.58+ is installed, a raw, unbuffered spew will be done instead on the
877 data encoded with "Unicode::UTF8".
878 NOTE: because the file is written to a temporary file and then renamed,
880 the new file will wind up with permissions based on your current umask.
881 This is a feature to protect you from a race condition that would
882 otherwise give different permissions than you might expect. If you
883 really want to keep the original mode flags, use "append" with the
884 "truncate" option.
885 Current API available since 0.011.
887 stat, lstat
889 $stat = path("foo.txt")->stat;
890 $stat = path("/some/symlink")->lstat;
891 Like calling "stat" or "lstat" from File::stat.
893 Current API available since 0.001.
895 stringify
897 $path = path("foo.txt");
898 say $path->stringify; # same as "$path"
899 Returns a string representation of the path. Unlike "canonpath", this
901 method returns the path standardized with Unix-style "/" directory
902 separators.
903 Current API available since 0.001.
905 subsumes
907 path("foo/bar")->subsumes("foo/bar/baz"); # true
908 path("/foo/bar")->subsumes("/foo/baz"); # false
909 Returns true if the first path is a prefix of the second path at a
911 directory boundary.
912 This does not resolve parent directory entries ("..") or symlinks:
914 path("foo/bar")->subsumes("foo/bar/../baz"); # true
916 If such things are important to you, ensure that both paths are
918 resolved to the filesystem with "realpath":
919 my $p1 = path("foo/bar")->realpath;
921 my $p2 = path("foo/bar/../baz")->realpath;
922 if ( $p1->subsumes($p2) ) { ... }
923 Current API available since 0.048.
925 touch
927 path("foo.txt")->touch;
928 path("foo.txt")->touch($epoch_secs);
929 Like the Unix "touch" utility. Creates the file if it doesn't exist,
931 or else changes the modification and access times to the current time.
932 If the first argument is the epoch seconds then it will be used.
933 Returns the path object so it can be easily chained with other methods:
935 # won't die if foo.txt doesn't exist
937 $content = path("foo.txt")->touch->slurp;
938 Current API available since 0.015.
940 touchpath
942 path("bar/baz/foo.txt")->touchpath;
943 Combines "mkdir" and "touch". Creates the parent directory if it
945 doesn't exist, before touching the file. Returns the path object like
946 "touch" does.
947 If you need to pass options, use "mkdir" and "touch" separately:
949 path("bar/baz")->mkdir( \%options )->child("foo.txt")->touch($epoch_secs);
951 Current API available since 0.022.
953 visit
955 path("/tmp")->visit( \&callback, \%options );
956 Executes a callback for each child of a directory. It returns a hash
958 reference with any state accumulated during iteration.
959 The options are the same as for "iterator" (which it uses internally):
961 "recurse" and "follow_symlinks". Both default to false.
962 The callback function will receive a "Path::Tiny" object as the first
964 argument and a hash reference to accumulate state as the second
965 argument. For example:
966 # collect files sizes
968 my $sizes = path("/tmp")->visit(
969 sub {
970 my ($path, $state) = @_;
971 return if $path->is_dir;
972 $state->{$path} = -s $path;
973 },
974 { recurse => 1 }
975 );
976 For convenience, the "Path::Tiny" object will also be locally aliased
978 as the $_ global variable:
979 # print paths matching /foo/
981 path("/tmp")->visit( sub { say if /foo/ }, { recurse => 1} );
982 If the callback returns a reference to a false scalar value, iteration
984 will terminate. This is not the same as "pruning" a directory search;
985 this just stops all iteration and returns the state hash reference.
986 # find up to 10 files larger than 100K
988 my $files = path("/tmp")->visit(
989 sub {
990 my ($path, $state) = @_;
991 $state->{$path}++ if -s $path > 102400
992 return \0 if keys %$state == 10;
993 },
994 { recurse => 1 }
995 );
996 If you want more flexible iteration, use a module like
998 Path::Iterator::Rule.
999 Current API available since 0.062.
1001 volume
1003 $vol = path("/tmp/foo.txt")->volume; # ""
1004 $vol = path("C:/tmp/foo.txt")->volume; # "C:"
1005 Returns the volume portion of the path. This is equivalent to what
1007 File::Spec would give from "splitpath" and thus usually is the empty
1008 string on Unix-like operating systems or the drive letter for an
1009 absolute path on "MSWin32".
1010 Current API available since 0.001.
1012
1014 Simple usage errors will generally croak. Failures of underlying Perl
1015 functions will be thrown as exceptions in the class
1016 "Path::Tiny::Error".
1017 A "Path::Tiny::Error" object will be a hash reference with the
1019 following fields:
1020 • "op" — a description of the operation, usually function call and
1022 any extra info
1023 • "file" — the file or directory relating to the error
1025 • "err" — hold $! at the time the error was thrown
1027 • "msg" — a string combining the above data and a Carp-like short
1029 stack trace
1030 Exception objects will stringify as the "msg" field.
1032
1034 PERL_PATH_TINY_NO_FLOCK
1035 If the environment variable "PERL_PATH_TINY_NO_FLOCK" is set to a true
1036 value then flock will NOT be used when accessing files (this is not
1037 recommended).
1038
1040 Subclassing not supported
1041 For speed, this class is implemented as an array based object and uses
1042 many direct function calls internally. You must not subclass it and
1043 expect things to work properly.
1044 Tilde expansion (deprecated)
1046 Tilde expansion was a nice idea, but it can't easily be applied
1047 consistently across the entire API. This was a source of bugs and
1048 confusion for users. Therefore, it is deprecated and its use is
1049 discouraged. Limitations to the existing, legacy behavior follow.
1050 Tilde expansion will only occur if the first argument to "path" begins
1052 with a tilde. No other method does tilde expansion on its arguments.
1053 If you want tilde expansion on arguments, you must explicitly wrap them
1054 in a call to "path".
1055 path( "~/foo.txt" )->copy( path( "~/bar.txt" ) );
1057 If you need a literal leading tilde, use path("./~whatever") so that
1059 the argument to "path" doesn't start with a tilde, but the path still
1060 resolves to the current directory.
1061 Behaviour of tilde expansion with a username for non-existent users
1063 depends on the output of "glob" on the system.
1064 File locking
1066 If flock is not supported on a platform, it will not be used, even if
1067 locking is requested.
1068 In situations where a platform normally would support locking, but the
1070 flock fails due to a filesystem limitation, Path::Tiny has some
1071 heuristics to detect this and will warn once and continue in an unsafe
1072 mode. If you want this failure to be fatal, you can fatalize the
1073 'flock' warnings category:
1074 use warnings FATAL => 'flock';
1076 See additional caveats below.
1078 NFS and BSD
1080 On BSD, Perl's flock implementation may not work to lock files on an
1082 NFS filesystem. If detected, this situation will warn once, as
1083 described above.
1084 Lustre
1086 The Lustre filesystem does not support flock. If detected, this
1088 situation will warn once, as described above.
1089 AIX and locking
1091 AIX requires a write handle for locking. Therefore, calls that
1093 normally open a read handle and take a shared lock instead will open a
1094 read-write handle and take an exclusive lock. If the user does not
1095 have write permission, no lock will be used.
1096 utf8 vs UTF-8
1098 All the *_utf8 methods by default use :encoding(UTF-8) -- either as
1099 :unix:encoding(UTF-8) (unbuffered, for whole file operations) or
1100 :raw:encoding(UTF-8) (buffered, for line-by-line operations). These are
1101 strict against the Unicode spec and disallows illegal Unicode
1102 codepoints or UTF-8 sequences.
1103 Unfortunately, :encoding(UTF-8) is very, very slow. If you install
1105 Unicode::UTF8 0.58 or later, that module will be used by some *_utf8
1106 methods to encode or decode data after a raw, binary input/output
1107 operation, which is much faster. Alternatively, if you install
1108 PerlIO::utf8_strict, that will be used instead of :encoding(UTF-8) and
1109 is also very fast.
1110 If you need the performance and can accept the security risk,
1112 "slurp({binmode => ":unix:utf8"})" will be faster than
1113 :unix:encoding(UTF-8) (but not as fast as "Unicode::UTF8").
1114 Note that the *_utf8 methods read in raw mode. There is no CRLF
1116 translation on Windows. If you must have CRLF translation, use the
1117 regular input/output methods with an appropriate binmode:
1118 $path->spew_utf8($data); # raw
1120 $path->spew({binmode => ":encoding(UTF-8)"}, $data; # LF -> CRLF
1121 Default IO layers and the open pragma
1123 If you have Perl 5.10 or later, file input/output methods ("slurp",
1124 "spew", etc.) and high-level handle opening methods ( "filehandle",
1125 "openr", "openw", etc. ) respect default encodings set by the "-C"
1126 switch or lexical open settings of the caller. For UTF-8, this is
1127 almost certainly slower than using the dedicated "_utf8" methods if you
1128 have Unicode::UTF8 or PerlIP::utf8_strict.
1129
1131 A standard MooseX::Types library is available at
1132 MooseX::Types::Path::Tiny. A Type::Tiny equivalent is available as
1133 Types::Path::Tiny.
1134
1136 These are other file/path utilities, which may offer a different
1137 feature set than "Path::Tiny".
1138 • File::chmod
1140 • File::Fu
1142 • IO::All
1144 • Path::Class
1146 These iterators may be slightly faster than the recursive iterator in
1148 "Path::Tiny":
1149 • Path::Iterator::Rule
1151 • File::Next
1153 There are probably comparable, non-Tiny tools. Let me know if you want
1155 me to add a module to the list.
1156 This module was featured in the 2013 Perl Advent Calendar
1158 <http://www.perladvent.org/2013/2013-12-18.html>.
1159
1161 Bugs / Feature Requests
1162 Please report any bugs or feature requests through the issue tracker at
1163 <https://github.com/dagolden/Path-Tiny/issues>. You will be notified
1164 automatically of any progress on your issue.
1165 Source Code
1167 This is open source software. The code repository is available for
1168 public review and contribution under the terms of the license.
1169 <https://github.com/dagolden/Path-Tiny>
1171 git clone https://github.com/dagolden/Path-Tiny.git
1173
1175 David Golden <dagolden@cpan.org>
1176
1178 • Alex Efros <powerman@powerman.name>
1179 • Aristotle Pagaltzis <pagaltzis@gmx.de>
1181 • Chris Williams <bingos@cpan.org>
1183 • Dan Book <grinnz@grinnz.com>
1185 • Dave Rolsky <autarch@urth.org>
1187 • David Steinbrunner <dsteinbrunner@pobox.com>
1189 • Doug Bell <madcityzen@gmail.com>
1191 • Elvin Aslanov <rwp.primary@gmail.com>
1193 • Flavio Poletti <flavio@polettix.it>
1195 • Gabor Szabo <szabgab@cpan.org>
1197 • Gabriel Andrade <gabiruh@gmail.com>
1199 • George Hartzell <hartzell@cpan.org>
1201 • Geraud Continsouzas <geraud@scsi.nc>
1203 • Goro Fuji <gfuji@cpan.org>
1205 • Graham Knop <haarg@haarg.org>
1207 • Graham Ollis <plicease@cpan.org>
1209 • Ian Sillitoe <ian@sillit.com>
1211 • James Hunt <james@niftylogic.com>
1213 • John Karr <brainbuz@brainbuz.org>
1215 • Karen Etheridge <ether@cpan.org>
1217 • Mark Ellis <mark.ellis@cartridgesave.co.uk>
1219 • Martin H. Sluka <fany@cpan.org>
1221 • Martin Kjeldsen <mk@bluepipe.dk>
1223 • Mary Ehlers <regina.verb.ae@gmail.com>
1225 • Michael G. Schwern <mschwern@cpan.org>
1227 • Nicolas R <nicolas@atoomic.org>
1229 • Nicolas Rochelemagne <rochelemagne@cpanel.net>
1231 • Nigel Gregoire <nigelgregoire@gmail.com>
1233 • Philippe Bruhat (BooK) <book@cpan.org>
1235 • regina-verbae <regina-verbae@users.noreply.github.com>
1237 • Roy Ivy III <rivy@cpan.org>
1239 • Shlomi Fish <shlomif@shlomifish.org>
1241 • Smylers <Smylers@stripey.com>
1243 • Tatsuhiko Miyagawa <miyagawa@bulknews.net>
1245 • Toby Inkster <tobyink@cpan.org>
1247 • Yanick Champoux <yanick@babyl.dyndns.org>
1249 • 김도형 - Keedi Kim <keedi@cpan.org>
1251
1253 This software is Copyright (c) 2014 by David Golden.
1254 This is free software, licensed under:
1256 The Apache License, Version 2.0, January 2004
1258perl v5.36.0 2023-01-20 Path::Tiny(3)