File Disk-5.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:

  1. status - boolean: true iff successful.
  2. errorMessage - string: if unsuccessful - the reason.
  3. 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 )
    end

    Example #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 )
    end

Return values:

  1. status - boolean: true iff successful.
  2. errorMessage - string: if unsuccessful - the reason.
  3. overwritten - boolean: true if pre-exisint file overwritten.
  4. dirsCreated - boolean: true if target dir had to be created.
  5. 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:

  1. status - boolean: true iff successful.
  2. 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:

  1. true iff deleted in its entirety.
  2. 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:

  1. status (boolean, always) true => disks in specified drives were successfully ejected.
  2. 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.
end

Parameters:

  • path:
  • type:
  • throwErrorIfWrongType:

Return values:

  1. boolean: true iff exists as specified type.
  2. 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:

  1. dir-path or nil.
  2. 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:

  1. folders - array of filenames, sorted.
  2. 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:

  1. status (boolean) true if files are same content-wise, false if different, nil if error.
  2. 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:

  1. true iff read-only.
  2. 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:

  1. true iff worked.
  2. error message iff didn't work.
Disk:makeReadOnly (path)
Make file read-only.

Parameters:

  • path:

Return values:

  1. true iff worked.
  2. error message iff didn't work.
Disk:makeReadWrite (path)
Make file read-write.

Parameters:

  • path:

Return values:

  1. true iff worked.
  2. 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:

  1. boolean: true iff successfully moved.
  2. 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:

  1. status - boolean: true iff successfully deleted. Hopefully it was moved to trash, but that is not guaranteed.
  2. 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:

  1. number of dir entries
  2. number of files (if any == false).
  3. 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:

  1. contents - string: non-nil if successful.
  2. 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:

  1. true iff successful.
  2. 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:

  1. true iff successful.
  2. error message iff failure.

Valid XHTML 1.0!