[libpath-tiny-perl] 09/11: Imported Upstream version 0.027
Jonas Smedegaard
js at alioth.debian.org
Wed Aug 7 16:10:31 UTC 2013
This is an automated email from the git hooks/post-receive script.
js pushed a commit to branch master
in repository libpath-tiny-perl.
commit 14c932bb829517e808575e86c591f7fbbd2ca1c3
Merge: c90f70d 1d904c8
Author: Jonas Smedegaard <dr at jones.dk>
Date: Wed Aug 7 17:55:54 2013 +0200
Imported Upstream version 0.027
Changes | 7 ++++++
MANIFEST | 1 +
META.json | 9 +++++---
META.yml | 9 +++++---
Makefile.PL | 4 +++-
README | 24 +++++++++++++++++---
dist.ini | 10 ++++-----
lib/Path/Tiny.pm | 58 +++++++++++++++++++++++++++++++++++++++++++------
t/00-report-prereqs.t | 2 ++
t/digest.t | 52 ++++++++++++++++++++++++++++++++++++++++++++
xt/author/pod-spell.t | 13 ++++++-----
11 files changed, 162 insertions(+), 27 deletions(-)
diff --cc Changes
index 90d77dc,4bedbb6..4bf2ea8
--- a/Changes
+++ b/Changes
@@@ -1,5 -1,12 +1,12 @@@
Revision history for Path-Tiny
-{{$NEXT}}
++0.027 2013-07-25 19:38:44 America/New_York
+
+ [ADDED]
+
+ - Added the 'digest' method to produce a hexadecimal SHA-256
+ (or user-specified) digest of a file
+
0.026 2013-07-14 21:25:22 America/New_York
[FIXED]
diff --cc MANIFEST
index 501eac7,0000000..830641d
mode 100644,000000..100644
--- a/MANIFEST
+++ b/MANIFEST
@@@ -1,38 -1,0 +1,39 @@@
+CONTRIBUTING
+Changes
+LICENSE
+MANIFEST
+META.json
+META.yml
+Makefile.PL
+README
+dist.ini
+lib/Path/Tiny.pm
+perlcritic.rc
+t/00-compile.t
+t/00-report-prereqs.t
+t/README
+t/basic.t
+t/children.t
++t/digest.t
+t/exception.t
+t/exports.t
+t/filesystem.t
+t/input_output.t
+t/input_output_no_UU.t
+t/mkpath.t
+t/normalize.t
+t/overloading.t
+t/parent.t
+t/recurse.t
+t/rel-abs.t
+t/temp.t
+t/zzz-spec.t
+tidyall.ini
+xt/author/critic.t
+xt/author/pod-spell.t
+xt/release/distmeta.t
+xt/release/minimum-version.t
+xt/release/pod-coverage.t
+xt/release/pod-syntax.t
+xt/release/portability.t
+xt/release/test-version.t
diff --cc META.yml
index 1aac7e5,0000000..ad77647
mode 100644,000000..100644
--- a/META.yml
+++ b/META.yml
@@@ -1,70 -1,0 +1,73 @@@
+---
+abstract: 'File path utility'
+author:
+ - 'David Golden <dagolden at cpan.org>'
+build_requires:
+ Devel::Hide: 0
+ ExtUtils::MakeMaker: 0
+ File::Find: 0
+ File::Spec::Functions: 0
+ File::Spec::Unix: 0
+ File::pushd: 0
+ List::Util: 0
+ Test::Deep: 0
+ Test::FailWarnings: 0
+ Test::Fatal: 0
+ Test::More: 0.96
+ open: 0
+configure_requires:
+ ExtUtils::MakeMaker: 6.30
+dynamic_config: 0
- generated_by: 'Dist::Zilla version 4.300035, CPAN::Meta::Converter version 2.131560'
++generated_by: 'Dist::Zilla version 4.300035, CPAN::Meta::Converter version 2.130880'
+license: apache
+meta-spec:
+ url: http://module-build.sourceforge.net/META-spec-v1.4.html
+ version: 1.4
+name: Path-Tiny
+no_index:
+ directory:
+ - t
+ - xt
+ - examples
+ - corpus
+ package:
+ - DB
+provides:
+ Path::Tiny:
+ file: lib/Path/Tiny.pm
- version: 0.026
++ version: 0.027
+recommends:
+ Unicode::UTF8: 0.58
+requires:
+ Carp: 0
+ Cwd: 0
++ Digest: 1.03
++ Digest::SHA: 5.45
+ Exporter: 5.57
+ Fcntl: 0
+ File::Copy: 0
+ File::Path: 2.07
+ File::Spec: 3.40
+ File::Temp: 0.18
+ File::stat: 0
+ autodie::exception: 2.14
+ constant: 0
+ overload: 0
+ perl: 5.008001
+ strict: 0
+ threads: 0
+ warnings: 0
+resources:
+ bugtracker: https://github.com/dagolden/path-tiny/issues
+ homepage: https://metacpan.org/release/Path-Tiny
+ repository: git://github.com/dagolden/path-tiny.git
- version: 0.026
++version: 0.027
+x_contributors:
+ - 'Chris Williams <bingos at cpan.org>'
+ - 'David Steinbrunner <dsteinbrunner at pobox.com>'
++ - 'Gabor Szabo <szabgab at cpan.org>'
+ - 'George Hartzell <hartzell at cpan.org>'
+ - 'Goro Fuji <gfuji at cpan.org>'
+ - 'Karen Etheridge <ether at cpan.org>'
+ - 'Keedi Kim <keedi at cpan.org>'
+ - 'Michael G. Schwern <mschwern at cpan.org>'
diff --cc Makefile.PL
index 725e493,0000000..9e9bf6f
mode 100644,000000..100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@@ -1,92 -1,0 +1,94 @@@
+
+use strict;
+use warnings;
+
+use 5.008001;
+
+use ExtUtils::MakeMaker 6.30;
+
+
+
+my %WriteMakefileArgs = (
+ "ABSTRACT" => "File path utility",
+ "AUTHOR" => "David Golden <dagolden\@cpan.org>",
+ "BUILD_REQUIRES" => {},
+ "CONFIGURE_REQUIRES" => {
+ "ExtUtils::MakeMaker" => "6.30"
+ },
+ "DISTNAME" => "Path-Tiny",
+ "EXE_FILES" => [],
+ "LICENSE" => "apache",
+ "NAME" => "Path::Tiny",
+ "PREREQ_PM" => {
+ "Carp" => 0,
+ "Cwd" => 0,
++ "Digest" => "1.03",
++ "Digest::SHA" => "5.45",
+ "Exporter" => "5.57",
+ "Fcntl" => 0,
+ "File::Copy" => 0,
+ "File::Path" => "2.07",
+ "File::Spec" => "3.40",
+ "File::Temp" => "0.18",
+ "File::stat" => 0,
+ "autodie::exception" => "2.14",
+ "constant" => 0,
+ "overload" => 0,
+ "strict" => 0,
+ "threads" => 0,
+ "warnings" => 0
+ },
+ "TEST_REQUIRES" => {
+ "Devel::Hide" => 0,
+ "ExtUtils::MakeMaker" => 0,
+ "File::Find" => 0,
+ "File::Spec::Functions" => 0,
+ "File::Spec::Unix" => 0,
+ "File::pushd" => 0,
+ "List::Util" => 0,
+ "Test::Deep" => 0,
+ "Test::FailWarnings" => 0,
+ "Test::Fatal" => 0,
+ "Test::More" => "0.96",
+ "open" => 0
+ },
- "VERSION" => "0.026",
++ "VERSION" => "0.027",
+ "test" => {
+ "TESTS" => "t/*.t"
+ }
+);
+
+
+unless ( eval { ExtUtils::MakeMaker->VERSION(6.63_03) } ) {
+ my $tr = delete $WriteMakefileArgs{TEST_REQUIRES};
+ my $br = $WriteMakefileArgs{BUILD_REQUIRES};
+ for my $mod ( keys %$tr ) {
+ if ( exists $br->{$mod} ) {
+ $br->{$mod} = $tr->{$mod} if $tr->{$mod} > $br->{$mod};
+ }
+ else {
+ $br->{$mod} = $tr->{$mod};
+ }
+ }
+}
+
+unless ( eval { ExtUtils::MakeMaker->VERSION(6.56) } ) {
+ my $br = delete $WriteMakefileArgs{BUILD_REQUIRES};
+ my $pp = $WriteMakefileArgs{PREREQ_PM};
+ for my $mod ( keys %$br ) {
+ if ( exists $pp->{$mod} ) {
+ $pp->{$mod} = $br->{$mod} if $br->{$mod} > $pp->{$mod};
+ }
+ else {
+ $pp->{$mod} = $br->{$mod};
+ }
+ }
+}
+
+delete $WriteMakefileArgs{CONFIGURE_REQUIRES}
+ unless eval { ExtUtils::MakeMaker->VERSION(6.52) };
+
+WriteMakefile(%WriteMakefileArgs);
+
+
+
diff --cc README
index 6e80be1,0000000..66e92df
mode 100644,000000..100644
--- a/README
+++ b/README
@@@ -1,545 -1,0 +1,563 @@@
+NAME
+ Path::Tiny - File path utility
+
+VERSION
- version 0.026
++ version 0.027
+
+SYNOPSIS
+ use Path::Tiny;
+
+ # creating Path::Tiny objects
+
+ $dir = path("/tmp");
+ $foo = path("foo.txt");
+
+ $subdir = $dir->child("foo");
+ $bar = $subdir->child("bar.txt");
+
+ # stringifies as cleaned up path
+
+ $file = path("./foo.txt");
+ print $file; # "foo.txt"
+
+ # reading files
+
+ $guts = $file->slurp;
+ $guts = $file->slurp_utf8;
+
+ @lines = $file->lines;
+ @lines = $file->lines_utf8;
+
+ $head = $file->lines( {count => 1} );
+
+ # writing files
+
+ $bar->spew( @data );
+ $bar->spew_utf8( @data );
+
+ # reading directories
+
+ for ( $dir->children ) { ... }
+
+ $iter = $dir->iterator;
+ while ( my $next = $iter->() ) { ... }
+
+DESCRIPTION
+ This module attempts to provide a small, fast utility for working with
+ file paths. It is friendlier to use than File::Spec and provides easy
+ access to functions from several other core file handling modules.
+
+ It doesn't attempt to be as full-featured as IO::All or Path::Class, nor
+ does it try to work for anything except Unix-like and Win32 platforms.
+ Even then, it might break if you try something particularly obscure or
+ tortuous. (Quick! What does this mean:
+ "///../../..//./././a//b/.././c/././"? And how does it differ on Win32?)
+
+ All paths are forced to have Unix-style forward slashes. Stringifying
+ the object gives you back the path (after some clean up).
+
+ File input/output methods "flock" handles before reading or writing, as
+ appropriate.
+
+ The *_utf8 methods ("slurp_utf8", "lines_utf8", etc.) operate in raw
+ mode without CRLF translation. Installing Unicode::UTF8 0.58 or later
+ will speed up several of them and is highly recommended.
+
+ It uses autodie internally, so most failures will be thrown as
+ exceptions.
+
+CONSTRUCTORS
+ path
+ $path = path("foo/bar");
+ $path = path("/tmp", "file.txt"); # list
+ $path = path("."); # cwd
+ $path = path("~user/file.txt"); # tilde processing
+
+ Constructs a "Path::Tiny" object. It doesn't matter if you give a file
+ or directory path. It's still up to you to call directory-like methods
+ only on directories and file-like methods only on files. This function
+ is exported automatically by default.
+
+ The first argument must be defined and have non-zero length or an
+ exception will be thrown. This prevents subtle, dangerous errors with
+ code like "path( maybe_undef() )->remove_tree".
+
+ If the first component of the path is a tilde ('~') then the component
+ will be replaced with the output of "glob('~')". If the first component
+ of the path is a tilde followed by a user name then the component will
+ be replaced with output of "glob('~username')". Behaviour for
+ non-existent users depends on the output of "glob" on the system.
+
+ new
+ $path = Path::Tiny->new("foo/bar");
+
+ This is just like "path", but with method call overhead. (Why would you
+ do that?)
+
+ cwd
+ $path = Path::Tiny->cwd; # path( Cwd::getcwd )
+ $path = cwd; # optional export
+
+ Gives you the absolute path to the current directory as a "Path::Tiny"
+ object. This is slightly faster than "path(".")->absolute".
+
+ "cwd" may be exported on request and used as a function instead of as a
+ method.
+
+ rootdir
+ $path = Path::Tiny->rootdir; # /
+ $path = rootdir; # optional export
+
+ Gives you "File::Spec->rootdir" as a "Path::Tiny" object if you're too
+ picky for "path("/")".
+
+ "rootdir" may be exported on request and used as a function instead of
+ as a method.
+
+ tempfile, tempdir
+ $temp = Path::Tiny->tempfile( @options );
+ $temp = Path::Tiny->tempdir( @options );
+ $temp = tempfile( @options ); # optional export
+ $temp = tempdir( @options ); # optional export
+
+ "tempfile" passes the options to "File::Temp->new" and returns a
+ "Path::Tiny" object with the file name. The "TMPDIR" option is enabled
+ by default.
+
+ The resulting "File::Temp" object is cached. When the "Path::Tiny"
+ object is destroyed, the "File::Temp" object will be as well.
+
+ "File::Temp" annoyingly requires you to specify a custom template in
+ slightly different ways depending on which function or method you call,
+ but "Path::Tiny" lets you ignore that and can take either a leading
+ template or a "TEMPLATE" option and does the right thing.
+
+ $temp = Path::Tiny->tempfile( "customXXXXXXXX" ); # ok
+ $temp = Path::Tiny->tempfile( TEMPLATE => "customXXXXXXXX" ); # ok
+
+ The tempfile path object will normalized to have an absolute path, even
+ if created in a relative directory using "DIR".
+
+ "tempdir" is just like "tempfile", except it calls "File::Temp->newdir"
+ instead.
+
+ Both "tempfile" and "tempdir" may be exported on request and used as
+ functions instead of as methods.
+
+METHODS
+ absolute
+ $abs = path("foo/bar")->absolute;
+ $abs = path("foo/bar")->absolute("/tmp");
+
+ Returns a new "Path::Tiny" object with an absolute path. Unless an
+ argument is given, the current directory is used as the absolute base
+ path. The argument must be absolute or you won't get an absolute result.
+
+ This will not resolve upward directories ("foo/../bar") unless
+ "canonpath" in File::Spec would normally do so on your platform. If you
+ need them resolved, you must call the more expensive "realpath" method
+ instead.
+
+ append, append_raw, append_utf8
+ path("foo.txt")->append(@data);
+ path("foo.txt")->append(\@data);
+ path("foo.txt")->append({binmode => ":raw"}, @data);
+ path("foo.txt")->append_raw(@data);
+ path("foo.txt")->append_utf8(@data);
+
+ Appends data to a file. The file is locked with "flock" prior to
+ writing. An optional hash reference may be used to pass options. The
+ only option is "binmode", which is passed to "binmode()" on the handle
+ used for writing.
+
+ "append_raw" is like "append" with a "binmode" of ":unix" for fast,
+ unbuffered, raw write.
+
+ "append_utf8" is like "append" with a "binmode" of
+ ":unix:encoding(UTF-8)". If Unicode::UTF8 0.58+ is installed, a raw
+ append will be done instead on the data encoded with "Unicode::UTF8".
+
+ basename
+ $name = path("foo/bar.txt")->basename; # bar.txt
+
+ Returns the file portion or last directory portion of a path.
+
+ canonpath
+ $canonical = path("foo/bar")->canonpath; # foo\bar on Windows
+
+ Returns a string with the canonical format of the path name for the
+ platform. In particular, this means directory separators will be "\" on
+ Windows.
+
+ child
+ $file = path("/tmp")->child("foo.txt"); # "/tmp/foo.txt"
+ $file = path("/tmp")->child(@parts);
+
+ Returns a new "Path::Tiny" object relative to the original. Works like
+ "catfile" or "catdir" from File::Spec, but without caring about file or
+ directories.
+
+ children
+ @paths = path("/tmp")->children;
+
+ Returns a list of "Path::Tiny" objects for all file and directories
+ within a directory. Excludes "." and ".." automatically.
+
+ copy
+ path("/tmp/foo.txt")->copy("/tmp/bar.txt");
+
+ Copies a file using File::Copy's "copy" function.
+
++ digest
++ $obj = path("/tmp/foo.txt")->digest; # SHA-256
++ $obj = path("/tmp/foo.txt")->digest("MD5"); # user-selected
++
++ Returns a hexadecimal digest for a file. Any arguments are passed to the
++ constructor for Digest to select an algorithm. If no arguments are
++ given, the default is SHA-256.
++
+ dirname
+ $name = path("/tmp/foo.txt")->dirname; # "/tmp/"
+
+ Returns the directory name portion of the path. This is roughly
+ equivalent to what File::Spec would give from "splitpath" and thus
+ usually has the trailing slash. If that's not desired, stringify
+ directories or call "parent" on files.
+
+ exists, is_file, is_dir
+ if ( path("/tmp")->exists ) { ... }
+ if ( path("/tmp")->is_file ) { ... }
+ if ( path("/tmp")->is_dir ) { ... }
+
+ Just like "-e", "-f" or "-d". This means the file or directory actually
+ has to exist on the filesystem. Until then, it's just a path.
+
+ filehandle
+ $fh = path("/tmp/foo.txt")->filehandle($mode, $binmode);
+
+ Returns an open file handle. The $mode argument must be a Perl-style
+ read/write mode string ("<" ,">", "<<", etc.). If a $binmode is given,
+ it is set during the "open" call.
+
+ See "openr", "openw", "openrw", and "opena" for sugar.
+
+ is_absolute, is_relative
+ if ( path("/tmp")->is_absolute ) { ... }
+ if ( path("/tmp")->is_relative ) { ... }
+
+ Booleans for whether the path appears absolute or relative.
+
+ iterator
+ $iter = path("/tmp")->iterator( \%options );
+
+ Returns a code reference that walks a directory lazily. Each invocation
+ returns a "Path::Tiny" object or undef when the iterator is exhausted.
+
+ $iter = path("/tmp")->iterator;
+ while ( $path = $iter->() ) {
+ ...
+ }
+
+ The current and parent directory entries ("." and "..") will not be
+ included.
+
+ If the "recurse" option is true, the iterator will walk the directory
+ recursively, breadth-first. If the "follow_symlinks" option is also
+ true, directory links will be followed recursively. There is no
+ protection against loops when following links.
+
+ For a more powerful, recursive iterator with built-in loop avoidance,
+ see Path::Iterator::Rule.
+
+ lines, lines_raw, lines_utf8
+ @contents = path("/tmp/foo.txt")->lines;
+ @contents = path("/tmp/foo.txt")->lines(\%options);
+ @contents = path("/tmp/foo.txt")->lines_raw;
+ @contents = path("/tmp/foo.txt")->lines_utf8;
+
++ @contents = path("/tmp/foo.txt")->lines( { chomp => 1, count => 4 } );
++
+ Returns a list of lines from a file. Optionally takes a hash-reference
+ of options. Valid options are "binmode", "count" and "chomp". If
+ "binmode" is provided, it will be set on the handle prior to reading. If
+ "count" is provided, up to that many lines will be returned. If "chomp"
+ is set, lines will be chomped before being returned.
+
+ Because the return is a list, "lines" in scalar context will return the
+ number of lines (and throw away the data).
+
+ $number_of_lines = path("/tmp/foo.txt")->lines;
+
+ "lines_raw" is like "lines" with a "binmode" of ":raw". We use ":raw"
+ instead of ":unix" so PerlIO buffering can manage reading by line.
+
+ "lines_utf8" is like "lines" with a "binmode" of ":raw:encoding(UTF-8)".
+ If Unicode::UTF8 0.58+ is installed, a raw UTF-8 slurp will be done and
+ then the lines will be split. This is actually faster than relying on
+ ":encoding(UTF-8)", though a bit memory intensive. If memory use is a
+ concern, consider "openr_utf8" and iterating directly on the handle.
+
+ mkpath
+ path("foo/bar/baz")->mkpath;
+ path("foo/bar/baz")->mkpath( \%options );
+
+ Like calling "make_path" from File::Path. An optional hash reference is
+ passed through to "make_path". Errors will be trapped and an exception
+ thrown. Returns the list of directories created or an empty list if the
+ directories already exist, just like "make_path".
+
+ move
+ path("foo.txt")->move("bar.txt");
+
+ Just like "rename".
+
+ openr, openw, openrw, opena
+ $fh = path("foo.txt")->openr($binmode); # read
+ $fh = path("foo.txt")->openr_raw;
+ $fh = path("foo.txt")->openr_utf8;
+
+ $fh = path("foo.txt")->openw($binmode); # write
+ $fh = path("foo.txt")->openw_raw;
+ $fh = path("foo.txt")->openw_utf8;
+
+ $fh = path("foo.txt")->opena($binmode); # append
+ $fh = path("foo.txt")->opena_raw;
+ $fh = path("foo.txt")->opena_utf8;
+
+ $fh = path("foo.txt")->openrw($binmode); # read/write
+ $fh = path("foo.txt")->openrw_raw;
+ $fh = path("foo.txt")->openrw_utf8;
+
+ Returns a file handle opened in the specified mode. The "openr" style
+ methods take a single "binmode" argument. All of the "open*" methods
+ have "open*_raw" and "open*_utf8" equivalents that use ":raw" and
+ ":raw:encoding(UTF-8)", respectively.
+
+ parent
+ $parent = path("foo/bar/baz")->parent; # foo/bar
+ $parent = path("foo/wibble.txt")->parent; # foo
+
+ $parent = path("foo/bar/baz")->parent(2); # foo
+
+ Returns a "Path::Tiny" object corresponding to the parent directory of
+ the original directory or file. An optional positive integer argument is
+ the number of parent directories upwards to return. "parent" by itself
+ is equivalent to parent(1).
+
+ realpath
+ $real = path("/baz/foo/../bar")->realpath;
+ $real = path("foo/../bar")->realpath;
+
+ Returns a new "Path::Tiny" object with all symbolic links and upward
+ directory parts resolved using Cwd's "realpath". Compared to "absolute",
+ this is more expensive as it must actually consult the filesystem.
+
+ relative
+ $rel = path("/tmp/foo/bar")->relative("/tmp"); # foo/bar
+
+ Returns a "Path::Tiny" object with a relative path name. Given the
+ trickiness of this, it's a thin wrapper around "File::Spec->abs2rel()".
+
+ remove
+ path("foo.txt")->remove;
+
+ Note: as of 0.012, remove only works on files.
+
+ This is just like "unlink", except if the path does not exist, it
+ returns false rather than throwing an exception.
+
+ remove_tree
+ # directory
+ path("foo/bar/baz")->remove_tree;
+ path("foo/bar/baz")->remove_tree( \%options );
+ path("foo/bar/baz")->remove_tree( { safe => 0 } ); # force remove
+
+ Like calling "remove_tree" from File::Path, but defaults to "safe" mode.
+ An optional hash reference is passed through to "remove_tree". Errors
+ will be trapped and an exception thrown. Returns the number of
+ directories deleted, just like "remove_tree".
+
+ If you want to remove a directory only if it is empty, use the built-in
+ "rmdir" function instead.
+
+ rmdir path("foo/bar/baz/");
+
+ slurp, slurp_raw, slurp_utf8
+ $data = path("foo.txt")->slurp;
+ $data = path("foo.txt")->slurp( {binmode => ":raw"} );
+ $data = path("foo.txt")->slurp_raw;
+ $data = path("foo.txt")->slurp_utf8;
+
+ Reads file contents into a scalar. Takes an optional hash reference may
+ be used to pass options. The only option is "binmode", which is passed
+ to "binmode()" on the handle used for reading.
+
+ "slurp_raw" is like "slurp" with a "binmode" of ":unix" for a fast,
+ unbuffered, raw read.
+
+ "slurp_utf8" is like "slurp" with a "binmode" of
+ ":unix:encoding(UTF-8)". If Unicode::UTF8 0.58+ is installed, a raw
+ slurp will be done instead and the result decoded with "Unicode::UTF8".
+ This is just as strict and is roughly an order of magnitude faster than
+ using ":encoding(UTF-8)".
+
+ spew, spew_raw, spew_utf8
+ path("foo.txt")->spew(@data);
+ path("foo.txt")->spew(\@data);
+ path("foo.txt")->spew({binmode => ":raw"}, @data);
+ path("foo.txt")->spew_raw(@data);
+ path("foo.txt")->spew_utf8(@data);
+
+ Writes data to a file atomically. The file is written to a temporary
+ file in the same directory, then renamed over the original. An optional
+ hash reference may be used to pass options. The only option is
+ "binmode", which is passed to "binmode()" on the handle used for
+ writing.
+
+ "spew_raw" is like "spew" with a "binmode" of ":unix" for a fast,
+ unbuffered, raw write.
+
+ "spew_utf8" is like "spew" with a "binmode" of ":unix:encoding(UTF-8)".
+ If Unicode::UTF8 0.58+ is installed, a raw spew will be done instead on
+ the data encoded with "Unicode::UTF8".
+
+ stat, lstat
+ $stat = path("foo.txt")->stat;
+ $stat = path("/some/symlink")->lstat;
+
+ Like calling "stat" or "lstat" from File::stat.
+
+ stringify
+ $path = path("foo.txt");
+ say $path->stringify; # same as "$path"
+
+ Returns a string representation of the path. Unlike "canonpath", this
+ method returns the path standardized with Unix-style "/" directory
+ separators.
+
+ touch
+ path("foo.txt")->touch;
+ path("foo.txt")->touch($epoch_secs);
+
+ Like the Unix "touch" utility. Creates the file if it doesn't exist, or
+ else changes the modification and access times to the current time. If
+ the first argument is the epoch seconds then it will be used.
+
+ Returns the path object so it can be easily chained with spew:
+
+ path("foo.txt")->touch->spew( $content );
+
+ touchpath
+ path("bar/baz/foo.txt")->touchpath;
+
+ Combines "mkpath" and "touch". Creates the parent directory if it
+ doesn't exist, before touching the file. Returns the path object like
+ "touch" does.
+
+ volume
+ $vol = path("/tmp/foo.txt")->volume;
+
+ Returns the volume portion of the path. This is equivalent equivalent to
+ what File::Spec would give from "splitpath" and thus usually is the
+ empty string on Unix-like operating systems.
+
+CAVEATS
+ utf8 vs UTF-8
+ All the *_utf8 methods use ":encoding(UTF-8)" -- either as
+ ":unix:encoding(UTF-8)" (unbuffered) or ":raw:encoding(UTF-8)"
+ (buffered) -- which is strict against the Unicode spec and disallows
+ illegal Unicode codepoints or UTF-8 sequences.
+
+ Unfortunately, ":encoding(UTF-8)" is very, very slow. If you install
+ Unicode::UTF8 0.58 or later, that module will be used by some *_utf8
+ methods to encode or decode data after a raw, binary input/output
+ operation, which is much faster.
+
+ If you need the performance and can accept the security risk,
+ "slurp({binmode => ":unix:utf8"})" will be faster than
+ ":unix:encoding(UTF-8)" (but not as fast as "Unicode::UTF8").
+
+ Note that the *_utf8 methods read in raw mode. There is no CRLF
+ translation on Windows. If you must have CRLF translation, use the
+ regular input/output methods with an appropriate binmode:
+
+ $path->spew_utf8($data); # raw
+ $path->spew({binmode => ":encoding(UTF-8)"}, $data; # LF -> CRLF
+
+ Consider PerlIO::utf8_strict for a faster PerlIO layer alternative to
+ ":encoding(UTF-8)", though it does not appear to be as fast as the
+ "Unicode::UTF8" approach.
+
+ Default IO layers and the open pragma
+ If you have Perl 5.10 or later, file input/output methods ("slurp",
+ "spew", etc.) and high-level handle opening methods ( "openr", "openw",
+ etc. but not "filehandle") respect default encodings set by the "-C"
+ switch or lexical open settings of the caller. For UTF-8, this is almost
+ certainly slower than using the dedicated "_utf8" methods if you have
+ Unicode::UTF8.
+
+TYPE CONSTRAINTS AND COERCION
+ A standard MooseX::Types library is available at
+ MooseX::Types::Path::Tiny.
+
+SEE ALSO
+ These are other file/path utilities, which may offer a different feature
+ set than "Path::Tiny".
+
- * File::Fu * IO::All * Path::Class
++ * File::Fu
++
++ * IO::All
++
++ * Path::Class
+
+ These iterators may be slightly faster than the recursive iterator in
+ "Path::Tiny":
+
- * Path::Iterator::Rule * File::Next
++ * Path::Iterator::Rule
++
++ * File::Next
+
+ There are probably comparable, non-Tiny tools. Let me know if you want
+ me to add a module to the list.
+
+SUPPORT
+ Bugs / Feature Requests
+ Please report any bugs or feature requests through the issue tracker at
+ <https://github.com/dagolden/path-tiny/issues>. You will be notified
+ automatically of any progress on your issue.
+
+ Source Code
+ This is open source software. The code repository is available for
+ public review and contribution under the terms of the license.
+
+ <https://github.com/dagolden/path-tiny>
+
+ git clone git://github.com/dagolden/path-tiny.git
+
+AUTHOR
+ David Golden <dagolden at cpan.org>
+
+CONTRIBUTORS
+ * Chris Williams <bingos at cpan.org>
+
+ * David Steinbrunner <dsteinbrunner at pobox.com>
+
++ * Gabor Szabo <szabgab at cpan.org>
++
+ * George Hartzell <hartzell at cpan.org>
+
+ * Goro Fuji <gfuji at cpan.org>
+
+ * Karen Etheridge <ether at cpan.org>
+
+ * Keedi Kim <keedi at cpan.org>
+
+ * Michael G. Schwern <mschwern at cpan.org>
+
+COPYRIGHT AND LICENSE
+ This software is Copyright (c) 2013 by David Golden.
+
+ This is free software, licensed under:
+
+ The Apache License, Version 2.0, January 2004
+
diff --cc lib/Path/Tiny.pm
index 975a989,5b83034..74f387f
--- a/lib/Path/Tiny.pm
+++ b/lib/Path/Tiny.pm
@@@ -4,7 -4,7 +4,7 @@@ use warnings
package Path::Tiny;
# ABSTRACT: File path utility
- our $VERSION = '0.026'; # VERSION
-# VERSION
++our $VERSION = '0.027'; # VERSION
# Dependencies
use autodie::exception 2.14; # autodie::skip support
@@@ -242,7 -403,35 +242,15 @@@ sub copy
or Carp::croak("copy failed for $self to $dest: $!");
}
-=method digest
-
- $obj = path("/tmp/foo.txt")->digest; # SHA-256
- $obj = path("/tmp/foo.txt")->digest("MD5"); # user-selected
-
-Returns a hexadecimal digest for a file. Any arguments are passed to the
-constructor for L<Digest> to select an algorithm. If no arguments are given,
-the default is SHA-256.
-
-=cut
+ sub digest {
+ my ($self, $alg, @args) = @_;
+ $alg = 'SHA-256' unless defined $alg;
+ require Digest;
+ return Digest->new($alg, @args)->add( $self->slurp_raw )->hexdigest;
+ }
+
-=method dirname
-
- $name = path("/tmp/foo.txt")->dirname; # "/tmp/"
-
-Returns the directory name portion of the path. This is roughly
-equivalent to what L<File::Spec> would give from C<splitpath> and thus
-usually has the trailing slash. If that's not desired, stringify directories
-or call C<parent> on files.
-
-=cut
+
sub dirname {
my ($self) = @_;
$self->_splitpath unless defined $self->[DIR];
@@@ -604,22 -1069,10 +612,22 @@@ sub volume
1;
-=for Pod::Coverage
-openr_utf8 opena_utf8 openw_utf8 openrw_utf8
-openr_raw opena_raw openw_raw openrw_raw
-DOES
+
+# vim: ts=4 sts=4 sw=4 et:
+
+__END__
+
+=pod
+
+=encoding utf-8
+
+=head1 NAME
+
+Path::Tiny - File path utility
+
+=head1 VERSION
+
- version 0.026
++version 0.027
=head1 SYNOPSIS
@@@ -684,549 -1137,68 +692,585 @@@ will speed up several of them and is hi
It uses L<autodie> internally, so most failures will be thrown as exceptions.
-=head1 CAVEATS
+=head1 CONSTRUCTORS
-=head2 utf8 vs UTF-8
+=head2 path
-All the C<*_utf8> methods use C<:encoding(UTF-8)> -- either as
-C<:unix:encoding(UTF-8)> (unbuffered) or C<:raw:encoding(UTF-8)> (buffered) --
-which is strict against the Unicode spec and disallows illegal Unicode
-codepoints or UTF-8 sequences.
+ $path = path("foo/bar");
+ $path = path("/tmp", "file.txt"); # list
+ $path = path("."); # cwd
+ $path = path("~user/file.txt"); # tilde processing
-Unfortunately, C<:encoding(UTF-8)> is very, very slow. If you install
-L<Unicode::UTF8> 0.58 or later, that module will be used by some C<*_utf8>
-methods to encode or decode data after a raw, binary input/output operation,
-which is much faster.
+Constructs a C<Path::Tiny> object. It doesn't matter if you give a file or
+directory path. It's still up to you to call directory-like methods only on
+directories and file-like methods only on files. This function is exported
+automatically by default.
-If you need the performance and can accept the security risk,
-C<< slurp({binmode => ":unix:utf8"}) >> will be faster than C<:unix:encoding(UTF-8)>
-(but not as fast as C<Unicode::UTF8>).
+The first argument must be defined and have non-zero length or an exception
+will be thrown. This prevents subtle, dangerous errors with code like
+C<< path( maybe_undef() )->remove_tree >>.
-Note that the C<*_utf8> methods read in B<raw> mode. There is no CRLF
-translation on Windows. If you must have CRLF translation, use the regular
-input/output methods with an appropriate binmode:
+If the first component of the path is a tilde ('~') then the component will be
+replaced with the output of C<glob('~')>. If the first component of the path
+is a tilde followed by a user name then the component will be replaced with
+output of C<glob('~username')>. Behaviour for non-existent users depends on
+the output of C<glob> on the system.
- $path->spew_utf8($data); # raw
- $path->spew({binmode => ":encoding(UTF-8)"}, $data; # LF -> CRLF
+=head2 new
-Consider L<PerlIO::utf8_strict> for a faster L<PerlIO> layer alternative to
-C<:encoding(UTF-8)>, though it does not appear to be as fast as the
-C<Unicode::UTF8> approach.
+ $path = Path::Tiny->new("foo/bar");
-=head2 Default IO layers and the open pragma
+This is just like C<path>, but with method call overhead. (Why would you
+do that?)
-If you have Perl 5.10 or later, file input/output methods (C<slurp>, C<spew>,
-etc.) and high-level handle opening methods ( C<openr>, C<openw>, etc. but not
-C<filehandle>) respect default encodings set by the C<-C> switch or lexical
-L<open> settings of the caller. For UTF-8, this is almost certainly slower
-than using the dedicated C<_utf8> methods if you have L<Unicode::UTF8>.
+=head2 cwd
-=head1 TYPE CONSTRAINTS AND COERCION
+ $path = Path::Tiny->cwd; # path( Cwd::getcwd )
+ $path = cwd; # optional export
-A standard L<MooseX::Types> library is available at
-L<MooseX::Types::Path::Tiny>.
+Gives you the absolute path to the current directory as a C<Path::Tiny> object.
+This is slightly faster than C<< path(".")->absolute >>.
-=head1 SEE ALSO
+C<cwd> may be exported on request and used as a function instead of as a
+method.
-These are other file/path utilities, which may offer a different feature
-set than C<Path::Tiny>.
+=head2 rootdir
-=for :list
-* L<File::Fu>
-* L<IO::All>
-* L<Path::Class>
+ $path = Path::Tiny->rootdir; # /
+ $path = rootdir; # optional export
-These iterators may be slightly faster than the recursive iterator in
-C<Path::Tiny>:
+Gives you C<< File::Spec->rootdir >> as a C<Path::Tiny> object if you're too
+picky for C<path("/")>.
-=for :list
-* L<Path::Iterator::Rule>
-* L<File::Next>
+C<rootdir> may be exported on request and used as a function instead of as a
+method.
-There are probably comparable, non-Tiny tools. Let me know if you want me to
-add a module to the list.
+=head2 tempfile, tempdir
-=cut
+ $temp = Path::Tiny->tempfile( @options );
+ $temp = Path::Tiny->tempdir( @options );
+ $temp = tempfile( @options ); # optional export
+ $temp = tempdir( @options ); # optional export
-# vim: ts=4 sts=4 sw=4 et:
+C<tempfile> passes the options to C<< File::Temp->new >> and returns a C<Path::Tiny>
+object with the file name. The C<TMPDIR> option is enabled by default.
+
+The resulting C<File::Temp> object is cached. When the C<Path::Tiny> object is
+destroyed, the C<File::Temp> object will be as well.
+
+C<File::Temp> annoyingly requires you to specify a custom template in slightly
+different ways depending on which function or method you call, but
+C<Path::Tiny> lets you ignore that and can take either a leading template or a
+C<TEMPLATE> option and does the right thing.
+
+ $temp = Path::Tiny->tempfile( "customXXXXXXXX" ); # ok
+ $temp = Path::Tiny->tempfile( TEMPLATE => "customXXXXXXXX" ); # ok
+
+The tempfile path object will normalized to have an absolute path, even if
+created in a relative directory using C<DIR>.
+
+C<tempdir> is just like C<tempfile>, except it calls
+C<< File::Temp->newdir >> instead.
+
+Both C<tempfile> and C<tempdir> may be exported on request and used as
+functions instead of as methods.
+
+=head1 METHODS
+
+=head2 absolute
+
+ $abs = path("foo/bar")->absolute;
+ $abs = path("foo/bar")->absolute("/tmp");
+
+Returns a new C<Path::Tiny> object with an absolute path. Unless
+an argument is given, the current directory is used as the absolute base path.
+The argument must be absolute or you won't get an absolute result.
+
+This will not resolve upward directories ("foo/../bar") unless C<canonpath>
+in L<File::Spec> would normally do so on your platform. If you need them
+resolved, you must call the more expensive C<realpath> method instead.
+
+=head2 append, append_raw, append_utf8
+
+ path("foo.txt")->append(@data);
+ path("foo.txt")->append(\@data);
+ path("foo.txt")->append({binmode => ":raw"}, @data);
+ path("foo.txt")->append_raw(@data);
+ path("foo.txt")->append_utf8(@data);
+
+Appends data to a file. The file is locked with C<flock> prior to writing. An
+optional hash reference may be used to pass options. The only option is
+C<binmode>, which is passed to C<binmode()> on the handle used for writing.
+
+C<append_raw> is like C<append> with a C<binmode> of C<:unix> for fast,
+unbuffered, raw write.
+
+C<append_utf8> is like C<append> with a C<binmode> of
+C<:unix:encoding(UTF-8)>. If L<Unicode::UTF8> 0.58+ is installed, a raw
+append will be done instead on the data encoded with C<Unicode::UTF8>.
+
+=head2 basename
+
+ $name = path("foo/bar.txt")->basename; # bar.txt
+
+Returns the file portion or last directory portion of a path.
+
+=head2 canonpath
+
+ $canonical = path("foo/bar")->canonpath; # foo\bar on Windows
+
+Returns a string with the canonical format of the path name for
+the platform. In particular, this means directory separators
+will be C<\> on Windows.
+
+=head2 child
+
+ $file = path("/tmp")->child("foo.txt"); # "/tmp/foo.txt"
+ $file = path("/tmp")->child(@parts);
+
+Returns a new C<Path::Tiny> object relative to the original. Works
+like C<catfile> or C<catdir> from File::Spec, but without caring about
+file or directories.
+
+=head2 children
+
+ @paths = path("/tmp")->children;
+
+Returns a list of C<Path::Tiny> objects for all file and directories
+within a directory. Excludes "." and ".." automatically.
+
+=head2 copy
+
+ path("/tmp/foo.txt")->copy("/tmp/bar.txt");
+
+Copies a file using L<File::Copy>'s C<copy> function.
+
++=head2 digest
++
++ $obj = path("/tmp/foo.txt")->digest; # SHA-256
++ $obj = path("/tmp/foo.txt")->digest("MD5"); # user-selected
++
++Returns a hexadecimal digest for a file. Any arguments are passed to the
++constructor for L<Digest> to select an algorithm. If no arguments are given,
++the default is SHA-256.
++
+=head2 dirname
+
+ $name = path("/tmp/foo.txt")->dirname; # "/tmp/"
+
+Returns the directory name portion of the path. This is roughly
+equivalent to what L<File::Spec> would give from C<splitpath> and thus
+usually has the trailing slash. If that's not desired, stringify directories
+or call C<parent> on files.
+
+=head2 exists, is_file, is_dir
+
+ if ( path("/tmp")->exists ) { ... }
+ if ( path("/tmp")->is_file ) { ... }
+ if ( path("/tmp")->is_dir ) { ... }
+
+Just like C<-e>, C<-f> or C<-d>. This means the file or directory actually has to
+exist on the filesystem. Until then, it's just a path.
+
+=head2 filehandle
+
+ $fh = path("/tmp/foo.txt")->filehandle($mode, $binmode);
+
+Returns an open file handle. The C<$mode> argument must be a Perl-style
+read/write mode string ("<" ,">", "<<", etc.). If a C<$binmode>
+is given, it is set during the C<open> call.
+
+See C<openr>, C<openw>, C<openrw>, and C<opena> for sugar.
+
+=head2 is_absolute, is_relative
+
+ if ( path("/tmp")->is_absolute ) { ... }
+ if ( path("/tmp")->is_relative ) { ... }
+
+Booleans for whether the path appears absolute or relative.
+
+=head2 iterator
+
+ $iter = path("/tmp")->iterator( \%options );
+
+Returns a code reference that walks a directory lazily. Each invocation
+returns a C<Path::Tiny> object or undef when the iterator is exhausted.
+
+ $iter = path("/tmp")->iterator;
+ while ( $path = $iter->() ) {
+ ...
+ }
+
+The current and parent directory entries ("." and "..") will not
+be included.
+
+If the C<recurse> option is true, the iterator will walk the directory
+recursively, breadth-first. If the C<follow_symlinks> option is also true,
+directory links will be followed recursively. There is no protection against
+loops when following links.
+
+For a more powerful, recursive iterator with built-in loop avoidance, see
+L<Path::Iterator::Rule>.
+
+=head2 lines, lines_raw, lines_utf8
+
+ @contents = path("/tmp/foo.txt")->lines;
+ @contents = path("/tmp/foo.txt")->lines(\%options);
+ @contents = path("/tmp/foo.txt")->lines_raw;
+ @contents = path("/tmp/foo.txt")->lines_utf8;
+
++ @contents = path("/tmp/foo.txt")->lines( { chomp => 1, count => 4 } );
++
+Returns a list of lines from a file. Optionally takes a hash-reference of
+options. Valid options are C<binmode>, C<count> and C<chomp>. If C<binmode>
+is provided, it will be set on the handle prior to reading. If C<count> is
+provided, up to that many lines will be returned. If C<chomp> is set, lines
+will be chomped before being returned.
+
+Because the return is a list, C<lines> in scalar context will return the number
+of lines (and throw away the data).
+
+ $number_of_lines = path("/tmp/foo.txt")->lines;
+
+C<lines_raw> is like C<lines> with a C<binmode> of C<:raw>. We use C<:raw>
+instead of C<:unix> so PerlIO buffering can manage reading by line.
+
+C<lines_utf8> is like C<lines> with a C<binmode> of
+C<:raw:encoding(UTF-8)>. If L<Unicode::UTF8> 0.58+ is installed, a raw
+UTF-8 slurp will be done and then the lines will be split. This is
+actually faster than relying on C<:encoding(UTF-8)>, though a bit memory
+intensive. If memory use is a concern, consider C<openr_utf8> and
+iterating directly on the handle.
+
+=head2 mkpath
+
+ path("foo/bar/baz")->mkpath;
+ path("foo/bar/baz")->mkpath( \%options );
+
+Like calling C<make_path> from L<File::Path>. An optional hash reference
+is passed through to C<make_path>. Errors will be trapped and an exception
+thrown. Returns the list of directories created or an empty list if
+the directories already exist, just like C<make_path>.
+
+=head2 move
+
+ path("foo.txt")->move("bar.txt");
+
+Just like C<rename>.
+
+=head2 openr, openw, openrw, opena
+
+ $fh = path("foo.txt")->openr($binmode); # read
+ $fh = path("foo.txt")->openr_raw;
+ $fh = path("foo.txt")->openr_utf8;
+
+ $fh = path("foo.txt")->openw($binmode); # write
+ $fh = path("foo.txt")->openw_raw;
+ $fh = path("foo.txt")->openw_utf8;
+
+ $fh = path("foo.txt")->opena($binmode); # append
+ $fh = path("foo.txt")->opena_raw;
+ $fh = path("foo.txt")->opena_utf8;
+
+ $fh = path("foo.txt")->openrw($binmode); # read/write
+ $fh = path("foo.txt")->openrw_raw;
+ $fh = path("foo.txt")->openrw_utf8;
+
+Returns a file handle opened in the specified mode. The C<openr> style methods
+take a single C<binmode> argument. All of the C<open*> methods have
+C<open*_raw> and C<open*_utf8> equivalents that use C<:raw> and
+C<:raw:encoding(UTF-8)>, respectively.
+
+=head2 parent
+
+ $parent = path("foo/bar/baz")->parent; # foo/bar
+ $parent = path("foo/wibble.txt")->parent; # foo
+
+ $parent = path("foo/bar/baz")->parent(2); # foo
+
+Returns a C<Path::Tiny> object corresponding to the parent directory of the
+original directory or file. An optional positive integer argument is the number
+of parent directories upwards to return. C<parent> by itself is equivalent to
+C<parent(1)>.
+
+=head2 realpath
+
+ $real = path("/baz/foo/../bar")->realpath;
+ $real = path("foo/../bar")->realpath;
+
+Returns a new C<Path::Tiny> object with all symbolic links and upward directory
+parts resolved using L<Cwd>'s C<realpath>. Compared to C<absolute>, this is
+more expensive as it must actually consult the filesystem.
+
+=head2 relative
+
+ $rel = path("/tmp/foo/bar")->relative("/tmp"); # foo/bar
+
+Returns a C<Path::Tiny> object with a relative path name.
+Given the trickiness of this, it's a thin wrapper around
+C<< File::Spec->abs2rel() >>.
+
+=head2 remove
+
+ path("foo.txt")->remove;
+
+B<Note: as of 0.012, remove only works on files>.
+
+This is just like C<unlink>, except if the path does not exist, it returns
+false rather than throwing an exception.
+
+=head2 remove_tree
+
+ # directory
+ path("foo/bar/baz")->remove_tree;
+ path("foo/bar/baz")->remove_tree( \%options );
+ path("foo/bar/baz")->remove_tree( { safe => 0 } ); # force remove
+
+Like calling C<remove_tree> from L<File::Path>, but defaults to C<safe> mode.
+An optional hash reference is passed through to C<remove_tree>. Errors will be
+trapped and an exception thrown. Returns the number of directories deleted,
+just like C<remove_tree>.
+
+If you want to remove a directory only if it is empty, use the built-in
+C<rmdir> function instead.
+
+ rmdir path("foo/bar/baz/");
+
+=head2 slurp, slurp_raw, slurp_utf8
+
+ $data = path("foo.txt")->slurp;
+ $data = path("foo.txt")->slurp( {binmode => ":raw"} );
+ $data = path("foo.txt")->slurp_raw;
+ $data = path("foo.txt")->slurp_utf8;
+
+Reads file contents into a scalar. Takes an optional hash reference may be
+used to pass options. The only option is C<binmode>, which is passed to
+C<binmode()> on the handle used for reading.
+
+C<slurp_raw> is like C<slurp> with a C<binmode> of C<:unix> for
+a fast, unbuffered, raw read.
+
+C<slurp_utf8> is like C<slurp> with a C<binmode> of
+C<:unix:encoding(UTF-8)>. If L<Unicode::UTF8> 0.58+ is installed, a raw
+slurp will be done instead and the result decoded with C<Unicode::UTF8>.
+This is just as strict and is roughly an order of magnitude faster than
+using C<:encoding(UTF-8)>.
+
+=head2 spew, spew_raw, spew_utf8
+
+ path("foo.txt")->spew(@data);
+ path("foo.txt")->spew(\@data);
+ path("foo.txt")->spew({binmode => ":raw"}, @data);
+ path("foo.txt")->spew_raw(@data);
+ path("foo.txt")->spew_utf8(@data);
+
+Writes data to a file atomically. The file is written to a temporary file in
+the same directory, then renamed over the original. An optional hash reference
+may be used to pass options. The only option is C<binmode>, which is passed to
+C<binmode()> on the handle used for writing.
+
+C<spew_raw> is like C<spew> with a C<binmode> of C<:unix> for a fast,
+unbuffered, raw write.
+
+C<spew_utf8> is like C<spew> with a C<binmode> of C<:unix:encoding(UTF-8)>.
+If L<Unicode::UTF8> 0.58+ is installed, a raw spew will be done instead on
+the data encoded with C<Unicode::UTF8>.
+
+=head2 stat, lstat
+
+ $stat = path("foo.txt")->stat;
+ $stat = path("/some/symlink")->lstat;
+
+Like calling C<stat> or C<lstat> from L<File::stat>.
+
+=head2 stringify
+
+ $path = path("foo.txt");
+ say $path->stringify; # same as "$path"
+
+Returns a string representation of the path. Unlike C<canonpath>, this method
+returns the path standardized with Unix-style C</> directory separators.
+
+=head2 touch
+
+ path("foo.txt")->touch;
+ path("foo.txt")->touch($epoch_secs);
+
+Like the Unix C<touch> utility. Creates the file if it doesn't exist, or else
+changes the modification and access times to the current time. If the first
+argument is the epoch seconds then it will be used.
+
+Returns the path object so it can be easily chained with spew:
+
+ path("foo.txt")->touch->spew( $content );
+
+=head2 touchpath
+
+ path("bar/baz/foo.txt")->touchpath;
+
+Combines C<mkpath> and C<touch>. Creates the parent directory if it doesn't exist,
+before touching the file. Returns the path object like C<touch> does.
+
+=head2 volume
+
+ $vol = path("/tmp/foo.txt")->volume;
+
+Returns the volume portion of the path. This is equivalent
+equivalent to what L<File::Spec> would give from C<splitpath> and thus
+usually is the empty string on Unix-like operating systems.
+
+=for Pod::Coverage openr_utf8 opena_utf8 openw_utf8 openrw_utf8
+openr_raw opena_raw openw_raw openrw_raw
+DOES
+
+=head1 CAVEATS
+
+=head2 utf8 vs UTF-8
+
+All the C<*_utf8> methods use C<:encoding(UTF-8)> -- either as
+C<:unix:encoding(UTF-8)> (unbuffered) or C<:raw:encoding(UTF-8)> (buffered) --
+which is strict against the Unicode spec and disallows illegal Unicode
+codepoints or UTF-8 sequences.
+
+Unfortunately, C<:encoding(UTF-8)> is very, very slow. If you install
+L<Unicode::UTF8> 0.58 or later, that module will be used by some C<*_utf8>
+methods to encode or decode data after a raw, binary input/output operation,
+which is much faster.
+
+If you need the performance and can accept the security risk,
+C<< slurp({binmode => ":unix:utf8"}) >> will be faster than C<:unix:encoding(UTF-8)>
+(but not as fast as C<Unicode::UTF8>).
+
+Note that the C<*_utf8> methods read in B<raw> mode. There is no CRLF
+translation on Windows. If you must have CRLF translation, use the regular
+input/output methods with an appropriate binmode:
+
+ $path->spew_utf8($data); # raw
+ $path->spew({binmode => ":encoding(UTF-8)"}, $data; # LF -> CRLF
+
+Consider L<PerlIO::utf8_strict> for a faster L<PerlIO> layer alternative to
+C<:encoding(UTF-8)>, though it does not appear to be as fast as the
+C<Unicode::UTF8> approach.
+
+=head2 Default IO layers and the open pragma
+
+If you have Perl 5.10 or later, file input/output methods (C<slurp>, C<spew>,
+etc.) and high-level handle opening methods ( C<openr>, C<openw>, etc. but not
+C<filehandle>) respect default encodings set by the C<-C> switch or lexical
+L<open> settings of the caller. For UTF-8, this is almost certainly slower
+than using the dedicated C<_utf8> methods if you have L<Unicode::UTF8>.
+
+=head1 TYPE CONSTRAINTS AND COERCION
+
+A standard L<MooseX::Types> library is available at
+L<MooseX::Types::Path::Tiny>.
+
+=head1 SEE ALSO
+
+These are other file/path utilities, which may offer a different feature
+set than C<Path::Tiny>.
+
- * L<File::Fu>
- * L<IO::All>
- * L<Path::Class>
++=over 4
++
++=item *
++
++L<File::Fu>
++
++=item *
++
++L<IO::All>
++
++=item *
++
++L<Path::Class>
++
++=back
+
+These iterators may be slightly faster than the recursive iterator in
+C<Path::Tiny>:
+
- * L<Path::Iterator::Rule>
- * L<File::Next>
++=over 4
++
++=item *
++
++L<Path::Iterator::Rule>
++
++=item *
++
++L<File::Next>
++
++=back
+
+There are probably comparable, non-Tiny tools. Let me know if you want me to
+add a module to the list.
+
+=for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan
+
+=head1 SUPPORT
+
+=head2 Bugs / Feature Requests
+
+Please report any bugs or feature requests through the issue tracker
+at L<https://github.com/dagolden/path-tiny/issues>.
+You will be notified automatically of any progress on your issue.
+
+=head2 Source Code
+
+This is open source software. The code repository is available for
+public review and contribution under the terms of the license.
+
+L<https://github.com/dagolden/path-tiny>
+
+ git clone git://github.com/dagolden/path-tiny.git
+
+=head1 AUTHOR
+
+David Golden <dagolden at cpan.org>
+
+=head1 CONTRIBUTORS
+
+=over 4
+
+=item *
+
+Chris Williams <bingos at cpan.org>
+
+=item *
+
+David Steinbrunner <dsteinbrunner at pobox.com>
+
+=item *
+
++Gabor Szabo <szabgab at cpan.org>
++
++=item *
++
+George Hartzell <hartzell at cpan.org>
+
+=item *
+
+Goro Fuji <gfuji at cpan.org>
+
+=item *
+
+Karen Etheridge <ether at cpan.org>
+
+=item *
+
+Keedi Kim <keedi at cpan.org>
+
+=item *
+
+Michael G. Schwern <mschwern at cpan.org>
+
+=back
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is Copyright (c) 2013 by David Golden.
+
+This is free software, licensed under:
+
+ The Apache License, Version 2.0, January 2004
+
+=cut
diff --cc t/00-report-prereqs.t
index 95166ad,0000000..2f60ad5
mode 100644,000000..100644
--- a/t/00-report-prereqs.t
+++ b/t/00-report-prereqs.t
@@@ -1,84 -1,0 +1,86 @@@
+#!perl
+
+use strict;
+use warnings;
+
+use Test::More tests => 1;
+
+use ExtUtils::MakeMaker;
+use File::Spec::Functions;
+use List::Util qw/max/;
+
+my @modules = qw(
+ Carp
+ Cwd
+ Devel::Hide
++ Digest
++ Digest::SHA
+ Exporter
+ ExtUtils::MakeMaker
+ Fcntl
+ File::Copy
+ File::Find
+ File::Path
+ File::Spec
+ File::Spec::Functions
+ File::Spec::Unix
+ File::Temp
+ File::pushd
+ File::stat
+ List::Util
+ Test::Deep
+ Test::FailWarnings
+ Test::Fatal
+ Test::More
+ Unicode::UTF8
+ autodie::exception
+ constant
+ open
+ overload
+ perl
+ strict
+ threads
+ warnings
+);
+
+# replace modules with dynamic results from MYMETA.json if we can
+# (hide CPAN::Meta from prereq scanner)
+my $cpan_meta = "CPAN::Meta";
+if ( -f "MYMETA.json" && eval "require $cpan_meta" ) { ## no critic
+ if ( my $meta = eval { CPAN::Meta->load_file("MYMETA.json") } ) {
+ my $prereqs = $meta->prereqs;
+ delete $prereqs->{develop};
+ my %uniq = map {$_ => 1} map { keys %$_ } map { values %$_ } values %$prereqs;
+ $uniq{$_} = 1 for @modules; # don't lose any static ones
+ @modules = sort keys %uniq;
+ }
+}
+
+my @reports = [qw/Version Module/];
+
+for my $mod ( @modules ) {
+ next if $mod eq 'perl';
+ my $file = $mod;
+ $file =~ s{::}{/}g;
+ $file .= ".pm";
+ my ($prefix) = grep { -e catfile($_, $file) } @INC;
+ if ( $prefix ) {
+ my $ver = MM->parse_version( catfile($prefix, $file) );
+ $ver = "undef" unless defined $ver; # Newer MM should do this anyway
+ push @reports, [$ver, $mod];
+ }
+ else {
+ push @reports, ["missing", $mod];
+ }
+}
+
+if ( @reports ) {
+ my $vl = max map { length $_->[0] } @reports;
+ my $ml = max map { length $_->[1] } @reports;
+ splice @reports, 1, 0, ["-" x $vl, "-" x $ml];
+ diag "Prerequisite Report:\n", map {sprintf(" %*s %*s\n",$vl,$_->[0],-$ml,$_->[1])} @reports;
+}
+
+pass;
+
+# vim: ts=2 sts=2 sw=2 et:
diff --cc t/digest.t
index 0000000,054cc70..1ac13d0
mode 000000,100644..100644
--- a/t/digest.t
+++ b/t/digest.t
@@@ -1,0 -1,44 +1,52 @@@
+ use 5.008001;
+ use strict;
+ use warnings;
+ use Test::More 0.96;
+
+ use Path::Tiny;
+ use Digest;
+
+ my $dir = Path::Tiny->tempdir;
+ my $file = $dir->child('foo.bin');
+
+ my $chunk = pack("Z*", "Hello Path::Tiny\nThis is packed binary string\n");
+ ok( $file->spew_raw($chunk), "created test file with packed binary string" );
+
+ is(
+ $file->digest,
+ 'a98e605049836e8adb36d351abb95a09e9e5e200703576ecdaec0e697d17d626',
+ 'digest SHA-256 (hardcoded)',
+ );
+
+ my $sha = Digest->new('SHA-256');
+ $sha->add($chunk);
+ is(
+ $file->digest,
+ $sha->hexdigest,
+ 'digest SHA-256',
+ );
+
+ is(
+ $file->digest('MD5'),
+ 'ce05aca61c0e58d7396073b668bcafd0',
+ 'digest MD5 (hardcoded)',
+ );
+
+ my $md5 = Digest->new('MD5');
+ $md5->add($chunk);
+ is(
+ $file->digest('MD5'),
+ $md5->hexdigest,
+ 'digest MD5',
+ );
+
+ done_testing;
-# COPYRIGHT
++#
++# This file is part of Path-Tiny
++#
++# This software is Copyright (c) 2013 by David Golden.
++#
++# This is free software, licensed under:
++#
++# The Apache License, Version 2.0, January 2004
++#
diff --cc xt/author/pod-spell.t
index 50bb5a3,0000000..312b65a
mode 100644,000000..100644
--- a/xt/author/pod-spell.t
+++ b/xt/author/pod-spell.t
@@@ -1,56 -1,0 +1,59 @@@
+use strict;
+use warnings;
+use Test::More;
+
+# generated by Dist::Zilla::Plugin::Test::PodSpelling 2.006000
+eval "use Test::Spelling 0.12; use Pod::Wordlist::hanekomu; 1" or die $@;
+
+
+add_stopwords(<DATA>);
+all_pod_files_spelling_ok( qw( bin lib ) );
+__DATA__
+BENCHMARKING
- BinGOs
+CRLF
- Etheridge
- Goro
- Hartzell
- Stringifying
++SHA
+canonpath
+codepoints
+cwd
+dirname
+lstat
+mkpath
+opena
+openr
+openrw
+openw
+realpath
++stringifying
+subclasses
+touchpath
+unlinked
+utf
+David
+Golden
+dagolden
+Chris
+Williams
+bingos
+Steinbrunner
+dsteinbrunner
++Gabor
++Szabo
++szabgab
+George
++Hartzell
+hartzell
++Goro
+Fuji
+gfuji
+Karen
++Etheridge
+ether
+Keedi
+Kim
+keedi
+Michael
+Schwern
+mschwern
+lib
+Path
+Tiny
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libpath-tiny-perl.git
More information about the Pkg-perl-cvs-commits
mailing list