Section Files

Files utility functions

Class

Class	Summary
INI	Rough INI configuration file reader and writer.

Summary

Return type	Function and summary
	CreateFolders(string fullPath) Create all folders that build a path.
table	FileReadLines(string path, int stringEncoding, int crlf, boolean errorIfNotFound) Syntaxic sugar to read all lines of a file, and return a table of them.
	FileWriteLines(string path, table lines, function formatFunc, int stringEncoding, int crlf) Syntaxic sugar to writes a table of strings as lines in a file.
table	GetFilesInFolder(string folder, string mask, boolean recursive, boolean fullPath, boolean caseInsensitive, boolean ignoreDiacritics) `BrowseFolder(...)` needs a callback function, and has a bug: here is a fixed and simplified version.
	PlayThemeSound(string soundName, boolean wait) Play a "theme" sound, if set to active.
string	ScriptReadVersion(string file) Read the version of a script.
string, string	SplitPath(string path) Split a path into directory and file, no file if path ends by a '/'.

Functions

PlayThemeSound(string soundName, boolean wait)

Play a "theme" sound, if set to active.

Parameter	Type	Default	Description
soundName	string		One of `"open", "close", "bell", "error", "confirmation", "message", "toggle-off", "toggle-on", "window-slide"`
wait	boolean	false	If `true`, wait until sound file if played to continue script execution. If `false`, script continue immediately. A new call to `PlayThemeSound(...)` or `Application.PlayWavFile(...)` may interrupt and replace the first played sound.

GetFilesInFolder(string folder, string mask, boolean recursive, boolean fullPath, boolean caseInsensitive, boolean ignoreDiacritics)

BrowseFolder(...) needs a callback function, and has a bug: here is a fixed and simplified version.

Parameter	Type	Default	Description
folder	string		Folder name
mask	string	"."	Mask to search file, e.g. `".myr", "a.*"`
recursive	boolean	false	`true` to browse sub-folders
fullPath	boolean	false	`true` returns the full path, `false` returns only file names
caseInsensitive	boolean	true on Windows, false else	Is the matching with `mask` case-insensitive? If `true`, `.pdf` will match `file.pdf` and `file.PDF`, and return both files If `false`, `.pdf` will match only `file.pdf` but not `file.PDF`, and then return only one of these files
ignoreDiacritics	boolean	false

Return: table: File names: array of string, in alphabetic order

CreateFolders(string fullPath)

Create all folders that build a path.

The MyrScript CreateFolder(...) (without ending 's') function doesn't create subfolders. This function (with an ending 's') call as many times as needed the CreateFolder(...).
Another way to explain:
CreateFolders("C:/a/b") ensure that folder "a" is created in "C:", then next "b" is created in "a".
If fullPath already exist, nothing is done.

Parameter	Type	Default	Description
fullPath	string		Full or relative path, e.g. `"C:/a/b", "/path/to/folder/", "subfolder/123"`

Return: Error message as string or 0 if no error.

FileReadLines(string path, int stringEncoding, int crlf, boolean errorIfNotFound)

Syntaxic sugar to read all lines of a file, and return a table of them.

Note:

encoding is supposed to be UTF-8 BOM and lines terminated by Macintosh CR.
Convenient for small files when full content have to been read and stored.

Parameter	Type	Default	Description
path	string		The full path of the file to read.
stringEncoding	int	UTF8_STR_ENCODING	String encoding constant from MSDefine, e.g. `UNKNOWN_STR_ENCODING`
crlf	int	MAC_CR	Carriage return constant from MSDefine, `MAC_CR, LINUX_CR, WIN_CR, UNKNOWN_CR`
errorIfNotFound	boolean		(defaut=true) Throw error if file is not found, else return an empty table.

Return

table: Table of string, one item per line

Errors

if argument is not a string

if file can't be read

See

FileWriteLines

Example



 local lines = FileReadLines("/path/to/myConfigFile.txt")
 print(lines[1]) -- first line of the config file

FileWriteLines(string path, table lines, function formatFunc, int stringEncoding, int crlf)

Syntaxic sugar to writes a table of strings as lines in a file.

Collection and Map are also handled, and an optional formating function can transform lines before writing. Notes:

The file is overwritten,
Encoding is UTF-8 BOM and lines are terminated by Macintosh CR.

Parameter	Type	Default	Description
path	string		The full path of the file to write
lines	table		The lines to write, can be a table, a Collection or a Map
formatFunc	function	nil	Formatting function that receive two arguments and must return a string that will be written into the file. Arguments are: if simple table: int table index and the value, if Collection: a int counter and a Collection item, if Map, key and value (an entry of the Map). If formatFunc is `nil` then table and Collection prints their values, Map prints key and values separated by a space char.
stringEncoding	int	UTF8_STR_ENCODING	String encoding constant from MSDefine, e.g. `HTML_STR_ENCODING`
crlf	int	MAC_CR	Carriage return constant from MSDefine, `MAC_CR, LINUX_CR, WIN_CR, UNKNOWN_CR`

Errors

if arguments have bad type.

if file can't be written.

See

FileReadLines

Examples



 local lines = FileReadLines("/path/to/myConfigFile.txt")
 lines[1] = "0" -- change a value in the config file
 FileWriteLines("/path/to/myConfigFile.txt", lines)



 local map = Map:new("number", "string", SORT_ASCENDING)
 map:put(1, "one"); map:put(2, "two"); map:put(3, "three")
  FileWriteLines("/path/to/file/count.txt", map,
   function(key,value) return tostring(key).."="..strupper(value); end)
 )
 -- outputs 3 lines 1=ONE, 2=TWO and 3=THREE

ScriptReadVersion(string file)

Read the version of a script.

Look for the --VERSION: x.y in first 30 lines of source code.

Parameter	Type	Default	Description
file	string		Script file name (or full path)

Return: string: A version in the x.y.z or yyyyMMdd form (as source code), or nil if file doesn't exist or version not found.

SplitPath(string path)

Split a path into directory and file, no file if path ends by a '/'.

Parameter	Type	Default	Description
path	string		path

Returns: string: directory; string: file name