...
 
# Changes in shell-docs-generator
## 1.6 (2017-11-11)
* also scan variables (for now global ones only) for doc-stanzas
* in Bash, functions may be defined by syntax 'function xyz()' too
* remove the --silent parameter
* progress is now only shown with --verbose enabled
* introduced --skip parameter, that allows to skip certain stanza-types
(ie. 'var' and/or 'function' right now)
* add functions is\_verbose(), verbose() and is\_skipped()
* change markdown-layout a bit (add about section, etc.)
## 1.5 (2017-11-02)
* is\_array(), fix handling read-only arrays.
......
This diff is collapsed.
This diff is collapsed.
......@@ -2,8 +2,12 @@
. common.sh
assert_func is_declared $TEST_TRUE $TEST_EMPTY LOGNAME
assert_func is_declared "${TEST_FALSE}" "Invalid[[:blank:]]parameters"
assert_func is_declared "${TEST_FALSE}" "Invalid[[:blank:]]parameters" foo bar
assert_func is_declared "${TEST_FALSE}" "Invalid[[:blank:]]parameters" 'foo bar'
unset -v SOME_UNKNOWN_VARIABLE
assert_func is_declared $TEST_FALSE $TEST_EMPTY SOME_UNKNOWN_VARIABLE
assert_func is_declared $TEST_FALSE $TEST_EMPTY
assert_func is_declared "${TEST_FALSE}" "${TEST_EMPTY}" SOME_UNKNOWN_VARIABLE
SOME_UNKNOWN_VARIABLE=true
assert_func is_declared "${TEST_TRUE}" "${TEST_EMPTY}" SOME_UNKNOWN_VARIABLE
unset -v SOME_UNKNOWN_VARIABLE
......@@ -2,10 +2,11 @@
. common.sh
assert_func is_empty "${TEST_FAIL}" "${TEST_EMPTY}"
assert_func is_empty "${TEST_FAIL}" "${TEST_EMPTY}" '/tmp' 'bla'
assert_func is_empty "${TEST_FAIL}" "Invalid[[:blank:]]parameters"
assert_func is_empty "${TEST_FAIL}" "Invalid[[:blank:]]parameters" ''
assert_func is_empty "${TEST_FAIL}" "Invalid[[:blank:]]parameters" 'FOO BAR'
assert_func is_empty "${TEST_FAIL}" "Invalid[[:blank:]]parameters" '/tmp' 'bla'
assert_func is_empty "${TEST_FAIL}" "Variable[[:blank:]]is[[:blank:]]not[[:blank:]]declared" ''
assert_func is_empty "${TEST_FAIL}" "Variable[[:blank:]]is[[:blank:]]not[[:blank:]]declared" 'foo'
declare -g -a TESTARY=()
......
#!/bin/bash
. common.sh
assert_func is_allowed_type "${TEST_FAIL}" "Invalid[[:blank:]]parameters"
assert_func is_allowed_type "${TEST_FAIL}" "Invalid[[:blank:]]parameters" foo bar
assert_func is_allowed_type "${TEST_FAIL}" "${TEST_EMPTY}" foobar
assert_func is_allowed_type "${TEST_OK}" "${TEST_EMPTY}" function
assert_func is_allowed_type "${TEST_FAIL}" "${TEST_EMPTY}" param
assert_func is_allowed_type "${TEST_OK}" "${TEST_EMPTY}" var
assert_func is_allowed_type "${TEST_FAIL}" "${TEST_EMPTY}" param123
#!/bin/bash
. common.sh
VERBOSE=false
assert_func is_verbose $TEST_FALSE $TEST_EMPTY
VERBOSE=true
assert_func is_verbose $TEST_TRUE $TEST_EMPTY
VERBOSE=false
assert_func is_verbose $TEST_FALSE $TEST_EMPTY
#!/bin/bash
. common.sh
assert_func is_skipped "${TEST_FALSE}" "Invalid[[:blank:]]parameters"
assert_func is_skipped "${TEST_FALSE}" "Invalid[[:blank:]]parameters" foo bar
assert_func is_skipped "${TEST_FALSE}" "Invalid[[:blank:]]parameters" 'foo bar'
assert_func is_skipped "${TEST_FALSE}" "Invalid[[:blank:]]parameters" 'foobar'
assert_func is_skipped "${TEST_FALSE}" "${TEST_EMPTY}" 'var'
assert_func is_skipped "${TEST_FALSE}" "${TEST_EMPTY}" 'function'
SKIP="bla"
assert_func is_skipped "${TEST_FALSE}" "${TEST_EMPTY}" 'var'
assert_func is_skipped "${TEST_FALSE}" "${TEST_EMPTY}" 'function'
SKIP="var"
assert_func is_skipped "${TEST_OK}" "${TEST_EMPTY}" 'var'
assert_func is_skipped "${TEST_FALSE}" "${TEST_EMPTY}" 'function'
SKIP="function"
assert_func is_skipped "${TEST_FALSE}" "${TEST_EMPTY}" 'var'
assert_func is_skipped "${TEST_OK}" "${TEST_EMPTY}" 'function'
SKIP="var,function"
assert_func is_skipped "${TEST_OK}" "${TEST_EMPTY}" 'var'
assert_func is_skipped "${TEST_OK}" "${TEST_EMPTY}" 'function'
SKIP="var function"
assert_func is_skipped "${TEST_FALSE}" "${TEST_EMPTY}" 'var'
assert_func is_skipped "${TEST_FALSE}" "${TEST_EMPTY}" 'function'
unset -v SKIP
#!/bin/bash
. common.sh
VERBOSE=true
RESULT=$(verbose "bla" 2>&1)
assert_equals "${RESULT}" "^main\(\[$(((LINENO-1)))\]\):[[:blank:]]+bla$"
VERBOSE=false
unset -v RESULT
......@@ -10,10 +10,34 @@ read_file testfile_valid.sh
ORIG_DEBUG="${DEBUG}"; \
unset -v DEBUG; \
}
assert_func parse_input "${TEST_OK}" '^Parsing[[:blank:]]tags[[:blank:]]for[[:blank:]]function[[:blank:]][[:print:]]+...'
[[ ! -v "VERBOSE" ]] || { \
ORIG_VERBOSE="${VERBOSE}"; \
unset -v VERBOSE; \
}
assert_func parse_input "${TEST_OK}" "${TEST_EMPTY}"
VERBOSE=true
assert_func parse_input "${TEST_OK}" 'Parsing[[:blank:]]tags[[:blank:]]for[[:blank:]](function|var)[[:blank:]][[:print:]]+...'
unset VERBOSE
DEBUG=true
assert_func parse_input "${TEST_OK}" 'Tag[[:blank:]]found'
unset DEBUG
unset FORCE
read_file testfile_invalid.sh
assert_func parse_input "${TEST_FAIL}" 'Please check if you have defined the same function tags twice'
assert_func parse_input "${TEST_FAIL}" 'Found[[:blank:]]a[[:blank:]]variable[[:blank:]]without[[:blank:]]a[[:blank:]]doc-stanza'
FORCE=true
assert_func parse_input "${TEST_FAIL}" 'Please[[:blank:]]check[[:blank:]]if[[:blank:]]you[[:blank:]]have[[:blank:]]defined[[:blank:]]the[[:blank:]]same[[:blank:]]doc-stanzas[[:blank:]]twice'
unset FORCE
[[ ! -v "ORIG_DEBUG" ]] || { \
DEBUG="${ORIG_DEBUG}"; \
unset -v ORIG_DEBUG; \
}
[[ ! -v "ORIG_VERBOSE" ]] || { \
VERBOSE="${ORIG_VERBOSE}"; \
unset -v ORIG_VERBOSE; \
}
......@@ -5,7 +5,15 @@
assert_func formated_output "${TEST_FAIL}" "Invalid[[:blank:]]parameters"
assert_func formated_output "${TEST_FAIL}" "Invalid[[:blank:]]parameters" foo
assert_func formated_output "${TEST_FAIL}" "Invalid[[:blank:]]parameters" foo bar
assert_func formated_output "${TEST_FAIL}" "Invalid[[:blank:]]parameters" foo bar bla blub
declare -A FOOBAR=()
assert_func formated_output "${TEST_FAIL}" "Unable[[:blank:]]to[[:blank:]]perform,[[:blank:]]no[[:blank:]]@function[[:blank:]]tag[[:blank:]]is[[:blank:]]found" FOOBAR
FOOBAR+=( ['function']="bla" )
assert_func formated_output "${TEST_FAIL}" 'Unable[[:blank:]]to[[:blank:]]perform,[[:blank:]]no[[:blank:]]stanza-name[[:blank:]]found' FOOBAR
FOOBAR+=( ['name']="bla" )
assert_func formated_output "${TEST_FAIL}" 'Unable[[:blank:]]to[[:blank:]]perform,[[:blank:]]no[[:blank:]]stanza-type[[:blank:]]found' FOOBAR
FOOBAR+=( ['type']="bla" )
assert_func formated_output "${TEST_FAIL}" "Unknown[[:blank:]]stanza-type[[:blank:]]'bla'[[:blank:]]found" FOOBAR
FOOBAR+=( ['type']="var" )
assert_func formated_output "${TEST_OK}" "${TEST_EMPTY}" FOOBAR
FOOBAR+=( ['type']="function" )
assert_func formated_output "${TEST_OK}" "${TEST_EMPTY}" FOOBAR
unset -v FOOBAR
#!/bin/bash
. common.sh
assert_func is_stanza_already_handled "${TEST_FAIL}" "Invalid[[:blank:]]parameters"
assert_func is_stanza_already_handled "${TEST_FAIL}" "Invalid[[:blank:]]parameters" 'foo bar'
assert_func is_stanza_already_handled "${TEST_FAIL}" "Invalid[[:blank:]]parameters" foo bar
assert_func is_stanza_already_handled "${TEST_FAIL}" "Invalid[[:blank:]]parameters" foo 'ba r'
HANDLED_STANZAS=()
assert_func is_stanza_already_handled "${TEST_FAIL}" "${TEST_EMPTY}" 'foo'
HANDLED_STANZAS+=( 'foo' )
assert_func is_stanza_already_handled "${TEST_FAIL}" "${TEST_EMPTY}" 'bar'
assert_func is_stanza_already_handled "${TEST_OK}" "${TEST_EMPTY}" 'foo'
HANDLED_STANZAS=()
assert_func is_stanza_already_handled "${TEST_FAIL}" "${TEST_EMPTY}" 'foo'
unset -v HANDLED_STANZAS
......@@ -7,11 +7,15 @@ is_declared
is_empty
is_empty_str
is_allowed_tag
is_allowed_type
is_cmd
is_debug
is_verbose
is_skipped
ascii_to_int
int_to_ascii
debug
verbose
write
mdout
read_file
......@@ -21,3 +25,4 @@ show_help
fail
output_markdown
parse_parameters
is_stanza_already_handled
......@@ -32,28 +32,62 @@ set -u -e -o pipefail # exit-on-error, error on undeclared variables.
# remember, on the shell TRUE=0, FALSE=1.
#
# @var CSL_EXIT_WARN
readonly CSL_EXIT_OK=0
# @varniable CSL_EXIT_WARNING
readonly CSL_EXIT_WARNING=1
# @variable CSL_EXIT_CRITICAL
readonly CSL_EXIT_CRITICAL=2
# @func CSL_EXIT_UNKNOWN
readonly CSL_EXIT_UNKNOWN=3
# @var CSL_TRUE
readonly CSL_TRUE=true
# @var CSL_FALSE
readonly CSL_FALSE=false
# reset variables, just in case...
# @var CSL_EXIT_NO_DATA_IS_CRITICAL=0
declare -g CSL_EXIT_NO_DATA_IS_CRITICAL=0
declare -g CSL_RESULT_CODE= CSL_RESULT_TEXT= CSL_RESULT_PERFDATA=
declare -g CSL_WARNING_LIMIT= CSL_CRITICAL_LIMIT=
declare -g CSL_DEBUG= CSL_VERBOSE=
declare -g CSL_DEFAULT_HELP_TEXT= CSL_HELP_TEXT=
declare -g CSL_GETOPT_SHORT= CSL_GETOPT_LONG=
# @var CSL_RESULT_CODE
declare -g CSL_RESULT_CODE=
# @var CSL_RESULT_TEXT
declare -g CSL_RESULT_TEXT=
# @var CSL_RESULT_PERFDATA
declare -g CSL_RESULT_PERFDATA=
# @var CSL_WARNING_LIMIT
declare -g CSL_WARNING_LIMIT=
# @var CSL_CRITICAL_LIMIT
declare -g CSL_CRITICAL_LIMIT=
# @var CSL_DEBUG
declare -g CSL_DEBUG=
# @var CSL_VERBOSE
declare -g CSL_VERBOSE=
# @var CSL_DEFAULT_HELP_TEXT
declare -g CSL_DEFAULT_HELP_TEXT=
# @var CSL_HELP_TEXT
declare -g CSL_HELP_TEXT=
# @var CSL_GETOPT_SHORT
declare -g CSL_GETOPT_SHORT=
# @var CSL_GETOPT_LONG
declare -g CSL_GETOPT_LONG=
# @var CSL_DEFAULT_GETOPT_SHORT
readonly CSL_DEFAULT_GETOPT_SHORT='w:c:dhv'
# @var CSL_DEFAULT_GETOPT_LONG
readonly CSL_DEFAULT_GETOPT_LONG='warning:,critical:,debug,verbose,help'
# @var CSL_DEFAULT_PREREQ
readonly -a CSL_DEFAULT_PREREQ=( 'getopt' 'cat' 'bc' 'mktemp' )
# @var CSL_USER_PREREQ
declare -a CSL_USER_PREREQ=()
# @var CSL_USER_PARAMS
declare -A CSL_USER_PARAMS=()
# @var CSL_USER_GETOPT_PARAMS
declare -A CSL_USER_GETOPT_PARAMS=()
#
......@@ -62,6 +96,7 @@ declare -A CSL_USER_GETOPT_PARAMS=()
# could then take care of it and removes all the temp-directories
# on script-exit.
#
# @var CSL_TEMP_DIRS
declare -a CSL_TEMP_DIRS=()
# the '&& true' is required as read exits non-zero on reaching end-of-file
......
......@@ -32,28 +32,62 @@ set -u -e -o pipefail # exit-on-error, error on undeclared variables.
# remember, on the shell TRUE=0, FALSE=1.
#
# @var CSL_EXIT_OK
readonly CSL_EXIT_OK=0
# @var CSL_EXIT_WARNING
readonly CSL_EXIT_WARNING=1
# @var CSL_EXIT_CRITICAL
readonly CSL_EXIT_CRITICAL=2
# @var CSL_EXIT_UNKNOWN
readonly CSL_EXIT_UNKNOWN=3
# @var CSL_TRUE
readonly CSL_TRUE=true
# @var CSL_FALSE
readonly CSL_FALSE=false
# reset variables, just in case...
# @var CSL_EXIT_NO_DATA_IS_CRITICAL
declare -g CSL_EXIT_NO_DATA_IS_CRITICAL=0
declare -g CSL_RESULT_CODE= CSL_RESULT_TEXT= CSL_RESULT_PERFDATA=
declare -g CSL_WARNING_LIMIT= CSL_CRITICAL_LIMIT=
declare -g CSL_DEBUG= CSL_VERBOSE=
declare -g CSL_DEFAULT_HELP_TEXT= CSL_HELP_TEXT=
declare -g CSL_GETOPT_SHORT= CSL_GETOPT_LONG=
# @var CSL_RESULT_CODE
declare -g CSL_RESULT_CODE=
# @var CSL_RESULT_TEXT
declare -g CSL_RESULT_TEXT=
# @var CSL_RESULT_PERFDATA
declare -g CSL_RESULT_PERFDATA=
# @var CSL_WARNING_LIMIT
declare -g CSL_WARNING_LIMIT=
# @var CSL_CRITICAL_LIMIT
declare -g CSL_CRITICAL_LIMIT=
# @var CSL_DEBUG
declare -g CSL_DEBUG=
# @var CSL_VERBOSE
declare -g CSL_VERBOSE=
# @var CSL_DEFAULT_HELP_TEXT
declare -g CSL_DEFAULT_HELP_TEXT=
# @var CSL_HELP_TEXT
declare -g CSL_HELP_TEXT=
# @var CSL_GETOPT_SHORT
declare -g CSL_GETOPT_SHORT=
# @var CSL_GETOPT_LONG
declare -g CSL_GETOPT_LONG=
# @var CSL_DEFAULT_GETOPT_SHORT
readonly CSL_DEFAULT_GETOPT_SHORT='w:c:dhv'
# @var CSL_DEFAULT_GETOPT_LONG
readonly CSL_DEFAULT_GETOPT_LONG='warning:,critical:,debug,verbose,help'
# @var CSL_DEFAULT_PREREQ
readonly -a CSL_DEFAULT_PREREQ=( 'getopt' 'cat' 'bc' 'mktemp' )
# @var CSL_USER_PREREQ
declare -a CSL_USER_PREREQ=()
# @var CSL_USER_PARAMS
declare -A CSL_USER_PARAMS=()
# @var CSL_USER_GETOPT_PARAMS
declare -A CSL_USER_GETOPT_PARAMS=()
#
......@@ -62,6 +96,7 @@ declare -A CSL_USER_GETOPT_PARAMS=()
# could then take care of it and removes all the temp-directories
# on script-exit.
#
# @var CSL_TEMP_DIRS
declare -a CSL_TEMP_DIRS=()
# the '&& true' is required as read exits non-zero on reaching end-of-file
......@@ -1340,7 +1375,7 @@ readonly -f csl_get_long_params
# there is a hard-coded limit for max. 10 temp-directories.
# @output temp-directory
# @return int 0 on success, 1 on failure
create_tmpdir ()
function create_tmpdir ()
{
local CSL_TMPDIR= RETVAL=
......@@ -1373,7 +1408,7 @@ create_tmpdir ()
readonly -f create_tmpdir
# @function setup_cleanup_trap()
# registers a signal-trap for certain signals like \
# @brief registers a signal-trap for certain signals like \
# EXIT and INT, to call the cleanup() function on program-termination \
# (irrespectivly of success or failure). \
# \
......