From f33b60c001390edb934941255cdb51ae6815dae7 Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Thu, 17 Aug 2023 22:20:22 +0200
Subject: [PATCH] deprecate `--format` and `--list` in `into datetime` (#10017)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

related to
-
https://discord.com/channels/601130461678272522/614593951969574961/1141009665266831470

# Description
this PR
- prints a colorful warning when a user uses either `--format` or
`--list` on `into datetime`
- does NOT remove the features for now, i.e. the two options still work
- redirect to the `format date` command instead

i propose to
- land this now
- prepare a removal PR right after this
- land the removal PR in between 0.84 and 0.85

# User-Facing Changes
`into datetime --format` and `into datetime --list` will be deprecated
in 0.85.

## how it looks
- `into datetime --list` in the REPL
```nushell
> into datetime --list | first
Error:   × Deprecated option
   ╭─[entry #1:1:1]
 1 │ into datetime --list | first
   · ──────┬──────
   ·       ╰── `into datetime --list` is deprecated and will be removed in 0.85
   ╰────
  help: see `format datetime --list` instead


╭───────────────┬────────────────────────────────────────────╮
│ Specification │ %Y                                         │
│ Example       │ 2023                                       │
│ Description   │ The full proleptic Gregorian year,         │
│               │ zero-padded to 4 digits.                   │
╰───────────────┴────────────────────────────────────────────╯
```

- `into datetime --list` in a script
```nushell
> nu /tmp/foo.nu
Error:   × Deprecated option
   ╭─[/tmp/foo.nu:4:1]
 4 │ #
 5 │ into datetime --list | first
   · ──────┬──────
   ·       ╰── `into datetime --list` is deprecated and will be removed in 0.85
   ╰────
  help: see `format datetime --list` instead


╭───────────────┬────────────────────────────────────────────╮
│ Specification │ %Y                                         │
│ Example       │ 2023                                       │
│ Description   │ The full proleptic Gregorian year,         │
│               │ zero-padded to 4 digits.                   │
╰───────────────┴────────────────────────────────────────────╯
```

- `help into datetime`


![baz](https://github.com/nushell/nushell/assets/44101798/08beece0-9c89-4665-bfe4-76a32207470f)

# Tests + Formatting

# After Submitting
---
 .../src/conversions/into/datetime.rs          | 31 +++++++++++++++++--
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/crates/nu-command/src/conversions/into/datetime.rs b/crates/nu-command/src/conversions/into/datetime.rs
index dd33eb677..d40ec9903 100644
--- a/crates/nu-command/src/conversions/into/datetime.rs
+++ b/crates/nu-command/src/conversions/into/datetime.rs
@@ -5,6 +5,7 @@ use nu_engine::CallExt;
 use nu_protocol::ast::Call;
 use nu_protocol::ast::CellPath;
 use nu_protocol::engine::{Command, EngineState, Stack};
+use nu_protocol::report_error_new;
 use nu_protocol::{
     Category, Example, IntoPipelineData, PipelineData, ShellError, Signature, Span, Spanned,
     SyntaxShape, Type, Value,
@@ -87,12 +88,12 @@ impl Command for SubCommand {
             .named(
                 "format",
                 SyntaxShape::String,
-                "Specify expected format of string input to parse to datetime. Use --list to see options",
+                "DEPRECATED option, will be removed in 0.85: see `format date`",
                 Some('f'),
             )
             .switch(
                 "list",
-                "Show all possible variables for use in --format flag",
+                "DEPRECATED option, will be removed in 0.85: see `format date --list`",
                 Some('l'),
                 )
             .rest(
@@ -111,6 +112,17 @@ impl Command for SubCommand {
         input: PipelineData,
     ) -> Result<PipelineData, ShellError> {
         if call.has_flag("list") {
+            report_error_new(
+                engine_state,
+                &ShellError::GenericError(
+                    "Deprecated option".into(),
+                    "`into datetime --list` is deprecated and will be removed in 0.85".into(),
+                    Some(call.head),
+                    Some("see `format datetime --list` instead".into()),
+                    vec![],
+                ),
+            );
+
             Ok(generate_strftime_list(call.head, true).into_pipeline_data())
         } else {
             let cell_paths = call.rest(engine_state, stack, 0)?;
@@ -130,6 +142,19 @@ impl Command for SubCommand {
                     }),
                 };
 
+            if call.has_flag("format") {
+                report_error_new(
+                    engine_state,
+                    &ShellError::GenericError(
+                        "Deprecated option".into(),
+                        "`into datetime --format` is deprecated and will be removed in 0.85".into(),
+                        Some(call.head),
+                        Some("see `format datetime` instead".into()),
+                        vec![],
+                    ),
+                );
+            }
+
             let format_options = call
                 .get_flag::<String>(engine_state, stack, "format")?
                 .as_ref()
@@ -174,7 +199,7 @@ impl Command for SubCommand {
             },
             Example {
                 description:
-                    "Convert non-standard timestamp string to datetime using a custom format",
+                    "Convert non-standard timestamp string to datetime using a custom format (DEPRECATED: will be removed in 0.85)",
                 example: "'20210227_135540+0000' | into datetime -f '%Y%m%d_%H%M%S%z'",
                 #[allow(clippy::inconsistent_digit_grouping)]
                 result: example_result_1(1614434140_000000000),