I may have finally finished clirenesance.

This commit is contained in:
Gabe Venberg 2024-08-30 18:01:42 -05:00
parent f1146661b4
commit c3c5c434f5

View file

@ -213,8 +213,84 @@ but its an extremely usable IDE out of the box thanks to having all of its featu
### Helpful error messages
<!-- look at nushells error messages -->
When the user does do something wrong, it is vital to let them know exactly what, where, and how it went wrong,
and if at all possible, what action the user can do to fix it.
`Operation Failed`, `Error` or `syntax error` on their own are horrible error messages.
They tell you that something *somewhere* failed, giving almost no information the user can use to troubleshoot.
In the worst case, they can even point you in a completely different direction than what is actually needed to fix things.
Git is a good example of this. As much as I love git, sometimes its error messages are the opposite of helpful.
To borrow an example from [Julia Evans](https://jvns.ca/blog/2024/04/10/notes-on-git-error-messages/#git-checkout-asdf),
if you run `git checkout SomeNonExistantBranch`, you get:
`error: pathspec 'SomeNonexistantBranch` did not match any file(s) known to git`.
This is confusing because you are trying to checkout a branch, you arent thinking about files.
TODO [before](../nushell)
Another example, I covered [before](../nushell) is the contrast between Bash and Nushell.
Consider the following script:
{{<highlight sh "linenos=false">}}
$ for i in $(ls -l | tr -s " " | cut --fields=5 --delimiter=" "); do
echo "$i / 1000" | bc
done
{{</highlight>}}
This gets the sizes of all the files in KiB. But what if we typo the cut field?
{{<highlight sh "linenos=false">}}
$ for i in $(ls -l | tr -s " " | cut --fields=6 --delimiter=" "); do
echo "$i / 1000" | bc
done
(standard_in) 1: syntax error
(standard_in) 1: syntax error
(standard_in) 1: syntax error
(standard_in) 1: syntax error
(standard_in) 1: syntax error
(standard_in) 1: syntax error
(standard_in) 1: syntax error
(standard_in) 1: syntax error
(standard_in) 1: syntax error
{{</highlight>}}
Due to the syntax error coming from bc rather than bash directly,
even the line number it gives you is misleading,
and in order to have the slightest clue whats going on,
you have to start print debugging.
The equivalent in nushell would be:
{{<highlight sh "linenos=false">}}
> ls | get size | each {|item| $item / 1000}
{{</highlight>}}
and the equivilant error would be:
{{<highlight sh "linenos=false">}}
> ls | get type | each {|item| $item / 1000}
Error: nu::shell::eval_block_with_input
× Eval block failed with pipeline input
╭─[entry #5:1:1]
1 │ ls | get type | each {|item| $item / 1000}
· ─┬
· ╰── source value
╰────
Error: nu::shell::type_mismatch
× Type mismatch during operation.
╭─[entry #5:1:30]
1 │ ls | get type | each {|item| $item / 1000}
· ──┬── ┬ ──┬─
· │ │ ╰── int
· │ ╰── type mismatch for operator
· ╰── string
╰────
{{</highlight>}}
Though the first error isnt helpful, the second one tells us right away that `$item` is not what we expect it to be,
hopefully pointing us to the `get type` mistake.
Nushells error messages are miles ahead of other shells just...
being useful, helping you find where you made an error,
rather than just telling you theres an error *somewhere*.
### Concise and discoverable documentation
@ -325,9 +401,25 @@ allowing for more people to experiment with the design and ergonomics of CLI too
## Conclusion
TODO
<!-- emphasize that the new tools are not 'better' just because they are new,
but because they take the old tools and learn what did and did not work for them. -->
> If I have seen further than others, it is by standing on the shoulders of giants.
-- Isaac Newton, 1675
Once again, Id like to state that I am not advocating for shiny new tools *because* they are shiny and new.
Likewise, I dont think the old tools are *bad*, nor does their age alone count against them.
However, new tools have the opportunity to learn from their predecessors and build upon them.
In this way, the new tools are a tribute to those tools that came before;
a recognition of their strengths, an acknowledgement of their weaknesses.
Now, these new tools are not the be-all end-all of the command line interface.
Just because this new generation of tools improve on the old ones,
it does not mean they are themselves perfect.
As we use these tools, we will become familiar with them,
and we will discover their sharp edges,
or their common usecase will change,
or we develop a new usecase entirely.
And when these things happen, we will develop yet another generation of tools,
one further polished and adapted to new usecases.
## Appendix: the tools