search

nushell / nushell.github.io

Nushell's main website, blog, book, and more
https://www.nushell.sh/book/
MIT License
169 stars 416 forks source link

Issue with terminology in Thinking in Nu page #1221

Open TWSiO opened 8 months ago

TWSiO commented 8 months ago

In the "Nushell's environment is scoped" section of the Thinking in Nu page, it says that

In Nushell, blocks control their own environment. Changes to the environment are scoped to the block where they happen.

However, that's not really true for blocks technically, but it is for closures and command definitions. For example

if 1 > 0 { cd .. }

will change the current directory. You can also mutate other variables in blocks of course.

I've been trying to think up a good way to reword that section but I can't think of anything off the top of my head. It could say "commands and closures" rather than blocks, but that feels like it has less impact when talking about a significant design decision and might be a bit confusing before both concepts have really been introduced. I'm not sure there is a term or concept in Nushell at the moment that groups together commands and closures, but excludes blocks.

Anyone else have any ideas?

TWSiO commented 8 months ago

Just so we remember later, the same issue is also in this section: https://www.nushell.sh/book/environment.html#scoping

Kissaki commented 4 months ago

Also https://www.nushell.sh/lang-guide/chapters/variable_scope.html

Kissaki commented 4 months ago

Given the Block terminology definition you linked, it's certainly wrong.

There's no book or language ref docs on functions or commands specifically, but closure and function or command seem to be the correct terminology.

Maybe in this case we can simply evade using the general, wrong block terminology.

I think the docs should not only mention how env behaves, but contrast it.

Something like

In Nushell, closure and function blocks control their own environment. Changes to the environment are scoped to the block where they happen. Flow control blocks do not scope variables or the environment.

I wonder if it's even worth it to describe it like this, instead of a neutral general two-case description. But I guess it's because of the "thinking in nu" and headline.