File Object

Under macOS sandboxing a macro will not have access to most files. Please see the section “Sandbox” for more.

File Type Commands

File.isEquivalentPaths path, otherPath v2.1.1

Returns @true if the file paths are equivalent, otherwise @false. Two paths are considered equivalent if they describe the same location. For example, if your macOS account user name is eskimo, then these are equivalent:

~/Documents/file.txt

/Users/eskimo/Documents/file.txt

Some other path normalizations are handled, like removing empty path components, but this does not include resolving aliases or symlinks in the path.

File.existsAtPath path v1.1

Returns @true if a file or folder exists at the given path, otherwise @false.

File.isFolderAtPath path v1.1

Returns @true if the file both exists and is a folder, otherwise @false.

File.canReadFromPath path v1.1

Returns @true if the file or folder exists and permissions allow data to be read from it, otherwise @false.

File.canWriteToPath path v1.1

Returns @true if the file or folder exists and permissions allow data to be written to it, otherwise @false.

File.canExecutePath path v1.3

Returns @true if the file exists and permissions allow it to be executed, otherwise @false.

File.namesInFolderAtPath path v1.1

Returns an array of the names of all files and subfolders contained inside the folder at the given path. This list does not include hidden files. If the given path is not a folder or does not exist, returns an empty array.

File.infoAtPath path v1.2

Returns a hash with various pieces of information about the file at the given path. The following pieces of information are set in the returned hash:

If no file exists at the given path, the @undefined value is returned.

File.revealPathInFinder path v1.2

Shows and selects the file or folder at the given path in the Finder.

File.createFolderWithPath path v1.1

Creates a new folder at the given path. If any parent folders do not exist, they are also created. Returns @true if the folder was successfully created or the folder already exists, otherwise @false.

File.moveFromPathToPath sourcePath, destinationPath v1.2

Moves the file from the source path to the destination path. If the source is a folder then all files in that folder are copied to the destination (including all nested sub-folders). The destination must not exist. Returns @true if the move was a success, or @false on failure.

Note: this command can also be used to do simple file renames. In that case the folder for the source and destination paths is the same, only the last path component is different, eg:

File.moveFromPathToPath ‘~/Desktop/old.rtf’, ‘~/Desktop/new.rtf’

File.copyFromPathToPath sourcePath, destinationPath v1.1

Copies the file from the source path to the destination path. If the source is a folder then all files in that folder are copied to the destination (including all nested sub-folders). The destination must not exist. Returns @true if the copy was made, or @false on failure.

File.uniqueNameInFolderAtPath name, folderPath v2.0

Returns a possibly modified version of name, so that it is unique in the given folder. If the given folder does not exist, an error is displayed.

File.uniqueFilePath filePath v3.1

Returns a possibly modified version of the given path, so that the last path component (eg: the file name) is unique in its enclosing folder. If the given path doesn’t exist, then returns it without modification.

File.temporaryPathWithName name v1.1

Returns a full path to a unique temporary file that does not exist at the time the command was executed. The returned path will always have the same file extension as the given name, but the actual name might be different.

If your macro creates a file or folder at the returned location, your macro is also responsible for deleting it.

File.readDataFromPath path v1.1

Returns the contents of the file that exists at the specified path. The contents are read and returned as an uninterpreted Data object. Returns the @undefined value if the command fails.

File.writeDataToPath data, path v1.1

Overwrites the file at the specified path with the given data. If the file does not exist, then creates it. Any intermediate folders that do not exist are also created. Returns @true if the data was written, otherwise @false.

File.appendDataToPath data, path v1.1

Appends the given data to the file at the specified path. If the file does not exist, then creates it. Returns @true if the data was written, otherwise @false.

File.readStringFromPath path, [textEncodingName] v2.1.2

Returns the contents of the file as a plain text string, ignoring the file format. This command returns the @undefined value if the read fails. If you want to read the file as formatted text, use the Document object’s open commands instead. 

On input, the given textEncodingName is used to interpret the file’s data. This should be an IANA text encoding name. If the encoding argument is omitted (or is the empty string), then a text encoding is chosen automatically using a variety of factors (the file’s text encoding xattr, UTF byte order marks, etc).

If a textEncodingName is specified, then upon return it will be updated to contain the actual text encoding that was used to read the data. This allows you to know the encoding used to interpret the bytes. For example:

$encoding = ""

$text = File.readStringFromPath("~/Documents/file.txt", $encoding)

Prompt "Read the file using $encoding. The text:", $text

File.writeStringToPath string, path, [textEncodingName] v2.1.2

Overwrites the file at the specified path with a plain text string. If the file does not exist, then creates it. Any intermediate folders that do not exist are also created. Returns @true if the string was written, otherwise @false.

Optionally an IANA text encoding name may be given, which is used to convert the string to a sequence of bytes. This command returns @false if the string cannot be encoded using the given text encoding. If the encoding argument is omitted, a text encoding is chosen automatically. 

File.trashPath path v1.1

Move the file (or the contents of the entire folder) at the given path to the current users’ Trash folder. Returns @true on success, or @false if the move could not be completed.

File.deletePath path v1.1

Immediately deletes the file (or the contents of the entire folder) at the given path. This operation is not undoable and should be used with great care. Returns @true on success, or @false if the deletion could not be completed.

File.isLinkAtPath path v1.3

Returns @true if the file at the given path is an alias or symlink (symbolic link) file, otherwise returns @false.

File.resolveLinkAtPath path v1.3

If the file at the given path is an alias or symlink (symbolic link), returns the path of the targeted file. If the file is not an alias or symlink, returns the original/given path.

File.createAliasAtPathFromPath destinationPath, sourcePath v1.3

Creates an alias file at the given destination that points to the source file. The source file must exist and the destination must not. Returns @true if the alias was created or @false if not.

File.createSymlinkAtPathFromPath destinationPath, sourcePath v1.3

Creates a symlink (symbolic link file) at the given destination that points to the source file. The source file must exist and the destination must not. Returns @true if the link was created or @false if not.