README.md

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.