Deprecate --numbered from for (#13112)

# Description

#7777 removed the `--numbered` flag from `each`, `par-each`, `reduce`,
and `each while`. It was suggested at the time that it should be removed
from `for` as well, but for several reasons it wasn't.

This PR deprecates `--numbered` in anticipation of removing it in 0.96.

Note: Please review carefully, as this is my first "real" Rust/Nushell
code. I was hoping that some prior commit would be useful as a template,
but since this was an argument on a parser keyword, I didn't find too
much useful. So I had to actually find the relevant helpers in the code
and `nu_protocol` doc and learn how to use them - oh darn ;-) But please
make sure I did it correctly.

# User-Facing Changes

* Use of `--numbered` will result in a deprecation warning.
* Changed help example to demonstrate the new syntax.
* Help shows deprecation notice on the flag

crates/nu-cmd-lang/src/core_commands/for_.rs

@@ -1,5 +1,6 @@
 use nu_engine::{command_prelude::*, get_eval_block, get_eval_expression};
 use nu_protocol::engine::CommandType;
+use nu_protocol::ParseWarning;
 
 #[derive(Clone)]
 pub struct For;
@@ -30,7 +31,7 @@ impl Command for For {
             .required("block", SyntaxShape::Block, "The block to run.")
             .switch(
                 "numbered",
-                "return a numbered item ($it.index and $it.item)",
+                "DEPRECATED: return a numbered item ($it.index and $it.item)",
                 Some('n'),
             )
             .creates_scope()
@@ -78,6 +79,20 @@ impl Command for For {
         let value = eval_expression(engine_state, stack, keyword_expr)?;
 
         let numbered = call.has_flag(engine_state, stack, "numbered")?;
+        if numbered {
+            nu_protocol::report_error_new(
+                engine_state,
+                &ParseWarning::DeprecatedWarning {
+                    old_command: "--numbered/-n".into(),
+                    new_suggestion: "use `enumerate`".into(),
+                    span: call
+                        .get_named_arg("numbered")
+                        .expect("`get_named_arg` found `--numbered` but still failed")
+                        .span,
+                    url: "See `help for` examples".into(),
+                },
+            );
+        }
 
         let ctrlc = engine_state.ctrlc.clone();
         let engine_state = engine_state.clone();
@@ -198,8 +213,7 @@ impl Command for For {
             },
             Example {
                 description: "Number each item and print a message",
-                example:
+                example: r#"for $it in (['bob' 'fred'] | enumerate) { print $"($it.index) is ($it.item)" }"#,
-                    "for $it in ['bob' 'fred'] --numbered { print $\"($it.index) is ($it.item)\" }",
                 result: None,
             },
         ]

crates/nu-protocol/src/errors/parse_warning.rs

@@ -10,7 +10,7 @@ pub enum ParseWarning {
     DeprecatedWarning {
         old_command: String,
         new_suggestion: String,
-        #[label("`{old_command}` is deprecated and will be removed in 0.94. Please {new_suggestion} instead")]
+        #[label("`{old_command}` is deprecated and will be removed in a future release. Please {new_suggestion} instead")]
         span: Span,
         url: String,
     },