classDocs / Tar

Tar

classsharedsource

Object → Tar

The tar (.tar) archive.

Parses POSIX ustar, pax and GNU archives (long names and base-256 numbers), gzip compressed archives are decompressed on parse.

Builds ustar archives, long paths and out of range values are written with pax headers.

lua

local tar = Tar()
tar:addDirectory( "docs" )
tar:addFile( "docs/readme.txt", "hello" )

local data = tar:compile()
print( Tar( data ):readFile( "docs/readme.txt" ) ) -- hello

Constructor

Tar(data: string?): Tar

Fields

Name	Type	Description
`files`	`Tar.File[]`	The entries of the archive.
`file_count`	`integer`	The number of entries.
`file_indexes`	`table<string, integer>`	The indexes of entries in `files` by their paths.
`gzipped`	`boolean`	`true` if the parsed archive was gzip compressed.
`data`	`string \| nil`	The parsed archive data, the content of not yet read entries.

Methods

`addDirectory`	Adds the directory to the archive, replaces the existing entry with the same path.
`addFile`	Adds the regular file to the archive, replaces the existing entry with the same path.
`addSymlink`	Adds the symbolic link to the archive, replaces the existing entry with the same path.
`compile`	Builds the .tar data of the archive.
`getFile`	Returns the entry of the archive.
`parse`	Replaces the archive with the parsed .tar or .tar.gz data.
`readFile`	Returns the content of the entry of the archive.
`removeFile`	Removes the entry from the archive.

#Tar:addDirectory

sharedsource

function Tar:addDirectory(directory_path: string, mode?: integer): Tar.File

Adds the directory to the archive, replaces the existing entry with the same path.

Parameters

Name	Type	Description
`directory_path`	`string`	The path of the directory inside of the archive, `/` is appended if missing.
`mode`optional	`integer`	The permission bits, `493` (`0755`) by default.

Returns

Type	Name	Description
`Tar.File`	`file`	The added directory.

#Tar:addFile

sharedsource

function Tar:addFile(file_path: string, content: string, mode?: integer): Tar.File

Adds the regular file to the archive, replaces the existing entry with the same path.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the archive, e.g. `docs/readme.txt`.
`content`	`string`	The file content.
`mode`optional	`integer`	The permission bits, `420` (`0644`) by default.

Returns

Type	Name	Description
`Tar.File`	`file`	The added file.

#Tar:addSymlink

sharedsource

function Tar:addSymlink(link_path: string, target: string): Tar.File

Adds the symbolic link to the archive, replaces the existing entry with the same path.

Parameters

Name	Type	Description
`link_path`	`string`	The path of the link inside of the archive.
`target`	`string`	The path the link points to.

Returns

Type	Name	Description
`Tar.File`	`file`	The added link.

#Tar:compile

sharednodiscardsource

function Tar:compile(): string

Builds the .tar data of the archive.

Use gzip.compress on the result to get .tar.gz.

Returns

Type	Name	Description
`string`	`data`	The `.tar` data.

#Tar:getFile

sharednodiscardsource

function Tar:getFile(file_path: string): Tar.File | nil

Returns the entry of the archive.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the entry inside of the archive.

Returns

Type	Name	Description
`Tar.File \| nil`	`file`	The entry, `nil` if there is no such entry.

#Tar:parse

sharedsource

function Tar:parse(data: string)

Replaces the archive with the parsed .tar or .tar.gz data.

File contents are not copied, they are read from the data on demand by readFile.

Parameters

Name	Type	Description
`data`	`string`	The `.tar` or `.tar.gz` data.

#Tar:readFile

sharednodiscardsource

function Tar:readFile(file_path: string): string | nil

Returns the content of the entry of the archive.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the entry inside of the archive.

Returns

Type	Name	Description
`string \| nil`	`content`	The content, `nil` if there is no such entry.

#Tar:removeFile

sharedsource

function Tar:removeFile(file_path: string): boolean

Removes the entry from the archive.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the entry inside of the archive.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the entry was removed, `false` if there is no such entry.