From bb30051006e8ec7a429df06ec668f124be75edd5 Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Fri, 16 Jun 2023 20:23:44 +0200
Subject: [PATCH] add a "capture" example to `str replace`, before the fancy
 ones (#9447)

closes https://github.com/nushell/nushell/issues/9437
cc/ @Sygmei :wink:

# Description
the syntax of *captures* used in `str replace` can be confusing for
people not used to the `regex` syntax.
there is already a capture example in `help str replace`
```bash
  Find and replace with fancy-regex
  > 'a successful b' | str replace '\b([sS])uc(?:cs|s?)e(ed(?:ed|ing|s?)|ss(?:es|ful(?:ly)?|i(?:ons?|ve(?:ly)?)|ors?)?)\b' '${1}ucce$2'
  a successful b
```
but it's really not trivial to understand the *capture* syntax...

this PR adds a simpler example only focused on *captures*
:partying_face:
```bash
  Use captures to manipulate the input text
  > "abc-def" | str replace "(.+)-(.+)" "${2}_${1}"
  def_abc
```

# User-Facing Changes
an example in `help str replace` to understand the syntax of *captures*.

# Tests + Formatting
- :green_circle: `toolkit fmt`
- :green_circle: `toolkit clippy`
- :black_circle: `toolkit test`
- :black_circle: `toolkit test stdlib`

# After Submitting
```
$nothing
```
---
 crates/nu-command/src/strings/str_/replace.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/crates/nu-command/src/strings/str_/replace.rs b/crates/nu-command/src/strings/str_/replace.rs
index 5c6356368..17bd8d524 100644
--- a/crates/nu-command/src/strings/str_/replace.rs
+++ b/crates/nu-command/src/strings/str_/replace.rs
@@ -133,6 +133,11 @@ impl Command for SubCommand {
                 example: r#"'abc abc abc' | str replace -a 'b' 'z' -s"#,
                 result: Some(Value::test_string("azc azc azc")),
             },
+            Example {
+                description: "Use captures to manipulate the input text",
+                example: r#""abc-def" | str replace "(.+)-(.+)" "${2}_${1}""#,
+                result: Some(Value::test_string("def_abc")),
+            },
             Example {
                 description: "Find and replace with fancy-regex",
                 example: r#"'a successful b' | str replace '\b([sS])uc(?:cs|s?)e(ed(?:ed|ing|s?)|ss(?:es|ful(?:ly)?|i(?:ons?|ve(?:ly)?)|ors?)?)\b' '${1}ucce$2'"#,