NAME
    File::Trash::Undoable - Trash files (with undo support)

VERSION
    version 0.04

SYNOPSIS
     # use the trash-u script

DESCRIPTION
    This module provides routines to trash files, with undo/redo support.
    Originally written to demonstrate/test Perinci::Sub::Gen::Undoable.

SEE ALSO
    *   gvfs-trash

        A command-line utility, part of the GNOME project.

    *   trash-cli, https://github.com/andreafrancia/trash-cli

        A Python-based command-line application. Also follows
        freedesktop.org trash specification.

    *   rmv, http://code.google.com/p/rmv/

        A bash script. Features undo ("rollback"). At the time of this
        writing, does not support per-filesystem trash (everything goes into
        home trash).

DESCRIPTION
    This module has Rinci metadata.

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

  empty_trash() -> [status, msg, result, meta]
    Empty trash.

    No arguments.

    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.

  list_trash_contents() -> [status, msg, result, meta]
    List contents of trash directory.

    No arguments.

    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.

  trash(%args) -> [status, msg, result, meta]
    Trash a file.

    Fixed state: path does not exist.

    Fixable state: path exists.

    This function supports undo operation. This function supports dry-run
    operation. This function is idempotent (repeated invocations with same
    arguments has the same effect as single invocation). This function
    requires transactions.

    Arguments ('*' denotes required arguments):

    *   path => *str*

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    *   -tx_action => *str*

        You currently can set this to 'rollback'. Usually you do not have to
        pass this yourself, Perinci::Access::InProcess will do it for you.
        For more details on transactions, see Rinci::function::Transaction.

    *   -tx_manager => *obj*

        Instance of transaction manager object, usually
        Perinci::Tx::Manager. Usually you do not have to pass this yourself,
        Perinci::Access::InProcess will do it for you. For more details on
        transactions, see Rinci::function::Transaction.

    *   -undo_action => *str*

        To undo, pass -undo_action=>'undo' to function. You will also need
        to pass -undo_data, unless you use transaction. For more details on
        undo protocol, see Rinci::function::Undo.

    *   -undo_data => *array*

        Required if you want undo and you do not use transaction. For more
        details on undo protocol, see Rinci::function::Undo.

    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.

  trash_files(%args) -> [status, msg, result, meta]
    Trash files (with undo support).

    This function supports undo operation. This function supports dry-run
    operation. This function is idempotent (repeated invocations with same
    arguments has the same effect as single invocation). This function
    requires transactions.

    Arguments ('*' denotes required arguments):

    *   files* => *array*

        Files/dirs to delete.

        Files must exist.

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    *   -tx_action => *str*

        You currently can set this to 'rollback'. Usually you do not have to
        pass this yourself, Perinci::Access::InProcess will do it for you.
        For more details on transactions, see Rinci::function::Transaction.

    *   -tx_manager => *obj*

        Instance of transaction manager object, usually
        Perinci::Tx::Manager. Usually you do not have to pass this yourself,
        Perinci::Access::InProcess will do it for you. For more details on
        transactions, see Rinci::function::Transaction.

    *   -undo_action => *str*

        To undo, pass -undo_action=>'undo' to function. You will also need
        to pass -undo_data, unless you use transaction. For more details on
        undo protocol, see Rinci::function::Undo.

    *   -undo_data => *array*

        Required if you want undo and you do not use transaction. For more
        details on undo protocol, see Rinci::function::Undo.

    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.

  untrash() -> [status, msg, result, meta]
    Untrash a file.

    Fixed state: path exists.

    Fixable state: Path does not exist (and entry for path is contained in
    trash; this bit is currently not implemented).

    This function supports undo operation. This function supports dry-run
    operation. This function is idempotent (repeated invocations with same
    arguments has the same effect as single invocation). This function
    requires transactions.

    No arguments.

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    *   -tx_action => *str*

        You currently can set this to 'rollback'. Usually you do not have to
        pass this yourself, Perinci::Access::InProcess will do it for you.
        For more details on transactions, see Rinci::function::Transaction.

    *   -tx_manager => *obj*

        Instance of transaction manager object, usually
        Perinci::Tx::Manager. Usually you do not have to pass this yourself,
        Perinci::Access::InProcess will do it for you. For more details on
        transactions, see Rinci::function::Transaction.

    *   -undo_action => *str*

        To undo, pass -undo_action=>'undo' to function. You will also need
        to pass -undo_data, unless you use transaction. For more details on
        undo protocol, see Rinci::function::Undo.

    *   -undo_data => *array*

        Required if you want undo and you do not use transaction. For more
        details on undo protocol, see Rinci::function::Undo.

    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.

