Mojo::File(3pm)

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;

  download
  my $bool = $path->download('https://example.com/test.tar.gz');
  my $bool = $path->download('https://example.com/test.tar.gz', {headers => {Accept => '*/*'}});
  my $bool = $path->download('https://example.com/test.tar.gz', {ua => Mojo::UserAgent->new});

Download file from URL, returns true once the file has been downloaded completely. Incomplete downloads are resumed. Follows 10 redirects by default and does not limit the size of the response, which will be streamed memory efficiently. Note that this method is EXPERIMENTAL and might change without warning!

  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.

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.

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

Alias for "spew" that writes multiple chunks of bytes.

  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>.