🥊 mulle-bashfunctions, a collection of shell functions

This is a shell function library used by a lot of mulle tools. It is compatible with bash v3.2+ and zsh 5+. Use mulle-bashfunctions to develop more featureful scripts that work on multiple platforms. This library has been tested on Debian, FreeBSD, macOS, Manjaro, MinGW, NetBSD, OpenBSD, Solaris, Ubuntu.

Release Version	Release Notes
	RELEASENOTES

Executables

Executable	Description
mulle-bash	Shell executor as a replacement for #! /bin/sh
mulle-bashfunctions	Include support, documentation and more

Developer Guide

Use mulle-bashfunctions in an old bash script

Add this near the top of your script. This will load the default set of mulle-bashfunctions:

eval "`mulle-bashfunctions load --if-missing `"
[ -z "${MULLE_BASHGLOBAL_SH}" ] && exit 1

Create a new mulle-bash script

To create a new mulle-bashfunctions script say:

mulle-bashfunctions new my-script > my-script.sh
chmod +x my-script.sh

Use mulle-bashfunctions also for discovery and documentation of the available functions. Lets say you want to produce identifiers for arbitrary strings. You can use apropos to discover functionality:

mulle-bashfunctions apropos identifier

Once you have found a function of interest, you can checkout its description with:

mulle-bashfunctions man r_smart_downcase_identifier

and try it out with eval for functions printing to standard output, or r-eval, for functions that return values in the RVAL global variable (these functionss are prefixed with r_):

$ mulle-bashfunctions r-eval r_smart_downcase_identifier MyScript
my_script

Finally say

mulle-bashfunction embed < my-script.sh > my.sh

to create a standalone script. This script will run with #! /bin/sh and does not need a mulle-bashfunctions installation.

Libraries

Your script running under #! /usr/bin/env mulle-bash will have mulle-bashfunction.sh preloaded. So you have access to a basic selection of libraries, namely:

Name	Descriptions
compatibility	abstraction of zsh and bash differences
logging	log support with colorization, zero cost if unused
exekutor	run external commands with logging and "dry-run"
file	functions to manage files, directories, symlinks
options	default handling of command line options and trace support
path	functions dealing with file paths
string	a multitude of string functions

Use include "<name>" to get access to the functions not included in mulle-bashfunctions.sh namely:

Name	Descriptions
array	maintain arrays as a string separated by linefeeds
case	perform camelCase conversions
etc	maintain a writable etc folder, shadowed by read-only share
parallel	execute parallel processes without swamping the machine
url	URL parser
version	semver version management major.minor.version

Usage

Usage:
   mulle-bashfunctions [command]

   Use mulle-bashfunctions to

   * load the mulle-bashfunctions into an interactive shell
   * show documentation for the provided shell functions
   * embed "mulle-bashfunctions.sh" into another shell script
   * show the path to "mulle-bashfunctions.sh"
   * locate the "mulle-bashfunctions.sh" install path for a desired variant
   * list the available libraries, which you can "include"
   * run an arbitrary mulle-bashfunction with eval and r-eval
   * get some information about the execution environment

Example:
   Load mulle-bashfunctions into the current interactive shell:

      eval `mulle-bashfunctions load all`

   Now try out an r_function, a function which returns a value in the global
   variable RVAL:

      r_escaped_json '{ "url": "https://www.mulle-kybernetik.com" }'
      echo $RVAL

Commands:
   apropos <f>    : search for a function by keywords
   embed          : embed mulle-bashfunctions into a script
   common-unames  : list of known values for uname
   env            : print environment needed for "mulle-bashfunctions.sh"
   eval <cmd>     : evaluate cmd inside of mulle-bashfunctions
   globals [-a]   : list global MULLE_ prefixed variables, -a for all globals
   functions      : list defined functions
   hostname       : show system hostname as used by mulle-bashfunctions
   libraries      : list available libraries
   load [variant] : eval `mulle-bashfunctions load <none|minimal|all>`
   man <function> : show documention for function, if available
   new <name>     : prints a mulle-bash shell script
   path [variant] : path to "mulle-bashfunctions.sh"
   r-eval <cmd>   : evaluate cmd inside of mulle-bashfunctions and print RVAL
   shell          : path of executing shell
   username       : show username as used by mulle-bashfunctions
   uname          : show system short name as used by mulle-bashfunctions
   uuid           : generate a UUID
   version        : print currently used version
   versions       : list installed versions

Developer Info

Runtime environment

If run under zsh, mulle-bashfunctions.sh will setopt sh_word_split and setopt POSIX_ARGZERO and will also set -o GLOB_SUBST.

• pipefail is set and expected to be kept.
• extglob is set and required for bash and zsh for a few functions.
• expand_aliases is set and required for use of the .for .do .done macros.
• -u or +u should work
• -e will not work (!)
• posix is turned off

Glob settings are unaffected and expected to be enabled by default.

Conventions

RVAL is a global variable. It is used to pass return values from functions. The RVAL value can be clobbered by any function. Functions that return RVAL are prefixed with r_ or _r_ or some such. Functions that return multiple values are currently prefixed with __. This may change to g_ in the future.

Develop

Do not edit the amalgamated mulle-bashfunctions*.sh files, they are generated by running cmake . in the project directory. Check out the small pamphlet Modern Bash (Zsh) Scripting by yours truly, for some background information on the techniques being used.

Install

The command to install the latest mulle-bashfunctions into /usr/local (with sudo) is:

curl -L 'https://github.com/mulle-nat/mulle-bashfunctions/archive/latest.tar.gz' \
 | tar xfz - && cd 'mulle-bashfunctions-latest' && sudo ./bin/installer /usr/local

Packages

OS	Command	Comment
macos	brew install mulle-kybernetik/mulle-bashfunctions
linux	apt install mulle-bashfunctions	See here for apt repository

Author

Nat! for Mulle kybernetiK