g.bash

A Bash framework.

Documentation (WIP)

Global Helpers

• g::eval [...command] - Execute a command, but w/ in-framework logging
• g::silence [...command] - Execute a command, squashing all output
• g::now - Get a timestamp in ISO8061
• g::bc [...args] - Execute a bc math statement
• g::awk [...inputs] - Execute an awk print command

Utilties (g::util)

• isNumeric [value] - Checks if a given value is a number with optional decimal and positive/negative
• true - A successful exit code/return value (0)
• false - A failure exit code/return value (1)
• returnToEcho [...command] - Execute a command that returns true/false and instead echo 1 on success, 0 otherwise
• uuid - Generate a UUID
• uuid::underscore - Generate a UUID (underscore-separated)
• escape [value] - Bash-escape a value for safe use in eval strings
• realpath [path] - A non-GNU real path resolver
• trace [?message] [?skip = frames to exclude] - Generate a stack trace with an optional message

Strings (g::str)

• quote [str] - Surround a string in quotes
• eval [...args] - Execute a command and quote the output
• length [str] - Get the number of chars in a string
• padLeft [str] [length] [pad character=' '] - Left-pad a string to the given length
• padRight [str] [length] [pad character=' '] - Right-pad a string to the given length
• padCenter [str] [length] [pad character=' '] - Center-pad a string to the given length
• substring [str] [startAt] [length] - Get a substring
• offset [str] [startAt] - Drop the first n characters of a string
• reverse [str] - Reverse a string
• startsWith [haystack] [needle] - Check if the haystack starts with the needle
• endsWith [haystack] [needle] - Check if the haystack ends with the needle
• trim [str] - Trim the whitespace from either end of the string
• indexOf [str] [substring] - Print the character index where the substring appears, if any (returns g::util::false if no match)
• replace [str] [find] [replace] - Find-and-replace all occurrences in a string
• replace::once [str] [find] [replace] - Find-and-replace the first occurrence in a string

Arrays (g::arr)

Note: When passing an array as an argument to a function, it should be passed as "${array[@]}"

• includes [value] [array] - Checks if a given value exists in the array
• assoc::hasKey [key] [array] - Checks if an associative array has a given key
• join [delimiter] [array] - Implodes a list of values to a string using the given delimiter

Math (g::math)

• Constants (g::math::c)
  • e - Euler's constant
  • ln2 - Natural log of 2
  • ln10 - Natural log of 10
  • pi - Pi
  • sqrt05 - Square root of 1/2
  • sqrt2 - Square root of 2
• abs [num] - Absolute value of a number
• cubeRoot [num] - Cube root of a number
• squareRoot [num] - Square root of a number
• lessThan [left] [right] - Check if left < right
• greaterThan [left] [right] - Check if left > right
• equalTo [left] [right] - Check if left == right, numerically
• isPositive [num] - Check if num > 0
• isNegative [num] - Check if num < 0
• signOf [num] - Prints the leading sign of a number (either + or -)
• mod [num] [modulus] - Compute the modulus of a number
• ceiling [num] - Round the number up to the nearest int
• truncate [num] - Truncate the number to an int
• floor [num] - Round the number down to the nearest int
• exponent [num] [power] - Compute num^power
• cos [num] - Cosine of a number
• sine [num] - Sine of a number
• tan [num] - Tangent of a number
• ln [num] - Natural log of a number
• log10 [num] - Log base 10 of a number
• log2 [num] - Log base 2 of a number
• log [num] [base] - Arbitrary base logarithm
• random - Get a random float
• max [...nums] - Get the max value of some numbers
• min [...nums] - Get the min value of some numbers
• round [num] [precision] - Round a number to the specified number of decimal points

Files (g::file)

• appendString [path] [string] - Append the string contents to the end of a file
• exists [path] - Checks if a file exists
• directoryExists [path] - Checks if a directory exists
• touch [path] - Create a file if it does not exist
• truncate [path] - If a file exists, empty its contents

Source Code (g::source)

g::source allows you to organize your scripts into multiple files, and perform filesystem-relative source imports. Similarly, it will prevent the same source file from being re-imported multiple times.

Example:

# index.bash
g::source src/setup
g::source src/logging

# src/setup.bash
g::source logging

# src/logging.bash
# This file is included once

• g::source [path] [?up=1] - Load a source file relative to the current script (must end in .bash and will only be loaded once)
• resolve [path] [?up=1] - Resolve the path of a source file relative to the current script
• exists [path] [?up=1] - Check if a source file exists relative to the current script
• force [path] [?up=1] - Resolve and load a source file, bypassing the cache
• has [path] [?up=1] - Check if the given source file has been loaded

Configuration File (g::config)

Provides a simple key-value way of storing persistent configuration.

Example:

echo "Last run: $(g::config::get last-run Never)"
g::config::set 'last-run' "$(g::now)"

• setDefault [name] - Set the default name of the config file
• getDefault - Get the default name of the config file
• init [?name] - Make sure a config file exists
• get [name] [?default value] - Get a value from the default config file
• get::forFile [file] [name] [?default value] - Get a value from a non-default config file
• set [name] [value] - Store a value in the default config file
• set::forFile [file] [name] [value] - Store a value in a non-default config file

Paths (g::path)

• concat [path] [...parts] - Combine path segments into a path, accounting for leading and trailing slashes
• resolve [...parts] - Concat path parts and determine the real path
• resolveFrom [base dir] [...parts] - Concat path parts and determine the real path relative to some base directory
• cd [...parts] - Resolve path parts and change directories
• tmp - Get a temp file path (and mark it for cleanup)
• tmpdir - Get a temp dir path (and mark it for cleanup)

Errors (g::error)

• throw [message] - Throw an error
• (global) try
• (global) catch

Logging (g::log)

g::log provides level- and target-aware logging output. The internal level is used by g.bash itself.

Available levels: error | warn | info | debug | verbose | internal

• enableTarget [name] - Enable log outputs for the given target
• enableAllTargets - Enable log outputs for ALL targets
• all - Shorthand to enable the highest verbosity for ALL targets
• getLevel - Get the current logging level
• setLevel [name] - Set a new logging level
• enable [target=stdout|stderr|file] [?param] - Enable logging to the specified target
• disable [target=stdout|stderr|file] - Disable logging to the specified target
• g::error [output] [?target] - Write a log message at the error level, optionally for a specific target
  • Same format for g::warn, g::info, g::debug, g::verbose, and g::internal
• g::log::rotate - Archive the log file to a timestamped version and start a new one

Locks (g::lock)

• try [name] - Try to acquire a lock, returning g::util::true if successful
• acquire [name] - Acquire a lock, sleeping until it is available
• holds [name] - Check if we currently hold the given lock
• release [name] - Release the given lock if held
• singleton - Throw an error if this script is being executed concurrently
• singleton::acquire - Wait for other instances of this script to finish

App Framework (g::app)

g::app is a way of defining multi-directive CLI applications with argument/option parsing.

Each application is broken up into "commands," and each command can have multiple arguments/flags.

Your source code can provide multiple applications (switching between them using g::app) with app-scoped storage.

• g::app [?name=app] [?description] - Create a new top-level application
• get [name] [?default value] - Get the value of an app-scoped variable
• set [name] [value] - Set the value of an app-scoped variable
• has [name] - Check if the app-scope has a variable with the given name
• usage - Print usage information for the current application
• invoke [command] [...args] - Invoke a command in the current application

Defining Commands (g::app::command)

A command is an invokable sub-command function for an application, which can have multiple flags and positional arguments associated with it.

When a command is executed, its arguments are parsed and a function app::<app name>::<command name> is called. Basic example:

g::app myapp "An example application"

g::app::command greet "Greeting command"
g::app::command::arg name "Name of the person to greet" "World"
g::app::command::flag greeting= "Override the greeting"

function app::myapp::greet() {
    local args="$1"
    name="$(g::arg "$args" name)"
    greeting="$(g::flag "$args" greeting)"
    if [ -z "$greeting" ]; then
        greeting="Hello,"
    fi

    echo "$greeting $name"
}

• g::app::command [name] [?description] - Start defining a new command in the current app
• exists [name] - Check if a given command exists in the current app
• description [name] - Get the description for a command in the current app
• arg [name] [?description] [?default value] - Add a positional argument to the current command
• flag [name] [?description] - Add a position-less flag option. If name trails with a =, then a value is expected
• rest [name] [?description] - Register a rest-argument ([...args]) for the current command

Accessing Arguments

When arguments for a command are parsed, they are stored in an "argument set." The argument set is a series of data structures containing the parsed/validated flags & positional arguments.

The argument set ID is passed to the command handler as the only parameter ($1) and can be used to look up the values of flags and arguments.

• g::args [uuid] - Get the raw arguments from a parsed set (akin to $@)
• g::arg [uuid] [name] - Get the value of a positional argument
• g::arg::has [uuid] [name] - Checks if a positional argument was provided
• g::arg::rest [uuid] - Get all the unmatched CLI arguments/flags
• g::flag [uuid] [name] - Get the value of a position-less flag
• g::flag::has [uuid] [name] - Checks if a position-less flag was specified