NAME
    Setup::File::Symlink - Setup symlink (existence, target)

VERSION
    version 0.13

SYNOPSIS
     use Setup::File::Symlink 'setup_symlink';

     # simple usage (doesn't save undo data)
     my $res = setup_symlink symlink => "/baz", target => "/qux";
     die unless $res->[0] == 200 || $res->[0] == 304;

     # perform setup and save undo data
     my $res = setup_symlink symlink => "/foo", target => "/bar",
                             -undo_action => 'do';
     die unless $res->[0] == 200 || $res->[0] == 304;
     my $undo_data = $res->[3]{undo_data};

     # perform undo
     my $res = setup_symlink symlink => "/symlink", target=>"/target",
                             -undo_action => "undo", -undo_data=>$undo_data;
     die unless $res->[0] == 200;

DESCRIPTION
    This module provides one function setup_symlink.

    This module is part of the Setup modules family.

    This module uses Log::Any logging framework.

    This module has 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.

FUNCTIONS
    None are exported by default, but they are exportable.

  setup_symlink(%args) -> [STATUS_CODE, ERR_MSG, RESULT]
    Setup symlink (existence, target).

    On do, will create symlink which points to specified target. If symlink
    already exists but points to another target, it will be replaced with
    the correct symlink if replace_symlink option is true. If a file already
    exists, it will be removed (or, backed up to temporary directory) before
    the symlink is created, if replace_file option is true.

    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.

    On undo, will delete symlink if it was created by this function, and
    restore the original symlink/file/dir if it was replaced during do.

    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):

    *   target* => *str*

        Target path of symlink.

    *   symlink* => *str*

        Path to symlink.

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

    *   create* => *bool* (default 1)

        Create if symlink doesn't exist.

        If set to false, then setup will fail (412) if this condition is
        encountered.

    *   replace_dir* => *bool* (default 0)

        Replace if there is existing dir.

        If set to false, then setup will fail (412) if this condition is
        encountered.

    *   replace_file* => *bool* (default 0)

        Replace if there is existing non-symlink file.

        If set to false, then setup will fail (412) if this condition is
        encountered.

    *   replace_symlink* => *bool* (default 1)

        Replace previous symlink if it already exists but doesn't point to
        the wanted target.

        If set to false, then setup will fail (412) if this condition is
        encountered.

SEE ALSO
    Other modules in Setup:: namespace.

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.