Mojo::File(3pm)

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

NAME

6       Mojo::File - File system paths
7

SYNOPSIS

9         use Mojo::File;
10
11         # Portably deal with file system paths
12         my $path = Mojo::File->new('/home/sri/.vimrc');
13         say $path->slurp;
14         say $path->dirname;
15         say $path->basename;
16         say $path->extname;
17         say $path->sibling('.bashrc');
18
19         # Use the alternative constructor
20         use Mojo::File qw(path);
21         my $path = path('/tmp/foo/bar')->make_path;
22         $path->child('test.txt')->spurt('Hello Mojo!');
23

DESCRIPTION

25       Mojo::File is a scalar-based container for file system paths that
26       provides a friendly API for dealing with different operating systems.
27
28         # Access scalar directly to manipulate path
29         my $path = Mojo::File->new('/home/sri/test');
30         $$path .= '.txt';
31

FUNCTIONS

33       Mojo::File implements the following functions, which can be imported
34       individually.
35
36   curfile
37         my $path = curfile;
38
39       Construct a new scalar-based Mojo::File object for the absolute path to
40       the current source file.
41
42   path
43         my $path = path;
44         my $path = path('/home/sri/.vimrc');
45         my $path = path('/home', 'sri', '.vimrc');
46         my $path = path(File::Temp->newdir);
47
48       Construct a new scalar-based Mojo::File object, defaults to using the
49       current working directory.
50
51         # "foo/bar/baz.txt" (on UNIX)
52         path('foo', 'bar', 'baz.txt');
53
54   tempdir
55         my $path = tempdir;
56         my $path = tempdir('tempXXXXX');
57
58       Construct a new scalar-based Mojo::File object for a temporary
59       directory with File::Temp.
60
61         # Longer version
62         my $path = path(File::Temp->newdir('tempXXXXX'));
63
64   tempfile
65         my $path = tempfile;
66         my $path = tempfile(DIR => '/tmp');
67
68       Construct a new scalar-based Mojo::File object for a temporary file
69       with File::Temp.
70
71         # Longer version
72         my $path = path(File::Temp->new(DIR => '/tmp'));
73

METHODS

75       Mojo::File implements the following methods.
76
77   basename
78         my $name = $path->basename;
79         my $name = $path->basename('.txt');
80
81       Return the last level of the path with File::Basename.
82
83         # ".vimrc" (on UNIX)
84         path('/home/sri/.vimrc')->basename;
85
86         # "test" (on UNIX)
87         path('/home/sri/test.txt')->basename('.txt');
88
89   child
90         my $child = $path->child('.vimrc');
91
92       Return a new Mojo::File object relative to the path.
93
94         # "/home/sri/.vimrc" (on UNIX)
95         path('/home')->child('sri', '.vimrc');
96
97   chmod
98         $path = $path->chmod(0644);
99
100       Change file permissions.
101
102   copy_to
103         my $destination = $path->copy_to('/home/sri');
104         my $destination = $path->copy_to('/home/sri/.vimrc.backup');
105
106       Copy file with File::Copy and return the destination as a Mojo::File
107       object.
108
109   dirname
110         my $name = $path->dirname;
111
112       Return all but the last level of the path with File::Basename as a
113       Mojo::File object.
114
115         # "/home/sri" (on UNIX)
116         path('/home/sri/.vimrc')->dirname;
117
118   extname
119         my $ext = $path->extname;
120
121       Return file extension of the path. Note that this method is
122       EXPERIMENTAL and might change without warning!
123
124         # "js"
125         path('/home/sri/test.js')->extname;
126
127   is_abs
128         my $bool = $path->is_abs;
129
130       Check if the path is absolute.
131
132         # True (on UNIX)
133         path('/home/sri/.vimrc')->is_abs;
134
135         # False (on UNIX)
136         path('.vimrc')->is_abs;
137
138   list
139         my $collection = $path->list;
140         my $collection = $path->list({hidden => 1});
141
142       List all files in the directory and return a Mojo::Collection object
143       containing the results as Mojo::File objects. The list does not include
144       "." and "..".
145
146         # List files
147         say for path('/home/sri/myapp')->list->each;
148
149       These options are currently available:
150
151       dir
152           dir => 1
153
154         Include directories.
155
156       hidden
157           hidden => 1
158
159         Include hidden files.
160
161   list_tree
162         my $collection = $path->list_tree;
163         my $collection = $path->list_tree({hidden => 1});
164
165       List all files recursively in the directory and return a
166       Mojo::Collection object containing the results as Mojo::File objects.
167       The list does not include "." and "..".
168
169         # List all templates
170         say for path('/home/sri/myapp/templates')->list_tree->each;
171
172       These options are currently available:
173
174       dir
175           dir => 1
176
177         Include directories.
178
179       dont_use_nlink
180           dont_use_nlink => 1
181
182         Force File::Find to always stat directories.
183
184       hidden
185           hidden => 1
186
187         Include hidden files and directories.
188
189       max_depth
190           max_depth => 3
191
192         Maximum number of levels to descend when searching for files.
193
194   lstat
195         my $stat = $path->lstat;
196
197       Return a File::stat object for the symlink.
198
199         # Get symlink size
200         say path('/usr/sbin/sendmail')->lstat->size;
201
202         # Get symlink modification time
203         say path('/usr/sbin/sendmail')->lstat->mtime;
204
205   make_path
206         $path = $path->make_path;
207         $path = $path->make_path({mode => 0711});
208
209       Create the directories if they don't already exist, any additional
210       arguments are passed through to File::Path.
211
212   move_to
213         my $destination = $path->move_to('/home/sri');
214         my $destination = $path->move_to('/home/sri/.vimrc.backup');
215
216       Move file with File::Copy and return the destination as a Mojo::File
217       object.
218
219   new
220         my $path = Mojo::File->new;
221         my $path = Mojo::File->new('/home/sri/.vimrc');
222         my $path = Mojo::File->new('/home', 'sri', '.vimrc');
223         my $path = Mojo::File->new(File::Temp->new);
224         my $path = Mojo::File->new(File::Temp->newdir);
225
226       Construct a new Mojo::File object, defaults to using the current
227       working directory.
228
229         # "foo/bar/baz.txt" (on UNIX)
230         Mojo::File->new('foo', 'bar', 'baz.txt');
231
232   open
233         my $handle = $path->open('+<');
234         my $handle = $path->open('r+');
235         my $handle = $path->open(O_RDWR);
236         my $handle = $path->open('<:encoding(UTF-8)');
237
238       Open file with IO::File.
239
240         # Combine "fcntl.h" constants
241         use Fcntl qw(O_CREAT O_EXCL O_RDWR);
242         my $handle = path('/home/sri/test.pl')->open(O_RDWR | O_CREAT | O_EXCL);
243
244   realpath
245         my $realpath = $path->realpath;
246
247       Resolve the path with Cwd and return the result as a Mojo::File object.
248
249   remove
250         $path = $path->remove;
251
252       Delete file.
253
254   remove_tree
255         $path = $path->remove_tree;
256         $path = $path->remove_tree({keep_root => 1});
257
258       Delete this directory and any files and subdirectories it may contain,
259       any additional arguments are passed through to File::Path.
260
261   sibling
262         my $sibling = $path->sibling('.vimrc');
263
264       Return a new Mojo::File object relative to the directory part of the
265       path.
266
267         # "/home/sri/.vimrc" (on UNIX)
268         path('/home/sri/.bashrc')->sibling('.vimrc');
269
270         # "/home/sri/.ssh/known_hosts" (on UNIX)
271         path('/home/sri/.bashrc')->sibling('.ssh', 'known_hosts');
272
273   slurp
274         my $bytes = $path->slurp;
275
276       Read all data at once from the file.
277
278   spurt
279         $path = $path->spurt($bytes);
280         $path = $path->spurt(@chunks_of_bytes);
281
282       Write all data at once to the file.
283
284   stat
285         my $stat = $path->stat;
286
287       Return a File::stat object for the path.
288
289         # Get file size
290         say path('/home/sri/.bashrc')->stat->size;
291
292         # Get file modification time
293         say path('/home/sri/.bashrc')->stat->mtime;
294
295   tap
296         $path = $path->tap(sub {...});
297
298       Alias for "tap" in Mojo::Base.
299
300   to_abs
301         my $absolute = $path->to_abs;
302
303       Return absolute path as a Mojo::File object, the path does not need to
304       exist on the file system.
305
306   to_array
307         my $parts = $path->to_array;
308
309       Split the path on directory separators.
310
311         # "home:sri:.vimrc" (on UNIX)
312         join ':', @{path('/home/sri/.vimrc')->to_array};
313
314   to_rel
315         my $relative = $path->to_rel('/some/base/path');
316
317       Return a relative path from the original path to the destination path
318       as a Mojo::File object.
319
320         # "sri/.vimrc" (on UNIX)
321         path('/home/sri/.vimrc')->to_rel('/home');
322
323   to_string
324         my $str = $path->to_string;
325
326       Stringify the path.
327
328   touch
329         $path = $path->touch;
330
331       Create file if it does not exist or change the modification and access
332       time to the current time.
333
334         # Safely read file
335         say path('.bashrc')->touch->slurp;
336
337   with_roles
338         my $new_class = Mojo::File->with_roles('Mojo::File::Role::One');
339         my $new_class = Mojo::File->with_roles('+One', '+Two');
340         $path         = $path->with_roles('+One', '+Two');
341
342       Alias for "with_roles" in Mojo::Base.
343

OPERATORS

345       Mojo::File overloads the following operators.
346
347   array
348         my @parts = @$path;
349
350       Alias for "to_array".
351
352   bool
353         my $bool = !!$path;
354
355       Always true.
356
357   stringify
358         my $str = "$path";
359
360       Alias for "to_string".
361

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

METHODS

OPERATORS

SEE ALSO