DeleteFile(file$[, t])

DeleteFile(file$[, callback, userdata, pattern$, matchdir])

DeleteFile() supports several 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 DeleteFile().

The following table fields are recognized by this function:

Recursive:

By default, DeleteFile() will recurse into all subdirectories and delete them if file$ specifies a directory. If you don't want that, set this tag to False. (V9.0)

Force:

If this tag is set to True, write- or delete-protected files will automatically be deleted without asking the callback function first. Note that if there is no callback function and Force is set to False (the default), DeleteFile() will just skip all write- or delete-protected files. Defaults to False. (V9.0)

MustExist:

By default, DeleteFile() will silently fail if you specify a file or directory that does not exist in file$. No error will be generated in this case. If you want DeleteFile() to show an error instead, set this tag to True. (V9.0)

Pattern:

You can pass a filter pattern in this table field. In that case, DeleteFile() will only delete the files that match the specified pattern. For example, passing *.jpg in Pattern will only delete files that use the .jpg file extension. Of course, using a filter pattern makes only sense if you pass a directory in file$. Note that for historical reasons, the pattern specified in Pattern will also be matched against all subdirectories that are to be deleted. 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, DeleteFile() will only recurse into subdirectories that match the specified filter pattern. If it is set to False, DeleteFile() 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)

FailOnError:

By default, DeleteFile() will fail if a file or directory can't be deleted. You can change this behaviour by setting FailOnError to False. In that case, DeleteFile() won't fail if a file or directory can't be deleted but instead your callback function, if there is one, will be notified using the #DELETEFILE_FAILED message and your callback must tell DeleteFile() how to proceed (retry, continue, abort). See below to learn how to set up a callback function for DeleteFile(). Note that FailOnError isn't used when file$ is just a single file. It is only used when deleting complete directories or multiple files using patterns. FailOnError defaults to True. (V9.0)

Async:

If this is set to True, DeleteFile() 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 DeleteFile() 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 filesystem adapters that should be asked to handle the operation. This must be set 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 filesystem 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)

Callback:

For fine-tuned control of the delete operation, you can specify a callback function that will be called on various occasions. For example, DeleteFile() will call it from time to time so that you can update a progress bar. It will also be called when a file is delete-protected to ask you how to proceed. If there is no callback function, DeleteFile() will silently skip delete-protected files. The callback function receives one argument: A table that contains more information.

The following callback types are available:

#DELETEFILE_UNPROTECT:

The callback function of type #DELETEFILE_UNPROTECT will be called if a file that should be deleted is 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 delete operation will be completely aborted.

Action:

#DELETEFILE_UNPROTECT

File:

Contains the delete protected file that is to be unprotected. (fully qualified path)

UserData:

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

(V2.0)

#DELETEFILE_STATUS:

This callback will be run whenever a file is deleted. This is useful for updating a status bar, for example. The callback function of type #DELETEFILE_STATUS should normally return False. If it returns True, the delete operation will be aborted.

Action:

#DELETEFILE_STATUS

File:

Contains the fully qualified path of the file that is to be deleted next

UserData:

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

(V2.0)

#DELETEFILE_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 #DELETEFILE_FAILED will be called whenever a delete operation has failed. It has to return True to abort the delete operation, False to continue even though an error has occurred or -1 to retry the delete operation that has just failed. The following fields will be set in the table parameter that is passed to your callback function:

Action:

#DELETEFILE_FAILED

File:

Contains the fully qualified path of the file that could not be deleted.

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. (V3.1)

file$

Filename or directory to delete

t

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

DeleteFile("FooBar")

Function p_DeleteCallback(msg)
  Switch msg.action
  Case #DELETEFILE_STATUS:
    DebugPrint("Now deleting", FilePart(msg.file))
  Case #DELETEFILE_UNPROTECT:
    Return(SystemRequest("Hollywood", FilePart(msg.file) ..
      " is delete protected!\nDo you want me to unprotect it?",
      "Yes|No"))
  EndSwitch
  Return(False)
EndFunction
DeleteFile("TestDir", {Callback = p_DeleteCallback})