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')->spurt('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;

       Read all data at once from the file.

   spurt
         $path = $path->spurt($bytes);
         $path = $path->spurt(@chunks_of_bytes);

       Write all data at once to the file.

   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, <https://mojolicious.org>.