.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojo::File 3pm"
.TH Mojo::File 3pm "2019-02-05" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mojo::File \- File system paths
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mojo::File;
\&
\&  # Portably deal with file system paths
\&  my $path = Mojo::File\->new(\*(Aq/home/sri/.vimrc\*(Aq);
\&  say $path\->slurp;
\&  say $path\->dirname;
\&  say $path\->basename;
\&  say $path\->sibling(\*(Aq.bashrc\*(Aq);
\&
\&  # Use the alternative constructor
\&  use Mojo::File \*(Aqpath\*(Aq;
\&  my $path = path(\*(Aq/tmp/foo/bar\*(Aq)\->make_path;
\&  $path\->child(\*(Aqtest.txt\*(Aq)\->spurt(\*(AqHello Mojo!\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mojo::File is a scalar-based container for file system paths that provides a
friendly \s-1API\s0 for dealing with different operating systems.
.PP
.Vb 3
\&  # Access scalar directly to manipulate path
\&  my $path = Mojo::File\->new(\*(Aq/home/sri/test\*(Aq);
\&  $$path .= \*(Aq.txt\*(Aq;
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
Mojo::File implements the following functions, which can be imported
individually.
.SS "path"
.IX Subsection "path"
.Vb 4
\&  my $path = path;
\&  my $path = path(\*(Aq/home/sri/.vimrc\*(Aq);
\&  my $path = path(\*(Aq/home\*(Aq, \*(Aqsri\*(Aq, \*(Aq.vimrc\*(Aq);
\&  my $path = path(File::Temp\->newdir);
.Ve
.PP
Construct a new scalar-based Mojo::File object, defaults to using the current
working directory.
.PP
.Vb 2
\&  # "foo/bar/baz.txt" (on UNIX)
\&  path(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz.txt\*(Aq);
.Ve
.SS "tempdir"
.IX Subsection "tempdir"
.Vb 2
\&  my $path = tempdir;
\&  my $path = tempdir(\*(AqtempXXXXX\*(Aq);
.Ve
.PP
Construct a new scalar-based Mojo::File object for a temporary directory with
File::Temp.
.PP
.Vb 2
\&  # Longer version
\&  my $path = path(File::Temp\->newdir(\*(AqtempXXXXX\*(Aq));
.Ve
.SS "tempfile"
.IX Subsection "tempfile"
.Vb 2
\&  my $path = tempfile;
\&  my $path = tempfile(DIR => \*(Aq/tmp\*(Aq);
.Ve
.PP
Construct a new scalar-based Mojo::File object for a temporary file with
File::Temp.
.PP
.Vb 2
\&  # Longer version
\&  my $path = path(File::Temp\->new(DIR => \*(Aq/tmp\*(Aq));
.Ve
.SH "METHODS"
.IX Header "METHODS"
Mojo::File implements the following methods.
.SS "basename"
.IX Subsection "basename"
.Vb 2
\&  my $name = $path\->basename;
\&  my $name = $path\->basename(\*(Aq.txt\*(Aq);
.Ve
.PP
Return the last level of the path with File::Basename.
.PP
.Vb 2
\&  # ".vimrc" (on UNIX)
\&  path(\*(Aq/home/sri/.vimrc\*(Aq)\->basename;
\&
\&  # "test" (on UNIX)
\&  path(\*(Aq/home/sri/test.txt\*(Aq)\->basename(\*(Aq.txt\*(Aq);
.Ve
.SS "child"
.IX Subsection "child"
.Vb 1
\&  my $child = $path\->child(\*(Aq.vimrc\*(Aq);
.Ve
.PP
Return a new Mojo::File object relative to the path.
.PP
.Vb 2
\&  # "/home/sri/.vimrc" (on UNIX)
\&  path(\*(Aq/home\*(Aq)\->child(\*(Aqsri\*(Aq, \*(Aq.vimrc\*(Aq);
.Ve
.SS "chmod"
.IX Subsection "chmod"
.Vb 1
\&  $path = $path\->chmod(0644);
.Ve
.PP
Change file permissions.
.SS "copy_to"
.IX Subsection "copy_to"
.Vb 2
\&  my $destination = $path\->copy_to(\*(Aq/home/sri\*(Aq);
\&  my $destination = $path\->copy_to(\*(Aq/home/sri/.vimrc.backup\*(Aq);
.Ve
.PP
Copy file with File::Copy and return the destination as a Mojo::File
object.
.SS "dirname"
.IX Subsection "dirname"
.Vb 1
\&  my $name = $path\->dirname;
.Ve
.PP
Return all but the last level of the path with File::Basename as a
Mojo::File object.
.PP
.Vb 2
\&  # "/home/sri" (on UNIX)
\&  path(\*(Aq/home/sri/.vimrc\*(Aq)\->dirname;
.Ve
.SS "is_abs"
.IX Subsection "is_abs"
.Vb 1
\&  my $bool = $path\->is_abs;
.Ve
.PP
Check if the path is absolute.
.PP
.Vb 2
\&  # True (on UNIX)
\&  path(\*(Aq/home/sri/.vimrc\*(Aq)\->is_abs;
\&
\&  # False (on UNIX)
\&  path(\*(Aq.vimrc\*(Aq)\->is_abs;
.Ve
.SS "list"
.IX Subsection "list"
.Vb 2
\&  my $collection = $path\->list;
\&  my $collection = $path\->list({hidden => 1});
.Ve
.PP
List all files in the directory and return a Mojo::Collection object
containing the results as Mojo::File objects. The list does not include \f(CW\*(C`.\*(C'\fR
and \f(CW\*(C`..\*(C'\fR.
.PP
.Vb 2
\&  # List files
\&  say for path(\*(Aq/home/sri/myapp\*(Aq)\->list\->each;
.Ve
.PP
These options are currently available:
.IP "dir" 2
.IX Item "dir"
.Vb 1
\&  dir => 1
.Ve
.Sp
Include directories.
.IP "hidden" 2
.IX Item "hidden"
.Vb 1
\&  hidden => 1
.Ve
.Sp
Include hidden files.
.SS "list_tree"
.IX Subsection "list_tree"
.Vb 2
\&  my $collection = $path\->list_tree;
\&  my $collection = $path\->list_tree({hidden => 1});
.Ve
.PP
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 \f(CW\*(C`.\*(C'\fR and \f(CW\*(C`..\*(C'\fR.
.PP
.Vb 2
\&  # List all templates
\&  say for path(\*(Aq/home/sri/myapp/templates\*(Aq)\->list_tree\->each;
.Ve
.PP
These options are currently available:
.IP "dir" 2
.IX Item "dir"
.Vb 1
\&  dir => 1
.Ve
.Sp
Include directories.
.IP "dont_use_nlink" 2
.IX Item "dont_use_nlink"
.Vb 1
\&  dont_use_nlink => 1
.Ve
.Sp
Force File::Find to always stat directories.
.IP "hidden" 2
.IX Item "hidden"
.Vb 1
\&  hidden => 1
.Ve
.Sp
Include hidden files and directories.
.IP "max_depth" 2
.IX Item "max_depth"
.Vb 1
\&  max_depth => 3
.Ve
.Sp
Maximum number of levels to descend when searching for files.
.SS "lstat"
.IX Subsection "lstat"
.Vb 1
\&  my $stat = $path\->lstat;
.Ve
.PP
Return a File::stat object for the symlink.
.PP
.Vb 2
\&  # Get symlink size
\&  say path(\*(Aq/usr/sbin/sendmail\*(Aq)\->lstat\->size;
\&
\&  # Get symlink modification time
\&  say path(\*(Aq/usr/sbin/sendmail\*(Aq)\->lstat\->mtime;
.Ve
.SS "make_path"
.IX Subsection "make_path"
.Vb 2
\&  $path = $path\->make_path;
\&  $path = $path\->make_path({mode => 0711});
.Ve
.PP
Create the directories if they don't already exist, any additional arguments are
passed through to File::Path.
.SS "move_to"
.IX Subsection "move_to"
.Vb 2
\&  my $destination = $path\->move_to(\*(Aq/home/sri\*(Aq);
\&  my $destination = $path\->move_to(\*(Aq/home/sri/.vimrc.backup\*(Aq);
.Ve
.PP
Move file with File::Copy and return the destination as a Mojo::File
object.
.SS "new"
.IX Subsection "new"
.Vb 5
\&  my $path = Mojo::File\->new;
\&  my $path = Mojo::File\->new(\*(Aq/home/sri/.vimrc\*(Aq);
\&  my $path = Mojo::File\->new(\*(Aq/home\*(Aq, \*(Aqsri\*(Aq, \*(Aq.vimrc\*(Aq);
\&  my $path = Mojo::File\->new(File::Temp\->new);
\&  my $path = Mojo::File\->new(File::Temp\->newdir);
.Ve
.PP
Construct a new Mojo::File object, defaults to using the current working
directory.
.PP
.Vb 2
\&  # "foo/bar/baz.txt" (on UNIX)
\&  Mojo::File\->new(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz.txt\*(Aq);
.Ve
.SS "open"
.IX Subsection "open"
.Vb 4
\&  my $handle = $path\->open(\*(Aq+<\*(Aq);
\&  my $handle = $path\->open(\*(Aqr+\*(Aq);
\&  my $handle = $path\->open(O_RDWR);
\&  my $handle = $path\->open(\*(Aq<:encoding(UTF\-8)\*(Aq);
.Ve
.PP
Open file with IO::File.
.PP
.Vb 3
\&  # Combine "fcntl.h" constants
\&  use Fcntl qw(O_CREAT O_EXCL O_RDWR);
\&  my $handle = path(\*(Aq/home/sri/test.pl\*(Aq)\->open(O_RDWR | O_CREAT | O_EXCL);
.Ve
.SS "realpath"
.IX Subsection "realpath"
.Vb 1
\&  my $realpath = $path\->realpath;
.Ve
.PP
Resolve the path with Cwd and return the result as a Mojo::File object.
.SS "remove"
.IX Subsection "remove"
.Vb 1
\&  $path = $path\->remove;
.Ve
.PP
Delete file.
.SS "remove_tree"
.IX Subsection "remove_tree"
.Vb 2
\&  $path = $path\->remove_tree;
\&  $path = $path\->remove_tree({keep_root => 1});
.Ve
.PP
Delete this directory and any files and subdirectories it may contain, any
additional arguments are passed through to File::Path.
.SS "sibling"
.IX Subsection "sibling"
.Vb 1
\&  my $sibling = $path\->sibling(\*(Aq.vimrc\*(Aq);
.Ve
.PP
Return a new Mojo::File object relative to the directory part of the path.
.PP
.Vb 2
\&  # "/home/sri/.vimrc" (on UNIX)
\&  path(\*(Aq/home/sri/.bashrc\*(Aq)\->sibling(\*(Aq.vimrc\*(Aq);
\&
\&  # "/home/sri/.ssh/known_hosts" (on UNIX)
\&  path(\*(Aq/home/sri/.bashrc\*(Aq)\->sibling(\*(Aq.ssh\*(Aq, \*(Aqknown_hosts\*(Aq);
.Ve
.SS "slurp"
.IX Subsection "slurp"
.Vb 1
\&  my $bytes = $path\->slurp;
.Ve
.PP
Read all data at once from the file.
.SS "spurt"
.IX Subsection "spurt"
.Vb 2
\&  $path = $path\->spurt($bytes);
\&  $path = $path\->spurt(@chunks_of_bytes);
.Ve
.PP
Write all data at once to the file.
.SS "stat"
.IX Subsection "stat"
.Vb 1
\&  my $stat = $path\->stat;
.Ve
.PP
Return a File::stat object for the path.
.PP
.Vb 2
\&  # Get file size
\&  say path(\*(Aq/home/sri/.bashrc\*(Aq)\->stat\->size;
\&
\&  # Get file modification time
\&  say path(\*(Aq/home/sri/.bashrc\*(Aq)\->stat\->mtime;
.Ve
.SS "tap"
.IX Subsection "tap"
.Vb 1
\&  $path = $path\->tap(sub {...});
.Ve
.PP
Alias for \*(L"tap\*(R" in Mojo::Base.
.SS "to_abs"
.IX Subsection "to_abs"
.Vb 1
\&  my $absolute = $path\->to_abs;
.Ve
.PP
Return absolute path as a Mojo::File object, the path does not need to exist
on the file system.
.SS "to_array"
.IX Subsection "to_array"
.Vb 1
\&  my $parts = $path\->to_array;
.Ve
.PP
Split the path on directory separators.
.PP
.Vb 2
\&  # "home:sri:.vimrc" (on UNIX)
\&  join \*(Aq:\*(Aq, @{path(\*(Aq/home/sri/.vimrc\*(Aq)\->to_array};
.Ve
.SS "to_rel"
.IX Subsection "to_rel"
.Vb 1
\&  my $relative = $path\->to_rel(\*(Aq/some/base/path\*(Aq);
.Ve
.PP
Return a relative path from the original path to the destination path as a
Mojo::File object.
.PP
.Vb 2
\&  # "sri/.vimrc" (on UNIX)
\&  path(\*(Aq/home/sri/.vimrc\*(Aq)\->to_rel(\*(Aq/home\*(Aq);
.Ve
.SS "to_string"
.IX Subsection "to_string"
.Vb 1
\&  my $str = $path\->to_string;
.Ve
.PP
Stringify the path.
.SS "touch"
.IX Subsection "touch"
.Vb 1
\&  $path = $path\->touch;
.Ve
.PP
Create file if it does not exist or change the modification and access time to
the current time.
.PP
.Vb 2
\&  # Safely read file
\&  say path(\*(Aq.bashrc\*(Aq)\->touch\->slurp;
.Ve
.SS "with_roles"
.IX Subsection "with_roles"
.Vb 3
\&  my $new_class = Mojo::File\->with_roles(\*(AqMojo::File::Role::One\*(Aq);
\&  my $new_class = Mojo::File\->with_roles(\*(Aq+One\*(Aq, \*(Aq+Two\*(Aq);
\&  $path         = $path\->with_roles(\*(Aq+One\*(Aq, \*(Aq+Two\*(Aq);
.Ve
.PP
Alias for \*(L"with_roles\*(R" in Mojo::Base.
.SH "OPERATORS"
.IX Header "OPERATORS"
Mojo::File overloads the following operators.
.SS "array"
.IX Subsection "array"
.Vb 1
\&  my @parts = @$path;
.Ve
.PP
Alias for \*(L"to_array\*(R".
.SS "bool"
.IX Subsection "bool"
.Vb 1
\&  my $bool = !!$path;
.Ve
.PP
Always true.
.SS "stringify"
.IX Subsection "stringify"
.Vb 1
\&  my $str = "$path";
.Ve
.PP
Alias for \*(L"to_string\*(R".
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.