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   path
36         my $path = path;
37         my $path = path('/home/sri/.vimrc');
38         my $path = path('/home', 'sri', '.vimrc');
39         my $path = path(File::Temp->newdir);
40
41       Construct a new scalar-based Mojo::File object, defaults to using the
42       current working directory.
43
44         # "foo/bar/baz.txt" (on UNIX)
45         path('foo', 'bar', 'baz.txt');
46
47   tempdir
48         my $path = tempdir;
49         my $path = tempdir('tempXXXXX');
50
51       Construct a new scalar-based Mojo::File object for a temporary
52       directory with File::Temp.
53
54         # Longer version
55         my $path = path(File::Temp->newdir('tempXXXXX'));
56
57   tempfile
58         my $path = tempfile;
59         my $path = tempfile(DIR => '/tmp');
60
61       Construct a new scalar-based Mojo::File object for a temporary file
62       with File::Temp.
63
64         # Longer version
65         my $path = path(File::Temp->new(DIR => '/tmp'));
66

METHODS

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

OPERATORS

329       Mojo::File overloads the following operators.
330
331   array
332         my @parts = @$path;
333
334       Alias for "to_array".
335
336   bool
337         my $bool = !!$path;
338
339       Always true.
340
341   stringify
342         my $str = "$path";
343
344       Alias for "to_string".
345

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

METHODS

OPERATORS

SEE ALSO