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

OPERATORS

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

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

METHODS

OPERATORS

SEE ALSO