Shell: Add some sections on the manpage about `match'

1 files changed, 24 insertions, 0 deletions

diff --git a/Base/usr/share/man/man5/Shell.md b/Base/usr/share/man/man5/Shell.md
index 5c299ce74e..590288d1f8 100644
--- a/Base/usr/share/man/man5/Shell.md
+++ b/Base/usr/share/man/man5/Shell.md
@@ -60,6 +60,8 @@ The following tokens:
 * `in` as a syntactic element of a `for` expression
 * `if` in command name position, or after the `else` keyword
 * `else` after a partial `if` expression
+* `match` in command name position
+* `as` as part of a `match` expression
 
 ##### Special characters
 Any of the following:
@@ -251,6 +253,28 @@ $ fn 1 2 3 4
 # 1 2 3 ( 1 2 3 4 )
 ```
 
+##### Match Expressions
+The pattern matching construct `match` shall choose from a sequence of patterns, and execute the corresponding action in a new frame.
+The choice is done by matching the result of the _matched expression_ (after expansion) against the _patterns_ (expanded down to either globs or literals).
+Multiple _patterns_ can be attributed to a single given action by delimiting them with a pipe ('|') symbol.
+
+The expanded _matched expression_ can optionally be given a name using the `as name` clause after the _matched expression_, with which it may be accessible in the action clauses.
+
+######
+```sh
+# Match the result of running 'make_some_value' (which is a list when captured by $(...))
+match "$(make_some_value)" as value {
+    (hello*) { echo "Hi!" }
+    (say\ *) { echo "No, I will not $value" }
+}
+
+# Match the result of running 'make_some_value', cast to a string.
+match "$(make_some_value)" {
+    hello* { echo "Hi!" }
+    say\ * { echo "No, I will not!" }
+}
+```
+
 ## Formal Grammar
 
 ### Shell Grammar