nushell / nushell/nushell.github.io

Confusing example on script definition order

Open
#1,163 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
258
Forks
561
Avg merge
3h 20m
Merged PRs (30d)
15

Description

Issue

I'm currently reading the book which claims that

there is no requirement that definitions have to come before the parts of the script that call the definitions [...]

while showing these scripts as examples of how definition order does not matter:

def greet [name] {
  ["hello" $name]
}

greet "world"
greet "world"

def greet [name] {
  ["hello" $name]
}

This choice of examples is a bit unfortunate in my opinion as, when running both scripts, they have different output.
My understanding is that this is caused by the last expression in a script being printed which evaluates to ["hello" "world"] and nothing respectively.
However, this confused me initially and I would expect this to trip up some other new users as well.

Possible improvements

  1. Changing the script to e.g.
def greet [name] {
  ["hello" $name]
}
greet "world" | null

or

def greet [name] {
  ["hello" $name]
}
let foo = greet "world"
$foo

would result in the same output when moving the command invocation line around but might raise other questions.

def greet [name] {
  ["hello" $name]
}
def greet-world [] {
  greet "world"
}
greet-world

and then moving the definition of greet-world to the top is probably the best example I can think of right now.

  1. Alternatively, the different output could be explained in a small note. I'm not even sure sure if the book explains the last expression of a script being printed up to that point. It's definitely explained in a note for functions but I don't remember reading that the same applies for scripts. I wouldn't rule out that I simply missed that part, though.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the scripts documentation page linked in the issue and review the definition-order examples alongside the surrounding explanation of script output. Update the example or add a note so the differing output is clearly explained when the invocation moves. Done means the documentation accurately demonstrates definition order without misleading newcomers.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.