Module system - bash::framehead

Module overview

bash::framehead provides 16 specialized modules totaling ~785 functions. Each module focuses on a specific domain and follows consistent design patterns.

Available modules

string

115 functions — Case conversion, padding, splitting, encoding, validation, UUID, base64/32

fs

79 functions — Read/write, paths, find, checksums, temp files, symlinks, permissions

timedate

74 functions — Dates, times, durations, timezones, calendars, stopwatch

terminal

74 functions — Cursor control, screen manipulation, input handling, color detection

colour

65 functions — 4-bit, 8-bit, 24-bit color, ANSI escapes, strip, wrap

math

53 functions — Integer and float arithmetic, trig, stats, unit conversion

process

51 functions — Query, signal, lock, retry, timeout, jobs, services

runtime

50 functions — OS/arch detection, shell flags, environment introspection

array

42 functions — Slice, sort, filter, set operations, zip, chunk, rotate

net

38 functions — IP, DNS, HTTP, interfaces, fetch, ping, port scan

git

35 functions — Branch, commit, status, stash, tags, remotes

hardware

34 functions — CPU, RAM, GPU, disk, battery, partitions

device

25 functions — Block devices, loop, TTY, mount, filesystem

hash

23 functions — MD5, SHA*, HMAC, FNV, DJB2, CRC32, UUID5, slots

random

22 functions — Native, LCG, xorshift, PCG32, xoshiro, ISAAC, WELL512

pm

5 functions — Package manager abstraction (apt/pacman/brew/dnf/…)

Core module: runtime

The runtime module (331 lines) is the foundation of the entire framework. Every other module depends on it.

Key capabilities

Environment detection:

src/runtime.sh:2-5

runtime::is_terminal() {
  # Thorough check for all standard file descriptors
  [[ -t 0 && -t 1 && -t 2 ]]
}

Command availability:

if runtime::has_command bc; then
    result=$(math::bc "22/7" 2)
fi

Shell flag detection:

src/runtime.sh:27-29

runtime::errexit_enabled() {
    [[ "$-" == *e* ]]
}

Version checking:

if runtime::is_minimum_bash 5; then
    # Use Bash 5+ features
fi

You can remove any module except runtime.sh when compiling a custom build. See compilation for details.

String module

The largest module at 933 lines, string provides comprehensive text manipulation.

Function categories

Inspection:

src/string.sh:11-13

string::length() {
  echo "${#1}"
}

src/string.sh:27-29

string::contains() {
  [[ "$1" == *"$2"* ]]
}

Case conversion:

src/string.sh:93-95

string::upper() {
  echo "${1^^}"
}

Bash 3 compatibility variants are provided with ::legacy suffix:

src/string.sh:98-100

string::upper::legacy() {
  echo "$1" | tr '[:lower:]' '[:upper:]'
}

Validation:

src/string.sh:50-52

string::is_integer() {
  [[ "$1" =~ ^-?[0-9]+$ ]]
}

src/string.sh:55-57

string::is_float() {
  [[ "$1" =~ ^-?[0-9]+(\.[0-9]+)?([Ee][+-]?[0-9]+)?$ ]]
}

Case system matrix

The string module includes 56 conversion functions between 8 naming conventions:

From / To	snake_case	kebab-case	camelCase	PascalCase	CONSTANT	plain text	dot.case	path/case
snake_case	—	✓	✓	✓	✓	✓	✓	✓
kebab-case	✓	—	✓	✓	✓	✓	✓	✓
camelCase	✓	✓	—	✓	✓	✓	✓	✓
PascalCase	✓	✓	✓	—	✓	✓	✓	✓
CONSTANT	✓	✓	✓	✓	—	✓	✓	✓
plain text	✓	✓	✓	✓	✓	—	✓	✓
dot.case	✓	✓	✓	✓	✓	✓	—	✓
path/case	✓	✓	✓	✓	✓	✓	✓	—

See the string module reference for the complete function list.

Math module

The math module (841 lines) handles both integer and floating-point arithmetic.

Integer operations

Pure Bash implementations with no external dependencies:

math::abs -5           # 5
math::factorial 10     # 3628800
math::fibonacci 7      # 13
math::is_prime 17      # exit 0 (true)

Floating-point operations

Floating-point functions require bc and check availability:

src/math.sh:37-44

math::bc() {
    local expr="$1" scale="${2:-$MATH_SCALE}"
    if ! math::has_bc; then
        echo "math::bc: requires bc (GNU coreutils)" >&2
        return 1
    fi
    echo "scale=${scale}; ${expr}" | bc -l
}

Mathematical constants

The module provides high-precision constants (42 digits):

src/math.sh:16-26

readonly MATH_PI="3.141592653589793238462643383279502884197169"
readonly MATH_E="2.718281828459045235360287471352662497757237"
readonly MATH_PHI="1.618033988749894848204586834365638117720309"
readonly MATH_SQRT2="1.414213562373095048801688724209698078569671"
readonly MATH_LN2="0.693147180559945309417232121458176568075500"
readonly MATH_TAU="6.283185307179586476925286766559005768394338"  # 2π

Precision for floating-point calculations defaults to 10 decimal places but can be overridden via MATH_SCALE environment variable.

Array module

The array module (438 lines) provides functional-style array operations.

Usage pattern

Bash arrays can’t be passed by value, so functions accept elements as $@:

src/array.sh:3-11

# array.sh — bash-frameheader array lib
# Requires: runtime.sh (runtime::is_minimum_bash)
#
# USAGE NOTE: Bash arrays cannot be passed by value — callers must use
# nameref (Bash 4.3+) or pass elements as individual arguments.
# Functions that take arrays expect elements as "$@" unless noted.

Example usage:

array::first a b c              # a
array::last a b c               # c
array::reverse a b c            # c\nb\na
array::contains b a b c         # exit 0 (true)

Construction utilities

src/array.sh:18-40

array::from_string() {
    local delim="$1" s="$2"
    local elements
    elements=$(echo "$s" | awk -v d="$delim" 'BEGIN {ORS="\n"} {
        gsub(d, "\n")
        print
    }')
    echo "$elements"
}

Filesystem module

The fs module (523 lines) handles all file and path operations.

File tests

Clean wrappers around Bash test operators:

fs::exists /path/to/file     # exit 0 if exists
fs::is_file /path            # exit 0 if regular file
fs::is_dir /path             # exit 0 if directory  
fs::is_symlink /path         # exit 0 if symlink
fs::is_readable /path        # exit 0 if readable
fs::is_writable /path        # exit 0 if writable

Path manipulation

Portable path operations without basename/dirname:

fs::path::basename /foo/bar/test.txt    # test.txt
fs::path::dirname /foo/bar/test.txt     # /foo/bar
fs::path::extension file.txt            # txt
fs::path::extensions file.tar.gz        # tar.gz
fs::path::stem file.txt                 # file
fs::path::join a b c                    # a/b/c

Hash module

The hash module (367 lines) provides cryptographic and non-cryptographic hashing.

Available algorithms

Cryptographic:

hash::md5 — MD5 digest
hash::sha1 — SHA-1 digest
hash::sha256 — SHA-256 digest
hash::sha512 — SHA-512 digest
hash::sha3_256 — SHA3-256 (requires openssl/python3)
hash::blake2b — BLAKE2b (requires openssl/python3)

Non-cryptographic (pure Bash):

hash::djb2 — DJB2 string hash
hash::djb2a — DJB2a variant
hash::sdbm — SDBM hash
hash::fnv1a32 — FNV-1a 32-bit
hash::fnv1a64 — FNV-1a 64-bit
hash::adler32 — Adler-32 checksum
hash::crc32 — CRC32 checksum

HMAC support

Message authentication codes with OpenSSL:

hash::hmac::sha256 "secret-key" "message"
hash::hmac::sha512 "secret-key" "message"
hash::hmac::md5 "secret-key" "message"

Testing coverage

The framework includes 785 test cases in main.sh:146-2800:

main.sh:240-247

echo "--- string ---"
_test "string::upper"              "HELLO"          "$(string::upper hello)"
_test "string::lower"              "hello"          "$(string::lower HELLO)"
_test "string::length"             "5"              "$(string::length hello)"
_test "string::contains (true)"    "0"              "$( string::contains hello ell; echo $? )"
_test "string::reverse"            "olleh"          "$(string::reverse hello)"
_test "string::trim"               "hello"          "$(string::trim "  hello  ")"

Run the full test suite:

./main.sh test ./compiled.sh
# === Results: 659 passed, 0 failed, 8 skipped, 1 untested ===

Module interdependencies

Minimal coupling enables customization:

Only runtime.sh is mandatory. All other modules depend solely on runtime, allowing you to remove any modules you don’t need.

Next steps

Architecture

Understand the overall framework design

Compilation

Learn how to build custom distributions

Naming conventions

Master the module::function pattern

API Reference

Browse the complete function reference

Get Started

Core Concepts

Development

​Module overview

​Available modules

string

fs

timedate

terminal

colour

math

process

runtime

array

net

git

hardware

device

hash

random

pm

​Core module: runtime

​Key capabilities

​String module

​Function categories

​Case system matrix

​Math module

​Integer operations

​Floating-point operations

​Mathematical constants

​Array module

​Usage pattern

​Construction utilities

​Filesystem module

​File tests

​Path manipulation

​Hash module

​Available algorithms

​HMAC support

​Testing coverage

​Module interdependencies

​Next steps

Architecture

Compilation

Naming conventions

API Reference

Build docs developers (and LLMs) love

Module overview

Available modules

Core module: runtime

Key capabilities

String module

Function categories

Case system matrix

Math module

Integer operations

Floating-point operations

Mathematical constants

Array module

Usage pattern

Construction utilities

Filesystem module

File tests

Path manipulation

Hash module

Available algorithms

HMAC support

Testing coverage

Module interdependencies

Next steps