diff --git a/libexec/bash-utils-core b/libexec/bash-utils-core index bd89f01..49acc37 100644 --- a/libexec/bash-utils-core +++ b/libexec/bash-utils-core @@ -687,7 +687,7 @@ readonly BASH_UTILS_ROOT="${libexecdir}" readonly BASH_UTILS_MODULES="${libexecdir}/bash-utils-modules" readonly BASH_UTILS_NAME='Bash-Utils' readonly BASH_UTILS_KEY='bash-utils' -readonly BASH_UTILS_VERSION='0.1.0' +readonly BASH_UTILS_VERSION='0.1.1' readonly BASH_UTILS_COPYRIGHT='Copyright (c) 2015 Pierre Cassat & contributors' readonly BASH_UTILS_LICENSE="Apache Software Foundation license 2.0 This program is free software, distributed on an \"AS IS\" BASIS, diff --git a/man/MANPAGE.1.md b/man/MANPAGE.1.md index 0cf2c3b..7198c7e 100644 --- a/man/MANPAGE.1.md +++ b/man/MANPAGE.1.md @@ -3,7 +3,7 @@ Man-name: bash-utils Author: Pierre Cassat Section: 1 Date: 2016-04-27 -Version: 0.1.0 +Version: 0.1.1 ## NAME diff --git a/man/MANPAGE.7.md b/man/MANPAGE.7.md index cf64266..3cbc24e 100644 --- a/man/MANPAGE.7.md +++ b/man/MANPAGE.7.md @@ -3,7 +3,7 @@ Man-name: bash-utils Author: Pierre Cassat Section: 7 Date: 2016-04-27 -Version: 0.1.0 +Version: 0.1.1 ## USAGE diff --git a/man/bash-utils.1.man b/man/bash-utils.1.man index 4892791..27db457 100644 --- a/man/bash-utils.1.man +++ b/man/bash-utils.1.man @@ -1,151 +1,3 @@ -.\" man: Bash-Utils Manual -.\" man-name: bash-utils -.\" author: Pierre Cassat -.\" section: 1 -.\" date: 2016-04-27 -.\" version: 0.1.0 -.TH "bash-utils" "1" "2016-04-27" "Version 0.1.0" "Bash-Utils Manual" -.SH NAME +.TH "" "3" "" "" "" .PP -Bash-Utils - A short \fIbash\fP library for better scripting. -.SH SYNOPSIS -.PP -Usage of the library as a script's interpreter: -.RS - -.EX -#!/usr/bin/env bash-utils -.EE -.RE -.PP -Usage of the library in a script: -.RS - -.EX -source bash-utils -- || { echo "> bash-utils not found!" >&2; exit 1; }; -.EE -.RE -.PP -Usage of the library as a command: -.PP -\fBbash-utils\fP [\fB-fhqvVx\fP] - [\fB--debug\fP|\fB--dry-run\fP|\fB--force\fP|\fB--help\fP|\fB--quiet\fP|\fB--verbose\fP|\fB--version\fP] - [\fB-e\fP|\fB--exec\fP[=\fIarg\fP]] -.SH DESCRIPTION -.PP -The \fIBash-Utils\fP command is a small library of utilities to quickly write robust and complete \fIBash\fP scripts. -It proposes a set of useful functions and environment variables in an enhanced environment with some system -options enabled by default, to let you build a script with user options and arguments, an automatic generation -of some informational output about the script's usage, a special handling of errors, stack trace and debugging, -and some more features (see bash-utils(7) for a full documentation). -.PP -It also embeds a various set of \fImodules\fP constructed as stand-alone bash-utils scripts you can use "as-is", -calling them directly, or in a script using the library with the help of the `\fSrun()\fP` or `\fSuse()\fP` functions. -.SH OPTIONS -.SS Scripts using the library -.PP -The following options are supported by default for any script using the library: -.TP -\fI--dry-run\fP -Process a dry-run. -.TP -\fI-f\fP, \fI--force\fP -Force some commands to not prompt confirmation. -.TP -\fI-h\fP, \fI--help\fP -See the help information about the script, a module or the library itself. -.TP -\fI-q\fP, \fI--quiet\fP -Decrease script's verbosity. -.TP -\fI-v\fP, \fI--verbose\fP -Increase script's verbosity. -.TP -\fI-V\fP, \fI--version\fP -See the script, module or library version and copyright information ; -use option `\fS--quiet\fP` to get version number only. -.TP -\fI-x\fP, \fI--debug\fP -See some debugging information. -.PP -Please note that these options are available but not necessarily used in scripts or modules. -.SS Using the library as a command -.PP -The following additional options are available when you call the library itself: -.TP -\fI-e\fP, \fI--exec\fP [\fB=arg\fP] -Execute the argument in the library's environment ; as the argument is optional, the equal sign -is REQUIRED ; without argument, any piped content will be evaluated: -.br -bash-utils --exec='onoff_bit true' -.br -echo 'onoff_bit true' | bash-utils --exec -.br -.PP -The following additional arguments are available when you call the library itself: -.TP -\fIabout\fP -alias of '--version' -.TP -\fIabout module-name\fP -alias of 'module-name --version' -.TP -\fIhelp\fP -alias of '--help' -.TP -\fIhelp module-name\fP -get the help about a module -.TP -\fImodules\fP -get the list of available modules -.TP -\fIusage\fP -get the library synopsis -.TP -\fIusage module-name\fP -get a module synopsis -.TP -\fIversion\fP -alias of '--version --quiet' -.TP -\fIversion module-name\fP -alias of 'module-name --version --quiet' -.SH EXAMPLES -.PP -You can use the \fImodel\fP module to get a full example of a script using the library. -.RS - -.EX -bash-utils model bash-utils -.EE -.RE -.PP -A starter template is available in bash-utils(7). -.SH LICENSE -.PP -Copyright (c) 2015, Pierre Cassat & contributors -.PP -Licensed under the Apache Software Foundation license, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -.PP -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -.PP -For the full copyright and license information, please view the LICENSE -file that was distributed with this source code or see -. -.SH BUGS -.PP -To transmit bugs, see . -.SH AUTHOR -.PP -\fBBash-Utils\fP is created and maintained by Pierre Cassat (picas - ) -& contributors. -.SH SEE ALSO -.PP -For documentation, sources & updates, see . -.PP -bash(1), bash-utils(7) +/Users/piwi/www/projects/piwi/bash-utilsman/MANPAGE.1.md \ No newline at end of file diff --git a/man/bash-utils.7.man b/man/bash-utils.7.man index 5ae54f9..f08bbf3 100644 --- a/man/bash-utils.7.man +++ b/man/bash-utils.7.man @@ -1,475 +1,3 @@ -.\" man: Bash-Utils Documentation -.\" man-name: bash-utils -.\" author: Pierre Cassat -.\" section: 7 -.\" date: 2016-04-27 -.\" version: 0.1.0 -.TH "bash-utils" "7" "2016-04-27" "Version 0.1.0" "Bash-Utils Documentation" -.SH USAGE +.TH "" "3" "" "" "" .PP -To create a script using the library, you can call the \fImodel\fP argument of the library itself, which -will create a starter template script: -.RS - -.EX -bash-utils model bash-utils /path/to/your/script.sh -.EE -.RE -.PP -Actually, the only requirement to use the library is to source it in your script: -.RS - -.EX -source bash-utils -- -.EE -.RE -.PP -The final double-dashes `\fS--\fP` are required to avoid parameters expansion when including the library. -.PP -You can also use it as your script's \fIinterpreter\fP defining it in your -\fIhash bang\fP (\fIshebang\fP) line (this is the case -of the model): -.RS - -.EX -#!/usr/bin/env bash-utils -.br - -.br -# write your script here -.EE -.RE -.PP -You can even enable some library's flags by adding options to the \fIshebang\fP: -.RS - -.EX -#!/usr/bin/env bash-utils -v -.EE -.RE -.PP -You must separate them when using multiple flags: -.RS - -.EX -#!/usr/bin/env bash-utils -v -x -.EE -.RE -.SS Notes about \fIbash\fP scripting and usage -.TP use-your-binaries-easily -\fBUse your binaries easily\fP -.RS -.PP -To enable "per-user" binaries (let the system look in any `\fS$HOME/bin/\fP` directory when searching scripts), -be sure to add that directory to the `\fS$PATH\fP` environment variable (in your `\fS$HOME/.bashrc\fP` for instance): -.RS - -.EX -# user binaries path -.br -[ -d "${HOME}/bin" ] && export PATH="${PATH}:${HOME}/bin"; -.EE -.RE -.PP -You can name your scripts following your preferences and place it where you want as long as you can access it easily. -The file extension has no incidence upon the script's type (\fIbash\fP in our case) as the interpreter is designed by the -\fBshebang\fP directive ; you could name your script with an -`\fS.sh\fP`, a `\fS.bash\fP` and even a `\fS.py\fP` extension (which would have no real sense here) or let it without extension -at all with no difference. -.RE -.TP scripts-terminal-usage -\fBScripts terminal usage\fP -.RS -.PP -A command-line program (such as a shell script) often accepts to set some options and arguments calling it in a terminal -or another script. A global synopsis of a command line call can be: -.RS - -.EX -path/to/script [-o | --options (=argument)] [--] [ ...] -.br -# e.g.: -.br -program-to-run -o --option='my value' --option-2 'my value' argument1 argument2 -.EE -.RE -.PP -The rules are the followings: -.RS -.IP \(bu -\fIoptions\fP are various settings passed to the script when calling it ; each option is prefixed by one or more dash `\fS-\fP` -and can have an argument ; by convention, a short option is composed by one single letter prefixed by one dash, e.g. `\fS-o\fP`, -and a long option is composed by a word prefixed by two dashes, e.g. `\fS--option\fP` ; when an option accepts an argument, -it must be separated from the option name by an equal sign, e.g. `\fS--option=argument\fP` and `\fS-o=argument\fP` ; e.g. -`\fS./script -o --option-with-no-arg --option-with-arg=argument_value\fP` -.IP \(bu -a double dashes `\fS--\fP` can be used to identify the end of options ; the rest of the call will be considered as arguments -only -.IP \(bu -an \fIargument\fP is a setting passed to the script when calling it ; the arguments are not the same as the options as -they are not named but identified by their positions ; e.g. `\fS./script --option argument1 argument2\fP` -.RE -.RE -.TP commands-vs-builtins -\fBCommands vs. builtins\fP -.RS -.PP -\fIBash\fP proposes a large set of \fBbuiltins\fP "commands", which must be differentiated from \fIexternal commands\fP. The bash -builtins are always available in any bash environment while external commands must be installed on the system to work. -If you have a doubt about a command, you can verify running `\fStype \fP`, which will respond `\fS... is a shell builtin\fP` -for builtins. If you have the choice, you should always prefer a builtin rather than an external command, unless you -are absolutely sure it is present on all UNIX installations. -.PP -To get the help about an external command, you can read its \fImanpage\fP: -.RS - -.EX -man -.EE -.RE -.PP -To get the help about a builtin, you may use `\fShelp\fP`: -.RS - -.EX -help -.EE -.RE -.RS -.RS -.SS Starter template -.PP -Below is a very simple starter template of a script using the library: -.RS - -.EX -#!/usr/bin/env bash-utils -.br -# reset bash options here if needed -.br -# set +E -.br - -.br -# write your scripts logic here -.br -# ... -.br - -.br -# a script should always return a status -.br -exit 0 -.EE -.RE -.PP -You should use the \fImodel\fP module for a more complex template: -.RS - -.EX -bash-utils model bash-utils -.EE -.RE -.SS Customize your script -.PP -To build your own command, you may first override informational variables: -.RS - -.EX -CMD_NAME=... -.br -CMD_VERSION=... -.br -CMD_COPYRIGHT=... -.br -CMD_LICENSE=... -.br -CMD_SOURCES=... -.br -CMD_DESCRIPTION=... -.br -CMD_SYNOPSIS=... -.br -CMD_HELP=... -.br -CMD_OPTS_SHORT=(...) -.br -CMD_OPTS_LONG=(...) -.br -CMD_ARGS=(...) -.br -#CMD_SYNOPSIS=... -.br -CMD_USAGE=... -.EE -.RE -.PP -Then you can customize script's options (see below) to fit your needs and write your script's logic in the last -part of the model. -.SH DOCUMENTATION -.SS Library's methods -.PP -The library embeds a short set of methods to facilitate your scripts: -.RS -.IP \(bu -the `\fSdie()\fP` method will exit with an error message and a back trace, all to STDERR -.IP \(bu -the `\fSerror()\fP` method will exit with an error message to STDERR (user friendly) -.IP \(bu -the `\fSwarning()\fP` method will write an error message to STDERR (without exiting the script) -.IP \(bu -the `\fStry()\fP` method will emulate a \fItry/catch\fP process by calling a sub-command catching its result -.RE -.PP -Errors are handled by the `\fSdie()\fP` method (using the \fItrap\fP built-in command - see the \fITechnical points\fP section below). -.PP -A special \fIoptions\fP and \fIarguments\fP handling is designed to rebuild the input command and follow special treatments -for default options and arguments. To use this, add in your script: -.RS - -.EX -rearrange_options "$@" -.br -[ -n "$CMD_REQ" ] && eval set -- "$CMD_REQ"; -.br -common_options "$@" -.EE -.RE -.PP -You can \fBoverride any method\fP by re-defining it after having sourced the library: -.RS - -.EX -source bash-utils -- || { echo "> ${BASH_SOURCE[0]}:${LINENO}: bash-utils not found!" >&2; exit 1; }; -.br - -.br -error() { -.br - # your custom error handler -.br -} -.EE -.RE -.PP -The best practice is to create user methods instead of overload native ones and call them: -.RS - -.EX -source bash-utils -- || { echo "> ${BASH_SOURCE[0]}:${LINENO}: bash-utils not found!" >&2; exit 1; }; -.br - -.br -user_error() { -.br - # your custom error handler -.br -} -.br - -.br -[ -f filename ] || user_error 'file not found'; -.EE -.RE -.SS Script's options -.PP -Default options handled by the library are: -.RS -.IP \(bu -\fB-q\fP | \fB--quiet\fP: enables the `\fS$QUIET\fP` environment variables ; this should decrease script's output (only errors or -required output should be returned) ; this option disables the `\fS$VERBOSE\fP` environment variable -.IP \(bu -\fB-v\fP | \fB--verbose\fP: enables the `\fS$VERBOSE\fP` environment variable ; this should increase script's verbosity (inform -user about what is happening) ; this option disables the `\fS$QUIET\fP` environment variable -.IP \(bu -\fB-f\fP | \fB--force\fP: enables the `\fS$FORCE\fP` environment variable ; this should let the user to choose all default behaviors -in case a choice is required (no prompt running the script) -.IP \(bu -\fB-x\fP | \fB--debug\fP: enables the `\fS$DEBUG\fP` environment variable ; this should drastically increase script's verbosity -(verbosity should be one level more than in `\fS$VERBOSE\fP` mode) -.IP \(bu -\fB--dry-run\fP: enables the `\fS$DRY_RUN\fP` environment variable ; this should not do sensible stuff but inform user about -what should be done -.RE -.PP -The library also handles those informational options: -.RS -.IP \(bu -\fB-V\fP | \fB--version\fP to get the name and version number of the script -.IP \(bu -\fB-h\fP | \fB--help\fP to get the full help information of script's usage -.RE -.PP -The output of the informational arguments listed above are constructed using the `\fSCMD_...\fP` environment -variables you may define for each script (see the \fICustomize your script\fP section above). -.PP -These options are handled by the \fIgetopt\fP program. You can add your own options by overriding the following variables: -.RS - -.EX -CMD_OPTS_SHORT=(f h q v V x) -.br -CMD_OPTS_LONG=(debug dry-run force help quiet verbose version) -.EE -.RE -.PP -The `\fSCMD_OPTS_...\fP` definitions are used to build auto-completion. -.PP -By default, the `\fScommon_options()\fP` method will throw en error if an unknown option is met. You can avoid this behavior -by prefixing the `\fSCMD_OPTS_SHORT\fP` by a colon `\fS:\fP`: -.RS - -.EX -CMD_OPTS_SHORT=(':' f h q v V x) -.EE -.RE -.PP -For each option added, you MUST define your own treatment for it in a parsing loop: -.RS - -.EX -while [ $# -gt 0 ]; do -.br - case "$1" in -.br - # do not throw error for common options -.br - -f | -h | -q | -v | -V | -x | --force | --help | --quiet | --verbose | --version | --debug | --dry-run ) true;; -.br - # user option -.br - -o | --my-option ) -.br - OPTARG="$(echo "$2" | cut -d'=' -f2)" -.br - MYVAR="${OPTARG:-default}" -.br - shift -.br - ;; -.br - esac -.br - shift -.br -done -.EE -.RE -.PP -In your script, you can use a flag like: -.RS - -.EX -$FLAG && ...; # do something when FLAG is ENABLED -.br -$FLAG || ...; # do something when FLAG is DISABLED -.EE -.RE -.PP -Due to known limitations of the \fIgetopt\fP program, you should always use an equal sign between -an option (short or long) and its argument: `\fS-o=arg\fP` or `\fS--option=arg\fP`, even if that argument is required. -.SS Script's arguments -.PP -Arguments can be handled in the same logic as options: -.RS -.IP \(bu -.PP -you may first define them in the `\fSCMD_ARGS\fP` array, with a trailing double point if it requires a second argument, -and two double points if it can accept a second argument: -.RS - -.EX -CMD_ARGS=('argument:' 'arg2::' arg3) -.EE -.RE - -.IP \(bu - -then, once you have looped (and shifted) over all options, you can loop over arguments: -.br -case "$1" in -.br - ... -.br -esac -.br - -.RE -.PP -The `\fSCMD_ARGS\fP` definition is used to build auto-completion. -.SS Technical points -.PP -The library enables the following \fIBash\fP options by default: -.RS -.IP \(bu -`\fSposix\fP`: match the POSIX 1003.2 standard -.IP \(bu -`\fSexpand_aliases\fP`: allow to use aliases in scripts -.IP \(bu -`\fSallexport\fP`: export all modified variables -.IP \(bu -`\fSerrexit\fP`: exit if a command has a non-zero status -.IP \(bu -`\fSerrtrace\fP`: trap on ERR are inherited by shell functions -.IP \(bu -`\fSpipefail\fP`: do not mask pipeline's errors -.IP \(bu -`\fSnounset\fP`: throw error on unset variable usage -.IP \(bu -`\fSfunctrace\fP`: trap on DEBUG and RETURN are inherited by shell functions -.RE -.PP -Run `\fShelp set\fP` for a full list of bash \fIset\fP built-in available options. -.PP -Moreover, the library \fItrap\fP errors and early exits signals to the `\fSdie()\fP` function to display an error string and -stack trace in each case. It also defines a `\fSshutdown_handler()\fP` method trapped at the end of the process; you can -redefine this function with your own logic to make a cleanup at the end of each run. -.PP -To make robust scripts, here are some reminders: -.RS -.IP \(bu -to use a variable eventually unset: `\fSecho ${VARIABLE:-default}\fP` and `\fSecho ${VARIABLE[*]:-}\fP` -.IP \(bu -to make a silent sub-command call: `\fSval=$(sub-command 2>/dev/null)\fP` -.RE -.SH FILES -.TP -\fIbin/bash-utils\fP | \fBlibexec/bash-utils\fP -This is the "entry point" of \fIBash-Utils\fP ; it should be available in one of the `\fS$PATH\fP` paths for all users ; -it acts like a loader of the library and a script's interpreter you can use as a script's \fIshebang\fP. -.TP -\fBlibexec/bash-utils-core\fP -This is the core of \fIBash-Utils\fP ; it mostly defines required functions and environment variables for the library -to work by itself and to handle its modules ; it uses almost only bash \fIbuiltins\fP. -.TP -\fBlibexec/bash-utils-lib\fP -This is the library of functions ; it embeds various useful functions and variables commonly used in \fIbash\fP scripts. -.TP -\fBlibexec/bash-utils-cmd\fP -This is the script that handles default parameters and actions of \fIBash-Utils\fP when you call it directly. -.TP -\fBlibexec/bash-utils-modules/\fP -This is the directory where modules are stored ; each module is a single script in that directory ; a module is -identified by its filename. -.TP -\fBetc/bash_completion.d/bash-utils-completion\fP -This is the script that handles terminal completion for the library (core and modules). -.SH SEE ALSO -.PP -Online \fIbash\fP scripting guides and tools: -.RS -.IP \(bu -the \fIBash Guide for Beginners\fP: (recommended) -.IP \(bu -the \fIAdvanced Bash-Scripting Guide\fP: (recommended) -.IP \(bu -the \fIBash Reference Manual\fP: -.IP \(bu -the \fIGNU Coding Standards\fP: -.IP \(bu -\fIBATS\fP, a test suite for Bash scripts: -.IP \(bu -\fIShellCheck\fP, a Bash validator: -.RE -.PP -bash(1), bash-utils(1), getopt(1) +/Users/piwi/www/projects/piwi/bash-utilsman/MANPAGE.7.md \ No newline at end of file