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

NAME

Setup::Dir - Ensure dir (non-)existence & mode/permission

VERSION

version 0.02

SYNOPSIS

use Setup::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 Sub::Spec specs.

THE SETUP MODULES FAMILY

I use the Setup:: namespace for the Setup modules family, typically used in installers (or other applications). The modules in Setup family have these characteristics:

  • used to reach some desired state

    For example, Setup::Symlink::setup_symlink makes sure a symlink exists to the desired target. Setup::File::setup_file makes sure a file exists with the correct content/ownership/permission.

  • do nothing if desired state has been reached

  • support dry-run (simulation) mode

  • support undo to restore state to previous/original one

FUNCTIONS

None are exported by default, but they are exportable.

setup_dir(%args) -> [STATUS_CODE, ERR_MSG, RESULT]

Ensure directory (non-)existence and mode/permission.

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

Returns a 3-element arrayref. STATUS_CODE is 200 on success, or an error code between 3xx-5xx (just like in HTTP). ERR_MSG is a string containing error message, RESULT is the actual result.

This function supports undo operation. See Sub::Spec::Clause::features for details on how to perform do/undo/redo.

This function supports dry-run (simulation) mode. To run in dry-run mode, add argument -dry_run => 1.

Arguments (* denotes required arguments):

  • path* => str

    Path to dir.

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

  • allow_symlink* => bool (default 0)

    Whether symlink is allowed.

    If existing dir is a symlink then if allow_symlink is false then it is an unacceptable condition (the symlink will be replaced if replace_symlink 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.

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

SEE ALSO

Sub::Spec, specifically Sub::Spec::Clause::features on dry-run/undo.

Other modules in Setup:: namespace.

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 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.