Simplify your shell scripting workflow with self-documenting shell scripts with robust argument validation. Just prefix a comment with two pound signs (##) on the line above any function or variable to generate helpful documentation using the "help" command.
While GNU Make is a powerful build tool, it's not primarily designed for general-purpose scripting :
- Its specialized syntax for defining dependencies and build rules can be less intuitive and flexible compared to plain Shell scripting.
- Additionally, GNU Make may not be universally available across all Linux distributions, particularly in Android-based systems or minimal Docker containers like Alpine or Busybox.
- Also, a lack of dedicated linting and unit testing tools for Makefiles can hinder code quality and maintainability.
- Finally Makefile's parameter handling approach is inconvenient, often requiring the use of environment variables.
TangoMan Shoe Shell Microframework fills this gap by providing a lightweight, Posix-compatible alternative that's easy to set up, lint, test and use.
TangoMan Shoe Shell Microframework provides the following features:
- ⚡ Shell Script Boilerplate:
Use TangoMan Shoe Shell Microframework as a starting point for your own shell scripts, benefiting from its modular structure and best practices.
- ⚡ Semantic Output Coloring:
TangoMan Shoe Shell Microframework includes a suite of visually appealing and semantically meaningful color functions.
You can print primary, secondary, success, danger, warning, info, light and dark text with indentation and padding in any POSIX terminal.
- ⚡ Easy Annotation:
TangoMan Shoe Shell Microframework provides an intuitive annotation system that enables parameter validation and automatic documentation generation.
- ⚡ Self-Documenting Shell Scripts:
Prefix a comment with two pound signs (##) on the line above any function or variable, the help command will generate documentation on the fly.
- ⚡ Automatic Function-to-Command Conversion:
Define your functions as usual, they are automatically available as commands at runtime, making your scripting more intuitive.
- ⚡ Automatic Variable-to-Option Conversion:
Define your global variables as usual, they are converted as options at runtime.
- ⚡ Runtime Parameter Validation:
Append a regular expression (eg: /^a-zA-Z$/) at the end of any option's annotation, it will provide automatic validation at runtime.
- ⚡ Automatic Boolean-to-Flag Conversion:
Set a global variable to false, it creates a flag for simple on/off settings.
- ⚡ Automatic Shorthand:
Shorthand for commands, options and flags are automatically created.
- ⚡ POSIX Shell Compatibility:
TangoMan Shoe Shell Microframework is 100% POSIX compliant, run your scripts in virtually any environment, including containers and android based systems.
- ⚡ MacOS Compatibility Layer:
TangoMan Shoe Shell Microframework provides optional compatibility functions, since some shell commands syntax can vary between Mac and Linux (eg: sed).
- ⚡ Global Installation With Autocomplete:
Install and use your custom command across your system, TangoMan Shoe Shell Microframework will dump and load the appropriate comspec in your sh, bash or zsh terminal.
- ⚡ Extract Markdown Documentation Directly From Script Source:
Automate the generation of comprehensive Markdown documentation from a single source of truth. TangoMan Shoe Shell Microframework extracts information from the script annotations to generate documentation, it will never become outdated !
- ⚡ Automate Makefile Creation:
By extracting information from your shell scripts, it automatically generates Makefiles, complete with build rules and help messages.
- ⚡ Shellcheck Validation:
TangoMan Shoe Shell Microframework codebase is 100% shellcheck validated, it will not trigger any warnings or errors in your CI/CD pipeline.
- ⚡ Unit Test Coverage:
TangoMan Shoe Shell Microframework codebase is thoroughly covered with bashunit tests, ensuring code quality and reliability.
- ⚡ Command Grouping:
Prefix a comment with three pound signs (###) to organize related commands into categories for better help output.
- ⚡ Shoemaker Developement Tool:
Use shoemaker.sh tool to split a script file into its components, build a script from a "build.lst" file, generate Makefile or Markdown documentation from a shoe script.
- ⚡ Code Snippets:
In addition, TangoMan Shoe Shell Microframework includes a library of reusable code snippets that cover common use cases, saving you time and effort.
- Full Shoe documentation can be found here: ./doc/shoe.md
- Documentation for
shoemaker.shcan be found here: ./doc/shoemaker.md - Documentation for
entrypoint.shcan be found here: ./doc/entrypoint.md
Prefix a comment with two pound signs (##) on the line above any function or variable to generate helpful documentation using the help command.
help prints commands in the order they appear in the script.
Group commands by categories by dividing them with a comment prefixed with three pound signs (###).
Change displayed title and description by editing docblock infos at the top of the actual file.
#/**
# * Script Title
# *
# * Place here script description.
# *
# * @author "Your Name" <your@email.com>
# * @version 0.1.0
# * @link https://your.website.com
# * @update-link https://raw.githubusercontent.com/<USERNAME>/<REPOSITORY>/refs/heads/main/<SCRIPT>.sh
# */TangoMan Shoe Shell Microframework allows you to use short versions (shorthands) for functions, flags, or options with a specific alphabetial character. Only the first occurrence of each letter can be used as a shorthand. These shorthands work based on the order they appear in the script.
$ sh shoe.sh h
# will return the same result as
$ sh shoe.sh hello
# but it will NOT execute "help"$ sh shoe.sh hello -f
# is the same as
$ sh shoe.sh hello --foobar
# and
$ sh shoe.sh hello -w TangoMan
# is the same as
$ sh shoe.sh hello --who TangoManAny uppercase variable is considered a constant withing the framework, they cannot be directly modified from the command line but will be displayed in the help output.
Elements prefixed with an underscore are considered private.
This means they are not visible in the help output and cannot be accessed or invoked from the command line.
#--------------------------------------------------
# Place your options after this line
#--------------------------------------------------
## Greeting recipient name /^[a-zA-Z-]+$/
who="World"
#--------------------------------------------------
# Place your flags after this line
#--------------------------------------------------
# (any variable set to "false" will convert to a flag at runtime)
## Example Flag
flag=false
#--------------------------------------------------
# Place your private constants after this line
#--------------------------------------------------
## This constant is private (it will not de displayed in the "help" output)
_PRIVATE="I'm a private constant"
#--------------------------------------------------
# Place your global variables after this line
#--------------------------------------------------
## This variable is private (it will not de displayed in the "help" output)
_global_variable="I'm a global variable"
#--------------------------------------------------
# Place your functions after this line
#--------------------------------------------------
## Greets a specified recipient a given number of times
hello() {
# the recipient's name is provided with the "--who" option
# the repetition count is provided with the "--count" option
loop=0
while [ "${loop}" -lt "${count}" ]; do
echo "Hello ${who} !"
loop=$((loop+1))
done
}
## Prints flag status
flag_test() {
if [ "${flag}" = true ]; then
echo "Flag is on"
return 0
fi
echo "Flag is off"
}
#--------------------------------------------------
# Place your private functions after this line
#--------------------------------------------------
# Private functions are prefixed with underscore, they cannot be called from the command line and will not appear in the help section.
_private() {
echo "I'm private"
}The example above will generate this result:
If you provide an unrecognized command, the script will display an error message like this:
Similarly, an invalid option will trigger an error message:
Illegal arguments will also result in an error message:
Due to inherent limitations in awk's regular expression capabilities, interval syntax (e.g., {1,3}) is not supported.
For instance, the following regular expression, will not function as expected:
## Local IP address /^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$/
ip=127.0.0.1
However, the following alternative, which uses the + quantifier to match one or more digits, will work correctly:
## Local IP address /^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/
ip=127.0.0.1
hello function thee times.
$ sh shoe.sh hello hello hello$ sh shoe.sh hello --who=foo --who=barThe command above will return :
Hello bar !
TangoMan Shoe Shell Microframework adheres to the Google Shell Style Guide, promoting consistent and readable scripts. You can find the guide here: https://google.github.io/styleguide/shellguide.html
POSIX shell has no variable scope limitations.
To mitigate potential name collisions, variables in kernel use dunder syntax (double underscores).
Ideally, to avoid variable-related issues entirely within Shoe private functions, it's recommended to use positional arguments.
This involves assigning values to positional parameters using the set command (eg: set -- "$1" "$2" "$3").
To maintain a consistent developper experience, required arguments, particularly file paths, should be specified first. Optional arguments can be added after these.
TangoMan Shoe Shell Microframework requires the following dependencies:
- Awk
- Sed
- Shell (ash supported)
- Docker (dev)
- bash_unit (dev)
- Shellcheck (dev)
Thank you for your interrest in contributing to TangoMan Shoe Shell Microframework.
Please review the code of conduct and contribution guidelines before starting to work on any features.
If you want to open an issue, please check first if it was not reported already before creating a new one.
Copyrights (c) 2024 "Matthias Morin" <mat@tangoman.io>
If you like TangoMan Shoe Shell Microframework please star, follow or tweet:
... And check my other cool projects.
- This script was inspired by Peter Forret bashew
- bash_unit: bash unit testing enterprise edition framework (used for CI/CD)
- shellcheck: a static analysis tool for shell scripts (used for CI/CD)