BashX | Bash eXtended

Description

• Bash Framework.
• Helps to bash scripting.
• Add common functions to help the developer.
• Compatible with Android Shell.
• Auto-documentation/help generation.

Why use it

• Very easy to implement.
• No additional components required.
• No need to learn a new language.
• No need to learn a new syntax.
• Common functions and utils already implemented.
• Auto-documentation/help from source code comments.
• Solution to common SO compatibility problems (sed -i ... on Linux and sed -i '' ... on Mac). See @sed

Quick start

You can start your project with:

./bashx _bashx init project {BASHX_VERSION} {PROJECT_PATH}

Where:

• BASHX_VERSION is a tag from this repository
• PROJECT_PATH is the script name with full path.

Examples

./bashx _bashx init project v3.1.2 my-app

./bashx _bashx init project v3.1.2 ~/projects/my-script.sh

Manual start

1) Add next at beginning of the script file:

#!/usr/bin/env bash

###############################################################################
# BashX | https:/reduardo7/bashx
set +ex;export BASHX_VERSION="v3.1.2"
(export LC_CTYPE=C;export LC_ALL=C;export LANG=C;set -e;x() { s="$*";echo "# Error: ${s:-Installation fail}" >&2;exit 1;};d=/dev/null;[ ! -z "$BASHX_VERSION" ] || x BASHX_VERSION is required;export BASHX_DIR="${BASHX_DIR:-${HOME:-/tmp}/.bashx/$BASHX_VERSION}";if [ ! -d "$BASHX_DIR" ];then u="https://raw.githubusercontent.com/reduardo7/bashx/$BASHX_VERSION/src/setup.sh";if type wget >$d 2>&1;then sh -c "$(wget -q $u -O -)" || x;elif type curl >$d 2>&1;then sh -c "$(curl -fsSL $u)" || x;else x wget or curl are required. Install wget or curl to continue;fi;fi) || exit $?
. "${HOME:-/tmp}/.bashx/${BASHX_VERSION}/src/init.sh"
###############################################################################

See /bashx

2) Write your code.

3) Optionally, add next at end of the script file, to work as cli:

@app.run

Project Example

#!/usr/bin/env bash

###############################################################################
# BashX | https:/reduardo7/bashx
set +ex;export BASHX_VERSION="v3.1.2"
(export LC_CTYPE=C;export LC_ALL=C;export LANG=C;set -e;x() { s="$*";echo "# Error: ${s:-Installation fail}" >&2;exit 1;};d=/dev/null;[ ! -z "$BASHX_VERSION" ] || x BASHX_VERSION is required;export BASHX_DIR="${BASHX_DIR:-${HOME:-/tmp}/.bashx/$BASHX_VERSION}";if [ ! -d "$BASHX_DIR" ];then u="https://raw.githubusercontent.com/reduardo7/bashx/$BASHX_VERSION/src/setup.sh";if type wget >$d 2>&1;then sh -c "$(wget -q $u -O -)" || x;elif type curl >$d 2>&1;then sh -c "$(curl -fsSL $u)" || x;else x wget or curl are required. Install wget or curl to continue;fi;fi) || exit $?
. "${HOME:-/tmp}/.bashx/${BASHX_VERSION}/src/init.sh"
###############################################################################

@Actions.action1() { # \\n Action without arguments
  @log "
  Action 1
  Multi-Line
"
}

@Actions.action2() { # param1 [param2] \\n Action with arguments\\n\\tdescription second line\\nother line
  local param1="$1"
  local param2="$2"
  [ "$param1" != 'asd' ] && @throw.invalidParam param1

  @log Action 2
  @log Param1: $1
  @log Param2: $2
}

@app.run

Project Structure

--> project-directory-name          # Optional. Container directory.
    |                               #
    +-> my-script-name              # Required. Main script.
    |                               #
    +-> .my-script-name.env         # Optional. Config file.
    |                               #
    +-> my-script-name.src/         # Optional. Sources.
        |                           #
        +-> actions/                # Optional. Actions scripts.
        |   |                       #
        |   +-> [group...]          #    Script group. Can be multi-level.
        |   |   |                   #
        |   |   +-> [name].xsh      #      Test script into group example... (Use with @group.name)
        |   |                       #
        |   +-> [action-name].xsh   #    Test script example...
        |   |                       #
        |   +-> *                   #    Test script example...
        |                           #
        +-> tests/                  # Optional. Test scripts.
        |   |                       #
        |   +-> [test-name].xsh     #     Test script example...
        |   |                       #
        |   +-> *                   #     Test script example...
        |                           #
        +-> utils/                  # Optional. Utils scripts.
        |   |                       #
        |   +-> [util-name].xsh     #     Test script example...
        |   |                       #
        |   +-> *                   #     Test script example...
        |                           #
        +-> events/                 # Optional. Events scripts. Executed in next order:
        |   |                       #
        |   +-> invalid-action.xsh  #     Optional. Triggered on invalid action called.
        |   |                       #
        |   +-> ready.xsh           #     Optional. Triggered on ready.
        |   |                       #
        |   +-> start.xsh           #     Optional. Triggered on start the selected action.
        |   |                       #
        |   +-> error.xsh           #     Optional. Triggered on error (exit code != 0).
        |   |                       #
        |   +-> finish.xsh          #     Optional. Triggered on execution finished.
        |                           #
        +-> resources/              # Optional. Resources files.
            |                       #
            +-> [resource].[ext]    #     Resource file...
            |                       #
            +-> *                   #     Resource file...

Valid events options constant: BX_EVENTS_OPTS.

Doc

Go to src/README.md documentation for more details.

Development Documentation

Show Development Documentation using:

./bashx _dev-doc

Framework Utilities

Show Framework Utilities Documentation using:

./bashx _bashx

Global Variables

BASHX_COLORS_DISABLED

Set vale to 1 to disable BashX output colors, disabling the @style function.

Example:

BASHX_COLORS_DISABLED=1 ./bashx

Tips

Print/Log (echo ...)

• echo is used for function output.
• Use @log to print log messages.
• Use @log.warn to print warning messages.

Command log (set -x)

• Avoid usage of BashX Functions inside of set -x section.

Command log examples

...
( set -x
  ...
  echo my test
  ...
)
...

...
set -x
  ...
  echo my test
  ...
set +x
...

APP Exit & Error

• Use @app.exit to exit.
• Use @app.error to print an error and exit.

Events Workflow

1. src/events/invalid-action.xsh is triggered if an invalid action was used.
2. src/events/ready.xsh is triggered on the initialization is complete.
3. src/events/start.xsh is triggered before a valid action is called.
4. src/events/error.xsh is triggered when an error has occurred.
5. src/events/finish.xsh is triggered on execution finished.

Valid events options constant: BX_EVENTS_OPTS.

Optimizations

See: http://tldp.org/LDP/abs/html/optimizations.html

Testing with Docker

docker run --rm \
  -v $(pwd):/root/.bashx/master:ro \
  -v $(pwd):/app:ro \
  -w '/app' \
  -ti ubuntu '/app/bashx'

docker run --rm \
  -v $(pwd):/root/.bashx/master:ro \
  -v $(pwd):/app:ro \
  -w '/app' \
  -ti debian:8 '/app/bashx'

Notes

VIM

In order to make VIM syntax check and code format work, add the following line at the end of your .xsh file:

# vim: filetype=sh tabstop=2 softtabstop=0 expandtab shiftwidth=2 smarttab

Constants & Config Variables

All BashX constants starts with BX_, and configuration starts with BASHX_.