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

External argument

Description:A parameter that reads its argument the way an external command's argument is read
Annotation:external_arg
Literal syntax:None
Casts:N/A
See also:Custom Commands - Parameter types in the Book

Additional Language Notes

  1. Like path, external_arg is a "syntax shape" rather than a full type. It is meant for custom command parameters, where it changes how the argument is parsed:

    • A bare word keeps the exact text you typed. 0001, 5 and true aren't turned into an int or a bool. The value is a glob holding that text, so when you pass it on to an external command, a pattern such as *.md or a leading ~ is expanded there.
    • A quoted string stays a string, and isn't expanded.
    • A variable, subexpression or list literal keeps its own value and type.
    def show [x: external_arg] { [$x ($x | describe)] | to nuon }
    show 0001
    # => ["0001", glob]
    show "a b"
    # => ["a b", string]
    show (1 + 1)
    # => [2, int]

    An untyped parameter parses the same bare word as a number, so show-any 0001 with def show-any [x] { ... } receives the int 1.

  2. It is mainly useful for commands that hand their arguments to an external program, such as the main command of a script called from another shell, or a wrapper with a rest parameter. In a directory that holds README.md:

    def run-echo [...args: external_arg] { ^echo ...$args }
    run-echo 0001 *.md "*.md"
    # => 0001 README.md *.md

    Here the bare *.md matched README.md, while the quoted "*.md" was passed as written. The untyped rest parameter of a def --wrapped command reads bare words the same way, so 0001 keeps its text and a bare *.md is expanded when it reaches the external command. In that rest list, a bare word without glob characters is a string, not a glob, and a leading ~ or ... in it is already expanded, so ~/x arrives as /home/me/x (see Rest Parameters with Wrapped External Commands).

  3. On a variable, external_arg doesn't change how the value is parsed. It accepts any value, as any does, so a variable annotated this way behaves like an unannotated one:

    let e: external_arg = 0001
    $e | describe
    # => int
Edit this page on GitHub
Contributors: fdncred
Prev
Path