mirror of
https://github.com/nushell/nushell.git
synced 2025-06-30 06:30:08 +02:00
# Description <!-- Thank you for improving Nushell. Please, check our [contributing guide](../CONTRIBUTING.md) and talk to the core team before making major changes. Description of your pull request goes here. **Provide examples and/or screenshots** if your changes affect the user experience. --> Replaces #8824, which was languishing in review limbo and becoming increasingly difficult to keep current with upstream changes. In addition to all the edits, this PR includes updated documentation for running unit tests via `std run-tests`. # User-Facing Changes <!-- List of all changes that impact the user experience here. This helps us keep track of breaking changes. --> A CONTRIBUTING.md documenting guidelines and getting started info for potential stdlib contributors. # Tests + Formatting <!-- Don't forget to add tests that cover your changes. Make sure you've run and fixed any issues with these commands: - `cargo fmt --all -- --check` to check standard code formatting (`cargo fmt --all` applies these changes) - `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A clippy::needless_collect` to check that you're using the standard code style - `cargo test --workspace` to check that all tests pass - `cargo run -- crates/nu-std/tests/run.nu` to run the tests for the standard library > **Note** > from `nushell` you can also use the `toolkit` as follows > ```bash > use toolkit.nu # or use an `env_change` hook to activate it automatically > toolkit check pr > ``` --> # After Submitting <!-- If your PR had any user-facing changes, update [the documentation](https://github.com/nushell/nushell.github.io) after the PR is merged, if necessary. This will help us keep the docs up to date. -->
This commit is contained in:
@ -3,36 +3,48 @@
|
||||
<img src="https://media.giphy.com/media/hvRJCLFzcasrR4ia7z/giphy.gif" width="28"></img>
|
||||
</h1>
|
||||
|
||||
The standard library is a pure-`nushell` collection of commands to allow anyone to build
|
||||
complex applications using standardized tools gathered incrementally.
|
||||
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.
|
||||
|
||||
In this library, you might find `rust`-like `assert` commands to write tests, tools to
|
||||
manipulate paths and strings, etc, etc, ...
|
||||
|
||||
## :toolbox: use the standard library in the REPL or in scripts
|
||||
in order to "import" the standard library to either the interactive [*REPL*][REPL] of
|
||||
`nushell` or inside some `.nu` script, you might want to use the
|
||||
[`use`](https://nushell.sh/commands/docs/use.html) command!
|
||||
```bash
|
||||
use std
|
||||
To see what's here:
|
||||
```
|
||||
〉use std
|
||||
〉help commands | select name usage | where name =~ "std "
|
||||
╭────┬─────────────────────────────┬────────────────────────────────────────────────────────────────╮
|
||||
│ # │ name │ usage │
|
||||
│ 0 │ std assert │ Universal assert command │
|
||||
│ 1 │ std assert equal │ Assert $left == $right │
|
||||
. . .
|
||||
│ 11 │ std clip │ put the end of a pipe into the system clipboard. │
|
||||
│ 12 │ std dirs add │ Add one or more directories to the list. │
|
||||
. . .
|
||||
├────┼─────────────────────────────┼────────────────────────────────────────────────────────────────┤
|
||||
│ # │ name │ usage │
|
||||
╰────┴─────────────────────────────┴────────────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
## :toolbox: 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`](https://nushell.sh/commands/docs/use.html) 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.
|
||||
|
||||
## :pencil2: contribute to the standard library
|
||||
- all the commands of the standard_library are located in [`std.nu`](std.nu)
|
||||
- the tests are located in files that have a name starting with "test_", e.g. [`test_std.nu`](test_std.nu)
|
||||
- a test runner, at [`tests.nu`](tests.nu), allows to run all the tests automatically
|
||||
|
||||
### :wrench: add new commands
|
||||
- add new standard commands by appending to [`std.nu`](std.nu)
|
||||
- add associated tests to [`test_std.nu`](tests_std.nu) or preferably to `test_<submodule>.nu`.
|
||||
- define a new exported (!) `test_<feature>` command
|
||||
- import the `assert` functions you need at the top of the functions, e.g. `use std.nu "assert eq"`
|
||||
|
||||
### :test_tube: run the tests
|
||||
the following call should return no errors
|
||||
```bash
|
||||
NU_LOG_LEVEL=DEBUG cargo run -- -c "use std; std run-tests --path crates/nu-std"
|
||||
```
|
||||
|
||||
> **Warning**
|
||||
> the `cargo run --` part of this command is important to ensure the version of `nushell` and the version of the library are the same.
|
||||
You're invited to contribute to the standard library!
|
||||
See [CONTRIBUTING.md]([./CONTRIBUTING.md](https://github.com/nushell/nushell/blob/main/crates/nu-std/CONTRIBUTING.md))
|
||||
for details
|
||||
|
Reference in New Issue
Block a user