compress: functions module for [shellfire]

This module provides a simple framework for working with compressions such as gzip and xz. It abstracts away most details, providing a consistent interface to all forms of compression. It focuses entirely on compressing files with maximum compression. In doing so, wherever possible, it eliminates file meta data (eg timestamps). It preserves original, uncompressed files. Wherever possible, it uses the optimum tool and 'turns the dial upto 11' but can fallback as appropriate (eg pigz for gzip, falling back to zopfli and then gzip proper). Functions exist to determine file extensions and MIME types for a compressor. It does not support decompression.

An example user is the swaddle packaging tool.

Compatibility

• Tag release_2015.0117.1750-1 is compatible with shellfire release release_2015.0117.1750-1.

Overview

For example, to maximally compress a file with gzip:-

compress_gzip '/path/to/file'

This will output the file '/path/to/file.gz' and keep '/path/to/file'. No metadata will be kept and maximal compression will be used. The compressed file's timestamps will match the original's.

Functions are sanely named, so for example the following works:-

for compressor in gzip bzip2 xz lrzip
do
	compress_${compressor} '/path/to/file'
done

Currently, the following compressors are defined (in rough compressive power order):-

• lzop
• zip (not a typo; creates a single-file zip archive)
• gzip
• zlib
• bzip2
• rzip
• lzma
• xz
• lzip
• zpaq
• lrzip (insane crushing potential)

Compressors choose amongst the available alternatives on any system, and try to install using the dependency framework in core the preferred compressor. Each compressor is in its own functions file, so it needn't pollute your code if not needed.

Importing

To import this module, add a git submodule to your repository. From the root of your git repository in the terminal, type:-

mkdir -p lib/shellfire
cd lib/shellfire
git submodule add "https://github.com/shellfire-dev/compress.git"
cd -
git submodule init --update

You may need to change the url https://github.com/shellfire-dev/compress.git" above if using a fork.

You will also need to add paths - include the module paths.d.

Namespace compress

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress
	…
}

Functions

---

compress_extension()

Parameter	Value	Optional
compressor	Compressor as defined in Overview, or none	No

Returns a file extension string. Result is printed to standard out without an initial period, so use captures, eg

local fileExtensionExcludingInitialPeriod="$(compress_extension 'gzip')"

---

compress_mimeType()

Parameter	Value	Optional
compressor	Compressor as defined in Overview, or none	No

Returns a MIME type string. Result is printed to standard out without an initial period, so use captures, eg

local mimeType="$(compress_mimeType 'gzip')"

---

compress_properName()

Parameter	Value	Optional
compressor	Compressor as defined in Overview, or none	No

Returns a cased string reflecting the author(s) names for this compressor. Result is printed to standard out, so use captures, eg

# Produces `Gzip`
local properName="$(compress_properName 'gzip')"

---

Namespace compress_bzip2

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress bzip2

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress bzip2
	…
}

Functions

---

compress_bzip2()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension bzip2). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_bzip2 '/path/to/file'

---

Namespace compress_gzip

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress gzip

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress gzip
	…
}

Functions

---

compress_gzip()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension gzip). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_gzip '/path/to/file'

---

Namespace compress_lrzip

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress lrzip

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress lrzip
	…
}

Functions

---

compress_lrzip()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension lrzip). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_lrzip '/path/to/file'

---

Namespace compress_lzip

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress lzip

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress lzip
	…
}

Functions

---

compress_lzip()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension lzip). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_lzip '/path/to/file'

---

Namespace compress_lzma

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress lzma

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress lzma
	…
}

Functions

---

compress_lzma()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension lzma). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_lzma '/path/to/file'

---

Namespace compress_lzop

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress lzop

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress lzop
	…
}

Functions

---

compress_lzop()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension lzop). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_lzop '/path/to/file'

---

Namespace compress_rzip

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress rzip

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress rzip
	…
}

Functions

---

compress_rzip()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension rzip). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_rzip '/path/to/file'

---

Namespace compress_xz

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress xz

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress xz
	…
}

Functions

---

compress_xz()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension xz). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_xz '/path/to/file'

---

Namespace compress_zip

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress zip

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress zip
	…
}

Functions

---

compress_zip()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension zip). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original. Creates a ZIP archive with a single member.

compress_zip '/path/to/file'

---

Namespace compress_zlib

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress zlib

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress zlib
	…
}

Functions

---

compress_zlib()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension zlib). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original.

compress_zlib '/path/to/file'

---

Namespace compress_zpaq

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn compress zpaq

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn compress zpaq
	…
}

Functions

---

compress_zpaq()

Parameter	Value	Optional
uncompressedFilePath	Extant uncompressed file path	No

Compresses uncompressedFilePath to uncompressedFilePath + .$(compress_extension zpaq). Preserves uncompressedFilePath. Sets the compressed file's timestamp to match the uncompressed original. Creates a ZPAQ archive with a single member.

compress_zpaq '/path/to/file'