str collect => str join (#6531)

* Initialize join.rs as a copy of collect.rs

* Evolve StrCollect into StrJoin

* Replace 'str collect' with 'str join' everywhere

git ls-files | lines | par-each { |it| sed -i 's,str collect,str join,g' $it }

* Deprecate 'str collect'

* Revert "Deprecate 'str collect'"

This reverts commit 959d14203e.

* Change `str collect` help message to say that it is deprecated

We cannot remove `str collect` currently (i.e. via
`nu_protocol::ShellError::DeprecatedCommand` since a prominent project
uses the API:

b85542c31c/src/virtualenv/activation/nushell/activate.nu (L43)

crates/nu-command/src/default_context.rs

@@ -201,6 +201,7 @@ pub fn create_default_context() -> EngineState {
             StrDistance,
             StrDowncase,
             StrEndswith,
+            StrJoin,
             StrReplace,
             StrIndexOf,
             StrKebabCase,

crates/nu-command/src/example_test.rs

@@ -14,7 +14,7 @@ use crate::To;
 #[cfg(test)]
 use super::{
     Ansi, Date, From, If, Into, LetEnv, Math, Path, Random, Split, SplitColumn, SplitRow, Str,
-    StrCollect, StrLength, StrReplace, Url, Wrap,
+    StrJoin, StrLength, StrReplace, Url, Wrap,
 };
 
 #[cfg(test)]
@@ -29,7 +29,7 @@ pub fn test_examples(cmd: impl Command + 'static) {
         // Try to keep this working set small to keep tests running as fast as possible
         let mut working_set = StateWorkingSet::new(&*engine_state);
         working_set.add_decl(Box::new(Str));
-        working_set.add_decl(Box::new(StrCollect));
+        working_set.add_decl(Box::new(StrJoin));
         working_set.add_decl(Box::new(StrLength));
         working_set.add_decl(Box::new(StrReplace));
         working_set.add_decl(Box::new(BuildString));

crates/nu-command/src/filters/upsert.rs

@@ -62,7 +62,7 @@ impl Command for Upsert {
             result: Some(Value::List { vals: vec![Value::Record { cols: vec!["count".into(), "fruit".into()], vals: vec![Value::test_int(2), Value::test_string("apple")], span: Span::test_data()}], span: Span::test_data()}),
         }, Example {
             description: "Use in block form for more involved updating logic",
-            example: "echo [[project, authors]; ['nu', ['Andrés', 'JT', 'Yehuda']]] | upsert authors {|a| $a.authors | str collect ','}",
+            example: "echo [[project, authors]; ['nu', ['Andrés', 'JT', 'Yehuda']]] | upsert authors {|a| $a.authors | str join ','}",
             result: Some(Value::List { vals: vec![Value::Record { cols: vec!["project".into(), "authors".into()], vals: vec![Value::test_string("nu"), Value::test_string("Andrés,JT,Yehuda")], span: Span::test_data()}], span: Span::test_data()}),
         }]
     }

crates/nu-command/src/platform/ansi/ansi_.rs

@@ -141,7 +141,7 @@ lazy_static! {
     // Reference for ansi codes https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797
     // Another good reference http://ascii-table.com/ansi-escape-sequences.php
 
-    // For setting title like `echo [(char title) (pwd) (char bel)] | str collect`
+    // For setting title like `echo [(char title) (pwd) (char bel)] | str join`
     AnsiCode{short_name: None, long_name:"title", code: "\x1b]2;".to_string()}, // ESC]2; xterm sets window title using OSC syntax escapes
 
     // Ansi Erase Sequences
@@ -258,7 +258,7 @@ following values:
     https://en.wikipedia.org/wiki/ANSI_escape_code
 
 OSC: '\x1b]' is not required for --osc parameter
-Example: echo [(ansi -o '0') 'some title' (char bel)] | str collect
+Example: echo [(ansi -o '0') 'some title' (char bel)] | str join
 Format: #
     0 Set window title and icon name
     1 Set icon name
@@ -285,14 +285,14 @@ Format: #
             Example {
                 description:
                     "Use ansi to color text (rb = red bold, gb = green bold, pb = purple bold)",
-                example: r#"echo [(ansi rb) Hello " " (ansi gb) Nu " " (ansi pb) World (ansi reset)] | str collect"#,
+                example: r#"echo [(ansi rb) Hello " " (ansi gb) Nu " " (ansi pb) World (ansi reset)] | str join"#,
                 result: Some(Value::test_string(
                     "\u{1b}[1;31mHello \u{1b}[1;32mNu \u{1b}[1;35mWorld\u{1b}[0m",
                 )),
             },
             Example {
                 description: "Use ansi to color text (italic bright yellow on red 'Hello' with green bold 'Nu' and purple bold 'World')",
-                example: r#"echo [(ansi -e '3;93;41m') Hello (ansi reset) " " (ansi gb) Nu " " (ansi pb) World (ansi reset)] | str collect"#,
+                example: r#"echo [(ansi -e '3;93;41m') Hello (ansi reset) " " (ansi gb) Nu " " (ansi pb) World (ansi reset)] | str join"#,
                 result: Some(Value::test_string(
                     "\u{1b}[3;93;41mHello\u{1b}[0m \u{1b}[1;32mNu \u{1b}[1;35mWorld\u{1b}[0m",
                 )),

crates/nu-command/src/platform/ansi/strip.rs

@@ -40,7 +40,7 @@ impl Command for SubCommand {
     fn examples(&self) -> Vec<Example> {
         vec![Example {
             description: "Strip ANSI escape sequences from a string",
-            example: r#"echo [ (ansi green) (ansi cursor_on) "hello" ] | str collect | ansi strip"#,
+            example: r#"echo [ (ansi green) (ansi cursor_on) "hello" ] | str join | ansi strip"#,
             result: Some(Value::test_string("hello")),
         }]
     }

crates/nu-command/src/strings/char_.rs

@@ -185,7 +185,7 @@ impl Command for Char {
             },
             Example {
                 description: "Output prompt character, newline and a hamburger character",
-                example: r#"echo [(char prompt) (char newline) (char hamburger)] | str collect"#,
+                example: r#"echo [(char prompt) (char newline) (char hamburger)] | str join"#,
                 result: Some(Value::test_string("\u{25b6}\n\u{2261}")),
             },
             Example {

crates/nu-command/src/strings/str_/collect.rs

@@ -25,11 +25,7 @@ impl Command for StrCollect {
     }
 
     fn usage(&self) -> &str {
-        "Concatenate multiple strings into a single string, with an optional separator between each"
-    }
-
-    fn search_terms(&self) -> Vec<&str> {
-        vec!["join", "concatenate"]
+        "'str collect' is deprecated. Please use 'str join' instead."
     }
 
     fn run(

crates/nu-command/src/strings/str_/join.rs

@@ -0,0 +1,106 @@
+use nu_engine::CallExt;
+use nu_protocol::ast::Call;
+use nu_protocol::engine::{Command, EngineState, Stack};
+use nu_protocol::{
+    Category, Example, IntoPipelineData, PipelineData, ShellError, Signature, Span, SyntaxShape,
+    Value,
+};
+
+#[derive(Clone)]
+pub struct StrJoin;
+
+impl Command for StrJoin {
+    fn name(&self) -> &str {
+        "str join"
+    }
+
+    fn signature(&self) -> Signature {
+        Signature::build("str join")
+            .optional(
+                "separator",
+                SyntaxShape::String,
+                "optional separator to use when creating string",
+            )
+            .category(Category::Strings)
+    }
+
+    fn usage(&self) -> &str {
+        "Concatenate multiple strings into a single string, with an optional separator between each"
+    }
+
+    fn search_terms(&self) -> Vec<&str> {
+        vec!["collect", "concatenate"]
+    }
+
+    fn run(
+        &self,
+        engine_state: &EngineState,
+        stack: &mut Stack,
+        call: &Call,
+        input: PipelineData,
+    ) -> Result<PipelineData, ShellError> {
+        let separator: Option<String> = call.opt(engine_state, stack, 0)?;
+
+        let config = engine_state.get_config();
+
+        // let output = input.collect_string(&separator.unwrap_or_default(), &config)?;
+        // Hmm, not sure what we actually want. If you don't use debug_string, Date comes out as human readable
+        // which feels funny
+        let mut strings: Vec<String> = vec![];
+
+        for value in input {
+            match value {
+                Value::Error { error } => {
+                    return Err(error);
+                }
+                value => {
+                    strings.push(value.debug_string("\n", config));
+                }
+            }
+        }
+
+        let output = if let Some(separator) = separator {
+            strings.join(&separator)
+        } else {
+            strings.join("")
+        };
+
+        Ok(Value::String {
+            val: output,
+            span: call.head,
+        }
+        .into_pipeline_data())
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![
+            Example {
+                description: "Create a string from input",
+                example: "['nu', 'shell'] | str join",
+                result: Some(Value::String {
+                    val: "nushell".to_string(),
+                    span: Span::test_data(),
+                }),
+            },
+            Example {
+                description: "Create a string from input with a separator",
+                example: "['nu', 'shell'] | str join '-'",
+                result: Some(Value::String {
+                    val: "nu-shell".to_string(),
+                    span: Span::test_data(),
+                }),
+            },
+        ]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn test_examples() {
+        use crate::test_examples;
+
+        test_examples(StrJoin {})
+    }
+}

crates/nu-command/src/strings/str_/mod.rs

@@ -4,6 +4,7 @@ mod contains;
 mod distance;
 mod ends_with;
 mod index_of;
+mod join;
 mod length;
 mod lpad;
 mod replace;
@@ -19,6 +20,7 @@ pub use contains::SubCommand as StrContains;
 pub use distance::SubCommand as StrDistance;
 pub use ends_with::SubCommand as StrEndswith;
 pub use index_of::SubCommand as StrIndexOf;
+pub use join::*;
 pub use length::SubCommand as StrLength;
 pub use lpad::SubCommand as StrLpad;
 pub use replace::SubCommand as StrReplace;