Introduction

imosh is a library for bash. It consists of utilities like gflags and glog and PHP-like functions.

imosh is tested on drone.io (https://drone.io/github.com/imos/imosh).

Supported BASH versions

BASH 3.2.51 on Mac OSX Mavericks
BASH 4.2.25 on Ubuntu 14.04

Features

Man-like help

imosh can show a help page like a man page.

Stack trace

imosh shows a stack trace when some error arises.

gflags-like flag definitions

imosh enables shell scripts to use flag definitions like gflags.

DEFINE_string 'string' 'default' 'String flag.'
DEFINE_int 'int' 100 'Integer flag.'
DEFINE_bool 'bool' false 'Boolean flag.'

Glog-like logging

imosh provides a standard way for logging like glog.

LOG ERROR 'some error happens!'

Usage

Copy imosh in the top directory to some directory listed in ${PATH}.

source imosh || exit 1

DEFINE_string 'string' 'default' 'String flag.'
DEFINE_int 'int' 100 'Integer flag.'
DEFINE_bool 'bool' false 'Boolean flag.'

eval "${IMOSH_INIT}"

Terminal

imosh is also useful for regular shell operations. You can use imosh by running the following command beforehand:

source imosh

Flag Definition

DEFINE_<type> <flag name> <default value> <flag description>

Flag Types

string ... string type,
bool ... boolean type,
int ... integer type.

Flag Options

--alias=alias name ... declares a flag alias. This is useful for short flag names.

Other Features

The --help (-h) flag is defined, and it shows the list of flags defined in the script.
Environment variables specified by IMOSH_FLAGS_<flag name> change flags' default values.

Logging

LOG <severity> <message>

Severity

INFO is NOT output to stderr by default,
WARNING is NOT output to stderr by default,
ERROR is output to stderr by default,
FATAL is output to stderr by default.

Flags

--alsologtostderr makes all severities output to stderr in addition to log files,
--logtostderr makes all severities output to stderr instead of log files.

Path to Output

imosh outputs log files to ${TMPDIR}/<program name>.<host name>.<user>.<severity>.<date>.<time>.<process ID>.

Functions

Arrays

array -- Creates an array.
array_is_empty -- Checks if an array is empty.
array_keys -- Gets an array's keys.
array_map -- Applies a callback to elements.
array_unique -- Removes duplicated elements from an array variable.
array_values -- Copies elements from an array to an array.
count -- Counts the number of elements.
in_array -- Checks if a value exists in an array.
in_array -- Finds whether a variable is an array.
sort -- Sorts elements.

Date/Time

date -- Format a local time/date.
strtotime -- Parses a datetime text into a UNIX timestamp.
time -- Returns current Unix timestamp.

Filesystem

fgets -- Gets a line from STDIN.
file_get_contents -- Reads an entire file into a string.
readarray -- Reads a line as an array.
readline -- Gets a line.
tmpfile -- Creates a temporary file.
function_exists -- Returns true iff the given function has been defined.

Regular Expressions (Glob-Compatible)

For more details of GREG pattern, see http://mywiki.wooledge.org/glob.

ereg_match -- Checks if a string matches an EREG pattern.
greg_match -- Checks if a string matches a GREG pattern.
greg_replace -- Replace a GREG pattern with a string.
greg_split -- Splits a string with a GREG pattern.

imosh Options and Information

getchildpids -- Gets child process IDs.
getmypid -- Gets the current process ID.
is_main -- Returns 0 iff caller is in the main script.

Logging Functions

CHECK -- checks if a command succeeds.
DEPRECATED -- Declares as deprecated.
LOG -- Logs a message.

Mathematical Functions

rand -- Generates a random integer.

Miscellaneous Functions

atexit -- Registers a function on shutdown.
exec -- Executes an external program.
exit, die -- Kills the current script.
throttle -- Throttles by the number of child processes.
usage -- Shows a usage message.

Strings

addslashes -- Quotes a string with backslahses.
base64_decode -- Decodes data with MIME base64.
base64_encode -- Encodes data with MIME base64.
bin2hex -- Converts a binary string into hexadecimal representation.
escapeshellarg -- Escapes a variable as a shell argument.
explode -- Splits a string by a substring.
hex2bin -- Decodes a hexadecimally encoded binary string.
implode -- Joins array elements with a string.
ltrim -- Strips whitespace(s) from the beginning of a string.
md5 -- Calculates a MD5 hash.
md5 -- Calculates the MD5 hash of a given file.
ord -- Gets a character's ASCII code.
print -- Prints a message.
println -- Prints a message with a new line.
rtrim -- Strips whitespace(s) from the end of a string.
sha1 -- Calculates a MD5 hash.
str_replace -- Replaces a substring with another substring.
strcpy -- Copies a string from a variable to another variable.
strtolower -- Makes a string lowercase.
strtoupper -- Makes a string uppercase.
substr -- Returns a substring.
trim -- Strips whitespaces from both sides.

Testing

Functions only for testing.

ASSERT_ALIVE -- Asserts a command successfully dies.
ASSERT_DEATH -- Asserts a command unsuccessfully dies.
ASSERT_EQ -- Asserts two arguments are equal.
ASSERT_FALSE -- Expects a command fails.
ASSERT_NE -- Asserts two arguments are not equal.
ASSERT_TRUE -- Asserts a command succeeds.
EXPECT_ALIVE -- Expects a command successfully exits.
EXPECT_DEATH -- Expects a command unsuccessfully dies.
EXPECT_EQ -- Expects two arguments are equal.
EXPECT_FALSE -- Expects a command fails.
EXPECT_GE -- Expects first one is greater than or equal to second one.
EXPECT_GT -- Expects first one is greater than second one.
EXPECT_LE -- Expects first one is less than or equal to second one.
EXPECT_LT -- Expects first one is less than second one.
EXPECT_NE -- Expects two arguments are not equal.
EXPECT_TRUE -- Expects a command succeeds.
FAILURE -- Declares a test case failed.
test_file -- Tests a file.

Variable handling

boolval -- Casts a variable as a boolean value.
cast -- Casts a variable.
enumval -- Casts a variable as an enum value.
floatval -- Casts a variable as a float value.
intval -- Casts a variable as an integer value.
isset -- Checks if a variable exists.
let -- Assigns a value into a variable.
strval -- Casts a variable as a string value.