Namespace LrFileUtils

Summary

Functions

LrFileUtils.chooseUniqueFileName( path )

Creates a path string that (if written to) would not overwrite any existing file. If the given path does not refer to an existing file, the path is returned unchanged. If the path does refer to an existing file, the last component of the path is altered until the newly generated path no longer refers to any existing file. The filename extension is not changed in any case. The method of alteration is not specified, but is intended to make it obvious to the user that the path was generated. For example: LrFileUtils.chooseUniqueFileName( "/MyDir/MyFile.jpg" ) might return "/MyDir/MyFile-2.jpg".

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The initial path.

Return value

(string) The unique path name derived from the given path.

LrFileUtils.copy( srcPath, destPath )

Copies a file from one location to another. The parent directory at the destination must already exist; if it does not, the copy operation fails. The operation also fails if there is already a file with the same name as the source file at the destination location.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. srcPath

(string) The path to the existing source file.

2. destPath

(string) The path to a location for the copy.

Return value

(Boolean) True on success. On failure, can return a second parameter indicating the reason.

LrFileUtils.createAllDirectories( path )

Creates a directory at a given path, recursively creating any parent directories that do not already exist.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path of the new directory.

Return value

(Boolean) True if any parent directory was created; false if all parents already existed.

LrFileUtils.createDirectory( path )

Creates a directory at a given path.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path of the new directory. The parent directory must already exist.

LrFileUtils.delete( path )

Immediately deletes the file or directory at a given path. If the path refers to a directory, all of the contents are deleted. Use with care; in most cases, moveToTrash() is preferred.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(Boolean) True on success. On failure, can return a second parameter indicating the reason.

LrFileUtils.directoryEntries( pathToFolder )

Iterates through the files and folder that are immediate children of the folder. Use this in a for loop, like this:

for filePath in LrFileUtils.directoryEntries( pathToFolder ) do ... end

This iterator includes any folders that are inside this folder, but does not look inside those folders. A file handle will remain open for the folder until the for loop completes normally. Do not use break to exit this for loop.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. pathToFolder

(string) The folder to examine

LrFileUtils.exists( path )

Reports whether a given path indicates an existing file or directory.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(string or Boolean) The string 'file' or 'directory' if the path corresponds to an existing entity on disk, false if not.

LrFileUtils.fileAttributes( path )

Retrieves the file attributes for the file or directory at a given path.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(table) A set of file attributes, or, if the file does not exist, an empty table. The file attributes include:

• fileSize: File size in bytes
• fileCreationDate: The creation date.
• fileModificationDate: The modification date.

Dates are expressed as a number of seconds since midnight GMT, January 1, 2001.

See also

LrDate

LrFileUtils.files( pathToFolder )

Iterates through the files that are immediate children of the folder. Use this in a for loop, like this:

for filePath in LrFileUtils.files( pathToFolder ) do ... end

This iterator skips any folders that are inside this folder. A file handle will remain open for the folder until the for loop completes normally. Do not use break to exit this for loop.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. pathToFolder

(string) The folder to examine.

LrFileUtils.hasNoVisibleFiles( path )

Reports whether a given path refers to a directory that contains no visible files. The definition of "visible" differs in Mac OS and in Windows, but generally means what is shown to the user in Finder or Windows Explorer.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The directory path.

Return value

(Boolean) True if the path is for a directory that contains no visible files; false otherwise.

LrFileUtils.isDeletable( path )

Reports whether a file or directory can be deleted.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(Boolean) True if there is a file that can be deleted at this path; false if not.

LrFileUtils.isEmptyDirectory( path )

Reports whether a given path refers to a directory that contains no files.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The directory path.

Return value

(Boolean) True if the path is for a directory that contains no files; false otherwise.

LrFileUtils.isReadable( path )

Reports whether a path indicates a readable disk file.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(Boolean) True if there is a file that can be read at this path; false if not.

LrFileUtils.isWritable( path )

Reports whether a path indicates a writable disk file.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(Boolean) True if there is a file that can be written to at this path; false if not.

LrFileUtils.makeFileWritable( path )

Makes a file writeable, if possible.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(Boolean) True if the file is writeable after the call, false if not.

LrFileUtils.move( srcPath, destPath )

Moves a file from one location to another. The parent directory at the destination must already exist; if it does not, the move operation fails. The operation also fails if there is already a file with the same name as the source file at the destination location.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. srcPath

(string) The path to the existing source file.

2. destPath

(string) The path to a new location for the file.

Return value

(Boolean) True on success. On failure, can return a second parameter indicating the reason.

LrFileUtils.moveToTrash( path )

Moves a file or directory to the system trash or recycle bin.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(Boolean) True on success. If false, the function returns a second parameter indicating the reason.

LrFileUtils.pathsAreOnSameVolume( path1, path2 )

Reports whether two paths are on the same volume (which means you could move from one path to the other without copying).

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path1

(string) The first path.

2. path2

(string) The second path.

Return value

(Boolean) True if the two paths are on the same volume, false otherwise.

LrFileUtils.readFile( path )

Reads the contents of a file into memory. Use this in preference to the built-in Lua io namespace if the path you are reading might contain non-ASCII characters.

First supported in version 2.2 of the Lightroom SDK.

Parameters

1. path

(string) The file to read.

Return value

(string) The contents of the file.

LrFileUtils.recursiveDirectoryEntries( pathToFolder )

Iterates through all files and folders that are anywhere inside the folder. Use this in a for loop, like this:

for filePath in LrFileUtils.recursiveDirectoryEntries( pathToFolder ) do ... end

This iterator includes any folders that are inside this folder, as well as the contained files. A file handle will remain open for the folder until the for loop completes normally. Do not use break to exit this for loop.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. pathToFolder

(string) The folder to examine

LrFileUtils.recursiveFiles( pathToFolder )

Iterates through all files that are anywhere inside the folder. Use this in a for loop, like this:

for filePath in LrFileUtils.recursiveFiles( pathToFolder ) do ... end

This iterator looks inside all folders inside this folder, but does not return the folder entries themselves, only the contained files. A file handle will remain open for the folder until the for loop completes normally. Do not use break to exit this for loop.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. pathToFolder

(string) The folder to examine

LrFileUtils.resolveAlias( path )

Resolves an alias (in Mac OS) or shortcut (in Windows).

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) path to examine

Return value

(string) If path points to an alias or shortcut file, returns the path pointed to by that alias or shortcut. If it is not an alias or shortcut, returns the path unchanged.

LrFileUtils.resolveAllAliases( path )

Resolves all aliases and shortcuts in this path and returns the resulting path (that is, the actual file location). Resolves aliases at any location in the path string. Can be time consuming.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(string) The fully resolved path.

LrFileUtils.volumeAttributes( path )

Retrieves information about the disk volume containing a given path.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. path

(string) The path.

Return value

(table) A table containing these attributes:

• fileSystemSize: The total number of bytes on the disk.
• fileSystemFreeSize: The number of available bytes on the disk.