fhFileUtils

Reference for the fhFileUtils module, a set of functions for Family Historian plugins to work with extended-character-set file and folder names, and to read and write text files with extended names and extended-character-set contents (using Windows scripting via Scripting.FileSystemObject).

• Version: 1.9
• Author: Calico Pie
• Contributors: Jane Taubman, Helen Wright
• Licence: MIT (see plugin licence)
• Dependencies: luacom

All functions below are accessed via the fhFileUtils table, e.g. fhFileUtils.fileExists(...).

Error convention: every function that can fail returns two values: the result (or false on failure) and an error string on failure. The specific error strings a function can return are listed per function below.

Emulator note: functions that read file dates, sizes or attributes are not supported when running under an emulator (e.g. Crossover) and will return an error in that case — see getFolderContents, getDateModified, getDateCreated, getFileFolderDetails.

Contents

• Existence & path checks
• Folder operations
• File operations
• Text file I/O
• Binary file I/O
• File/folder details & dates
• Attributes
• Path utilities

Existence & path checks

fhFileUtils.folderExists(sPath)

• Parameters: sPath — full folder path
• Returns: boolean — true if the folder exists

fhFileUtils.fileExists(sPath)

• Parameters: sPath — full file path
• Returns: boolean — true if the file exists

fhFileUtils.getParent(sPath)

Returns the parent folder for the given path. The path itself is not validated.

• Parameters: sPath — full file or folder path
• Returns: parent folder path, or false on failure
• Errors: 'Path not found'

Folder operations

fhFileUtils.getFolderContents(sPath, bRecurse, bExtend)

Returns a table of all files and folders in the specified folder. For each item, path, created, modified, size and attributes are included.

• Parameters:
  • sPath — full folder path
  • bRecurse — recurse into subfolders; defaults to false
  • bExtend — return extended details (dates, size, attributes); defaults to true. If false (required in emulator environments), dates/attributes are set to "" and size to 0
• Returns: table of results, or false on failure
• Errors: 'Folder not found', 'Extended details not supported in an emulator', 'Operation failed' (with luacom code)

fhFileUtils.createFolder(sPath)

• Parameters: sPath — full folder path
• Returns: true if created, or false on failure
• Errors: 'Parent folder not found', 'Bad folder name', 'Folder already exists', 'Operation failed' (with luacom code)

fhFileUtils.deleteFolder(sPath, bForce)

Deletes a folder and all its contents.

• Parameters:
  • sPath — full folder path
  • bForce — delete even if it contains read-only files; defaults to false
• Returns: true if deleted, or false on failure
• Errors: 'Folder not found', 'Operation failed' (with luacom code)

fhFileUtils.renameFolder(sPath, sNewName)

Renames a folder in its current location.

• Parameters: sPath — full folder path; sNewName — new folder name
• Returns: true if renamed, or false on failure
• Errors: 'Folder not found', 'Folder already exists', 'Bad folder name', 'Operation failed' (with luacom code)

fhFileUtils.copyFolder(sPath, sDestination)

Copies a folder as a sub-folder of the destination folder. Will not copy on top of an existing folder.

• Parameters: sPath — full folder path to copy; sDestination — full destination folder path
• Returns: true if copied, or false on failure
• Errors: 'Folder not found', 'Destination folder not found', 'Folder already exists', 'Operation failed' (with luacom code)

fhFileUtils.moveFolder(sPath, sDestination)

• Parameters: sPath — full folder path; sDestination — full destination folder path
• Returns: true if moved, or false on failure
• Errors: 'Folder not found', 'Destination folder not found', 'Folder already exists', 'Operation failed' (with luacom code)

File operations

fhFileUtils.deleteFile(sPath, bForce)

• Parameters:
  • sPath — full file path
  • bForce — delete even if read-only; defaults to false
• Returns: true if deleted, or false on failure
• Errors: 'Read-only file', 'File not found', 'Operation failed' (with luacom code)

fhFileUtils.renameFile(sPath, sNewName)

Renames a file in its current location.

• Parameters: sPath — full file path; sNewName — new file name including extension
• Returns: true if renamed, or false on failure
• Errors: 'File not found', 'File already exists', 'Bad file name', 'Operation failed' (with luacom code)

fhFileUtils.copyFile(sPath, sDestination, bOverwrite)

• Parameters:
  • sPath — full file path to copy
  • sDestination — full file or folder path (folders must have a trailing path separator)
  • bOverwrite — overwrite an existing file; defaults to false. A read-only file can never be overwritten
• Returns: true if copied, or false on failure
• Errors: 'File not found', 'Destination folder not found', 'File already exists', 'Operation failed' (with luacom code)

fhFileUtils.moveFile(sPath, sDestination)

• Parameters:
  • sPath — full file path
  • sDestination — full file or folder path (folders must have a trailing path separator)
• Returns: true if moved, or false on failure
• Errors: 'File not found', 'Destination folder not found', 'File already exists', 'Operation failed' (with luacom code)

Text file I/O

fhFileUtils.createTextFile(sPath, bOverwrite, bUnicode, sContents, iBits)

Creates a text file with optional contents.

• Parameters:
  • sPath — full file path
  • bOverwrite — overwrite an existing file; defaults to false
  • bUnicode — create a Unicode file rather than ANSI; defaults to false
  • sContents — contents to write; defaults to ""
  • iBits — 8 for UTF-8 or 16 for UTF-16; defaults to 8. 16 requires bUnicode = true
• Returns: true if created, or false on failure
• Errors: 'Bad parameters' (e.g. iBits == 16 without bUnicode), 'Destination folder not found', 'Bad file name', 'File already exists', 'Operation failed'

fhFileUtils.readTextFile(sPath, bUnicode, iBits)

Reads an existing text file. No checks are made that the file is actually in the specified format.

• Parameters:
  • sPath — full file path
  • bUnicode — file is Unicode rather than ANSI; defaults to false
  • iBits — 8 for UTF-8 or 16 for UTF-16; defaults to 8
• Returns: file contents as a string, or false on failure
• Errors: 'File not found', 'Bad parameters', 'Operation failed'

Binary file I/O

fhFileUtils.fileGetContents(sFileName)

Loads the contents of any existing file into a string, reading it as binary — safe for graphics or other binary files. For text files, prefer readTextFile.

• Parameters: sFileName — filename with path
• Returns: file contents as a string, or false on failure
• Errors: 'File not found', 'Operation failed' (with luacom code)

fhFileUtils.filePutContents(sFileName, sContents, bOverwrite)

Saves a string to a file, writing it as binary — safe for graphics or other binary files. For text files, prefer createTextFile.

• Parameters:
  • sFileName — filename with path
  • sContents — string to write
  • bOverwrite — overwrite an existing file; defaults to false. A read-only file can never be overwritten
• Returns: true if written, or false on failure
• Errors: 'Destination folder not found', 'Bad file name', 'File already exists', 'Operation failed'

File/folder details & dates

fhFileUtils.getDateModified(sPath)

• Parameters: sPath — full file (or folder) path
• Returns: modification date as UNIX epoch seconds, or false on failure
• Errors: 'Modified date not supported in an emulator', 'File or folder not found', 'Operation failed' (with luacom code)

fhFileUtils.getDateCreated(sPath)

• Parameters: sPath — full file (or folder) path
• Returns: creation date as UNIX epoch seconds, or false on failure
• Errors: 'Created date not supported in an emulator', 'File or folder not found', 'Operation failed' (with luacom code)

fhFileUtils.getFileFolderDetails(sPath, bExtend)

Returns details for a single file or folder: path, created/createdepoch, modified/modifiedepoch, size and attributes.

• Parameters:
  • sPath — full file or folder path
  • bExtend — return extended details (dates, size, attributes); defaults to true. If false (required in emulator environments), dates/attributes are set to "" and size to 0
• Returns: table of results, or false on failure
• Errors: 'Extended details not available in emulator', 'File or folder not found', 'Operation failed' (with luacom code)

Attributes

fhFileUtils.isFileReadOnly(sPath)

• Parameters: sPath — full file path
• Returns: "Read only" or "Read write", or false on failure
• Errors: 'File not found', 'Operation failed' (with luacom code)

fhFileUtils.setFileReadOnly(sPath, setReadOnly)

Sets or clears a file's read-only attribute.

• Parameters: sPath — full file path; setReadOnly — true to set read-only, false to clear it
• Returns: true if successful, or false on failure
• Errors: 'File not found', 'Operation failed' (with luacom code)

Path utilities

fhFileUtils.splitPath(sPath)

Splits a path into its component parts. The path is not validated, only split — except that for a network share path (\\computer\share) the share must exist for drive to be returned.

• Parameters: sPath — full file or folder path
• Returns: table with drive, abs_path (fully resolved path), parent, filename (excluding path), basename (excluding path and extension), ext

fhFileUtils.buildPath(sFolderPath, sAppend)

Builds a path string from a folder path and a filename or sub-path. Does not validate the input or the result.

• Parameters: sFolderPath — full path to a folder; sAppend — file or folder name to append
• Returns: constructed path string

Internal helpers (not exported)

Used internally by the module but not part of the fhFileUtils public table:

• saveLuacomErrorHandling() / testLuacomErrorState() — disable luacom's abort-on-error around a COM call, then report whether it succeeded
• nameValid(sName) — checks a file/folder name doesn't contain invalid characters (<>:"/\|?*)
• fileReadOnly(sPath) — checks the read-only attribute bit on a file
• getName(sPath) — returns the file name portion of a path
• getDetails(f, bExtend) — builds the common {name, created, path, size, modified, attributes} table used by getFolderContents and getFileFolderDetails
• EpochTime(dDate) — converts a COM date object to UNIX epoch seconds