add documentation for Mojo::File

mojolicious · Jan 7, 2017 · e25c058 · e25c058
1 parent 47873c6
commit e25c058
Show file tree

Hide file tree

Showing 2 changed files with 205 additions and 1 deletion.
diff --git a/lib/Mojo/File.pm b/lib/Mojo/File.pm
@@ -98,3 +98,207 @@ sub to_rel { $_[0]->new(File::Spec->abs2rel(${$_[0]}, $_[1])) }
 sub to_string {"${$_[0]}"}
 
 1;
+
+=encoding utf8
+
+=head1 NAME
+
+Mojo::File - File paths
+
+=head1 SYNOPSIS
+
+  use Mojo::File;
+
+  my $path = Mojo::File->new('/home/sri/.vimrc');
+  say $path->basename;
+  say $path->dirname->child('.bashrc');
+
+  # Use the alternative constructor
+  use Mojo::File 'path';
+  my $path = path('/home/sri/.vimrc')->dirname;
+
+=head1 DESCRIPTION
+
+L<Mojo::File> is a scalar-based container for file system paths.
+
+  # Access scalar directly to manipulate path
+  my $path = Mojo::File->new('/home/sri/');
+  $$path .= '.vimrc';
+
+=head1 FUNCTIONS
+
+L<Mojo::File> implements the following functions, which can be imported
+individually.
+
+=head2 path
+
+  my $path = path;
+  my $path = path('/home/sri/.vimrc');
+  my $path = path('/home', 'sri', '.vimrc');
+
+Construct a new scalar-based L<Mojo::File> object, defaults to using the current
+working directory.
+
+=head2 tempdir
+
+  my $path = tempdir;
+  my $path = tempdir('tempXXXXX');
+
+Construct a new scalar-based L<Mojo::File> object with L<File::Temp>.
+
+  # Longer version
+  my $path = Mojo::File->new(File::Temp->new('tempXXXXX'));
+
+=head1 METHODS
+
+L<Mojo::File> implements the following methods.
+
+=head2 basename
+
+  my $name = $path->basename;
+
+Return the last level of the path with L<File::Basename> as a string.
+
+  # ".vimrc" (on UNIX)
+  Mojo::File->new('/home/sri/.vimrc')->basename;
+
+=head2 child
+
+  my $child = $path->child('.vimrc');
+
+Return a new L<Mojo::File> object relative to the original.
+
+  # "/home/sri/.vimrc" (on UNIX)
+  Mojo::File->new('/home')->child('sri', '.vimrc');
+
+=head2 dirname
+
+  my $name = $path->dirname;
+
+Return all but the last level of the path with L<File::Basename> as a
+L<Mojo::File> object.
+
+  # "/home/sri" (on UNIX)
+  Mojo::File->new('/home/sri/.vimrc')->dirname;
+
+=head2 list_tree
+
+  my $collection = $path->list_tree;
+  my $collection = $path->list_tree({hidden => 1});
+
+List all files recursively in a directory and return a L<Mojo::Collection>
+object containing the results as L<Mojo::File> objects.
+
+  # List all templates
+  say for Mojo::File->new('/home/sri/myapp/templates')->list_tree->each;
+
+These options are currently available:
+
+=over 2
+
+=item hidden
+
+  hidden => 1
+
+Include hidden files and directories.
+
+=back
+
+=head2 make_path
+
+  $path = $path->make_path;
+
+Create the given directories if they don't exist already with L<File::Path>.
+
+=head2 move_to
+
+  my $path = $path->move_to('/home/sri/.vimrc.backup');
+
+Move a file with L<File::Copy> and return a new L<Mojo::File> object for the
+destination path.
+
+=head2 new
+
+  my $path = Mojo::File->new;
+  my $path = Mojo::File->new('/home/sri/.vimrc');
+  my $path = Mojo::File->new('/home', 'sri', '.vimrc');
+
+Construct a new L<Mojo::File> object, defaults to using the current working
+directory.
+
+=head2 slurp
+
+  my $bytes = $path->slurp;
+
+Read all data at once from file.
+
+=head2 spurt
+
+  $path = $path->spurt($bytes);
+
+Write all data at once to file.
+
+=head2 tap
+
+  $path = $path->tap(sub {...});
+
+Alias for L<Mojo::Base/"tap">.
+
+=head2 to_abs
+
+  my $absolute = $path->to_abs;
+
+Return the canonical path as a L<Mojo::File> object.
+
+=head2 to_array
+
+  my $parts = $path->to_array;
+
+Split the path on directory separators.
+
+  # "home:sri:.vimrc" (on UNIX)
+  join ':', @{Mojo::File->new('/home/sri/.vimrc')->to_array};
+
+=head2 to_rel
+
+  my $relative = $path->to_rel('/some/base/path');
+
+Return a relative path from the original path to the destination path as a
+L<Mojo::File> object.
+
+  # "sri/.vimrc" (on UNIX)
+  Mojo::File->new('/home/sri/.vimrc')->to_rel('/home');
+
+=head2 to_string
+
+  my $str = $path->to_string;
+
+Turn path into a string.
+
+=head1 OPERATORS
+
+L<Mojo::File> overloads the following operators.
+
+=head2 array
+
+  my @parts = @$path;
+
+Alias for L</"to_array">.
+
+=head2 bool
+
+  my $bool = !!$path;
+
+Always true.
+
+=head2 stringify
+
+  my $str = "$path";
+
+Alias for L</"to_string">.
+
+=head1 SEE ALSO
+
+L<Mojolicious>, L<Mojolicious::Guides>, L<http://mojolicious.org>.
+
+=cut
diff --git a/t/pod_coverage.t b/t/pod_coverage.t
@@ -8,4 +8,4 @@ plan skip_all => 'Test::Pod::Coverage 1.04+ required for this test!'
   unless eval 'use Test::Pod::Coverage 1.04; 1';
 
 # DEPRECATED!
-all_pod_coverage_ok({also_private => [qw(list_files rel_dir is_status_class)]});
+all_pod_coverage_ok({also_private => [qw(files rel_dir is_status_class)]});