...
 
Commits (10)
*.swp
FUNCREF.md
tests/testout.md
.pc
# Changes in shell-docs-generator
## 1.5 (2017-11-02)
* is\_array(), fix handling read-only arrays.
* is\_empty() renamed to is\_empty\_str().
* added a new is\_empty().
* added is\_declared().
* use a table within the return-code section.
* add ascii\_to\_int().
* add int\_to\_ascii().
* automatically count sections within a stanza instead of hard-coded one's.
* now prints the generated text default to STDOUT (like if '-' output parameter
is given).
* add new tag 'deprecated'.
* output TOC-tag (and a note that this is the job of the markdown-renderer to fulfill.
## 1.4.1 (2017-10-31)
* make the created-by line contain the english-language, UTC time.
......
# shell-docs-generator
| Tag | Value |
| - | - |
| Author | Andreas Unterkircher |
| Version | 1.5 |
| License | AGPLv3 |
<!-- if a table-of-contents gets actually rendered, depends on your markdown-viewer -->
[TOC]
## 1. Function `sanitize`
This function tries to sanitize the provided string and removes all characters
from the string that are not matching the provided pattern mask.
### 1a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | text |
### 1b. Output
`string`
### 1b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 2. Function `parse_parameters`
This function parse the given command-line parameters and arguments by using
GNU getopt.
### 2a. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 3. Function `in_array`
searches the array $1 for the value given in $2. $2 may even contain a
regular expression pattern. On success, it returns 0. Otherwise 1 is returned.
### 3a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | array-name |
| *$2* | string | needle |
### 3b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 4. Function `in_array_re`
This function works similar as in_array(), but uses the patterns that have
been stored in the array $1 against the fixed string provided with $2. On
success, it returns 0. Otherwise 1 is returned.
### 4a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | array-name |
| *$2* | string | needle |
### 4b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 5. Function `is_array`
This function tests if the provided array $1 is either an indexed- or an
associative-array. If so, the function returns 0, otherwise 1.
### 5a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | array-name |
### 5b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 6. Function `is_empty`
returns 0, if the provided string or array variable have a value of length
of zero. Otherwise it returns 1.
### 6a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string|array | $string |
### 6b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
| Value | 0 on success, 1 on failure |
## 7. Function `is_empty_str`
This function is actually just a wrapper around the already simple
zero-length-string-test 'test -z'. But this wrapper helps to make the rest of
the code a bit easier to read. If the string is empty, it returns 0. Otherwise
it returns 1.
### 7a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | var-name |
### 7b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 8. Function `is_declared`
returns 0 if the provided variable has been declared (that does not mean,
that the variable actually has a value!), otherwise it returns 1.
### 8a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | $var |
### 8b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
| Value | 0 on success, 1 on failure |
## 9. Function `is_allowed_tag`
This function tests the provided tag-name for any match in the ALLOWED_TAGS
array. On success, it returns 0. Otherwise it will return 1.
### 9a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | tag |
### 9b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 10. Function `is_cmd`
returns 0, if the provided external command exists. Otherwise it returns 1.
### 10a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | $command |
### 10b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
| Value | 0 on success, 1 on failure |
## 11. Function `is_debug`
This function returns 0, if debugging has been enabled. Otherwise it will
return 1.
### 11a. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 12. Function `debug`
This function issues debugging-output, but only if debugging has actually been
enabled. Otherwise, output is suppressed. Note: Debug-output is sent to STDERR!
### 12a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | text |
### 12b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 13. Function `write`
Adds the provided text to MARKDOWN_RESULT array.
### 13a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | text |
### 13b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 14. Function `mdout`
Writes the provided text to the OUTPUT file.
### 14a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | text |
### 14b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 15. Function `read_file`
This function reads the provided file into the indexed-array CODE_SRC. On
success it returns 0, otherwise it will return non-zero.
### 15a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | file |
### 15b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 16. Function `parse_input`
This function is the actual workhorse of the shell-docs-generator. It parses
the lines stored in the CODE_SRC array and extracts all documentation tags. On
success, this function returns 0. Otherwise it returns non-zero.
### 16a. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 17. Function `ascii_to_int`
Converts a single ASCII character to its decimal representation.
### 17a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | $ascii |
### 17b. Output
`int`
### 17b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
### 17c. Example
```
echo $(ascii_to_int A) --> 65
```
## 18. Function `int_to_ascii`
Converts a decimal value to its corresponding ASCII character.
### 18a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | int | $i |
### 18b. Output
`string`
### 18b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
### 18c. Example
```
echo $(int_to_ascii 65) --> A
```
## 19. Function `formated_output`
This function performs the actual output of the generated documentation into
the $OUTPUT file. On success it returns 0, otherwise it returns non-zero.
### 19a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | array | array-name |
### 19b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 20. Function `show_help`
Output help text
### 20a. Output
`string`
### 20a. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 21. Function `fail`
prints the fail-text as well as the function and code-line from which it
was called.
### 21a. Parameters
| ID | Type | Description |
| - | - | - |
| *$1* | string | $fail_text |
### 21b. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
## 22. Function `output_markdown`
This function performs the actual output of the Markdown-formated text. It
retrieves its information from the MARKDOWN_RESULT array, that was previously
filled by parse_input(). The output is stored in the $OUTPUT file.
### 22a. Return-Code
| Desc | Value |
| - | - |
| Type | `int` |
[^1]: Created by _shell-docs-gen.sh_ _v1.5_ on Thu Nov 2 17:04:25 UTC 2017.
shell-docs-generator (1.5-1~unki.1) stretch; urgency=medium
* pack new upstream release v1.5
-- Andreas Unterkircher <unki@netshadow.net> Thu, 02 Nov 2017 18:05:26 +0100
shell-docs-generator (1.4.1-1~unki.1) stretch; urgency=medium
* pack new upstream release v1.4.1
......
......@@ -2,7 +2,7 @@ Source: shell-docs-generator
Section: devel
Priority: optional
Maintainer: Andreas Unterkircher <unki@ask.unki.land>
Build-Depends: debhelper (>= 9), bash (>= 4.3~), util-linux, shellcheck
Build-Depends: debhelper (>= 9), bash (>= 4.3~), util-linux, shellcheck, markdownlint
Standards-Version: 3.9.8
Homepage: https://netshadow.org/miscellaneous/shell-docs-generator
Vcs-Git: https://netshadow.org/miscellaneous/shell-docs-generator.git
......
This diff is collapsed.
#!/bin/bash
. common.sh
assert_func is_declared $TEST_TRUE $TEST_EMPTY LOGNAME
unset -v SOME_UNKNOWN_VARIABLE
assert_func is_declared $TEST_FALSE $TEST_EMPTY SOME_UNKNOWN_VARIABLE
assert_func is_declared $TEST_FALSE $TEST_EMPTY
#!/bin/bash
. common.sh
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_OK}" "${TEST_EMPTY}" ''
assert_func is_empty "${TEST_OK}" "${TEST_EMPTY}" ""
assert_func is_empty "${TEST_FAIL}" "${TEST_EMPTY}" "foo"
#!/bin/bash
. 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}" "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=()
assert_func is_empty "${TEST_OK}" "${TEST_EMPTY}" TESTARY
TESTARY+=( 'foo' )
assert_func is_empty "${TEST_FAIL}" "${TEST_EMPTY}" TESTARY
TESTARY+=( 'bar' )
assert_func is_empty "${TEST_FAIL}" "${TEST_EMPTY}" TESTARY
unset -v TESTARY
declare -g -A TESTARY=()
assert_func is_empty "${TEST_OK}" "${TEST_EMPTY}" TESTARY
TESTARY+=( ['key0']='foo' )
assert_func is_empty "${TEST_FAIL}" "${TEST_EMPTY}" TESTARY
TESTARY+=( ['key1']='bar' )
assert_func is_empty "${TEST_FAIL}" "${TEST_EMPTY}" TESTARY
unset -v TESTARY
#!/bin/bash
. common.sh
assert_func is_empty_str "${TEST_FAIL}" "Invalid[[:blank:]]parameters"
assert_func is_empty_str "${TEST_FAIL}" "Invalid[[:blank:]]parameters" '/tmp' 'bla'
assert_func is_empty_str "${TEST_OK}" "${TEST_EMPTY}" ''
assert_func is_empty_str "${TEST_FAIL}" "${TEST_EMPTY}" 'foo'
#!/bin/bash
. common.sh
assert_func ascii_to_int "${TEST_FAIL}" "Invalid[[:blank:]]parameter"
assert_func ascii_to_int "${TEST_FAIL}" "Invalid[[:blank:]]parameter" 'a' 'b'
assert_func ascii_to_int "${TEST_FAIL}" "Invalid[[:blank:]]parameter" 'abc'
assert_func ascii_to_int "${TEST_FAIL}" "Invalid[[:blank:]]parameter" '!'
assert_func ascii_to_int "${TEST_FAIL}" "Invalid[[:blank:]]parameter" '!!!'
assert_func ascii_to_int "${TEST_OK}" "65" 'A'
assert_func ascii_to_int "${TEST_OK}" "97" 'a'
assert_func ascii_to_int "${TEST_OK}" "49" '1'
assert_func ascii_to_int "${TEST_OK}" "57" '9'
#!/bin/bash
. common.sh
assert_func int_to_ascii "${TEST_FAIL}" 'Invalid[[:blank:]]parameter'
assert_func int_to_ascii "${TEST_FAIL}" 'Invalid[[:blank:]]parameter' 'a' 'b'
assert_func int_to_ascii "${TEST_FAIL}" 'Invalid[[:blank:]]parameter' 'abc'
assert_func int_to_ascii "${TEST_FAIL}" 'Invalid[[:blank:]]parameter' '1' '2'
assert_func int_to_ascii "${TEST_FAIL}" 'Invalid[[:blank:]]parameter' '1234'
assert_func int_to_ascii "${TEST_FAIL}" 'Invalid[[:blank:]]parameter' '!'
assert_func int_to_ascii "${TEST_FAIL}" 'Invalid[[:blank:]]parameter' '!!!'
assert_func int_to_ascii "${TEST_OK}" 'A' '65'
assert_func int_to_ascii "${TEST_OK}" 'a' '97'
assert_func int_to_ascii "${TEST_OK}" '1' '49'
......@@ -6,6 +6,6 @@ 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
declare -A FOOBAR=()
assert_func formated_output "${TEST_FAIL}" "Unable[[:blank:]]to[[:blank:]]perform,[[:blank:]]if[[:blank:]]no" 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_OK}" "${TEST_EMPTY}" FOOBAR
......@@ -3,10 +3,14 @@ sanitize
in_array
in_array_re
is_array
is_declared
is_empty
is_empty_str
is_allowed_tag
is_cmd
is_debug
ascii_to_int
int_to_ascii
debug
write
mdout
......