From 4dc7585dc37e6880dbe0c4ca88c83c4985ac23ee Mon Sep 17 00:00:00 2001 From: Raoul Kent Date: Tue, 3 Jun 2025 16:44:17 +0200 Subject: [PATCH 1/3] docs(closure.md): Add simple examples of using closures --- .../chapters/types/basic_types/closure.md | 82 ++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/lang-guide/chapters/types/basic_types/closure.md b/lang-guide/chapters/types/basic_types/closure.md index ae8e464e7b0..0cf8eac881f 100644 --- a/lang-guide/chapters/types/basic_types/closure.md +++ b/lang-guide/chapters/types/basic_types/closure.md @@ -10,7 +10,7 @@ Closures are used in Nu extensively as parameters to iteration style commands like `each`, `filter`, and `reduce`, to name but a few. A closure acts like a custom command that can be invoked either explicitly or by other commands. Closures can take parameters, return values and be passed to commands, either builtin or custom. -## Language Notes: +## Language Notes 1. A closure can be directly invoked using the [`do`](/commands/docs/do.md) command. @@ -106,3 +106,83 @@ Closures are used in Nu extensively as parameters to iteration style commands li - `update` - `upsert` - `zip` + +### Examples of using closures + +Here are a few select, concise examples to illustrate the broad use of closures with some of the aforementioned common Nushell commands: + +#### `each` – Applying a transformation + +The `each` command iterates over input, applying a closure to transform each item. + +```nu +[1 2 3] | each { |num| $num * 10 } +``` + +_Explanation:_ This takes a list of numbers. The closure `{|num| $num * 10}` is executed for each number (`num`), multiplying it by 10. + +**Output:** + +```nu +[10 20 30] +``` + +--- + +#### `where` – Filtering data + +The `where` command filters data based on a condition defined in a closure. The closure must return true (keep) or false (discard). + +```nu +ls | where { |file_info| $file_info.size > 1mb } +``` + +_Explanation:_ This lists files and then filters them. The closure `{|file_info| $file_info.size > 1mb}` checks if each file's size is greater than 1 megabyte. + +**Output:** + +```nu +# A table of files larger than 1MB +``` + +_Closure's role:_ Defines the operation to perform on every element. + +--- + +#### `sort-by` – Custom sorting logic + +The `sort-by` command sorts a list or table. The closure is used to extract or calculate the value to sort on for each item. + +```nu +["kiwi" "apple" "banana"] | sort-by { |fruit_name| $fruit_name | str length } +``` + +_Explanation:_ This sorts a list of fruit names. The closure `{|fruit_name| $fruit_name | str length}` calculates the length of each fruit name. `sort-by` then uses these lengths for sorting. + +**Output:** + +```nu +["kiwi" "apple" "banana"] # sorted by string length: kiwi (4), apple (5), banana (6) +``` + +_Closure's role:_ Specifies the attribute or derived value to use for comparison during sorting. + +--- + +#### `reduce` – Aggregating values + +The `reduce` command processes a list to accumulate a single result. The closure defines how to combine the current item with the accumulated value. + +```nu +[1 2 3 4] | reduce { |accumulator, current_value| $accumulator + $current_value } +``` + +_Explanation:_ This sums the numbers in the list. The closure `{|accumulator, current_value| $accumulator + $current_value}` adds the `current_value` to the `accumulator`. By default, the first item is the initial accumulator, and iteration starts from the second. + +**Output:** + +```nu +10 +``` + +_Closure's role:_ Defines the operation for combining elements into a single accumulated value. From 2e9a2067d3575588dfe8e750dfc57f468bfb5012 Mon Sep 17 00:00:00 2001 From: Raoul Kent Date: Thu, 5 Jun 2025 08:05:40 +0200 Subject: [PATCH 2/3] feature(make_docs.nu): adjust the input/output section generation now uses the data directly from help {command} to ensure that the table is fully populated by all input/output combinations. --- make_docs.nu | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/make_docs.nu b/make_docs.nu index 2c1fcb0642a..ade2896d818 100644 --- a/make_docs.nu +++ b/make_docs.nu @@ -1,4 +1,3 @@ - def plugin-paths [ nu_path?: path ] { const PLUGINS = [ nu_plugin_inc, @@ -243,10 +242,13 @@ $"## Notes # FIXME: Parentheses are required here to mutate $input_output, otherwise it won't work, maybe a bug? $input_output = ($input_output | append [[input output]; [$input $output]]) } - let in_out = if ($input_output | length) > 0 { - let markdown = ($input_output | sort-by input | to md --pretty | str replace -a '<' '\<' | str replace -a '>' '\>') - ['', '## Input/output types:', '', $markdown, ''] | str join (char newline) - } else { '' } + # Input/output types: use help commands + let input_output_table = help commands | where name == $command.name | get input_output | first | to md + let in_out = if ($input_output_table | is-empty) { + '' + } else { + ['', '## Input/output types:', '', $input_output_table, ''] | str join (char newline) + } let examples = if ($command.examples | length) > 0 { let example_top = $"## Examples(char newline)(char newline)" From 0677edb1d473b66eed0b5df5cc7923da5530f756 Mon Sep 17 00:00:00 2001 From: Raoul Kent Date: Fri, 6 Jun 2025 09:10:26 +0200 Subject: [PATCH 3/3] Update make_docs.nu Co-authored-by: 132ikl <132@ikl.sh> --- make_docs.nu | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/make_docs.nu b/make_docs.nu index ade2896d818..cf0e16a0793 100644 --- a/make_docs.nu +++ b/make_docs.nu @@ -243,7 +243,15 @@ $"## Notes $input_output = ($input_output | append [[input output]; [$input $output]]) } # Input/output types: use help commands - let input_output_table = help commands | where name == $command.name | get input_output | first | to md + let input_output_table = ( + help commands + | where name == $command.name + | get input_output + | first + | to md --pretty + | str replace -a '<' '<' + | str replace -a '>' '>' + ) let in_out = if ($input_output_table | is-empty) { '' } else {