//
//------------------ DOK FILE --------------------------------------------------
+Header	core.util.tar
=pkg	core.util.tar
=title	core.util.tar
=short	*.tar files
=desc	This library can read or write tar files.
//
//
//------------------ PROTO ----------------------------------------------------- tarFromFileList
+Proto	tarFromFileList
=type	fun list [Str Int Str] -> Str
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc
This function archives a list of files and returns the binary string ready to be saved as a *.tar file.
	tarFromFileList (["tmp/foo.txt", time(), "Hello Foo"]::["tmp/bar.txt", time()-3600, "Hello Bar"]::nil)
//
+arg	lData
=type	list [Str Int Str]
=desc	A list of files to archive. Each tuple is [name, timestamp, content]
//
+arg	result
=type	Str
=desc	A binary string with the resulting archive.
//
//
//------------------ PROTO ----------------------------------------------------- tarFromFileInfoList
+Proto	tarFromFileInfoList
=type	fun list FileInfo -> Str
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc
This function archives a list of files and returns the binary string ready to be saved as a *.tar file.
	tarFromFileInfoList (fileListInfo ("tmp/"))
//
+arg	lFileInfo
=type	list FileInfo
=desc	A list of files (see bios functions [[fileListInfo]], [[fileInfo]])
//
+arg	result
=type	Str
=desc	A binary string with the resulting archive.
//
//
//------------------ PROTO ----------------------------------------------------- tarExtractFiles
+Proto	tarExtractFiles
=type	fun Str Bool -> list TarFile
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc
This function parses a tar content and returns the list of files, as a list of [[TarFile]] structures.
When withContent is true, the content of each [[TarFile]] is uncompressed.
Else the [[tarLoadContent]] function allows to uncompress a specific TarFile
//
+arg	src
=type	Str
=desc	The binary string of an archive
//
+arg	withContent
=type	Bool
=desc	A boolean
//
+arg	result
=type	list TarFile
=desc	A list of files present in the archive
//
//
//------------------ PROTO ----------------------------------------------------- tarExtractDirectories
+Proto	tarExtractDirectories
=type	fun Str -> list TarFile
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc	This function parses a tar content and returns the list of directories, as a list of [[TarFile]] structures.
//
+arg	src
=type	Str
=desc	The binary string of an archive
//
+arg	result
=type	list TarFile
=desc	A list of directories present in the archive
//
//
//------------------ PROTO ----------------------------------------------------- tarUpdate
+Proto	tarUpdate
=type	fun TarFile -> Int
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc	This function returns the timestamp of a file present in a tar file
//
+arg	t
=type	TarFile
=desc	A file structure returned by [[tarExtractFiles]] or [[tarExtractDirectories]]
//
+arg	result
=type	Int
=desc	A timestamp
//
//
//------------------ PROTO ----------------------------------------------------- tarContent
+Proto	tarContent
=type	fun TarFile -> Str
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc
This function returns the content of a file present in a tar file. It may return nil if the content is not yet available.
Content is available only if:
-	function [[tarExtractFiles]] was called with withContent = true
-	or content was read by a call to [[tarLoadContent]]
//
+arg	t
=type	TarFile
=desc	A file structure returned by [[tarExtractFiles]]
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- tarSize
+Proto	tarSize
=type	fun TarFile -> Int
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc	This function returns the size of the file
//
+arg	t
=type	TarFile
=desc	A file structure returned by [[tarExtractFiles]]
//
+arg	result
=type	Int
=desc	An integer
//
//
//------------------ PROTO ----------------------------------------------------- tarFileName
+Proto	tarFileName
=type	fun TarFile -> Str
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc	This function returns the name of the file
//
+arg	t
=type	TarFile
=desc	A file structure returned by [[tarExtractFiles]] or [[tarExtractDirectories]]
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- tarMode
+Proto	tarMode
=type	fun TarFile -> Str
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc	This function returns the mode of the file
//
+arg	t
=type	TarFile
=desc	A file structure returned by [[tarExtractFiles]] or [[tarExtractDirectories]]
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- TarFile
+Proto	TarFile
=type	TarFile
=mode	structure
=pkg	core.util.tar
=impl	mcy
=link	
=desc	This structure describes a file present in an archive.
//
//
//------------------ PROTO ----------------------------------------------------- tarLoadContent
+Proto	tarLoadContent
=type	fun Str TarFile -> Str
=mode	function
=pkg	core.util.tar
=impl	mcy
=link	
=desc	When [[tarExtractFiles]] is called with withContent=false, the [[tarLoadContent]] is used to later retrieve the content of a [[TarFile]].
//
+arg	src
=type	Str
=desc	A binary string of an archive
//
+arg	t
=type	TarFile
=desc	A file structure returned by a call to tarExtract with the exact same src
//
+arg	result
=type	Str
=desc	The decompressed content