Copy_file

copy_file! copies one file to another path.

Overview

Use copy_file! when you want to copy a file from one path to another:

copy_file!("drafts/post.md", "public/post.md")

copy_file!("drafts/post.md", "public/post.md")

The first argument is the source path. The second argument is the destination path.

Because this changes the filesystem, copy_file! uses bang syntax.

Bang Required

copy_file! is a filesystem mutation operation. The ! is required:

copy_file!("source.txt", "backup/source.txt")

copy_file!("source.txt", "backup/source.txt")

The non-bang form is rejected:

copy_file("source.txt", "backup/source.txt")
/// error: M0001 mutation-operator-required

copy_file("source.txt", "backup/source.txt")
/// error: M0001 mutation-operator-required

The bang says, plainly: this call changes something outside the program.

Source and Destination

The source path must point to the file you want to copy:

source | "content/about.md"
dest | "public/about.md"

copy_file!(source, dest)

source | "content/about.md"
dest | "public/about.md"

copy_file!(source, dest)

The destination path is where the copy should be written.

Parent Directories

copy_file! creates missing parent directories for the destination:

copy_file!("avatar.png", "public/images/users/avatar.png")

copy_file!("avatar.png", "public/images/users/avatar.png")

If public/images/users does not exist, Goblin creates it before copying the file.

Existing Destination

If the destination file already exists, copy_file! replaces it:

copy_file!("new-config.json", "config.json")

copy_file!("new-config.json", "config.json")

Use File Exists first if you want to avoid overwriting:

if file_exists("config.json")
    :say("config already exists")
else
    copy_file!("new-config.json", "config.json")
end

if file_exists("config.json")
    :say("config already exists")
else
    copy_file!("new-config.json", "config.json")
end

Return Value

copy_file! returns unit:

result | copy_file!("source.txt", "copy.txt")

:say(result.vt)  /// unit

result | copy_file!("source.txt", "copy.txt")

:say(result.vt)  /// unit

Its purpose is the filesystem side effect.

Signature

copy_file!(source, destination)

copy_file!(source, destination)

Returns unit.

Errors

copy_file! requires exactly two arguments:

copy_file!("source.txt")
/// error: R0301 wrong-arity

copy_file!("source.txt")
/// error: R0301 wrong-arity

Both arguments must be strings:

copy_file!(42, "copy.txt")
/// error: T0205 type-mismatch

copy_file!(42, "copy.txt")
/// error: T0205 type-mismatch

The non-bang form raises a mutation error:

copy_file("source.txt", "copy.txt")
/// error: M0001 mutation-operator-required

copy_file("source.txt", "copy.txt")
/// error: M0001 mutation-operator-required

Filesystem problems raise a filesystem I/O error:

copy_file!("missing.txt", "copy.txt")
/// error: FS0001 filesystem-io

copy_file!("missing.txt", "copy.txt")
/// error: FS0001 filesystem-io

This can happen when the source file does not exist, the destination cannot be written, or permissions prevent the copy.