NAME

Aion::Fs - utilities for filesystem: read, write, find, replace files, etc

VERSION

0.0.6

SYNOPSIS

use Aion::Fs;

lay mkpath "hello/world.txt", "hi!";
lay mkpath "hello/moon.txt", "noreplace";
lay mkpath "hello/big/world.txt", "hellow!";
lay mkpath "hello/small/world.txt", "noenter";

mtime "hello"  # ~> ^\d+(\.\d+)?$

[map cat, grep -f, find ["hello/big", "hello/small"]]  # --> [qw/ hellow! noenter /]

my @noreplaced = replace { s/h/$a $b H/ }
    find "hello", "-f", "*.txt", qr/\.txt$/, sub { /\.txt$/ },
        noenter "*small*",
            errorenter { die "find $_: $!" };

\@noreplaced # --> ["hello/moon.txt"]

cat "hello/world.txt"       # => hello/world.txt :utf8 Hi!
cat "hello/moon.txt"        # => noreplace
cat "hello/big/world.txt"   # => hello/big/world.txt :utf8 Hellow!
cat "hello/small/world.txt" # => noenter

[find "hello", "*.txt"]  # --> [qw!  hello/moon.txt  hello/world.txt  hello/big/world.txt  hello/small/world.txt  !]
[find "hello", "-d"]  # --> [qw!  hello  hello/big hello/small  !]

erase reverse find "hello";

-e "hello"  # -> undef

DESCRIPTION

This module provide light entering to filesystem.

Modules File::Path, File::Slurper and File::Find are quite weighted with various features that are rarely used, but take time to get acquainted and, thereby, increases the entry threshold.

In Aion::Fs used the programming principle KISS - Keep It Simple, Stupid.

Supermodule IO::All provide OOP, and Aion::Fs provide FP.

• OOP - object oriented programming.
• FP - functional programming.

SUBROUTINES/METHODS

cat ($file)

Read file. If file not specified, then use $_.

cat "/etc/passwd"  # ~> root

cat read with layer :utf8. But you can set the level like this:

lay "unicode.txt", "↯";
length cat "unicode.txt"            # -> 1
length cat["unicode.txt", ":raw"]   # -> 3

cat raise exception by error on io operation:

eval { cat "A" }; $@  # ~> cat A: No such file or directory

See also:

• File::Slurp — read_file('file.txt').
• File::Slurper — read_text('file.txt'), read_binary('file.txt').
• IO::All — io('file.txt') > $contents.

lay ($file, $content)

Write $content in $file.

• If one parameter specified, then use $_ as $file.
• lay using layer :utf8. For set layer using two elements array for $file:

lay "unicode.txt", "↯"  # => unicode.txt
lay ["unicode.txt", ":raw"], "↯"  # => unicode.txt

eval { lay "/", "↯" }; $@ # ~> lay /: Is a directory

See also:

• File::Slurp — write_file('file.txt', $contents).
• File::Slurper — write_text('file.txt', $contents), write_binary('file.txt', $contents).
• IO::All — io('file.txt') < $contents.

find ($path, @filters)

Finded files and returns array paths from start path or paths if $path is array ref.

Filters may be:

• Subroutine - the each path fits to $_ and test with subroutine.
• Regexp - test the each path on the regexp.
• String as "-Xxx", where Xxx - one or more symbols. Test on the perl file testers. Example "-fr" test the path on -f and -r file testers.
• Any string interpret function wildcard to regexp and the each path test on it.

The paths that have not passed testing by @filters are not returned.

If filter -X is unused, then throw exception:

eval { find "example", "-h" }; $@   # ~> Undefined subroutine &Aion::Fs::h called

If find is impossible to enter the subdirectory, then call errorenter with set variable $_ and $!.

mkpath ["example/", 0];

[find "example"]    # --> ["example"]
[find "example", noenter "-d"]    # --> ["example"]

eval { find "example", errorenter { die "find $_: $!" } }; $@   # ~> find example: Permission denied

See also:

• File::Find — find(sub { push @paths, $File::Find::name }, $dir).

noenter (@filters)

No enter to catalogs. Using in find. @filters same as in find.

errorenter (&block)

Call &block for each error on open catalog.

erase (@paths)

Remove files and empty catalogs. Returns the @paths.

eval { erase "/" }; $@  # ~> erase dir /: Device or resource busy
eval { erase "/dev/null" }; $@  # ~> erase file /dev/null: Permission denied

See also:

• .
• File::Path — remove_tree("dir").

mkpath ($path)

As mkdir -p, but consider last path-part (after last slash) as filename, and not create this catalog.

• If $path not specified, then use PATH.
• If $path is array ref, then use path as first and permission as second element.
• Default permission is 0755.
• Returns $path.

local $_ = ["A", 0755];
mkpath   # => A

eval { mkpath "/A/" }; $@   # ~> mkpath /A: Permission denied

mkpath "A///./file";
-d "A"  # -> 1

See also:

• File::Path — mkpath("dir1/dir2").

mtime ($file)

Time modification the $file in unixtime in subsecond resolution (from Time::HiRes::stat).

Raise exeception if file not exists, or not permissions:

local $_ = "nofile";
eval { mtime }; $@  # ~> mtime nofile: No such file or directory

mtime ["/"]   # ~> ^\d+(\.\d+)?$

See also:

• <-M> — -M "file.txt", -M _ in days.
• — (stat "file.txt")[9] in seconds.
• Time::HiRes — (Time::HiRes::stat "file.txt")[9] in seconds with fractional part.

replace (&sub, @files)

Replacing each the file if &sub replace $_. Returns files in which there were no replacements.

@files can contain arrays of two elements. The first one is treated as a path, and the second one is treated as a layer. Default layer is :utf8.

local $_ = "replace.ex";
lay "abc";
replace { $b = ":utf8"; y/a/¡/ } [$_, ":raw"];
cat  # => ¡bc

See also:

• File::Edit.
• File::Edit::Portable.

include ($pkg)

Require $pkg and returns it.

File lib/A.pm:

package A;
sub new { bless {@_}, shift }
1;

File lib/N.pm:

package N;
sub ex { 123 }
1;

use lib "lib";
include("A")->new               # ~> A=HASH\(0x\w+\)
[map include, qw/A N/]          # --> [qw/A N/]
{ local $_="N"; include->ex }   # -> 123

catonce ($file)

Read the file in first call with this file. Any call with this file return undef. Using for insert js and css modules in the resulting file.

local $_ = "catonce.txt";
lay "result";
catonce  # -> "result"
catonce  # -> undef

eval { catonce[] }; $@ # ~> catonce not use ref path!

wildcard ($wildcard)

Translate the wildcard to regexp.

• ** - [^/]*
• * - .*
• ? - .
• ?? - [^/]
• { - (
• } - )
• , - |
• Any symbols translate by quotemeta.

wildcard "*.{pm,pl}"  # \> (?^usn:^.*?\.(pm|pl)$)
wildcard "?_??_**"  # \> (?^usn:^._[^/]_[^/]*?$)

Using in filters the function find.

See also:

• File::Wildcard.
• String::Wildcard::Bash.

goto_editor ($path, $line)

Open the file in editor from config on the line.

File .config.pm:

package config;

config_module 'Aion::Fs' => {
    EDITOR => 'echo %p:%l > ed.txt',
};

1;

goto_editor "mypath", 10;
cat "ed.txt"  # => mypath:10\n

eval { goto_editor "`", 1 }; $@  # ~> `:1 --> 512

Default the editor is vscodium.

from_pkg (;$pkg)

From package to file path.

from_pkg "Aion::Fs"  # => Aion/Fs.pm
[map from_pkg, "Aion::Fs", "A::B::C"]  # --> ["Aion/Fs.pm", "A/B/C.pm"]

to_pkg (;$path)

From file path to package.

to_pkg "Aion/Fs.pm"  # => Aion::Fs
[map to_pkg, "Aion/Fs.md", "A/B/C.md"]  # --> ["Aion::Fs", "A::B::C"]

AUTHOR

Yaroslav O. Kosmina dart@cpan.org

LICENSE

⚖ GPLv3

COPYRIGHT

The Aion::Fs is copyright © 2023 by Yaroslav O. Kosmina. Rusland. All rights reserved.