//
//------------------ DOK FILE --------------------------------------------------
+Header	fileLib
=pkg	bios
=title	Files
=short	files and file system
=desc
On PCs and mobile host, Minimacy has access to the host file system.
This library has simple functions such as [[load]] or [[save]], and lower level functions such as [[fileOpen]], [[fileRead]], ...
File paths are expected to use slash instead of backslash to separate the directories and the files.
Most of these functions run in a "worker": their thread is suspended while the operation is processed in another system thread. During the thread, other Minimacy threads continue.
//
//
//------------------ PROTO ----------------------------------------------------- SOURCE_EXTENSION
+Proto	SOURCE_EXTENSION
=type	Str
=mode	constant
=pkg	bios
=impl	mcy
=link	
=desc	
This constant contains the file extension for Minimacy source code files.
	> SOURCE_EXTENSION
>-> Str: ".mcy"
//
//
//------------------ PROTO ----------------------------------------------------- parentDir
+Proto	parentDir
=type	fun Str -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function considers that src is a path name, and returns the path of the parent directory.
It is a pure computation on strings, and does not check if src is a real path.
//
+arg	src
=type	Str
=desc	A string
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- fileClose
+Proto	fileClose
=type	fun a1{File} -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function closes the file, and returns true on success. It returns nil when the file is already closed.
//
+arg	file
=type	a1{File}
=desc	A file
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- fileInfo
+Proto	fileInfo
=type	fun Str -> FileInfo
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function retrieves information on the file path, or nil if the file does not exist.
//
+arg	path
=type	Str
=desc	A string
//
+arg	result
=type	FileInfo
=desc	A FileInfo structure or nil
//
//
//------------------ PROTO ----------------------------------------------------- fileInfoIsDir
+Proto	fileInfoIsDir
=type	fun FileInfo -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns true if src is a directory.
//
+arg	src
=type	FileInfo
=desc	A FileInfo structure
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- fileInfoName
+Proto	fileInfoName
=type	fun FileInfo -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function returns the name of the file defined by src. This is not always the full path, it depends on how the [[FileInfo]] structure has been computed.
Usually, such a structure is returned by [[fileListInfo]], [[dirListInfo]] or [[diskListInfo]]. These 3 functions are called with a path. The [[fileInfoName]] will start with the path, followed by the file name or the directory name.
	> fileInfoName (head (fileListInfo ("demo")))
>-> Str: "demo/demo.2d.polygon.mcy"
//
+arg	src
=type	FileInfo
=desc	A FileInfo structure
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- fileInfoSize
+Proto	fileInfoSize
=type	fun FileInfo -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the size of the file defined by src.
//
+arg	src
=type	FileInfo
=desc	A FileInfo structure
//
+arg	result
=type	Int
=desc	A positive integer
//
//
//------------------ PROTO ----------------------------------------------------- fileInfoUpdate
+Proto	fileInfoUpdate
=type	fun FileInfo -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the timestamp (seconds since 01/01/1970) of the file defined by src.
//
+arg	src
=type	FileInfo
=desc	A FileInfo structure
//
+arg	result
=type	Int
=desc	A positive integer
//
//
//------------------ PROTO ----------------------------------------------------- fileOpen
+Proto	fileOpen
=type	fun Str FileMode -> File
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function opens a file. It returns a [[File]] structure to be used with [[fileRead]], [[fileWrite]], [[fileClose]], fil[[eSize.
The mode defines how to open the file: read-only, read and write, rewrite from scratch, append. See [[FileMode]] for more information.
//
+arg	fileName
=type	Str
=desc	A file path
//
+arg	mode
=type	FileMode
=desc	A mode
//
+arg	result
=type	File
=desc	A file structure
//
//
//------------------ PROTO ----------------------------------------------------- fileRead
+Proto	fileRead
=type	fun a1{File} Int Int -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function reads a number of bytes from the file.
The argument seek makes it possible to specify the position in the file. If nil, the reading will start from the current file pointer.
The function returns a string with the read bytes. Its size should be len, except if the end of the file is reached.
The file pointer is updated at the end of the operation.
//
+arg	file
=type	a1{File}
=desc	A file
//
+arg	seek
=type	Int
=desc	A position in the file or nil
//
+arg	len
=type	Int
=desc	A number of bytes to read
//
+arg	result
=type	Str
=desc	The string made of read bytes.
//
//
//------------------ PROTO ----------------------------------------------------- fileSize
+Proto	fileSize
=type	fun a1{File} -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function returns the size of the file.
The file pointer is updated at the beginning of the file.
//
+arg	file
=type	a1{File}
=desc	A file
//
+arg	result
=type	Int
=desc	A positive integer
//
//
//------------------ PROTO ----------------------------------------------------- fileWrite
+Proto	fileWrite
=type	fun a1{File} Int Str Int Int -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function writes up to len bytes from position start in string src, into the file.
The argument seek makes it possible to specify the position in the file. If nil, the writing will start from the current file pointer.
The file pointer is updated at the end of the operation.
//
+arg	file
=type	a1{File}
=desc	A file
//
+arg	seek
=type	Int
=desc	A position in the file, or nil
//
+arg	src
=type	Str
=desc	A string
//
+arg	start
=type	Int
=desc	A position in the string src
//
+arg	len
=type	Int
=desc	A number of bytes to write
//
+arg	result
=type	Int
=desc	The number of bytes actually written
//
//
//------------------ PROTO ----------------------------------------------------- fileTell
+Proto	fileTell
=type	fun a1{File} -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the current value of the file position indicator.
//
+arg	file
=type	a1{File}
=desc	A file
//
+arg	result
=type	Int
=desc	A positive integer
//
//
//------------------ PROTO ----------------------------------------------------- fileListInfo
+Proto	fileListInfo
=type	fun Str -> list FileInfo
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function is given a directory path as an argument and returns the list of the files in this path.
For each file, a [[FileInfo]] structure is returned.
See [[dirListInfo]] for a list of directories, and [[diskListInfo]] for both files and directories.
//
+arg	path
=type	Str
=desc	A string
//
+arg	result
=type	list FileInfo
=desc	A list of FileInfo structures
//
//
//------------------ PROTO ----------------------------------------------------- dirListInfo
+Proto	dirListInfo
=type	fun Str -> list FileInfo
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function is given a directory path as an argument and returns the list of the directories in this path.
For each directory, a [[FileInfo]] structure is returned.
See [[fileListInfo]] for a list of files, and [[diskListInfo]] for both files and directories.
//
+arg	path
=type	Str
=desc	A string
//
+arg	result
=type	list FileInfo
=desc	A list of FileInfo structures
//
//
//------------------ PROTO ----------------------------------------------------- diskListInfo
+Proto	diskListInfo
=type	fun Str -> list FileInfo
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function is given a directory path as an argument and returns the list of the files and the directories in this path.
For each directory, a [[FileInfo]] structure is returned.
See [[fileListInfo]] for a list of files, and [[dirListInfo]] a list of directories.
//
+arg	path
=type	Str
=desc	A string
//
+arg	result
=type	list FileInfo
=desc	A list of FileInfo structures
//
//
//------------------ PROTO ----------------------------------------------------- fileList
+Proto	fileList
=type	fun Str -> list Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function is given a directory path as an argument and returns the list of the files in this path.
For each file, the returned path is the concatenation of path and the name of the file.

	> fileList ("demo")
>-> list Str:
>   Str: "demo/demo.fun.boing.mcy"
>   Str: "demo/demo.fun.gasp.mcy"
>   Str: "demo/demo.fun.mandelbrot.mcy"
>   Str: "demo/demo.fun.maze.mcy"
>   Str: "demo/demo.fun.tetris.mcy"
//
+arg	path
=type	Str
=desc	A string
//
+arg	result
=type	list Str
=desc	A list of paths
//
//
//------------------ PROTO ----------------------------------------------------- dirList
+Proto	dirList
=type	fun Str -> list Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function is given a directory path as an argument and returns the list of the directories in this path.
For each directory, the returned path is the concatenation of path and the name of the directory and a final "/".
//
+arg	path
=type	Str
=desc	A string
//
+arg	result
=type	list Str
=desc	A list of paths
//
//
//------------------ PROTO ----------------------------------------------------- FILE_APPEND
+Proto	FILE_APPEND
=type	FileMode
=mode	empty constructor
=pkg	bios
=impl	native
=link	
=desc	Constant for [[fileOpen]]: the file can be read or written, the file pointer is at the end of the file.
//
//
//------------------ PROTO ----------------------------------------------------- FILE_READ_ONLY
+Proto	FILE_READ_ONLY
=type	FileMode
=mode	empty constructor
=pkg	bios
=impl	native
=link	
=desc	Constant for [[fileOpen]]: the file can only be only read, the file pointer is at the beginning of the file.
//
//
//------------------ PROTO ----------------------------------------------------- FILE_READ_WRITE
+Proto	FILE_READ_WRITE
=type	FileMode
=mode	empty constructor
=pkg	bios
=impl	native
=link	
=desc	Constant for [[fileOpen]]: the file can be read or written, the file pointer is at the beginning of the file.
//
//
//------------------ PROTO ----------------------------------------------------- FILE_REWRITE
+Proto	FILE_REWRITE
=type	FileMode
=mode	empty constructor
=pkg	bios
=impl	native
=link	
=desc	Constant for [[fileOpen]]: the file content is erased and the file can be read or written, the file pointer is obviously at the beginning of the file.
//
//
//------------------ PROTO ----------------------------------------------------- File
+Proto	File
=type	File
=mode	type
=pkg	bios
=impl	mcy
=link	
=desc
The type File is a native structure which is used to operate on a file. It is mostly made of three elements:
-	the file path
-	an operation mode: is it possible to write, or is it a read-only file?
-	a file pointer: this is a position in the file from where the next operation is supposed to be performed.
//
//
//------------------ PROTO ----------------------------------------------------- FileInfo
+Proto	FileInfo
=type	FileInfo
=mode	structure
=pkg	bios
=impl	mcy
=link	
=desc
The type FileInfo is used to put together information on a file in the filesystem: a path, a timestamp and a type (file or directory).
For a file the FileInfo contains also the size in bytes.
//
//
//------------------ PROTO ----------------------------------------------------- FileMode
+Proto	FileMode
=type	FileMode
=mode	sum
=pkg	bios
=impl	native
=link	
=desc	FileMode is a sum type to use with [[fileOpen]].
//
//
//------------------ PROTO ----------------------------------------------------- cleanPath
+Proto	cleanPath
=type	fun Str -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
It takes care of special paths such as /../, /./, //, /~/
This function has no connection with the actual file system: it only operates on strings.
	> cleanPath ("foo/../bar")
>-> Str: "/bar"
//
+arg	path
=type	Str
=desc	A path
//
+arg	result
=type	Str
=desc	A clean equivalent path
//
//
//------------------ PROTO ----------------------------------------------------- save
+Proto	save
=type	fun Str Str -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function save the content in fileName. It returns true when it succeeds.
This function runs in a worker: the thread is frozen until the result is available, but other threads are still running.
//
+arg	content
=type	Str
=desc	A string containing the data to save
//
+arg	fileName
=type	Str
=desc	A file path
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- userDir
+Proto	userDir
=type	Str
=mode	constant
=pkg	bios
=impl	native
=link	
=desc
A constant path in which the application can write files. It depends on the host operating system:
-	windows: C:/Users/[USERNAME]/Documents/
-	unix: /home/[USERNAME]/
//
//
//------------------ PROTO ----------------------------------------------------- load
+Proto	load
=type	fun Str -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function loads the content of the file and returns it as a string. It returns nil when the file does not exist.
This function runs in a worker: the thread is frozen until the result is available, but other threads are still running.
//
+arg	fileName
=type	Str
=desc	A file path
//
+arg	result
=type	Str
=desc	The content of the file
//
//
//------------------ PROTO ----------------------------------------------------- append
+Proto	append
=type	fun Str Str -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function appends the content to a file or create it if it did not exist. It returns true when it succeeds.
This function runs in a worker: the thread is frozen until the result is available, but other threads are still running.
//
+arg	content
=type	Str
=desc	A string containing the data to append
//
+arg	fileName
=type	Str
=desc	A file path
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- fileDelete
+Proto	fileDelete
=type	fun Str -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function deletes the specified file. It returns true when it succeeds.
//
+arg	path
=type	Str
=desc	A string containing a file path
//
+arg	result
=type	Bool
=desc	
//
//