/ 
Path-Class-Tiny-0.02
River stage zero No dependents
/ Path::Class::Tiny

NAME

Path::Class::Tiny - a Path::Tiny wrapper for Path::Class compatibility

VERSION

This document describes version 0.02 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 yep

Going 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 style

Slurping 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 weird

DETAILS

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.

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 true

SUPPORT

Perldoc

You can find documentation for this module with the perldoc command.

perldoc Path::Class::Tiny

Bugs / 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 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: L<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.git

AUTHOR

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)