Add IO function for copying files and directories

[kings177]

Implement copy functionality to give Bend the ability to copy files and directories. This should support both single file copying and recursive directory copying.

1. copy(source, destination, recursive=False, overwrite=False)

@spec copy(str, str, bool, bool) -> Result[None, Error]

Copies a file or directory from the source path to the destination path.

Parameters

• source: Path of the file or directory to be copied
• destination: Path where the file or directory should be copied to
• recursive: If True, copies directories and their contents recursively. Ignored for single copies.
• overwrite: If True, overwrites the destination if it exists. If False, returns an error if the destination exists.

Returns Ok(None) if successful, or Err(reason) if an error occurs.

Possible (but not limited to) errors:

• FileNotFound: The source file or directory does not exist
• PermissionDenied: Lack of permission to read the source or write to the destination
• FileExists: The destination already exists and overwrite is False
• NotADirectory: The source is a directory but recursive is False

Examples

# Copy a file
result = copy("source.txt", "destination.txt")
# Ok(None)

# Copy and overwrite an existing file
result = copy("source.txt", "existing.txt", overwrite=True)
# Ok(None)

# Recursively copy a directory and its contents
result = copy("source_dir", "dest_dir", recursive=True)
# Ok(None)

# Try to copy to non-existing file or directory
result = copy("nonexistent, "dest")
# Err(FileNotFound)

# Try to copy to an existing destination without overwrite
result = copy("source.txt", "existing.txt")
# Err(FileExists)

# Try to copy a directory (non-recursively)
result = copy("source_dir", "dest_dir")
# Err(NotADirectory)

Considerations

• Handle symbolic links appropriately (whether to follow them or copy the link itself).
• Implement proper error handling and propagation.
• Consider preserving file metadata (permissions etc) during copying.
• Ensure the function can distinguish between files and directories without relying on separate stat calls.
• Be aware of potential issues with copying across different filesystems or drives.
• Implement appropriate logging for debugging.

Test cases to implement

1. Copy a small text file
2. Copy a large binary file
3. Recursively copy a directory with subdirectories and files
4. Attempt to copy a non-existent file or directory
5. Attempt to copy to a read-only destination
6. Copy a file or directory to an existing destination with and without overwrite flag
7. Copy a symbolic link (both the link itself and following the link)
8. Copy files and directories with various permission settings
9. Attempt to copy a directory non-recursively when it contains files or subdirectories
10. Copy a file using the recursive flag (should work the same as non-recursive)
11. Attempt to copy a file or directory into itself or its subdirectory