s = CS.File.copy(source := ..., destination := ...ʃ, overwrite := ...ʅ)
Argument | Description | Types / Required |
source | The source path or sharable URI of file(s) to copy. | string, array
required |
destination | The destination path, or directory, of the file(s) to be copied. | string
required |
overwrite | If true, destination file(s) are replaced if they already exist.
The default value is true. | boolean
not required |
The
File.copy action copies one or more files. It can copy a single file to another file, or it can copy a group of files to a directory. The
source argument, detailing the files to copy, can be specified as:
- A single string representing a file path or sharable URI.
- A single string using wildcard characters "*" and "?" to specify a group of files.
- An array of strings containing strings specified in one of the two above forms.
If multiple files are specified when evaluating source, the destination must be a directory where all of the files are copied, using their original names. When copying only a single file, if destination is a directory, the source file is copied to that directory using its original name; otherwise, destination is considered the path of the new, copied file.
The
overwrite flag lets you conditionally copy files based on whether a file already exists. If set to
false, an exception is thrown if the destination file already exists.
The action returns the fully evaluated destination path, or array of destination paths, of the copied file(s). An array of strings containing the paths is returned unless source is a single string that does not contain wildcard characters, in which case a single string is returned.
The action throws an exception if any of its arguments are not specified in a valid form, or if:
- The source file(s) do not exist.
- Multiple source files are specified but the destination is not a directory.
- The destination file exists but the overwrite flag is false.
In the following examples, the return value is displayed as
JSON:
Copying a single file, specifying the output path as a file: "C:/AMO/Honey (copy).txt"
CS.File.copy({
source: "C:/AMO/Honey.txt",
destination: "C:/AMO/Honey (copy).txt"
});
Copying a single file, demonstrating behavior differences when the destination path exists:
- If "Tastes" already exists as a directory: "C:/AMO/Tastes/Honey.txt"
- If "Tastes" already exists as a file, or does not exist at all: "C:/AMO/Tastes"
CS.File.copy({
source: "C:/AMO/Honey.txt",
destination: "C:/AMO/Tastes"
});
Copying a single file that uses a wildcard to a directory: [ "C:/AMO/Tastes/Honey.txt" ]
CS.File.copy({
source: "C:/AMO/Honey.*",
destination: "C:/AMO/Tastes/"
});
Copying multiple files to a directory: [ "C:/AMO/Tastes/Honey.txt", "C:/AMO/Tastes/Milk.txt" ]
CS.File.copy({
source: [
"C:/AMO/Honey.*",
"C:/AMO/Milk.txt",
],
destination: "C:/AMO/Tastes/"
});