NAME
File::Create::Layout - Quickly create files/directories according to a
layout
VERSION
This document describes version 0.060 of File::Create::Layout (from Perl
distribution File-Create-Layout), released on 2019-04-16.
SYNOPSIS
use File::Create::Layout qw(
create_files_using_layout
check_layout
parse_layout
);
my $res = create_files_using_layout(layout => <<'EOL');
file1.txt
file2(0600)
file3.txt(0644) "content":"hello, world\n"
dir1/
file1
file2
file3
dir2/(root,bin,0600)
# some comment
file1
dir3/
anotherfile.txt "content":"secret"
file2
EOL
DESCRIPTION
EARLY DEVELOPMENT. MORE OPTIONS WILL BE AVAILABLE (E.G. DRY-RUN,
CHECKING A LAYOUT AGAINST FILESYSTEM, VARIOUS ERROR HANDLING OPTIONS).
LAYOUT SPECIFICATION
Layout is a text document containing zero or more lines. Each line is
either a file/directory specification line, a blank line, or a comment
line.
Comment line starts with zero or more whitespaces, a "#" (hash)
character, and zero or more non-newline characters as the comment's
content.
The simplest specification line contains just the name of a file or
directory. To specify a directory, you need to add "/" (slash)
immediately after the name:
# a file
foo.txt
# a directory
bar/
# another directory
baz.txt/
To specify filename containing special characters, like "#", you can
quote the file using double quotes:
"#tmpname#"
"filename containing \"quotes\""
The string will be parsed as a JSON string.
Permission and ownership. Immediately after the filename or directory
name, you can specify permission mode, as well as ownership (owner
user/group):
# specify permission mode, both are identical
file.txt(0600)
file2.txt(600)
# specify owner as well as user+group
dir1/(ujang,admin,0700)
Symlink. To create a symlink, add "->" (arrow) followed by the symlink
target. Like filename, symlink target can be an unquoted sequence of
non-whitespace characters, or a quoted JSON string if you want to have
whitespace or other special characters:
symlink1 -> ../target
symlink2 -> "/home/ujang/My Documents"
File content. An unquoted JSON hash (object) can be added in the end,
prefixed by at least one whitespace to specify extra stuffs, including
file content. By unquoted, it means that the enclosing curly braces "{
.. }" is not written:
file.txt "content":"This is line 1\nThis is line 2\n"
file2.txt(0660) "content":"secret","foo":"bar","mtime":1441853999
Putting files/directories in a subdirectory. Indentation (only spaces,
tabs are not allowed) is used for this:
dir1/
file1-inside-dir1
file2-inside-dir1
dir2/
file3-inside-dir2
file4-inside-dir2
another-file-inside-dir1
file5-in-top-level
file6
FUNCTIONS
check_layout
Usage:
check_layout(%args) -> [status, msg, payload, meta]
Check whether layout has syntax errors.
This function is not exported.
Arguments ('*' denotes required arguments):
* layout* => *str*
Layout.
See the module documentation for the format/specification of layout.
Returns an enveloped result (an array).
First element (status) is an integer containing HTTP status code (200
means OK, 4xx caller error, 5xx function error). Second element (msg) is
a string containing error message, or 'OK' if status is 200. Third
element (payload) is optional, the actual result. Fourth element (meta)
is called result metadata and is optional, a hash that contains extra
information.
Return value: (any)
create_files_using_layout
Usage:
create_files_using_layout(%args) -> [status, msg, payload, meta]
Create files/directories according to a layout.
This routine can be used to quickly create several files/directories
according to a layout which you specify. The layout uses a few simple
rules and common conventions usually found in Linux/Unix environment.
You can use this routine e.g. in a test script.
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
* layout* => *str*
Layout.
See the module documentation for the format/specification of layout.
* prefix => *str*
Root directory to create the files/directories in.
Directory must already exist.
If unspecified, will simply create starting from current directory.
Returns an enveloped result (an array).
First element (status) is an integer containing HTTP status code (200
means OK, 4xx caller error, 5xx function error). Second element (msg) is
a string containing error message, or 'OK' if status is 200. Third
element (payload) is optional, the actual result. Fourth element (meta)
is called result metadata and is optional, a hash that contains extra
information.
Return value: (any)
parse_layout
Usage:
parse_layout(%args) -> [status, msg, payload, meta]
Parse layout string into a data structure suitable for processing.
This function is not exported.
Arguments ('*' denotes required arguments):
* layout* => *str*
Layout.
See the module documentation for the format/specification of layout.
Returns an enveloped result (an array).
First element (status) is an integer containing HTTP status code (200
means OK, 4xx caller error, 5xx function error). Second element (msg) is
a string containing error message, or 'OK' if status is 200. Third
element (payload) is optional, the actual result. Fourth element (meta)
is called result metadata and is optional, a hash that contains extra
information.
Return value: (any)
HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/File-Create-Layout>.
SOURCE
Source repository is at
<https://github.com/perlancar/perl-File-Create-Layout>.
BUGS
Please report any bugs or feature requests on the bugtracker website
<https://rt.cpan.org/Public/Dist/Display.html?Name=File-Create-Layout>
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.
SEE ALSO
Setup::File::Layout, transactional/undoable version of this module
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2019, 2017, 2015 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.