tar
Pure Blade library for creating and extracting TAR archives.
Package Information
- Name: tar
- Version: 1.0.0
- Homepage: Homepage goes here.
- Tags: tar, archive, extract, blade, gzip
- Author: Richard Ore <eqliqandfriends@gmail.com>
- License: MIT
Installation
You can install the tar library with Nyssa package manager
nyssa install tar
Important
The library exports two helper function compress()
and extract()
by that allows you to create and/or extract TAR archives. Note that this library does not yet support TAR archives compressed with the bzip2 algorithm (typically files ending in .bz2
and .tbz
).
Extracting TAR archives
Use the helper function extract()
for a quick way to extract TAR archives.
import tar
tar.extract('/path/to/archive.tar.gz', '/destination')
The destination can be omitted in which case the archive will be extracted into the same directory as the source with same name without the last extension. e.g. for /path/to/file.tar.gz
will extract to /path/to/file.tar
directory is the destination is not given.
Creating a new TAR ball
To quickly create a new tarball, you can use the compress()
helper function in the library like this,
import tar
tar.compress('/path/to/file/or/directory', '/destination.tar.gz')
The compress function can be used to compress a single file or an entire directory. Like the extract()
function, you can choose to omit the destination parameter in which case compress will save the file to the current working directory with the same name as the file/directory with the extension .tar.gz
.
API Definition
For a more fine grained control and to create TAR archives from scratch while adding file and data as you wish or to get the list of files in a TAR archive, you need to make use of the library API as described below. They are self explanatory and you can check out the examples to see more details on their use.
Constants
COMPRESS_AUTO
: Automatically select and detect compression type (Default).COMPRESS_NONE
: Create and read archives without any compression.COMPRESS_GZIP
: Create and read archives with the GZip compression method.COMPRESS_BZIP
: Create and read archives with the BZip2 compression method (Not yet supported).
Functions
compress(path: string, destination: string = ')
$.tar.gz
in the current directory if the destination is not given.- @param string
path
the file or directory that will be compressed. - @param string
destination
the destination of the compressed TAR ball.
extract(file: string, destination: string = ')
Extracts a TAR file to the given destination or to the same directory as the source file with the same name as the TAR file (without the last extension) if destination is not given.
- @param string
file
the file to be extracted - @param string
destination
the path to extract to (Optional). - @return List<Dictionary> of extracted items (see
contents()
).
- @param string
Class Tar
Creates or extracts TAR archives with long pathnames (> 100 characters) support in POSIX ustar and GNU longlink formats.
Methods
set_compression(level: number = 9, type: COMPRESS_*)
- @param int
level
Compression level (0 to 9) - Default = 9 - @param int
type
Type of compression to use (use COMPRESS_* constants) - Default = COMPRESS_AUTO - @throws TarIllegalCompressionException
open(file: string)
- @param string
file
- @throws TarIOException
- @throws TarIllegalCompressionException
contents()
Read the contents of a Tar archive
This function lists the files stored in the Tar, and returns an indexed array of FileInfo objects
The Tar is closed afer reading the contents, because rewinding is not possible in bzip2 streams. Reopen the file with open() again if you want to do additional operations
- @return List<Dictionary>: This dictionary contains the following keys which describe the individual files in the archive:
- @return List<Dictionary>: This dictionary contains the following keys which describe the individual files in the archive:
extract(outdir: string, strip: int|string = 0, exclude: string = '', include: string = '')
Extract an existing Tar archive
The strip parameter allows you to strip a certain number of path components from the filenames found in the Tar file, similar to the --strip-components feature of GNU tar. This is triggered when an integer is passed as strip. Alternatively a fixed string prefix may be passed in strip. If the filename matches this prefix, the prefix will be stripped. It is recommended to give prefixes with a trailing slash.
By default this will extract all files found in the Tar. You can restrict the output using the include and exclude parameter. Both expect a full regular expression (including delimiters and modifiers). If include is set, only files that match this expression will be extracted. Files that match the exclude expression will never be extracted. Both parameters can be used in combination. Expressions are matched against stripped filenames as described above.
The Tar is closed afterwards. Reopen the file with open() again if you want to do additional operations
- @param string
outdir
the target directory for extracting - @param int|string
strip
either the number of path components or a fixed prefix to strip - @param string
exclude
a regular expression of files to exclude - @param string
include
a regular expression of files to include - @throws TarIOException
- @return list
- @param string
create(file: string = '')
Create a new Tar file
If file is empty, the Tar file will be created in memory
- @param string
file
- @param string
add_file(path: string, header: string|dict)
Add a file to the current Tar using an existing file in the filesystem
- @param string
path
path to the original file - @param string|dict
header
either the name to use in Tar (string) or a dictionary oject with all meta data, empty to take from original - @throws TarIOException
content()
.
- @param string
add_data(data: bytes, header: string|dict)
Untitled-
will be created.- @param bytes
bytes
binary content of the file to add - @param string|dict
header
either the name to us in Tar (string) or a dictionary oject with all meta data - @throws TarIOException
- @param bytes
close()
- @link http://www.gnu.org/software/tar/manual/html_chapter/tar_8.html#SEC134
- @throws TarIOException
get_archive()
close()
on the Tar.- @throws TarIOException
- @throws TarIllegalCompressionException
- @returns bytes
save(path: string)
- @param string
path
add_directory(directory: string, file_blacklist: list = [], ext_blacklist: list = [])
directory
recursively to the archive and set's it path in the archive todir
.- @param string
directory
- @param string
file_blacklist
if not empty, this function will ignore every file with a matching path. - @param list
ext_blacklist
if not empty, this function will ignore every file with a matching extension. - @throws TarIOException|Exception
- @param string
file_type(file: string)
COMPRESS_AUTO
somewhere.- @param string
file
- @return int (one of COMPRESS_BZIP, COMPRESS_GZIP or COMPRESS_NONE)
- @param string