Document how to alias subexpressions

[giggio]

Related problem

Docs should show how to alias subexpressions.

Describe the solution you'd like

For example:

alias nn = ^($env.HOME | path join bin n)

Describe alternatives you've considered

N/A

Additional context and details

No response

[hardfau1t]

This feature is recently removed in this release, now alias can't have pipes in it.

alternative would be to define a function like

def nn [] {
$env.HOME | path join bin n
}

[mksinicus]

do $closure will do

alias nn = do {$env.HOME | path join bin n}

[giggio]

@mksinicus

do $closure will do

alias nn = do {$env.HOME | path join bin n}

I just tried that, but when why run nn --help it is different from when I run $HOME/bin/n --help, it shows me help from do.
And when I run nn directly it just prints the path (expanded /home/<user>/bin/n).

[mksinicus]

@giggio

I just tried that, but when why run nn --help it is different from when I run $HOME/bin/n --help, it shows me help from do. And when I run nn directly it just prints the path (expanded /home/<user>/bin/n).

I see! So you wanted an "escape to the system", not aliasable subexpressions.

TL;DR: You can use

alias nn = ^($env.HOME | path join bin n)

That caret (^) interprets the string that follows it as a given path to an external call. For example ^$env.VISUAL starts your default visual editor in the current environment. (Unfortunately the usage of caret seems poorly documented in the link above)

[giggio]

Yes, that works. I don't get what the difference is, though.
For example, I aliased terraform to tf and it works just fine:

alias tf = terraform

I also noticed I can alias to the full path:

alias tf2 = /path/to/terraform

Then why do I need the ^ in the subexpression?

Also, I believe my original question is resolved, but I also think this information should be in the docs, as this is a common requirement, to alias to a dynamic path, like a subdir in the home directory.

[mksinicus]

Yes, that works. I don't get what the difference is, though.

Glad that worked!

The difference lies where Nushell tries to be a full-fledged programming language (cf. Thinking in Nu), with its data fully typed and flowing through the pipe in a structured manner. Therefore "path/to/terraform" is just a string and never a call. If you try alias tf = "/path/to/terraform" the shell gives you a warning. But alias tf = ^"/path/to/terraform" will pass, since the caret explicitly transforms the string into an external call.

The caret exists probably because Nushell wants to retain (some) compatibility with the POSIX-ish approach of putting executables in PATH. For example, Nushell has a builtin zip command, which definitely isn't what you want with zip in other shells. In cases like this, one has to use ^zip for the latter (or if one doesn't want to, hide zip first).

Also, I believe my original question is resolved, but I also think this information should be in the docs, as this is a common requirement, to alias to a dynamic path, like a subdir in the home directory.

Totally agree. I'd love to help with the docs, but I'm by no means familiar with the relevant source code 😢

Oh, and alias is a "parser keyword", so alias foo = bar is essentially different from let foo = bar. In the alias one bar could point to an internal or external call (in PATH), while in the let line bar is just a shorthand for "bar".

(Updated: In Nu 0.83 there can only be let foo = "bar". Now quotes are mandatory, otherwise it would be parsed as a command.)

[giggio]

@mksinicus I changed the title and description to make this an issue about docs.

[amtoine]

@giggio
when you say "an issue about docs", is that about the help pages of commands like alias or the book? 😋

[amtoine]

maybe this issue should be moved to https://github.com/nushell/nushell.github.io?

[giggio]

maybe this issue should be moved to nushell/nushell.github.io?

@amtoine yes, I agree. Is there a way to move automatically or we close it here and reopen it there?

[amtoine]

this is how it's done @giggio 😉