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')->spew('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         my $chars = $path->slurp('UTF-8');
275
276       Read all data at once from the file. If an encoding is provided, an
277       attempt will be made to decode the content.
278
279   spew
280         $path = $path->spew($bytes);
281         $path = $path->spew($chars, 'UTF-8');
282
283       Write all data at once to the file. If an encoding is provided, an
284       attempt to encode the content will be made prior to writing.
285
286   stat
287         my $stat = $path->stat;
288
289       Return a File::stat object for the path.
290
291         # Get file size
292         say path('/home/sri/.bashrc')->stat->size;
293
294         # Get file modification time
295         say path('/home/sri/.bashrc')->stat->mtime;
296
297   tap
298         $path = $path->tap(sub {...});
299
300       Alias for "tap" in Mojo::Base.
301
302   to_abs
303         my $absolute = $path->to_abs;
304
305       Return absolute path as a Mojo::File object, the path does not need to
306       exist on the file system.
307
308   to_array
309         my $parts = $path->to_array;
310
311       Split the path on directory separators.
312
313         # "home:sri:.vimrc" (on UNIX)
314         join ':', @{path('/home/sri/.vimrc')->to_array};
315
316   to_rel
317         my $relative = $path->to_rel('/some/base/path');
318
319       Return a relative path from the original path to the destination path
320       as a Mojo::File object.
321
322         # "sri/.vimrc" (on UNIX)
323         path('/home/sri/.vimrc')->to_rel('/home');
324
325   to_string
326         my $str = $path->to_string;
327
328       Stringify the path.
329
330   touch
331         $path = $path->touch;
332
333       Create file if it does not exist or change the modification and access
334       time to the current time.
335
336         # Safely read file
337         say path('.bashrc')->touch->slurp;
338
339   with_roles
340         my $new_class = Mojo::File->with_roles('Mojo::File::Role::One');
341         my $new_class = Mojo::File->with_roles('+One', '+Two');
342         $path         = $path->with_roles('+One', '+Two');
343
344       Alias for "with_roles" in Mojo::Base.
345

OPERATORS

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

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

METHODS

OPERATORS

SEE ALSO