NAME
Path::Class::Tiny - a Path::Tiny wrapper for Path::Class compatibility
VERSION
This document describes version 0.03 of Path::Class::Tiny.
SYNOPSIS
use Path::Class::Tiny;
# creating Path::Class::Tiny objects
$dir1 = path("/tmp");
$dir2 = dir("/home");
$foo = path("foo.txt");
$foo = file("bar.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;
@lines = $file->slurp;
# writing files
$bar->spew( $data );
$bar->spew( @data );
# comparing files
if ( $foo->ef($bar) ) { ... }
# reading directories
for ( $dir->children ) { ... }DESCRIPTION
What do you do if you started out (Perl) life using Path::Class, but then later on you switched to Path::Tiny? Well, one thing you could do is relearn a bunch of things and go change a lot of existing code. Or, another thing would be to use Path::Class::Tiny instead.
Path::Class::Tiny is a thin(ish) wrapper around Path::Tiny that (mostly) restores the Path::Class interface. Where the two don't conflict, you can do it either way. Where they do conflict, you use the Path::Class way. Except where Path::Class is totally weird, in which case you use the Path::Tiny way.
Some examples:
Creating file/dir/path objects
Path::Class likes you to make either a file object or a dir object. Path::Tiny says that's silly and you should just make a path object. Path::Class::Tiny says you can use any of the 3 words you like; all the objects will be the same underneath.
my $a = file('foo', 'bar');
my $b = dir('foo', 'bar');
my $c = path('foo', 'bar');
say "true" if $a eq $b; # yep
say "true" if $b eq $c; # also yepGoing up or down the tree
Again, both styles work.
my $d = dir("foo");
my $up = $d->dir; # this works
$up = $d->parent; # so does this
$up = $d->dir->parent; # sure, why not?
my $down = $d->child('bar'); # Path::Tiny style
my $down = $d->subdir('bar'); # Path::Class styleSlurping files
This mostly works like Path::Class, in that the return value is context-sensitive, and options are sent as a hash and not as a hashref.
my $data = $file->slurp; # one big string
my @data = $file->slurp; # one element per line
my @data = $file->slurp(chomp => 1); # chomp every line
my @data = $file->slurp(iomode => '<:crlf'); # Path::Class style; works
my @data = $file->slurp(binmode => ':crlf'); # vaguely Path::Tiny style; also works
my @data = $file->slurp({binmode => ':crlf'}); # this one doesn't work
my $data = $file->slurp(chomp => 1); # neither does this one, because it's weirdDETAILS
This module is still undergoing active development. While the general UI is somewhat constrained by the design goals, specific choices may, and almost certainly will, change. I think this module can be useful to you, but for right now I would only use it for personal scripts.
A Path::Class::Tiny isa Path::Tiny, but not isa Path::Class::Entity. At least not currently.
Path::Class::Tiny is not entirely a drop-in replacement for Path::Class, and most likely never will be. In particular, I have no interest in implementing any of the "foreign" methods. However, it should work for most common cases, and, if it doesn't, patches are welcome.
Performance of Path::Class::Tiny should be comparable to Path::Tiny. Again, if it's not, please let me know.
The POD is somewhat impoverished at the moment. Hopefully that will improve over time. Again, patches welcomed.
PATH::CLASS STYLE METHODS
cleanup
Redirects to "canonpath" in Path::Tiny.
components
Basically just like components from Path::Class::Dir, which means that it accepts offset and length arguments (which Path::Class::File doesn't). Another nice difference: calling components from Path::Class::File in scalar context doesn't do anything useful, whereas Path::Class::Tiny always returns the number of components, which is (hopefully) what you expect.
The only real difference between Path::Class::Tiny's components and Path::Class::Dir's components is that you don't get the volume returned in the Path::Class::Dir version. In this version, the volume (if any) will just be part of the first component in the list.
dir_list
Just an alias for "components", so it also works on files (Path::Class::File doesn't have a dir_list method). This means the basename is always the last entity in the list, even for files. Basically this is just here for compatibility's sake, and you probably shouldn't use it for new code, because the name doesn't really sound like what it does.
next
Uses "iterator" in Path::Tiny (with its default value of no recursion) to implement the interface of next from Path::Class::Dir. The primary difference this engenders is that the Path::Class::Dir version will return . and .., whereas this version will not. I also don't guarantee this version is re-entrant.
rmtree
Just an alias to "remove_tree" in Path::Tiny.
subdir
Just an alias to "child" in Path::Tiny.
NEW METHODS
ef
Are you tired of trying to remember which method (or combination of methods) you have to call to verify that two files are actually the same file, where one path might be relative and the other absolute, or one might be a symlink to the other, or one might be a completely different path but one directory somewhere in the middle is really a symlink to a directory in the middle of the other path so they wind up being the same path, really? Yeah, me too. In bash, this is super easy:
if [[ $file1 -ef $file2 ]]Well, why shouldn't it be easy in Perl too? Okay, now it is:
my $file1 = path($whatever);
if ( $file1->ef($file2) )While $file1 must obviously be a Path::Class::Tiny, $file2 can be another Path::Class::Tiny object, or a Path::Class::Entity, or a Path::Tiny, or just a bare string. Most anything should work, really. Do note that both files must actually exist in the filesystem though. It's also okay for both to be exactly the same object:
if ( $file1->ef($file1) ) # always trueSUPPORT
Perldoc
You can find documentation for this module with the perldoc command.
perldoc Path::Class::TinyBugs / Feature Requests
This module is on GitHub. Feel free to fork and submit patches. Please note that I develop via TDD (Test-Driven Development), so a patch that includes a failing test is much more likely to get accepted (or at least likely to get accepted more quickly).
If you just want to report a problem or suggest a feature, that's okay too. You can create an issue on GitHub here: http://github.com/barefootcoder/path-class-tiny/issues.
Source Code
none https://github.com/barefootcoder/path-class-tiny
git clone https://github.com/barefootcoder/path-class-tiny.gitAUTHOR
Buddy Burden <barefootcoder@gmail.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2018 by Buddy Burden.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)