From 46b5e510ac32fbb746c3b8259b2e0ac4c27cb961 Mon Sep 17 00:00:00 2001
From: Darren Schroeder <343840+fdncred@users.noreply.github.com>
Date: Fri, 12 Jul 2024 09:48:27 -0500
Subject: [PATCH] tweak `parse` usage and examples to be more clear (#13363)

# Description

This PR just tweaks the `parse` command's usage and examples to make it
clearer what's going on "under the hood".

# User-Facing Changes
<!-- List of all changes that impact the user experience here. This
helps us keep track of breaking changes. -->

# Tests + Formatting
<!--
Don't forget to add tests that cover your changes.

Make sure you've run and fixed any issues with these commands:

- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used` to
check that you're using the standard code style
- `cargo test --workspace` to check that all tests pass (on Windows make
sure to [enable developer
mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging))
- `cargo run -- -c "use toolkit.nu; toolkit test stdlib"` to run the
tests for the standard library

> **Note**
> from `nushell` you can also use the `toolkit` as follows
> ```bash
> use toolkit.nu # or use an `env_change` hook to activate it
automatically
> toolkit check pr
> ```
-->

# After Submitting
<!-- If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
-->
---
 crates/nu-command/src/strings/parse.rs | 27 ++++++++++++++++----------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/crates/nu-command/src/strings/parse.rs b/crates/nu-command/src/strings/parse.rs
index 9bf31de73c..86b27aecbc 100644
--- a/crates/nu-command/src/strings/parse.rs
+++ b/crates/nu-command/src/strings/parse.rs
@@ -12,13 +12,17 @@ impl Command for Parse {
     }
 
     fn usage(&self) -> &str {
-        "Parse columns from string data using a simple pattern."
+        "Parse columns from string data using a simple pattern or a supplied regular expression."
     }
 
     fn search_terms(&self) -> Vec<&str> {
         vec!["pattern", "match", "regex", "str extract"]
     }
 
+    fn extra_usage(&self) -> &str {
+        "The parse command always uses regular expressions even when you use a simple pattern. If a simple pattern is supplied, parse will transform that pattern into a regular expression."
+    }
+
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("parse")
             .required("pattern", SyntaxShape::String, "The pattern to match.")
@@ -32,21 +36,24 @@ impl Command for Parse {
     }
 
     fn examples(&self) -> Vec<Example> {
-        let result = Value::test_list(vec![Value::test_record(record! {
-            "foo" => Value::test_string("hi"),
-            "bar" => Value::test_string("there"),
-        })]);
-
         vec![
             Example {
                 description: "Parse a string into two named columns",
                 example: "\"hi there\" | parse \"{foo} {bar}\"",
-                result: Some(result.clone()),
+                result: Some(Value::test_list(
+                    vec![Value::test_record(record! {
+                        "foo" => Value::test_string("hi"),
+                        "bar" => Value::test_string("there"),
+                    })])),
             },
             Example {
-                description: "Parse a string using regex pattern",
-                example: "\"hi there\" | parse --regex '(?P<foo>\\w+) (?P<bar>\\w+)'",
-                result: Some(result),
+                description: "This is how the first example is interpreted in the source code",
+                example: "\"hi there\" | parse --regex '(?s)\\A(?P<foo>.*?) (?P<bar>.*?)\\z'",
+                result: Some(Value::test_list(
+                    vec![Value::test_record(record! {
+                        "foo" => Value::test_string("hi"),
+                        "bar" => Value::test_string("there"),
+                    })])),
             },
             Example {
                 description: "Parse a string using fancy-regex named capture group pattern",