File `fhFileUtils.lua`

Functions

copyFile (sPath, sDestination, bOverwrite)	Copies an existing file and returns true if file copied OK
copyFolder (sPath, sDestination)	Copies an existing folder and returns true if folder copied OK Will NOT copy on top of an existing folder
createFolder (sPath)	Creates a folder and returns true if folder created
createTextFile (sPath, bOverwrite, bUnicode, sContents, iBits)	Creates a text file with optional contents and returns true if file created
deleteFile (sPath, bForce)	Deletes existing file and returns true if file deleted
deleteFolder (sPath, bForce)	Deletes a folder and all its contents and returns true if folder deleted
fileExists (sPath)	Returns true if specified file exists
fileGetContents (sFileName)	Loads the content of any existing file into a string.
filePutContents (sFileName, sContents, bOverwrite, bOK, sError)	Saves the content a string to a file.
folderExists (sPath)	Returns true if specified folder exists
getDateCreated (sPath)	Return the date a file/folder was created as UNIX epoch seconds since 01/01/1970.
getDateModified (sPath)	Return the date a file/folder was modified as UNIX epoch seconds since 01/01/1970.
getFileFolderDetails (sPath)	Return details of a single file or folder For the specified file or folder, the type,path,shortname, shortpath, created (date as a string), createdepoch (as an epoch time), modified (date as a string) , modifiedepoch (as an epoch time), size and attributes are returned in a table.
getFolderContents (sPath, bRecurse)	Return table of all files and folders in a specified folder.
getParent (sPath)	Returns Parent folder for Path Provided.
moveFile (sPath, sDestination)	Moves an existing file and returns true if file moved OK.
moveFolder (sPath, sDestination)	Moves an existing folder and returns true if moved OK
readTextFile (sPath, bUnicode, iBits)	Reads an existing text file and returns a string of the contents.
renameFile (sPath, sNewName)	Renames an existing file in its current location and returns true if file renamed
renameFolder (sPath, sNewName)	Renames an existing folder in its current location and returns true if folder renamed
splitPath (sPath)	Returns table of Path Parts drive=drive letter with colon, abs_path=fully resolved path, parent = parent folder,filename= file name excluding path,basename=file name excluding path and extension,ext=extension Notes: path is not validated only split; network file paths are not supported.

Functions

copyFile (sPath, sDestination, bOverwrite)

Copies an existing file and returns true if file copied OK

Parameters:

sPath: Full File Path
sDestination: Full File or Folder Path. Folders must have a trailing path separator
bOverwrite: Overwrite existing file. Defaults to false. Note a read-only file cannot be overwritten.

Return values:

True if file copied
string Error if operation failed ('File not found', 'Destination folder not found','File already exists','Operation failed' )

copyFolder (sPath, sDestination)

Copies an existing folder and returns true if folder copied OK Will NOT copy on top of an existing folder

Parameters:

sPath: Full Folder Path
sDestination: Full Folder Path

Return values:

True if folder copied as a sub-folder of destination folder
string Error if operation failed ('Folder not found', 'Destination folder not found', 'Folder already exists','Operation failed' )

createFolder (sPath)

Creates a folder and returns true if folder created

Parameters:

sPath: Full Folder Path

Return values:

True if folder created
String Error if the operation failed ('Parent folder not found', 'Bad folder name', 'Folder already exists', 'Operation failed')

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

Creates a text file with optional contents and returns true if file created

Parameters:

sPath: Full File Path
bOverwrite: True if existing file can be overwritten. Defaults to true
bUnicode: True if file should be a Unicode file. Defaults to false (ANSI file)
sContents: Optional contents to be written to file. Defaults to an empty string
iBits: 8 for a UTF8 file or 16 for a UTF16 file. Defaults to 8 (UTF8)

Return values:

boolean True if file created
string Error if file was not created ('Bad parameters', 'Destination folder not found', 'Bad file name','File already exists', 'Operation failed' )

deleteFile (sPath, bForce)

Deletes existing file and returns true if file deleted

Parameters:

sPath: Full File Path
bForce: True if read only files are to be deleted. Defaults to false

Return values:

True if file deleted
string Error if operation failed ('Read-only file', 'File not found', 'Operation failed')

deleteFolder (sPath, bForce)

Deletes a folder and all its contents and returns true if folder deleted

Parameters:

sPath: Full Folder Path
bForce: True if read only files within the folder are to be deleted. Defaults to false

Return values:

True if folder deleted
string Error if operation failed ('Folder not found', 'Operation failed')

fileExists (sPath)

Returns true if specified file exists

Parameters:

sPath: Full File Path

Return value:

True if file exists

fileGetContents (sFileName)

Loads the content of any existing file into a string. It is read as binary so can be used for graphics or other binary files. For text files it is recommended to use readTextFile

Parameters:

sFileName: Filename with path

Return values:

string File Contents or False if the operation failed
string Error if operation failed ('File not found', 'Operation failed')

filePutContents (sFileName, sContents, bOverwrite, bOK, sError)

Saves the content a string to a file. It is saved as binary so can be used so can be used for graphics or other binary files. For text files it is recommended to use createTextFile

Parameters:

sFileName: Filename with path
sContents: string to write
bOverwrite: True if an existing file should be overwritten. Defaults to false. A read only file cannot be overwritten
bOK: true is operation succeeded
sError: Error string if the operation failed ('Destination folder not found', 'Bad file name, ' 'File already exists', 'Operation failed'))

folderExists (sPath)

Returns true if specified folder exists

Parameters:

sPath: Full Folder Path

Return value:

True if folder exists

getDateCreated (sPath)

Return the date a file/folder was created as UNIX epoch seconds since 01/01/1970.

Parameters:

sPath: Full File Path

Return values:

integer date that a file was modified as UNIX epoch seconds since 01/01/1970, or false if sPath is invalid
string Error if the operation failed ('File or Folder not found', or 'Operation Failed')

getDateModified (sPath)

Return the date a file/folder was modified as UNIX epoch seconds since 01/01/1970.

Parameters:

sPath: Full File Path

Return values:

integer date that a file was modified as UNIX epoch seconds since 01/01/1970, or false if sPath is invalid
string Error if the operation failed ('File or Folder not found', or 'Operation Failed')

getFileFolderDetails (sPath)

Return details of a single file or folder For the specified file or folder, the type,path,shortname, shortpath, created (date as a string), createdepoch (as an epoch time), modified (date as a string) , modifiedepoch (as an epoch time), size and attributes are returned in a table.

Parameters:

sPath: Full File or Folder Path

Return values:

Table of Results or False if specified folder not found
string Error if the operation failed ('File or Folder not found' or 'Operation failed')

getFolderContents (sPath, bRecurse)

Return table of all files and folders in a specified folder. For each item the type,path,shortname, shortpath, created date (as a string),modified date (as a string),size and attributes are returned in a table.

Parameters:

sPath: Full Folder Path
bRecurse: boolean Recurse subfolders (defaults to false)

Return values:

Table of Results or False if specified folder not found
string Error if the operation failed ('Folder not found')

getParent (sPath)

Returns Parent folder for Path Provided. Note: path is not validated

Parameters:

sPath: Full File or Folder Path

Return values:

Path of Parent Folder or False if path not found
string Error ('Path not found')

moveFile (sPath, sDestination)

Moves an existing file and returns true if file moved OK.

Parameters:

sPath: Full File Path
sDestination: Full File or Folder Path. Folders must have a trailing path separator

Return values:

True if file moved
string Error string if the operation failed ('File not found', 'Destination folder not found', 'File already exists', 'Operation failed')

moveFolder (sPath, sDestination)

Moves an existing folder and returns true if moved OK

Parameters:

sPath: Full Folder Path
sDestination: Full Folder Path

Return values:

boolean True if folder moved
strError string if the operation failed ('Folder not found', 'Destination folder not found', 'Folder already exists', 'Operation failed')

readTextFile (sPath, bUnicode, iBits)

Reads an existing text file and returns a string of the contents. No checks are made that the specified file is of the correct format

Parameters:

sPath: Full File Path
bUnicode: True if file is a Unicode file. Defaults to false (ANSI file)
iBits: 8 for a UTF8 file or 16 for a UTF16 file. Defaults to 8 (UTF8)

Return values:

string Contents of the file or false if the operation failed
string Error string if the operation failed ('File not found','Bad parameters', 'Operation failed')

renameFile (sPath, sNewName)

Renames an existing file in its current location and returns true if file renamed

Parameters:

sPath: Full File Path
sNewName: New File Name including Extension

Return values:

True if file renamed
string Error if operation failed ('File not found', 'File already exists', 'Bad file name', 'Operation failed')

renameFolder (sPath, sNewName)

Renames an existing folder in its current location and returns true if folder renamed

Parameters:

sPath: Full Folder Path
sNewName: New Folder Name

Return values:

True if folder renamed
string Error if operation failed ('Folder not found', Folder already exists', 'Bad folder name', 'Operation failed')

splitPath (sPath)

Returns table of Path Parts
drive=drive letter with colon, abs_path=fully resolved path, parent = parent folder,filename= file name excluding path,basename=file name excluding path and extension,ext=extension
Notes: path is not validated only split; network file paths are not supported.

Parameters:

sPath: Full File or Folder Path (excludng network file paths)

Return value:

Path Elements table

LuaDoc

Files

File fhFileUtils.lua

Functions

Functions

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return value:

Parameters:

Return values:

Parameters:

Parameters:

Return value:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return values:

Parameters:

Return value:

File `fhFileUtils.lua`