.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 2024-05-15 "perl v5.38.2" "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\->extname;
\&  say $path\->sibling(\*(Aq.bashrc\*(Aq);
\&
\&  # Use the alternative constructor
\&  use Mojo::File qw(path);
\&  my $path = path(\*(Aq/tmp/foo/bar\*(Aq)\->make_path;
\&  $path\->child(\*(Aqtest.txt\*(Aq)\->spew(\*(AqHello Mojo!\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Mojo::File is a scalar-based container for file system paths that provides a friendly API 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 curfile
.IX Subsection "curfile"
.Vb 1
\&  my $path = curfile;
.Ve
.PP
Construct a new scalar-based Mojo::File object for the absolute path to the current source file.
.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 extname
.IX Subsection "extname"
.Vb 1
\&  my $ext = $path\->extname;
.Ve
.PP
Return file extension of the path.
.PP
.Vb 2
\&  # "js"
\&  path(\*(Aq/home/sri/test.js\*(Aq)\->extname;
.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 2
\&  my $bytes = $path\->slurp;
\&  my $chars = $path\->slurp(\*(AqUTF\-8\*(Aq);
.Ve
.PP
Read all data at once from the file. If an encoding is provided, an attempt will be made to decode the content.
.SS spew
.IX Subsection "spew"
.Vb 2
\&  $path = $path\->spew($bytes);
\&  $path = $path\->spew($chars, \*(AqUTF\-8\*(Aq);
.Ve
.PP
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.
.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 "tap" 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 "with_roles" 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 "to_array".
.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 "to_string".
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.