bashUtils is a collection of (more or less) useful functions.

Sourcing the loader.sh script and running the loadBashUtils function will give you access to all functions described below.

NOTE: Some functions use global variables. Variable names starting with __CLASS or __INTERNAL should be avoided

• Object Oriented BASH
  • Example
  • Object operators
• Bash Curses
• Bash C bindings
  • WARNING - read this
  • Function definition file Syntax
• Logging functions
• Util functions

# base.sh

class Base
  private:
    -- var

  protected:
    :: print

  public:
    :: Base
    :: ~Base
ssalc

Base::print() {
  msg1 "Base: var: '$($1 . var)'"
}

Base::Base() {
  msg1 "Constructing Base"
  $1 . var "Hello World"
}

Base::~Base() {
  msg1 "Destructing Base"
}

# vector.sh

class Vector Base # Start class definition
  private:
    -- x
    -- y
    -- z
    :: privateFunc

  public:
    :: Vector  # Constructor
    :: ~Vector # Destructor
    :: show
ssalc        # End class definition

# $1 is always a 'pointer' to this
Vector::Vector() {
  msg1 "Constructing $($1 classname)"

  $1 . x "$2" # Sets attr x to 0
  $1 . y "$3"
  $1 . z "$4"
}

Vector::~Vector() {
  msg1 "Destructing $($1 classname)"
}

Vector::privateFunc() {
  msg1 "PRIVATE echo: ${@:2}"
}

Vector::show() {
  msg1 "Vector '$($1 name)':"
  msg2 "X: $($1 . x)"
  msg2 "Y: $($1 . y)"
  msg2 "Z: $($1 . z)"
  $1 . privateFunc "Hello" "World" # Output: "PRIVATE echo: Hello World"
  $1 . print # In Base class
  # $1 . var # ERROR
}

# main.sh

Vector vec1 5 5 6
vec1 . show
#vec1 . privateFunc # ERROR: privateFunc is private
#vec1 . y 5         # ERROR: y is private
vec1 destruct
#vec1 . show        # Bash error: vec1: command not found

bashUtils provides classes to read and parse the terminfo file for the current terminal and create ncurses like windows and mouse input.

The class bTermInfo is responsible for loading the terminfo file and setting the COLUMNS and LINES environment variables.

All parsed data can be accessed via <objectName> . <CapName>. All CapNames are listed in the terminfo manpage.

The main / init class.

Special key names are the CapNames from the terminfo manpage.

Parameters:

Buttons:

Base class for all objects

Note: all coordinates start with 1, 1. NOT 0, 0

4000000000005
2           3
2           3
2           3
6111111111117

• off
• bold
• italic
• underline
• blink
• inverse
• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white

bashUtils provides a (base) class to create bindings for c-style functions and callbacks via c-style function pointers.

bashUtils uses a c program running in background to call the c functions. This program can be automatically generated with a simple function definition file (bind.def) in the binding root directory.

Short example:

class Bind1 BASHBinding # Inheriting everything from BASHBinding
  public:
    :: f1 # f1 is a c function
ssalc

Bind1 binding /path/to/binding/source/root /path/to/an/empty/directory/for/FIFOs
binding . bbind_compile
binding . bbind_start

binding . f1 "arg1"
msg1 "Return value of c function f1: $OUT_0"

binding destruct

Setting BASH_BINDING_START_WITH_GDB to 'true' will start the program with gdb.

Here is a working example with a simple c lib.

WARNING To support c pointers bashUtils does some questionable casting!

(pointer -> size_t -> c string -> Your Script -> c string -> size_t -> pointer)

A pointer in BASH is represented as an unsigend integer (base 10) with the prefix \x01PTR. So it is theoretically possible to do pointer arithmetic in BASH!

Because bashUtils supports low level c pointes your script might be partialy responsible for memory management. You can even malloc and free memory in your script (if you write the binding)!

I strongly recommend to avoid pointers whenever possible and to NEVER modify a pointer in BASH!

This file is used to automatically generate the c program. It contains all information about the function pointer types and functions.

NOTE: The filename has to be bind.def.

Commands:

Usage:

subdir: [<name>] <path>
# Example:
subdir: [lib1] ./lib1

Adds the <path> CMake subdirectory and <path> to the include directories. It will also link the final program against <name>.

NOTE: This command assumes that <name> is a library added with the CMake command add_library!

Usage:

includeDir: <path>
# Example:
includeDir: /ust/local/include

Adds <path> to the include directories.

Usage:

include: <filename>
# Example:
include: lib1.h

Adds #include <filename> to the c file.

This section starts with the command beginCallback:.

Just copy and paste the typedef into this section (without the typedef keyword, argument names and the ';') All typedefs will be automatically resolved.

Every argument cancontain metadata (default: none). Metadata can be set inside | chars.

This section starts with the command beginBinding:.

Just copy and paste the function prototypes into this section (without the argument names and the ';') All typedefs will be automatically resolved.

Every argument contains metadata (default: in). Metadata can be manualy set inside | chars.

Usage:

void func( int *|<metadata goes here>| )
Example:
void func( int * |in out :2|, size_t )

ask() {} # 3 Args: <question> <default> <VAR>

Prints a question to stdout and reads a line from stdin

printNumChar() {} # 2 Args: <char> <num>

Prints num times char

Prints logging message $*, a backtrace and exits

die_expected() {} # 2 Args: <expected> <wrong string>

argsRequired() {} # 2 Args: <expected args> <num args>

Dies if expected args != num args

fileRequired() {} # 2 Args: <filename> <error>

Test if file exists. When it does not it dies error=require or creates the file error=create

programRequired() {} # 1 Args: <program>

Test if program exists in path. When it does not it dies

assertEqual() {} # 2 Args: <value> <expected>

assertDoesNotContain() {} # 2 Args: <string> <substring>

dies if string contains substring

downloadFile() {} # 3 Args: <source> <output> <error>

Tries to download file source to output. On error: error=die: Program dies; else it prints a warning / error.

NOTE: this function requires wget

Config options can be read and set vie the CONFIG array

addToConfig() {} # 3 Args: <name> <default> <description>

Adds a config option

parseConfigFile() {} # 1 Args: <filenema>

generateConfigFile() {} # 1 Args: <filenema>

Functions for thread synchronization. A thread can be locked with FIFOwait and unlocked from an other thread via FIFOcontinue.

NOTE: those functions create temporary FIOS! Make sure you are using an empty directory to avoid collisions.

FIFOwait() {} # 1 Args: <fifoname>

FIFOcontinue() {} # 1 Args: <fifoname>