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
Like
path,external_argis 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,5andtruearen't turned into an int or a bool. The value is aglobholding that text, so when you pass it on to an external command, a pattern such as*.mdor 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 0001withdef show-any [x] { ... }receives the int1.- A bare word keeps the exact text you typed.
It is mainly useful for commands that hand their arguments to an external program, such as the
maincommand of a script called from another shell, or a wrapper with a rest parameter. In a directory that holdsREADME.md:def run-echo [...args: external_arg] { ^echo ...$args } run-echo 0001 *.md "*.md" # => 0001 README.md *.mdHere the bare
*.mdmatchedREADME.md, while the quoted"*.md"was passed as written. The untyped rest parameter of adef --wrappedcommand reads bare words the same way, so0001keeps its text and a bare*.mdis expanded when it reaches the external command. In that rest list, a bare word without glob characters is astring, not aglob, and a leading~or...in it is already expanded, so~/xarrives as/home/me/x(see Rest Parameters with Wrapped External Commands).On a variable,
external_argdoesn't change how the value is parsed. It accepts any value, asanydoes, so a variable annotated this way behaves like an unannotated one:let e: external_arg = 0001 $e | describe # => int