From 9cc74e7a9f6b012b94c7151213667c3735d7ae9f Mon Sep 17 00:00:00 2001 From: 132ikl <132@ikl.sh> Date: Thu, 5 Jun 2025 15:31:22 -0400 Subject: [PATCH] Update where documentation (#15467) # Description Updates `help where` to better explain row conditions, and provide more examples. Also, the syntax shape is changed to `one_of(condition, closure())>`. I don't think this should affect parsing at all because it should still always be parsed as `SyntaxShape::RowCondition`, but it should be more clear that you can use a row condition _or_ a closure here, even if technically we consider closures to be row conditions internally. In a similar vein, the help text makes this distinction explicitly to make it more clear to users that closures are supported. # User-Facing Changes * Updated `where` help text --------- Co-authored-by: Bahex Co-authored-by: Douglas <32344964+NotTheDr01ds@users.noreply.github.com> Co-authored-by: Stefan Holderbach --- crates/nu-command/src/filters/where_.rs | 59 +++++++++++++++++-------- 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/crates/nu-command/src/filters/where_.rs b/crates/nu-command/src/filters/where_.rs index eb43998358..b77dd13a9a 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 (`$in`) to the closure. Unlike row conditions, the `$it` variable isn't available inside closures. + +Row conditions cannot be stored in a variable. To pass a condition with a variable, use a closure instead."# } fn command_type(&self) -> CommandType { @@ -34,12 +42,12 @@ not supported."# (Type::Range, Type::Any), ]) .required( - "row_condition", + "condition", SyntaxShape::OneOf(vec![ SyntaxShape::RowCondition, SyntaxShape::Closure(Some(vec![SyntaxShape::Any])), ]), - "Filter condition.", + "Filter row condition or closure.", ) .allow_variants_without_examples(true) .category(Category::Filters) @@ -86,9 +94,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", @@ -96,13 +104,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 { @@ -110,18 +113,36 @@ 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 inside the row condition"#, 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, },