Name
CopyFile -- copy file or directory (V2.0)
Synopsis
CopyFile(src$, dst$[, newname$, func, userdata, pattern$, matchdir])
Function
This function copies the file or directory specified in src$ to the directory specified in dst$. Please note that you have to specify a directory, not a file, in dst$. If you would like to change the name of the file while copying it, use the optional newname$ argument. Obviously, this argument only makes sense when you specify a file in src$.

This function is powerful. It will fully recurse into all subdirectories and copy also the file attributes, date stamps and comments. If the destination directory does not exist, it will be created for you (even if it contains subdirectories that do not exist yet). All path specifications can be local to the current directory or qualified. You can also copy files to the current directory by specifying "" as dst$.

Starting with Hollywood 5.0, you can pass a filter pattern in the optional argument pattern$. In that case, CopyFile() will only copy the files that match the specified pattern. For example, passing *.jpg in pattern$ will only copy files that use the .jpg file extension. Of course, using a filter pattern makes only sense if you pass a directory in src$. The optional argument matchdir specifies whether or not the filter pattern should also be matched against subdirectories. If this is set to True, CopyFile() will only recurse into subdirectories that match the specified filter pattern. If it is set to False, CopyFile() will recurse into all subdirectories. For compatibility reasons, matchdir defaults to True, but most of the time you will want to pass False here because it usually does not make sense to match the file pattern against a directory name. For example, it does not make sense to match the *.jpg example from above against directories, too. The pattern specified in pattern$ must adhere to the pattern rules as described in the documentation of the MatchPattern() function. See MatchPattern for details.

The optional parameter func can be used to pass a callback function which will be called from time to time by CopyFile() so you can update a progress bar for example. The callback function gets also called if a destination file does already exist or is write/delete protected. The callback function receives one argument: A table that contains more information. The following callbacks are available:

Callback function type #COPYFILE_OVERWRITE:

Action:
#COPYFILE_OVERWRITE

Source:
Contains the fully qualified path of the file to copy.

Destination:
Contains the fully qualified path of the file that does already exist.

UserData:
Contains the value you passed in the userdata argument.

The callback function of type #COPYFILE_OVERWRITE has to return True if the file shall be overwritten or False if it shall be skipped. To abort the copy operation completely, return -1.

Callback function type #COPYFILE_UNPROTECT:

Action:
#COPYFILE_UNPROTECT

Destination:
Contains the write or delete protected destination file to be unprotected.

UserData:
Contains the value you passed in the userdata argument.

The callback function of type #COPYFILE_UNPROTECT will be called if the file that should be overwritten is write- or delete-protected. This callback function needs to return True, if it is okay to unprotect the file or False if it shall not be unprotected. If you return -1, the copy operation will be completely aborted.

Callback function type #COPYFILE_STATUS:

Action:
#COPYFILE_STATUS

Source:
Contains the fully qualified path of the file that is currently copied (source).

Destination:
Contains the fully qualified path of the file that is currently copied (destination).

Copied:
Contains the number of bytes that were already copied.

Filesize:
Contains the filesize of the source file.

UserData:
Contains the value you passed in the userdata argument.

The callback function of type #COPYFILE_STATUS should normally return False. If it returns True, the copy operation will be aborted.

Important note: If you do not specify a callback function, existing files will be silently overwritten. If they are write/delete protected, the copy function will skip them.

Starting with Hollywood 3.1 there is an optional argument called userdata. The value you specify here is passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the userdata argument you can easily pass data to your callback function. You can specify a value of any type in userdata. Numbers, strings, tables, and even functions can be passed as user data.

Inputs
src$
source file or directory to copy
dst$
destination directory
newname$
optional: new name for the file if src$ is a file; pass an empty string "" if you do not need this but want to specify a callback function
func
optional: function to ask when trouble appears
userdata
optional: user specific data to pass to callback function (V3.1)
pattern$
optional: filter pattern to use for determining which files to copy (V5.0)
matchdir
optional: whether or not to apply the filter pattern to directories also (defaults to True) (V5.0)
Example
CopyFile("image.png", "TestDir")
Copy the file "image.png" from the current directory to "TestDir".


CopyFile("Images", "Images_Bak")
Create a backup of the "Images" directory in the "Images_Bak" directory (the new directory will be created by this function automatically). All files including subdirectories will be copied to the new location.


CopyFile("Hollywood_Sources/WarpOS", "HW_BAK", "", Nil, Nil,
         "*.c;*.h", False)
Copies all source code and header files from Hollywood_Sources/WarpOS to HW_BAK.


Function p_CopyCallback(msg)
  Switch msg.action
  Case #COPYFILE_STATUS:
    DebugPrint("Now copying", FilePart(msg.source), "to",
               PathPart(msg.destination))
  Case #COPYFILE_OVERWRITE:
    Return(SystemRequest("Hollywood", FilePart(msg.destination) ..
      " does already exist!\nDo you want me to overwrite it?",
      "Yes|No"))
  Case #COPYFILE_UNPROTECT:
    Return(SystemRequest("Hollywood", FilePart(msg.destination) ..
      " is write/delete protected!\nDo you want me to unprotect it?",
      "Yes|No"))
  EndSwitch
  Return(False)
EndFunction
CopyFile("Images", "Copy_of_Images", "", p_CopyCallback)
Demonstrates the usage of a callback function.

Show TOC