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 path is specified, the current directory is assumed; if no checksum file name is specified, stdout/stdin are used for save and check respectively. Note that at least one checksummable file must be specified for the resulting file to be usable: a single empty directory, for instance, will result in an unusable file. Synopsis: csum [(--save|--check)] [<path>... [<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)
htmlToText.pl
Print the standard input received by it, with any HTML tags removed, to standard output. Synopsis: htmlToText.pl
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. Using bash's $()syntax (which creates a subshell), it can be written succinctly, with no need to unset afterwards, as $(e8787d06e61943a6874e94985b53bc0a="2dee41bf-53fb-4f65-997f-33bf50bfbb4d"; ember_bash_setup --version). (Note that if ember_bash_setup has already been sourced, the ember-shared version is already available as $emberSharedVersion, with no need for these shenanigans.) 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.

abspath
Get the absolute path to the specified file or directory, like readlink -f but without resolving symlinks. The path must exist. Synopsis: abspath <path>
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
defaultEditor
Wrapper around the default text editor. Synopsis: defaultEditor
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 (without interpreting metacharacters). Synopsis: ereplace <string-to-replace> <replacement-string> <file>
ereplaceRegEx
Perform a Perl regex substitution on the specified file (interpreting metacharacters). The match and replacement must be a valid within a s///g in Perl (it will be literally interpolated into the Perl code, rather than escaped as it is with ereplace). Synopsis: ereplaceRegEx <regex-match> <replacement> <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>
getDefaultEditor
Returns the command of the default text editor. Synopsis: getDefaultEditor
getDefaultEditorPath
Returns a path to the default text editor. Synopsis: getDefaultEditorPath
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. Using the downloadAsStream subcommand will send the contents of the file represented by the Internet Archive file download URL specified to stdout. checkeddl accepts an Internet Archive item details URL or plain identifier as input. The downloadHere subcommand is equivalent to wget <URL> for Internet Archive download URLs. Synopsis: ia ( ( ((downloadAsStream|downloadHere) <URL>) | (checkeddl <URL>...) ) | ([argument]...) )
iaident
Given an Internet Archive URL, path (with identifier), or plain identifier in the form [https://archive.org/download/]identifier[/file/path], return the Internet Archive identifier. For the example URL, this would return "identifier". Synopsis: iaident <input>
iapath
Given an Internet Archive URL, path (with identifier), or plain identifier in the form [https://archive.org/download/]identifier[/file/path], return the path to the item (not including the identifier). For the example URL, this would return "file/path". Synopsis: iapath <input>
iafilename
Given an Internet Archive URL, path (with identifier), or plain identifier in the form [https://archive.org/download/]identifier[/file/path], return the name of the last item in the path specified within the item specified. For the example URL, this would return "path". Synopsis: iafilename <input>
iasha1
Given an Internet Archive URL to a file, path to a file (with identifier), or identifier with file name in the form [https://archive.org/download/]identifier/file/path, return the SHA1 checksum that the Internet Archive reports for the file specified. Synopsis: iasha1 <input>
iamd5
Given an Internet Archive URL to a file, path to a file (with identifier), or identifier with file name in the form [https://archive.org/download/]identifier/file/path, return the MD5 checksum that the Internet Archive reports for the file specified. Synopsis: iamd5 <input>
iaurl
Given an Internet Archive URL, path (with identifier), or plain identifier in the form [https://archive.org/download/]identifier[/file/path], return the full URL. For the example URL, this would return "https://archive.org/download/identifier/file/path". Synopsis: iaurl <input>
isIaName
Given a string, exit 0 if it could be an Internet Archive URL, path, or identifier in the form [https://archive.org/download/]identifier[/file/path]; otherwise exit 1. Synopsis: isIaName <input>
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>
retryUntilSuccess
Retry the specified command until it succeeds. The default maximum number of retries is -1, representing an unlimited number. The default maximum time to wait between retries is 0 seconds. The default delay time backoff increment is 1. The default initial delay time is 0 seconds. A good set of values for this for network requests is -1 30 5 5, which is similar to what is used by Crystallize, and will start with a five-second wait on the first failure, and then increase the delay by five seconds for each subsequent retry, until the delay reaches thirty seconds. Synopsis: retryUntilSuccess [<maximum-number-of-retries>] [<maximum-time-to-wait-between-retries-in-seconds>] [<delay-time-backoff-increment>] [<initial-retry-delay-time>] <command-or-function> [<argument>...]
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 [-v|-vv] ((<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>
version_gt
Return 0 if the first version number is greater than (not equal to) the second, or non-zero otherwise (including if the two version numbers are the same). Synopsis: version_gt <version-number-1> <version-number-2>

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.