diff options
author | Alex Thiessen <alex.thiessen.de+github@gmail.com> | 2022-05-30 20:15:23 +0300 |
---|---|---|
committer | Alex Thiessen <alex.thiessen.de+github@gmail.com> | 2022-05-30 20:28:34 +0300 |
commit | baffb32e5dc6094df03239ab6286ce4ab8381ae3 (patch) | |
tree | 5c477027ac0482f0ce18b2cf987e4e1ad44da3cb | |
parent | 81d772487beab3925aec5efd4297e8ee8578ea88 (diff) |
README.md: Document `refute_regex`
Add a copy to the implementation, too.
-rw-r--r-- | README.md | 44 | ||||
-rw-r--r-- | src/refute_regex.bash | 43 |
2 files changed, 87 insertions, 0 deletions
@@ -728,6 +728,50 @@ Note that the `BASH_REMATCH` array is available immediately after the assertion succeeds but is fragile, i.e. prone to being overwritten as a side effect of other actions. +### `refute_regex` + +This function is similar to `refute_equal` but uses pattern matching instead of +equality, by wrapping `! [[ value =~ pattern ]]`. + +Fail if the value (first parameter) matches the pattern (second parameter). + +```bash +@test 'refute_regex()' { + refute_regex 'WhatsApp' 'Threema' +} +``` + +On failure, the value, the pattern and the match are displayed. + +``` +@test 'refute_regex()' { + refute_regex 'WhatsApp' 'What.' +} + +-- value matches regular expression -- +value : WhatsApp +pattern : What. +match : Whats +case : sensitive +-- +``` + +If the value or pattern is longer than one line then it is displayed in +*multi-line* format. + +An error is displayed if the specified extended regular expression is invalid. + +For description of the matching behavior, refer to the documentation of the +`=~` operator in the +[Bash manual]: https://www.gnu.org/software/bash/manual/html_node/Conditional-Constructs.html. + +Note that the `BASH_REMATCH` array is available immediately after the assertion +fails but is fragile, i.e. prone to being overwritten as a side effect of other +actions like calling `run`. Thus, it's good practice to avoid using +`BASH_REMATCH` in conjunction with `refute_regex()`. The valuable information +the array contains is the matching part of the value which is printed in the +failing test log, as mentioned above. + <!-- REFERENCES --> [bats]: https://github.com/bats-core/bats-core diff --git a/src/refute_regex.bash b/src/refute_regex.bash index 20f6b32..0918793 100644 --- a/src/refute_regex.bash +++ b/src/refute_regex.bash @@ -1,3 +1,46 @@ +# `refute_regex` +# +# This function is similar to `refute_equal` but uses pattern matching instead +# of equality, by wrapping `! [[ value =~ pattern ]]`. +# +# Fail if the value (first parameter) matches the pattern (second parameter). +# +# ```bash +# @test 'refute_regex()' { +# refute_regex 'WhatsApp' 'Threema' +# } +# ``` +# +# On failure, the value, the pattern and the match are displayed. +# +# ``` +# @test 'refute_regex()' { +# refute_regex 'WhatsApp' 'What.' +# } +# +# -- value matches regular expression -- +# value : WhatsApp +# pattern : What. +# match : Whats +# case : sensitive +# -- +# ``` +# +# If the value or pattern is longer than one line then it is displayed in +# *multi-line* format. +# +# An error is displayed if the specified extended regular expression is invalid. +# +# For description of the matching behavior, refer to the documentation of the +# `=~` operator in the +# [Bash manual]: https://www.gnu.org/software/bash/manual/html_node/Conditional-Constructs.html. +# +# Note that the `BASH_REMATCH` array is available immediately after the +# assertion fails but is fragile, i.e. prone to being overwritten as a side +# effect of other actions like calling `run`. Thus, it's good practice to avoid +# using `BASH_REMATCH` in conjunction with `refute_regex()`. The valuable +# information the array contains is the matching part of the value which is +# printed in the failing test log, as mentioned above. refute_regex() { local -r value="${1}" local -r pattern="${2}" |