From 4f8544beba4bb13a13a254cacf85043bd43e723e Mon Sep 17 00:00:00 2001
From: Alex Thiessen <alex.thiessen.de+github@gmail.com>
Date: Wed, 25 May 2022 21:19:45 +0200
Subject: [PATCH] README.md: Document `assert_regex`

Add a copy to the implementation, too.
---
 README.md             | 26 ++++++++++++++++++++++++++
 src/assert_regex.bash | 25 +++++++++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/README.md b/README.md
index fadf5c8..60c1277 100644
--- a/README.md
+++ b/README.md
@@ -693,6 +693,32 @@ An error is displayed if the specified extended regular expression is invalid.
 This option and partial matching (`--partial` or `-p`) are mutually exclusive.
 An error is displayed when used simultaneously.
 
+### `assert_regex`
+
+This function is similar to `assert_equal` but uses pattern matching instead of
+equality, by wrapping `[[ value =~ pattern ]]`.
+
+Fail if the value (first parameter) does not match the pattern (second
+parameter).
+
+```bash
+@test 'assert_regex()' {
+  assert_regex 'what' 'x$'
+}
+```
+
+On failure, the value and the pattern are displayed.
+
+```
+-- values does not match regular expression --
+value    : what
+pattern  : x$
+--
+```
+
+If the value is longer than one line then it is displayed in *multi-line*
+format.
+
 <!-- REFERENCES -->
 
 [bats]: https://github.com/bats-core/bats-core
diff --git a/src/assert_regex.bash b/src/assert_regex.bash
index b371bf3..5ad070e 100644
--- a/src/assert_regex.bash
+++ b/src/assert_regex.bash
@@ -1,3 +1,28 @@
+# `assert_regex`
+#
+# This function is similar to `assert_equal` but uses pattern matching instead
+# of equality, by wrapping `[[ value =~ pattern ]]`.
+#
+# Fail if the value (first parameter) does not match the pattern (second
+# parameter).
+#
+# ```bash
+# @test 'assert_regex()' {
+#   assert_regex 'what' 'x$'
+# }
+# ```
+#
+# On failure, the value and the pattern are displayed.
+#
+# ```
+# -- values does not match regular expression --
+# value    : what
+# pattern  : x$
+# --
+# ```
+#
+# If the value is longer than one line then it is displayed in *multi-line*
+# format.
 assert_regex() {
 	local -r value="${1}"
 	local -r pattern="${2}"