NAME

Setup::File - Setup file (existence, mode, permission, content)

VERSION

version 0.14

SYNOPSIS

use Setup::File 'setup_file';

# simple usage (doesn't save undo data)
my $res = setup_file path => '/etc/rc.local',
                     should_exist => 1,
                     gen_content_code => sub { \("#!/bin/sh\n") },
                     owner => 'root', group => 0,
                     mode => '+x';
die unless $res->[0] == 200 || $res->[0] == 304;

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

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

DESCRIPTION

This module uses Log::Any logging framework.

This module has Rinci metadata.

SEE ALSO

Setup

FUNCTIONS

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

Setup file (existence, mode, permission, content).

On do, will create file (if it doesn't already exist) and correct mode/permission as well as content.

On undo, will restore old mode/permission/content, or delete the file again if it was created by this function and its content hasn't changed since.

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.

Arguments ('*' denotes required arguments):

• allow_symlink* => bool (default: 1)

  Whether symlink is allowed.

  If existing file 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.

• check_content_code => code

  Code to check content.

  If unset, file will not be checked for its content. If set, code will be called whenever file content needs to be checked. Code will be passed the reference to file content and should return a boolean value indicating whether content is acceptable. If it returns a false value, content is deemed unacceptable and needs to be fixed.

  Alternatively you can use the simpler 'content' argument.

• content => str

  Desired file content.

  Alternatively you can also use checkcontentcode & gencontentcode.

• gen_content_code => code

  Code to generate content.

  If set, whenever a new file content is needed (e.g. when file is created or file content reset), this code will be called to provide it. If unset, empty string will be used instead.

  Code will be passed the reference to the current content (or undef) and should return the new content.

  Alternatively you can use the simpler 'content' argument.

• group => str

  Expected group.

• mode => str

  Expected permission mode.

• owner => str

  Expected owner.

• path* => str

  Path to file.

  File 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 file should exist.

  If undef, file need not exist. If set to 0, file must not exist and will be deleted if it does. If set to 1, file 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.