Add @requires

README.md

@@ -48,13 +48,18 @@ _Output_: [examples/readme-example.md](examples/readme-example.md)<br/><br/>
 #      * b
 #      * c
 #      * etc
+# @requires foo
+# @requires bar
 
 # @description My super function.
 # Not thread-safe.
 #
 # @example
 #    echo "test: $(say-hello World)"
 #
+# @requires Some very specific requirements
+#  that continue on the next line (indent by a
+#  single space to continue)
 #
 # @option -h | --help Display help.
 # @option -v<value> | --value=<value> Set a value.
@@ -69,6 +74,9 @@ _Output_: [examples/readme-example.md](examples/readme-example.md)<br/><br/>
 # @exitcode 0 If successful.
 # @exitcode 1 If an empty string passed.
 #
+# @requires foo
+# @requires bar
+#
 # @see validate()
 # @see [shdoc](https://github.com/reconquest/shdoc).
 say-hello() {
@@ -399,6 +407,28 @@ say-hello-world() {
     ...
 }
 ```
+### `@requires`
+
+Indicates requirements needed by the file or the given function
+
+**Example**
+
+```bash
+# @name My script
+# @requires foo
+# @requires A long description of the requirements
+#  (indent by one space to continue)
+```
+
+**Example**
+
+```bash
+# @requires ubuntu>20
+# @requires curl(1)
+say-hello-world() {
+    ...
+}
+```
 
 ### `@stdin`
 

examples/readme-example.md

@@ -10,6 +10,11 @@ The project solves lots of problems:
 * c
 * etc
 
+## Requires
+
+* foo
+* bar
+
 ## Index
 
 * [say-hello](#say-hello)
@@ -62,6 +67,12 @@ echo "test: $(say-hello World)"
 * [validate()](#validate)
 * [shdoc](https://github.com/reconquest/shdoc).
 
+### Requires
+
+* Some very specific requirements
+  that continue on the next line (indent by a
+  single space to continue)
+
 ## Sub-section
 
 Some grouped functions.

examples/readme-example.sh

@@ -7,13 +7,18 @@
 #      * b
 #      * c
 #      * etc
+# @requires foo
+# @requires bar
 
 # @description My super function.
 # Not thread-safe.
 #
 # @example
 #    echo "test: $(say-hello World)"
 #
+# @requires Some very specific requirements
+#  that continue on the next line (indent by a
+#  single space to continue)
 #
 # @option -h | --help Display help.
 # @option -v<value> | --value=<value> Set a value.
@@ -54,4 +59,4 @@ deeper-level() { echo; }
 # @endsection
 
 # @description Back up again
-up-again() { echo; }
+up-again() { echo; }

shdoc

@@ -643,6 +643,10 @@ function render_docblock(func_name, description, docblock, nesting) {
         render_docblock_list(docblock, "stderr", "Output on stderr", nesting_one)
     }
 
+    if (docblock_allows("requires") && "requires" in docblock) {
+        render_docblock_list(docblock, "requires", "Requires", nesting_one)
+    }
+
     if (docblock_allows("see") && "see" in docblock) {
         push(lines, render(nesting_one, "See also"))
         for (i in docblock["see"]) {
@@ -654,6 +658,7 @@ function render_docblock(func_name, description, docblock, nesting) {
         push(lines, "")
     }
 
+
     result = join(lines)
     return result
 }
@@ -912,9 +917,9 @@ multiple_line_docblock_name {
     }
 }
 
-# Process similarly @stdin, @stdout and @stderr entries.
+# Process similarly @stdin, @stdout, @stderr and @requires entries.
 # Allow for multiple lines entries.
-match($0, /^([[:blank:]]*#[[:blank:]]+)@(stdin|stdout|stderr)[[:blank:]]+(.*[^[:blank:]])[[:blank:]]*$/, contents) {
+match($0, /^([[:blank:]]*#[[:blank:]]+)@(stdin|stdout|stderr|requires)[[:blank:]]+(.*[^[:blank:]])[[:blank:]]*$/, contents) {
     # Fetch matched values.
     indentation = contents[1]
     docblock_name = contents[2]
@@ -980,6 +985,7 @@ match($0, /^([[:blank:]]*#[[:blank:]]+)@(stdin|stdout|stderr)[[:blank:]]+(.*[^[:
         docblock_filter["example"] = 1
         docblock_filter["see"] = 1
         docblock_filter["set"] = 1
+        docblock_filter["requires"] = 1
         file_annoblock = render_docblock("", "", docblock, 1)
         delete docblock_filter
     }

tests/testcases/@requires.test.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# @file test/testcases/@requires.test.sh
+# @author Jeremy Brubaker <jbrubke@orionarts.io>
+# @brief Test cases for @requires keyword.
+# @requires foo
+# @description
+#   Test these @requires comportements:
+#   - file-level @requires
+#   - simple one line message.
+#   - one line message with indentation and trailing spaces.
+#   - indented two lines message.
+#   - three lines message with trailing spaces.
+#   - appears between @stdin and @stderr sections.
+
+tests:put input <<EOF
+# @name shdoc @requires tests
+# @description Test @requires functionality.
+# @requires foo
+#  bar
+
+# @description test_requires dummy function.
+# @requires simple one line message.
+# @requires         one line message with indentation and trailing spaces.    
+    #   @requires   indented two lines message
+    #         to test how indentation is trimmed.
+    #   Message without sufficient indentation (ignored).
+# @requires three line message    
+#     with trailing spaces    
+#  and random indentation.  
+test_requires() {
+}
+EOF
+
+tests:put expected <<EOF
+# shdoc @requires tests
+
+## Overview
+
+Test @requires functionality.
+
+## Requires
+
+* foo
+  bar
+
+## Index
+
+* [test_requires](#test_requires)
+
+## test_requires
+
+test_requires dummy function.
+
+### Requires
+
+* simple one line message.
+* one line message with indentation and trailing spaces.
+* indented two lines message
+  to test how indentation is trimmed.
+* three line message
+  with trailing spaces
+  and random indentation.
+
+EOF
+
+assert