nushell/crates/nu-std
Ian Manske 3d008e2c4e
Error on non-zero exit statuses (#13515)
# Description
This PR makes it so that non-zero exit codes and termination by signal
are treated as a normal `ShellError`. Currently, these are silent
errors. That is, if an external command fails, then it's code block is
aborted, but the parent block can sometimes continue execution. E.g.,
see #8569 and this example:
```nushell
[1 2] | each { ^false }
```

Before this would give:
```
╭───┬──╮
│ 0 │  │
│ 1 │  │
╰───┴──╯
```

Now, this shows an error:
```
Error: nu:🐚:eval_block_with_input

  × Eval block failed with pipeline input
   ╭─[entry #1:1:2]
 1 │ [1 2] | each { ^false }
   ·  ┬
   ·  ╰── source value
   ╰────

Error: nu:🐚:non_zero_exit_code

  × External command had a non-zero exit code
   ╭─[entry #1:1:17]
 1 │ [1 2] | each { ^false }
   ·                 ──┬──
   ·                   ╰── exited with code 1
   ╰────
```

This PR fixes #12874, fixes #5960, fixes #10856, and fixes #5347. This
PR also partially addresses #10633 and #10624 (only the last command of
a pipeline is currently checked). It looks like #8569 is already fixed,
but this PR will make sure it is definitely fixed (fixes #8569).

# User-Facing Changes
- Non-zero exit codes and termination by signal now cause an error to be
thrown.
- The error record value passed to a `catch` block may now have an
`exit_code` column containing the integer exit code if the error was due
to an external command.
- Adds new config values, `display_errors.exit_code` and
`display_errors.termination_signal`, which determine whether an error
message should be printed in the respective error cases. For
non-interactive sessions, these are set to `true`, and for interactive
sessions `display_errors.exit_code` is false (via the default config).

# Tests
Added a few tests.

# After Submitting
- Update docs and book.
- Future work:
- Error if other external commands besides the last in a pipeline exit
with a non-zero exit code. Then, deprecate `do -c` since this will be
the default behavior everywhere.
- Add a better mechanism for exit codes and deprecate
`$env.LAST_EXIT_CODE` (it's buggy).
2024-09-07 06:44:26 +00:00
..
src Error on non-zero exit statuses (#13515) 2024-09-07 06:44:26 +00:00
std Respect user-defined $env.NU_LOG_FORMAT and $env.NU_LOG_DATE_FORMAT (#13692) 2024-08-28 07:57:43 -05:00
tests don't show result in error make examples (#13296) 2024-07-05 07:17:07 -05:00
Cargo.toml Setup global cargo lint configuration (#13691) 2024-08-28 23:37:17 +02:00
CONTRIBUTING.md Surprising symlink resolution for std path add (#13258) 2024-06-28 18:11:48 -05:00
LICENSE add LICENSE to nu-std (#8803) 2023-04-07 13:39:21 -07:00
README.md Change the usage misnomer to "description" (#13598) 2024-08-22 12:02:08 +02:00
testing.nu Update PR template (#12838) 2024-05-13 08:45:44 -05:00

Welcome to the standard library of `nushell`!

The standard library is a pure-nushell collection of custom commands which provide interactive utilities and building blocks for users writing casual scripts or complex applications.

To see what's here:

> use std
> scope commands | select name description | where name =~ "std "
#┬───────────name────────────┬───────────────────description───────────────────
0│std assert                 │Universal assert command
1│std assert equal           │Assert $left == $right
2│std assert error           │Assert that executing the code generates an error
3│std assert greater         │Assert $left > $right
4│std assert greater or equal│Assert $left >= $right
             ...                                     ...
─┴───────────────────────────┴─────────────────────────────────────────────────

🧰 Using the standard library in the REPL or in scripts

All commands in the standard library must be "imported" into the running environment (the interactive read-execute-print-loop (REPL) or a .nu script) using the use command.

You can choose to import the whole module, but then must refer to individual commands with a std prefix, e.g:

use std

std log debug "Running now"
std assert (1 == 2)

Or you can enumerate the specific commands you want to import and invoke them without the std prefix.

use std ["log debug" assert]

log debug "Running again"
assert (2 == 1)

This is probably the form of import you'll want to add to your env.nu for interactive use.

✏️ contribute to the standard library

You're invited to contribute to the standard library! See CONTRIBUTING.md for details