CopyFile(src$, dst$[, t])

CopyFile(src$, dst$[, newname$, func, userdata, pattern$, matchdir])

This function is powerful. It will fully recurse into all subdirectories and copy the file attributes, date stamps and comments as well. 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$.

CopyFile() supports many optional arguments. Before Hollywood 9.0, those had to be passed as optional parameters (see above). Since Hollywood 9.0, however, it is recommended to use the new syntax, which has a single optional table argument that can be used to pass one or more optional arguments to CopyFile().

The following table fields are recognized by this function:

NewName:

If you would like to change the name of the file while copying it, set this field to the desired new name for the file. Obviously, setting this field only makes sense when you specify a file in src$.

Pattern:

You can pass a filter pattern in this table field. 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$. Note that for historical reasons, the pattern specified in Pattern will also be matched against all subdirectories that are to be copied. If you don't want that, set the MatchDir table tag to False (see below). The pattern specified in Pattern must adhere to the pattern rules as described in the documentation of the MatchPattern() function. See MatchPattern for details. (V5.0)

MatchDir:

This table field specifies whether or not the filter pattern specified in 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 a file pattern against a directory name. For example, it does not make sense to match the *.jpg example from above against directories as well. (V5.0)

BufferSize:

This table field can be used to set the buffer size that should be used for copying files. The value passed here must be specified in bytes. The default is 16384, i.e. 16 kilobytes. (V9.0)

FailOnError:

By default, CopyFile() will fail when an error occurs. You can change this behaviour by setting FailOnError to False. In that case, CopyFile() won't fail on an error but instead your callback function, if there is one, will be notified using the #COPYFILE_FAILED message and your callback must tell CopyFile() how to proceed (retry, continue, abort). See below to learn how to set up a callback function for CopyFile(). FailOnError defaults to True. (V9.0)

Force:

If this tag is set to True, write- or delete-protected files will automatically be overwritten without asking the callback function first. Note that if there is no callback function and Force is set to False (the default), CopyFile() will fail if it can't overwrite a file because that file is write- or delete-protected. Defaults to False. (V9.0)

Async:

If this is set to True, CopyFile() will operate in asynchronous mode. This means that it will return immediately, passing an asynchronous operation handle to you. You can then use this asynchronous operation handle to finish the operation by repeatedly calling ContinueAsyncOperation() until it returns True. This is very useful in case your script needs to do something else while the operation is in progress, e.g. displaying a status animation or something similar. By putting CopyFile() into asynchronous mode, it is easily possible for your script to do something else while the operation is being processed. See ContinueAsyncOperation for details. Defaults to False. (V9.0)

Adapter:

This tag allows you to specify one or more file adapters that should be asked if they want to open the source file or directory. If you use this tag, you must set it to a string containing the name(s) of one or more adapter(s). Defaults to the adapter set using SetDefaultAdapter(). See Loaders and adapters for details. (V10.0)

UserTags:

This tag can be used to specify additional data that should be passed to file or directory adapters. If you use this tag, you must set it to a table of key-value pairs that contain the additional data that should be passed to plugins. See User tags for details. (V10.0)

DstAdapter:

This tag allows you to specify one or more filesystem adapters that should be asked to handle all operations on the side of the copy target. The filesystem adapter specified here will be responsible for creating directories and setting file and directory attributes, for example. This must be set to a string containing the name(s) of one or more adapter(s). Defaults to default. See Loaders and adapters for details. (V10.0)

DstUserTags:

This tag can be used to specify additional data that should be passed to filesystem adapters specified in DstAdapter. See above for details. If you use this tag, you must set it to a table of key-value pairs that contain the additional data that should be passed to plugins. See User tags for details. (V10.0)

Callback:

This table field can be used to pass a callback function which will be called by CopyFile() on various occasions, e.g. to allow you to update a progress bar for example. The callback function also gets called if a destination file already exists or is write/delete protected. The callback function receives one argument: A table that contains more information.

The following callback types are available:

#COPYFILE_OVERWRITE:

CopyFile() will run this callback to ask if a file can be overwritten. Your callback function 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. The following fields will be set in the table parameter that is passed to your callback function:

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 table field (see below).

#COPYFILE_UNPROTECT:

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 be skipped. If you return -1, the copy operation will be completely aborted.

Starting with Hollywood 9.0, your callback function can also return -2 to indicate that copying should still be attempted even though the file is write- or delete-protected. This, however, will typically lead to an error because write- or delete-protected files can't be overwritten without unprotecting them first. However, if you return -2 you can catch the ensuing error in your #COPYFILE_FAILED callback if you have set FailOnError to False (see above).

The following fields will be set in the table parameter that is passed to your callback function:

Action:

#COPYFILE_UNPROTECT

Destination:

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

UserData:

Contains the value you passed in the UserData table field (see below).

#COPYFILE_STATUS:

This callback function is run from time to time so that you can update a status bar or something similar. The callback function of type #COPYFILE_STATUS should normally return False. If it returns True, the copy operation will be aborted. The following fields will be set in the table parameter that is passed to your callback function:

Action:

#COPYFILE_STATUS

Source:

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

Destination:

Contains the fully qualified path of the file that is currently being written (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 table field (see below).

#COPYFILE_FAILED:

This callback can only be called if the FailOnError tag has been set to False (see above). In that case, the callback function of type #COPYFILE_FAILED will be called whenever a copy operation has failed. It has to return True to abort the copy operation, False to continue even though an error has occurred or -1 to retry the copy operation that has just failed. The following fields will be set in the table parameter that is passed to your callback function:

Action:

#COPYFILE_FAILED

Source:

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

Destination:

Contains the fully qualified path of the file that is currently being written (destination).

UserData:

Contains the value you passed in the UserData table field (see below).

(V9.0)

UserData:

This field can be used to pass an arbitrary value to your callback function. The value you specify here will be passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the UserData tag 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. Your callback will receive this data in the UserData field in the table that is passed to it. (V5.1)

src$

source file or directory to copy

dst$

destination directory

t

optional: table containing additional options (see above) (V9.0)

CopyFile("image.png", "TestDir")

CopyFile("Images", "Images_Bak")

CopyFile("Hollywood_Sources/WarpOS", "HW_BAK", {Pattern = "*.c;*.h",
  MatchDir = False})

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", {Callback = p_CopyCallback})