bashdrop Goto Github PK

About • Disclaimer • Getting Started • How To Use • Style Guidelines • Credits • License

Bashdrop is a micro-framework that provides a starting point for your console application.

GitHub offers a simple approach to generating a new repository with the same directory structure and files as the Bashdrop repository. You can click Use this template button or alternatively follow the steps in GitHub Creating a repository from a template for a step by step guide.

Documentation on the architectural concepts has been outlined below for you to get started:

To run the Bashdrop console app, you can run the app script:

$_ ./app

The app script will show a list of available commands. To invoke a command, you can provide your command name and the required arguments to the app script:

$_ ./app command argument

The entry point to the Bashdrop Shell Script is bin/bashdrop. This will trigger the main function, which is located in bin/bootstrap/app.sh. There is an alias shell script for this file in the root directory of the project, called app

Files prefixed with an underscore will source Shell files. Consider these files as Shell file importers. The _lib.sh will source third-party dependencies and other Shell file importers. Importers include a read-only array of dependencies within their domain e.g. the commands importer which is located in bin/lib/commands/_commands.sh

# bin/lib/_lib.sh

readonly DEPENDENCIES=(
  "commands"
  "console"
  "core"
  "filesystem"
  "support"
  "utils"
)

for DEPENDENCY in "${DEPENDENCIES[@]}"; do
  # shellcheck source=/dev/null
  source "${LIB_DIR}/${DEPENDENCY}/_${DEPENDENCY}.sh"
done

All of the environment variables listed in the .env file will be loaded into your console application. You can use the dotenv::get function to retrieve values from these variables.

APP_NAME="$(dotenv::get APP_NAME --default=Bashdrop)"

The second argument passed to the dotenv::get function is the "default value". This value will be returned if no environment variable exists for the given key.

You can create a config file in the bin/config directory. The recommended naming convention for global configuration variable names is to use upper case and snake case.

export APP_NAME="Bashdrop"

You will need to register your config file in the _config.sh Shell file importer.

# bin/lib/config/_config.sh

readonly CONFIGS=(
  "app"
  "filesystem"
  "git"
  "help"
  "modules"
)

The global configuration values may be accessed providing the variable name with the "${}" syntax.

"${APP_NAME}"

You can build your own custom commands. Commands are typically stored in the bin/lib/commands directory. You will need to register your command file in the _commands.sh Shell file importer.

# bin/lib/commands/_commands.sh

readonly COMMANDS=(
  "about"
  "docs"
  "help"
  "self_update"
  "usage"
  "version"
)

Let's take a look at an example command.

# shellcheck shell=bash
#
# Bashdrop example command.

#######################################
# An example command.
#
# Globals:
#   APP_NAME
#
# Arguments:
#   User input
#
# Outputs:
#   Writes messages to stdout.
#
# Returns:
#   1 if user provides invalid
#   combination of arguments.
#######################################
function command::example() {
  local message=$*

  console::output "${message}"
}

We can invoke our command as follows:

$_ ./app example Hello
Hello

To pass arguments to a Bash function, add the parameters after the function call separated by spaces. The table below outlines the available options when working with bash function arguments.

Unfortunately, Bash functions do not support named parameters. Users will need to provide the command's arguments in the exact order for the function to correspond the argument's position.

If your command as optional arguments or options, invoking the command can be challenging for users. Bashdrop solves this problem with additional code added to a Bash function.

# shellcheck shell=bash
#
# Bashdrop example command.

#######################################
# An example command.
# 
# Globals:
#   APP_NAME
#
# Arguments:
#   User input
#
# Outputs:
#   Writes messages to stdout.
#
# Returns:
#   1 if user provides invalid
#   combination of arguments.
#######################################
function command::example() {
  # Provide list of excepted options to array.
  local options_list=("directory")
  local directory
  local file=$*

  # This code will match the corresponding options of the provided user arguments 
  while [ $# -gt 0 ]; do
    if [[ $1 == *"--"* && $1 == *"="* ]]; then
      local option="${1/--/}"
      IFS='=' read -ra parameter <<< "${option}"

      if [[ "${options_list[*]}" =~ ${parameter[0]} ]]; then
        file="${file/--${option}/}"
        declare "${parameter[0]//-/_}"="${parameter[1]}"
      fi
    fi

    shift
  done

  unset options_list

  console::output "${directory}/${file}"
}

Options, like arguments, are another form of user input. Options are prefixed by two hyphens (--) when they are provided via the command line.

We can invoke our command as follows:

$_ ./app example example.txt --directory=/app
/app/example.txt

# You can change the order of the arguments
$_ ./app example --directory=/app example.txt
/app/example.txt

Bashdrop uses the Google Shell Style Guide.

This software uses the following open-source packages:

• ANSI Code Generator

The MIT License (MIT). Please see License File for more information.