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->sibling('.bashrc');
17
18         # Use the alternative constructor
19         use Mojo::File 'path';
20         my $path = path('/tmp/foo/bar')->make_path;
21         $path->child('test.txt')->spurt('Hello Mojo!');
22

DESCRIPTION

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

FUNCTIONS

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

METHODS

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

OPERATORS

335       Mojo::File overloads the following operators.
336
337   array
338         my @parts = @$path;
339
340       Alias for "to_array".
341
342   bool
343         my $bool = !!$path;
344
345       Always true.
346
347   stringify
348         my $str = "$path";
349
350       Alias for "to_string".
351

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

METHODS

OPERATORS

SEE ALSO