The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Path-Class-Tiny-0.03
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.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 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.

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