mirror of https://github.com/nushell/nushell synced 2024-12-29 06:23:11 +00:00

DOC: add a README to the standard library (#8304 )

# Description
this PR a `README` to the standard library in
`crates/nu-utils/standard_library/` 👍

> **Note**
> you can have a look at what the `README` looks like
[here](https://github.com/amtoine/nushell/blob/doc/add-a-readme-to-the-standard-library/crates/nu-utils/standard_library/README.md#--welcome-to-the-standard-library-of-nushell--)

# User-Facing Changes
the user can now access some documentation about the standard library. 

# Tests + Formatting
```
$nothing
```

# After Submitting
```
$nothing
```

2023-03-04 08:30:36 -06:00

2.5 KiB

Raw Blame History

Welcome to the standard library of `nushell`!

The standard library is a pure-nushell collection of commands to allow anyone to build complex applications using standardized tools gathered incrementally.

In this library, you might find rust-like assert commands to write tests, tools to manipulate paths and strings, etc, etc, ...

🧰 use the standard library in the REPL or in scripts

in order to "import" the standard library to either the interactive REPL of nushell or inside some .nu script, you might want to use the use command!

use /path/to/standard_library/std.nu

🔍 a concrete example

my name is @amtoine and i use the ghq tool to manage git projects

Note

ghq stores any repository inside $env.GHQ_ROOT under <host>/<owner>/<repo>/

the path to my local fork of nushell is then defined as

let-env NUSHELL_REPO = ($env.GHQ_ROOT | path join "github.com" "amtoine" "nushell")

and the full path to the standard library is defined as

let-env STD_LIB = ($env.NUSHELL_REPO | path join "crates" "nu-utils" "standard_library")

see the content of $env.STD_LIB 😋

>_ ls $env.STD_LIB | get name | str replace $env.STD_LIB "" | str trim -l -c "/"
╭───┬───────────╮
│ 0 │ README.md │
│ 1 │ std.nu    │
│ 2 │ tests.nu  │
╰───┴───────────╯

finally we can use the standard library and have access to the commands it exposes 👍

>_ use std.nu
>_ help std
Module: std

Exported commands:
  assert (std assert), assert eq (std assert eq), assert ne (std assert ne), match (std match)

This module does not export environment.

✏️ contribute to the standard library

🔧 add new commands

add new standard commands to std.nu
add associated tests to tests.nu
- define a new test_<feature> before the main
- import the assert functions you need at the top of the functions, e.g. use std.nu "assert eq"
- add a call to test_<feature> at the bottom of the main

🧪 run the tests

the following call should return nothing

nu ($env.STD_LIB | path join "tests.nu")

2.5 KiB Raw Blame History