withFileProtection<R> function

R withFileProtection<R>(List<String> protected, R action(), { String? workingDirectory, })

EXPERIMENTAL - use with caution and the api may change.

Allows you to nominate a list of files to be backed up before an operation commences and then restored once the operation completes.

Currently the files a protected by making a copy of each file/directory into a unique system temp directory and then moved back once the action has completed.

withFileProtection is safe to use in a nested fashion as each call to withFileProtection creates its own separate backup area.

If the VM aborts during execution of the action you will find the backed up files in the system temp directory under a directory named .withFileProtection'. You may need to use the time stamp to determine which directory is the right one if you have had mulitple failures. Under normal circumstances the temp directory is delete once the action completes.

The protected list can contain files, directories.

If the entry is a directory then all children (files and directories) are protected.

Entries in the protected list may be relative or absolute.

If protected contains a file or directory that doesn't exist and the action subsequently creates those entities, then those files and/or directories will be deleted after action completes.

This function can be useful for doing dry-run operations where you need to ensure the filesystem is restore to its prior state after the dry-run completes.

TODO: make this work for other than current drive under Windows

Implementation

///
/// [withFileProtection] is safe to use in a nested fashion as each call
/// to [withFileProtection] creates its own separate backup area.
///
/// If the VM aborts during execution of the [action] you will find
/// the backed up files in the system temp directory under a directory named
/// .withFileProtection'. You may need to use the time stamp to determine which
/// directory is the right one if you have had mulitple failures.
/// Under normal circumstances the temp directory is delete once the action
/// completes.
///
/// The [protected] list can contain files, directories.
///
/// If the entry is a directory then all children (files and directories)
/// are protected.
///
/// Entries in the [protected] list may be relative or absolute.
///
/// If [protected] contains a file or directory that doesn't exist
/// and the [action] subsequently creates those entities, then those files
/// and/or directories will be deleted after [action] completes.
///
/// This function can be useful for doing dry-run operations
/// where you need to ensure the filesystem is restore to its
/// prior state after the dry-run completes.
///
// ignore: flutter_style_todos
/// TODO: make this work for other than current drive under Windows
///
R withFileProtection<R>(
  List<String> protected,
  R Function() action, {
  String? workingDirectory,
}) =>
    waitForEx(
      // ignore: discarded_futures
      core.withFileProtection(
        protected,
        action,
        workingDirectory: workingDirectory,
      ),
    );