File Disk-10.lua
Functions
Disk:assureAllDirectories (targetDir) | Attempts to assure sub-directory tree will exist upon return. |
Disk:closeFile (fileHandle) | Closes a file protectedly. |
Disk:copyBigFile (sourcePath, destPath, createDestDirsIfNecessary, overwriteDestFileIfNecessary, avoidUnnecessaryUpdate, progressScope, timeCheckIsEnough) | Like copy-file, except for files big enough to warrant a progress-indicator - like video. |
Disk:copyFile (sourcePath, destPath, createDestDirsIfNecessary, overwriteDestFileIfNecessary, avoidUnnecessaryUpdate, timeCheckIsEnough, call, captionPrefix) | Copies source file to destination, as specified. |
Disk:copyTree (src, dest, excl, overwrite, timeCheckIsEnough, call) | Copy files in folder to target destination, maintaining directory structure. |
Disk:deleteFileConfirm (path) | Deletes a file and confirms deletion instead of relying on status code returned from delete. |
Disk:deleteFolderOrFile (path) | Deletes specified folder or file. |
Disk:deleteTree (tree, trash, leaveRoot, call) | Delete directory tree. |
Disk:eject (drives) | Eject disks. |
Disk:exists (p) | Same as lr-file-utils--exists |
Disk:existsAs (path, type, throwErrorIfWrongType) | Determines if path exists as a specified type. |
Disk:existsAsDirectory (path) | Determine if path is to a directory. |
Disk:existsAsFile (path) | Determine if path is to a file. |
Disk:getAppDataDir (winSubdir) | Get system-wide app-data location. |
Disk:getByte (file) | Reads one byte from a file. |
Disk:getDouble (file, bigEndian) | Reads one quadruple byte word from a file. |
Disk:getExactPath (_path) | Get exact path, case and all, to file (typically) already known to exist, but case unknown. |
Disk:getFileCreationDate (file) | Get file created date - file need not be known to exist. |
Disk:getFileModificationDate (file) | Get file modification date - file need not be known to exist. |
Disk:getFileSize (file) | Get file size - file need not be known to exist. |
Disk:getFoldersAndFiles (dir, folderSortFunc, fileSortFunc) | Get folders and files, separated and sorted. |
Disk:getWord (file, bigEndian) | Reads one double-byte word from a file. |
Disk:isChangedSince (srcFile, lastMod) | Determine if source file has cnanged since specified date. |
Disk:isDirEmpty (dir) | Determine if directory is empty. |
Disk:isFileSame (path1, path2, timeCheckIsEnough) | Determine if target file content is different than source file content. |
Disk:isNewer (srcFile, targFile) | Determine if source file is newer than target file. |
Disk:isReadOnly (path) | Determine if file is read-only. |
Disk:isReadWrite (path) | Determine if file is read-write. |
Disk:makeExecutable (path) | Make Mac file executable. |
Disk:makeReadOnly (path) | Make file read-only. |
Disk:makeReadWrite (path) | Make file read-write. |
Disk:moveFile (sourcePath, destPath, createDestDirsIfNecessary, overwriteDestFileIfNecessary, avoidUnnecessaryUpdate, timeCheckIsEnough) | Moves source file to destination, or rename. |
Disk:moveFolderOrFile (oldPath, newPath) | Move or rename a file. |
Disk:moveToTrash (path) | Moves specified folder or file to trash/recycle bin. |
Disk:new (t) | Constructor for new instance. |
Disk:newClass (t) | Constructor for extending class. |
Disk:numOfDirEntries (path, any) | Counts directory entries. |
Disk:readFile (filePath) | Get entire contents of file. |
Disk:readTextFile (filePath) | Reads as binary, then gets rid of the zero characters which look like string term char to Lr. |
Disk:writeFile (filePath, contents, dontAssumeDir, disallowOverwrite) | Write entire contents of file. |
Disk:writeFileAtomically (filePath, contents, dontAssumeDir, disallowOverwrite) | Write atomically (write to temp file, then move to final destination). |
Functions
- Disk:assureAllDirectories (targetDir)
-
Attempts to assure sub-directory tree will exist upon return.
Parameters:
-
targetDir
:
Usage:
throws error if target not directory.
Examples:
success, qual, created = fsoassureAllDirectories( target )
if success then
if created then
nCreated = nCreated + 1
if qual then
logMessageLine( qual )
else
logMessageLine( "Directories created: " .. target )
end
else
nAlready = nAlready + 1
end
-- do things to target...
else
assert( created == false )
assert( str:is( qual ) )
logError( "Unable to assure destination directory - " .. qual )
-- abort function...
end
Return values:
- status - boolean: true iff successful.
- errorMessage - string: if unsuccessful - the reason.
- created - boolean: true if dir not pre-existing (one or more dir in path was actually created).
-
- Disk:closeFile (fileHandle)
-
Closes a file protectedly.
Initial motivation: to keep file close errors from interrupting export services - better to log error and keep going.
Parameters:
-
fileHandle
:
Return value:
- true iff successful.
-
- Disk:copyBigFile (sourcePath, destPath, createDestDirsIfNecessary, overwriteDestFileIfNecessary, avoidUnnecessaryUpdate, progressScope, timeCheckIsEnough)
-
Like copy-file, except for files big enough to warrant a progress-indicator - like video.
Parameters:
-
sourcePath
: -
destPath
: -
createDestDirsIfNecessary
: -
overwriteDestFileIfNecessary
: -
avoidUnnecessaryUpdate
: -
progressScope
: -
timeCheckIsEnough
:
Usage:
deprecated - copyFile has big-file auto-detect built in.
The other motivation for this function is file transfer efficiency. For some reason, Lightrooms file copy/mover can be extremely inefficient sometimes.
I probably should find someway to move the decision for use out of the app and into this class, until then...
parameters are the same as for copying normal file, except progress-scope is new...
-
- Disk:copyFile (sourcePath, destPath, createDestDirsIfNecessary, overwriteDestFileIfNecessary, avoidUnnecessaryUpdate, timeCheckIsEnough, call, captionPrefix)
-
Copies source file to destination, as specified.
Initial motivation: frustration with most API's file copy functions which do not specify what they do if source does not exist, or target does... are directories created?...
Parameters:
-
sourcePath
: source file path. -
destPath
: destination file path. -
createDestDirsIfNecessary
: boolean: default is nil.- nil: dest-dir-tree not checked for, just does whatever lr version would in that respect.
- false: checks for dest-dirs, and if not there, returns failure and explanation.
- true: checks for dest-dirs, and if not there, creates them. -
overwriteDestFileIfNecessary
: boolean: default is nil.- nil: dest-file not checked for, just does whatever lr version would in that respect.
- false: checks for dest-file, and if there, returns failure and explanation.
- true: checks for dest-dirs, and if there, deletes it before copying. -
avoidUnnecessaryUpdate
: boolean: true => pre-read file before writing, and don't write if no new data. Default is false. -
timeCheckIsEnough
: -
call
: -
captionPrefix
:
Usage:
Assumes source file exists - bombs if not.
Example #1: sts, expl, ov, dirs, touched = fso:copyFile( source, dest, true, true )
if sts then
if expl then
logMessage( expl ) -- test mode log
else
logMessage( "File copied. " ) -- normal mode log.
end
if ov then
logMessage( "Target file overwritten. " )
elseif dirs then
logMessage( "Target dirs created. " )
end
logMessageLine()
else
logError( "File copy failed: " .. expl )
endExample #2: sts, expl = fso:copyFile( source, dest )
if sts then
if expl then
logMessageLine( expl ) -- test mode log
else
logMessageLine( "File copied. " ) -- normal mode log.
end
else
logError( "File copy failed: " .. expl )
endReturn values:
- status - boolean: true iff successful.
- errorMessage - string: if unsuccessful - the reason.
- overwritten - boolean: true if pre-exisint file overwritten.
- dirsCreated - boolean: true if target dir had to be created.
- touched - boolean: true if target file existed with exact same contents already.
-
- Disk:copyTree (src, dest, excl, overwrite, timeCheckIsEnough, call)
-
Copy files in folder to target destination, maintaining directory structure.
Parameters:
-
src
: -
dest
: -
excl
: -
overwrite
: -
timeCheckIsEnough
: -
call
:
Usage:
does not pre-check destination, so if an exact dup is desired, pre-delete dest.
-
- Disk:deleteFileConfirm (path)
-
Deletes a file and confirms deletion instead of relying on status code returned from delete.
Born from a case I had where a recently deleted file was not able to be immediately written, or something like that.
Parameters:
-
path
:
Usage:
****** MUST be called from a task.
Return value:
- *** Unlike most methods of file-system, this one throws an error if cant delete (instead of returning status).
-
- Disk:deleteFolderOrFile (path)
-
Deletes specified folder or file.
Thin wrapper around lr-file-utils - delete.
Initial motivation is "historical".
Parameters:
-
path
:
Usage:
Not sure what happens if specified item does not exist - same as lr version.
Return values:
- status - boolean: true iff successful.
- errorMessage - string: if unsuccessful - the reason.
-
- Disk:deleteTree (tree, trash, leaveRoot, call)
-
Delete directory tree.
Parameters:
-
tree
: (string, required) path to tree dir. -
trash
: (boolean, default=false) move-to-trash or delete permanently? -
leaveRoot
: (boolean, default=false) leave-root dir or remove it too? -
call
: (Call object, default=nil) pass call to make op cancelable.
Usage:
All contents are deleted - does not need to be empty to start with.
Throws error only upon attempt to delete root or nil tree arg.
Return values:
- true iff deleted in its entirety.
- error message if not deleted.
-
- Disk:eject (drives)
-
Eject disks.
Parameters:
-
drives
: (array of strings, required) drives to eject.
Usage:
callers responsibility to assure disks are ejectable.
Return values:
- status (boolean, always) true => disks in specified drives were successfully ejected.
- message (string, always) qualitative message for display to user or logging.
-
- Disk:exists (p)
-
Same as lr-file-utils--exists
Parameters:
-
p
:
-
- Disk:existsAs (path, type, throwErrorIfWrongType)
-
Determines if path exists as a specified type.
One motivation: Sometimes its not good enough to know if a path exists or not, but what type it exists as. Adobe realized this, which is why their exists method returns a type string. Problem is, one can not compare it directly to an expected type because if it does not exist, a "boolean being compared to string" error is thrown. Thus, a nested conditional is required: 1. does it exist, 2. What type. This method allows calling context to use a single conditional.
Side Benefit: Forces calling context to deal with the possibility that a folder may exist where a file is expected, or vice versa, which if un-detected, may cause strange and difficult to diagnose behavior / errors.
Examples:
path = "/asdf"
existsAsFile, isDir = fso:existsAs( path, 'file' ) -- return opposite type else not found if not type.
if existsAsFile then
-- process file
elseif isDir then
assert( dirType == 'directory', "Path is to directory: " .. path )
-- process path is to directory, not file.
else
-- process file not found.
end
existsAsDir = fso:existsAs( path, 'directory', true ) -- returns true or false, bombs if path is to file.
if existsAsDir then
-- process directory
else
-- process dir not found.
endParameters:
-
path
: -
type
: -
throwErrorIfWrongType
:
Return values:
- boolean: true iff exists as specified type.
- IF NOT THROWING ERROR UPON WRONG TYPE: returns the other type.
-
- Disk:existsAsDirectory (path)
-
Determine if path is to a directory.
Parameters:
-
path
: directory path
Usage:
The directory entry must either not exist, or be a directory, else an error is thrown.
-
- Disk:existsAsFile (path)
-
Determine if path is to a file.
Parameters:
-
path
: file path
Usage:
The directory entry must either not exist, or be a file, else an error is thrown.
-
- Disk:getAppDataDir (winSubdir)
-
Get system-wide app-data location.
Parameters:
-
winSubdir
: ignored on Mac, pass "Local" on Windows, if desired (default is "Roaming").
Usage:
Windows: C:\Users\{user}\AppData\Roaming
Macintosh: /Users/{user}/Library/Application Support
Return values:
- dir-path or nil.
- err-msg if dir-path nil.
-
- Disk:getByte (file)
-
Reads one byte from a file.
Parameters:
-
file
:
Return value:
- Numerical value of the byte, else nil for eof.
-
- Disk:getDouble (file, bigEndian)
-
Reads one quadruple byte word from a file.
Parameters:
-
file
: -
bigEndian
:
Return value:
- it
-
- Disk:getExactPath (_path)
-
Get exact path, case and all, to file (typically) already known to exist, but case unknown.
Handles condition when exact case of file on disk is important - like for looking up in lr-catalog.
Parameters:
-
_path
:
Usage:
Very inefficient for large directories - best confined to small dirs if possible.
Return value:
- path if exists, else nil.
-
- Disk:getFileCreationDate (file)
-
Get file created date - file need not be known to exist.
Parameters:
-
file
:
-
- Disk:getFileModificationDate (file)
-
Get file modification date - file need not be known to exist.
Parameters:
-
file
:
-
- Disk:getFileSize (file)
-
Get file size - file need not be known to exist.
Parameters:
-
file
:
-
- Disk:getFoldersAndFiles (dir, folderSortFunc, fileSortFunc)
-
Get folders and files, separated and sorted.
Parameters:
-
dir
: -
folderSortFunc
: -
fileSortFunc
:
Return values:
- folders - array of filenames, sorted.
- files - array of filenames, sorted.
-
- Disk:getWord (file, bigEndian)
-
Reads one double-byte word from a file.
Parameters:
-
file
: -
bigEndian
:
Usage:
Machines have native endian, but that's overridden by file type, e.g. jpeg is big-endian on all platforms.
Return value:
- Numerical value of the byte, else nil for eof.
-
- Disk:isChangedSince (srcFile, lastMod)
-
Determine if source file has cnanged since specified date.
Parameters:
-
srcFile
: -
lastMod
:
Usage:
both files are expected to exist.
-
- Disk:isDirEmpty (dir)
-
Determine if directory is empty.
Parameters:
-
dir
:
-
- Disk:isFileSame (path1, path2, timeCheckIsEnough)
-
Determine if target file content is different than source file content.
Parameters:
-
path1
: -
path2
: -
timeCheckIsEnough
:
Usage:
Keeps unchanged targets from being updated if not necessary.
Works in protected mode to avoid bombing upon i-o failure.
Tests a relatively small block first, then does larger ones from there on out.
Examples:
local same, problem = fso-isFileSame( path1, path2 )
if not problem then
if same
-- dont update
else
-- update target
end
else
-- process error message
end
Return values:
- status (boolean) true if files are same content-wise, false if different, nil if error.
- error message (string) if error.
-
- Disk:isNewer (srcFile, targFile)
-
Determine if source file is newer than target file.
Parameters:
-
srcFile
: -
targFile
:
Usage:
both files are expected to exist.
-
- Disk:isReadOnly (path)
-
Determine if file is read-only.
Parameters:
-
path
:
Return values:
- true iff read-only.
- error message iff didn't work.
-
- Disk:isReadWrite (path)
-
Determine if file is read-write.
Parameters:
-
path
:
Usage:
Convenience function: same as not-read-only.
-
- Disk:makeExecutable (path)
-
Make Mac file executable.
Parameters:
-
path
:
Return values:
- true iff worked.
- error message iff didn't work.
-
- Disk:makeReadOnly (path)
-
Make file read-only.
Parameters:
-
path
:
Return values:
- true iff worked.
- error message iff didn't work.
-
- Disk:makeReadWrite (path)
-
Make file read-write.
Parameters:
-
path
:
Return values:
- true iff worked.
- error message iff didn't work.
-
- Disk:moveFile (sourcePath, destPath, createDestDirsIfNecessary, overwriteDestFileIfNecessary, avoidUnnecessaryUpdate, timeCheckIsEnough)
-
Moves source file to destination, or rename.
Parameters:
-
sourcePath
: -
destPath
: -
createDestDirsIfNecessary
: -
overwriteDestFileIfNecessary
: -
avoidUnnecessaryUpdate
: -
timeCheckIsEnough
:
Usage:
Assumes source file exists - throws error if not.
See copy-file for additional info.
-
- Disk:moveFolderOrFile (oldPath, newPath)
-
Move or rename a file.
One motivation: to handle case of silent failure of Lr version.
Parameters:
-
oldPath
: -
newPath
:
Usage:
Lr doc says its just for files, but experience dictates it works on folders as well.
*** SOURCE EXISTENCE NOT PRE-CHECKED, NOR IS TARGET PRE-EXISTENCE - SO CHECK BEFORE CALLING IF DESIRED.
Return values:
- boolean: true iff successfully moved.
- error message if unable to move.
-
- Disk:moveToTrash (path)
-
Moves specified folder or file to trash/recycle bin.
Initial motivation: lr-move-to-trash was bombing when file was on network share.
If move-to-trash not supported, then file will simply be deleted.
Parameters:
-
path
:
Usage:
Note move-to-trash returns false with no reason if specified file does not exist, not sure about delete.
this function however will consider it a success if file not found, so it is strongly recommended to check existence before calling to avoid erroneous
messages about what got moved-to-trash/deleted.Return values:
- status - boolean: true iff successfully deleted. Hopefully it was moved to trash, but that is not guaranteed.
- qualifier - string: if item not deleted/moved-to-trash - the reason. if deleted, it's extra qualification.
-
- Disk:new (t)
-
Constructor for new instance.
Parameters:
-
t
:
-
- Disk:newClass (t)
-
Constructor for extending class.
Parameters:
-
t
:
-
- Disk:numOfDirEntries (path, any)
-
Counts directory entries.
Initial motivation - in case preparation needs be done before loop processing dir entries.
Parameters:
-
path
: (string, required) dir -
any
:
Usage:
Assumes specified directory is known to exist: does not check.
any (boolean, default=true) any kind of directory entry. If false, returns #files & #dirs too.
Return values:
- number of dir entries
- number of files (if any == false).
- number of dirs (if any == false).
-
- Disk:readFile (filePath)
-
Get entire contents of file.
Same as Lightroom's lr-file-utils-read-file, except returns error message upon failure instead of throwing error.
Parameters:
-
filePath
: absolute path to file.
Usage:
Uses binary mode, which can also be used for reading text files as long as you don't mind zeros and CR/LF in your string...
@3/Aug/2011 10:37 works with non-ascii chars in path (previous versions did NOT).
Return values:
- contents - string: non-nil if successful.
- comment - string: explanation for failure.
-
- Disk:readTextFile (filePath)
-
Reads as binary, then gets rid of the zero characters which look like string term char to Lr.
Parameters:
-
filePath
: absolute path to file.
Return value:
- binary file contents sans zero bytes.
-
- Disk:writeFile (filePath, contents, dontAssumeDir, disallowOverwrite)
-
Write entire contents of file.
Runs in protected mode so export does not die upon first io failure.
Parameters:
-
filePath
: (string, required) The (absolute) file path. -
contents
: (string, required) The contents to be. -
dontAssumeDir
: (boolean, default=false) If true, directory will be pre-assured, else error if target directory does not exist. -
disallowOverwrite
: (boolean, default=false) If true, an error will be thrown if target file already exists.
Usage:
Dunno how this works out when file-path contains non-ascii characters. ###2
Return values:
- true iff successful.
- error message if failure.
-
- Disk:writeFileAtomically (filePath, contents, dontAssumeDir, disallowOverwrite)
-
Write atomically (write to temp file, then move to final destination).
Parameters:
-
filePath
: (string, required) The (absolute) file path. -
contents
: (string, required) The contents to be. -
dontAssumeDir
: (boolean, default=false) If true, directory will be pre-assured, else error if target directory does not exist. -
disallowOverwrite
: (boolean, default=false) If true, an error will be thrown if target file already exists.
Usage:
Dunno how this works out when file-path contains non-ascii characters. ###2
Only throws error if bug in method - external (io) errors will result in status returned.
Return values:
- true iff successful.
- error message iff failure.
-