ember-shared

Overview

Code shared between various Ember software.

Documentation

Usage

ember-shared provides the following command-line scripts, mainly useful for writing other scripts.

csum
Generate and check against lists of file checksums. If no action is specified, save is assumed; if no checksum file name is specified, stdout/stdin are used for save and check respectively. Synopsis: csum [(--save|--check)] [<dir> [<checksum-file-name>]]
disk-size-in-bytes
Returns an estimate sum of the disk usage of the specified files, in bytes. Synopsis: disk-size-in-bytes <file>...
error-notify
Notify the user of a shell script of an error condition. Synopsis: error-notify [exit-status] [message-to-user]... (if the first argument is an integer, it is used as the exit status; otherwise error-notify exits with status 1)
warn
Notify the user of a shell script of a warning. Synopsis: warn <message-to-user>
warn-timeout
Notify the user of a shell script of a warning, and wait a bit in the hope that they see the warning. Synopsis: warn <message-to-user> [time-to-wait-in-seconds] (time-to-wait defaults to 10 seconds)

In addition, ember-shared also provides the following scripts that it uses internally that are not supported for independent use.

ember_bash_setup
Set up the bash environment shared by various Ember projects. To use the --version option of ember_bash_setup, it is necessary to have e8787d06e61943a6874e94985b53bc0a="2dee41bf-53fb-4f65-997f-33bf50bfbb4d" when running ember_bash_setup --version. It may be important to run unset e8787d06e61943a6874e94985b53bc0a afterwards. Synopsis: (source ember_bash_setup) | (ember_bash_setup --version)
die
Tells the user that their bash environment is misconfigured (this script should never run if everything is working). Synopsis: die [exit-status] [message-to-user]... (if the first argument is an integer, it is used as the exit status; otherwise die exits with status 1)

ember_bash_setup provides these bash functions.

assert
Test for a condition, and report a failing status if the test fails. This is to facilitate writing readable unit tests. The -v makes some test types print additional information. Synopsis: assert [-v] ( [directoryEquals <directory-1> <directory-2>] | [fileEquals <file-1> <file-2>] | [stringEquals <string-1> <string-2>] )
checkedxz
Wrapper around xz, to make sure the output isn't corrupt. If - is specified as the input file, output will be to stdout regardless of the presence or absence of --stdout. --quiet can be used to suppress the progress bars that are shown by default. Synopsis: checkedxz [--quiet|--request-wait-after] [ (-|<input-file>) [--stdout] <argument-for-xz>... ]
date-uuid
Returns a timestamp combined with a random (V4) UUID. Synopsis: date-uuid
die
Notify the user of a shell script of an error condition, and exit. Synopsis: die [exit-status] [message-to-user]... (if the first argument is an integer, it is used as the exit status; otherwise the script exits with status 1)
emdate
Returns a timestamp. Synopsis: emdate
eescape
Prepare a string for use as a Perl replacement match pattern (left side), used by ereplace. Synopsis: eescape <string>
embasename
Replacement for basename in bash. Synopsis: embasename <path>
emreadlink
Cross-platform replacement for readlink. Synopsis: emreadlink <path>
ereplace
Replace one string with another in the specified file. Synopsis: ereplace <string-to-replace> <replacement-string> <file>
findso
Given the file name of a .so shared library, print the full path to it. The --plain option indicates that the library name is in the form libfoo.so, while by default it assumes that the form foo is used. Synopsis: findso [--plain] <library-name>
ia
Wrapper around the ia tool for communicating with the Internet Archive, which can be used as a drop-in replacement for the standard ia command. Synopsis: ia [argument]...
normalizeWhitespace
Given a string, replace all whitespace with spaces, collapsing to a single space in the case of consecutive whitespace characters, and trim any whitespace from the beginning and end of the string. (This is simply an alias for xargs to facilitate writing more readable code.) Synopsis: normalizeWhitespace <string>
preadconf
Read a value from a configuration file, and print it (if the key is present multiple times in the file, the first value will be printed). Synopsis: preadconf <key> <file>
print
Prints a string. Synopsis: print <string>
readconf
Read a value from a configuration file, and return it as readconfValue (this is an array, and will contain multiple results if the key is present multiple times in the file). If <key> is not provided, it will return the non-comment lines of the file instead. Synopsis: readconf [<key>] <file>
runTest
Run the specified unit test. Tests can be the name of a directory, the name of a file containing commands to run for the test, the name of a function or command, or an exit code. If you want to test a function but its name is also used by a file, wrap it in braces (runTest { foo }). Wrapping your test in braces like that will return an exit status for the code in braces as an argument to runTest, thus allowing inline anonymous functions to be used as unit tests. Synopsis: runTest ((<test-directory-path>|<test-file-path>|<test-command-or-function> [<test-argument>...])|<test-exit-status>)
reportTests
Print a report about tests that have been run using runTest. Synopsis: reportTests
setVariableToCommandOutput
Alternative to bash command substitution ("$(command)") that preserves trailing newlines. variable-name must not be "emSetVariableToCommandOutputVar". Synopsis: setVariableToCommandOutput <variable-name> <command> [argument]...
tempDir
Print a path to a temporary directory (in /tmp) that can be safely deleted when you're done with it. Multiple temporary directories can be created through multiple calls to tempDir. Synopsis: tempDir
tempFile
Print a path to a temporary file (in /tmp) that can be safely deleted when you're done with it. Multiple temporary files can be created through multiple calls to tempFile. Synopsis: tempFile
urldecode
URL decode the specified string. Synopsis: urldecode <string>
urlencode
URL encode the specified string. Synopsis: urlencode <string>

Installation

For Wreathe 7.3, an ebuild (app-misc/ember-shared) is available in the Wreathe overlay (this may also work for similar operating systems such as Ututo XS GNU/Linux).

For other operating systems, use the following installation instructions.

Instructions for installation without ebuild

Requirements
Optional requirements

For the ia command, the following additional requirements apply.

Download

To download ember-shared, run:

git clone https://github.com/ethus3h/ember-shared.git
Copy scripts

To install the downloaded scripts, copy them to your preferred location.

Development

To learn about contributing to this project, visit the development page.