--- name: "Mojo::File" section: "3pm" platform: "linux" package: "libmojolicious-perl" version: "9.39+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Mojo::File" --- # Mojo::File(3pm) File system paths ## NAME Mojo::File - File system paths ## SYNOPSIS ``` use Mojo::File; # Portably deal with file system paths my $path = Mojo::File->new('/home/sri/.vimrc'); say $path->slurp; say $path->dirname; say $path->basename; say $path->extname; say $path->sibling('.bashrc'); # Use the alternative constructor use Mojo::File qw(path); my $path = path('/tmp/foo/bar')->make_path; $path->child('test.txt')->spew('Hello Mojo!'); ``` ## DESCRIPTION Mojo::File is a scalar-based container for file system paths that provides a friendly API for dealing with different operating systems. ``` # Access scalar directly to manipulate path my $path = Mojo::File->new('/home/sri/test'); $$path .= '.txt'; ``` ## FUNCTIONS Mojo::File implements the following functions, which can be imported individually. ### curfile ``` my $path = curfile; ``` Construct a new scalar-based Mojo::File object for the absolute path to the current source file. ### path ``` my $path = path; my $path = path('/home/sri/.vimrc'); my $path = path('/home', 'sri', '.vimrc'); my $path = path(File::Temp->newdir); ``` Construct a new scalar-based Mojo::File object, defaults to using the current working directory. ``` # "foo/bar/baz.txt" (on UNIX) path('foo', 'bar', 'baz.txt'); ``` ### tempdir ``` my $path = tempdir; my $path = tempdir('tempXXXXX'); ``` Construct a new scalar-based Mojo::File object for a temporary directory with File::Temp. ``` # Longer version my $path = path(File::Temp->newdir('tempXXXXX')); ``` ### tempfile ``` my $path = tempfile; my $path = tempfile(DIR => '/tmp'); ``` Construct a new scalar-based Mojo::File object for a temporary file with File::Temp. ``` # Longer version my $path = path(File::Temp->new(DIR => '/tmp')); ``` ## METHODS Mojo::File implements the following methods. ### basename ``` my $name = $path->basename; my $name = $path->basename('.txt'); ``` Return the last level of the path with File::Basename. ``` # ".vimrc" (on UNIX) path('/home/sri/.vimrc')->basename; # "test" (on UNIX) path('/home/sri/test.txt')->basename('.txt'); ``` ### child ``` my $child = $path->child('.vimrc'); ``` Return a new Mojo::File object relative to the path. ``` # "/home/sri/.vimrc" (on UNIX) path('/home')->child('sri', '.vimrc'); ``` ### chmod ``` $path = $path->chmod(0644); ``` Change file permissions. ### copy\_to ``` my $destination = $path->copy_to('/home/sri'); my $destination = $path->copy_to('/home/sri/.vimrc.backup'); ``` Copy file with File::Copy and return the destination as a Mojo::File object. ### dirname ``` my $name = $path->dirname; ``` Return all but the last level of the path with File::Basename as a Mojo::File object. ``` # "/home/sri" (on UNIX) path('/home/sri/.vimrc')->dirname; ``` ### extname ``` my $ext = $path->extname; ``` Return file extension of the path. ``` # "js" path('/home/sri/test.js')->extname; ``` ### is\_abs ``` my $bool = $path->is_abs; ``` Check if the path is absolute. ``` # True (on UNIX) path('/home/sri/.vimrc')->is_abs; # False (on UNIX) path('.vimrc')->is_abs; ``` ### list ``` my $collection = $path->list; my $collection = $path->list({hidden => 1}); ``` List all files in the directory and return a Mojo::Collection object containing the results as Mojo::File objects. The list does not include `"."` and `".."`. ``` # List files say for path('/home/sri/myapp')->list->each; ``` These options are currently available: - dir ``` dir => 1 ``` Include directories. - hidden ``` hidden => 1 ``` Include hidden files. ### list\_tree ``` my $collection = $path->list_tree; my $collection = $path->list_tree({hidden => 1}); ``` List all files recursively in the directory and return a Mojo::Collection object containing the results as Mojo::File objects. The list does not include `"."` and `".."`. ``` # List all templates say for path('/home/sri/myapp/templates')->list_tree->each; ``` These options are currently available: - dir ``` dir => 1 ``` Include directories. - dont\_use\_nlink ``` dont_use_nlink => 1 ``` Force File::Find to always stat directories. - hidden ``` hidden => 1 ``` Include hidden files and directories. - max\_depth ``` max_depth => 3 ``` Maximum number of levels to descend when searching for files. ### lstat ``` my $stat = $path->lstat; ``` Return a File::stat object for the symlink. ``` # Get symlink size say path('/usr/sbin/sendmail')->lstat->size; # Get symlink modification time say path('/usr/sbin/sendmail')->lstat->mtime; ``` ### make\_path ``` $path = $path->make_path; $path = $path->make_path({mode => 0711}); ``` Create the directories if they don't already exist, any additional arguments are passed through to File::Path. ### move\_to ``` my $destination = $path->move_to('/home/sri'); my $destination = $path->move_to('/home/sri/.vimrc.backup'); ``` Move file with File::Copy and return the destination as a Mojo::File object. ### new ``` my $path = Mojo::File->new; my $path = Mojo::File->new('/home/sri/.vimrc'); my $path = Mojo::File->new('/home', 'sri', '.vimrc'); my $path = Mojo::File->new(File::Temp->new); my $path = Mojo::File->new(File::Temp->newdir); ``` Construct a new Mojo::File object, defaults to using the current working directory. ``` # "foo/bar/baz.txt" (on UNIX) Mojo::File->new('foo', 'bar', 'baz.txt'); ``` ### open ``` my $handle = $path->open('+<'); my $handle = $path->open('r+'); my $handle = $path->open(O_RDWR); my $handle = $path->open('<:encoding(UTF-8)'); ``` Open file with IO::File. ``` # Combine "fcntl.h" constants use Fcntl qw(O_CREAT O_EXCL O_RDWR); my $handle = path('/home/sri/test.pl')->open(O_RDWR | O_CREAT | O_EXCL); ``` ### realpath ``` my $realpath = $path->realpath; ``` Resolve the path with Cwd and return the result as a Mojo::File object. ### remove ``` $path = $path->remove; ``` Delete file. ### remove\_tree ``` $path = $path->remove_tree; $path = $path->remove_tree({keep_root => 1}); ``` Delete this directory and any files and subdirectories it may contain, any additional arguments are passed through to File::Path. ### sibling ``` my $sibling = $path->sibling('.vimrc'); ``` Return a new Mojo::File object relative to the directory part of the path. ``` # "/home/sri/.vimrc" (on UNIX) path('/home/sri/.bashrc')->sibling('.vimrc'); # "/home/sri/.ssh/known_hosts" (on UNIX) path('/home/sri/.bashrc')->sibling('.ssh', 'known_hosts'); ``` ### slurp ``` my $bytes = $path->slurp; my $chars = $path->slurp('UTF-8'); ``` Read all data at once from the file. If an encoding is provided, an attempt will be made to decode the content. ### spew ``` $path = $path->spew($bytes); $path = $path->spew($chars, 'UTF-8'); ``` Write all data at once to the file. If an encoding is provided, an attempt to encode the content will be made prior to writing. ### stat ``` my $stat = $path->stat; ``` Return a File::stat object for the path. ``` # Get file size say path('/home/sri/.bashrc')->stat->size; # Get file modification time say path('/home/sri/.bashrc')->stat->mtime; ``` ### tap ``` $path = $path->tap(sub {...}); ``` Alias for "tap" in Mojo::Base. ### to\_abs ``` my $absolute = $path->to_abs; ``` Return absolute path as a Mojo::File object, the path does not need to exist on the file system. ### to\_array ``` my $parts = $path->to_array; ``` Split the path on directory separators. ``` # "home:sri:.vimrc" (on UNIX) join ':', @{path('/home/sri/.vimrc')->to_array}; ``` ### to\_rel ``` my $relative = $path->to_rel('/some/base/path'); ``` Return a relative path from the original path to the destination path as a Mojo::File object. ``` # "sri/.vimrc" (on UNIX) path('/home/sri/.vimrc')->to_rel('/home'); ``` ### to\_string ``` my $str = $path->to_string; ``` Stringify the path. ### touch ``` $path = $path->touch; ``` Create file if it does not exist or change the modification and access time to the current time. ``` # Safely read file say path('.bashrc')->touch->slurp; ``` ### with\_roles ``` my $new_class = Mojo::File->with_roles('Mojo::File::Role::One'); my $new_class = Mojo::File->with_roles('+One', '+Two'); $path = $path->with_roles('+One', '+Two'); ``` Alias for "with\_roles" in Mojo::Base. ## OPERATORS Mojo::File overloads the following operators. ### array ``` my @parts = @$path; ``` Alias for "to\_array". ### bool ``` my $bool = !!$path; ``` Always true. ### stringify ``` my $str = "$path"; ``` Alias for "to\_string". ## SEE ALSO Mojolicious, Mojolicious::Guides, \.