argsparse-completion.sh:

* some line wrapping
* return on script loading error
* document in progress

Author: Damien Nadé

argsparse-completion.sh

@@ -3,7 +3,7 @@
 #
 ## @file
 ## @author Damien Nadé <bash-argsparse@livna.org>
-## @brief ...
+## @brief Bash completion for scripts using argsparse library.
 ## @copyright WTFPLv2
 ## @version 1.7
 #
@@ -26,7 +26,74 @@
 #
 #########
 #
+## @details
+## @par URL
+## https://github.com/Anvil/bash-argsparse @n
+#
+## @par Purpose
+#
+## To automatically enable, for bash-completion users, completion for
+## scripts using the argsparse library.
+
+## @par Usage
+#
+## In you ~/.bashrc, add the following lines to enable completion for
+## all your argsparse-written scripts:
+##
+## @code
+##     . argsparse-completion.sh
+##     complete -F _argsparse_complete [ your scripts names ... ]
+## @endcode
+#
+## @par Required configuration
+#
+## argsparse-completion relies on a few shell settings:
+
+## @li "expand_aliases" @n
+##   This the expansion of an alias. Aliases are enabled by default in
+## interactive mode.
+##
+## @code
+##   shopt expand_aliases
+## @endcode
+##
+
+##
+## @li "sourcepath" shell option must be enabled. This should be
+##   enabled by default, but you can enforce it by running:
+##
+## @code
+##   shopt -s sourcepath
+## @endcode
+##
+## If correctly enabled, the following command below should return
+## this output.
+##
+## @code
+##   $ shopt sourcepath
+##   sourcepath      on
+## @endcode
+##
+## @par Limitations
+## @li The completed script will be sourced, up to the
+##   argsparse_parse_options function() call. This means the script
+##   should not performed any side effect (like file system alteration
+##   - file creation, ), and should avoid time-consuming tasks up to
+##   this point
+##
+##
+#
+## @defgroup ArgsparseCompletion Bash Completion-related functions.
 
+## @fn __argsparse_compgen()
+## @private
+## @brief A compgen wrapper.
+## @details This function will just call compgen with given argument,
+## safely adding $cur in the command line. Also if compgen_prefix is
+## set, a -P option will be provided to compgen.
+## @param param... any set of compgen options
+## @return
+## @ingroup ArgsparseCompletion
 __argsparse_compgen() {
 	if [[ -v compgen_prefix ]]
 	then
@@ -35,14 +102,17 @@ __argsparse_compgen() {
 	compgen "$@" -- "$cur"
 }
 
+## @fn __argsparse_complete_value()
+## @brief complete a value
+## @ingroup ArgsparseCompletion
 __argsparse_complete_value() {
 	local option array option_type
 	local -a values
 	option=$(__argsparse_complete_get_long "$prev" "${longs[@]}") && \
 		argsparse_has_option_property "$long" value || return 1
 	if array=$(__argsparse_values_array_identifier "$option")
 	then
-		values=( ${!array} )
+		values=( "${!array}" )
 		__argsparse_compgen -W "${values[*]}"
 	elif option_type=$(argsparse_has_option_property "$option" type)
 	then
@@ -70,6 +140,11 @@ __argsparse_complete_value() {
 	fi
 }
 
+## @fn __argsparse_complete_get_long()
+## @brief
+## @details
+## @param word
+## @ingroup ArgsparseCompletion
 __argsparse_complete_get_long() {
 	[[ $# -ge 1 ]] || return 1
 	local word=$1
@@ -90,12 +165,16 @@ __argsparse_complete_get_long() {
 	argsparse_has_option_property "$long" value
 }
 
+## @fn __argsparse_complete()
+## @brief
+## @details
+## @ingroup ArgsparseCompletion
 __argsparse_complete() {
 	local script=${words[0]}
 	(
 		set +o posix
 		ARGSPARSE_COMPLETION_MODE=1
-		. "$script" 2>/dev/null
+		. "$script" 2>/dev/null || return
 		longs=( "${!__argsparse_options_descriptions[@]}" )
 		longs=( "${longs[@]/#/--}" )
 		option=${prev#--}
@@ -112,13 +191,14 @@ __argsparse_complete() {
 					# Complete the --foo=something pattern as if
 					# prev=--foo and cur=something
 					# Complete -fsomething as if prev=-f and cur=something
-					if [[ "$cur" =~ ^((--[^=]+)=)(.*)$ || "$cur" =~ ^((-[^-]))(.*)$ ]]
+					if [[ "$cur" =~ ^((--[^=]+)=)(.*)$ ||
+						"$cur" =~ ^((-[^-]))(.*)$ ]]
 					then
 						compgen_prefix=${BASH_REMATCH[1]}
 						option=${BASH_REMATCH[2]}
 						cur=${BASH_REMATCH[3]}
-						long=$(
-							__argsparse_complete_get_long "$option" "${longs[@]}") && \
+						long=$(__argsparse_complete_get_long \
+								"$option" "${longs[@]}") && \
 							__argsparse_complete_value "$long"
 					fi
 					;;
@@ -138,6 +218,9 @@ __argsparse_complete() {
 	)
 }
 
+## @fn _argsparse_complete()
+## @brief
+## @details
 _argsparse_complete() {
 	local cur prev words cword split
 	_init_completion -s || return