nushell / nushell/nushell.github.io
Confusing example on script definition order
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
- 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.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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