Mercurial > hgrepos > FreeBSD > ports > sysutils > local-bsdtools

changeset 523:ea199195b214

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Style: make docs more consistent
author Franz Glasner <fzglas.hg@dom66.de>
date Tue, 03 Sep 2024 12:19:11 +0200
parents 210695c732dd
children 0665a15bd3ca
files share/local-bsdtools/array.sh
diffstat 1 files changed, 57 insertions(+), 56 deletions(-) [+]
line wrap: on
line diff
--- a/share/local-bsdtools/array.sh	Mon Sep 02 02:12:07 2024 +0200
+++ b/share/local-bsdtools/array.sh	Tue Sep 03 12:19:11 2024 +0200
@@ -64,7 +64,7 @@
 #: Internal error for fatal errors.
 #:
 #: Args:
-#:   $1 (str): The error message
+#:   $1 (str): The error message.
 #:
 _farr_fatal() {
     echo "ERROR: ${1}" 1>&2
@@ -76,7 +76,7 @@
 #: Quote the given input to be safely used in evals with "Dollar-Single Quotes"
 #:
 #: Args:
-#:   $1: the value to be quoted
+#:   $1: The value to be quoted.
 #:
 #:
 #: From FreeBSD's :manpage:`sh(1)`:
@@ -110,7 +110,7 @@
 #:
 #: Args:
 #:   $1 (str): The name of the array.
-#:             Must conform to shell variable naming conventions
+#:             Must conform to shell variable naming conventions.
 #:   $2... (optional): Optional initialization values
 #:
 #: Exit:
@@ -144,8 +144,8 @@
 #:
 #: Args:
 #:   $1 (str): The name of the array.
-#:             Must conform to shell variable naming conventions
-#:   $2... (optional): Optional initialization values
+#:             Must conform to shell variable naming conventions.
+#:   $2... (optional): Optional initialization values.
 #:
 #: If the array exists already it will be reinitialized completely.
 #: If the array does not exist already it is just like `array_create`.
@@ -162,7 +162,7 @@
 #: Get the length of an array and put it into a variable
 #:
 #: Args:
-#:   $1 (str): The name of the variable to put the length into
+#:   $1 (str): The name of the variable to put the length into.
 #:   $2 (str): The name of the array.
 #:
 #: Returns:
@@ -226,7 +226,7 @@
 #: Append a value to an existing array.
 #:
 #: Args:
-#:   $1 (str): The name of the existing array
+#:   $1 (str): The name of the existing array.
 #:   $2 (optional): The value to append. If the value is not given the null
 #:                  will be appended.
 #:
@@ -265,8 +265,8 @@
 #: Set an array at an index to a value.
 #:
 #: Args:
-#:   $1 (str): The name of the existing array
-#:   $2 (int): The index
+#:   $1 (str): The name of the existing array.
+#:   $2 (int): The index.
 #:   $3 (optional): The value to set. If the value is not given the null
 #:                  will be appended.
 #:
@@ -314,9 +314,9 @@
 #: Get an array value from a given index and put it into given variable.
 #:
 #: Args:
-#:   $1 (str): The name of the variable to put the value into
-#:   $2 (str): The name of the existing array
-#:   $3 (int): The index
+#:   $1 (str): The name of the variable to put the value into.
+#:   $2 (str): The name of the existing array.
+#:   $3 (int): The index.
 #:
 array_get() {
     local __farr_varname __farr_name __farr_index
@@ -350,13 +350,13 @@
 #: Try to get an array value from a given index into a variable
 #:
 #: Args:
-#:   $1 (str): The name of the variable to put the value into
-#:   $2 (str): The name of the existing array
-#:   $3 (int): The index
+#:   $1 (str): The name of the variable to put the value into.
+#:   $2 (str): The name of the existing array.
+#:   $3 (int): The index.
 #:
 #: Returns:
 #:   0 (truthy) on success,
-#:   1 (falsy) if the given index is out of bounds (i.e. EOD)
+#:   1 (falsy) if the given index is out of bounds (i.e. EOD).
 #:
 #: Exit:
 #:   Other errors (missing array name, missing index value) are considered
@@ -395,8 +395,8 @@
 #: Delete an array value at a given index.
 #:
 #: Args:
-#:   $1 (str): The name of the existing array
-#:   $2 (int): The index to delete to
+#:   $1 (str): The name of the existing array.
+#:   $2 (int): The index to delete to.
 #:
 array_del() {
     local __farr_name __farr_index
@@ -442,7 +442,7 @@
 #: Empty an existing array.
 #:
 #: Args:
-#:   $1 (str): The name of the existing array
+#:   $1 (str): The name of the existing array.
 #:
 array_clear() {
     local __farr_name
@@ -477,8 +477,8 @@
 #:   $1 (str): The name of an array. The array may exist or not.
 #:
 #: Returns:
-#:   - A truthy value if the array existed and has been deleted
-#:   - A falsy value if the array does not exist
+#:   - A truthy value if the array existed and has been deleted.
+#:   - A falsy value if the array does not exist.
 #:
 array_destroy() {
     local __farr_name
@@ -509,11 +509,11 @@
 #: Determine whether a value is found within the array
 #:
 #: Args:
-#:   $1: The name of an existing array
-#:   $2: The value to search for
+#:   $1: The name of an existing array.
+#:   $2: The value to search for.
 #:
 #: Returns:
-#:   0 (truish) if the argument value is found within the given array
+#:   0 (truish) if the argument value is found within the given array,
 #:   1 (falsy) otherwise
 #:
 array_contains() {
@@ -724,7 +724,7 @@
 #:
 #: Args:
 #:   $1 (str): The name of the alist.
-#:             Must conform to shell variable naming conventions
+#:             Must conform to shell variable naming conventions.
 #:
 #: Exit:
 #:   Iff the alist already exists.
@@ -755,7 +755,7 @@
 #:
 #: Returns:
 #:   0 (truthy) if the array exists,
-#:   1 (falsy) if the array does not exist
+#:   1 (falsy) if the array does not exist.
 #:
 alist_length() {
     local __farr_varname __farr_name
@@ -777,7 +777,7 @@
 #: Get the length of an alist.
 #:
 #: Args:
-#:   $1 (str): The name of the variable to put the length into
+#:   $1 (str): The name of the variable to put the length into.
 #:   $2 (str): The name of the alist.
 #:
 #: Output (stdout):
@@ -805,7 +805,7 @@
 #: Empty an existing alist.
 #:
 #: Args:
-#:   $1 (str): The name of the existing alist
+#:   $1 (str): The name of the existing alist.
 #:
 alist_clear() {
     local __farr_name
@@ -827,7 +827,7 @@
 #:
 #: Args:
 #:   $1 (str): The name of the alist.
-#:             Must conform to shell variable naming conventions
+#:             Must conform to shell variable naming conventions.
 #:
 #: If the alist exists already it will be reinitialized completely.
 #: If the alist does not exist already it is just like `alist_create`.
@@ -847,8 +847,8 @@
 #:   $1 (str): The name of an alist. The alist may exist or not.
 #:
 #: Returns:
-#:   - A truthy value if the alist existed and has been deleted
-#:   - A falsy value if the alist does not exist
+#:   - A truthy value if the alist existed and has been deleted.
+#:   - A falsy value if the alist does not exist.
 #:
 alist_destroy() {
     local __farr_name
@@ -872,12 +872,12 @@
 
 
 #:
-#: Map a key to a value
+#: Map a key to a value.
 #:
 #: Args:
-#:   $1 (str): The name of an existing alist
-#:   $2: The key
-#:   $3: The value
+#:   $1 (str): The name of an existing alist.
+#:   $2: The key.
+#:   $3: The value.
 #:
 #: Exit:
 #:   If one of the underlying arrays that implement the alist does not exist
@@ -916,13 +916,13 @@
 #: Get the value that is associated with a key and put it into a variable.
 #:
 #: Args:
-#:   $1 (str): The name of the variable to put the value into
-#:   $2 (str): The name of an existing alist
-#:   $3: The key
+#:   $1 (str): The name of the variable to put the value into.
+#:   $2 (str): The name of an existing alist.
+#:   $3: The key.
 #:
 #: Exit:
 #:   - If the key is not found.
-#:   - If one of the underlying arrays that implement the alist does not exist
+#:   - If one of the underlying arrays that implement the alist does not exist.
 #:     or if an internal inconsistency will be detected.
 #:
 alist_get() {
@@ -950,16 +950,17 @@
 
 
 #:
-#: Try to get the value that is associated with a key and store it in a variable
+#: Try to get the value that is associated with a key and store it in a
+#: variable.
 #:
 #: Args:
-#:   $1 (str): The name of the variable where to put the value into
-#:   $2 (str): The name of an existing alist
-#:   $3: The key
+#:   $1 (str): The name of the variable where to put the value into.
+#:   $2 (str): The name of an existing alist.
+#:   $3: The key.
 #:
 #: Returns:
 #:   0 (truthy) on success,
-#:   1 (falsy) if the given key is not found
+#:   1 (falsy) if the given key is not found.
 #:
 alist_tryget() {
     local __farr_varname __farr_name __farr_key
@@ -992,13 +993,13 @@
 #: Use this for iteration over values.
 #:
 #: Args:
-#:   $1 (str): The name of the variable where to put the key into
-#:   $2 (str): The name of an existing alist
-#:   $3 (int): The index
+#:   $1 (str): The name of the variable where to put the key into.
+#:   $2 (str): The name of an existing alist.
+#:   $3 (int): The index.
 #:
 #: Returns:
 #:   0 (truthy) on success,
-#:   1 (falsy) if the given index is out of bounds
+#:   1 (falsy) if the given index is out of bounds.
 #:
 #: Exit:
 #:   Other errors (missing array name, missing index value) are considered
@@ -1027,13 +1028,13 @@
 #: Use this for iteration over keys.
 #:
 #: Args:
-#:   $1 (str): The name of the variable where to put the value into
-#:   $2 (str): The name of an existing alist
-#:   $3 (int): The index
+#:   $1 (str): The name of the variable where to put the value into.
+#:   $2 (str): The name of an existing alist.
+#:   $3 (int): The index.
 #:
 #: Returns:
 #:   0 (truthy) on success,
-#:   1 (falsy) if the given index is out of bounds
+#:   1 (falsy) if the given index is out of bounds.
 #:
 #: Exit:
 #:   Other errors (missing array name, missing index value) are considered
@@ -1057,15 +1058,15 @@
 
 
 #:
-#: Determine whether a key is found within the alist
+#: Determine whether a key is found within the alist.
 #:
 #: Args:
-#:   $1 (str): The name of an existing alist
-#:   $2: The key
+#:   $1 (str): The name of an existing alist.
+#:   $2: The key.
 #:
 #: Returns:
 #:   0 (truthy) on success if the key is found,
-#:   1 (falsy) if the given key is not found
+#:   1 (falsy) if the given key is not found.
 #:
 alist_contains() {
     local __farr_name __farr_key