Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
  • Language Reference Guide
    • Readme
    • Types in the Nu Language
      • Basic Types
        • Any
        • Number
        • Boolean
        • Integer
        • Float
        • Filesize
        • Duration
        • Datetime
        • Range
        • String
        • Record
        • List
        • Table
        • Closure
        • Nothing
        • Binary
        • Glob
        • Cell-Path
      • Other Data Types

        • Types used only in command signatures
          • Path
          • External argument
        • Types which are not declarable
          • Error
          • CustomValue
          • Block
      • Type signatures
      • Commands that interact with types
    • Operators
    • Flow control
      • if/else
      • loop
      • for
      • while
      • match
      • try/catch
      • break
      • return
      • continue
    • Filters
      • each and par-each
      • Filters to select subsets of data
      • where and filter
      • Understanding the difference between get and select
      • Adding and changing data
      • Summarizing and comparing lists
      • record commands
    • Matrices
    • Custom Commands
    • Declarations
    • Variable Scope
    • Strings and Text Formatting
    • Helpers and debugging commands
    • Pipelines
    • MIME Types for Nushell

for

for runs a block once for each item of a list, table, range or stream, with the item bound to a loop variable.

for <variable> in <value> { <block> }

See also: for command help and Control Flow - for in the Book.

for x in [1 2 3] { $x * $x | print }
# => 1
# => 4
# => 9

What for iterates over

Value after inIterations
A listOne for each item
A tableOne for each row, as a record
A range such as 1..5 or 1..One for each number the range produces
A list streamOne for each item, as the item arrives
nullNone
Any other valueOne, with the whole value (a record, a string, binary data)

Language Notes

  1. A record is a single value, so the loop runs once with the whole record. To loop over its fields, turn it into a table with transpose, or use items instead of for:

    for x in {name: nu, version: 117} { print ($x | describe) }
    # => record<name: string, version: int>
    let config = {name: nu, version: 117}
    for entry in ($config | transpose key value) {
      print $"($entry.key) = ($entry.value)"
    }
    # => name = nu
    # => version = 117
  2. A string, a number or binary data also runs the block once. null runs it zero times, so a value that may be missing needs no special case:

    for x in 42 { print $x }; for x in null { print "never runs" }
    # => 42
  3. for takes the items of a stream one at a time, as they are produced. The block finishes with each item before the next one is produced:

    for x in (1..3 | each {|i| print $"producing ($i)"; $i }) { print $"got ($x)" }
    # => producing 1
    # => got 1
    # => producing 2
    # => got 2
    # => producing 3
    # => got 3

    A range is not turned into a list first either, so a range without an end, such as 1.., works when the block leaves with break:

    for x in 1.. {
      if $x > 3 { break }
      print $x
    }
    # => 1
    # => 2
    # => 3
  4. The output of an external command is a byte stream, not a list. Split it with lines to loop over its lines. Without lines, the output goes straight to the terminal and the block doesn't run:

    for line in (^printf "a\nb\n" | lines) { print $"line: ($line)" }
    # => line: a
    # => line: b
  5. To get the index of each item as well, loop over the output of enumerate:

    for item in ([a b] | enumerate) { print $"($item.index): ($item.item)" }
    # => 0: a
    # => 1: b
  6. Like while and loop, for is a statement. It evaluates to nothing, the values of its block are discarded, and it can't be used in a pipeline. Its block can update mut variables from the enclosing scope, but the loop variable itself can't be assigned:

    mut total = 0
    for x in [1 2 3] { $total += $x }
    $total
    # => 6

    To collect a result for each item, use each, which is an expression. See Loops in the Book for when to choose each one.

Edit this page on GitHub
Contributors: fdncred
Prev
loop
Next
while