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.