From 84b014bd8a46fc5d29b901c22a38e28991e2d95e Mon Sep 17 00:00:00 2001
From: Jan Klass <kissaki@posteo.de>
Date: Wed, 16 Jul 2025 19:30:56 +0200
Subject: [PATCH] Reduce and focus closure command examples

In this section of the language reference we want to explore and demonstrate examples of variance of use.

The unnecessary layout separation (headlines, horizontal line separators) and command elaboration took away from that.
This change focuses the examples into demonstrating different closure use cases and behaviors in the context of commands.

It also adjusts the examples to have one code block with input and output.

It also improves some code examples, like the sort-by actually doing some sorting, demonstrating.

With the sometimes adjusted examples and documented output, the closure behavior does not need the redundant explanation.
---
 .../chapters/types/basic_types/closure.md     | 84 ++++++-------------
 1 file changed, 25 insertions(+), 59 deletions(-)

diff --git a/lang-guide/chapters/types/basic_types/closure.md b/lang-guide/chapters/types/basic_types/closure.md
index 6638e46e0f9..910f67c1182 100644
--- a/lang-guide/chapters/types/basic_types/closure.md
+++ b/lang-guide/chapters/types/basic_types/closure.md
@@ -111,78 +111,44 @@ Closures are used in Nu extensively as parameters to iteration style commands li
 
 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
+[1 2 3] | each {|num| $num * 10 }
+# => ╭───┬────╮
+# => │ 0 │ 10 │
+# => │ 1 │ 20 │
+# => │ 2 │ 30 │
+# => ╰───┴────╯
 ```
 
-_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.
+The `where` command filters data based on the result of a closure (true: keep, false: reject).
 
 ```nu
-["kiwi" "apple" "banana"] | sort-by { |fruit_name| $fruit_name | str length }
+1..100 | where {|num| $num > 80 and $num < 86 }
+# => ╭───┬────╮
+# => │ 0 │ 81 │
+# => │ 1 │ 82 │
+# => │ 2 │ 83 │
+# => │ 3 │ 84 │
+# => │ 4 │ 85 │
+# => ╰───┴────╯
 ```
 
-_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:**
+The `sort-by` command sorts a list or table. The closure determines and returns the sort key.
 
 ```nu
-["kiwi" "apple" "banana"] # sorted by string length: kiwi (4), apple (5), banana (6)
+["apple" "banana" "kiwi"] | sort-by {|fruit_name| $fruit_name | str length }
+# => ╭───┬────────╮
+# => │ 0 │ kiwi   │
+# => │ 1 │ apple  │
+# => │ 2 │ banana │
+# => ╰───┴────────╯
 ```
 
-_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.
+The `reduce` command processes a list to accumulate a single result. The closure defines how to combine the current item with the (intermediate) accumulated value.
 
 ```nu
-[1 2 3 4] | reduce { |accumulator, current_value| $accumulator + $current_value }
+[1 2 3 4] | reduce {|accumulator, current_value| $accumulator + $current_value }
+# => 10
 ```
-
-_Explanation:_ This sums the numbers in the list. The closure `{|current_value, accumulator| $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.