NAME

Aion::Fs - утилиты для файловой системы: чтение, запись, поиск, замена файлов и т.д.

VERSION

0.1.2

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 { warn "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

Этот модуль облегчает использование файловой системы.

Модули File::Path, File::Slurper и File::Find обременены различными возможностями, которые используются редко, но требуют времени на ознакомление и тем самым повышают порог входа.

В Aion::Fs же использован принцип программирования KISS - чем проще, тем лучше!

Супермодуль IO::All не является конкурентом Aion::Fs, т.к. использует ООП подход, а Aion::Fs – ФП.

ООП — объектно-ориентированное программирование.
ФП — функциональное программирование.

SUBROUTINES/METHODS

cat ($file)

Считывает файл. Если параметр не указан, использует $_.

cat "/etc/passwd"  # ~> root

cat читает со слоем :utf8. Но можно указать другой слой следующим образом:

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

cat вызывает исключение в случае ошибки операции ввода-вывода:

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

lay ($file?, $content)

Записывает $content в $file.

Если указан один параметр, использует $_ вместо $file.
lay, использует слой :utf8. Для указания иного слоя используется массив из двух элементов в параметре $file:

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

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

find (;$path, @filters)

Рекурсивно обходит и возвращает пути из указанного пути или путей, если $path является ссылкой на массив. Без параметров использует $_ как $path.

Фильтры могут быть:

Подпрограммой — путь к текущему файлу передаётся в $_, а подпрограмма должна вернуть истину или ложь, как они понимаются perl-ом.
Regexp — тестирует каждый путь регулярным выражением.
Строка в виде "-Xxx", где Xxx — один или несколько символов. Аналогична операторам perl-а для тестирования файлов. Пример: -fr проверяет путь файловыми тестировщиками LLhttps://perldoc.perl.org/functions/-X.
Остальные строки превращаются функцией wildcard (см. ниже) в регулярное выражение для проверки каждого пути.

Пути, не прошедшие проверку @filters, не возвращаются.

Если фильтр -X не является файловой функцией perl, то выбрасывается исключение:

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

В этом примере find не может войти в подкаталог и передаёт ошибку в функцию errorenter (см. ниже) с установленными переменными $_ и $! (путём к каталогу и сообщением ОС об ошибке).

Внимание! Если errorenter не указана, то все ошибки игнорируются!

mkpath ["example/", 0];

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

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

mkpath for qw!ex/1/11 ex/1/12 ex/2/21 ex/2/22!;

my $count = 0;
find "ex", sub { find_stop if ++$count == 3; 1}  # -> 2

noenter (@filters)

Говорит find не входить в каталоги соответствующие фильтрам за ним.

errorenter (&block)

Вызывает &block для каждой ошибки возникающей при невозможности войти в какой-либо каталог.

find_stop ()

Останавливает find будучи вызван в одном из его фильтров, errorenter или noenter.

my $count = 0;
find "ex", sub { find_stop if ++$count == 3; 1}  # -> 2

erase (@paths)

Удаляет файлы и пустые каталоги. Возвращает @paths. При ошибке ввода-вывода выбрасывает исключение.

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

replace (&sub, @files)

Заменяет каждый файл на $_, если его изменяет &sub. Возвращает файлы, в которых не было замен.

@files может содержать массивы из двух элементов. Первый рассматривается как путь, а второй — как слой. Слой по умолчанию — :utf8.

&sub вызывается для каждого файла из @files. В неё передаются:

$_ — содержимое файла.
$a — путь к файлу.
$b — слой которым был считан файл и которым он будет записан.

В примере ниже файл "replace.ex" считывается слоем :utf8, а записывается слоем :raw в функции replace:

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

mkpath (;$path)

Как mkdir -p, но считает последнюю часть пути (после последней косой черты) именем файла и не создаёт её каталогом. Без параметра использует $_.

Если $path не указан, использует $_.
Если $path является ссылкой на массив, тогда используется путь в качестве первого элемента и права в качестве второго элемента.
Права по умолчанию — 0755.
Возвращает $path.

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

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

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

mtime (;$path)

Время модификации $path в unixtime с дробной частью (из Time::HiRes::stat). Без параметра использует $_.

Выбрасывает исключение, если файл не существует или нет прав:

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

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

sta (;$path)

Возвращает статистику о файле. Без параметра использует $_.

Чтобы можно было использовать с другими файловыми функциями, может получать ссылку на массив из которого берёт первый элемент в качестве файлового пути.

Выбрасывает исключение, если файл не существует или нет прав:

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

sta(["/"])->{ino} # ~> ^\d+$
sta(".")->{atime} # ~> ^\d+(\.\d+)?$

path (;$path)

Разбивает файловый путь на составляющие или собирает его из составляющих.

Если получает ссылку на массив, то воспринимает его первый элемент как путь.
Если получает ссылку на хэш, то собирает из него путь. Незнакомые ключи просто игнорирует. Набор ключей для каждой ФС – разный.
ФС берётся из системной переменной $^O.
К файловой системе не обращается.

{
    local $^O = "freebsd";

    path "."        # --> {path => ".", file => ".", name => "."}
    path ".bashrc"  # --> {path => ".bashrc", file => ".bashrc", name => ".bashrc"}
    path ".bash.rc"  # --> {path => ".bash.rc", file => ".bash.rc", name => ".bash", ext => "rc"}
    path ["/"]      # --> {path => "/", dir => "/"}
    local $_ = "";
    path            # --> {path => ""}
    path "a/b/c.ext.ly"   # --> {path => "a/b/c.ext.ly", dir => "a/b", file => "c.ext.ly", name => "c", ext => "ext.ly"}

    path +{dir  => "/", ext => "ext.ly"}    # => /.ext.ly
    path +{file => "b.c", ext => "ly"}      # => b.ly
    path +{path => "a/b/f.c", dir => "m"}   # => m/f.c

    local $_ = +{path => "a/b/f.c", dir => undef, ext => undef};
    path # => f
    path +{path => "a/b/f.c", volume => "/x", dir => "m/y/", file => "f.y", name => "j", ext => "ext"} # => m/y//j.ext
    path +{path => "a/b/f.c", volume => "/x", dir => "/y", file => "f.y", name => "j", ext => "ext"} # => /y/j.ext
}

{
    local $^O = "MSWin32"; # also os2, symbian and dos

    path "."        # --> {path => ".", file => ".", name => "."}
    path ".bashrc"  # --> {path => ".bashrc", file => ".bashrc", name => ".bashrc"}
    path "/"        # --> {path => "\\", dir => "\\", folder => "\\"}
    path "\\"       # --> {path => "\\", dir => "\\", folder => "\\"}
    path ""         # --> {path => ""}
    path "a\\b\\c.ext.ly"   # --> {path => "a\\b\\c.ext.ly", dir => "a\\b\\", folder => "a\\b", file => "c.ext.ly", name => "c", ext => "ext.ly"}

    path +{dir  => "/", ext => "ext.ly"}    # => \\.ext.ly
    path +{dir  => "\\", ext => "ext.ly"}   # => \\.ext.ly
    path +{file => "b.c", ext => "ly"}      # => b.ly
    path +{path => "a/b/f.c", dir => "m/r/"}   # => m\\r\\f.c

    path +{path => "a/b/f.c", dir => undef, ext => undef} # => f
    path +{path => "a/b/f.c", volume => "x", dir => "m/y/", file => "f.y", name => "j", ext => "ext"} # \> x:m\y\j.ext
    path +{path => "x:/a/b/f.c", volume => undef, dir =>  "/y/", file => "f.y", name => "j", ext => "ext"} # \> \y\j.ext
}

{
    local $^O = "amigaos";

    my $path = {
        path   => "Work1:Documents/Letters/Letter1.txt",
        dir    => "Work1:Documents/Letters/",
        volume => "Work1",
        folder => "Documents/Letters",
        file   => "Letter1.txt",
        name   => "Letter1",
        ext    => "txt",
    };

    path "Work1:Documents/Letters/Letter1.txt" # --> $path

    path {volume => "Work", file => "Letter1.pm", ext => "txt"} # => Work:Letter1.txt
}

{
    local $^O = "cygwin";

    my $path = {
        path   => "/cygdrive/c/Documents/Letters/Letter1.txt",
        dir    => "/cygdrive/c/Documents/Letters/",
        volume => "c",
        folder => "Documents/Letters",
        file   => "Letter1.txt",
        name   => "Letter1",
        ext    => "txt",
    };

    path "/cygdrive/c/Documents/Letters/Letter1.txt" # --> $path

    path {volume => "c", file => "Letter1.pm", ext => "txt"} # => /cygdrive/c/Letter1.txt
}

{
    local $^O = "dos";

    my $path = {
        path   => 'c:\Documents\Letters\Letter1.txt',
        dir    => 'c:\Documents\Letters\\',
        volume => 'c',
        folder => '\Documents\Letters',
        file   => 'Letter1.txt',
        name   => 'Letter1',
        ext    => 'txt',
    };

    path 'c:\Documents\Letters\Letter1.txt' # --> $path

    path {volume => "c", file => "Letter1.pm", ext => "txt"} # \> c:Letter1.txt
    path {dir => 'r\t\\',  file => "Letter1",    ext => "txt"} # \> r\t\Letter1.txt
}

{
    local $^O = "VMS";

    my $path = {
        path   => "DISK:[DIRECTORY.SUBDIRECTORY]FILENAME.EXTENSION",
        dir    => "DISK:[DIRECTORY.SUBDIRECTORY]",
        volume => "DISK:",
        disk   => "DISK",
        folder => "DIRECTORY.SUBDIRECTORY",
        card   => "FILENAME.EXTENSION",
        file   => "FILENAME.EXTENSION",
        name   => "FILENAME",
        ext    => "EXTENSION",
    };

    path "DISK:[DIRECTORY.SUBDIRECTORY]FILENAME.EXTENSION" # --> $path

    $path = {
        path        => 'NODE["account password"]::DISK$USER:[DIRECTORY.SUBDIRECTORY]FILENAME.EXTENSION;7',
        dir         => 'NODE["account password"]::DISK$USER:[DIRECTORY.SUBDIRECTORY]',
        node        => "NODE",
        accountname => "account",
        password    => "password",
        volume      => 'DISK$USER:',
        disk        => 'DISK',
        user        => 'USER',
        folder      => "DIRECTORY.SUBDIRECTORY",
        card        => "FILENAME.EXTENSION;7",
        file        => "FILENAME.EXTENSION",
        name        => "FILENAME",
        ext         => "EXTENSION",
        version     => 7,
    };

    path 'NODE["account password"]::DISK$USER:[DIRECTORY.SUBDIRECTORY]FILENAME.EXTENSION;7' # --> $path

    path {volume => "DISK:", file => "FILENAME.pm", ext => "EXTENSION"} # => DISK:FILENAME.EXTENSION
    path {user => "USER", folder => "DIRECTORY.SUBDIRECTORY", file => "FILENAME.pm", ext => "EXTENSION"} # \> $USER:[DIRECTORY.SUBDIRECTORY]FILENAME.EXTENSION
}

{
    local $^O = "VOS";

    my $path = {
        path    => "%sysname#module1>SubDir>File.txt",
        dir     => "%sysname#module1>SubDir>",
        volume  => "%sysname#module1>",
        sysname => "sysname",
        module  => "module1",
        folder  => "SubDir",
        file    => "File.txt",
        name    => "File",
        ext     => "txt",
    };

    path $path->{path} # --> $path

    path {volume => "%sysname#module1>", file => "File.pm", ext => "txt"} # => %sysname#module1>File.txt
    path {module => "module1", file => "File.pm"} # => %#module1>File.pm
    path {sysname => "sysname", file => "File.pm"} # => %sysname#>File.pm
    path {dir => "dir>subdir>", file => "File.pm", ext => "txt"} # => dir>subdir>File.txt
}

{
    local $^O = "riscos";

    my $path = {
        path   => 'Filesystem#Special_Field::DiskName.$.Directory.Directory.File/Ext/Ext',
        dir    => 'Filesystem#Special_Field::DiskName.$.Directory.Directory.',
        volume => 'Filesystem#Special_Field::DiskName.',
        fstype => "Filesystem",
        option => "Special_Field",
        disk   => "DiskName",
        folder => '$.Directory.Directory',
        file   => "File/Ext/Ext",
        name   => "File",
        ext    => "Ext/Ext",
    };

    path $path->{path} # --> $path

    $path = {
        path => '.$.Directory.Directory.',
        dir => '.$.Directory.Directory.',
        folder => '.$.Directory.Directory',
    };

    path '.$.Directory.Directory.' # --> $path

    path {volume => "ADFS::HardDisk.", file => "File"} # => ADFS::HardDisk.$.File
    path {folder => "x"}  # => x.
    path {dir    => "x."} # => x.
}

{
    local $^O = "MacOS";

    my $path = {
        path   => '::::mix:report.doc',
        dir    => "::::mix:",
        folder => ":::mix",
        file   => "report.doc",
        name   => "report",
        ext    => "doc",
    };

    path $path->{path} # --> $path
    path $path         # => $path->{path}

    path 'report' # --> {path => 'report', file => 'report', name => 'report'}

    path {volume => "x", file => "f"} # => x:f
    path {folder => "x"} # => x:
}

{
    local $^O = "vmesa";

    my $path = {
        path   => ' USERID   FILE EXT   VOLUME ',
        userid => "USERID",
        file   => "FILE EXT",
        name   => "FILE",
        ext    => "EXT",
        volume => "VOLUME",
    };

    path $path->{path} # --> $path

    path {volume => "x", file => "f"} # -> ' f  x'
}

transpath ($path?, $from, $to)

Переводит путь из формата одной ОС в другую.

Если $path не указан, то используется $_.

Перечень поддерживаемых ОС смотрите в примерах подпрограммы path чуть выше или так: keys %Aion::Fs::FS.

Названия ОС – регистронезависимы.

local $_ = ">x>y>z.doc.zip";
transpath "vos", "unix"       # \> /x/y/z.doc.zip
transpath "vos", "VMS"        # \> [.x.y]z.doc.zip
transpath $_, "vos", "RiscOS" # \> .x.y.z/doc/zip

splitdir (;$dir)

Разбивает директорию на составляющие. Директорию следует вначале получить из path->{dir}.

local $^O = "unix";
[ splitdir "/x/" ]    # --> ["", "x", ""]

joindir (;$dirparts)

Объединяет директорию из составляющих. Затем полученную директорию следует включить в path +{dir => $dir}.

local $^O = "unix";
joindir qw/x y z/    # => x/y/z

path +{ dir => joindir qw/x y z/ } # => x/y/z/

splitext (;$ext)

Разбивает расширение на составляющие. Расширение следует вначале получить из path->{ext}.

local $^O = "unix";
[ splitext ".x." ]    # --> ["", "x", ""]

joinext (;$extparts)

Объединяет расширение из составляющих. Затем полученное расширение следует включить в path +{ext => $ext}.

local $^O = "unix";
joinext qw/x y z/    # => x.y.z

path +{ ext => joinext qw/x y z/ } # => .x.y.z

include (;$pkg)

Подключает $pkg (если он ещё не был подключён через use или require) и возвращает его. Без параметра использует $_.

Файл lib/A.pm:

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

Файл 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)

Считывает файл в первый раз. Любая последующая попытка считать этот файл возвращает undef. Используется для вставки модулей js и css в результирующий файл. Без параметра использует $_.

$file может содержать массивы из двух элементов. Первый рассматривается как путь, а второй — как слой. Слой по умолчанию — :utf8.
Если $file не указан – использует $_.

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

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

wildcard (;$wildcard)

Переводит файловую маску в регулярное выражение. Без параметра использует $_.

** - [^/]*
* - .*
? - .
?? - [^/]
{ - (
} - )
, - |
Остальные символы экранируются с помощью quotemeta.

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

Используется в фильтрах функции find.

goto_editor ($path, $line)

Открывает файл в редакторе из .config на указанной строке. По умолчанию использует vscodium %p:%l.

Файл .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

from_pkg (;$pkg)

Переводит пакет в путь ФС. Без параметра использует $_.

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)

Переводит путь из ФС в пакет. Без параметра использует $_.

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 mailto:dart@cpan.org

LICENSE

⚖ GPLv3

COPYRIGHT

To install Aion::Fs, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Aion::Fs

CPAN shell

perl -MCPAN -e shell
install Aion::Fs

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

SUBROUTINES/METHODS

cat ($file)

See also

lay ($file?, $content)

See also

find (;$path, @filters)

See also

noenter (@filters)

errorenter (&block)

find_stop ()

erase (@paths)

See also

replace (&sub, @files)

See also

mkpath (;$path)

See also

mtime (;$path)

See also

sta (;$path)

See also

path (;$path)

See also

transpath ($path?, $from, $to)

splitdir (;$dir)

joindir (;$dirparts)

splitext (;$ext)

joinext (;$extparts)

include (;$pkg)

catonce (;$file)

wildcard (;$wildcard)

See also

goto_editor ($path, $line)

from_pkg (;$pkg)

to_pkg (;$path)

AUTHOR

LICENSE

COPYRIGHT

Module Install Instructions