/ 
Setup-File-0.13
River stage one • 3 direct dependents • 3 total dependents
/ Setup::File::Dir

NAME

Setup::File::Dir - Setup directory (existence, mode, permission)

VERSION

version 0.13

SYNOPSIS

use Setup::File::Dir 'setup_dir';

# simple usage (doesn't save undo data)
$res = setup_dir path => '/etc/myapp',
                 should_exist => 1,
                 owner => 'root', group => 0, mode => 0755;
die unless $res->[0] == 200;

# perform setup and save undo data (undo data should be serializable)
$res = setup_dir ..., -undo_action => 'do';
die unless $res->[0] == 200;
my $undo_data = $res->[3]{undo_data};

# perform undo
$res = setup_dir ..., -undo_action => "undo", -undo_data=>$undo_data;
die unless $res->[0] == 200;

# state that dir must not exist
setup_dir path => '/foo/bar', should_exist => 0;

DESCRIPTION

This module provides one function: setup_dir.

This module is part of the Setup modules family.

This module uses Log::Any logging framework.

This module's functions have Rinci metadata.

THE SETUP MODULES FAMILY

I use the Setup:: namespace for the Setup modules family. See Setup::File for more details on the goals, characteristics, and implementation of Setup modules family.

SEE ALSO

Setup::File.

Other modules in Setup:: namespace.

FUNCTIONS

setup_dir(%args) -> [status, msg, result, meta]

Setup directory (existence, mode, permission).

On do, will create directory (if it doesn't already exist) and fix its mode/permission.

On undo, will restore old mode/permission (and delete directory if it is empty and was created by this function).

If given, -undohint should contain {tmpdir=>...} to specify temporary directory to save replaced file/dir. Temporary directory defaults to ~/.setup, it will be created if not exists.

Will not create intermediate directories like "mkdir -p". Create intermediate directories using several setup_dir() invocation.

Arguments ('*' denotes required arguments):

  • allow_symlink* => bool (default: 1)

    Whether symlink is allowed.

    If existing dir is a symlink then if allowsymlink is false then it is an unacceptable condition (the symlink will be replaced if replacesymlink is true).

    Note: if you want to setup symlink instead, use Setup::Symlink.

  • group => str

    Expected group.

  • mode => str

    Expected permission mode.

  • owner => str

    Expected owner.

  • path* => str

    Path to dir.

    Dir path needs to be absolute so it's normalized.

  • replace_dir* => bool (default: 1)

    Replace existing dir if it needs to be replaced.

  • replace_file* => bool (default: 1)

    Replace existing file if it needs to be replaced.

  • replace_symlink* => bool (default: 1)

    Replace existing symlink if it needs to be replaced.

  • should_exist => bool

    Whether dir should exist.

    If undef, dir need not exist. If set to 0, dir must not exist and will be deleted if it does. If set to 1, dir must exist and will be created if it doesn't.

Return value:

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 (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Steven Haryanto.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.