From cdbcf83b5708a222e10810377b2f8414b9a5ed6e Mon Sep 17 00:00:00 2001 From: 132ikl <132@ikl.sh> Date: Tue, 1 Apr 2025 18:52:37 -0400 Subject: [PATCH 1/4] Update where documentation --- crates/nu-command/src/filters/where_.rs | 59 ++++++++++++++++--------- 1 file changed, 37 insertions(+), 22 deletions(-) diff --git a/crates/nu-command/src/filters/where_.rs b/crates/nu-command/src/filters/where_.rs index cf40639172..d0c4288c83 100644 --- a/crates/nu-command/src/filters/where_.rs +++ b/crates/nu-command/src/filters/where_.rs @@ -10,13 +10,21 @@ impl Command for Where { } fn description(&self) -> &str { - "Filter values based on a row condition." + "Filter values of an input list based on a condition." } fn extra_description(&self) -> &str { - r#"This command works similar to 'filter' but allows extra shorthands for working with -tables, known as "row conditions". On the other hand, reading the condition from a variable is -not supported."# + r#"A condition is evaluated for each element of the input, and only elements which meet the condition are included in the output. + +A condition can be either a "row condition", or a closure. A row condition is a special short-hand syntax to makes accessing fields easier. +Each element of the input can be accessed through the $it variable. + +On the left hand side of a row condition, any field name is automatically expanded to use $it. +For example, where type == dir is equivalent to where $it.type == dir. This expansion does not happen when passing a subexpression or closure to where. + +When using a closure, the element is passed as an argument and as pipeline input to the closure. + +While where supports closure literals, they can not be read from a variable. To filter using a closure stored in a variable, use the filter command."# } fn command_type(&self) -> CommandType { @@ -34,9 +42,9 @@ not supported."# (Type::Range, Type::Any), ]) .required( - "row_condition", - SyntaxShape::RowCondition, - "Filter condition.", + "condition", + SyntaxShape::OneOf(vec![SyntaxShape::RowCondition, SyntaxShape::Closure(None)]), + "Filter row condition or closure.", ) .allow_variants_without_examples(true) .category(Category::Filters) @@ -85,11 +93,9 @@ not supported."# )), }, Example { - description: "Filter items of a list according to a condition", - example: "[1 2] | where {|x| $x > 1}", - result: Some(Value::test_list( - vec![Value::test_int(2)], - )), + description: "List only the files in the current directory", + example: "ls | where type == file", + result: None, }, Example { description: "List all files in the current directory with sizes greater than 2kb", @@ -97,13 +103,8 @@ not supported."# result: None, }, Example { - description: "List only the files in the current directory", - example: "ls | where type == file", - result: None, - }, - Example { - description: "List all files with names that contain \"Car\"", - example: "ls | where name =~ \"Car\"", + description: r#"List all files with names that contain "Car""#, + example: r#"ls | where name =~ "Car""#, result: None, }, Example { @@ -111,18 +112,32 @@ not supported."# example: "ls | where modified >= (date now) - 2wk", result: None, }, + Example { + description: "Filter items of a list with a row condition", + example: "[1 2 3 4 5] | where $it > 2", + result: Some(Value::test_list( + vec![Value::test_int(3), Value::test_int(4), Value::test_int(5)], + )), + }, + Example { + description: "Filter items of a list with a closure", + example: "[1 2 3 4 5] | where {|x| $x > 2 }", + result: Some(Value::test_list( + vec![Value::test_int(3), Value::test_int(4), Value::test_int(5)], + )), + }, Example { description: "Find files whose filenames don't begin with the correct sequential number", - example: "ls | where type == file | sort-by name --natural | enumerate | where {|e| $e.item.name !~ $'^($e.index + 1)' } | each {|| get item }", + example: "ls | where type == file | sort-by name --natural | enumerate | where {|e| $e.item.name !~ $'^($e.index + 1)' } | get item", result: None, }, Example { - description: r#"Find case-insensitively files called "readme", without an explicit closure"#, + description: r#"Find case-insensitively files called "readme", with a subexpression"#, example: "ls | where ($it.name | str downcase) =~ readme", result: None, }, Example { - description: "same as above but with regex only", + description: r#"Find case-insensitively files called "readme", with regex only"#, example: "ls | where name =~ '(?i)readme'", result: None, } From 1da3beb1ca7841288c99802330d92fb794fd3477 Mon Sep 17 00:00:00 2001 From: 132ikl <132@ikl.sh> Date: Tue, 1 Apr 2025 23:45:42 -0400 Subject: [PATCH 2/4] Update crates/nu-command/src/filters/where_.rs Co-authored-by: Bahex --- crates/nu-command/src/filters/where_.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/crates/nu-command/src/filters/where_.rs b/crates/nu-command/src/filters/where_.rs index d0c4288c83..f6ece970bf 100644 --- a/crates/nu-command/src/filters/where_.rs +++ b/crates/nu-command/src/filters/where_.rs @@ -43,7 +43,10 @@ While where supports closure literals, they can not be read from a variable. To ]) .required( "condition", - SyntaxShape::OneOf(vec![SyntaxShape::RowCondition, SyntaxShape::Closure(None)]), + SyntaxShape::OneOf(vec![ + SyntaxShape::RowCondition, + SyntaxShape::Closure(Some(vec![SyntaxShape::Any])), + ]), "Filter row condition or closure.", ) .allow_variants_without_examples(true) From 3f708959697abe40e75193e94a700ec15e712c91 Mon Sep 17 00:00:00 2001 From: 132ikl <132@ikl.sh> Date: Wed, 2 Apr 2025 18:31:59 -0400 Subject: [PATCH 3/4] Update crates/nu-command/src/filters/where_.rs Co-authored-by: Douglas <32344964+NotTheDr01ds@users.noreply.github.com> --- crates/nu-command/src/filters/where_.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/nu-command/src/filters/where_.rs b/crates/nu-command/src/filters/where_.rs index f6ece970bf..d9caab1050 100644 --- a/crates/nu-command/src/filters/where_.rs +++ b/crates/nu-command/src/filters/where_.rs @@ -16,7 +16,7 @@ impl Command for Where { fn extra_description(&self) -> &str { r#"A condition is evaluated for each element of the input, and only elements which meet the condition are included in the output. -A condition can be either a "row condition", or a closure. A row condition is a special short-hand syntax to makes accessing fields easier. +A condition can be either a "row condition" or a closure. A row condition is a special short-hand syntax to simplify field access. Each element of the input can be accessed through the $it variable. On the left hand side of a row condition, any field name is automatically expanded to use $it. From a0051b33a20c3273c593fecae6c391bf4c37c88b Mon Sep 17 00:00:00 2001 From: 132ikl <132@ikl.sh> Date: Wed, 2 Apr 2025 18:32:06 -0400 Subject: [PATCH 4/4] Update crates/nu-command/src/filters/where_.rs Co-authored-by: Douglas <32344964+NotTheDr01ds@users.noreply.github.com> --- crates/nu-command/src/filters/where_.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/nu-command/src/filters/where_.rs b/crates/nu-command/src/filters/where_.rs index d9caab1050..9c61caa9e5 100644 --- a/crates/nu-command/src/filters/where_.rs +++ b/crates/nu-command/src/filters/where_.rs @@ -24,7 +24,7 @@ For example, where type == dir is equivalent to where $it.type == dir. This expa When using a closure, the element is passed as an argument and as pipeline input to the closure. -While where supports closure literals, they can not be read from a variable. To filter using a closure stored in a variable, use the filter command."# +`where` supports closure literals, but not closures stored in a variable. To filter using a closure stored in a variable, use the `filter` command."# } fn command_type(&self) -> CommandType {