diff --git a/.github/workflows/command-block.yml b/.github/workflows/command-block.yml index 260c2a96803..704f9077090 100644 --- a/.github/workflows/command-block.yml +++ b/.github/workflows/command-block.yml @@ -1,12 +1,16 @@ name: Comment on manual command changes on: - pull_request: + pull_request_target: paths: - 'commands/docs/**' + - 'commands/categories/**' jobs: comment: runs-on: ubuntu-latest + # Maintainers/Contributors can add themselves exempt from this bot if they regularly run the command doc generation. + # If you are on this list, be careful about accidental changes! + if: ${{!contains(fromJSON('["hustcer", "sholderbach"]'), github.event.pull_request.user.login)}} steps: - uses: actions/github-script@v7.0.1 with: @@ -16,8 +20,13 @@ jobs: owner: context.repo.owner, repo: context.repo.repo, body: 'Awesome that you are trying to improve the documentation of a nushell command!\n\n' + - 'As we autogenerate these command pages from the help information defined with the command after each release:\n'+ - '- If you already updated the command help, you are already done!\n'+ - '- Else, please look for the command in the [source tree](https://github.com/nushell/nushell/tree/main/crates) and make your changes directly there.\n\n'+ + '**You should not modify the files in `commands/docs` or `commands/categories`!**\n' + + 'We autogenerate these command pages from the `help` information defined by the command implementation, after each release. Thus:\n'+ + '- If you already updated the command help, you are already done and can close this PR!\n'+ + '- Else, please look for the command in the [source tree](https://github.com/nushell/nushell/tree/main/crates) and make your changes directly there in the `impl Command` and `Signature`.\n'+ + '- If you accidentally made a change in `commands/` while working on general documentation, please revert changes to `commands/`\n\n'+ 'Thanks for helping out!' }) + - run: | + echo "This PR touched autogenerated command docs. If you are not a maintainer of the autogenerated docs, please revert changes to `commands/docs/**` and make the change on the nushell side" + exit 1 diff --git a/.vuepress/configs/sidebar/command_categories.ts b/.vuepress/configs/sidebar/command_categories.ts index b396886c265..53b047a60d4 100644 --- a/.vuepress/configs/sidebar/command_categories.ts +++ b/.vuepress/configs/sidebar/command_categories.ts @@ -10,6 +10,7 @@ export const commandCategories = [ '/commands/categories/date.md', '/commands/categories/debug.md', '/commands/categories/default.md', + '/commands/categories/deprecated.md', '/commands/categories/env.md', '/commands/categories/expression.md', '/commands/categories/filesystem.md', diff --git a/blog/2024-12-04-configuration_preview.md b/blog/2024-12-04-configuration_preview.md index f329933df97..08525adc936 100644 --- a/blog/2024-12-04-configuration_preview.md +++ b/blog/2024-12-04-configuration_preview.md @@ -14,7 +14,7 @@ Today, we're releasing two documentation items related to these changes: - A guide to upgrading your configuration to take advantage of the enhancements (below). This will also be linked from the 0.101 Release Notes when it becomes available. -- A [preview of the new Configuration chapter](/book/configuration_preview.md) of the Book. This chapter has been rewritten to match the new functionality, as well as add some previously missing documentation on features like autoload dirs (and more). Once 0.101 releases, this will replace the previous configuration chapter. We welcome reviews of the updates, and any corrections or enhancements can be submitted to [the doc repository](https://github.com/nushell/nushell.github.io) if needed. +- A [preview of the (now live) new Configuration chapter](/book/configuration) of the Book. This chapter has been rewritten to match the new functionality, as well as add some previously missing documentation on features like autoload dirs (and more). Once 0.101 releases, this will replace the previous configuration chapter. We welcome reviews of the updates, and any corrections or enhancements can be submitted to [the doc repository](https://github.com/nushell/nushell.github.io) if needed. --- @@ -126,8 +126,7 @@ $env.config.history = { - The commented, sample `default_env.nu` and `default_config.nu` in older releases was useful for learning about configuration options. Since these (long) files are no longer copied to the filesystem, you can access an enhanced version of this documentation using: ```nu - config env --sample | nu-highlight | less -R - config nu --sample | nu-highlight | less -R + config nu --doc | nu-highlight | less -R ``` - Skeleton config files (`env.nu` and `config.nu`) are automatically created when the default config directory is created. Usually this will be the first time Nushell is started. The user will no longer be asked whether or not to create the files. @@ -136,8 +135,6 @@ $env.config.history = { - An internal `default_env.nu` is loaded immediately before the user's `env.nu`. You can inspect its contents using `config env --default | nu-highlight | less -R`. - This means that, as with `config.nu`, you can also use your `env.nu` to just override the default environment variables if desired. - - Likewise, a `default_config.nu` is loaded immediately before the user's `config.nu`. View this file using `config nu --default | nu-highlight | less -R`. diff --git a/blog/2024-12-24-nushell_0_101_0.md b/blog/2024-12-24-nushell_0_101_0.md new file mode 100644 index 00000000000..27de5461a50 --- /dev/null +++ b/blog/2024-12-24-nushell_0_101_0.md @@ -0,0 +1,775 @@ +--- +title: Nushell 0.101.0 +author: The Nu Authors +author_site: https://twitter.com/nu_shell +author_image: https://www.nushell.sh/blog/images/nu_logo.png +excerpt: Today, we're releasing version 0.101.0 of Nu. This release adds a simplified startup configuration, several new commands, and additional tools to introspect the Nushell engine. +--- + + +# Nushell 0.101.0 + + +Today, we're releasing version 0.101.0 of Nu. This release adds a simplified startup configuration, several new commands, and additional tools to introspect the Nushell engine. + +# Where to get it + +Nushell 0.101.0 is available as [pre-built binaries](https://github.com/nushell/nushell/releases/tag/0.101.0) or from [crates.io](https://crates.io/crates/nu). If you have Rust installed, you can also install it using `cargo install nu`. + +As part of this release, we also publish a set of optional [plugins](/book/plugins.md) you can install and use with Nushell. + +# Table of contents + +- [_Highlights and themes of this release_](#highlights-and-themes-of-this-release-toc) + - [_Simplified Startup Configuration_](#simplified-startup-configuration-toc) + - [_Related Startup Config Changes_](#related-startup-config-changes-toc) + - [_Breaking Startup Config Changes_](#breaking-startup-config-changes-toc) +- [_Changes_](#changes-toc) + - [_Additions_](#additions-toc) + - [_`path self`_](#path-self-toc) + - [_`chunk-by`_](#chunk-by-toc) + - [_`term query`_](#term-query-toc) + - [_`merge deep`_](#merge-deep-toc) + - [_`utouch`_](#utouch-toc) + - [_WASM support_](#wasm-support-toc) + - [_`sys net` columns_](#sys-net-columns-toc) + - [_Raw string pattern matching_](#raw-string-pattern-matching-toc) + - [_Duration/Date Arithmetic_](#duration-date-arithmetic-toc) + - [_`explore` keybinds_](#explore-keybinds-toc) + - [_Version in Startup banner_](#version-in-startup-banner-toc) + - [_`input --default`_](#input-default-toc) + - [_PowerShell script invocation on Windows_](#powershell-script-invocation-on-windows-toc) + - [_New introspection tools_](#new-introspection-tools-toc) + - [_Breaking changes_](#breaking-changes-toc) + - [_`++` operator_](#operator-toc) + - [_Stricter command signature parsing_](#stricter-command-signature-parsing-toc) + - [_`group-by`_](#group-by-toc) + - [_`timeit`_](#timeit-toc) + - [_`sys cpu`_](#sys-cpu-toc) + - [_`from csv` and `from tsv`_](#from-csv-and-from-tsv-toc) + - [_`std/iter scan`_](#std-iter-scan-toc) + - [_Completion sorting_](#Completion-sorting-toc) + - [_Import module naming_](#import-module-naming-toc) + - [_`table` formatting and the `display_output` hook_](#table-formatting-and-the-display-output-hook-toc) + - [_`du` flag changes_](#du-flag-changes-toc) + - [_Code specific environment variables updated during `source`_](#code-specific-environment-variables-updated-during-source-toc) + - [_Deprecations_](#deprecations-toc) + - [_`split-by`_](#split-by-toc) + - [_`date to-record` and `date to-table`_](#date-to-record-and-date-to-table-toc) + - [_`do --ignore-shell-errors` and `--ignore-program-errors`_](#do-ignore-shell-errors-and-ignore-program-errors-toc) + - [_Removals_](#removals-toc) + - [_`NU_DISABLE_IR`_](#nu-disable-ir-toc) + - [_Bug fixes and other changes_](#bug-fixes-and-other-changes-toc) + - [_`ls`_](#ls-toc) + - [_`SHLVL`_](#shlvl-toc) + - [_`from` commands_](#from-commands-toc) + - [_Completions on custom commands_](#completions-on-custom-commands-toc) + - [_`seq char`_](#seq-char-toc) + - [_`http` multipart_](#http-multipart-toc) + - [_`scope variables`_](#scope-variables-toc) + - [_`help` system_](#help-system-toc) +- [_Notes for plugin developers_](#notes-for-plugin-developers-toc) +- [_Hall of fame_](#hall-of-fame-toc) +- [_Full changelog_](#full-changelog-toc) + + +# Highlights and themes of this release [[toc](#table-of-contents)] + +## Simplified Startup Configuration [[toc](#table-of-contents)] + +With [#14249](https://github.com/nushell/nushell/pull/14249), Nushell now always loads its internal `default_env.nu` before the user `env.nu` is loaded, then loads the internal `default_config.nu` before the user's `config.nu` is loaded. This allows for a simpler user-configuration experience. Details are in [this blog entry](https://www.nushell.sh/blog/2024-12-04-configuration_preview.html) along with an updated [Configuration Chapter](https://www.nushell.sh/book/configuration.html) which should go live sometime today. + +### Related Startup Config Changes [[toc](#table-of-contents)] + +- [#14345](https://github.com/nushell/nushell/pull/14345): Hooks fields are non-optional +- [#14341](https://github.com/nushell/nushell/pull/14341): Hooks now default to an empty value of the proper type (e.g., `[]` or `{}`) when not otherwise specified. This means that you can always safely append or merge a new hook without first needing to check if it was a valid list/record. +- [#14435](https://github.com/nushell/nushell/pull/14435): An `$env.config` is always created at startup, populated with default values, even when no configuration files are loaded. +- [#14549](https://github.com/nushell/nushell/pull/14549): The `const` version of `NU_LIB_DIRS` is now populated by default instead of `$env.NU_LIB_DIRS`. +- [#14553](https://github.com/nushell/nushell/pull/14553): The `const` version of `NU_PLUGIN_DIRS` is now populated by default instead of `$env.NU_PLUGIN_DIRS`. +- [#14566](https://github.com/nushell/nushell/pull/14566): `ENV_CONVERSIONS` is now an empty record by default. The `PATH`/`Path` conversions are handled internally. +- [#14579](https://github.com/nushell/nushell/pull/14579): More defaults are set in Rust. Also sets a default, empty `TRANSIENT_PROMPT_COMMAND_RIGHT` and `TRANSIENT_PROMPT_MULTILINE_INDICATOR`. + +### Breaking Startup Config Changes [[toc](#table-of-contents)] + +There may be (hopefully) minor breaking changes due to the startup configuration handling. Known possible issues include: + +- Cannot merge changes to default menus since their definitions are no longer in `config.nu` by default. Instead, the entire menu should be redefined. +- Querying the `$env.NU_LIB_DIRS` will return an empty result by default. Query the constant `$NU_LIB_DIRS` instead. + + + + +# Changes [[toc](#table-of-contents)] + +## Additions [[toc](#table-of-contents)] + +### `path self` [[toc](#table-of-contents)] + +Thanks to [@Bahex](https://github.com/Bahex) in [#14303](https://github.com/nushell/nushell/pull/14303), this release adds the `path self` command. `path self` is a parse-time only command for getting the absolute path of the source file containing it, or any file relative to the source file. + +```nushell +const this_file = path self +const this_directory = path self . +``` + +### `chunk-by` [[toc](#table-of-contents)] + +This release adds a new `chunk-by` command which will split a list into chunks based on a closure. The closure is applied to each element of the input list, and adjacent elements that share the same closure result value will be chunked together. This command was added in [#14410](https://github.com/nushell/nushell/pull/14410) thanks to [@cosineblast](https://github.com/cosineblast). + +```nu +# chunk by a predicate +[1 3 -2 -2 0 1 2] | chunk-by {|x| $x >= 0 } +# [[1 3] [-2 -2] [0 1 2]] + +# chunk duplicate, adjacent elements together +[a b b c a a] | chunk-by { $in } +# [[a] [b b] [c] [a a]] +``` + +### `term query` [[toc](#table-of-contents)] + +Thanks to [@Bahex](https://github.com/Bahex) in [#14427](https://github.com/nushell/nushell/pull/14427), this release adds the `term query` command. +`term query` allows sending a query to your terminal emulator and reading the reply. + +```nushell +# Get cursor position +term query (ansi cursor_position) --prefix (ansi csi) --terminator 'R' + +# Get terminal background color. +term query $'(ansi osc)10;?(ansi st)' --prefix $'(ansi osc)10;' --terminator (ansi st) + +# Read clipboard content on terminals supporting OSC-52. +term query $'(ansi osc)52;c;?(ansi st)' --prefix $'(ansi osc)52;c;' --terminator (ansi st) +``` + +### `merge deep` [[toc](#table-of-contents)] + +To merge nested record structures we now have `merge deep` as a subcommand of `merge` which only operates on the flat structure of tables. + +Here you can see how it is used to update a record with fields from a given record, by either adding the fields or replacing those leaf nodes that share a common cellpath. +```nushell +{a: {foo: 123 bar: "overwrite me"}, b: [1, 2, 3]} | merge deep {a: {bar: 456, baz: 789}, b: [4, 5, 6]} +# => ╭───┬───────────────╮ +# => │ │ ╭─────┬─────╮ │ +# => │ a │ │ foo │ 123 │ │ +# => │ │ │ bar │ 456 │ │ +# => │ │ │ baz │ 789 │ │ +# => │ │ ╰─────┴─────╯ │ +# => │ │ ╭───┬───╮ │ +# => │ b │ │ 0 │ 4 │ │ +# => │ │ │ 1 │ 5 │ │ +# => │ │ │ 2 │ 6 │ │ +# => │ │ ╰───┴───╯ │ +# => ╰───┴───────────────╯ +``` + +While the record entries get updated based on the path, by default lists at a given path are updated by replacement. + +`merge deep` also has different strategies for merging inner lists and tables. For example, you can use the `append` strategy to _merge_ the inner `b` list instead of overwriting it. + +```nushell +{a: {foo: 123 bar: "overwrite me"}, b: [1, 2, 3]} | merge deep --strategy=append {a: {bar: 456, baz: 789}, b: [4, 5, 6]} +# => ╭───┬───────────────╮ +# => │ │ ╭─────┬─────╮ │ +# => │ a │ │ foo │ 123 │ │ +# => │ │ │ bar │ 456 │ │ +# => │ │ │ baz │ 789 │ │ +# => │ │ ╰─────┴─────╯ │ +# => │ │ ╭───┬───╮ │ +# => │ b │ │ 0 │ 1 │ │ +# => │ │ │ 1 │ 2 │ │ +# => │ │ │ 2 │ 3 │ │ +# => │ │ │ 3 │ 4 │ │ +# => │ │ │ 4 │ 5 │ │ +# => │ │ │ 5 │ 6 │ │ +# => │ │ ╰───┴───╯ │ +# => ╰───┴───────────────╯ +``` + +This command is the work of a productive collaboration by [@132ikl](https://github.com/132ikl) and [@Bahex](https://github.com/Bahex). + +### `utouch` [[toc](#table-of-contents)] + +This release adds the new `utouch` command, utilizing uutils/coreutils! In addition to all the flags of `touch`, `utouch` also has a `--timestamp` and `--date` flag to specify the timestamp to use. Eventually, the `utouch` command will replace the `touch` command. + +### WASM support [[toc](#table-of-contents)] + +Nushell used to have WASM support a while back, but at some point became incompatible with WASM. Thanks to the amazing work of [@cptpiepmatz](https://github.com/cptpiepmatz) in [#14418](https://github.com/nushell/nushell/pull/14418), Nushell can now be compiled to WASM again! In order to do so, certain (cargo) features have to be disabled meaning certain commands (like filesystem commands) will not be available. + +### `sys net` columns [[toc](#table-of-contents)] + +Thanks to [@rfaulhaber](https://github.com/rfaulhaber) in [#14389](https://github.com/nushell/nushell/pull/14389), the `sys net` command now has two additional columns. One is the `mac` column which lists mac address. The other is the `ip` column which lists the address(es) for each network interface. + +### Raw string pattern matching [[toc](#table-of-contents)] + +With this release, raw strings can now be used as match patterns thanks to [@sgvictorino](https://github.com/sgvictorino) in [#14573](https://github.com/nushell/nushell/pull/14573). + +```nu +match 'foo' { + r#'foo'# => true + _ => false +} +``` + +### Duration/Date Arithmetic [[toc](#table-of-contents)] + +With [#14295](https://github.com/nushell/nushell/pull/14295), dates can now be added to durations. Previously only durations could be added to dates. + +### `explore` keybinds [[toc](#table-of-contents)] + +In [#14468](https://github.com/nushell/nushell/pull/14468) thanks to [@paulie4](https://github.com/paulie4), more default keybindings were added to `explore` to better match `less`. + +### Version in Startup banner [[toc](#table-of-contents)] + +With [#14625](https://github.com/nushell/nushell/pull/14625), the Nushell version now displays at startup in the banner. + +### `input --default` [[toc](#table-of-contents)] + +Thanks to [@WindSoilder](https://github.com/WindSoilder) in [#14374](https://github.com/nushell/nushell/pull/14374), the `input` command now has a `--default` parameter to set a default value when none is provided in the input. + +### PowerShell script invocation on Windows [[toc](#table-of-contents)] + +With [#14379](https://github.com/nushell/nushell/pull/14379) by [@fdncred](https://github.com/fdncred) we now launch PowerShell scripts with a `.ps1` extension directly through `powershell.exe`. This behavior follows the same logic we offer for scripts launched by `cmd.exe`. + +### New introspection tools [[toc](#table-of-contents)] + +[@fdncred](https://github.com/fdncred) added a series of new tools permitting you to inspect internals of Nushell's engine for better understanding or debugging. We hope you can put them to good use to drill down into bugs or to learn more how the Nushell engine understands a piece of code or represents your current state. As they refer to the engine internals we still want to actively evolve their output or behavior may change as we continue development. So don't depend on them in scripts but feel free to use them to diagnose issues or learn about the behavior of the current version. + +#### [`view source` now supports internal IDs](https://github.com/nushell/nushell/pull/14609) +To access the content of closures or other code `view source` can now accept an integer ID which represents the internal `BlockId` to access the code stored there. This is useful whenever our output provided you with ``. For closures stored in a variable you can still access it directly via `view source`. + +#### [`view blocks`](https://github.com/nushell/nushell/pull/14610) +This new commands lists the raw code blocks as stored in the engine after parsing including `block_id`, source code, and spans. + +#### [`ast --flatten`](https://github.com/nushell/nushell/pull/14400) +The `ast` command can now also output the flattened and simplified representation of the AST used by syntax highlighting and some of the completion logic. This is accessible through the `--flatten` flag. + +#### [`config flatten`](https://github.com/nushell/nushell/pull/14621) +To see the whole configuration in a simplified representation, especially to spot differences between different user configurations, `config flatten` provides a simplified view that is not nested like `$env.config`. Note that this output is not directly compatible with the config record and may not have the correct types. + +## Breaking changes [[toc](#table-of-contents)] + +### `++` operator [[toc](#table-of-contents)] + +The `++` operator previously performed both appending and concatenation. + +```nu +# Appending +[1 2 3] ++ 4 == [1 2 3 4] + +# Concatenation +[1 2 3] ++ [4 5 6] == [1 2 3 4 5 6] +``` + +This created ambiguity when operating on nested lists: + +```nu +[[1 2] [3 4]] ++ [5 6] +# Should this be [[1 2] [3 4] [5 6]] or [[1 2] [3 4] 5 6] ? +``` + +Additionally, the `++=` operator was able to change the type of a mutable a due to its dual role: + +```nu +mut str: string = 'hello ' +($str | describe) == string + +$str ++= ['world'] +($str | describe) == list +``` + +After [#14344](https://github.com/nushell/nushell/pull/14344), the `++` operator now only performs concatenation (between lists, strings, or binary values). To append a value to a list, either wrap the value in a list or use the `append` command. + +```nu +mut list = [1 2] +$list ++= [3] +$list = $list | append 4 +``` + + + +### Stricter command signature parsing [[toc](#table-of-contents)] + +#### Input/output types + +Previous versions of Nushell would fail to parse input/output types on custom commands in some cases. However, a parse error would not be shown, making these silent parse errors. + +```nu +# These input/output types are not valid, but no error would be shown: +def some_cmd [] -> string { '' } +def some_cmd [] : string { '' } + +# Since the input/output types failed to parse, then this code would fail only at runtime: +(some_cmd) + 1 +``` + +Thanks to [@ratherforky](https://github.com/ratherforky), this has been fixed in [#14510](https://github.com/nushell/nushell/pull/14510). Invalid input/output types will now cause an error to be shown at parse-time. + +``` +# The custom commands above will now cause a parse error and should instead be: +def some_cmd []: any -> string { '' } +def some_cmd [] : any -> string { '' } + +# This will now fail at parse-time due to type checking, before any user code is run: +(some_cmd) + 1 +``` + +#### Custom command arguments + +This release also makes the parsing for custom command arguments more strict thanks to +[@sgvictorino](https://github.com/sgvictorino) in [#14309](https://github.com/nushell/nushell/pull/14309). For example, a colon (`:`) without a corresponding type is now an error. Below are some more examples of code snippets which are now parse errors. + +``` +# expected parameter or flag +def foo [ bar: int: ] {} + +# expected type +def foo [ bar: = ] {} +def foo [ bar: ] {} + +# expected default value +def foo [ bar = ] {} +``` + +### `group-by` [[toc](#table-of-contents)] + +Thanks to [@Bahex](https://github.com/Bahex) in [#14337](https://github.com/nushell/nushell/pull/14337), the `group-by` command now supports grouping by multiple criteria (henceforth referred to as a grouper). When using multiple groupers, the output is in the form of nested records. + +```nu +let data = [ + [category color name]; + [fruit red apple] + [fruit red strawberry] + [vegetable red tomato] + [fruit orange orange] + [vegetable orange carrot] + [vegetable orange pumpkin] +] + +$data | group-by color category +``` + +``` +╭────────┬───────────────────────────────────────────────────────╮ +│ │ ╭───────────┬───────────────────────────────────────╮ │ +│ red │ │ │ ╭───┬──────────┬───────┬────────────╮ │ │ +│ │ │ fruit │ │ # │ category │ color │ name │ │ │ +│ │ │ │ ├───┼──────────┼───────┼────────────┤ │ │ +│ │ │ │ │ 0 │ fruit │ red │ apple │ │ │ +│ │ │ │ │ 1 │ fruit │ red │ strawberry │ │ │ +│ │ │ │ ╰───┴──────────┴───────┴────────────╯ │ │ +│ │ │ │ ╭───┬───────────┬───────┬────────╮ │ │ +│ │ │ vegetable │ │ # │ category │ color │ name │ │ │ +│ │ │ │ ├───┼───────────┼───────┼────────┤ │ │ +│ │ │ │ │ 0 │ vegetable │ red │ tomato │ │ │ +│ │ │ │ ╰───┴───────────┴───────┴────────╯ │ │ +│ │ ╰───────────┴───────────────────────────────────────╯ │ +│ │ ╭───────────┬──────────────────────────────────────╮ │ +│ orange │ │ │ ╭───┬──────────┬────────┬────────╮ │ │ +│ │ │ fruit │ │ # │ category │ color │ name │ │ │ +│ │ │ │ ├───┼──────────┼────────┼────────┤ │ │ +│ │ │ │ │ 0 │ fruit │ orange │ orange │ │ │ +│ │ │ │ ╰───┴──────────┴────────┴────────╯ │ │ +│ │ │ │ ╭───┬───────────┬────────┬─────────╮ │ │ +│ │ │ vegetable │ │ # │ category │ color │ name │ │ │ +│ │ │ │ ├───┼───────────┼────────┼─────────┤ │ │ +│ │ │ │ │ 0 │ vegetable │ orange │ carrot │ │ │ +│ │ │ │ │ 1 │ vegetable │ orange │ pumpkin │ │ │ +│ │ │ │ ╰───┴───────────┴────────┴─────────╯ │ │ +│ │ ╰───────────┴──────────────────────────────────────╯ │ +╰────────┴───────────────────────────────────────────────────────╯ +``` + +With the `--to-table` flag, instead of nested records, the output is in the form of a table with columns corresponding to each grouper and the `items` column. +Each column corresponding to a `grouper` is named after it. For closure groupers, the columns are named with the scheme `closure_{i}`. + +```nu +$data | group-by color category --to-table +``` + +``` +╭───┬────────┬───────────┬───────────────────────────────────────╮ +│ # │ color │ category │ items │ +├───┼────────┼───────────┼───────────────────────────────────────┤ +│ 0 │ red │ fruit │ ╭───┬──────────┬───────┬────────────╮ │ +│ │ │ │ │ # │ category │ color │ name │ │ +│ │ │ │ ├───┼──────────┼───────┼────────────┤ │ +│ │ │ │ │ 0 │ fruit │ red │ apple │ │ +│ │ │ │ │ 1 │ fruit │ red │ strawberry │ │ +│ │ │ │ ╰───┴──────────┴───────┴────────────╯ │ +│ 1 │ red │ vegetable │ ╭───┬───────────┬───────┬────────╮ │ +│ │ │ │ │ # │ category │ color │ name │ │ +│ │ │ │ ├───┼───────────┼───────┼────────┤ │ +│ │ │ │ │ 0 │ vegetable │ red │ tomato │ │ +│ │ │ │ ╰───┴───────────┴───────┴────────╯ │ +│ 2 │ orange │ fruit │ ╭───┬──────────┬────────┬────────╮ │ +│ │ │ │ │ # │ category │ color │ name │ │ +│ │ │ │ ├───┼──────────┼────────┼────────┤ │ +│ │ │ │ │ 0 │ fruit │ orange │ orange │ │ +│ │ │ │ ╰───┴──────────┴────────┴────────╯ │ +│ 3 │ orange │ vegetable │ ╭───┬───────────┬────────┬─────────╮ │ +│ │ │ │ │ # │ category │ color │ name │ │ +│ │ │ │ ├───┼───────────┼────────┼─────────┤ │ +│ │ │ │ │ 0 │ vegetable │ orange │ carrot │ │ +│ │ │ │ │ 1 │ vegetable │ orange │ pumpkin │ │ +│ │ │ │ ╰───┴───────────┴────────┴─────────╯ │ +╰───┴────────┴───────────┴───────────────────────────────────────╯ +``` + +### `timeit` [[toc](#table-of-contents)] + +The `timeit` command previously had a special behavior where expressions passed as arguments would have their evaluation deferred in order to later be timed. This lead to an interesting bug ([14401](https://github.com/nushell/nushell/issues/14401)) where the expression would be evaluated twice, since the new IR evaluator eagerly evaluates arguments passed to commands. + +To make the deferred evaluation more explicit, the `timeit` command can now only take a closure as an argument instead of any expression or value ([#14483](https://github.com/nushell/nushell/pull/14483)). Additionally, blocks are no longer supported by `timeit`, so any changes to the environment will be isolated to inside the closure. + +### `sys cpu` [[toc](#table-of-contents)] + +The `cpu_usage` column outputted by `sys cpu` works by sampling the CPU over a 400ms period. This wait long time is unhelpful if you are only interested in other information about the CPU like the number of cores (i.e., `sys cpu | length`). With [#14485](https://github.com/nushell/nushell/pull/14485), the `cpu_usage` column is now gated behind the `--long` flag. This way, `sys cpu` will take around 0-2ms instead of 400ms by default. + +### `from csv` and `from tsv` [[toc](#table-of-contents)] + +Thanks to [@Bahex](https://github.com/Bahex) in [#14399](https://github.com/nushell/nushell/pull/14399), parsing csv and tsv content with the `--flexible` flag is more flexible than before. Previously, the first row of csv or tsv content would determine the number of columns, and rows containing more values than the determined columns would be truncated, losing those extra values. + +With this release, that is no longer the case. Now, `--flexible` flag means the number of columns aren't limited by the first row and can have not just less but also more values than the first row. + +```csv +value +1,aaa +2,bbb +3 +4,ddd +5,eee,extra +``` + +```nu +.. | from csv --flexible --noheaders +``` + +``` +╭─#─┬─column0─┬─column1─┬─column2─╮ +│ 0 │ value │ ❎ │ ❎ │ +│ 1 │ 1 │ aaa │ ❎ │ +│ 2 │ 2 │ bbb │ ❎ │ +│ 3 │ 3 │ ❎ │ ❎ │ +│ 4 │ 4 │ ddd │ ❎ │ +│ 5 │ 5 │ eee │ extra │ +╰─#─┴─column0─┴─column1─┴─column2─╯ +``` + +### `std/iter scan` [[toc](#table-of-contents)] + +Thanks to [@Bahex](https://github.com/Bahex) in [#14596](https://github.com/nushell/nushell/pull/14596), the order of `scan`'s closure's parameters are flipped to be consistent with `reduce`. +The closure now also receives the accumulator value as pipeline input as well. + +```nushell +> [a b c d] | iter scan "" {|x, y| [$x, $y] | str join} -n +# To keep its behavior same, this command should be changed to either of the following +> [a b c d] | iter scan "" {|it, acc| [$acc, $it] | str join} -n +> [a b c d] | iter scan "" {|it| append $it | str join} -n +``` + +### Completion sorting [[toc](#table-of-contents)] + +In [#14424](https://github.com/nushell/nushell/pull/14424), some changes were made to completion sorting. If you have a custom completer that returns a record with an `options` field, then this may affect you. + +- If `options` contains `sort: true`, then completions will be sorted according to `$env.config.completions.sort`. Previously, they would have been sorted in alphabetical order. +- If `options` contains `sort: false`, completions will not be sorted. +- If `options` does not have a `sort` column, then that will be treated as `sort: true`. Previously, this would have been treated as `sort: false`. + +### Import module naming [[toc](#table-of-contents)] + +Thanks to [@sgvictorino](https://github.com/sgvictorino) in [#14353](https://github.com/nushell/nushell/pull/14353), modules with special characters in their name will be normalized by converting these special characters to underscores (`_`). Previously, it was not possible to use these modules after importing them. + +### `table` formatting and the `display_output` hook [[toc](#table-of-contents)] +With [#14361](https://github.com/nushell/nushell/pull/14361) by [@132ikl](https://github.com/132ikl) our machinery to format structured now follows a simpler logic. +If a `$env.config.hooks.display_output` hook is set, it is fully responsible for formatting the structured data, e.g. by invoking `table` with custom settings. Only if it is not set by `null` will `table` without arguments be run by default. +Previously the output logic would invoke `table` regardless on top of the formatting by your `display_output` hook. This avoids some spurious formatting attempts. + +### `du` flag changes [[toc](#table-of-contents)] + +Thanks to [@WindSoilder](https://github.com/WindSoilder) in [#14407](https://github.com/nushell/nushell/pull/14407), the `du` command shows a more condensed output by default. The `files` and (recursive) `directories` are not shown by default. Use `du --long (-l)` to show these columns. The `--all (-a)` switch has been removed -- Files and directories will both be shown with `--long (-l)`. + +### Code specific environment variables updated during `source` [[toc](#table-of-contents)] +The variables `$env.CURRENT_FILE` and `$env.FILE_PWD` had already been set to the respective file paths whenever a script was executed or module loaded. Similarly `$env.PROCESS_PATH` is set for the execution of a script or module but unset when a module is simply `use`d. + +With [#14486](https://github.com/nushell/nushell/pull/14486) by [@fdncred](https://github.com/fdncred) `$env.CURRENT_FILE` and `$env.FILE_PWD` will now also be updated when a particular file is included via `source`. Similarly `$env.PROCESS_PATH` will be unset. + +```nushell +# test_source.nu +print $"$env.CURRENT_FILE = ($env.CURRENT_FILE?)" +print $"$env.FILE_PWD = ($env.FILE_PWD?)" +print $"$env.PROCESS_PATH = ($env.PROCESS_PATH?)" +``` +``` nushell +source test_source.nu +# => $env.CURRENT_FILE = /Users/fdncred/src/nushell/test_source.nu +# => $env.FILE_PWD = /Users/fdncred/src/nushell +# => $env.PROCESS_PATH = +``` + +## Deprecations [[toc](#table-of-contents)] + +### `split-by` [[toc](#table-of-contents)] + +In [#14019](https://github.com/nushell/nushell/pull/14019), the `split-by` command was deprecated. Instead, please use `group-by` with multiple groupers [as shown above](#group-by-toc). + +### `date to-record` and `date to-table` [[toc](#table-of-contents)] + +In [#14319](https://github.com/nushell/nushell/pull/14319): + +- `date to-record` has been deprecated and will be removed in a future release. Please use `into record` in its place. +- `date to-table` has been deprecated and will be removed in a future release. Please use `into record | transpose | transpose -r` in its place. + +### `do --ignore-shell-errors` and `--ignore-program-errors` [[toc](#table-of-contents)] + +Thanks to [@WindSoilder](https://github.com/WindSoilder) in [#14385](https://github.com/nushell/nushell/pull/14385), `--ignore-shell-errors` and `--ignore-program-errors` for the `do` command have been deprecated. Use `--ignore-errors (-i)` instead. + +## Removals [[toc](#table-of-contents)] + +### `NU_DISABLE_IR` [[toc](#table-of-contents)] + +With [#14293](https://github.com/nushell/nushell/pull/14293), the `NU_DISABLE_IR` environment variable is no longer used. Nushell will now always use the new IR evaluator instead of previous AST based evaluator. + +## Bug fixes and other changes [[toc](#table-of-contents)] + +### `ls` [[toc](#table-of-contents)] + +The `ls` command used to have deterministic output order, but this was broken in 0.94.0. Thanks to [@userwiths](https://github.com/userwiths) in [#13875](https://github.com/nushell/nushell/pull/13875), `ls` output will now be sorted by the `name` column. Future changes to the order of `ls` will be a breaking change. + +Additionally, thanks to [@sgvictorino](https://github.com/sgvictorino) in [#14310](https://github.com/nushell/nushell/pull/14310), `ls` will now error if there are insufficient permissions to list the current working directory. Previously, `ls` would return empty output. + +### `SHLVL` [[toc](#table-of-contents)] + +When starting Nushell as an interactive REPL, Nushell will now increment the `SHLVL` environment variable. This change was made in [#14404](https://github.com/nushell/nushell/pull/14404) thanks to [@rikukiix](https://github.com/rikukiix). (Note that it is a known issue that `SHLVL` is still incremented on `exec`.) + +### `from` commands [[toc](#table-of-contents)] + +After [#14602](https://github.com/nushell/nushell/pull/14602), the `from` commands now remove the `content_type` pipeline metadata thanks to [@Bahex](https://github.com/Bahex). + +### Completions on custom commands [[toc](#table-of-contents)] + +Thanks to [@RobbingDaHood](https://github.com/RobbingDaHood) in [#14481](https://github.com/nushell/nushell/pull/14481), file completions are now triggered once again on custom commands after the first parameter. This was a regression due to the 0.99.x release. + +### `seq char` [[toc](#table-of-contents)] + +Thanks to [@anomius](https://github.com/anomius) in [#14261](https://github.com/nushell/nushell/pull/14261), `seq char` now works on any ASCII characters instead of only alphabetical ASCII characters. + +### `http` multipart [[toc](#table-of-contents)] + +The `http` commands now use CRLF when joining headers to match the HTTP specification. This change was made in [#14417](https://github.com/nushell/nushell/pull/14417) thanks to [@Beinsezii](https://github.com/Beinsezii). + +### `scope variables` [[toc](#table-of-contents)] + +`scope variables` now lists constant variables in scope (when using the IR evaluator) thanks to [@sgvictorino](https://github.com/sgvictorino in [#14577](https://github.com/nushell/nushell/pull/14577). + +### `help` system [[toc](#table-of-contents)] + +[@132ikl](https://github.com/132ikl) fixed a long standing issue in the help system, where commands with the same name but different module paths clashed. Now the `help ` correctly refers to the name of a command like it is visible in the scope through the definitions or `use` imports thanks to [#14490](https://github.com/nushell/nushell/pull/14490). + +# Notes for plugin developers [[toc](#table-of-contents)] + +As part of cleaning up we removed several enum variants actually unused in the core codebase: + +- `Type::ListStream` as the engine represents `PipelineData::ListStream` more consistently as `Type::List` +- `FlatShape::And`/`FlatShape::Or` as they are never populated. + +Furthermore `Value::Filesize` now stores its value in its own `Filesize` type instead of a bare `i64` to avoid confusion about the particular unit. + +# Hall of fame [[toc](#table-of-contents)] + +Thanks to all the contributors below for helping us solve issues, improve documentation, refactor code, and more! :pray: + +| author | title | link | +| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------- | +| [@132ikl](https://github.com/132ikl) | Change tests which may invoke externals to use non-conflicting names | [#14516](https://github.com/nushell/nushell/pull/14516) | +| [@132ikl](https://github.com/132ikl) | Make `glob` stream | [#14495](https://github.com/nushell/nushell/pull/14495) | +| [@Bahex](https://github.com/Bahex) | docs(reduce): add example demonstrating accumulator as pipeline input | [#14593](https://github.com/nushell/nushell/pull/14593) | +| [@Bahex](https://github.com/Bahex) | test(path self): Add tests | [#14607](https://github.com/nushell/nushell/pull/14607) | +| [@DziubaMaksym](https://github.com/DziubaMaksym) | fix: sample_config | [#14465](https://github.com/nushell/nushell/pull/14465) | +| [@Jasha10](https://github.com/Jasha10) | enable test_cp_recurse on macos | [#14358](https://github.com/nushell/nushell/pull/14358) | +| [@Kissaki](https://github.com/Kissaki) | Fix doc and code comment typos | [#14366](https://github.com/nushell/nushell/pull/14366) | +| [@PegasusPlusUS](https://github.com/PegasusPlusUS) | Fix unstable test case: One time my windows report drive letter as lowercase | [#14451](https://github.com/nushell/nushell/pull/14451) | +| [@PerchunPak](https://github.com/PerchunPak) | Fix issues in the example configs | [#14601](https://github.com/nushell/nushell/pull/14601) | +| [@alex-kattathra-johnson](https://github.com/alex-kattathra-johnson) | Shorten --max-time in tests and use a more stable error check | [#14494](https://github.com/nushell/nushell/pull/14494) | +| [@cptpiepmatz](https://github.com/cptpiepmatz) | Fix missing `installed_plugins` field in `version` command | [#14488](https://github.com/nushell/nushell/pull/14488) | +| [@cptpiepmatz](https://github.com/cptpiepmatz) | Fix `commands::network::http::*::*_timeout` tests on non-english system | [#14640](https://github.com/nushell/nushell/pull/14640) | +| [@maxim-uvarov](https://github.com/maxim-uvarov) | rewrite error message to not use the word `function` | [#14533](https://github.com/nushell/nushell/pull/14533) | +| [@sgvictorino](https://github.com/sgvictorino) | skip `test_iteration_errors` if `/root` is missing | [#14299](https://github.com/nushell/nushell/pull/14299) | +| [@sgvictorino](https://github.com/sgvictorino) | return accurate type errors from blocks/expressions in type unions | [#14420](https://github.com/nushell/nushell/pull/14420) | +| [@zhiburt](https://github.com/zhiburt) | nu-table/ Do footer_inheritance by accounting for rows rather then a f… | [#14380](https://github.com/nushell/nushell/pull/14380) | + +# Full changelog [[toc](#table-of-contents)] + +| author | title | link | +| ------ | ----- | ---- | +|[@132ikl](https://github.com/132ikl)|Rely on `display_output` hook for formatting values from evaluations|[#14361](https://github.com/nushell/nushell/pull/14361)| +|[@132ikl](https://github.com/132ikl)|Make length only operate on supported input types|[#14475](https://github.com/nushell/nushell/pull/14475)| +|[@132ikl](https://github.com/132ikl)|Add label rendering to try/catch rendered errors|[#14477](https://github.com/nushell/nushell/pull/14477)| +|[@132ikl](https://github.com/132ikl)|Change `help commands` to use name from scope instead of the name from the declaration|[#14490](https://github.com/nushell/nushell/pull/14490)| +|[@132ikl](https://github.com/132ikl)|Make `glob` stream|[#14495](https://github.com/nushell/nushell/pull/14495)| +|[@132ikl](https://github.com/132ikl)|Change tests which may invoke externals to use non-conflicting names|[#14516](https://github.com/nushell/nushell/pull/14516)| +|[@132ikl](https://github.com/132ikl)|Add `merge deep` command|[#14525](https://github.com/nushell/nushell/pull/14525)| +|[@132ikl](https://github.com/132ikl)|Remove grid icons deprecation warning|[#14526](https://github.com/nushell/nushell/pull/14526)| +|[@Bahex](https://github.com/Bahex)|Add `path self` command for getting absolute paths to files at parse time|[#14303](https://github.com/nushell/nushell/pull/14303)| +|[@Bahex](https://github.com/Bahex)|add multiple grouper support to `group-by`|[#14337](https://github.com/nushell/nushell/pull/14337)| +|[@Bahex](https://github.com/Bahex)|fix(group-by): re #14337 name collision prevention|[#14360](https://github.com/nushell/nushell/pull/14360)| +|[@Bahex](https://github.com/Bahex)|truly flexible csv/tsv parsing|[#14399](https://github.com/nushell/nushell/pull/14399)| +|[@Bahex](https://github.com/Bahex)|Add `term query`, for querying information from terminals.|[#14427](https://github.com/nushell/nushell/pull/14427)| +|[@Bahex](https://github.com/Bahex)|`term query`: refactor, add `--prefix` flag|[#14446](https://github.com/nushell/nushell/pull/14446)| +|[@Bahex](https://github.com/Bahex)|Propagate existing errors in insert and merge|[#14453](https://github.com/nushell/nushell/pull/14453)| +|[@Bahex](https://github.com/Bahex)|lsp and --ide-check fix for `path self` related diagnostics|[#14538](https://github.com/nushell/nushell/pull/14538)| +|[@Bahex](https://github.com/Bahex)|docs(reduce): add example demonstrating accumulator as pipeline input|[#14593](https://github.com/nushell/nushell/pull/14593)| +|[@Bahex](https://github.com/Bahex)|remove the deprecated index argument from filter commands' closure signature|[#14594](https://github.com/nushell/nushell/pull/14594)| +|[@Bahex](https://github.com/Bahex)|`std/iter scan`: change closure signature to be consistent with `reduce`|[#14596](https://github.com/nushell/nushell/pull/14596)| +|[@Bahex](https://github.com/Bahex)|remove `content_type` metadata from pipeline after `from ...` commands|[#14602](https://github.com/nushell/nushell/pull/14602)| +|[@Bahex](https://github.com/Bahex)|test(path self): Add tests|[#14607](https://github.com/nushell/nushell/pull/14607)| +|[@Beinsezii](https://github.com/Beinsezii)|command/http/client use CRLF for headers join instead of LF|[#14417](https://github.com/nushell/nushell/pull/14417)| +|[@DziubaMaksym](https://github.com/DziubaMaksym)|fix: sample_config|[#14465](https://github.com/nushell/nushell/pull/14465)| +|[@IanManske](https://github.com/IanManske)|Deprecate `split-by` command|[#14019](https://github.com/nushell/nushell/pull/14019)| +|[@IanManske](https://github.com/IanManske)|Change append operator to concatenation operator|[#14344](https://github.com/nushell/nushell/pull/14344)| +|[@IanManske](https://github.com/IanManske)|Make `Hooks` fields non-optional to match the new config defaults|[#14345](https://github.com/nushell/nushell/pull/14345)| +|[@IanManske](https://github.com/IanManske)|Add `Filesize` type|[#14369](https://github.com/nushell/nushell/pull/14369)| +|[@IanManske](https://github.com/IanManske)|Remove `ListStream` type|[#14425](https://github.com/nushell/nushell/pull/14425)| +|[@IanManske](https://github.com/IanManske)|Make `timeit` take only closures as an argument|[#14483](https://github.com/nushell/nushell/pull/14483)| +|[@IanManske](https://github.com/IanManske)|Remove duplicate implementations of `CallExt::rest`|[#14484](https://github.com/nushell/nushell/pull/14484)| +|[@IanManske](https://github.com/IanManske)|Add `--long` flag for `sys cpu`|[#14485](https://github.com/nushell/nushell/pull/14485)| +|[@Jasha10](https://github.com/Jasha10)|enable test_cp_recurse on macos|[#14358](https://github.com/nushell/nushell/pull/14358)| +|[@Kissaki](https://github.com/Kissaki)|Fix doc and code comment typos|[#14366](https://github.com/nushell/nushell/pull/14366)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Load `default_env.nu`/`default_config.nu` before user `env.nu`/`config.nu`|[#14249](https://github.com/nushell/nushell/pull/14249)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Allow date to be added to duration|[#14295](https://github.com/nushell/nushell/pull/14295)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Deprecate `date to-record` and `date to-table`|[#14319](https://github.com/nushell/nushell/pull/14319)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Add proper config defaults for hooks|[#14341](https://github.com/nushell/nushell/pull/14341)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Fix small typos in std/dirs|[#14422](https://github.com/nushell/nushell/pull/14422)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Always populate config record during startup|[#14435](https://github.com/nushell/nushell/pull/14435) +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Remove long-unused `autoenv` tests|[#14436](https://github.com/nushell/nushell/pull/14436)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Add example for PROMPT_COMMAND_RIGHT|[#14439](https://github.com/nushell/nushell/pull/14439)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Bump reedline to current main|[#14455](https://github.com/nushell/nushell/pull/14455)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Update default-files README|[#14461](https://github.com/nushell/nushell/pull/14461)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Allow inherited environment variables|[#14467](https://github.com/nushell/nushell/pull/14467)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Only run `from_string` conversion on strings|[#14509](https://github.com/nushell/nushell/pull/14509)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Use const NU_LIB_DIRS in startup|[#14549](https://github.com/nushell/nushell/pull/14549)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Allow both NU_PLUGIN_DIRS const and env at the same time|[#14553](https://github.com/nushell/nushell/pull/14553)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Set empty `ENV_CONVERSIONS` record by default|[#14566](https://github.com/nushell/nushell/pull/14566)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Update sample and scaffold files|[#14568](https://github.com/nushell/nushell/pull/14568)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Moves additional env vars out of default_env and updates some transient prompt vars|[#14579](https://github.com/nushell/nushell/pull/14579)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Add missing color_config settings|[#14603](https://github.com/nushell/nushell/pull/14603)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Doc file fixes|[#14608](https://github.com/nushell/nushell/pull/14608)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Remove duplicate version line|[#14611](https://github.com/nushell/nushell/pull/14611)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Add version info to startup banner|[#14625](https://github.com/nushell/nushell/pull/14625)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Add shape_garbage|[#14626](https://github.com/nushell/nushell/pull/14626)| +|[@NotTheDr01ds](https://github.com/NotTheDr01ds)|Set `split-by` doc category to "deprecated"|[#14633](https://github.com/nushell/nushell/pull/14633)| +|[@PegasusPlusUS](https://github.com/PegasusPlusUS)|Feature: PWD-per-drive to facilitate working on multiple drives at Windows|[#14411](https://github.com/nushell/nushell/pull/14411)| +|[@PegasusPlusUS](https://github.com/PegasusPlusUS)|Fix unstable test case: One time my windows report drive letter as lowercase|[#14451](https://github.com/nushell/nushell/pull/14451)| +|[@PerchunPak](https://github.com/PerchunPak)|Fix issues in the example configs|[#14601](https://github.com/nushell/nushell/pull/14601)| +|[@RobbingDaHood](https://github.com/RobbingDaHood)|#14238 Now the file completion is triggered on a custom command after the first parameter.|[#14481](https://github.com/nushell/nushell/pull/14481)| +|[@RobbingDaHood](https://github.com/RobbingDaHood)|For `#` to start a comment, then it either need to be the first chara…|[#14562](https://github.com/nushell/nushell/pull/14562)| +|[@WindSoilder](https://github.com/WindSoilder)|Tests: add a test to make sure that function can't use mutable variable|[#14314](https://github.com/nushell/nushell/pull/14314)| +|[@WindSoilder](https://github.com/WindSoilder)|make std help more user friendly|[#14347](https://github.com/nushell/nushell/pull/14347)| +|[@WindSoilder](https://github.com/WindSoilder)|add `--default` flag to input command|[#14374](https://github.com/nushell/nushell/pull/14374) +|[@WindSoilder](https://github.com/WindSoilder)|deprecate --ignore-shell-errors and --ignore-program-errors in `do` |[#14385](https://github.com/nushell/nushell/pull/14385)| +|[@WindSoilder](https://github.com/WindSoilder)|remove deprecated warnings|[#14386](https://github.com/nushell/nushell/pull/14386)| +|[@WindSoilder](https://github.com/WindSoilder)|raise ParseError if assign to a non-variable or non-mutable-variable|[#14405](https://github.com/nushell/nushell/pull/14405)| +|[@WindSoilder](https://github.com/WindSoilder)|du: add `-l/--long` flag, remove `-a/--all` flag|[#14407](https://github.com/nushell/nushell/pull/14407)| +|[@WindSoilder](https://github.com/WindSoilder)|update miette to 7.3|[#14454](https://github.com/nushell/nushell/pull/14454)| +|[@WindSoilder](https://github.com/WindSoilder)|update unicode-width to 0.2|[#14456](https://github.com/nushell/nushell/pull/14456)| +|[@WindSoilder](https://github.com/WindSoilder)|run `cargo update` manually to update dependencies|[#14569](https://github.com/nushell/nushell/pull/14569)| +|[@WindSoilder](https://github.com/WindSoilder)|update shadow-rs to 0.37|[#14617](https://github.com/nushell/nushell/pull/14617)| +|[@WindSoilder](https://github.com/WindSoilder)|Remove `-a/-all` flag in du.|[#14618](https://github.com/nushell/nushell/pull/14618)| +|[@alex-kattathra-johnson](https://github.com/alex-kattathra-johnson)|Shorten --max-time in tests and use a more stable error check|[#14494](https://github.com/nushell/nushell/pull/14494)| +|[@amtoine](https://github.com/amtoine)|add `from ndnuon` and `to ndnuon` to stdlib|[#14334](https://github.com/nushell/nushell/pull/14334)| +|[@amtoine](https://github.com/amtoine)|fix multiline strings in NDNUON|[#14519](https://github.com/nushell/nushell/pull/14519)| +|[@anomius](https://github.com/anomius)|Seq char update will work on all char|[#14261](https://github.com/nushell/nushell/pull/14261)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump crate-ci/typos from 1.27.0 to 1.27.3|[#14321](https://github.com/nushell/nushell/pull/14321)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump serial_test from 3.1.1 to 3.2.0|[#14325](https://github.com/nushell/nushell/pull/14325)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump tempfile from 3.13.0 to 3.14.0|[#14326](https://github.com/nushell/nushell/pull/14326)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump mockito from 1.5.0 to 1.6.1|[#14336](https://github.com/nushell/nushell/pull/14336)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump terminal_size from 0.3.0 to 0.4.0|[#14393](https://github.com/nushell/nushell/pull/14393)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump thiserror from 1.0.69 to 2.0.3|[#14394](https://github.com/nushell/nushell/pull/14394)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump shadow-rs from 0.35.2 to 0.36.0|[#14396](https://github.com/nushell/nushell/pull/14396)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump crate-ci/typos from 1.27.3 to 1.28.1|[#14447](https://github.com/nushell/nushell/pull/14447)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump crate-ci/typos from 1.28.1 to 1.28.2|[#14503](https://github.com/nushell/nushell/pull/14503)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump indexmap from 2.6.0 to 2.7.0|[#14505](https://github.com/nushell/nushell/pull/14505)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump multipart-rs from 0.1.11 to 0.1.13|[#14506](https://github.com/nushell/nushell/pull/14506)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump ureq from 2.10.1 to 2.12.0|[#14507](https://github.com/nushell/nushell/pull/14507)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump bytes from 1.8.0 to 1.9.0|[#14508](https://github.com/nushell/nushell/pull/14508)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump scraper from 0.21.0 to 0.22.0|[#14557](https://github.com/nushell/nushell/pull/14557)| +|[@app/dependabot](https://github.com/app/dependabot)|Bump crate-ci/typos from 1.28.2 to 1.28.4|[#14614](https://github.com/nushell/nushell/pull/14614)| +|[@ayax79](https://github.com/ayax79)|Add support for converting polars decimal values to nushell values|[#14343](https://github.com/nushell/nushell/pull/14343)| +|[@ayax79](https://github.com/ayax79)|Upgrading to polars 0.44|[#14478](https://github.com/nushell/nushell/pull/14478)| +|[@ayax79](https://github.com/ayax79)|Convert Filesize to Int|[#14491](https://github.com/nushell/nushell/pull/14491)| +|[@ayax79](https://github.com/ayax79)|Documentation and error handling around `polars with-column --name`|[#14527](https://github.com/nushell/nushell/pull/14527)| +|[@ayax79](https://github.com/ayax79)|Improve handling of columns with null values|[#14588](https://github.com/nushell/nushell/pull/14588)| +|[@ayax79](https://github.com/ayax79)|Added flag --coalesce-columns to allow columns to be coalesced on full joins|[#14578](https://github.com/nushell/nushell/pull/14578)| +|[@cosineblast](https://github.com/cosineblast)|Implement chunk_by operation|[#14410](https://github.com/nushell/nushell/pull/14410)| +|[@cptpiepmatz](https://github.com/cptpiepmatz)|Start to Add WASM Support Again|[#14418](https://github.com/nushell/nushell/pull/14418)| +|[@cptpiepmatz](https://github.com/cptpiepmatz)|Fix missing `installed_plugins` field in `version` command|[#14488](https://github.com/nushell/nushell/pull/14488)| +|[@cptpiepmatz](https://github.com/cptpiepmatz)|Fix `table` command when targeting WASM|[#14530](https://github.com/nushell/nushell/pull/14530)| +|[@cptpiepmatz](https://github.com/cptpiepmatz)|Expose "to html" command|[#14536](https://github.com/nushell/nushell/pull/14536)| +|[@cptpiepmatz](https://github.com/cptpiepmatz)|Fix `commands::network::http::*::*_timeout` tests on non-english system|[#14640](https://github.com/nushell/nushell/pull/14640)| +|[@devyn](https://github.com/devyn)|Remove the `NU_DISABLE_IR` option|[#14293](https://github.com/nushell/nushell/pull/14293)| +|[@devyn](https://github.com/devyn)|Turn compile errors into fatal errors|[#14388](https://github.com/nushell/nushell/pull/14388)| +|[@fdncred](https://github.com/fdncred)|allow nuscripts to be run again on windows with assoc/ftype|[#14318](https://github.com/nushell/nushell/pull/14318)| +|[@fdncred](https://github.com/fdncred)|fix ansi bleed over on right prompt|[#14357](https://github.com/nushell/nushell/pull/14357)| +|[@fdncred](https://github.com/fdncred)|update uutils crates|[#14371](https://github.com/nushell/nushell/pull/14371)| +|[@fdncred](https://github.com/fdncred)|allow ps1 files to be executed without pwsh/powershell -c file.ps1|[#14379](https://github.com/nushell/nushell/pull/14379)| +|[@fdncred](https://github.com/fdncred)|add function to make env vars case-insensitive|[#14390](https://github.com/nushell/nushell/pull/14390)| +|[@fdncred](https://github.com/fdncred)|add new --flatten parameter to the ast command|[#14400](https://github.com/nushell/nushell/pull/14400)| +|[@fdncred](https://github.com/fdncred)|remove `terminal_size` crate everywhere it makes sense|[#14423](https://github.com/nushell/nushell/pull/14423)| +|[@fdncred](https://github.com/fdncred)|update rust toolchain to rust 1.81.0|[#14473](https://github.com/nushell/nushell/pull/14473)| +|[@fdncred](https://github.com/fdncred)|Add environment variables for sourced files|[#14486](https://github.com/nushell/nushell/pull/14486)| +|[@fdncred](https://github.com/fdncred)|allow `select` to stream more|[#14492](https://github.com/nushell/nushell/pull/14492)| +|[@fdncred](https://github.com/fdncred)|add file column to `scope modules` output|[#14524](https://github.com/nushell/nushell/pull/14524)| +|[@fdncred](https://github.com/fdncred)|update to reedline 9eb3c2d|[#14541](https://github.com/nushell/nushell/pull/14541)| +|[@fdncred](https://github.com/fdncred)|fix 64-bit hex number parsing|[#14571](https://github.com/nushell/nushell/pull/14571)| +|[@fdncred](https://github.com/fdncred)|tweak polars join for better cross joins|[#14586](https://github.com/nushell/nushell/pull/14586)| +|[@fdncred](https://github.com/fdncred)|allow `view source` to take `int` as a parameter|[#14609](https://github.com/nushell/nushell/pull/14609)| +|[@fdncred](https://github.com/fdncred)|add `view blocks` command|[#14610](https://github.com/nushell/nushell/pull/14610)| +|[@fdncred](https://github.com/fdncred)|add `config flatten` command|[#14621](https://github.com/nushell/nushell/pull/14621)| +|[@fdncred](https://github.com/fdncred)|better error handling for `view source`|[#14624](https://github.com/nushell/nushell/pull/14624)| +|[@fdncred](https://github.com/fdncred)|lookup closures/blockids and get content in `config flatten`|[#14635](https://github.com/nushell/nushell/pull/14635)| +|[@fdncred](https://github.com/fdncred)|tweaks to `config flatten`|[#14639](https://github.com/nushell/nushell/pull/14639)| +|[@hustcer](https://github.com/hustcer)|Bump to dev version 0.100.1|[#14328](https://github.com/nushell/nushell/pull/14328)| +|[@hustcer](https://github.com/hustcer)|Fix the document CI error for `polars profile` command|[#14642](https://github.com/nushell/nushell/pull/14642)| +|[@maxim-uvarov](https://github.com/maxim-uvarov)|rewrite error message to not use the word `function`|[#14533](https://github.com/nushell/nushell/pull/14533)| +|[@michel-slm](https://github.com/michel-slm)|Bump quick-xml to 0.37.0|[#14354](https://github.com/nushell/nushell/pull/14354)| +|[@michel-slm](https://github.com/michel-slm)|Bump titlecase dependency|[#14502](https://github.com/nushell/nushell/pull/14502)| +|[@musicinmybrain](https://github.com/musicinmybrain)|Update rstest from 0.18 to 0.23 (the current version)|[#14350](https://github.com/nushell/nushell/pull/14350)| +|[@musicinmybrain](https://github.com/musicinmybrain)|Update procfs and which dependencies to their latest releases|[#14489](https://github.com/nushell/nushell/pull/14489)| +|[@musicinmybrain](https://github.com/musicinmybrain)|Update roxmltree from 0.19 to 0.20, the latest version|[#14513](https://github.com/nushell/nushell/pull/14513)| +|[@paulie4](https://github.com/paulie4)|`explore`: add more `less` key bindings and add `Transition::None`|[#14468](https://github.com/nushell/nushell/pull/14468)| +|[@ratherforky](https://github.com/ratherforky)|Fix silent failure of parsing input output types|[#14510](https://github.com/nushell/nushell/pull/14510)| +|[@rfaulhaber](https://github.com/rfaulhaber)|Add mac and IP address entries to `sys net`|[#14389](https://github.com/nushell/nushell/pull/14389)| +|[@rikukiix](https://github.com/rikukiix)|Update SHLVL (only when interactive) on startup|[#14404](https://github.com/nushell/nushell/pull/14404)| +|[@schrieveslaach](https://github.com/schrieveslaach)|Bump Calamine|[#14403](https://github.com/nushell/nushell/pull/14403)| +|[@sgvictorino](https://github.com/sgvictorino)|skip `test_iteration_errors` if `/root` is missing|[#14299](https://github.com/nushell/nushell/pull/14299)| +|[@sgvictorino](https://github.com/sgvictorino)|make command signature parsing more strict|[#14309](https://github.com/nushell/nushell/pull/14309)| +|[@sgvictorino](https://github.com/sgvictorino)|make `ls` return "Permission denied" for CWD instead of empty results|[#14310](https://github.com/nushell/nushell/pull/14310)| +|[@sgvictorino](https://github.com/sgvictorino)|normalize special characters in module names to allow variable access|[#14353](https://github.com/nushell/nushell/pull/14353)| +|[@sgvictorino](https://github.com/sgvictorino)|return accurate type errors from blocks/expressions in type unions|[#14420](https://github.com/nushell/nushell/pull/14420)| +|[@sgvictorino](https://github.com/sgvictorino)|support raw strings in match patterns|[#14573](https://github.com/nushell/nushell/pull/14573)| +|[@sgvictorino](https://github.com/sgvictorino)|return const values from `scope variables`|[#14577](https://github.com/nushell/nushell/pull/14577)| +|[@sholderbach](https://github.com/sholderbach)|Cut down unnecessary lint allows|[#14335](https://github.com/nushell/nushell/pull/14335)| +|[@sholderbach](https://github.com/sholderbach)|Remove unused `FlatShape`s `And`/`Or`|[#14476](https://github.com/nushell/nushell/pull/14476)| +|[@sholderbach](https://github.com/sholderbach)|Add `remove` as a search term on `drop` commands|[#14493](https://github.com/nushell/nushell/pull/14493)| +|[@sholderbach](https://github.com/sholderbach)|Improve `sleep` example using multiple durations|[#14520](https://github.com/nushell/nushell/pull/14520)| +|[@sholderbach](https://github.com/sholderbach)|Remove unused `sample_login.nu` file|[#14632](https://github.com/nushell/nushell/pull/14632)| +|[@sholderbach](https://github.com/sholderbach)|Remove `pub` on some command internals|[#14636](https://github.com/nushell/nushell/pull/14636)| +|[@sholderbach](https://github.com/sholderbach)|Pin reedline to 0.38.0 release|[#14651](https://github.com/nushell/nushell/pull/14651)| +|[@userwiths](https://github.com/userwiths)|Fix inconsistency in `ls` sort-order|[#13875](https://github.com/nushell/nushell/pull/13875)| +|[@ysthakur](https://github.com/ysthakur)|Add utouch command from uutils/coreutils|[#11817](https://github.com/nushell/nushell/pull/11817)| +|[@ysthakur](https://github.com/ysthakur)|Avoid recomputing fuzzy match scores|[#13700](https://github.com/nushell/nushell/pull/13700)| +|[@ysthakur](https://github.com/ysthakur)|fix: Respect sort in custom completions|[#14424](https://github.com/nushell/nushell/pull/14424)| +|[@zhiburt](https://github.com/zhiburt)|nu-table/ Do footer_inheritance by accounting for rows rather then a f…|[#14380](https://github.com/nushell/nushell/pull/14380)| diff --git a/book/3rdpartyprompts.md b/book/3rdpartyprompts.md index aa47d4befc3..13146f0821e 100644 --- a/book/3rdpartyprompts.md +++ b/book/3rdpartyprompts.md @@ -25,10 +25,10 @@ If you like [oh-my-posh](https://ohmyposh.dev/), you can use oh-my-posh with Nus ```nu # Generate the .oh-my-posh.nu file -> oh-my-posh init nu --config ~/.poshthemes/M365Princess.omp.json +oh-my-posh init nu --config ~/.poshthemes/M365Princess.omp.json # Initialize oh-my-posh.nu at shell startup by adding this line in your config.nu file -> source ~/.oh-my-posh.nu +source ~/.oh-my-posh.nu ``` For MacOS users: diff --git a/book/aliases.md b/book/aliases.md index f74f2cc5d9f..798261d4520 100644 --- a/book/aliases.md +++ b/book/aliases.md @@ -5,19 +5,19 @@ Aliases in Nushell offer a way of doing a simple replacement of command calls (b For example, let's create an alias called `ll` which will expand to `ls -l`. ```nu -> alias ll = ls -l +alias ll = ls -l ``` We can now call this alias: ```nu -> ll +ll ``` Once we do, it's as if we typed `ls -l`. This also allows us to pass in flags or positional parameters. For example, we can now also write: ```nu -> ll -a +ll -a ``` And get the equivalent to having typed `ls -l -a`. diff --git a/book/cheat_sheet.md b/book/cheat_sheet.md index 175ba9eed5b..c325620f980 100644 --- a/book/cheat_sheet.md +++ b/book/cheat_sheet.md @@ -46,72 +46,72 @@ select two named columns from the table and print their values: interpolate text: ```nu -> let name = "Alice" -> $"greetings, ($name)!" -greetings, Alice! +let name = "Alice" +$"greetings, ($name)!" +# => greetings, Alice! ``` split text on comma delimiter and save the list to `string_list` variable: ```nu -> let string_list = "one,two,three" | split row "," -> $string_list -╭───┬───────╮ -│ 0 │ one │ -│ 1 │ two │ -│ 2 │ three │ -╰───┴───────╯ +let string_list = "one,two,three" | split row "," +$string_list +# => ╭───┬───────╮ +# => │ 0 │ one │ +# => │ 1 │ two │ +# => │ 2 │ three │ +# => ╰───┴───────╯ ``` check if a string contains a substring: ```nu -> "Hello, world!" | str contains "o, w" -true +"Hello, world!" | str contains "o, w" +# => true ``` join multiple strings with delimiter: ```nu -> let str_list = [zero one two] -> $str_list | str join ',' -zero,one,two +let str_list = [zero one two] +$str_list | str join ',' +# => zero,one,two ``` slice text by indices: ```nu -> 'Hello World!' | str substring 4..8 -o Wor +'Hello World!' | str substring 4..8 +# => o Wor ``` parse string into named columns: ```nu -> 'Nushell 0.80' | parse '{shell} {version}' -╭───┬─────────┬─────────╮ -│ # │ shell │ version │ -├───┼─────────┼─────────┤ -│ 0 │ Nushell │ 0.80 │ -╰───┴─────────┴─────────╯ +'Nushell 0.80' | parse '{shell} {version}' +# => ╭───┬─────────┬─────────╮ +# => │ # │ shell │ version │ +# => ├───┼─────────┼─────────┤ +# => │ 0 │ Nushell │ 0.80 │ +# => ╰───┴─────────┴─────────╯ ``` parse comma separated values (csv): ```nu -> "acronym,long\nAPL,A Programming Language" | from csv -╭───┬─────────┬────────────────────────╮ -│ # │ acronym │ long │ -├───┼─────────┼────────────────────────┤ -│ 0 │ APL │ A Programming Language │ -╰───┴─────────┴────────────────────────╯ +"acronym,long\nAPL,A Programming Language" | from csv +# => ╭───┬─────────┬────────────────────────╮ +# => │ # │ acronym │ long │ +# => ├───┼─────────┼────────────────────────┤ +# => │ 0 │ APL │ A Programming Language │ +# => ╰───┴─────────┴────────────────────────╯ ``` color text in command-line terminal: ```nu -> $'(ansi purple_bold)This text is a bold purple!(ansi reset)' -This text is a bold purple! +$'(ansi purple_bold)This text is a bold purple!(ansi reset)' +# => This text is a bold purple! ``` ## Lists @@ -119,136 +119,136 @@ This text is a bold purple! insert list value at index: ```nu -> [foo bar baz] | insert 1 'beeze' -╭───┬───────╮ -│ 0 │ foo │ -│ 1 │ beeze │ -│ 2 │ bar │ -│ 3 │ baz │ -╰───┴───────╯ +[foo bar baz] | insert 1 'beeze' +# => ╭───┬───────╮ +# => │ 0 │ foo │ +# => │ 1 │ beeze │ +# => │ 2 │ bar │ +# => │ 3 │ baz │ +# => ╰───┴───────╯ ``` update list value by index: ```nu -> [1, 2, 3, 4] | update 1 10 -╭───┬────╮ -│ 0 │ 1 │ -│ 1 │ 10 │ -│ 2 │ 3 │ -│ 3 │ 4 │ -╰───┴────╯ +[1, 2, 3, 4] | update 1 10 +# => ╭───┬────╮ +# => │ 0 │ 1 │ +# => │ 1 │ 10 │ +# => │ 2 │ 3 │ +# => │ 3 │ 4 │ +# => ╰───┴────╯ ``` prepend list value: ```nu -> let numbers = [1, 2, 3] -> $numbers | prepend 0 -╭───┬───╮ -│ 0 │ 0 │ -│ 1 │ 1 │ -│ 2 │ 2 │ -│ 3 │ 3 │ -╰───┴───╯ +let numbers = [1, 2, 3] +$numbers | prepend 0 +# => ╭───┬───╮ +# => │ 0 │ 0 │ +# => │ 1 │ 1 │ +# => │ 2 │ 2 │ +# => │ 3 │ 3 │ +# => ╰───┴───╯ ``` append list value: ```nu -> let numbers = [1, 2, 3] -> $numbers | append 4 -╭───┬───╮ -│ 0 │ 1 │ -│ 1 │ 2 │ -│ 2 │ 3 │ -│ 3 │ 4 │ -╰───┴───╯ +let numbers = [1, 2, 3] +$numbers | append 4 +# => ╭───┬───╮ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => │ 2 │ 3 │ +# => │ 3 │ 4 │ +# => ╰───┴───╯ ``` slice first list values: ```nu -> [cammomile marigold rose forget-me-not] | first 2 -╭───┬───────────╮ -│ 0 │ cammomile │ -│ 1 │ marigold │ -╰───┴───────────╯ +[cammomile marigold rose forget-me-not] | first 2 +# => ╭───┬───────────╮ +# => │ 0 │ cammomile │ +# => │ 1 │ marigold │ +# => ╰───┴───────────╯ ``` iterate over a list; `elt` is current list value: ```nu -> let planets = [Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune] -> $planets | each { |elt| $"($elt) is a planet of the solar system" } -╭───┬─────────────────────────────────────────╮ -│ 0 │ Mercury is a planet of the solar system │ -│ 1 │ Venus is a planet of the solar system │ -│ 2 │ Earth is a planet of the solar system │ -│ 3 │ Mars is a planet of the solar system │ -│ 4 │ Jupiter is a planet of the solar system │ -│ 5 │ Saturn is a planet of the solar system │ -│ 6 │ Uranus is a planet of the solar system │ -│ 7 │ Neptune is a planet of the solar system │ -╰───┴─────────────────────────────────────────╯ +let planets = [Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune] +$planets | each { |elt| $"($elt) is a planet of the solar system" } +# => ╭───┬─────────────────────────────────────────╮ +# => │ 0 │ Mercury is a planet of the solar system │ +# => │ 1 │ Venus is a planet of the solar system │ +# => │ 2 │ Earth is a planet of the solar system │ +# => │ 3 │ Mars is a planet of the solar system │ +# => │ 4 │ Jupiter is a planet of the solar system │ +# => │ 5 │ Saturn is a planet of the solar system │ +# => │ 6 │ Uranus is a planet of the solar system │ +# => │ 7 │ Neptune is a planet of the solar system │ +# => ╰───┴─────────────────────────────────────────╯ ``` iterate over a list with an index and value: ```nu -> $planets | enumerate | each { |elt| $"($elt.index + 1) - ($elt.item)" } -╭───┬─────────────╮ -│ 0 │ 1 - Mercury │ -│ 1 │ 2 - Venus │ -│ 2 │ 3 - Earth │ -│ 3 │ 4 - Mars │ -│ 4 │ 5 - Jupiter │ -│ 5 │ 6 - Saturn │ -│ 6 │ 7 - Uranus │ -│ 7 │ 8 - Neptune │ -╰───┴─────────────╯ +$planets | enumerate | each { |elt| $"($elt.index + 1) - ($elt.item)" } +# => ╭───┬─────────────╮ +# => │ 0 │ 1 - Mercury │ +# => │ 1 │ 2 - Venus │ +# => │ 2 │ 3 - Earth │ +# => │ 3 │ 4 - Mars │ +# => │ 4 │ 5 - Jupiter │ +# => │ 5 │ 6 - Saturn │ +# => │ 6 │ 7 - Uranus │ +# => │ 7 │ 8 - Neptune │ +# => ╰───┴─────────────╯ ``` reduce the list to a single value; `reduce` gives access to accumulator that is applied to each element in the list: ```nu -> let scores = [3 8 4] -> $"total = ($scores | reduce { |elt, acc| $acc + $elt })" -total = 15 +let scores = [3 8 4] +$"total = ($scores | reduce { |elt, acc| $acc + $elt })" +# => total = 15 ``` reduce with an initial value (`--fold`): ```nu -> let scores = [3 8 4] -> $"total = ($scores | reduce --fold 1 { |elt, acc| $acc * $elt })" -total = 96 +let scores = [3 8 4] +$"total = ($scores | reduce --fold 1 { |elt, acc| $acc * $elt })" +# => total = 96 ``` give access to the 3rd item in the list: ```nu -> let planets = [Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune] -> $planets.2 -Earth +let planets = [Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune] +$planets.2 +# => Earth ``` check if any string in the list starts with `E`: ```nu -> let planets = [Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune] -> $planets | any {|elt| $elt | str starts-with "E" } -true +let planets = [Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune] +$planets | any {|elt| $elt | str starts-with "E" } +# => true ``` slice items that satisfy provided condition: ```nu -> let cond = {|x| $x < 0 }; [-1 -2 9 1] | take while $cond -╭───┬────╮ -│ 0 │ -1 │ -│ 1 │ -2 │ -╰───┴────╯ +let cond = {|x| $x < 0 }; [-1 -2 9 1] | take while $cond +# => ╭───┬────╮ +# => │ 0 │ -1 │ +# => │ 1 │ -2 │ +# => ╰───┴────╯ ``` ## Tables @@ -268,30 +268,28 @@ ls | sort-by size | first 5 concatenate two tables with same columns: ```nu -> let $a = [[first_column second_column third_column]; [foo bar snooze]] -> let $b = [[first_column second_column third_column]; [hex seeze feeze]] -> $a | append $b - -╭───┬──────────────┬───────────────┬──────────────╮ -│ # │ first_column │ second_column │ third_column │ -├───┼──────────────┼───────────────┼──────────────┤ -│ 0 │ foo │ bar │ snooze │ -│ 1 │ hex │ seeze │ feeze │ -╰───┴──────────────┴───────────────┴──────────────╯ +let $a = [[first_column second_column third_column]; [foo bar snooze]] +let $b = [[first_column second_column third_column]; [hex seeze feeze]] +$a | append $b +# => ╭───┬──────────────┬───────────────┬──────────────╮ +# => │ # │ first_column │ second_column │ third_column │ +# => ├───┼──────────────┼───────────────┼──────────────┤ +# => │ 0 │ foo │ bar │ snooze │ +# => │ 1 │ hex │ seeze │ feeze │ +# => ╰───┴──────────────┴───────────────┴──────────────╯ ``` remove the last column of a table: ```nu -> let teams_scores = [[team score plays]; ['Boston Celtics' 311 3] ['Golden State Warriors', 245 2]] -> $teams_scores | drop column - -╭───┬───────────────────────┬───────╮ -│ # │ team │ score │ -├───┼───────────────────────┼───────┤ -│ 0 │ Boston Celtics │ 311 │ -│ 1 │ Golden State Warriors │ 245 │ -╰───┴───────────────────────┴───────╯ +let teams_scores = [[team score plays]; ['Boston Celtics' 311 3] ['Golden State Warriors', 245 2]] +$teams_scores | drop column +# => ╭───┬───────────────────────┬───────╮ +# => │ # │ team │ score │ +# => ├───┼───────────────────────┼───────┤ +# => │ 0 │ Boston Celtics │ 311 │ +# => │ 1 │ Golden State Warriors │ 245 │ +# => ╰───┴───────────────────────┴───────╯ ``` ## Files and Filesystem @@ -337,7 +335,7 @@ watch . --glob=**/*.rs {|| cargo test } custom command with parameter type set to string: ```nu -> def greet [name: string] { +def greet [name: string] { $"hello ($name)" } ``` @@ -345,7 +343,7 @@ custom command with parameter type set to string: custom command with default parameter set to nushell: ```nu -> def greet [name = "nushell"] { +def greet [name = "nushell"] { $"hello ($name)" } ``` @@ -353,20 +351,20 @@ custom command with default parameter set to nushell: passing named parameter by defining flag for custom commands: ```nu -> def greet [ +def greet [ name: string --age: int ] { [$name $age] } -> greet world --age 10 +greet world --age 10 ``` using flag as a switch with a shorthand flag (-a) for the age: ```nu -> def greet [ +def greet [ name: string --age (-a): int --twice @@ -377,24 +375,24 @@ using flag as a switch with a shorthand flag (-a) for the age: [$name $age] } } -> greet -a 10 --twice hello +greet -a 10 --twice hello ``` custom command which takes any number of positional arguments using rest params: ```nu -> def greet [...name: string] { +def greet [...name: string] { print "hello all:" for $n in $name { print $n } } -> greet earth mars jupiter venus -hello all: -earth -mars -jupiter -venus +greet earth mars jupiter venus +# => hello all: +# => earth +# => mars +# => jupiter +# => venus ``` ## Variables @@ -402,64 +400,64 @@ venus an immutable variable cannot change its value after declaration: ```nu -> let val = 42 -> print $val -42 +let val = 42 +print $val +# => 42 ``` shadowing variable (declaring variable with the same name in a different scope): ```nu -> let val = 42 -> do { let val = 101; $val } -101 -> $val -42 +let val = 42 +do { let val = 101; $val } +# => 101 +$val +# => 42 ``` declaring a mutable variable with mut key word: ```nu -> mut val = 42 -> $val += 27 -> $val -69 +mut val = 42 +$val += 27 +$val +# => 69 ``` closures and nested defs cannot capture mutable variables from their environment (errors): ```nu -> mut x = 0 -> [1 2 3] | each { $x += 1 } -Error: nu::parser::expected_keyword - - × Capture of mutable variable. - ╭─[entry #83:1:18] - 1 │ [1 2 3] | each { $x += 1 } - · ─┬ - · ╰── capture of mutable variable - ╰──── +mut x = 0 +[1 2 3] | each { $x += 1 } +# => Error: nu::parser::expected_keyword +# => +# => × Capture of mutable variable. +# => ╭─[entry #83:1:18] +# => 1 │ [1 2 3] | each { $x += 1 } +# => · ─┬ +# => · ╰── capture of mutable variable +# => ╰──── ``` a constant variable is immutable and is fully evaluated at parse-time: ```nu -> const file = 'path/to/file.nu' -> source $file +const file = 'path/to/file.nu' +source $file ``` use question mark operator `?` to return null instead of error if provided path is incorrect: ```nu -> let files = (ls) -> $files.name?.0? +let files = (ls) +$files.name?.0? ``` assign the result of a pipeline to a variable: ```nu -> let big_files = (ls | where size > 10kb) -> $big_files +let big_files = (ls | where size > 10kb) +$big_files ``` ## Modules @@ -467,7 +465,7 @@ assign the result of a pipeline to a variable: use an inline module: ```nu -> module greetings { +module greetings { export def hello [name: string] { $"hello ($name)!" } @@ -476,8 +474,8 @@ use an inline module: $"hi ($where)!" } } -> use greetings hello -> hello "world" +use greetings hello +hello "world" ``` import module from file and use its environment in current scope: @@ -491,11 +489,11 @@ export def hello [] { $"hello ($env.MYNAME)" } -> use greetings.nu -> $env.MYNAME -Arthur, King of the Britons -> greetings hello -hello Arthur, King of the Britons! +use greetings.nu +$env.MYNAME +# => Arthur, King of the Britons +greetings hello +# => hello Arthur, King of the Britons! ``` use main command in module: @@ -514,9 +512,9 @@ export def main [] { "greetings and salutations!" } -> use greetings.nu -> greetings -greetings and salutations! -> greetings hello world -hello world! +use greetings.nu +greetings +# => greetings and salutations! +greetings hello world +# => hello world! ``` diff --git a/book/coloring_and_theming.md b/book/coloring_and_theming.md index c1763b7a571..a7b25ced8ab 100644 --- a/book/coloring_and_theming.md +++ b/book/coloring_and_theming.md @@ -13,7 +13,7 @@ Many parts of Nushell's interface can have their color customized. All of these Table borders are controlled by the `$env.config.table.mode` setting in `config.nu`. Here is an example: ```nu -> $env.config = { +$env.config = { table: { mode: rounded } @@ -269,7 +269,7 @@ This is the current list of primitives. Not all of these are configurable. The c Here's a small example of changing some of these values. ```nu -> let config = { +let config = { color_config: { separator: purple leading_trailing_space_bg: "#ffffff" @@ -294,7 +294,7 @@ Here's a small example of changing some of these values. Here's another small example using multiple color syntaxes with some comments. ```nu -> let config = { +let config = { color_config: { separator: "#88b719" # this sets only the foreground color like PR #486 leading_trailing_space_bg: white # this sets only the foreground color in the original style @@ -348,7 +348,7 @@ Here's the current list of flat shapes. Here's a small example of how to apply color to these items. Anything not specified will receive the default color. ```nu -> $env.config = { +$env.config = { color_config: { shape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b} shape_bool: green @@ -372,13 +372,13 @@ The Nushell prompt is configurable through these environment variables and confi Example: For a simple prompt one could do this. Note that `PROMPT_COMMAND` requires a `block` whereas the others require a `string`. ```nu -> $env.PROMPT_COMMAND = { build-string (date now | format date '%m/%d/%Y %I:%M:%S%.3f') ': ' (pwd | path basename) } +$env.PROMPT_COMMAND = { build-string (date now | format date '%m/%d/%Y %I:%M:%S%.3f') ': ' (pwd | path basename) } ``` If you don't like the default `PROMPT_INDICATOR` you could change it like this. ```nu -> $env.PROMPT_INDICATOR = "> " +$env.PROMPT_INDICATOR = "> " ``` If you're using `starship`, you'll most likely want to show the right prompt on the last line of the prompt, just like zsh or fish. You could modify the `config.nu` file, just set `render_right_prompt_on_last_line` to true: @@ -401,13 +401,13 @@ Each of the `PROMPT_*` variables has a corresponding `TRANSIENT_PROMPT_*` variab For example, if you want to make past prompts show up without a left prompt entirely and leave only the indicator, you can use: ```nu -> $env.TRANSIENT_PROMPT_COMMAND = "" +$env.TRANSIENT_PROMPT_COMMAND = "" ``` If you want to go back to the normal left prompt, you'll have to unset `TRANSIENT_PROMPT_COMMAND`: ```nu -> hide-env TRANSIENT_PROMPT_COMMAND +hide-env TRANSIENT_PROMPT_COMMAND ``` ## `LS_COLORS` Colors for the [`ls`](/commands/docs/ls.md) Command diff --git a/book/coming_from_bash.md b/book/coming_from_bash.md index cf8964ad136..bb29b1ad37a 100644 --- a/book/coming_from_bash.md +++ b/book/coming_from_bash.md @@ -52,8 +52,8 @@ $env.Path = ($env.Path | prepend 'C:\Program Files\Git\usr\bin') | | `help commands` | List all available commands | | | `help --find ` | Search for match in all available commands | | `command1 && command2` | `command1; command2` | Run a command, and if it's successful run a second | -| `stat $(which git)` | `stat (which git).path` | Use command output as argument for other command | -| `echo /tmp/$RANDOM` | `$"/tmp/(random integer)"` | Use command output in a string | +| `stat $(which git)` | `stat ...(which git).path` | Use command output as argument for other command | +| `echo /tmp/$RANDOM` | `$"/tmp/(random int)"` | Use command output in a string | | `cargo b --jobs=$(nproc)` | `cargo b $"--jobs=(sys cpu \| length)"` | Use command output in an option | | `echo $PATH` | `$env.PATH` (Non-Windows) or `$env.Path` (Windows) | See the current path | | `` | `vim $nu.config-path` | Update PATH permanently | diff --git a/book/configuration.md b/book/configuration.md index 4b6b48e67e7..5d507c73f02 100644 --- a/book/configuration.md +++ b/book/configuration.md @@ -1,242 +1,697 @@ # Configuration -## Nushell Configuration with `env.nu` and `config.nu` +## Quickstart -Nushell uses a configuration system that loads and runs two Nushell script files at launch time: +While Nushell provides many options for managing its startup and configuration, new users +can get started with just a few simple steps: -- `env.nu` is used to define environment variables or write files before `config.nu` starts. For example [`$env.NU_LIB_DIRS`](/book/modules.md#dumping-files-into-directory) controls where Nu finds imports. Third party scripts, like prompts or [mise](https://mise.jdx.dev/getting-started.html#nushell), must already be saved to disk before `config.nu` can read them. -- `config.nu` is used to add definitions, aliases, and more to the global namespace. It can also use the environment variables and constants defined in `env.nu`. If you can't decide which file to add stuff, prefer `config.nu`. +1. Tell Nushell what editor to use: -Check where Nushell is reading these config files from by calling `$nu.env-path` and `$nu.config-path`. + ```nu + $env.config.buffer_editor = + ``` + + For example: + + ```nu + $env.config.buffer_editor = "code" + # or + $env.config.buffer_editor = "nano" + # or + $env.config.buffer_editor = "hx" + # or + $env.config.buffer_editor = "vi" + # etc. + ``` + +2. Edit `config.nu` using: + + ```nu + config nu + ``` + + This will open the current `config.nu` in the editor defined above. + +3. Add commands to this file that should run each time Nushell starts. A good first example might be the `buffer_editor` setting above. + + You can find a detailed list of available settings using: + + ```nu + config nu --doc | nu-highlight | less -R + ``` + +4. Save, exit the editor, and start a new Nushell session to load these settings. + +That's it! More details are below when you need them ... + +--- + +[[toc]] + +::: tip +To view a simplified version of this documentation from inside Nushell, run: ```nu -> $nu.env-path -/Users/FirstNameLastName/Library/Application Support/nushell/env.nu +config env --doc | nu-highlight | less -R ``` -_(You can think of the Nushell config loading sequence as executing two [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) lines on startup: `source /path/to/env.nu` and `source /path/to/config.nu`. Therefore, using `env.nu` for environment and `config.nu` for other config is just a convention.)_ +::: + +## Configuration Overview -When you launch Nushell without these files set up, Nushell will prompt you to download the [default config files](https://github.com/nushell/nushell/tree/main/crates/nu-utils/src/default_files). +Nushell uses multiple, optional configuration files. These files are loaded in the following order: + +1. The first file loaded is `env.nu`, which was historically used to override environment variables. However, the current "best-practice" recommendation is to set all environment variables (and other configuration) using `config.nu` and the autoload directories below. + +2. `config.nu` is typically used to override default Nushell settings, define (or import) custom commands, or run any other startup tasks. +3. Files in `$nu.vendor-autoload-dirs` are loaded. These files can be used for any purpose and are a convenient way to modularize a configuration. +4. `login.nu` runs commands or handles configuration that should only take place when Nushell is running as a login shell. + +By default, `env.nu`, `config.nu`, and `login.nu` are read from the `$nu.default-config-dir` directory. For example: + +```nu +$nu.default-config-dir +# macOS +# => /Users/me/Library/Application Support/nushell +# Linux +# => /home/me/.config/nushell +# Windows +# => C:\Users\me\AppData\Roaming\nushell +``` + +The first time Nushell is launched, it will create the configuration directory and an empty (other than comments) `env.nu` and `config.nu`. ::: tip -The default config files aren't required. If you prefer to start with an empty `env.nu` and `config.nu` then Nu applies identical defaults in internal Rust code. You can still browse the default files for default values of environment variables and a list of all configurable settings using the [`config`](#configurations-with-built-in-commands) commands: +You can quickly open `config.nu` in your default text editor using the `config nu` command. Likewise, the `config env` command will open `env.nu`. + +This requires that you have configured a default editor using either: + +- Nushell's `$env.config.buffer_editor` setting +- The `$env.VISUAL` or `$env.EDITOR` environment variables + +For example, place this in your `config.nu` to edit your files in Visual Studio Code: ```nu -> config env --default | nu-highlight | lines -> config nu --default | nu-highlight | lines +$env.config.buffer_editor = 'code' ``` ::: -Control which directory Nushell reads config files from with the `XDG_CONFIG_HOME` environment variable. When you set it to -an absolute path, Nushell will read config files from `$"($env.XDG_CONFIG_HOME)/nushell"`. For example, if you set it to -`C:\Users\bob\.config`, Nushell will read config files from `C:\Users\bob\.config\nushell\`. +## Common Configuration Tasks in `config.nu`: -::: warning -`XDG_CONFIG_HOME` must be set **before** starting Nushell. Setting it in `env.nu` or `config.nu` won't change where Nushell -looks for configuration files. -::: +::: tip +Some users will prefer a "monolithic" configuration file with most or all startup tasks in one place. `config.nu` can be used for this purpose. -On Windows, you can persistently set the `XDG_CONFIG_HOME` environment variable through the Control Panel. To get there, just -search for "environment variable" in the Start menu. +Other users may prefer a "modular" configuration where each file handles a smaller, more focused set of tasks. Files in the autoload dirs can be used to create this experience. +::: -On other platforms, if Nushell isn't your login shell, then you can set `XDG_CONFIG_HOME` before launching Nushell. For example, if you -use MacOS and your login shell is Zsh, you could add the following to your `.zshrc`: +`config.nu` is commonly used to: -```zsh -export XDG_CONFIG_HOME="/Users/bob/.config" -``` +- Set [environment variables](#set-environment-variables) for Nushell and other applications +- Set Nushell settings in [`$env.config`](#nushell-settings-in-the-envconfig-record) +- Load modules or source files so that their commands are readily available +- Run any other applications or commands at startup -If Nushell is your login shell, then ways to set `XDG_CONFIG_HOME` will depend on your OS. -Some Linux distros will let you set environment variables in `/etc/profile` or `/etc/profile.d`. -On modern Linux distros, you can also set it through PAM in `/etc/environment`. +## Set Environment Variables -::: warning -[`XDG_CONFIG_HOME`](https://xdgbasedirectoryspecification.com) is not a Nushell-specific environment variable and should not be set to the -directory that contains Nushell config files. It should be the directory _above_ the `nushell` directory. If you set it to -`/Users/username/dotfiles/nushell`, Nushell will look for config files in `/Users/username/dotfiles/nushell/nushell` instead. -In this case, you would want to set it to `/Users/username/dotfiles`. +::: tip See Also +The [Environment](./environment.md) Chapter covers additional information on how to set and access environment variables. ::: -## Configuring `$env.config` +### Path Configuration + +As with most shells, Nushell searches the environment variable named `PATH` (or variants). +The `env.nu` file is often used to add (and sometimes remove) directories on the path. + +:::tip +Unlike some shells, Nushell attempts to be "case agnostic" with environment variables. `Path`, `path`, `PATH`, and even `pAtH` are all allowed variants of the same environment variable. See [Environment - Case Sensitivity](./environment.md#case-sensitivity) for details. +::: -Nushell's main settings are kept in the `config` environment variable as a record. This record can be created using: +When Nushell is launched, it usually inherits the `PATH` as a string. However, Nushell automatically converts this to a Nushell list for easy access. This means that you can _append_ to +the path using, for example: ```nu -$env.config = { - ... -} +$env.path ++= ["~/.local/bin"] ``` -Note that setting any key overwrites its previous value. Likewise it's an error to reference any missing key. If `$env.config` already exists you can update or gracefully insert a [`cell-path`](/book/types_of_data.html#cell-paths) at any depth using [`upsert`](/commands/docs/upsert.md): +The Standard Library also includes a helper command. The default `path add` behavior is to _prepend_ +a directory so that it has higher precedence than the rest of the path. For example, the following can be +added to `env.nu`: -```nu -$env.config = ($env.config | upsert ) +```nushell +use std/util "path add" +path add "~/.local/bin" +path add ($env.CARGO_HOME | path join "bin") ``` -By convention, this variable is defined in the `config.nu` file. +::: tip +Notice the use of `path join` in the example above. This command properly joins two path +components regardless of whether or not the path separator is present. See `help path` for +more commands in this category. +::: + +### Prompt Configuration + +Nushell provides a number of prompt configuration options. By default, Nushell includes: + +- A prompt which includes the current directory, abbreviated using `~` if it is (or is under) + the home directory. +- A prompt indicator which appears immediately to the right of the prompt. This defaults to `> ` when in normal editing mode, or a `: ` when in Vi-insert mode. Note extra space after the character to provide separation of the command from the prompt. +- A right-prompt with the date and time +- An indicator which is displayed when the current commandline extends over multiple lines - `::: ` by default + +The environment variables which control these prompt components are: -### Environment +- `$env.PROMPT_COMMAND`: The prompt itself +- `$env.PROMPT_COMMAND_RIGHT`: A prompt which can appear on the right side of the terminal +- `$env.PROMPT_INDICATOR`: Emacs mode indicator +- `$env.PROMPT_INDICATOR_VI_NORMAL`: Vi-normal mode indicator +- `$env.PROMPT_INDICATOR_VI_INSERT`: Vi-insert mode indicator +- `$env.PROMPT_MULTILINE_INDICATOR`: The multi-line indicator -You can set environment variables for the duration of a Nushell session using the `$env. = ` structure inside the `env.nu` file. For example: +Each of these variables accepts either: + +- A string, in which case the component will be statically displayed as that string. +- A closure (with no parameters), in which case the component will be dynamically displayed based on the closure's code. +- `null`, in which case the component will revert to its internal default value. + +::: tip +To disable the right-prompt, for instance, add the following to `env.nu`: ```nu -$env.FOO = 'BAR' +$env.PROMPT_COMMAND_RIGHT = "" +# or +$env.PROMPT_COMMAND_RIGHT = {||} ``` -_(Although $env.config is an environment variable, it is still defined by convention inside config.nu.)_ +::: -These are some important variables to look at for Nushell-specific settings: +#### Transient Prompts -- `LS_COLORS`: Sets up colors per file type in ls -- `PROMPT_COMMAND`: Code to execute for setting up the prompt (block or string) -- `PROMPT_COMMAND_RIGHT`: Code to execute for setting up the right prompt (block) -- `PROMPT_INDICATOR = "〉"`: The indicator printed after the prompt (by default ">"-like Unicode symbol) -- `PROMPT_INDICATOR_VI_INSERT = ": "` -- `PROMPT_INDICATOR_VI_NORMAL = "〉 "` -- `PROMPT_MULTILINE_INDICATOR = "::: "` +Nushell also supports transient prompts, which allow a different prompt to be shown _after_ a commandline has been executed. This can be useful in several situations: -### Configurations with Built-in Commands +- When using a multi-line prompt, the transient prompt can be a more condensed version. +- Removing the transient multiline indicator and right-prompt can simplify copying from the terminal. -The ([`config nu`](/commands/docs/config_nu.md) and [`config env`](/commands/docs/config_env.md)) commands open their respective configurations for quick editing in your preferred text editor or IDE. Nu determines your editor from the following environment variables in order: +As with the normal prompt commands above, each transient prompt can accept a (static) string, a (dynamic) closure, or a `null` to use the Nushell internal defaults. -1. `$env.config.buffer_editor` -2. `$env.VISUAL` -3. `$env.EDITOR` +The environment variables which control the transient prompt components are: -### Color Config Section +- `$env.TRANSIENT_PROMPT_COMMAND`: The prompt itself after the commandline has been executed +- `$env.TRANSIENT_PROMPT_COMMAND_RIGHT`: A prompt which can appear on the right side of the terminal +- `$env.TRANSIENT_PROMPT_INDICATOR`: Emacs mode indicator +- `$env.TRANSIENT_PROMPT_INDICATOR_VI_NORMAL`: Vi-normal mode indicator +- `$env.TRANSIENT_PROMPT_INDICATOR_VI_INSERT`: Vi-insert mode indicator +- `$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR`: The multi-line indicator -You can learn more about setting up colors and theming in the [associated chapter](coloring_and_theming.md). +::: tip +Nushell sets `TRANSIENT_PROMPT_COMMAND_RIGHT` and `TRANSIENT_PROMPT_MULTILINE_INDICATOR` to an empty string (`""`) so that each disappears after the previous command is entered. This simplifies copying and pasting from the terminal. -### Remove Welcome Message +To disable this feature and always show those items, set: + +```nu +$env.TRANSIENT_PROMPT_COMMAND_RIGHT = null +$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR = null +``` -To remove the welcome message, you need to edit your `config.nu` by typing `config nu` in your terminal, then you go to the global configuration `$env.config` and set `show_banner` option to false, like this: +::: + +### ENV_CONVERSIONS + +Certain variables, such as those containing multiple paths, are often stored as a +colon-separated string in other shells. Nushell can convert these automatically to a +more convenient Nushell list. The ENV_CONVERSIONS variable specifies how environment +variables are: -@[code](@snippets/installation/remove_welcome_message.nu) +- converted from a string to a value on Nushell startup (from_string) +- converted from a value back to a string when running external commands (to_string) -## Configuring Nu as a Login Shell +`ENV_CONVERSIONS` is a record, where: -To use Nu as a login shell, you'll need to configure the `$env` variable. This sets up the environment for external programs. +- each key is an environment variable to be converted +- each value is another record containing a: + ```nu + { + from_string: + to_string: + } + ``` -To get an idea of which environment variables are set up by your current login shell, start a new shell session, then run nu in that shell. +::: tip +As mentioned above, the OS Path variable is automatically converted by Nushell. As a result, it can be treated as a list within `env.nu` without needing to be present in `ENV_CONVERSIONS`. Other colon-separated paths, like `XDG_DATA_DIRS`, are not automatically converted. +::: -You can then configure some `$env. = ` that setup the same environment variables in your nu login shell. Use this command to generate some `$env. = ` for all the environment variables: +To add an additional conversion, [`merge`](/commands/docs/merge.md) it into the `$env.ENV_CONVERSIONS` record. For example, to add a conversion for the `XDG_DATA_DIRS` variable: ```nu -$env | reject config | transpose key val | each {|r| echo $"$env.($r.key) = '($r.val)'"} | str join (char nl) +$env.ENV_CONVERSIONS = $env.ENV_CONVERSIONS | merge { + "XDG_DATA_DIRS": { + from_string: {|s| $s | split row (char esep) | path expand --no-symlink } + to_string: {|v| $v | path expand --no-symlink | str join (char esep) } + } +} ``` -This will print out `$env. = ` lines, one for each environment variable along with its setting. You may not need all of them, for instance the `PS1` variable is bash specific. +### `LS_COLORS` + +As with many `ls`-like utilities, Nushell's directory listings make use of the `LS_COLORS` environment variable for defining styles/colors to apply to certain file types and patterns. + +## Nushell Settings in the `$env.config` Record + +### Changing Settings in the `$env.config` Record -Next, on some distros you'll also need to ensure Nu is in the /etc/shells list: +The primary mechanism for changing Nushell's behavior is the `$env.config` record. While this record is accessed as an environment variable, unlike most other variables it is: -```sh -> cat /etc/shells -# /etc/shells: valid login shells -/bin/sh -/bin/dash -/bin/bash -/bin/rbash -/usr/bin/screen -/usr/bin/fish -/home/sophia/.cargo/bin/nu +- Not inherited from the parent process. Instead, it is populated by Nushell itself with certain defaults. +- Not exported to child processes started by Nushell. + +To examine the current settings in `$env.config`, just type the variable name: + +```nu +$env.config ``` -With this, you should be able to `chsh` and set Nu to be your login shell. After a logout, on your next login you should be greeted with a shiny Nu prompt. +::: tip +Since Nushell provides so many customization options, it may be better to send this to a pager like: -### Configuration with `login.nu` +```nu +$env.config | table -e | less -R +# or, if bat is installed: +$env.config | table -e | bat -p +``` -If Nushell is used as a login shell, you can use a specific configuration file which is only sourced in this case. Therefore a file with name `login.nu` has to be in the standard configuration directory. +::: -The file `login.nu` is sourced after `env.nu` and `config.nu`, so that you can overwrite those configurations if you need. There is an environment variable `$nu.loginshell-path` containing the path to this file. +An appendix documenting each setting will be available soon. In the meantime, abbreviated documentation on each setting can be viewed in Nushell using: -What about customizing interactive shells, similar to `.zshrc`? By default `config.nu` is only loaded in interactive shells, not scripts. +```nu +config nu --doc | nu-highlight | bat +# or +config nu --doc | nu-highlight | less -R +``` -### macOS: Keeping `/usr/bin/open` as `open` +To avoid overwriting existing settings, it's best to simply assign updated values to the desired configuration keys, rather than the entire `config` record. In other words: -Some tools (e.g. Emacs) rely on an [`open`](/commands/docs/open.md) command to open files on Mac. -As Nushell has its own [`open`](/commands/docs/open.md) command which has different semantics and shadows `/usr/bin/open`, these tools will error out when trying to use it. -One way to work around this is to define a custom command for Nushell's [`open`](/commands/docs/open.md) and create an alias for the system's [`open`](/commands/docs/open.md) in your `config.nu` file like this: +::: warning Wrong ```nu -alias nu-open = open -alias open = ^open +$env.config = { + show_banner: false +} ``` -The `^` symbol escapes the Nushell `open` command, which invokes the operating system's `open` command. -For more about escape and `^` see the [chapter about escapes](./running_externals.md). +This would reset any _other_ settings that had been changed, since the entire record would be overwritten. +::: + +::: tip Right + +```nu +$env.config.show_banner = false +``` -## PATH configuration +This changes _only_ the `show_banner` key/value pair, leaving all other keys with their existing values. +::: -In Nushell, [the PATH environment variable]() (Path on Windows) is a list of paths. To append a new path to it, you can use `$env. = ` and [`append`](/commands/docs/append.md) in `env.nu`: +Certain keys are themselves also records. It's okay to overwrite these records, but it's best-practice +to set all values when doing so. For example: ```nu -$env.PATH = ($env.PATH | split row (char esep) | append '/some/path') +$env.config.history = { + file_format: sqlite + max_size: 1_000_000 + sync_on_enter: true + isolation: true +} ``` -This will append `/some/path` to the end of PATH; you can also use [`prepend`](/commands/docs/prepend.md) to add entries to the start of PATH. +### Remove Welcome Message -Note the `split row (char esep)` step. We need to add it because in `env.nu`, the environment variables inherited from the host process are still strings. The conversion step of environment variables to Nushell values happens after reading the config files (see also the [Environment](environment.md#environment-variable-conversions) section). After that, for example in the Nushell REPL when `PATH`/`Path` is a list , you can use [`append`](/commands/docs/append.md)/[`prepend`](/commands/docs/prepend.md) directly. +:::note +This section is linked directly from the banner message, so it repeats some information from above. +::: -To add multiple paths only if not already listed, one can add to `env.nu`: +To remove the welcome message that displays each time Nushell starts: -```nu -$env.PATH = ( - $env.PATH - | split row (char esep) - | append /usr/local/bin - | append ($env.CARGO_HOME | path join bin) - | append ($env.HOME | path join .local bin) - | uniq # filter so the paths are unique -) +1. Type `config nu` to edit your configuration file. +2. If you receive an error regarding the editor not being defined: + + ```nu + $env.config.buffer_editor = + # Such as: + $env.config.buffer_editor = "code" + $env.config.buffer_editor = "vi" + # Or with editor arguments: + $env.config.buffer_editor: ["emacsclient", "-s", "light", "-t"], + ``` + + Then repeat step 1. + +3. Add the following line to the end of the file: + + ```nu + $env.config.show_banner = false + ``` + +4. Save and exit your editor. +5. Restart Nushell to test the change. + +## Additional Startup Configuration + +### Changing default directories + +::: warning Important +As discussed below, variables in this section must be set **before** Nushell is launched. +::: + +Some variables that control Nushell startup file locations must be set **before** Nushell is loaded. This is often done by a parent process such as: + +- The terminal application in which Nushell is run + +- The operating system or window manager. When running Nushell as a login shell, this will likely be the only mechanism available. + + For example, on Windows, you can set environment variables through the Control Panel. Choose the Start Menu and search for _"environment variables"_. + + On Linux systems using PAM, `/etc/environment` (and other system-specific mechanisms) can be used. + +- A parent shell. For example, exporting the value from `bash` before running `nu`. + +### Startup Variables + +The variables that affect Nushell file locations are: + +- `$env.XDG_CONFIG_HOME`: If this environment variable is set, it is used to change the directory that Nushell searches for its configuration files such as `env.nu`, `config.nu`, and `login.nu`. The history and plugin files are also stored in this directory by default. + + Once Nushell starts, this value is stored in the `$nu.default-config-path` constant. See [Using Constants](#using-constants) below. + +- `$env.XDG_DATA_HOME`: If this environment variable is set, Nushell sets the `$nu.data-dir` constant to this value. The `data-dir` is used in several startup tasks: + + - `($nu.data-dir)/nushell/completions` is added to the `$env.NU_LIB_DIRS` search path. + - `($nu.data-dir)/vendor/autoloads` is added as the last path in `nu.vendor-autoload-dirs`. This means that files in this directory will be read last during startup (and thus override any definitions made in earlier files). + + Note that the directory represented by `$nu.data-dir`, nor any of its subdirectories, are created by default. Creation and use of these directories is up to the user. + +- `$env.XDG_DATA_DIRS` _(Unix Platforms Only)_: If this environment variable is set, it is used to populate the `$nu.vendor-auto-load` directories in the order listed. The first directory in the list is processed first, meaning the last one read will have the ability to override previous definitions. + +::: warning +The `XDG_*` variables are **not** Nushell-specific and should not be set to a directory with only Nushell files. Instead, set the environment variable to the directory _above_ the one with the `nushell` directory. + +For example, if you set `$env.XDG_CONFIG_HOME` to: + +``` +/users/username/dotfiles/nushell ``` -This will add `/usr/local/bin`, the `bin` directory of CARGO_HOME, the `.local/bin` of HOME to PATH. It will also remove duplicates from PATH. +... Nushell will look for config files in `/Users/username/dotfiles/nushell/nushell`. The proper setting would be: + +``` +/users/username/dotfiles +``` + +Also keep in mind that if the system has already set `XDG` variables, then there may already be files in use in those directories. Changing the location may require that you move other application's files to the new directory. +::: ::: tip -There's a convenience command for updating your system path but you must first open the [`std`](/book/standard_library.md) [module](/book/cheat_sheet.md#modules) (in preview): +You can easily test out config changes in a "fresh" environment using the following recipe. The following is run from inside Nushell, but can be +adapted to other shells as well: + +```nu +# Create an empty temporary directory +let temp_home = (mktemp -d) +# Set the configuration path to this directory +$env.XDG_CONFIG_HOME = $temp_home +# Set the data-dir to this directory +$env.XDG_DATA_HOME = $temp_home +# Remove other potential autoload directories +$env.XDG_DATA_DIRS = "" +# Run Nushell in this environment +nu + +# Edit config +config nu +# Exit the subshell +exit +# Run the temporary config +nu +``` + +When done testing the configuration: ```nu -use std * -path add /usr/local/bin ($env.CARGO_HOME | path join bin) # etc. +# Remove the temporary config directory, if desired +rm $temp_home +``` + +**Important:** Then exit the parent shell so that the `XDG` changes are not accidentally propagated to other processes. +::: + +### Using Constants + +Some important commands, like `source` and `use`, that help define custom commands (and other definitions) are parse-time keywords. Among other things, this means means that all arguments must be known at parse-time. + +In other words, **_variable arguments are not allowed for parser keywords_**. + +However, Nushell creates some convenience _constants_ that can be used to help identify common file locations. For instance, you can source a file in the default configuration directory using: + +``` +source ($nu.default-config-dir | path join "myfile.nu") ``` -You can optionally `--append` paths to be checked last like the ones below. +Because the constant value is known at parse-time, it can be used with parse-time keywords like `source` and `use`. + +:::tip See Also +See [Parse-time Constant Evaluation](./how_nushell_code_gets_run.md#parse-time-constant-evaluation) for more details on this process. ::: -### Homebrew +#### `$nu` Constant + +To see a list of the built-in Nushell constants, examine the record constant using `$nu` (including the dollar sign). + +#### `NU_LIB_DIRS` Constant -[Homebrew](https://brew.sh/) is a popular package manager that often requires PATH configuration. To add it to your Nushell PATH: +Nushell can also make use of a `NU_LIB_DIRS` _constant_ which can act like the `$env.NU_LIB_DIRS` variable mentioned above. However, unlike `$env.NU_LIB_DIRS`, it can be defined _and_ used in `config.nu`. For example: ```nu -# macOS ARM64 (Apple Silicon) -$env.PATH = ($env.PATH | split row (char esep) | prepend '/opt/homebrew/bin') +# Define module and source search path +const NU_LIB_DIRS = [ + '~/myscripts' +] +# Load myscript.nu from the ~/myscripts directory +source myscript.nu +``` -# Linux -$env.PATH = ($env.PATH | split row (char esep) | prepend '/home/linuxbrew/.linuxbrew/bin') +If both the variable `$env.NU_LIB_DIRS` and the const `NU_LIB_DIRS` are defined, both sets +of paths will be searched. The constant `NU_LIB_DIRS` will be searched _first_ and have +precedence. If a file matching the name is found in one of those directories, the search will +stop. Otherwise, it will continue into the `$env.NU_LIB_DIRS` search path. + +#### `NU_PLUGIN_DIRS` Constant + +`const NU_PLUGIN_DIRS` works in the same way for the plugin search path. + +The following `NU_PLUGIN_DIRS` configuration will allow plugins to be loaded from; + +- The directory where the `nu` executable is located. This is typically where plugins are located in release packages. +- A directory in `$nu.data-dirs` named after the version of Nushell running (e.g. `0.100.0`). +- A `plugins` directory in your `$nu.config-path`. + +```nu +const NU_PLUGIN_DIRS = [ + ($nu.current-exe | path dirname) + ($nu.data-dir | path join 'plugins' | path join (version).version) + ($nu.config-path | path dirname | path join 'plugins') +] ``` -### Pyenv +### Colors, Theming, and Syntax Highlighting + +You can learn more about setting up colors and theming in the [associated chapter](coloring_and_theming.md). + +### Configuring Nu as a Login Shell + +The login shell is often responsible for setting certain environment variables which will be inherited by subshells and other processes. When setting Nushell as a user's default login shell, you'll want to make sure that the `login.nu` handles this task. -[Pyenv](https://github.com/pyenv/pyenv) is a popular Python version manager. To add it to your Nushell PATH: +Many applications will assume a POSIX or PowerShell login shell, and will either provide instructions for modifying the system or user `profile` that is loaded by POSIX login-shells (or `.ps1` file on PowerShell systems). -#### MacOS or Linux +As you may have noticed by now, Nushell is not a POSIX shell, nor is it PowerShell, and it won't be able to process a profile written for these. You'll need to set these values in `login.nu` instead. + +To find environment variables that may need to be set through `login.nu`, examine the inherited environment from your login shell by running `nu` from within your previous login shell. Run: ```nu -# MacOS or Linux -$env.PATH = ($env.PATH | split row (char esep) | prepend $"(pyenv root)/shims") +$env | reject config | transpose key val | each {|r| echo $"$env.($r.key) = '($r.val)'"} | str join (char nl) ``` -#### Windows +Look for any values that may be needed by third-party applications and copy these to your `login.nu`. Many of these will not be needed. For instance, the `PS1` setting is the current prompt in POSIX shells and won't be useful in Nushell. + +When ready, add Nushell to your `/etc/shells` (Unix) and `chsh` as discussed in [the Installation Chapter](./default_shell.md). + +### macOS: Keeping `/usr/bin/open` as `open` -Windows users need to install [pyenv-win](https://github.com/pyenv-win/pyenv-win) -and execute the `Get-Command pyenv` command in PowerShell to get the path of `pyenv.ps1` after the installation. +Some tools such as Emacs rely on an [`open`](/commands/docs/open.md) command to open files on Mac. -The result usually looks like: `C:\Users\\.pyenv\pyenv-win\bin\pyenv.ps1` +Since Nushell has its own [`open`](/commands/docs/open.md) command with a different meaning which shadows (overrides) `/usr/bin/open`, these tools will generate an error when trying to use the command. -Then add the path of pyenv to your Nushell PATH: +One way to work around this is to define a custom command for Nushell's [`open`](/commands/docs/open.md) and create an alias for the system's [`open`](/commands/docs/open.md) in your `config.nu` file like this: ```nu -# Windows -$env.Path = ($env.Path | split row (char esep) | prepend $"~/.pyenv/pyenv-win/bin/pyenv.ps1") +alias nu-open = open +alias open = ^open ``` + +Place this in your `config.nu` to make it permanent. + +The `^` symbol tells Nushell to run the following command as an _external_ command, rather than as a Nushell built-in. After running these commands, `nu-open` will be the Nushell _internal_ version, and the `open` alias will call the Mac, external `open` instead. + +For more information, see [Running System (External) Commands](./running_externals.md). + +## Detailed Configuration Startup Process + +This section contains a more detailed description of how different configuration (and flag) options can be used to +change Nushell's startup behavior. + +### Launch Stages + +The following stages and their steps _may_ occur during startup, based on the flags that are passed to `nu`. See [Flag Behavior](#flag-behavior) immediately following this table for how each flag impacts the process: + +| Step | Stage | Nushell Action | +| ---- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0. | (misc) | Sets internal defaults via its internal Rust implementation. In practice, this may not take place until "first use" of the setting or variable, but there will typically be a Rust default for most (but not all) settings and variables that control Nushell's behavior. These defaults can then be superseded by the steps below. | +| 1. | (main) | Inherits its initial environment from the calling process. These will initially be converted to Nushell strings, but can be converted to other structures later using `ENV_CONVERSIONS` (see below). | +| 2. | (main) | Gets the configuration directory. This is OS-dependent (see [dirs::config_dir](https://docs.rs/dirs/latest/dirs/fn.config_dir.html)), but can be overridden using `XDG_CONFIG_HOME` on all platforms as discussed [above](#changing-default-directories). | +| 3. | (main) | Creates the initial `$env.NU_LIB_DIRS` variable. By default, it includes (1) the `scripts` directory under the configuration directory, and (2) `nushell/completions` under the default data directory (either `$env.XDG_DATA_HOME` or [the default provided by the dirs crate](https://docs.rs/dirs/latest/dirs/fn.data_dir.html)). These directories are not created by default. | +| 4. | (main) | Creates the initial `$env.NU_PLUGIN_DIRS` variable. By default, this will include the configuration directory. | +| 5. | (main) | Initializes the in-memory SQLite database. This allows the `stor` family of commands to be used in the following configuration files. | +| 6. | (main) | Processes commandline arguments such as `--plugin-config `, `--plugins `, and others. See `nu --help` for a complete list. | +| 7. | (main) | Gets the path to `env.nu` and `config.nu`. By default, these are located in the config directory, but either or both can be overridden using the `--env-config ` and `--config ` flags. | +| 8. | (main) | If the `--include-path (-I)` flag was used, it overrides the default `$env.NU_LIB_DIRS` that was obtained above. | +| 9. | (main) | Loads the initial `$env.config` values from the internal defaults. | +| 10. | (stdlib) | Loads the [Standard Library](./standard_library.md) into the virtual filesystem. It is not parsed or evaluated at this point. | +| 11. | (stdlib) | Parses and evaluates `std/core`, which brings the `banner` and `pwd` commands into scope. | +| 12. | (main) | Generates the initial [`$nu` record constant](#using-constants) so that items such as `$nu.default-config-dir` can be used in the following config files. | +| 13. | (main) | Loads any plugins that were specified using the `--plugin` flag. | +| 14. | (config files) (plugin) | Processes the signatures in the user's `plugin.msgpackz` (located in the configuration directory) so that added plugins can be used in the following config files. | +| 15. | (config files) | If this is the first time Nushell has been launched, then it creates the configuration directory. "First launch" is determined by whether or not the configuration directory exists. | +| 16. | (config files) | Also, if this is the first time Nushell has been launched, creates a mostly empty (other than a few comments) `env.nu` and `config .nu` in that directory. | +| 17. | (config files) (default_env.nu) | Loads default environment variables from the internal `default_env.nu`. This file can be viewed with: `nu config env --default \| nu-highlight \| less -R`. | +| 18. | (config files) (env.nu) | Converts the `PATH` variable into a list so that it can be accessed more easily in the next step. | +| 19. | (config files) (env.nu) | Loads (parses and evaluates) the user's `env.nu` (the path to which was determined above). | +| 20. | (config files) (config.nu) | Processes any `ENV_CONVERSIONS` that were defined in the user's `env.nu` so that those environment variables can be treated as Nushell structured data in the `config.nu`. | +| 21. | (config files) (config.nu) | Loads a minimal `$env.config` record from the internal `default_config.nu`. This file can be viewed with: `nu config nu --default \| nu-highlight \| less -R`. Most values that are not defined in `default_config.nu` will be auto-populated into `$env.config` using their internal defaults as well. | +| 22. | (config files) (config.nu) | Loads (parses and evaluates) the user's `config.nu` (the path to which was determined above). | +| 23. | (config files) (login) | When Nushell is running as a login shell, loads the user's `login.nu`. | +| 24. | (config files) | Loops through autoload directories and loads any `.nu` files found. The directories are processed in the order found in `$nu.vendor-autoload-directories`, and files in those directories are processed in alphabetical order. | +| 25. | (repl) | Processes any additional `ENV_CONVERSIONS` that were defined in `config.nu` or the autoload files. | +| 26. | (repl) and (stdlib) | Shows the banner if configured. | +| 27. | (repl) | Nushell enters the normal commandline (REPL). | + +### Flag Behavior + +| Mode | Command/Flags | Behavior | +| ------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Normal Shell | `nu` (no flags) | All launch steps **_except_** those marked with **_(login)_** occur. | +| Login Shell | `nu --login/-l` | All launch steps occur. | +| Command-string | `nu --commands ` (or `-c`) | All Launch stages **_except_** those marked with **_(config files)_** or **_(repl)_** occur. However, **_(default_env)_** and **_(plugin)_** do occur. The first allows the path `ENV_CONVERSIONS` defined there can take place. The second allows plugins to be used in the command-string. | +| Script file | `nu ` | Same as with Command-string. | +| No config | `nu -n` | **_(config files)_** stages do **_not_** occur, regardless of other flags. | +| No Standard Library | `nu --no-std-lib` | Regardless of other flags, the steps marked **_(stdlib)_** will **_not_** occur. | +| Force config file | `nu --config ` | Forces steps marked with **_(config.nu)_** above to run with the provided config ``, unless `-n` was also specified | +| Force env file | `nu --env-config ` | Forces steps marked with **_(default_env.nu)_** and **_(env.nu)_** above to run with the specified env ``, unless `-n` was also specified | + +### Scenarios + +- `nu`: + + - ✅ Makes the Standard Library available + - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory + - ✅ Sources the `default_env.nu` file internally + - ✅ Sources the user's `env.nu` file if it exists in the config directory + - ✅ Sources the `default_config.nu` file internally + - ✅ Sources user's `config.nu` file if it exists if it exists in the config directory + - ❌ Does not read `personal login.nu` file + - ✅ Enters the REPL + +- `nu -c "ls"`: + + - ✅ Makes the Standard Library available + - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory + - ✅ Sources the `default_env.nu` file internally + - ❌ Does not source the user's `env.nu` + - ❌ Does not read the internal `default_config.nu` file + - ❌ Does not read the user's `config.nu` file + - ❌ Does not read the user's `login.nu` file + - ✅ Runs the `ls` command and exits + - ❌ Does not enter the REPL + +- `nu -l -c "ls"`: + + - ✅ Makes the Standard Library available + - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory + - ✅ Sources the `default_env.nu` file internally + - ✅ Sources the user's `env.nu` file if it exists in the config directory + - ✅ Sources the `default_config.nu` file internally + - ✅ Sources user's `config.nu` file if it exists in the config directory + - ✅ Sources the user's `login.nu` file if it exists in the config directory + - ✅ Runs the `ls` command and exits + - ❌ Does not enter the REPL + +- `nu -l -c "ls" --config foo_config.nu` + + - Same as above, but reads an alternative config file named `foo_config.nu` from the config directory + +- `nu -n -l -c "ls"`: + + - ✅ Makes the Standard Library available + - ❌ Does not read user's `plugin.msgpackz` + - ❌ Does not read the internal `default_env.nu` + - ❌ Does not source the user's `env.nu` + - ❌ Does not read the internal `default_config.nu` file + - ❌ Does not read the user's `config.nu` file + - ❌ Does not read the user's `login.nu` file + - ✅ Runs the `ls` command and exits + - ❌ Does not enter the REPL + +- `nu test.nu`: + + - ✅ Makes the Standard Library available + - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory + - ✅ Sources the `default_env.nu` file internally + - ❌ Does not source the user's `env.nu` + - ❌ Does not read the internal `default_config.nu` file + - ❌ Does not read the user's `config.nu` file + - ❌ Does not read the user's `login.nu` file + - ✅ Runs `test.nu` file as a script + - ❌ Does not enter the REPL + +- `nu --config foo_config.nu test.nu` + + - ✅ Makes the Standard Library available + - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory + - ✅ Sources the `default_env.nu` file internally + - ❌ Does not source the user's `env.nu` (no `--env-config` was specified) + - ✅ Sources the `default_config.nu` file internally. Note that `default_config.nu` is always handled before a user's config + - ✅ Sources user's `config.nu` file if it exists in the config directory + - ❌ Does not read the user's `login.nu` file + - ✅ Runs `test.nu` file as a script + - ❌ Does not enter the REPL + +- `nu -n --no-std-lib` (fastest REPL startup): + + - ❌ Does not make the Standard Library available + - ❌ Does not read user's `plugin.msgpackz` + - ❌ Does not read the internal `default_env.nu` + - ❌ Does not source the user's `env.nu` + - ❌ Does not read the internal `default_config.nu` file + - ❌ Does not read the user's `config.nu` file + - ❌ Does not read the user's `login.nu` file + - ✅ Enters the REPL + +- `nu -n --no-std-lib -c "ls"` (fastest command-string invocation): + + - ❌ Does not make the Standard Library available + - ❌ Does not read user's `plugin.msgpackz` + - ❌ Does not read the internal `default_env.nu` + - ❌ Does not source the user's `env.nu` + - ❌ Does not read the internal `default_config.nu` file + - ❌ Does not read the user's `config.nu` file + - ❌ Does not read the user's `login.nu` file + - ✅ Runs the `ls` command and exits + - ❌ Does not enter the REPL diff --git a/book/configuration_preview.md b/book/configuration_preview.md deleted file mode 100644 index f0f3c79dede..00000000000 --- a/book/configuration_preview.md +++ /dev/null @@ -1,671 +0,0 @@ -# Configuration - -## Quickstart - -While Nushell provides many options for managing its startup and configuration, new users -can get started with just a few simple steps: - -1. Tell Nushell what editor to use: - - ```nu - $env.config.buffer_editor = - ``` - -2. Edit `config.nu` using: - - ```nu - config nu - ``` - - This will open the current `config.nu` in the editor defined above. - -3. Add commands to this file that should run each time Nushell starts. A good first example might be the `buffer_editor` setting above. - - You can find a detailed list of available settings using: - - ```nu - config nu --sample | nu-highlight | less -R - config env --sample | nu-highlight | less -R - ``` - -4. Save, exit the editor, and start a new Nushell session to load these settings. - -That's it! More details are below when you need them ... - ---- - -[[toc]] - -::: tip -To view a simplified version of this documentation from inside Nushell, run: - -```nu -config env --sample | nu-highlight | less -R -config nu --sample | nu-highlight | less -R -``` - -::: - -## Configuration Overview - -Nushell uses multiple, optional configuration files. These files are loaded in the following order: - -1. `env.nu` is typically used to define or override environment variables. -2. `config.nu` is typically used to override default Nushell settings, define (or import) custom commands, or run any other startup tasks. -3. Files in `$nu.vendor-autoload-dirs` are loaded. These files can be used for any purpose and are a convenient way to modularize a configuration. -4. `login.nu` runs commands or handles configuration that should only take place when Nushell is running as a login shell. - -By default, `env.nu`, `config.nu`, and `login.nu` are read from the `$nu.default-config-dir` directory. For example: - -```nu -$nu.default-config-dir -# macOS -# => /Users/me/Library/Application Support/nushell -# Linux -# => /home/me/.config/nushell -# Windows -# => C:\Users\me\AppData\Roaming\nushell -``` - -The first time Nushell is launched, it will create the configuration directory and an empty (other than comments) `env.nu` and `config.nu`. - -::: tip -You can quickly open `config.nu` in your default text editor using the `config nu` command. Likewise, the `config env` command will open `env.nu`. - -This requires that you have configured a default editor using either: - -- Nushell's `$env.config.buffer_editor` setting -- The `$env.VISUAL` or `$env.EDITOR` environment variables - -For example, place this in your `config.nu` to edit your files in Visual Studio Code: - -```nu -$env.config.buffer_editor = 'code' -``` - -::: - -## Common Configuration Tasks in `env.nu`: - -::: tip See Also -The [Environment](./environment.md) Chapter covers additional information on how to set and access environment variables. -::: - -### Path Configuration - -As with most shells, Nushell searches the environment variable named `PATH` (or variants). -The `env.nu` file is often used to add (and sometimes remove) directories on the path. - -:::tip -Unlike some shells, Nushell attempts to be "case agnostic" with environment variables. `Path`, `path`, `PATH`, and even `pAtH` are all allowed variants of the same environment variable. See [Environment - Case Sensitivity](./environment.md#case-sensitivity) for details. -::: - -When Nushell is launched, it usually inherits the `PATH` as a string. However, Nushell automatically converts this to a Nushell list for easy access. This means that you can _append_ to -the path using, for example: - -```nu -$env.path ++= ["~/.local/bin"] -``` - -The Standard Library also includes a helper command. The default `path add` behavior is to _prepend_ -a directory so that it has higher precedence than the rest of the path. For example, the following can be -added to `env.nu`: - -```nushell -use std/util "path add" -path add "~/.local/bin" -path add ($env.CARGO_HOME | path join "bin") -``` - -::: tip -Notice the use of `path join` in the example above. This command properly joins two path -components regardless of whether or not the path separator is present. See `help path` for -more commands in this category. -::: - -### Prompt Configuration - -Nushell provides a number of prompt configuration options. By default, Nushell includes: - -- A prompt which includes the current directory, abbreviated using `~` if it is (or is under) - the home directory. -- A prompt indicator which appears immediately to the right of the prompt. This defaults to `> ` when in normal editing mode, or a `: ` when in Vi-insert mode. Note - extra space after the character to provide separation of the command from the prompt. -- A right-prompt with the date and time -- An indicator which is displayed when the current commandline extends over multiple lines - `::: ` by default - -The environment variables which control these prompt components are: - -- `$env.PROMPT_COMMAND`: The prompt itself -- `$env.PROMPT_COMMAND_RIGHT`: A prompt which can appear on the right side of the terminal -- `$env.PROMPT_INDICATOR`: Emacs mode indicator -- `$env.PROMPT_INDICATOR_VI_NORMAL`: Vi-normal mode indicator -- `$env.PROMPT_INDICATOR_VI_INSERT`: Vi-insert mode indicator -- `$env.PROMPT_MULTILINE_INDICATOR`: The multi-line indicator - -Each of these variables accepts either: - -- A string, in which case the component will be statically displayed as that string. -- A closure (with no parameters), in which case the component will be dynamically displayed based on the closure's code. -- `null`, in which case the component will revert to its internal default value. - -::: tip -To disable the right-prompt, for instance, add the following to `env.nu`: - -```nu -$env.PROMPT_COMMAND_RIGHT = "" -# or -$env.PROMPT_COMMAND_RIGHT = {||} -``` - -::: - -#### Transient Prompts - -Nushell also supports transient prompts, which allow a different prompt to be shown _after_ a commandline has been executed. This can be useful in several situations: - -- When using a multi-line prompt, the transient prompt can be a more condensed version. -- Removing the transient multiline indicator and right-prompt can simplify copying from the terminal. - -As with the normal prompt commands above, each transient prompt can accept a (static) string, a (dynamic) closure, or a `null` to use the Nushell internal defaults. - -The environment variables which control the transient prompt components are: - -- `$env.TRANSIENT_PROMPT_COMMAND`: The prompt itself after the commandline has been executed -- `$env.TRANSIENT_PROMPT_COMMAND_RIGHT`: A prompt which can appear on the right side of the terminal -- `$env.TRANSIENT_PROMPT_INDICATOR`: Emacs mode indicator -- `$env.TRANSIENT_PROMPT_INDICATOR_VI_NORMAL`: Vi-normal mode indicator -- `$env.TRANSIENT_PROMPT_INDICATOR_VI_INSERT`: Vi-insert mode indicator -- `$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR`: The multi-line indicator - -### ENV_CONVERSIONS - -Certain variables, such as those containing multiple paths, are often stored as a -colon-separated string in other shells. Nushell can convert these automatically to a -more convenient Nushell list. The ENV_CONVERSIONS variable specifies how environment -variables are: - -- converted from a string to a value on Nushell startup (from_string) -- converted from a value back to a string when running external commands (to_string) - -`ENV_CONVERSIONS` is a record, where: - -- each key is an environment variable to be converted -- each value is another record containing a: - ```nu - { - from_string: - to_string: - } - ``` - -::: tip -The OS Path variable is automatically converted before `env.nu` loads. As a result, it can be treated as a list within `env.nu`. This conversion is handled via an initial, pre-defined `$env.ENV_CONVERSIONS` of: - -```nu -$env.ENV_CONVERSIONS = { - "Path": { - from_string: { |s| $s | split row (char esep) | path expand --no-symlink } - to_string: { |v| $v | path expand --no-symlink | str join (char esep) } - } -} - -``` - -Note that environment variables are not case-sensitive in Nushell, so the above will work -for both Windows and Unix-like platforms. -::: - -To add an additional conversion, [`merge`](/commands/docs/merge.md) it into the `$env.ENV_CONVERSIONS` record. For example, to add a conversion for the `XDG_DATA_DIRS` variable: - -```nu -$env.ENV_CONVERSIONS = $env.ENV_CONVERSIONS | merge { - "XDG_DATA_DIRS": { - from_string: { |s| $s | split row (char esep) | path expand --no-symlink } - to_string: { |v| $v | path expand --no-symlink | str join (char esep) } - } -} -``` - -### `LS_COLORS` - -As with many `ls`-like utilities, Nushell's directory listings make use of the `LS_COLORS` environment variable for defining styles/colors to apply to certain file types and patterns. - -### Additional `$env.nu` Notes - -While `env.nu` is typically used for environment variable configuration, this is purely by convention. Environment variables can be set in _any_ -of the available configuration files. Likewise, `env.nu` can be used for any purpose, if desired. - -There are several configuration tasks where `env.nu` has advantages: - -1. As mentioned above, `$env.ENV_CONVERSIONS` can be defined in `env.nu` to translate certain environment variables to (and from) Nushell structured data types. In order to treat these variables as structured-data in `config.nu`, then conversion needs to be defined in `env.nu`. - -2. Modules or source files that are written or modified during `env.nu` can be imported or evaluated during `config.nu`. This is a fairly advanced, uncommon - technique. - -## Common Configuration Tasks in `config.nu` - -The primary purpose of `config.nu` is to: - -- Override default Nushell settings in the `$env.config` record -- Define or import custom commands -- Run other startup tasks - -::: tip -Some users will prefer a "monolithic" configuration file with most or all startup tasks in one place. `config.nu` can be used for this purpose. - -Other users may prefer a "modular" configuration where each file handles a smaller, more focused set of tasks. Files in the autoload dirs can be used to create this experience. -::: - -### Changing Settings in the `$env.config` Record - -The primary mechanism for changing Nushell's behavior is the `$env.config` record. While this record is accessed as an environment variable, unlike most other variables it is: - -- Not inherited from the parent process. Instead, it is populated by Nushell itself with certain defaults. -- Not exported to child processes started by Nushell. - -To examine the current settings in `$env.config`, just type the variable name: - -```nu -$env.config -``` - -::: tip -Since Nushell provides so many customization options, it may be better to send this to a pager like: - -```nu -$env.config | table -e | less -R -# or, if bat is installed: -$env.config | table -e | bat -p -``` - -::: - -An appendix documenting each setting will be available soon. In the meantime, abbreviated documentation on each setting can be -viewed in Nushell using: - -```nu -config nu --sample | nu-highlight | bat -# or -config nu --sample | nu-highlight | less -R -``` - -To avoid overwriting existing settings, it's best to simply assign updated values to the desired configuration keys, rather than the entire `config` record. In other words: - -::: warning Wrong - -```nu -$env.config = { - show_banner: false -} -``` - -This would reset any _other_ settings that had been changed, since the entire record would be overwritten. -::: - -::: tip Right - -```nu -$env.config.show_banner = false -``` - -This changes _only_ the `show_banner` key/value pair, leaving all other keys with their existing values. -::: - -Certain keys are themselves also records. It's okay to overwrite these records, but it's best-practice -to set all values when doing so. For example: - -```nu -$env.config.history = { - file_format: sqlite - max_size: 1_000_000 - sync_on_enter: true - isolation: true -} -``` - -### Remove Welcome Message - -:::note -This section is linked directly from the banner message, so it repeats some information from above. -::: - -To remove the welcome message that displays each time Nushell starts: - -1. Type `config nu` to edit your configuration file. -2. If you receive an error regarding the editor not being defined: - - ```nu - $env.config.buffer_editor = - # Such as: - $env.config.buffer_editor = "code" - $env.config.buffer_editor = "vi" - # Or with editor arguments: - $env.config.buffer_editor: ["emacsclient", "-s", "light", "-t"], - ``` - - Then repeat step 1. - -3. Add the following line to the end of the file: - - ```nu - $env.config.show_banner = false - ``` - -4. Save and exit your editor. -5. Restart Nushell to test the change. - -## Additional Startup Configuration - -### Changing default directories - -::: warning Important -As discussed below, variables in this section must be set **before** Nushell is launched. -::: - -Some variables that control Nushell startup file locations must be set **before** Nushell is loaded. This is often done by a parent process such as: - -- The terminal application in which Nushell is run - -- The operating system or window manager. When running Nushell as a login shell, this will likely be the only mechanism available. - - For example, on Windows, you can set environment variables through the Control Panel. Choose the Start Menu and search for _"environment variables"_. - - On Linux systems using PAM, `/etc/environment` (and other system-specific mechanisms) can be used. - -- A parent shell. For example, exporting the value from `bash` before running `nu`. - -### Startup Variables - -The variables that affect Nushell file locations are: - -- `$env.XDG_CONFIG_HOME`: If this environment variable is set, it is used to change the directory that Nushell searches for its configuration files such as `env.nu`, `config.nu`, and `login.nu`. The history and plugin files are also stored in this directory by default. - - Once Nushell starts, this value is stored in the `$nu.default-config-path` constant. See [Using Constants](#using-constants) below. - -- `$env.XDG_DATA_HOME`: If this environment variable is set, Nushell sets the `$nu.data-dir` constant to this value. The `data-dir` is used in several startup tasks: - - - `($nu.data-dir)/nushell/completions` is added to the `$env.NU_LIB_DIRS` search path. - - `($nu.data-dir)/vendor/autoloads` is added as the last path in `nu.vendor-autoload-dirs`. This means that files in this directory will be read last during startup (and thus override any definitions made in earlier files). - - Note that the directory represented by `$nu.data-dir`, nor any of its subdirectories, are created by default. Creation and use of these directories is up to the user. - -- `$env.XDG_DATA_DIRS` _(Unix Platforms Only)_: If this environment variable is set, it is used to populate the `$nu.vendor-auto-load` directories in the order listed. The first directory in the list is processed first, meaning the last one read will have the ability to override previous definitions. - -::: warning -The `XDG_*` variables are **not** Nushell-specific and should not be set to a directory with only Nushell files. Instead, set the environment variable to the directory _above_ the one with the `nushell` directory. - -For example, if you set `$env.XDG_CONFIG_HOME` to: - -``` -/users/username/dotfiles/nushell -``` - -... Nushell will look for config files in `/Users/username/dotfiles/nushell/nushell`. The proper setting would be: - -``` -/users/username/dotfiles -``` - -Also keep in mind that if the system has already set `XDG` variables, then there may already be files in use in those directories. Changing the location may require that you move other application's files to the new directory. -::: - -::: tip -You can easily test out config changes in a "fresh" environment using the following recipe. The following is run from inside Nushell, but can be -adapted to other shells as well: - -```nu -# Create an empty temporary directory -let temp_home = (mktemp -d) -# Set the configuration path to this directory -$env.XDG_CONFIG_HOME = $temp_home -# Set the data-dir to this directory -$env.XDG_DATA_HOME = $temp_home -# Remove other potential autoload directories -$env.XDG_DATA_DIRS = "" -# Run Nushell in this environment -nu - -# Edit config -config nu -# Exit the subshell -exit -# Run the temporary config -nu -``` - -When done testing the configuration: - -```nu -# Remove the temporary config directory, if desired -rm $temp_home -``` - -**Important:** Then exit the parent shell so that the `XDG` changes are not accidentally propagated to other processes. -::: - -### Using Constants - -Some important commands, like `source` and `use`, that help define custom commands (and other definitions) are parse-time keywords. Along other things, this means means that all arguments must be known at parse-time. - -In other words, **_variable arguments are not allowed for parser keywords_**. - -However, Nushell creates some convenience _constants_ that can be used to help identify common file locations. For instance, you can source a file in the default configuration directory using: - -``` -source ($nu.default-config-dir | path join "myfile.nu") -``` - -Because the constant value is known at parse-time, it can be used with parse-time keywords like `source` and `use`. - -To see a list of the built-in Nushell constants, examine the record constant using `$nu` (including the dollar sign). - -Nushell can also make use of a `NU_LIB_DIRS` _constant_ which can act like the `$env.NU_LIB_DIRS` variable mentioned above. However, unlike `$env.NU_LIB_DIRS`, it can be defined _and_ used in `config.nu`. For example: - -```nu -# Define module and source search path -const NU_LIB_DIRS = [ - '~/myscripts' -] -# Load myscript.nu from the ~/myscripts directory -source myscript.nu -``` - -If both the variable `$env.NU_LIB_DIRS` and the const `NU_LIB_DIRS` are defined, both sets -of paths will be searched. The constant `NU_LIB_DIRS` will be searched _first_ and have -precedence. If a file matching the name is found in one of those directories, the search will -stop. Otherwise, it will continue into the `$env.NU_LIB_DIRS` search path. - -### Colors, Theming, and Syntax Highlighting - -You can learn more about setting up colors and theming in the [associated chapter](coloring_and_theming.md). - -### Configuring Nu as a Login Shell - -The login shell is often responsible for setting certain environment variables which will be inherited by subshells and other processes. When setting Nushell as a user's default login shell, you'll want to make sure that the `login.nu` handles this task. - -Many applications will assume a POSIX or PowerShell login shell, and will either provide instructions for modifying the system or user `profile` that is loaded by POSIX login-shells (or `.ps1` file on PowerShell systems). - -As you may have noticed by now, Nushell is not a POSIX shell, nor is it PowerShell, and it won't be able to process a profile written for these. You'll need to set these values in `login.nu` instead. - -To find environment variables that may need to be set through `login.nu`, examine the inherited environment from your login shell by running `nu` from within your previous login shell. Run: - -```nu -$env | reject config | transpose key val | each {|r| echo $"$env.($r.key) = '($r.val)'"} | str join (char nl) -``` - -Look for any values that may be needed by third-party applications and copy these to your `login.nu`. Many of these will not be needed. For instance, the `PS1` setting is the current prompt in POSIX shells and won't be useful in Nushell. - -When ready, add Nushell to your `/etc/shells` (Unix) and `chsh` as discussed in [the Installation Chapter](./default_shell.md). - -### macOS: Keeping `/usr/bin/open` as `open` - -Some tools such as Emacs rely on an [`open`](/commands/docs/open.md) command to open files on Mac. - -Since Nushell has its own [`open`](/commands/docs/open.md) command with a different meaning which shadows (overrides) `/usr/bin/open`, these tools will generate an error when trying to use the command. - -One way to work around this is to define a custom command for Nushell's [`open`](/commands/docs/open.md) and create an alias for the system's [`open`](/commands/docs/open.md) in your `config.nu` file like this: - -```nu -alias nu-open = open -alias open = ^open -``` - -Place this in your `config.nu` to make it permanent. - -The `^` symbol tells Nushell to run the following command as an _external_ command, rather than as a Nushell built-in. After running these commands, `nu-open` will be the Nushell _internal_ version, and the `open` alias will call the Mac, external `open` instead. - -For more information, see [Running System (External) Commands](./running_externals.md). - -## Detailed Configuration Startup Process - -This section contains a more detailed description of how different configuration (and flag) options can be used to -change Nushell's startup behavior. - -### Launch Stages - -The following stages and their steps _may_ occur during startup, based on the flags that are passed to `nu`. See [Flag Behavior](#flag-behavior) immediately following this table for how each flag impacts the process: - -| Step | Stage | Nushell Action | -| ---- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 0. | (misc) | Sets internal defaults via its internal Rust implementation. In practice, this may not take place until "first use" of the setting or variable, but there will typically be a Rust default for most (but not all) settings and variables that control Nushell's behavior. These defaults can then be superseded by the steps below. | -| 1. | (main) | Inherits its initial environment from the calling process. These will initially be converted to Nushell strings, but can be converted to other structures later using `ENV_CONVERSIONS` (see below). | -| 2. | (main) | Gets the configuration directory. This is OS-dependent (see [dirs::config_dir](https://docs.rs/dirs/latest/dirs/fn.config_dir.html)), but can be overridden using `XDG_CONFIG_HOME` on all platforms as discussed [above](#changing-default-directories). | -| 3. | (main) | Creates the initial `$env.NU_LIB_DIRS` variable. By default, it includes (1) the `scripts` directory under the configuration directory, and (2) `nushell/completions` under the default data directory (either `$env.XDG_DATA_HOME` or [the default provided by the dirs crate](https://docs.rs/dirs/latest/dirs/fn.data_dir.html)). These directories are not created by default. | -| 4. | (main) | Creates the initial `$env.NU_PLUGIN_DIRS` variable. By default, this will include the configuration directory. | -| 5. | (main) | Initializes the in-memory SQLite database. This allows the `stor` family of commands to be used in the following configuration files. | -| 6. | (main) | Processes commandline arguments such as `--plugin-config `, `--plugins `, and others. See `nu --help` for a complete list. | -| 7. | (main) | Gets the path to `env.nu` and `config.nu`. By default, these are located in the config directory, but either or both can be overridden using the `--env-config ` and `--config ` flags. | -| 8. | (main) | If the `--include-path (-I)` flag was used, it overrides the default `$env.NU_LIB_DIRS` that was obtained above. | -| 9. | (main) | Loads the initial `$env.config` values from the internal defaults. | -| 10. | (stdlib) | Loads the [Standard Library](./standard_library.md) into the virtual filesystem. It is not parsed or evaluated at this point. | -| 11. | (stdlib) | Parses and evaluates `std/core`, which brings the `banner` and `pwd` commands into scope. | -| 12. | (main) | Generates the initial [`$nu` record constant](#using-constants) so that items such as `$nu.default-config-dir` can be used in the following config files. | -| 13. | (main) | Loads any plugins that were specified using the `--plugin` flag. | -| 14. | (config files) (plugin) | Processes the signatures in the user's `plugin.msgpackz` (located in the configuration directory) so that added plugins can be used in the following config files. | -| 15. | (config files) | If this is the first time Nushell has been launched, then it creates the configuration directory. "First launch" is determined by whether or not the configuration directory exists. | -| 16. | (config files) | Also, if this is the first time Nushell has been launched, creates a mostly empty (other than a few comments) `env.nu` and `config .nu` in that directory. | -| 17. | (config files) (default_env.nu) | Loads default environment variables from the internal `default_env.nu`. This file can be viewed with: `nu config env --default \| nu-highlight \| less -R`. | -| 18. | (config files) (env.nu) | Converts the `PATH` variable into a list so that it can be accessed more easily in the next step. | -| 19. | (config files) (env.nu) | Loads (parses and evaluates) the user's `env.nu` (the path to which was determined above). | -| 20. | (config files) (config.nu) | Processes any `ENV_CONVERSIONS` that were defined in the user's `env.nu` so that those environment variables can be treated as Nushell structured data in the `config.nu`. | -| 21. | (config files) (config.nu) | Loads a minimal `$env.config` record from the internal `default_config.nu`. This file can be viewed with: `nu config nu --default \| nu-highlight \| less -R`. Most values that are not defined in `default_config.nu` will be auto-populated into `$env.config` using their internal defaults as well. | -| 22. | (config files) (config.nu) | Loads (parses and evaluates) the user's `config.nu` (the path to which was determined above). | -| 23. | (config files) (login) | When Nushell is running as a login shell, loads the user's `login.nu`. | -| 24. | (config files) | Loops through autoload directories and loads any `.nu` files found. The directories are processed in the order found in `$nu.vendor-autoload-directories`, and files in those directories are processed in alphabetical order. | -| 25. | (repl) | Processes any additional `ENV_CONVERSIONS` that were defined in `config.nu` or the autoload files. | -| 26. | (repl) and (stdlib) | Shows the banner if configured. | -| 27. | (repl) | Nushell enters the normal commandline (REPL). | - -### Flag Behavior - -| Mode | Command/Flags | Behavior | -| ------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Normal Shell | `nu` (no flags) | All launch steps **_except_** those marked with **_(login)_** occur. | -| Login Shell | `nu --login/-l` | All launch steps occur. | -| Command-string | `nu --commands ` (or `-c`) | All Launch stages **_except_** those marked with **_(config files)_** or **_(repl)_** occur. However, **_(default_env)_** and **_(plugin)_** do occur. The first allows the path `ENV_CONVERSIONS` defined there can take place. The second allows plugins to be used in the command-string. | -| Script file | `nu ` | Same as with Command-string. | -| No config | `nu -n` | **_(config files)_** stages do **_not_** occur, regardless of other flags. | -| No Standard Library | `nu --no-std-lib` | Regardless of other flags, the steps marked **_(stdlib)_** will **_not_** occur. | -| Force config file | `nu --config ` | Forces steps marked with **_(config.nu)_** above to run with the provided config ``, unless `-n` was also specified | -| Force env file | `nu --env-config ` | Forces steps marked with **_(default_env.nu)_** and **_(env.nu)_** above to run with the specified env ``, unless `-n` was also specified | - -### Scenarios - -- `nu`: - - - ✅ Makes the Standard Library available - - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory - - ✅ Sources the `default_env.nu` file internally - - ✅ Sources the user's `env.nu` file if it exists in the config directory - - ✅ Sources the `default_config.nu` file internally - - ✅ Sources user's `config.nu` file if it exists if it exists in the config directory - - ❌ Does not read `personal login.nu` file - - ✅ Enters the REPL - -- `nu -c "ls"`: - - - ✅ Makes the Standard Library available - - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory - - ✅ Sources the `default_env.nu` file internally - - ❌ Does not source the user's `env.nu` - - ❌ Does not read the internal `default_config.nu` file - - ❌ Does not read the user's `config.nu` file - - ❌ Does not read the user's `login.nu` file - - ✅ Runs the `ls` command and exits - - ❌ Does not enter the REPL - -- `nu -l -c "ls"`: - - - ✅ Makes the Standard Library available - - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory - - ✅ Sources the `default_env.nu` file internally - - ✅ Sources the user's `env.nu` file if it exists in the config directory - - ✅ Sources the `default_config.nu` file internally - - ✅ Sources user's `config.nu` file if it exists in the config directory - - ✅ Sources the user's `login.nu` file if it exists in the config directory - - ✅ Runs the `ls` command and exits - - ❌ Does not enter the REPL - -- `nu -l -c "ls" --config foo_config.nu` - - - Same as above, but reads an alternative config file named `foo_config.nu` from the config directory - -- `nu -n -l -c "ls"`: - - - ✅ Makes the Standard Library available - - ❌ Does not read user's `plugin.msgpackz` - - ❌ Does not read the internal `default_env.nu` - - ❌ Does not source the user's `env.nu` - - ❌ Does not read the internal `default_config.nu` file - - ❌ Does not read the user's `config.nu` file - - ❌ Does not read the user's `login.nu` file - - ✅ Runs the `ls` command and exits - - ❌ Does not enter the REPL - -- `nu test.nu`: - - - ✅ Makes the Standard Library available - - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory - - ✅ Sources the `default_env.nu` file internally - - ❌ Does not source the user's `env.nu` - - ❌ Does not read the internal `default_config.nu` file - - ❌ Does not read the user's `config.nu` file - - ❌ Does not read the user's `login.nu` file - - ✅ Runs `test.nu` file as a script - - ❌ Does not enter the REPL - -- `nu --config foo_config.nu test.nu` - - - ✅ Makes the Standard Library available - - ✅ Reads user's `plugin.msgpackz` file if it exists in the config directory - - ✅ Sources the `default_env.nu` file internally - - ❌ Does not source the user's `env.nu` (no `--env-config` was specified) - - ✅ Sources the `default_config.nu` file internally. Note that `default_config.nu` is always handled before a user's config - - ✅ Sources user's `config.nu` file if it exists in the config directory - - ❌ Does not read the user's `login.nu` file - - ✅ Runs `test.nu` file as a script - - ❌ Does not enter the REPL - -- `nu -n --no-std-lib` (fastest REPL startup): - - - ❌ Does not make the Standard Library available - - ❌ Does not read user's `plugin.msgpackz` - - ❌ Does not read the internal `default_env.nu` - - ❌ Does not source the user's `env.nu` - - ❌ Does not read the internal `default_config.nu` file - - ❌ Does not read the user's `config.nu` file - - ❌ Does not read the user's `login.nu` file - - ✅ Enters the REPL - -- `nu -n --no-std-lib -c "ls"` (fastest command-string invocation): - - - ❌ Does not make the Standard Library available - - ❌ Does not read user's `plugin.msgpackz` - - ❌ Does not read the internal `default_env.nu` - - ❌ Does not source the user's `env.nu` - - ❌ Does not read the internal `default_config.nu` file - - ❌ Does not read the user's `config.nu` file - - ❌ Does not read the user's `login.nu` file - - ✅ Runs the `ls` command and exits - - ❌ Does not enter the REPL diff --git a/book/control_flow.md b/book/control_flow.md index e9e4625cc3b..e2c3c5e5ef1 100644 --- a/book/control_flow.md +++ b/book/control_flow.md @@ -25,8 +25,8 @@ The following commands execute code based on some given condition. The choice/conditional commands are expressions so they return values, unlike the other commands on this page. This means the following works. ```nu -> 'foo' | if $in == 'foo' { 1 } else { 0 } | $in + 2 -3 +'foo' | if $in == 'foo' { 1 } else { 0 } | $in + 2 +# => 3 ``` ::: @@ -36,7 +36,7 @@ The choice/conditional commands are expressions so they return values, unlike th [`if`](/commands/docs/if.html) evaluates branching [blocks](/book/types_of_data.html#blocks) of code based on the results of one or more conditions similar to the "if" functionality in other programming languages. For example: ```nu -> if $x > 0 { 'positive' } +if $x > 0 { 'positive' } ``` Returns `'positive`' when the condition is `true` (`$x` is greater than zero) and `null` when the condition is `false` (`$x` is less than or equal to zero). @@ -44,7 +44,7 @@ Returns `'positive`' when the condition is `true` (`$x` is greater than zero) an We can add an `else` branch to the `if` after the first block which executes and returns the resulting value from the `else` block when the condition is `false`. For example: ```nu -> if $x > 0 { 'positive' } else { 'non-positive' } +if $x > 0 { 'positive' } else { 'non-positive' } ``` This time it returns `'positive'` when the condition is `true` (`$x` is greater than zero) and `'non-positive`' when the condition is `false` (`$x` is less than or equal to zero). @@ -52,7 +52,7 @@ This time it returns `'positive'` when the condition is `true` (`$x` is greater We can also chain multiple `if`s together like the following: ```nu -> if $x > 0 { 'positive' } else if $x == 0 { 'zero' } else { "negative" } +if $x > 0 { 'positive' } else if $x == 0 { 'zero' } else { "negative" } ``` When the first condition is `true` (`$x` is greater than zero) it will return `'positive'`, when the first condition is `false` and the next condition is `true` (`$x` equals zero) it will return `'zero'`, otherwise it will return `'negative'` (when `$x` is less than zero). @@ -64,7 +64,7 @@ When the first condition is `true` (`$x` is greater than zero) it will return `' Basic usage of [`match`](/commands/docs/match.html) can conditionally run different code like a "switch" statement common in other languages. [`match`](/commands/docs/match.html) checks if the value after the word [`match`](/commands/docs/match.html) is equal to the value at the start of each branch before the `=>` and if it does, it executes the code after that branch's `=>`. ```nu -> match 3 { +match 3 { 1 => 'one', 2 => { let w = 'w' @@ -73,7 +73,7 @@ Basic usage of [`match`](/commands/docs/match.html) can conditionally run differ 3 => 'three', 4 => 'four' } -three +# => three ``` The branches can either return a single value or, as shown in the second branch, can return the results of a [block](/book/types_of_data.html#blocks). @@ -83,14 +83,14 @@ The branches can either return a single value or, as shown in the second branch, You can also have a catch all condition for when the given value doesn't match any of the other conditions by having a branch whose matching value is `_`. ```nu -> let foo = match 7 { +let foo = match 7 { 1 => 'one', 2 => 'two', 3 => 'three', _ => 'other number' } -> $foo -other number +$foo +# => other number ``` (Reminder, [`match`](/commands/docs/match.html) is an expression which is why we can assign the result to `$foo` here). @@ -100,13 +100,13 @@ other number You can "unpack" values from types like lists and records with [pattern matching](/cookbook/pattern_matching.html). You can then assign variables to the parts you want to unpack and use them in the matched expressions. ```nu -> let foo = { name: 'bar', count: 7 } -> match $foo { +let foo = { name: 'bar', count: 7 } +match $foo { { name: 'bar', count: $it } => ($it + 3), { name: _, count: $it } => ($it + 7), _ => 1 } -10 +# => 10 ``` The `_` in the second branch means it matches any record with field `name` and `count`, not just ones where `name` is `'bar'`. @@ -116,13 +116,13 @@ The `_` in the second branch means it matches any record with field `name` and ` You can also add an additional condition to each branch called a "guard" to determine if the branch should be matched. To do so, after the matched pattern put `if` and then the condition before the `=>`. ```nu -> let foo = { name: 'bar', count: 7 } -> match $foo { +let foo = { name: 'bar', count: 7 } +match $foo { { name: 'bar', count: $it } if $it < 5 => ($it + 3), { name: 'bar', count: $it } if $it >= 5 => ($it + 7), _ => 1 } -14 +# => 14 ``` --- @@ -138,22 +138,22 @@ The loop commands allow you to repeat a block of code multiple times. The functionality of the loop commands is similar to commands that apply a closure over elements in a list or table like [`each`](/commands/docs/each.html) or [`where`](/commands/docs/where.html) and many times you can accomplish the same thing with either. For example: ```nu -> mut result = [] -> for $it in [1 2 3] { $result = ($result | append ($it + 1)) } -> $result -╭───┬───╮ -│ 0 │ 2 │ -│ 1 │ 3 │ -│ 2 │ 4 │ -╰───┴───╯ - - -> [1 2 3] | each { $in + 1 } -╭───┬───╮ -│ 0 │ 2 │ -│ 1 │ 3 │ -│ 2 │ 4 │ -╰───┴───╯ +mut result = [] +for $it in [1 2 3] { $result = ($result | append ($it + 1)) } +$result +# => ╭───┬───╮ +# => │ 0 │ 2 │ +# => │ 1 │ 3 │ +# => │ 2 │ 4 │ +# => ╰───┴───╯ + + +[1 2 3] | each { $in + 1 } +# => ╭───┬───╮ +# => │ 0 │ 2 │ +# => │ 1 │ 3 │ +# => │ 2 │ 4 │ +# => ╰───┴───╯ ``` While it may be tempting to use loops if you're familiar with them in other languages, it is considered more in the [Nushell-style](book/thinking_in_nu.html) (idiomatic) to use commands that apply closures when you can solve a problem either way. The reason for this is because of a pretty big downside with using loops. @@ -167,16 +167,16 @@ This means that they don't work well with immutable variables and using immutabl Statements also don't work in Nushell pipelines which require some output. In fact Nushell will give an error if you try: ```nu -> [1 2 3] | for x in $in { $x + 1 } | $in ++ [5 6 7] -Error: nu::parser::unexpected_keyword - - × Statement used in pipeline. - ╭─[entry #5:1:1] - 1 │ [1 2 3] | for x in $in { $x + 1 } | $in ++ [5 6 7] - · ─┬─ - · ╰── not allowed in pipeline - ╰──── - help: 'for' keyword is not allowed in pipeline. Use 'for' by itself, outside of a pipeline. +[1 2 3] | for x in $in { $x + 1 } | $in ++ [5 6 7] +# => Error: nu::parser::unexpected_keyword +# => +# => × Statement used in pipeline. +# => ╭─[entry #5:1:1] +# => 1 │ [1 2 3] | for x in $in { $x + 1 } | $in ++ [5 6 7] +# => · ─┬─ +# => · ╰── not allowed in pipeline +# => ╰──── +# => help: 'for' keyword is not allowed in pipeline. Use 'for' by itself, outside of a pipeline. ``` Because Nushell is very pipeline oriented, this means using expression commands like [`each`](/commands/docs/each.html) is typically more natural than loop statements. @@ -186,29 +186,29 @@ Because Nushell is very pipeline oriented, this means using expression commands If loops have such a big disadvantage, why do they exist? Well, one reason is that closures, like [`each`](/commands/docs/each.html) uses, can't modify mutable variables in the surrounding environment. If you try to modify a mutable variable in a closure you will get an error: ```nu -> mut foo = [] -> [1 2 3] | each { $foo = ($foo | append ($in + 1)) } -Error: nu::parser::expected_keyword - - × Capture of mutable variable. - ╭─[entry #8:1:1] - 1 │ [1 2 3] | each { $foo = ($foo | append ($in + 1)) } - · ──┬─ - · ╰── capture of mutable variable - ╰──── +mut foo = [] +[1 2 3] | each { $foo = ($foo | append ($in + 1)) } +# => Error: nu::parser::expected_keyword +# => +# => × Capture of mutable variable. +# => ╭─[entry #8:1:1] +# => 1 │ [1 2 3] | each { $foo = ($foo | append ($in + 1)) } +# => · ──┬─ +# => · ╰── capture of mutable variable +# => ╰──── ``` If you modify an environmental variable in a closure, you can, but it will only modify it within the scope of the closure, leaving it unchanged everywhere else. Loops, however, use [blocks](/book/types_of_data.html#blocks) which means they can modify a regular mutable variable or an environmental variable within the larger scope. ```nu -> mut result = [] -> for $it in [1 2 3] { $result = ($result | append ($it + 1)) } -> $result -╭───┬───╮ -│ 0 │ 2 │ -│ 1 │ 3 │ -│ 2 │ 4 │ -╰───┴───╯ +mut result = [] +for $it in [1 2 3] { $result = ($result | append ($it + 1)) } +$result +# => ╭───┬───╮ +# => │ 0 │ 2 │ +# => │ 1 │ 3 │ +# => │ 2 │ 4 │ +# => ╰───┴───╯ ``` ### `for` @@ -216,10 +216,10 @@ If you modify an environmental variable in a closure, you can, but it will only [`for`](/commands/docs/for.html) loops over a range or collection like a list or a table. ```nu -> for x in [1 2 3] { $x * $x | print } -1 -4 -9 +for x in [1 2 3] { $x * $x | print } +# => 1 +# => 4 +# => 9 ``` #### Expression Command Alternatives @@ -234,8 +234,8 @@ If you modify an environmental variable in a closure, you can, but it will only [`while`](/commands/docs/while.html) loops the same block of code until the given condition is `false`. ```nu -> mut x = 0; while $x < 10 { $x = $x + 1 }; $x -10 +mut x = 0; while $x < 10 { $x = $x + 1 }; $x +# => 10 ``` #### Expression Command Alternatives @@ -252,8 +252,8 @@ The "until" and other "while" commands [`loop`](/commands/docs/loop.html) loops a block infinitely. You can use [`break`](/commands/docs/break.html) (as described in the next section) to limit how many times it loops. It can also be handy for continuously running scripts, like an interactive prompt. ```nu -> mut x = 0; loop { if $x > 10 { break }; $x = $x + 1 }; $x -11 +mut x = 0; loop { if $x > 10 { break }; $x = $x + 1 }; $x +# => 11 ``` ### `break` @@ -261,10 +261,10 @@ The "until" and other "while" commands [`break`](/commands/docs/break.html) will stop executing the code in a loop and resume execution after the loop. Effectively "break"ing out of the loop. ```nu -> for x in 1..10 { if $x > 3 { break }; print $x } -1 -2 -3 +for x in 1..10 { if $x > 3 { break }; print $x } +# => 1 +# => 2 +# => 3 ``` ### `continue` @@ -272,12 +272,12 @@ The "until" and other "while" commands [`continue`](/commands/docs/continue.html) will stop execution of the current loop, skipping the rest of the code in the loop, and will go to the next loop. If the loop would normally end, like if [`for`](/commands/docs/for.html) has iterated through all the given elements, or if [`while`](/commands/docs/while.html)'s condition is now false, it won't loop again and execution will continue after the loop block. ```nu -> mut x = -1; while $x <= 6 { $x = $x + 1; if $x mod 3 == 0 { continue }; print $x } -1 -2 -4 -5 -7 +mut x = -1; while $x <= 6 { $x = $x + 1; if $x mod 3 == 0 { continue }; print $x } +# => 1 +# => 2 +# => 4 +# => 5 +# => 7 ``` ## Errors @@ -287,14 +287,14 @@ The "until" and other "while" commands [`error make`](/commands/docs/error_make.html) creates an error that stops execution of the code and any code that called it, until either it is handled by a [`try`](/commands/docs/try.html) block, or it ends the script and outputs the error message. This functionality is the same as "exceptions" in other languages. ```nu -> print 'printed'; error make { msg: 'Some error info' }; print 'unprinted' -printed -Error: × Some error info - ╭─[entry #9:1:1] - 1 │ print 'printed'; error make { msg: 'Some error info' }; print 'unprinted' - · ─────┬──── - · ╰── originates from here - ╰──── +print 'printed'; error make { msg: 'Some error info' }; print 'unprinted' +# => printed +# => Error: × Some error info +# => ╭─[entry #9:1:1] +# => 1 │ print 'printed'; error make { msg: 'Some error info' }; print 'unprinted' +# => · ─────┬──── +# => · ╰── originates from here +# => ╰──── ``` The record passed to it provides some information to the code that catches it or the resulting error message. @@ -306,15 +306,15 @@ You can find more information about [`error make`](/commands/docs/error_make.htm [`try`](/commands/docs/try.html) will catch errors created anywhere in the [`try`](/commands/docs/try.html)'s code block and resume execution of the code after the block. ```nu -> try { error make { msg: 'Some error info' }}; print 'Resuming' -Resuming +try { error make { msg: 'Some error info' }}; print 'Resuming' +# => Resuming ``` This includes catching built in errors. ```nu -> try { 1 / 0 }; print 'Resuming' -Resuming +try { 1 / 0 }; print 'Resuming' +# => Resuming ``` The resulting value will be `nothing` if an error occurs and the returned value of the block if an error did not occur. @@ -322,8 +322,8 @@ The resulting value will be `nothing` if an error occurs and the returned value If you include a `catch` block after the [`try`](/commands/docs/try.html) block, it will execute the code in the `catch` block if an error occurred in the [`try`](/commands/docs/try.html) block. ```nu -> try { 1 / 0 } catch { 'An error happened!' } | $in ++ ' And now I am resuming.' -An error happened! And now I am resuming. +try { 1 / 0 } catch { 'An error happened!' } | $in ++ ' And now I am resuming.' +# => An error happened! And now I am resuming. ``` It will not execute the `catch` block if an error did not occur. @@ -345,17 +345,17 @@ def 'positive-check' [it] { ``` ```nu -> positive-check 3 -positive +positive-check 3 +# => positive -> positive-check (-3) -non-positive +positive-check (-3) +# => non-positive -> let positive_check = {|elt| if $elt > 0 { return 'positive' }; 'non-positive' } +let positive_check = {|elt| if $elt > 0 { return 'positive' }; 'non-positive' } -> do $positive_check 3 -positive +do $positive_check 3 +# => positive -> do $positive_check (-3) -non-positive +do $positive_check (-3) +# => non-positive ``` diff --git a/book/creating_errors.md b/book/creating_errors.md index b3f1d8b296f..48ebbc44b1c 100644 --- a/book/creating_errors.md +++ b/book/creating_errors.md @@ -37,13 +37,12 @@ def my-command [x] { When called with a value, we'll now see an error message returned: ```nu -> my-command 100 - -Error: - × this is fishy - ╭─[entry #5:1:1] - 1 │ my-command 100 - · ─┬─ - · ╰── fish right here - ╰──── +my-command 100 +# => Error: +# => × this is fishy +# => ╭─[entry #5:1:1] +# => 1 │ my-command 100 +# => · ─┬─ +# => · ╰── fish right here +# => ╰──── ``` diff --git a/book/custom_commands.md b/book/custom_commands.md index c5aa0448d47..cccc27bc05e 100644 --- a/book/custom_commands.md +++ b/book/custom_commands.md @@ -166,7 +166,7 @@ See also: [Pipelines](./pipelines.html) ### Pipeline Output ```nu -> ls | get name +ls | get name ``` Let's move [`ls`](/commands/docs/ls.md) into a command that we've written: @@ -178,7 +178,7 @@ def my-ls [] { ls } We can use the output from this command just as we would [`ls`](/commands/docs/ls.md). ```nu -> my-ls | get name +my-ls | get name # => ╭───┬───────────────────────╮ # => │ 0 │ myscript.nu │ # => │ 1 │ myscript2.nu │ @@ -186,7 +186,7 @@ We can use the output from this command just as we would [`ls`](/commands/docs/l # => ╰───┴───────────────────────╯ ``` -This lets us easily build custom commands and process their output. Remember that that we don't use return statements like other languages. Instead, the [implicit return](#returning-values-from-a-command) allows us to build pipelines that output streams of data that can be connected to other pipelines. +This lets us easily build custom commands and process their output. Remember that we don't use return statements like other languages. Instead, the [implicit return](#returning-values-from-a-command) allows us to build pipelines that output streams of data that can be connected to other pipelines. ::: tip Note The `ls` content is still streamed in this case, even though it is in a separate command. Running this command against a long-directory on a slow (e.g., networked) filesystem would return rows as they became available. @@ -286,7 +286,7 @@ def "str mycommand" [] { Now we can call our custom command as if it were a built-in subcommand of [`str`](/commands/docs/str.md): ```nu -> str mycommand +str mycommand ``` Of course, commands with spaces in their names are defined in the same way: diff --git a/book/custom_completions.md b/book/custom_completions.md index ea160671018..f006afc0345 100644 --- a/book/custom_completions.md +++ b/book/custom_completions.md @@ -11,11 +11,11 @@ Here's a simple example: ```nu # Completion command -> def animals [] { ["cat", "dog", "eel" ] } +def animals [] { ["cat", "dog", "eel" ] } # Command to be completed -> def my-command [animal: string@animals] { print $animal } ->| my-command -cat dog eel +def my-command [animal: string@animals] { print $animal } +my-command +# => cat dog eel ``` The first line defines a custom command which returns a list of three different animals. These are the possible values for the completion. diff --git a/book/dataframes.md b/book/dataframes.md index 3d090ffe7f5..b93c6babdc7 100644 --- a/book/dataframes.md +++ b/book/dataframes.md @@ -51,13 +51,13 @@ The dataset has 5 columns and 5,429,252 rows. We can check that by using the `polars store-ls` command: ```nu -> let df_0 = polars open --eager Data7602DescendingYearOrder.csv -> polars store-ls | select key type columns rows estimated_size -╭──────────────────────────────────────┬───────────┬─────────┬─────────┬────────────────╮ -│ key │ type │ columns │ rows │ estimated_size │ -├──────────────────────────────────────┼───────────┼─────────┼─────────┼────────────────┤ -│ b2519dac-3b64-4e5d-a0d7-24bde9052dc7 │ DataFrame │ 5 │ 5429252 │ 184.5 MB │ -╰──────────────────────────────────────┴───────────┴─────────┴─────────┴────────────────╯ +let df_0 = polars open --eager Data7602DescendingYearOrder.csv +polars store-ls | select key type columns rows estimated_size +# => ╭──────────────────────────────────────┬───────────┬─────────┬─────────┬────────────────╮ +# => │ key │ type │ columns │ rows │ estimated_size │ +# => ├──────────────────────────────────────┼───────────┼─────────┼─────────┼────────────────┤ +# => │ b2519dac-3b64-4e5d-a0d7-24bde9052dc7 │ DataFrame │ 5 │ 5429252 │ 184.5 MB │ +# => ╰──────────────────────────────────────┴───────────┴─────────┴─────────┴────────────────╯ ``` ::: tip @@ -68,25 +68,25 @@ To open as an eager dataframe, use the `--eager` flag. We can have a look at the first lines of the file using [`first`](/commands/docs/first.md): ```nu -> $df_0 | polars first -╭───┬──────────┬─────────┬──────┬───────────┬──────────╮ -│ # │ anzsic06 │ Area │ year │ geo_count │ ec_count │ -├───┼──────────┼─────────┼──────┼───────────┼──────────┤ -│ 0 │ A │ A100100 │ 2000 │ 96 │ 130 │ -╰───┴──────────┴─────────┴──────┴───────────┴──────────╯ +$df_0 | polars first +# => ╭───┬──────────┬─────────┬──────┬───────────┬──────────╮ +# => │ # │ anzsic06 │ Area │ year │ geo_count │ ec_count │ +# => ├───┼──────────┼─────────┼──────┼───────────┼──────────┤ +# => │ 0 │ A │ A100100 │ 2000 │ 96 │ 130 │ +# => ╰───┴──────────┴─────────┴──────┴───────────┴──────────╯ ``` ...and finally, we can get an idea of the inferred data types: ```nu -> $df_0 | polars schema -╭───────────┬─────╮ -│ anzsic06 │ str │ -│ Area │ str │ -│ year │ i64 │ -│ geo_count │ i64 │ -│ ec_count │ i64 │ -╰───────────┴─────╯ +$df_0 | polars schema +# => ╭───────────┬─────╮ +# => │ anzsic06 │ str │ +# => │ Area │ str │ +# => │ year │ i64 │ +# => │ geo_count │ i64 │ +# => │ ec_count │ i64 │ +# => ╰───────────┴─────╯ ``` ### Group-by Comparison @@ -94,7 +94,7 @@ We can have a look at the first lines of the file using [`first`](/commands/docs To output more statistically correct timings, let's load and use the `std bench` command. ```nu -> use std bench +use std bench ``` We are going to group the data by year, and sum the column `geo_count`. @@ -187,7 +187,7 @@ To do that, let's stop the `polars`. When we execute our next commands, we will start a new instance of plugin. ```nu -> plugin stop polars +plugin stop polars ``` ## Working with Dataframes @@ -220,7 +220,7 @@ Now, to read that file as a dataframe use the `polars open` command like this: ```nu -> let df_1 = polars open --eager test_small.csv +let df_1 = polars open --eager test_small.csv ``` This should create the value `$df_1` in memory which holds the data we just @@ -233,12 +233,12 @@ The `polars open` command can read files in formats: **csv**, **tsv**, **parquet To see all the dataframes that are stored in memory you can use ```nu -> polars store-ls | select key type columns rows estimated_size -╭──────────────────────────────────────┬───────────┬─────────┬──────┬────────────────╮ -│ key │ type │ columns │ rows │ estimated_size │ -├──────────────────────────────────────┼───────────┼─────────┼──────┼────────────────┤ -│ e780af47-c106-49eb-b38d-d42d3946d66e │ DataFrame │ 8 │ 10 │ 403 B │ -╰──────────────────────────────────────┴───────────┴─────────┴──────┴────────────────╯ +polars store-ls | select key type columns rows estimated_size +# => ╭──────────────────────────────────────┬───────────┬─────────┬──────┬────────────────╮ +# => │ key │ type │ columns │ rows │ estimated_size │ +# => ├──────────────────────────────────────┼───────────┼─────────┼──────┼────────────────┤ +# => │ e780af47-c106-49eb-b38d-d42d3946d66e │ DataFrame │ 8 │ 10 │ 403 B │ +# => ╰──────────────────────────────────────┴───────────┴─────────┴──────┴────────────────╯ ``` As you can see, the command shows the created dataframes together with basic @@ -248,21 +248,21 @@ And if you want to see a preview of the loaded dataframe you can send the dataframe variable to the stream ```nu -> $df_1 -╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ -├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ -│ 0 │ 1 │ 11 │ 0.10 │ 1.00 │ a │ b │ c │ first │ -│ 1 │ 2 │ 12 │ 0.20 │ 1.00 │ a │ b │ c │ second │ -│ 2 │ 3 │ 13 │ 0.30 │ 2.00 │ a │ b │ c │ third │ -│ 3 │ 4 │ 14 │ 0.40 │ 3.00 │ b │ a │ c │ second │ -│ 4 │ 0 │ 15 │ 0.50 │ 4.00 │ b │ a │ a │ third │ -│ 5 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ -│ 6 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ -│ 7 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ -│ 8 │ 9 │ 19 │ 0.90 │ 8.00 │ c │ c │ b │ ninth │ -│ 9 │ 0 │ 10 │ 0.00 │ 9.00 │ c │ c │ b │ ninth │ -╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ +$df_1 +# => ╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ +# => ├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ +# => │ 0 │ 1 │ 11 │ 0.10 │ 1.00 │ a │ b │ c │ first │ +# => │ 1 │ 2 │ 12 │ 0.20 │ 1.00 │ a │ b │ c │ second │ +# => │ 2 │ 3 │ 13 │ 0.30 │ 2.00 │ a │ b │ c │ third │ +# => │ 3 │ 4 │ 14 │ 0.40 │ 3.00 │ b │ a │ c │ second │ +# => │ 4 │ 0 │ 15 │ 0.50 │ 4.00 │ b │ a │ a │ third │ +# => │ 5 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ +# => │ 6 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ +# => │ 7 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ +# => │ 8 │ 9 │ 19 │ 0.90 │ 8.00 │ c │ c │ b │ ninth │ +# => │ 9 │ 0 │ 10 │ 0.00 │ 9.00 │ c │ c │ b │ ninth │ +# => ╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ ``` With the dataframe in memory we can start doing column operations with the @@ -279,12 +279,12 @@ Let's start with basic aggregations on the dataframe. Let's sum all the columns that exist in `df` by using the `aggregate` command ```nu -> $df_1 | polars sum -╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬──────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ -├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼──────┤ -│ 0 │ 40 │ 145 │ 4.50 │ 46.00 │ │ │ │ │ -╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴──────╯ +$df_1 | polars sum +# => ╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬──────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ +# => ├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼──────┤ +# => │ 0 │ 40 │ 145 │ 4.50 │ 46.00 │ │ │ │ │ +# => ╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴──────╯ ``` As you can see, the aggregate function computes the sum for those columns where @@ -292,19 +292,19 @@ a sum makes sense. If you want to filter out the text column, you can select the columns you want by using the [`polars select`](/commands/docs/polars_select.md) command ```nu -> $df_1 | polars sum | polars select int_1 int_2 float_1 float_2 -╭───┬───────┬───────┬─────────┬─────────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ -├───┼───────┼───────┼─────────┼─────────┤ -│ 0 │ 40 │ 145 │ 4.50 │ 46.00 │ -╰───┴───────┴───────┴─────────┴─────────╯ +$df_1 | polars sum | polars select int_1 int_2 float_1 float_2 +# => ╭───┬───────┬───────┬─────────┬─────────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ +# => ├───┼───────┼───────┼─────────┼─────────┤ +# => │ 0 │ 40 │ 145 │ 4.50 │ 46.00 │ +# => ╰───┴───────┴───────┴─────────┴─────────╯ ``` You can even store the result from this aggregation as you would store any other Nushell variable ```nu -> let res = $df_1 | polars sum | polars select int_1 int_2 float_1 float_2 +let res = $df_1 | polars sum | polars select int_1 int_2 float_1 float_2 ``` ::: tip @@ -315,7 +315,7 @@ executed command. Note the space between `=` and `!!`. And now we have two dataframes stored in memory ```nu -> polars store-ls | select key type columns rows estimated_size +polars store-ls | select key type columns rows estimated_size ╭──────────────────────────────────────┬───────────┬─────────┬──────┬────────────────╮ │ key │ type │ columns │ rows │ estimated_size │ ├──────────────────────────────────────┼───────────┼─────────┼──────┼────────────────┤ @@ -349,7 +349,7 @@ are going to call it `test_small_a.csv`) We use the `polars open` command to create the new variable ```nu -> let df_2 = polars open --eager test_small_a.csv +let df_2 = polars open --eager test_small_a.csv ``` Now, with the second dataframe loaded in memory we can join them using the @@ -357,15 +357,15 @@ column called `int_1` from the left dataframe and the column `int_1` from the right dataframe ```nu -> $df_1 | polars join $df_2 int_1 int_1 -╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────┬─────────┬───────────┬───────────┬─────────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ int_2_x │ float_1_x │ float_2_x │ first_x │ -├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┼─────────┼───────────┼───────────┼─────────┤ -│ 0 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ 11 │ 0.10 │ 0.00 │ b │ -│ 1 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ 12 │ 0.20 │ 1.00 │ a │ -│ 2 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ 13 │ 0.30 │ 2.00 │ a │ -│ 3 │ 9 │ 19 │ 0.90 │ 8.00 │ c │ c │ b │ ninth │ 14 │ 0.40 │ 3.00 │ a │ -╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────┴─────────┴───────────┴───────────┴─────────╯ +$df_1 | polars join $df_2 int_1 int_1 +# => ╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────┬─────────┬───────────┬───────────┬─────────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ int_2_x │ float_1_x │ float_2_x │ first_x │ +# => ├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┼─────────┼───────────┼───────────┼─────────┤ +# => │ 0 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ 11 │ 0.10 │ 0.00 │ b │ +# => │ 1 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ 12 │ 0.20 │ 1.00 │ a │ +# => │ 2 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ 13 │ 0.30 │ 2.00 │ a │ +# => │ 3 │ 9 │ 19 │ 0.90 │ 8.00 │ c │ c │ b │ ninth │ 14 │ 0.40 │ 3.00 │ a │ +# => ╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────┴─────────┴───────────┴───────────┴─────────╯ ``` ::: tip @@ -378,12 +378,12 @@ as long as they have the same type. For example: ```nu -> $df_1 | polars join $df_2 [int_1 first] [int_1 first] -╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────┬─────────┬───────────┬───────────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ int_2_x │ float_1_x │ float_2_x │ -├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┼─────────┼───────────┼───────────┤ -│ 0 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ 11 │ 0.10 │ 0.00 │ -╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────┴─────────┴───────────┴───────────╯ +$df_1 | polars join $df_2 [int_1 first] [int_1 first] +# => ╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────┬─────────┬───────────┬───────────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ int_2_x │ float_1_x │ float_2_x │ +# => ├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┼─────────┼───────────┼───────────┤ +# => │ 0 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ 11 │ 0.10 │ 0.00 │ +# => ╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────┴─────────┴───────────┴───────────╯ ``` By default, the join command does an inner join, meaning that it will keep the @@ -404,11 +404,11 @@ operations with the same group condition. To create a `GroupBy` object you only need to use the [`polars_group-by`](/commands/docs/polars_group-by.md) command ```nu -> let group = $df_1 | polars group-by first -> $group -╭─────────────┬──────────────────────────────────────────────╮ -│ LazyGroupBy │ apply aggregation to complete execution plan │ -╰─────────────┴──────────────────────────────────────────────╯ +let group = $df_1 | polars group-by first +$group +# => ╭─────────────┬──────────────────────────────────────────────╮ +# => │ LazyGroupBy │ apply aggregation to complete execution plan │ +# => ╰─────────────┴──────────────────────────────────────────────╯ ``` When printing the `GroupBy` object we can see that it is in the background a @@ -416,15 +416,15 @@ lazy operation waiting to be completed by adding an aggregation. Using the `GroupBy` we can create aggregations on a column ```nu -> $group | polars agg (polars col int_1 | polars sum) -╭────────────────┬───────────────────────────────────────────────────────────────────────────────────────╮ -│ plan │ AGGREGATE │ -│ │ [col("int_1").sum()] BY [col("first")] FROM │ -│ │ DF ["int_1", "int_2", "float_1", "float_2"]; PROJECT */8 COLUMNS; SELECTION: "None" │ -│ optimized_plan │ AGGREGATE │ -│ │ [col("int_1").sum()] BY [col("first")] FROM │ -│ │ DF ["int_1", "int_2", "float_1", "float_2"]; PROJECT 2/8 COLUMNS; SELECTION: "None" │ -╰────────────────┴───────────────────────────────────────────────────────────────────────────────────────╯ +$group | polars agg (polars col int_1 | polars sum) +# => ╭────────────────┬───────────────────────────────────────────────────────────────────────────────────────╮ +# => │ plan │ AGGREGATE │ +# => │ │ [col("int_1").sum()] BY [col("first")] FROM │ +# => │ │ DF ["int_1", "int_2", "float_1", "float_2"]; PROJECT */8 COLUMNS; SELECTION: "None" │ +# => │ optimized_plan │ AGGREGATE │ +# => │ │ [col("int_1").sum()] BY [col("first")] FROM │ +# => │ │ DF ["int_1", "int_2", "float_1", "float_2"]; PROJECT 2/8 COLUMNS; SELECTION: "None" │ +# => ╰────────────────┴───────────────────────────────────────────────────────────────────────────────────────╯ ``` or we can define multiple aggregations on the same or different columns @@ -468,15 +468,15 @@ as integers, decimals, or strings. Let's create a small dataframe using the command `polars into-df`. ```nu -> let df_3 = [[a b]; [1 2] [3 4] [5 6]] | polars into-df -> $df_3 -╭───┬───┬───╮ -│ # │ a │ b │ -├───┼───┼───┤ -│ 0 │ 1 │ 2 │ -│ 1 │ 3 │ 4 │ -│ 2 │ 5 │ 6 │ -╰───┴───┴───╯ +let df_3 = [[a b]; [1 2] [3 4] [5 6]] | polars into-df +$df_3 +# => ╭───┬───┬───╮ +# => │ # │ a │ b │ +# => ├───┼───┼───┤ +# => │ 0 │ 1 │ 2 │ +# => │ 1 │ 3 │ 4 │ +# => │ 2 │ 5 │ 6 │ +# => ╰───┴───┴───╯ ``` ::: tip @@ -488,15 +488,15 @@ We can append columns to a dataframe in order to create a new variable. As an example, let's append two columns to our mini dataframe `$df_3` ```nu -> let df_4 = $df_3 | polars with-column $df_3.a --name a2 | polars with-column $df_3.a --name a3 -> $df_4 -╭───┬───┬───┬────┬────╮ -│ # │ a │ b │ a2 │ a3 │ -├───┼───┼───┼────┼────┤ -│ 0 │ 1 │ 2 │ 1 │ 1 │ -│ 1 │ 3 │ 4 │ 3 │ 3 │ -│ 2 │ 5 │ 6 │ 5 │ 5 │ -╰───┴───┴───┴────┴────╯ +let df_4 = $df_3 | polars with-column $df_3.a --name a2 | polars with-column $df_3.a --name a3 +$df_4 +# => ╭───┬───┬───┬────┬────╮ +# => │ # │ a │ b │ a2 │ a3 │ +# => ├───┼───┼───┼────┼────┤ +# => │ 0 │ 1 │ 2 │ 1 │ 1 │ +# => │ 1 │ 3 │ 4 │ 3 │ 3 │ +# => │ 2 │ 5 │ 6 │ 5 │ 5 │ +# => ╰───┴───┴───┴────┴────╯ ``` Nushell's powerful piping syntax allows us to create new dataframes by @@ -504,17 +504,17 @@ taking data from other dataframes and appending it to them. Now, if you list you dataframes you will see in total five dataframes ```nu -> polars store-ls | select key type columns rows estimated_size -╭──────────────────────────────────────┬─────────────┬─────────┬──────┬────────────────╮ -│ key │ type │ columns │ rows │ estimated_size │ -├──────────────────────────────────────┼─────────────┼─────────┼──────┼────────────────┤ -│ e780af47-c106-49eb-b38d-d42d3946d66e │ DataFrame │ 8 │ 10 │ 403 B │ -│ 3146f4c1-f2a0-475b-a623-7375c1fdb4a7 │ DataFrame │ 4 │ 1 │ 32 B │ -│ 455a1483-e328-43e2-a354-35afa32803b9 │ DataFrame │ 5 │ 4 │ 132 B │ -│ 0d8532a5-083b-4f78-8f66-b5e6b59dc449 │ LazyGroupBy │ │ │ │ -│ 9504dfaf-4782-42d4-9110-9dae7c8fb95b │ DataFrame │ 2 │ 3 │ 48 B │ -│ 37ab1bdc-e1fb-426d-8006-c3f974764a3d │ DataFrame │ 4 │ 3 │ 96 B │ -╰──────────────────────────────────────┴─────────────┴─────────┴──────┴────────────────╯ +polars store-ls | select key type columns rows estimated_size +# => ╭──────────────────────────────────────┬─────────────┬─────────┬──────┬────────────────╮ +# => │ key │ type │ columns │ rows │ estimated_size │ +# => ├──────────────────────────────────────┼─────────────┼─────────┼──────┼────────────────┤ +# => │ e780af47-c106-49eb-b38d-d42d3946d66e │ DataFrame │ 8 │ 10 │ 403 B │ +# => │ 3146f4c1-f2a0-475b-a623-7375c1fdb4a7 │ DataFrame │ 4 │ 1 │ 32 B │ +# => │ 455a1483-e328-43e2-a354-35afa32803b9 │ DataFrame │ 5 │ 4 │ 132 B │ +# => │ 0d8532a5-083b-4f78-8f66-b5e6b59dc449 │ LazyGroupBy │ │ │ │ +# => │ 9504dfaf-4782-42d4-9110-9dae7c8fb95b │ DataFrame │ 2 │ 3 │ 48 B │ +# => │ 37ab1bdc-e1fb-426d-8006-c3f974764a3d │ DataFrame │ 4 │ 3 │ 96 B │ +# => ╰──────────────────────────────────────┴─────────────┴─────────┴──────┴────────────────╯ ``` One thing that is important to mention is how the memory is being optimized @@ -540,15 +540,15 @@ Let's start our exploration with Series by creating one using the `polars into-d command: ```nu -> let df_5 = [9 8 4] | polars into-df -> $df_5 -╭───┬───╮ -│ # │ 0 │ -├───┼───┤ -│ 0 │ 9 │ -│ 1 │ 8 │ -│ 2 │ 4 │ -╰───┴───╯ +let df_5 = [9 8 4] | polars into-df +$df_5 +# => ╭───┬───╮ +# => │ # │ 0 │ +# => ├───┼───┤ +# => │ 0 │ 9 │ +# => │ 1 │ 8 │ +# => │ 2 │ 4 │ +# => ╰───┴───╯ ``` We have created a new series from a list of integers (we could have done the @@ -559,15 +559,15 @@ other Series. Let's create a new Series by doing some arithmetic on the previously created column. ```nu -> let df_6 = $df_5 * 3 + 10 -> $df_6 -╭───┬────╮ -│ # │ 0 │ -├───┼────┤ -│ 0 │ 37 │ -│ 1 │ 34 │ -│ 2 │ 22 │ -╰───┴────╯ +let df_6 = $df_5 * 3 + 10 +$df_6 +# => ╭───┬────╮ +# => │ # │ 0 │ +# => ├───┼────┤ +# => │ 0 │ 37 │ +# => │ 1 │ 34 │ +# => │ 2 │ 22 │ +# => ╰───┴────╯ ``` Now we have a new Series that was constructed by doing basic operations on the @@ -581,71 +581,71 @@ use `scope variables` Let's rename our previous Series so it has a memorable name ```nu -> let df_7 = $df_6 | polars rename "0" memorable -> $df_7 -╭───┬───────────╮ -│ # │ memorable │ -├───┼───────────┤ -│ 0 │ 37 │ -│ 1 │ 34 │ -│ 2 │ 22 │ -╰───┴───────────╯ +let df_7 = $df_6 | polars rename "0" memorable +$df_7 +# => ╭───┬───────────╮ +# => │ # │ memorable │ +# => ├───┼───────────┤ +# => │ 0 │ 37 │ +# => │ 1 │ 34 │ +# => │ 2 │ 22 │ +# => ╰───┴───────────╯ ``` We can also do basic operations with two Series as long as they have the same data type ```nu -> $df_5 - $df_7 -╭───┬─────────────────╮ -│ # │ sub_0_memorable │ -├───┼─────────────────┤ -│ 0 │ -28 │ -│ 1 │ -26 │ -│ 2 │ -18 │ -╰───┴─────────────────╯ +$df_5 - $df_7 +# => ╭───┬─────────────────╮ +# => │ # │ sub_0_memorable │ +# => ├───┼─────────────────┤ +# => │ 0 │ -28 │ +# => │ 1 │ -26 │ +# => │ 2 │ -18 │ +# => ╰───┴─────────────────╯ ``` And we can add them to previously defined dataframes ```nu -> let df_8 = $df_3 | polars with-column $df_5 --name new_col -> $df_8 -╭───┬───┬───┬─────────╮ -│ # │ a │ b │ new_col │ -├───┼───┼───┼─────────┤ -│ 0 │ 1 │ 2 │ 9 │ -│ 1 │ 3 │ 4 │ 8 │ -│ 2 │ 5 │ 6 │ 4 │ -╰───┴───┴───┴─────────╯ +let df_8 = $df_3 | polars with-column $df_5 --name new_col +$df_8 +# => ╭───┬───┬───┬─────────╮ +# => │ # │ a │ b │ new_col │ +# => ├───┼───┼───┼─────────┤ +# => │ 0 │ 1 │ 2 │ 9 │ +# => │ 1 │ 3 │ 4 │ 8 │ +# => │ 2 │ 5 │ 6 │ 4 │ +# => ╰───┴───┴───┴─────────╯ ``` The Series stored in a Dataframe can also be used directly, for example, we can multiply columns `a` and `b` to create a new Series ```nu -> $df_8.a * $df_8.b -╭───┬─────────╮ -│ # │ mul_a_b │ -├───┼─────────┤ -│ 0 │ 2 │ -│ 1 │ 12 │ -│ 2 │ 30 │ -╰───┴─────────╯ +$df_8.a * $df_8.b +# => ╭───┬─────────╮ +# => │ # │ mul_a_b │ +# => ├───┼─────────┤ +# => │ 0 │ 2 │ +# => │ 1 │ 12 │ +# => │ 2 │ 30 │ +# => ╰───┴─────────╯ ``` and we can start piping things in order to create new columns and dataframes ```nu -> let df_9 = $df_8 | polars with-column ($df_8.a * $df_8.b / $df_8.new_col) --name my_sum -> $df_9 -╭───┬───┬───┬─────────┬────────╮ -│ # │ a │ b │ new_col │ my_sum │ -├───┼───┼───┼─────────┼────────┤ -│ 0 │ 1 │ 2 │ 9 │ 0 │ -│ 1 │ 3 │ 4 │ 8 │ 1 │ -│ 2 │ 5 │ 6 │ 4 │ 7 │ -╰───┴───┴───┴─────────┴────────╯ +let df_9 = $df_8 | polars with-column ($df_8.a * $df_8.b / $df_8.new_col) --name my_sum +$df_9 +# => ╭───┬───┬───┬─────────┬────────╮ +# => │ # │ a │ b │ new_col │ my_sum │ +# => ├───┼───┼───┼─────────┼────────┤ +# => │ 0 │ 1 │ 2 │ 9 │ 0 │ +# => │ 1 │ 3 │ 4 │ 8 │ 1 │ +# => │ 2 │ 5 │ 6 │ 4 │ 7 │ +# => ╰───┴───┴───┴─────────┴────────╯ ``` Nushell's piping system can help you create very interesting workflows. @@ -657,26 +657,26 @@ that we can build boolean masks out of them. Let's start by creating a simple mask using the equality operator ```nu -> let mask_0 = $df_5 == 8 -> $mask_0 -╭───┬───────╮ -│ # │ 0 │ -├───┼───────┤ -│ 0 │ false │ -│ 1 │ true │ -│ 2 │ false │ -╰───┴───────╯ +let mask_0 = $df_5 == 8 +$mask_0 +# => ╭───┬───────╮ +# => │ # │ 0 │ +# => ├───┼───────┤ +# => │ 0 │ false │ +# => │ 1 │ true │ +# => │ 2 │ false │ +# => ╰───┴───────╯ ``` and with this mask we can now filter a dataframe, like this ```nu -> $df_9 | polars filter-with $mask_0 -╭───┬───┬───┬─────────┬────────╮ -│ # │ a │ b │ new_col │ my_sum │ -├───┼───┼───┼─────────┼────────┤ -│ 0 │ 3 │ 4 │ 8 │ 1 │ -╰───┴───┴───┴─────────┴────────╯ +$df_9 | polars filter-with $mask_0 +# => ╭───┬───┬───┬─────────┬────────╮ +# => │ # │ a │ b │ new_col │ my_sum │ +# => ├───┼───┼───┼─────────┼────────┤ +# => │ 0 │ 3 │ 4 │ 8 │ 1 │ +# => ╰───┴───┴───┴─────────┴────────╯ ``` Now we have a new dataframe with only the values where the mask was true. @@ -684,70 +684,70 @@ Now we have a new dataframe with only the values where the mask was true. The masks can also be created from Nushell lists, for example: ```nu -> let mask_1 = [true true false] | polars into-df -> $df_9 | polars filter-with $mask_1 -╭───┬───┬───┬─────────┬────────╮ -│ # │ a │ b │ new_col │ my_sum │ -├───┼───┼───┼─────────┼────────┤ -│ 0 │ 1 │ 2 │ 9 │ 0 │ -│ 1 │ 3 │ 4 │ 8 │ 1 │ -╰───┴───┴───┴─────────┴────────╯ +let mask_1 = [true true false] | polars into-df +$df_9 | polars filter-with $mask_1 +# => ╭───┬───┬───┬─────────┬────────╮ +# => │ # │ a │ b │ new_col │ my_sum │ +# => ├───┼───┼───┼─────────┼────────┤ +# => │ 0 │ 1 │ 2 │ 9 │ 0 │ +# => │ 1 │ 3 │ 4 │ 8 │ 1 │ +# => ╰───┴───┴───┴─────────┴────────╯ ``` To create complex masks, we have the `AND` ```nu -> $mask_0 and $mask_1 -╭───┬─────────╮ -│ # │ and_0_0 │ -├───┼─────────┤ -│ 0 │ false │ -│ 1 │ true │ -│ 2 │ false │ -╰───┴─────────╯ +$mask_0 and $mask_1 +# => ╭───┬─────────╮ +# => │ # │ and_0_0 │ +# => ├───┼─────────┤ +# => │ 0 │ false │ +# => │ 1 │ true │ +# => │ 2 │ false │ +# => ╰───┴─────────╯ ``` and `OR` operations ```nu -> $mask_0 or $mask_1 -╭───┬────────╮ -│ # │ or_0_0 │ -├───┼────────┤ -│ 0 │ true │ -│ 1 │ true │ -│ 2 │ false │ -╰───┴────────╯ +$mask_0 or $mask_1 +# => ╭───┬────────╮ +# => │ # │ or_0_0 │ +# => ├───┼────────┤ +# => │ 0 │ true │ +# => │ 1 │ true │ +# => │ 2 │ false │ +# => ╰───┴────────╯ ``` We can also create a mask by checking if some values exist in other Series. Using the first dataframe that we created we can do something like this ```nu -> let mask_2 = $df_1 | polars col first | polars is-in [b c] -> $mask_2 -╭──────────┬─────────────────────────╮ -│ input │ [table 2 rows] │ -│ function │ Boolean(IsIn) │ -│ options │ FunctionOptions { ... } │ -╰──────────┴─────────────────────────╯ +let mask_2 = $df_1 | polars col first | polars is-in [b c] +$mask_2 +# => ╭──────────┬─────────────────────────╮ +# => │ input │ [table 2 rows] │ +# => │ function │ Boolean(IsIn) │ +# => │ options │ FunctionOptions { ... } │ +# => ╰──────────┴─────────────────────────╯ ``` and this new mask can be used to filter the dataframe ```nu -> $df_1 | polars filter-with $mask_2 -╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ -├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ -│ 0 │ 4 │ 14 │ 0.40 │ 3.00 │ b │ a │ c │ second │ -│ 1 │ 0 │ 15 │ 0.50 │ 4.00 │ b │ a │ a │ third │ -│ 2 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ -│ 3 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ -│ 4 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ -│ 5 │ 9 │ 19 │ 0.90 │ 8.00 │ c │ c │ b │ ninth │ -│ 6 │ 0 │ 10 │ 0.00 │ 9.00 │ c │ c │ b │ ninth │ -╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ +$df_1 | polars filter-with $mask_2 +# => ╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ +# => ├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ +# => │ 0 │ 4 │ 14 │ 0.40 │ 3.00 │ b │ a │ c │ second │ +# => │ 1 │ 0 │ 15 │ 0.50 │ 4.00 │ b │ a │ a │ third │ +# => │ 2 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ +# => │ 3 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ +# => │ 4 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ +# => │ 5 │ 9 │ 19 │ 0.90 │ 8.00 │ c │ c │ b │ ninth │ +# => │ 6 │ 0 │ 10 │ 0.00 │ 9.00 │ c │ c │ b │ ninth │ +# => ╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ ``` Another operation that can be done with masks is setting or replacing a value @@ -755,21 +755,21 @@ from a series. For example, we can change the value in the column `first` where the value is equal to `a` ```nu -> $df_1 | polars get first | polars set new --mask ($df_1.first =~ a) -╭───┬────────╮ -│ # │ string │ -├───┼────────┤ -│ 0 │ new │ -│ 1 │ new │ -│ 2 │ new │ -│ 3 │ b │ -│ 4 │ b │ -│ 5 │ b │ -│ 6 │ b │ -│ 7 │ c │ -│ 8 │ c │ -│ 9 │ c │ -╰───┴────────╯ +$df_1 | polars get first | polars set new --mask ($df_1.first =~ a) +# => ╭───┬────────╮ +# => │ # │ string │ +# => ├───┼────────┤ +# => │ 0 │ new │ +# => │ 1 │ new │ +# => │ 2 │ new │ +# => │ 3 │ b │ +# => │ 4 │ b │ +# => │ 5 │ b │ +# => │ 6 │ b │ +# => │ 7 │ c │ +# => │ 8 │ c │ +# => │ 9 │ c │ +# => ╰───┴────────╯ ``` ## Series as Indices @@ -780,15 +780,15 @@ from our original dataframe. With that in mind, we can use the next command to extract that information ```nu -> let indices_0 = [1 4 6] | polars into-df -> $df_1 | polars take $indices_0 -╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ -├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ -│ 0 │ 2 │ 12 │ 0.20 │ 1.00 │ a │ b │ c │ second │ -│ 1 │ 0 │ 15 │ 0.50 │ 4.00 │ b │ a │ a │ third │ -│ 2 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ -╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ +let indices_0 = [1 4 6] | polars into-df +$df_1 | polars take $indices_0 +# => ╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ +# => ├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ +# => │ 0 │ 2 │ 12 │ 0.20 │ 1.00 │ a │ b │ c │ second │ +# => │ 1 │ 0 │ 15 │ 0.50 │ 4.00 │ b │ a │ a │ third │ +# => │ 2 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ +# => ╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ ``` The command [`polars take`](/commands/docs/polars_take.md) is very handy, especially if we mix it with other commands. @@ -797,15 +797,15 @@ column `first`. In order to do that, we can use the command `polars arg-unique` shown in the next example ```nu -> let indices_1 = $df_1 | polars get first | polars arg-unique -> $df_1 | polars take $indices_1 -╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ -├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ -│ 0 │ 1 │ 11 │ 0.10 │ 1.00 │ a │ b │ c │ first │ -│ 1 │ 4 │ 14 │ 0.40 │ 3.00 │ b │ a │ c │ second │ -│ 2 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ -╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ +let indices_1 = $df_1 | polars get first | polars arg-unique +$df_1 | polars take $indices_1 +# => ╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ +# => ├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ +# => │ 0 │ 1 │ 11 │ 0.10 │ 1.00 │ a │ b │ c │ first │ +# => │ 1 │ 4 │ 14 │ 0.40 │ 3.00 │ b │ a │ c │ second │ +# => │ 2 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ +# => ╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ ``` Or what if we want to create a new sorted dataframe using a column in specific. @@ -817,44 +817,44 @@ The same result could be accomplished using the command [`sort`](/commands/docs/ ::: ```nu -> let indices_2 = $df_1 | polars get word | polars arg-sort -> $df_1 | polars take $indices_2 -╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ -│ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ -├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ -│ 0 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ -│ 1 │ 1 │ 11 │ 0.10 │ 1.00 │ a │ b │ c │ first │ -│ 2 │ 9 │ 19 │ 0.90 │ 8.00 │ c │ c │ b │ ninth │ -│ 3 │ 0 │ 10 │ 0.00 │ 9.00 │ c │ c │ b │ ninth │ -│ 4 │ 2 │ 12 │ 0.20 │ 1.00 │ a │ b │ c │ second │ -│ 5 │ 4 │ 14 │ 0.40 │ 3.00 │ b │ a │ c │ second │ -│ 6 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ -│ 7 │ 3 │ 13 │ 0.30 │ 2.00 │ a │ b │ c │ third │ -│ 8 │ 0 │ 15 │ 0.50 │ 4.00 │ b │ a │ a │ third │ -│ 9 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ -╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ +let indices_2 = $df_1 | polars get word | polars arg-sort +$df_1 | polars take $indices_2 +# => ╭───┬───────┬───────┬─────────┬─────────┬───────┬────────┬───────┬────────╮ +# => │ # │ int_1 │ int_2 │ float_1 │ float_2 │ first │ second │ third │ word │ +# => ├───┼───────┼───────┼─────────┼─────────┼───────┼────────┼───────┼────────┤ +# => │ 0 │ 8 │ 18 │ 0.80 │ 7.00 │ c │ c │ b │ eight │ +# => │ 1 │ 1 │ 11 │ 0.10 │ 1.00 │ a │ b │ c │ first │ +# => │ 2 │ 9 │ 19 │ 0.90 │ 8.00 │ c │ c │ b │ ninth │ +# => │ 3 │ 0 │ 10 │ 0.00 │ 9.00 │ c │ c │ b │ ninth │ +# => │ 4 │ 2 │ 12 │ 0.20 │ 1.00 │ a │ b │ c │ second │ +# => │ 5 │ 4 │ 14 │ 0.40 │ 3.00 │ b │ a │ c │ second │ +# => │ 6 │ 6 │ 16 │ 0.60 │ 5.00 │ b │ a │ a │ second │ +# => │ 7 │ 3 │ 13 │ 0.30 │ 2.00 │ a │ b │ c │ third │ +# => │ 8 │ 0 │ 15 │ 0.50 │ 4.00 │ b │ a │ a │ third │ +# => │ 9 │ 7 │ 17 │ 0.70 │ 6.00 │ b │ c │ a │ third │ +# => ╰───┴───────┴───────┴─────────┴─────────┴───────┴────────┴───────┴────────╯ ``` And finally, we can create new Series by setting a new value in the marked indices. Have a look at the next command ```nu -> let indices_3 = [0 2] | polars into-df -> $df_1 | polars get int_1 | polars set-with-idx 123 --indices $indices_3 -╭───┬───────╮ -│ # │ int_1 │ -├───┼───────┤ -│ 0 │ 123 │ -│ 1 │ 2 │ -│ 2 │ 123 │ -│ 3 │ 4 │ -│ 4 │ 0 │ -│ 5 │ 6 │ -│ 6 │ 7 │ -│ 7 │ 8 │ -│ 8 │ 9 │ -│ 9 │ 0 │ -╰───┴───────╯ +let indices_3 = [0 2] | polars into-df +$df_1 | polars get int_1 | polars set-with-idx 123 --indices $indices_3 +# => ╭───┬───────╮ +# => │ # │ int_1 │ +# => ├───┼───────┤ +# => │ 0 │ 123 │ +# => │ 1 │ 2 │ +# => │ 2 │ 123 │ +# => │ 3 │ 4 │ +# => │ 4 │ 0 │ +# => │ 5 │ 6 │ +# => │ 6 │ 7 │ +# => │ 7 │ 8 │ +# => │ 8 │ 9 │ +# => │ 9 │ 0 │ +# => ╰───┴───────╯ ``` ## Unique Values @@ -869,14 +869,14 @@ example, we can use it to count how many occurrences we have in the column `first` ```nu -> $df_1 | polars get first | polars value-counts -╭───┬───────┬───────╮ -│ # │ first │ count │ -├───┼───────┼───────┤ -│ 0 │ a │ 3 │ -│ 1 │ b │ 4 │ -│ 2 │ c │ 3 │ -╰───┴───────┴───────╯ +$df_1 | polars get first | polars value-counts +# => ╭───┬───────┬───────╮ +# => │ # │ first │ count │ +# => ├───┼───────┼───────┤ +# => │ 0 │ a │ 3 │ +# => │ 1 │ b │ 4 │ +# => │ 2 │ c │ 3 │ +# => ╰───┴───────┴───────╯ ``` As expected, the command returns a new dataframe that can be used to do more @@ -886,14 +886,14 @@ Continuing with our exploration of `Series`, the next thing that we can do is to only get the unique unique values from a series, like this ```nu -> $df_1 | polars get first | polars unique -╭───┬───────╮ -│ # │ first │ -├───┼───────┤ -│ 0 │ a │ -│ 1 │ b │ -│ 2 │ c │ -╰───┴───────╯ +$df_1 | polars get first | polars unique +# => ╭───┬───────╮ +# => │ # │ first │ +# => ├───┼───────┤ +# => │ 0 │ a │ +# => │ 1 │ b │ +# => │ 2 │ c │ +# => ╰───┴───────╯ ``` Or we can get a mask that we can use to filter out the rows where data is @@ -949,12 +949,12 @@ operations. Let's create a small example of a lazy dataframe ```nu -> let lf_0 = [[a b]; [1 a] [2 b] [3 c] [4 d]] | polars into-lazy -> $lf_0 -╭────────────────┬───────────────────────────────────────────────────────╮ -│ plan │ DF ["a", "b"]; PROJECT */2 COLUMNS; SELECTION: "None" │ -│ optimized_plan │ DF ["a", "b"]; PROJECT */2 COLUMNS; SELECTION: "None" │ -╰────────────────┴───────────────────────────────────────────────────────╯ +let lf_0 = [[a b]; [1 a] [2 b] [3 c] [4 d]] | polars into-lazy +$lf_0 +# => ╭────────────────┬───────────────────────────────────────────────────────╮ +# => │ plan │ DF ["a", "b"]; PROJECT */2 COLUMNS; SELECTION: "None" │ +# => │ optimized_plan │ DF ["a", "b"]; PROJECT */2 COLUMNS; SELECTION: "None" │ +# => ╰────────────────┴───────────────────────────────────────────────────────╯ ``` As you can see, the resulting dataframe is not yet evaluated, it stays as a @@ -962,15 +962,15 @@ set of instructions that can be done on the data. If you were to collect that dataframe you would get the next result ```nu -> $lf_0 | polars collect -╭───┬───┬───╮ -│ # │ a │ b │ -├───┼───┼───┤ -│ 0 │ 1 │ a │ -│ 1 │ 2 │ b │ -│ 2 │ 3 │ c │ -│ 3 │ 4 │ d │ -╰───┴───┴───╯ +$lf_0 | polars collect +# => ╭───┬───┬───╮ +# => │ # │ a │ b │ +# => ├───┼───┼───┤ +# => │ 0 │ 1 │ a │ +# => │ 1 │ 2 │ b │ +# => │ 2 │ 3 │ c │ +# => │ 3 │ 4 │ d │ +# => ╰───┴───┴───╯ ``` as you can see, the collect command executes the plan and creates a nushell @@ -1034,29 +1034,29 @@ In some cases the use of the `polars col` command can be inferred. For example, using the `polars select` command we can use only a string ```nu -> $lf_0 | polars select a | polars collect -╭───┬───╮ -│ # │ a │ -├───┼───┤ -│ 0 │ 1 │ -│ 1 │ 2 │ -│ 2 │ 3 │ -│ 3 │ 4 │ -╰───┴───╯ +$lf_0 | polars select a | polars collect +# => ╭───┬───╮ +# => │ # │ a │ +# => ├───┼───┤ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => │ 2 │ 3 │ +# => │ 3 │ 4 │ +# => ╰───┴───╯ ``` or the `polars col` command ```nu -> $lf_0 | polars select (polars col a) | polars collect -╭───┬───╮ -│ # │ a │ -├───┼───┤ -│ 0 │ 1 │ -│ 1 │ 2 │ -│ 2 │ 3 │ -│ 3 │ 4 │ -╰───┴───╯ +$lf_0 | polars select (polars col a) | polars collect +# => ╭───┬───╮ +# => │ # │ a │ +# => ├───┼───┤ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => │ 2 │ 3 │ +# => │ 3 │ 4 │ +# => ╰───┴───╯ ``` Let's try something more complicated and create aggregations from a lazy diff --git a/book/environment.md b/book/environment.md index 30bed7c0993..d975521b79c 100644 --- a/book/environment.md +++ b/book/environment.md @@ -5,22 +5,22 @@ A common task in a shell is to control the environment that external application You can see the current environment variables in the $env variable: ```nu -~> $env | table -e -╭──────────────────────────────────┬───────────────────────────────────────────╮ -│ │ ╭──────┬────────────────────────────────╮ │ -│ ENV_CONVERSIONS │ │ │ ╭─────────────┬──────────────╮ │ │ -│ │ │ PATH │ │ from_string │ │ │ │ -│ │ │ │ │ to_string │ │ │ │ -│ │ │ │ ╰─────────────┴──────────────╯ │ │ -│ │ │ │ ╭─────────────┬──────────────╮ │ │ -│ │ │ Path │ │ from_string │ │ │ │ -│ │ │ │ │ to_string │ │ │ │ -│ │ │ │ ╰─────────────┴──────────────╯ │ │ -│ │ ╰──────┴────────────────────────────────╯ │ -│ HOME │ /Users/jelle │ -│ LSCOLORS │ GxFxCxDxBxegedabagaced │ -| ... | ... | -╰──────────────────────────────────┴───────────────────────────────────────────╯ +$env | table -e +# => ╭──────────────────────────────────┬───────────────────────────────────────────╮ +# => │ │ ╭──────┬────────────────────────────────╮ │ +# => │ ENV_CONVERSIONS │ │ │ ╭─────────────┬──────────────╮ │ │ +# => │ │ │ PATH │ │ from_string │ │ │ │ +# => │ │ │ │ │ to_string │ │ │ │ +# => │ │ │ │ ╰─────────────┴──────────────╯ │ │ +# => │ │ │ │ ╭─────────────┬──────────────╮ │ │ +# => │ │ │ Path │ │ from_string │ │ │ │ +# => │ │ │ │ │ to_string │ │ │ │ +# => │ │ │ │ ╰─────────────┴──────────────╯ │ │ +# => │ │ ╰──────┴────────────────────────────────╯ │ +# => │ HOME │ /Users/jelle │ +# => │ LSCOLORS │ GxFxCxDxBxegedabagaced │ +# => | ... | ... | +# => ╰──────────────────────────────────┴───────────────────────────────────────────╯ ``` In Nushell, environment variables can be any value and have any type. You can see the type of an env variable with the describe command, for example: `$env.PROMPT_COMMAND | describe`. @@ -38,7 +38,7 @@ There are several ways to set an environment variable: Using the `$env.VAR = "val"` is the most straightforward method ```nu -> $env.FOO = 'BAR' +$env.FOO = 'BAR' ``` So, if you want to extend the Windows `Path` variable, for example, you could do that as follows. @@ -55,7 +55,7 @@ If you want to give it the lowest priority instead, you can use the [`append`](/ If you have more than one environment variable you'd like to set, you can use [`load-env`](/commands/docs/load-env.md) to create a table of name/value pairs and load multiple variables at the same time: ```nu -> load-env { "BOB": "FOO", "JAY": "BAR" } +load-env { "BOB": "FOO", "JAY": "BAR" } ``` ### One-shot Environment Variables @@ -76,41 +76,41 @@ See [Modules](modules.md) for details. Individual environment variables are fields of a record that is stored in the `$env` variable and can be read with `$env.VARIABLE`: ```nu -> $env.FOO -BAR +$env.FOO +# => BAR ``` Sometimes, you may want to access an environmental variable which might be unset. Consider using the [question mark operator](types_of_data.md#optional-cell-paths) to avoid an error: ```nu -> $env.FOO | describe -Error: nu::shell::column_not_found - - × Cannot find column - ╭─[entry #1:1:1] - 1 │ $env.FOO - · ──┬─ ─┬─ - · │ ╰── cannot find column 'FOO' - · ╰── value originates here - ╰──── +$env.FOO | describe +# => Error: nu::shell::column_not_found +# => +# => × Cannot find column +# => ╭─[entry #1:1:1] +# => 1 │ $env.FOO +# => · ──┬─ ─┬─ +# => · │ ╰── cannot find column 'FOO' +# => · ╰── value originates here +# => ╰──── -> $env.FOO? | describe -nothing +$env.FOO? | describe +# => nothing -> $env.FOO? | default "BAR" -BAR +$env.FOO? | default "BAR" +# => BAR ``` Alternatively, you can check for the presence of an environmental variable with `in`: ``` -> $env.FOO -BAR +$env.FOO +# => BAR -> if "FOO" in $env { -> echo $env.FOO -> } -BAR +if "FOO" in $env { + echo $env.FOO +} +# => BAR ``` ### Case sensitivity @@ -126,14 +126,14 @@ When you set an environment variable, it will be available only in the current s Here is a small example to demonstrate the environment scoping: ```nu -> $env.FOO = "BAR" -> do { +$env.FOO = "BAR" +do { $env.FOO = "BAZ" $env.FOO == "BAZ" } -true -> $env.FOO == "BAR" -true +# => true +$env.FOO == "BAR" +# => true ``` See also: [Changing the Environment in a Custom Command](./custom_commands.html#changing-the-environment-in-a-custom-command). @@ -147,15 +147,15 @@ A common task in a shell is to change the directory using the [`cd`](/commands/d A common shorthand to set an environment variable once is available, inspired by Bash and others: ```nu -> FOO=BAR $env.FOO -BAR +FOO=BAR $env.FOO +# => BAR ``` You can also use [`with-env`](/commands/docs/with-env.md) to do the same thing more explicitly: ```nu -> with-env { FOO: BAR } { $env.FOO } -BAR +with-env { FOO: BAR } { $env.FOO } +# => BAR ``` The [`with-env`](/commands/docs/with-env.md) command will temporarily set the environment variable to the value given (here: the variable "FOO" is given the value "BAR"). Once this is done, the [block](types_of_data.md#blocks) will run with this new environment variable set. @@ -195,26 +195,26 @@ $env.ENV_CONVERSIONS = { Now, within a Nushell instance: ```nu -> with-env { FOO : 'a-b-c' } { nu } # runs Nushell with FOO env. var. set to 'a-b-c' +with-env { FOO : 'a-b-c' } { nu } # runs Nushell with FOO env. var. set to 'a-b-c' -> $env.FOO - 0 a - 1 b - 2 c +$env.FOO +# => 0 a +# => 1 b +# => 2 c ``` You can see the `$env.FOO` is now a list in a new Nushell instance with the updated config. You can also test the conversion manually by ```nu -> do $env.ENV_CONVERSIONS.FOO.from_string 'a-b-c' +do $env.ENV_CONVERSIONS.FOO.from_string 'a-b-c' ``` Now, to test the conversion list -> string, run: ```nu -> nu -c '$env.FOO' -a-b-c +nu -c '$env.FOO' +# => a-b-c ``` Because `nu` is an external program, Nushell translated the `[ a b c ]` list according to `ENV_CONVERSIONS.FOO.to_string` and passed it to the `nu` process. @@ -228,19 +228,19 @@ _(Important! The environment conversion string -> value happens **after** the en You can remove an environment variable only if it was set in the current scope via [`hide-env`](/commands/docs/hide-env.md): ```nu -> $env.FOO = 'BAR' -... -> hide-env FOO +$env.FOO = 'BAR' +# => ... +hide-env FOO ``` The hiding is also scoped which both allows you to remove an environment variable temporarily and prevents you from modifying a parent environment from within a child scope: ```nu -> $env.FOO = 'BAR' -> do { - hide-env FOO - # $env.FOO does not exist - } -> $env.FOO -BAR +$env.FOO = 'BAR' +do { + hide-env FOO + # $env.FOO does not exist +} +$env.FOO +# => BAR ``` diff --git a/book/externs.md b/book/externs.md index 40389c95066..156ca892c24 100644 --- a/book/externs.md +++ b/book/externs.md @@ -35,7 +35,7 @@ Notice that the syntax here is similar to that of the `def` keyword when definin This implementation: -- Will provide `-p` and `-i` (with descriptions) as possibly completions for `ssh -`. +- Will provide `-p` and `-i` (with descriptions) as possible completions for `ssh -`. - Will perform parse-time type checking. Attempting to use a non-`int` for the port number will result in an error (and error-condition syntax highlighting). - Will offer parse-time syntax highlighting based on the shapes of the arguments. - Will offer any private key files in `~/.ssh` as completion values for the `-i` (identity) option diff --git a/book/hooks.md b/book/hooks.md index 55b655bef85..1210ada2563 100644 --- a/book/hooks.md +++ b/book/hooks.md @@ -88,12 +88,12 @@ Environment variables defined inside the hook **block** will be preserved in a s You can test it with the following example: ```nu -> $env.config = ($env.config | upsert hooks { +$env.config = ($env.config | upsert hooks { pre_prompt: { $env.SPAM = "eggs" } }) -> $env.SPAM -eggs +$env.SPAM +# => eggs ``` The hook blocks otherwise follow the general scoping rules, i.e., commands, aliases, etc. defined within the block will be thrown away once the block ends. @@ -150,12 +150,12 @@ You can think of it as if you typed the string into the REPL and hit Enter. So, the hook from the previous section can be also written as ```nu -> $env.config = ($env.config | upsert hooks { +$env.config = ($env.config | upsert hooks { pre_prompt: '$env.SPAM = "eggs"' }) -> $env.SPAM -eggs +$env.SPAM +# => eggs ``` This feature can be used, for example, to conditionally bring in definitions based on the current directory: diff --git a/book/line_editor.md b/book/line_editor.md index d050653f875..cb69373c981 100644 --- a/book/line_editor.md +++ b/book/line_editor.md @@ -1,124 +1,207 @@ # Reedline, Nu's Line Editor -Nushell's line editor [Reedline](https://github.com/nushell/reedline) is a -cross-platform line reader designed to be modular and flexible. The engine is -in charge of controlling the command history, validations, completions, hints -and screen paint. +Nushell's line-editor [Reedline](https://github.com/nushell/reedline) is +cross-platform and designed to be modular and flexible. The line-editor is +in charge of controlling the command history, validations, completions, hints, +screen paint, and more. -## Configuration +[[toc]] -### Editing Mode +## Multi-line Editing -Reedline allows you to edit text using two modes: vi and emacs. If not -specified, the default edit mode is emacs mode. In order to select your -favorite you need to modify your config file and write down your preferred -mode. +Reedline allows Nushell commandlines to extend across multiple lines. This can be accomplished using several methods: -For example: +1. Pressing Enter when a bracketed expression is open. + + For example: + + ```nu + def my-command [] { + ``` + + Pressing Enter after the open-bracket will insert a newline. This will also occur with opening (and valid) `(` and `[` expressions. + + This is commonly used to create blocks and closures (as above), but also list, record, and table literals: + + ```nu + let file = { + name: 'repos.sqlite' + hash: 'b939a3fa4ca011ca1aa3548420e78cee' + version: '1.4.2' + } + ``` + + It can even be used to continue a single command across multiple lines: + + ::: details Example + + ```nu + ( + tar + -cvz + -f archive.tgz + --exclude='*.temp' + --directory=../project/ + ./ + ) + ``` + + ::: + +2. Pressing Enter at the end of a line with a trailing pipe-symbol (`|`). + + ```nu + ls | + where name =~ '^[0-9]' | # Comments after a trailing pipe are okay + get name | + mv ...$in ./backups/ + ``` + +3. Manually insert a newline using Alt+Enter or Shift+Enter. + + This can be used to create a somewhat more readable version of the previous commandline: + + ```nu + ls + | where name =~ '^[0-9]' # Files starting with a digit + | get name + | mv ...$in ./backups/ + ``` + + ::: tip + It's possible that one or both of these keybindings may be intercepted by the terminal application or window-manager. For instance, Windows Terminal (and most other terminal applications on Windows) assign Alt+Enter to expand the terminal to full-screen. If neither of the above keybindings work in your terminal, you can assign a different keybinding to: + + ```nu + event: { edit: insertnewline } + ``` + + See [Keybindings](#keybindings) below for more details. + + ::: + +4. Pressing Ctrl+O opens the current commandline in your editor. Saving the resulting file and exiting the editor will update the commandline with the results. + +## Setting the Editing Mode + +Reedline allows you to edit text using two modes — Vi and Emacs. If not +specified, the default mode is Emacs. To change the mode, use the +`edit_mode` setting. ```nu - $env.config = { - ... - edit_mode: emacs - ... - } +$env.config.edit_mode = 'vi' ``` -#### Default Keybindings - -Each edit mode comes with the usual keybinding for vi and emacs text editing. - -Emacs and Vi Insert keybindings - -| Key | Event | -| ----------- | --------------------- | -| Esc | Esc | -| Backspace | Backspace | -| End | Move to end of line | -| End | Complete history hint | -| Home | Move to line start | -| Ctr + c | Cancel current line | -| Ctr + l | Clear screen | -| Ctr + r | Search history | -| Ctr + Right | Complete history word | -| Ctr + Right | Move word right | -| Ctr + Left | Move word left | -| Up | Move menu up | -| Up | Move up | -| Down | Move menu down | -| Down | Move down | -| Left | Move menu left | -| Left | Move left | -| Right | History hint complete | -| Right | Move menu right | -| Right | Move right | -| Ctr + b | Move menu left | -| Ctr + b | Move left | -| Ctr + f | History hint complete | -| Ctr + f | Move menu right | -| Ctr + f | Move right | -| Ctr + p | Move menu up | -| Ctr + p | Move up | -| Ctr + n | Move menu down | -| Ctr + n | Move down | - -Vi Normal keybindings - -| Key | Event | -| ------- | ------------------- | -| Ctr + c | Cancel current line | -| Ctr + l | Clear screen | -| Up | Move menu up | -| Up | Move up | -| Down | Move menu down | -| Down | Move down | -| Left | Move menu left | -| Left | Move left | -| Right | Move menu right | -| Right | Move right | - -Besides the previous keybindings, while in Vi normal mode you can use the classic -vi mode of executing actions by selecting a motion or an action. The available -options for the combinations are: - -Vi Normal motions - -| Key | motion | -| --- | ----------------- | -| w | Word | -| 0 | Line start | -| $ | Line end | -| f | Right until char | -| t | Right before char | -| F | Left until char | -| T | Left before char | - -Vi Normal actions - -| Key | action | -| --- | ------------------------------- | -| d | Delete | -| p | Paste after | -| P | Paste before | -| h | Move left | -| l | Move right | -| j | Move down | -| k | Move up | -| w | Move word right | -| b | Move word left | -| i | Enter Vi insert at current char | -| a | Enter Vi insert after char | -| 0 | Move to start of line | -| ^ | Move to start of line | -| $ | Move to end of line | -| u | Undo | -| c | Change | -| x | Delete char | -| s | History search | -| D | Delete to end | -| A | Append to end | - -### Command History +This can be changed at the commandline or persisted in `config.nu`. + +::: note +Vi is a "modal" editor with "normal" mode and an "insert" mode. We recommend +becoming familiar with these modes through the use of the Vim or Neovim editors +before using Vi mode in Nushell. Each has a built-in tutorial covering the basics +(and more) of modal editing. +::: + +## Default Keybindings + +Each edit mode comes with common keybindings for Vi and Emacs text editing. + +### Emacs and Vi-insert Keybindings + +These keybinding events apply to both Emacs and Vi-insert mode: + +| Key | Event | +| ------------------------------------------ | ----------------------------------- | +| Shift+Enter | Insert newline | +| Alt+Enter | Insert newline | +| Backspace | Backspace | +| End | Move to end of line | +| End | Complete history hint | +| Home | Move to line start | +| Ctrl+C | Cancel current line | +| Ctrl+L | Clear screen | +| Ctrl+R | Search history | +| Ctrl+ (Right Arrow) | Complete history word | +| Ctrl+ (Right Arrow) | Move word right | +| Ctrl+ (Left Arrow) | Move word left | +| (Up Arrow) | Move up | +| (Down Arrow) | Move down | +| (Left Arrow) | Move left | +| (Right Arrow) | Move right | +| Ctrl+P | Move up | +| Ctrl+N | Move down | +| Ctrl+B | Move left | +| Ctrl+F | Move right | +| (Right Arrow) | History-hint complete | +| Ctrl+F | History-hint complete | +| Alt+F | History-hint complete one word | +| Alt+ (Left Arrow) | History-hint complete one word less | + +### Vi-insert Keybindings + +These keybinding events apply only to Vi-insert mode: + +| Key | Event | +| -------------- | ------------------------ | +| Esc | Switch to Vi-normal mode | + +### Vi-normal Keybindings + +These keybinding events apply only to Vi-normal mode: + +| Key | Event | +| ------------------------------------------- | ------------------- | +| Ctrl+C | Cancel current line | +| Ctrl+L | Clear screen | +| (Up Arrow) | Move up | +| (Down Arrow) | Move down | +| (Left Arrow) | Move left | +| (Right Arrow) | Move right | +| Ctrl>+ (Right Arrow) | Move right one word | +| Ctrl>+ (Left Arrow) | Move left one word | + +### Vi-normal Motions + +As with Vi, many motions and actions can be combined with an optional count in normal-mode. For example, 3dw deletes the next three words. + +| Key | Motion | +| -------------------------------------- | --------------------------------------------- | +| w | Move to beginning of next word | +| e | Move to end of current or next word | +| b | Move to beginning of current or previous word | +| 0 | Move to start of line | +| $ | Move to end of line | +| h | Move left | +| l | Move right | +| j | Move down | +| k | Move up | +| f+\ | Move right to \ | +| t+\ | Move right to before \ | +| Shift+F+\ | Move left to \ | +| Shift+T+\ | Move left to after \ | + +### Vi-normal Actions + +These actions can be combined with many of the [motions above](#vi-normal-motions). + +| Key | Action | +| ----------------------------- | -------------------------------------------------- | +| d | Delete | +| Shift+D | Delete to end of line | +| p | Paste after current character | +| Shift+P | Paste before current character | +| i | Enter Vi insert-mode (append) at current character | +| Shift+I | Enter insert-mode at beginning of line | +| a | Append after current character | +| Shift+A | Append to end of line | +| 0 | Move to start of line | +| ^ | Move to start of line | +| $ | Move to end of line | +| c | Change | +| r | Replace | +| s | Substitute character(s) | +| x | Delete character | +| u | Undo | + +## Command History As mentioned before, Reedline manages and stores all the commands that are edited and sent to Nushell. To configure the max number of records that @@ -136,50 +219,9 @@ Reedline should store you will need to adjust this value in your config file: } ``` -### Customizing your Prompt - -Reedline prompt is also highly customizable. In order to construct your perfect -prompt, you could define the next environment variables in your config file: - -```nu -# Use nushell functions to define your right and left prompt -def create_left_prompt [] { - let path_segment = ($env.PWD) - - $path_segment -} +## Customizing the Prompt -def create_right_prompt [] { - let time_segment = ([ - (date now | format date '%m/%d/%Y %r') - ] | str join) - - $time_segment -} - -$env.PROMPT_COMMAND = { create_left_prompt } -$env.PROMPT_COMMAND_RIGHT = { create_right_prompt } -``` - -::: tip -You don't have to define the environment variables using Nushell -functions. You can use simple strings to define them. -::: - -You can also customize the prompt indicator for the line editor by modifying -the next env variables. - -```nu -$env.PROMPT_INDICATOR = "〉" -$env.PROMPT_INDICATOR_VI_INSERT = ": " -$env.PROMPT_INDICATOR_VI_NORMAL = "〉" -$env.PROMPT_MULTILINE_INDICATOR = "::: " -``` - -::: tip -The prompt indicators are environment variables that represent the -state of the prompt -::: +The Reedline prompt is configured using a number of environment variables. See [Prompt Configuration](./configuration.md#prompt-configuration) for details. ## Keybindings @@ -538,8 +580,7 @@ e.g. to disable screen clearing with `Ctrl + l` for all edit modes ### Troubleshooting Keybinding Problems -Your terminal environment may not always propagate your key combinations on to nushell the way you expect it to. -You can use the command [`keybindings listen`](/commands/docs/keybindings_listen.md) to figure out if certain keypresses are actually received by nushell, and how. +Your terminal environment may not always propagate your key combinations on to Nushell the way you expect it to. You can use the command [`keybindings listen`](/commands/docs/keybindings_listen.md) to determine if certain keypresses are actually received by Nushell, and how. ## Menus @@ -547,6 +588,30 @@ Thanks to Reedline, Nushell has menus that can help you with your day to day shell scripting. Next we present the default menus that are always available when using Nushell +### Menu Keybindings + +When a menu is active, some keybindings change based on the keybinding [`until` specifier](#until-type) discussed above. Common keybindings for menus are: + +| Key | Event | +| ------------------------------- | -------------------- | +| Tab | Select next item | +| Shift+Tab | Select previous item | +| Enter | Accept selection | +| (Up Arrow) | Move menu up | +| (Down Arrow) | Move menu down | +| (Left Arrow) | Move menu left | +| (Right Arrow) | Move menu right | +| Ctrl+P | Move menu up | +| Ctrl+N | Move menu down | +| Ctrl+B | Move menu left | +| Ctrl+F | Move menu right | + +::: note +Menu direction behavior varies based on the menu type (see below). For example, +in a `description` menu, "Up" and "Down" apply to the "Extra" list, but in a +`list` menu the directions apply to the selection. +::: + ### Help Menu The help menu is there to ease your transition into Nushell. Say you are diff --git a/book/loading_data.md b/book/loading_data.md index e38a4b6d9a6..9c3fab8936c 100644 --- a/book/loading_data.md +++ b/book/loading_data.md @@ -13,8 +13,8 @@ In a similar way to [`ls`](/commands/docs/ls.md), opening a file type that Nu un If we wanted to check the version of the project we were looking at, we can use the [`get`](/commands/docs/get.md) command. ```nu -> open editors/vscode/package.json | get version -1.0.0 +open editors/vscode/package.json | get version +# => 1.0.0 ``` Nu currently supports the following formats for loading data directly into tables: @@ -44,7 +44,7 @@ You can thus simply extend the set of supported file types of `open` by creating But what happens if you load a text file that isn't one of these? Let's try it: ```nu -> open README.md +open README.md ``` We're shown the contents of the file. @@ -98,10 +98,10 @@ An important part of working with data coming from outside Nu is that it's not a Let's imagine that we're given this data file: ```nu -> open people.txt -Octavia | Butler | Writer -Bob | Ross | Painter -Antonio | Vivaldi | Composer +open people.txt +# => Octavia | Butler | Writer +# => Bob | Ross | Painter +# => Antonio | Vivaldi | Composer ``` Each bit of data we want is separated by the pipe ('|') symbol, and each person is on a separate line. Nu doesn't have a pipe-delimited file format by default, so we'll have to parse this ourselves. @@ -109,75 +109,75 @@ Each bit of data we want is separated by the pipe ('|') symbol, and each person The first thing we want to do when bringing in the file is to work with it a line at a time: ```nu -> open people.txt | lines -───┬────────────────────────────── - 0 │ Octavia | Butler | Writer - 1 │ Bob | Ross | Painter - 2 │ Antonio | Vivaldi | Composer -───┴────────────────────────────── +open people.txt | lines +# => ───┬────────────────────────────── +# => 0 │ Octavia | Butler | Writer +# => 1 │ Bob | Ross | Painter +# => 2 │ Antonio | Vivaldi | Composer +# => ───┴────────────────────────────── ``` We can see that we're working with the lines because we're back into a list. Our next step is to see if we can split up the rows into something a little more useful. For that, we'll use the [`split`](/commands/docs/split.md) command. [`split`](/commands/docs/split.md), as the name implies, gives us a way to split a delimited string. We will use [`split`](/commands/docs/split.md)'s `column` subcommand to split the contents across multiple columns. We tell it what the delimiter is, and it does the rest: ```nu -> open people.txt | lines | split column "|" -───┬──────────┬───────────┬─────────── - # │ column1 │ column2 │ column3 -───┼──────────┼───────────┼─────────── - 0 │ Octavia │ Butler │ Writer - 1 │ Bob │ Ross │ Painter - 2 │ Antonio │ Vivaldi │ Composer -───┴──────────┴───────────┴─────────── +open people.txt | lines | split column "|" +# => ───┬──────────┬───────────┬─────────── +# => # │ column1 │ column2 │ column3 +# => ───┼──────────┼───────────┼─────────── +# => 0 │ Octavia │ Butler │ Writer +# => 1 │ Bob │ Ross │ Painter +# => 2 │ Antonio │ Vivaldi │ Composer +# => ───┴──────────┴───────────┴─────────── ``` That _almost_ looks correct. It looks like there's an extra space there. Let's [`trim`](/commands/docs/str_trim.md) that extra space: ```nu -> open people.txt | lines | split column "|" | str trim -───┬─────────┬─────────┬────────── - # │ column1 │ column2 │ column3 -───┼─────────┼─────────┼────────── - 0 │ Octavia │ Butler │ Writer - 1 │ Bob │ Ross │ Painter - 2 │ Antonio │ Vivaldi │ Composer -───┴─────────┴─────────┴────────── +open people.txt | lines | split column "|" | str trim +# => ───┬─────────┬─────────┬────────── +# => # │ column1 │ column2 │ column3 +# => ───┼─────────┼─────────┼────────── +# => 0 │ Octavia │ Butler │ Writer +# => 1 │ Bob │ Ross │ Painter +# => 2 │ Antonio │ Vivaldi │ Composer +# => ───┴─────────┴─────────┴────────── ``` Not bad. The [`split`](/commands/docs/split.md) command gives us data we can use. It also goes ahead and gives us default column names: ```nu -> open people.txt | lines | split column "|" | str trim | get column1 -───┬───────── - 0 │ Octavia - 1 │ Bob - 2 │ Antonio -───┴───────── +open people.txt | lines | split column "|" | str trim | get column1 +# => ───┬───────── +# => 0 │ Octavia +# => 1 │ Bob +# => 2 │ Antonio +# => ───┴───────── ``` We can also name our columns instead of using the default names: ```nu -> open people.txt | lines | split column "|" first_name last_name job | str trim -───┬────────────┬───────────┬────────── - # │ first_name │ last_name │ job -───┼────────────┼───────────┼────────── - 0 │ Octavia │ Butler │ Writer - 1 │ Bob │ Ross │ Painter - 2 │ Antonio │ Vivaldi │ Composer -───┴────────────┴───────────┴────────── +open people.txt | lines | split column "|" first_name last_name job | str trim +# => ───┬────────────┬───────────┬────────── +# => # │ first_name │ last_name │ job +# => ───┼────────────┼───────────┼────────── +# => 0 │ Octavia │ Butler │ Writer +# => 1 │ Bob │ Ross │ Painter +# => 2 │ Antonio │ Vivaldi │ Composer +# => ───┴────────────┴───────────┴────────── ``` Now that our data is in a table, we can use all the commands we've used on tables before: ```nu -> open people.txt | lines | split column "|" first_name last_name job | str trim | sort-by first_name -───┬────────────┬───────────┬────────── - # │ first_name │ last_name │ job -───┼────────────┼───────────┼────────── - 0 │ Antonio │ Vivaldi │ Composer - 1 │ Bob │ Ross │ Painter - 2 │ Octavia │ Butler │ Writer -───┴────────────┴───────────┴────────── +open people.txt | lines | split column "|" first_name last_name job | str trim | sort-by first_name +# => ───┬────────────┬───────────┬────────── +# => # │ first_name │ last_name │ job +# => ───┼────────────┼───────────┼────────── +# => 0 │ Antonio │ Vivaldi │ Composer +# => 1 │ Bob │ Ross │ Painter +# => 2 │ Octavia │ Butler │ Writer +# => ───┴────────────┴───────────┴────────── ``` There are other commands you can use to work with strings: @@ -188,12 +188,12 @@ There are other commands you can use to work with strings: There is also a set of helper commands we can call if we know the data has a structure that Nu should be able to understand. For example, let's open a Rust lock file: ```nu -> open Cargo.lock -# This file is automatically @generated by Cargo. -# It is not intended for manual editing. -[[package]] -name = "adhoc_derive" -version = "0.1.2" +open Cargo.lock +# => # This file is automatically @generated by Cargo. +# => # It is not intended for manual editing. +# => [[package]] +# => name = "adhoc_derive" +# => version = "0.1.2" ``` The "Cargo.lock" file is actually a .toml file, but the file extension isn't .toml. That's okay, we can use the [`from`](/commands/docs/from.md) command using the `toml` subcommand: @@ -207,12 +207,12 @@ The [`from`](/commands/docs/from.md) command can be used for each of the structu While it's helpful to be able to open a file and immediately work with a table of its data, this is not always what you want to do. To get to the underlying text, the [`open`](/commands/docs/open.md) command can take an optional `--raw` flag: ```nu -> open Cargo.toml --raw -[package] name = "nu" -version = "0.1.3" -authors = ["Yehuda Katz ", "Sophia Turner <547158+sophiajt@users.noreply.github.com>"] -description = "A shell for the GitHub era" -license = "MIT" +open Cargo.toml --raw +# => [package] name = "nu" +# => version = "0.1.3" +# => authors = ["Yehuda Katz ", "Sophia Turner <547158+sophiajt@users.noreply.github.com>"] +# => description = "A shell for the GitHub era" +# => license = "MIT" ``` ## SQLite @@ -220,19 +220,19 @@ license = "MIT" SQLite databases are automatically detected by [`open`](/commands/docs/open.md), no matter what their file extension is. You can open a whole database: ```nu -> open foo.db +open foo.db ``` Or [`get`](/commands/docs/get.md) a specific table: ```nu -> open foo.db | get some_table +open foo.db | get some_table ``` Or run any SQL query you like: ```nu -> open foo.db | query db "select * from some_table" +open foo.db | query db "select * from some_table" ``` (Note: some older versions of Nu use `into db | query` instead of `query db` ) diff --git a/book/metadata.md b/book/metadata.md index 24f711cdeb6..950a050e7ed 100644 --- a/book/metadata.md +++ b/book/metadata.md @@ -3,14 +3,14 @@ In using Nu, you may have come across times where you felt like there was something extra going on behind the scenes. For example, let's say that you try to open a file that Nu supports only to forget and try to convert again: ```nu -> open Cargo.toml | from toml -error: Expected a string from pipeline -- shell:1:18 -1 | open Cargo.toml | from toml - | ^^^^^^^^^ requires string input -- shell:1:5 -1 | open Cargo.toml | from toml - | ---------- object originates from here +open Cargo.toml | from toml +# => error: Expected a string from pipeline +# => - shell:1:18 +# => 1 | open Cargo.toml | from toml +# => | ^^^^^^^^^ requires string input +# => - shell:1:5 +# => 1 | open Cargo.toml | from toml +# => | ---------- object originates from here ``` The error message tells us not only that what we gave [`from toml`](/commands/docs/from_toml.md) wasn't a string, but also where the value originally came from. How would it know that? @@ -20,20 +20,20 @@ Values that flow through a pipeline in Nu often have a set of additional informa Let's run the [`open`](/commands/docs/open.md) command again, but this time, we'll look at the tags it gives back: ```nu -> metadata (open Cargo.toml) -╭──────┬───────────────────╮ -│ span │ {record 2 fields} │ -╰──────┴───────────────────╯ +metadata (open Cargo.toml) +# => ╭──────┬───────────────────╮ +# => │ span │ {record 2 fields} │ +# => ╰──────┴───────────────────╯ ``` Currently, we track only the span of where values come from. Let's take a closer look at that: ```nu -> metadata (open Cargo.toml) | get span -╭───────┬────────╮ -│ start │ 212970 │ -│ end │ 212987 │ -╰───────┴────────╯ +metadata (open Cargo.toml) | get span +# => ╭───────┬────────╮ +# => │ start │ 212970 │ +# => │ end │ 212987 │ +# => ╰───────┴────────╯ ``` The span "start" and "end" here refer to where the underline will be in the line. If you count over 5, and then count up to 15, you'll see it lines up with the "Cargo.toml" filename. This is how the error we saw earlier knew what to underline. diff --git a/book/navigating_structured_data.md b/book/navigating_structured_data.md index 82da7978c76..754df773d0e 100644 --- a/book/navigating_structured_data.md +++ b/book/navigating_structured_data.md @@ -47,12 +47,12 @@ For a record, the cell-path specifies the name of a key, which is a `string`. #### Example - Access a Record Value: ```nu -> let my_record = { +let my_record = { a: 5 b: 42 } -> $my_record.b + 5 -47 +$my_record.b + 5 +# => 47 ``` ### Lists @@ -64,9 +64,9 @@ For a list, the cell-path specifies the position (index) of the value in the lis Remember, list indices are 0-based. ```nu -> let scoobies_list = [ Velma Fred Daphne Shaggy Scooby ] -> $scoobies_list.2 -Daphne +let scoobies_list = [ Velma Fred Daphne Shaggy Scooby ] +$scoobies_list.2 +# => Daphne ``` ### Tables @@ -137,30 +137,30 @@ This represents weather data in the form of a table with three columns: Access the second day's data as a record: ```nu -> $data.1 -╭───────────┬───────────────╮ -│ date │ 2 years ago │ -│ │ ╭───┬───────╮ │ -│ temps │ │ 0 │ 35.24 │ │ -│ │ │ 1 │ 35.94 │ │ -│ │ │ 2 │ 34.91 │ │ -│ │ │ 3 │ 35.24 │ │ -│ │ │ 4 │ 36.65 │ │ -│ │ ╰───┴───────╯ │ -│ condition │ sunny │ -╰───────────┴───────────────╯ +$data.1 +# => ╭───────────┬───────────────╮ +# => │ date │ 2 years ago │ +# => │ │ ╭───┬───────╮ │ +# => │ temps │ │ 0 │ 35.24 │ │ +# => │ │ │ 1 │ 35.94 │ │ +# => │ │ │ 2 │ 34.91 │ │ +# => │ │ │ 3 │ 35.24 │ │ +# => │ │ │ 4 │ 36.65 │ │ +# => │ │ ╰───┴───────╯ │ +# => │ condition │ sunny │ +# => ╰───────────┴───────────────╯ ``` #### Example - Access a Table Column (List) ```nu -> $data.condition -╭───┬────────╮ -│ 0 │ sunny │ -│ 1 │ sunny │ -│ 2 │ cloudy │ -│ 3 │ rain │ -╰───┴────────╯ +$data.condition +# => ╭───┬────────╮ +# => │ 0 │ sunny │ +# => │ 1 │ sunny │ +# => │ 2 │ cloudy │ +# => │ 3 │ rain │ +# => ╰───┴────────╯ ``` #### Example - Access a Table Cell (Value) @@ -168,8 +168,8 @@ Access the second day's data as a record: The condition for the fourth day: ```nu -> $data.condition.3 -rain +$data.condition.3 +# => rain ``` ### Nested Data @@ -181,8 +181,8 @@ Since data can be nested, a cell-path can contain references to multiple names o To obtain the temperature at the second weather station on the third day: ```nu -> $data.temps.2.1 -36.67 +$data.temps.2.1 +# => 36.67 ``` The first index `2` accesses the third day, then the next index `1` accesses the second weather station's temperature reading. @@ -202,31 +202,31 @@ Continuing with the sample table above: ### Example - `get` vs. `select` a table row ```nu -> $data | get 1 -╭───────────┬───────────────╮ -│ date │ 2 years ago │ -│ │ ╭───┬───────╮ │ -│ temps │ │ 0 │ 35.24 │ │ -│ │ │ 1 │ 35.94 │ │ -│ │ │ 2 │ 34.91 │ │ -│ │ │ 3 │ 35.24 │ │ -│ │ │ 4 │ 36.65 │ │ -│ │ ╰───┴───────╯ │ -│ condition │ sunny │ -╰───────────┴───────────────╯ - -> $data | select 1 -╭───┬─────────────┬───────────────┬───────────╮ -│ # │ date │ temps │ condition │ -├───┼─────────────┼───────────────┼───────────┤ -│ 0 │ 2 years ago │ ╭───┬───────╮ │ sunny │ -│ │ │ │ 0 │ 35.24 │ │ │ -│ │ │ │ 1 │ 35.94 │ │ │ -│ │ │ │ 2 │ 34.91 │ │ │ -│ │ │ │ 3 │ 35.24 │ │ │ -│ │ │ │ 4 │ 36.65 │ │ │ -│ │ │ ╰───┴───────╯ │ │ -╰───┴─────────────┴───────────────┴───────────╯ +$data | get 1 +# => ╭───────────┬───────────────╮ +# => │ date │ 2 years ago │ +# => │ │ ╭───┬───────╮ │ +# => │ temps │ │ 0 │ 35.24 │ │ +# => │ │ │ 1 │ 35.94 │ │ +# => │ │ │ 2 │ 34.91 │ │ +# => │ │ │ 3 │ 35.24 │ │ +# => │ │ │ 4 │ 36.65 │ │ +# => │ │ ╰───┴───────╯ │ +# => │ condition │ sunny │ +# => ╰───────────┴───────────────╯ + +$data | select 1 +# => ╭───┬─────────────┬───────────────┬───────────╮ +# => │ # │ date │ temps │ condition │ +# => ├───┼─────────────┼───────────────┼───────────┤ +# => │ 0 │ 2 years ago │ ╭───┬───────╮ │ sunny │ +# => │ │ │ │ 0 │ 35.24 │ │ │ +# => │ │ │ │ 1 │ 35.94 │ │ │ +# => │ │ │ │ 2 │ 34.91 │ │ │ +# => │ │ │ │ 3 │ 35.24 │ │ │ +# => │ │ │ │ 4 │ 36.65 │ │ │ +# => │ │ │ ╰───┴───────╯ │ │ +# => ╰───┴─────────────┴───────────────┴───────────╯ ``` Notice that: @@ -240,7 +240,7 @@ The row indices of the table resulting from `select` are not the same as that of To obtain the original index, you can using the [`enumerate`](/commands/docs/enumerate.md) command. For example: ```nu -> $data | enumerate | select 1 +$data | enumerate | select 1 ``` ::: @@ -250,13 +250,13 @@ To obtain the original index, you can using the [`enumerate`](/commands/docs/enu Because `select` results in a new table, it's possible to specify multiple column names, row indices, or even both. This example creates a new table containing the date and condition columns of the first and second rows: ```nu -> $data | select date condition 0 1 -╭───┬─────────────┬───────────╮ -│ # │ date │ condition │ -├───┼─────────────┼───────────┤ -│ 0 │ 2 years ago │ sunny │ -│ 1 │ 2 years ago │ sunny │ -╰───┴─────────────┴───────────╯ +$data | select date condition 0 1 +# => ╭───┬─────────────┬───────────╮ +# => │ # │ date │ condition │ +# => ├───┼─────────────┼───────────┤ +# => │ 0 │ 2 years ago │ sunny │ +# => │ 1 │ 2 years ago │ sunny │ +# => ╰───┴─────────────┴───────────╯ ``` ## Key/Column names with spaces @@ -266,16 +266,16 @@ If a key name or column name contains spaces or other characters that prevent it Example: ```nu -> let record_example = { +let record_example = { "key x":12 "key y":4 } -> $record_example."key x" -12 +$record_example."key x" +# => 12 # or -> $record_example | get "key x" -12 +$record_example | get "key x" +# => 12 ``` Quotes are also required when a key name may be confused for a numeric value. @@ -283,14 +283,14 @@ Quotes are also required when a key name may be confused for a numeric value. Example: ```nu -> let record_example = { - "1": foo - "2": baz - "3": far - } - -> $record_example."1" - foo +let record_example = { + "1": foo + "2": baz + "3": far +} + +$record_example."1" +# => foo ``` Do not confuse the key name with a row index in this case. Here, the first item is _assigned_ the key name `1` (a string). If converted to a table using the `transpose` command, key `1` (`string`) would be at row-index `0` (an integer). @@ -319,26 +319,26 @@ By default missing cells will be replaced by `null` when accessed via the option The [`default` command](/commands/docs/default.html) can be used to apply a default value to missing or null column result. ```nu -> let missing_value = [{a:1 b:2} {b:1}] -> $missing_value -╭───┬────┬───╮ -│ # │ a │ b │ -├───┼────┼───┤ -│ 0 │ 1 │ 2 │ -│ 1 │ ❎ │ 1 │ -╰───┴────┴───╯ - -> let with_default_value = ($missing_value | default 'n/a' a) -> $with_default_value -╭───┬─────┬───╮ -│ # │ a │ b │ -├───┼─────┼───┤ -│ 0 │ 1 │ 2 │ -│ 1 │ n/a │ 1 │ -╰───┴─────┴───╯ - -> $with_default_value.1.a -n/a +let missing_value = [{a:1 b:2} {b:1}] +$missing_value +# => ╭───┬────┬───╮ +# => │ # │ a │ b │ +# => ├───┼────┼───┤ +# => │ 0 │ 1 │ 2 │ +# => │ 1 │ ❎ │ 1 │ +# => ╰───┴────┴───╯ + +let with_default_value = ($missing_value | default 'n/a' a) +$with_default_value +# => ╭───┬─────┬───╮ +# => │ # │ a │ b │ +# => ├───┼─────┼───┤ +# => │ 0 │ 1 │ 2 │ +# => │ 1 │ n/a │ 1 │ +# => ╰───┴─────┴───╯ + +$with_default_value.1.a +# => n/a ``` ## Other commands for accessing structured data diff --git a/book/nu_as_a_shell.md b/book/nu_as_a_shell.md index ebb5aea8241..7f457ac9072 100644 --- a/book/nu_as_a_shell.md +++ b/book/nu_as_a_shell.md @@ -19,10 +19,10 @@ An interesting feature of Nushell is the [Directory Stack](directory_stack.md) w Nushell also has its own line editor [Reedline](line_editor.md). With Nushell's config, it is possible to configure some of the Reedline's features, such as the prompt, keybindings, history, or menus. -It is also possible to define [custom signatures for external commands](externs.md) which lets you define [custom completions](custom_completions.md) for them (the custom completions work also for Nushell custom commands). +It is also possible to define [custom signatures for external commands](externs.md) which lets you define [custom completions](custom_completions.md) for them (the custom completions also work for Nushell custom commands). [Coloring and Theming in Nu](coloring_and_theming.md) goes into more detail about how to configure Nushell's appearance. -If you want to schedule some commands to run in the background, [Background task in Nu](background_task.md) provide a simple guideline for you to follow. +If you want to schedule some commands to run in the background, [Background task in Nu](background_task.md) provides simple guidelines for you to follow. -And finally, [hooks](hooks.md) allow you to insert fragments of Nushell code to run at certain events. +Finally, [hooks](hooks.md) allow you to insert fragments of Nushell code to run at certain events. diff --git a/book/operators.md b/book/operators.md index ab53becf2f0..14a1eb33baf 100644 --- a/book/operators.md +++ b/book/operators.md @@ -59,8 +59,8 @@ Presented in descending order of precedence, the article details the operations - Logical not (`not`) ``` -> 3 * (1 + 2) -9 +3 * (1 + 2) +# => 9 ``` ## Types @@ -68,18 +68,18 @@ Presented in descending order of precedence, the article details the operations Not all operations make sense for all data types. If you attempt to perform an operation on non-compatible data types, you will be met with an error message that should explain what went wrong: ```nu -> "spam" - 1 -Error: nu::parser::unsupported_operation (link) - - × Types mismatched for operation. - ╭─[entry #49:1:1] - 1 │ "spam" - 1 - · ───┬── ┬ ┬ - · │ │ ╰── int - · │ ╰── doesn't support these values. - · ╰── string - ╰──── - help: Change string or int to be the right types and try again. +"spam" - 1 +# => Error: nu::parser::unsupported_operation (link) +# => +# => × Types mismatched for operation. +# => ╭─[entry #49:1:1] +# => 1 │ "spam" - 1 +# => · ───┬── ┬ ┬ +# => · │ │ ╰── int +# => · │ ╰── doesn't support these values. +# => · ╰── string +# => ╰──── +# => help: Change string or int to be the right types and try again. ``` The rules might sometimes feel a bit strict, but on the other hand there should be less unexpected side effects. @@ -143,35 +143,35 @@ some individual values. This can be done with `append` and `prepend`, but the sp operator can let you do it more easily. ```nushell -> let dogs = [Spot, Teddy, Tommy] -> let cats = ["Mr. Humphrey Montgomery", Kitten] -> [ - ...$dogs - Polly - ...($cats | each { |elt| $"($elt) \(cat\)" }) - ...[Porky Bessie] - ...Nemo - ] -╭───┬───────────────────────────────╮ -│ 0 │ Spot │ -│ 1 │ Teddy │ -│ 2 │ Tommy │ -│ 3 │ Polly │ -│ 4 │ Mr. Humphrey Montgomery (cat) │ -│ 5 │ Kitten (cat) │ -│ 6 │ Porky │ -│ 7 │ Bessie │ -│ 8 │ ...Nemo │ -╰───┴───────────────────────────────╯ +let dogs = [Spot, Teddy, Tommy] +let cats = ["Mr. Humphrey Montgomery", Kitten] +[ + ...$dogs + Polly + ...($cats | each { |elt| $"($elt) \(cat\)" }) + ...[Porky Bessie] + ...Nemo +] +# => ╭───┬───────────────────────────────╮ +# => │ 0 │ Spot │ +# => │ 1 │ Teddy │ +# => │ 2 │ Tommy │ +# => │ 3 │ Polly │ +# => │ 4 │ Mr. Humphrey Montgomery (cat) │ +# => │ 5 │ Kitten (cat) │ +# => │ 6 │ Porky │ +# => │ 7 │ Bessie │ +# => │ 8 │ ...Nemo │ +# => ╰───┴───────────────────────────────╯ ``` The below code is an equivalent version using `append`: ```nushell -> $dogs | - append Polly | - append ($cats | each { |elt| $"($elt) \(cat\)" }) | - append [Porky Bessie] | - append ...Nemo +$dogs | + append Polly | + append ($cats | each { |elt| $"($elt) \(cat\)" }) | + append [Porky Bessie] | + append ...Nemo ``` Note that each call to `append` results in the creation of a new list, meaning that in this second @@ -187,11 +187,11 @@ The `...` also won't be recognized as the spread operator if there's any whitesp the next expression: ```nushell -> [ ... [] ] -╭───┬────────────────╮ -│ 0 │ ... │ -│ 1 │ [list 0 items] │ -╰───┴────────────────╯ +[ ... [] ] +# => ╭───┬────────────────╮ +# => │ 0 │ ... │ +# => │ 1 │ [list 0 items] │ +# => ╰───┴────────────────╯ ``` This is mainly so that `...` won't be confused for the spread operator in commands such as `mv ... $dir`. @@ -202,35 +202,35 @@ Let's say you have a record with some configuration information and you want to this record: ```nushell -> let config = { path: /tmp, limit: 5 } +let config = { path: /tmp, limit: 5 } ``` You can make a new record with all the fields of `$config` and some new additions using the spread operator. You can use the spread multiple records inside a single record literal. ```nushell -> { - ...$config, - users: [alice bob], - ...{ url: example.com }, - ...(sys mem) - } -╭────────────┬───────────────╮ -│ path │ /tmp │ -│ limit │ 5 │ -│ │ ╭───┬───────╮ │ -│ users │ │ 0 │ alice │ │ -│ │ │ 1 │ bob │ │ -│ │ ╰───┴───────╯ │ -│ url │ example.com │ -│ total │ 8.3 GB │ -│ free │ 2.6 GB │ -│ used │ 5.7 GB │ -│ available │ 2.6 GB │ -│ swap total │ 2.1 GB │ -│ swap free │ 18.0 MB │ -│ swap used │ 2.1 GB │ -╰────────────┴───────────────╯ +{ + ...$config, + users: [alice bob], + ...{ url: example.com }, + ...(sys mem) +} +# => ╭────────────┬───────────────╮ +# => │ path │ /tmp │ +# => │ limit │ 5 │ +# => │ │ ╭───┬───────╮ │ +# => │ users │ │ 0 │ alice │ │ +# => │ │ │ 1 │ bob │ │ +# => │ │ ╰───┴───────╯ │ +# => │ url │ example.com │ +# => │ total │ 8.3 GB │ +# => │ free │ 2.6 GB │ +# => │ used │ 5.7 GB │ +# => │ available │ 2.6 GB │ +# => │ swap total │ 2.1 GB │ +# => │ swap free │ 18.0 MB │ +# => │ swap used │ 2.1 GB │ +# => ╰────────────┴───────────────╯ ``` Similarly to lists, inside record literals, the spread operator can only be used before variables (`...$foo`), @@ -245,7 +245,7 @@ external command. Here is an example custom command that has a rest parameter: ```nushell -> def foo [ --flag req opt? ...args ] { [$flag, $req, $opt, $args] | to nuon } +def foo [ --flag req opt? ...args ] { [$flag, $req, $opt, $args] | to nuon } ``` It has one flag (`--flag`), one required positional parameter (`req`), one optional positional parameter @@ -256,39 +256,39 @@ If you have a list of arguments to pass to `args`, you can spread it the same wa recognized before variables, subexpressions, and list literals, and no whitespace is allowed in between. ```nushell -> foo "bar" "baz" ...[1 2 3] # With ..., the numbers are treated as separate arguments -[false, bar, baz, [1, 2, 3]] -> foo "bar" "baz" [1 2 3] # Without ..., [1 2 3] is treated as a single argument -[false, bar, baz, [[1, 2, 3]]] +foo "bar" "baz" ...[1 2 3] # With ..., the numbers are treated as separate arguments +# => [false, bar, baz, [1, 2, 3]] +foo "bar" "baz" [1 2 3] # Without ..., [1 2 3] is treated as a single argument +# => [false, bar, baz, [[1, 2, 3]]] ``` A more useful way to use the spread operator is if you have another command with a rest parameter and you want it to forward its arguments to `foo`: ```nushell -> def bar [ ...args ] { foo --flag "bar" "baz" ...$args } -> bar 1 2 3 -[true, bar, baz, [1, 2, 3]] +def bar [ ...args ] { foo --flag "bar" "baz" ...$args } +bar 1 2 3 +# => [true, bar, baz, [1, 2, 3]] ``` You can spread multiple lists in a single call, and also intersperse individual arguments: ```nushell -> foo "bar" "baz" 1 ...[2 3] 4 5 ...(6..9 | take 2) last -[false, bar, baz, [1, 2, 3, 4, 5, 6, 7, last]] +foo "bar" "baz" 1 ...[2 3] 4 5 ...(6..9 | take 2) last +# => [false, bar, baz, [1, 2, 3, 4, 5, 6, 7, last]] ``` Flags/named arguments can go after a spread argument, just like they can go after regular rest arguments: ```nushell -> foo "bar" "baz" 1 ...[2 3] --flag 4 -[true, bar, baz, [1, 2, 3, 4]] +foo "bar" "baz" 1 ...[2 3] --flag 4 +# => [true, bar, baz, [1, 2, 3, 4]] ``` If a spread argument comes before an optional positional parameter, that optional parameter is treated as being omitted: ```nushell -> foo "bar" ...[1 2] "not opt" # The null means no argument was given for opt -[false, bar, null, [1, 2, "not opt"]] +foo "bar" ...[1 2] "not opt" # The null means no argument was given for opt +# => [false, bar, null, [1, 2, "not opt"]] ``` diff --git a/book/overlays.md b/book/overlays.md index 71002961b4f..118fe557d0a 100644 --- a/book/overlays.md +++ b/book/overlays.md @@ -14,7 +14,7 @@ You should see the default overlay listed there. To create a new overlay, you first need a module: ```nu -> module spam { +module spam { export def foo [] { "foo" } @@ -40,22 +40,22 @@ The module can be created by any of the three methods described in [Modules](mod To create the overlay, call [`overlay use`](/commands/docs/overlay_use.md): ```nu -> overlay use spam +overlay use spam -> foo foo +# => foo -> bar bar +# => bar -> $env.BAZ -baz +$env.BAZ +# => baz -> overlay list -───┬────── - 0 │ zero - 1 │ spam -───┴────── +overlay list +# => ───┬────── +# => 0 │ zero +# => 1 │ spam +# => ───┴────── ``` It brought the module's definitions into the current scope and evaluated the [`export-env`](/commands/docs/export-env.md) block the same way as [`use`](/commands/docs/use.md) command would (see [Modules](modules.md#environment-variables) chapter). diff --git a/book/parallelism.md b/book/parallelism.md index 955f0953d6c..f84e3cd72f4 100644 --- a/book/parallelism.md +++ b/book/parallelism.md @@ -13,7 +13,7 @@ Like [`each`](/commands/docs/each.md), [`par-each`](/commands/docs/par-each.md) Let's say you wanted to count the number of files in each sub-directory of the current directory. Using [`each`](/commands/docs/each.md), you could write this as: ```nu -> ls | where type == dir | each { |row| +ls | where type == dir | each { |row| { name: $row.name, len: (ls $row.name | length) } } ``` @@ -25,7 +25,7 @@ On your machine, the times may vary. For this machine, it took 21 milliseconds f Now, since this operation can be run in parallel, let's convert the above to parallel by changing [`each`](/commands/docs/each.md) to [`par-each`](/commands/docs/par-each.md): ```nu -> ls | where type == dir | par-each { |row| +ls | where type == dir | par-each { |row| { name: $row.name, len: (ls $row.name | length) } } ``` @@ -35,7 +35,7 @@ On this machine, it now runs in 6ms. That's quite a difference! As a side note: Because [environment variables are scoped](environment.md#scoping), you can use [`par-each`](/commands/docs/par-each.md) to work in multiple directories in parallel (notice the [`cd`](/commands/docs/cd.md) command): ```nu -> ls | where type == dir | par-each { |row| +ls | where type == dir | par-each { |row| { name: $row.name, len: (cd $row.name; ls | length) } } ``` diff --git a/book/pipelines.md b/book/pipelines.md index 5544b49579d..c23939e3b83 100644 --- a/book/pipelines.md +++ b/book/pipelines.md @@ -19,8 +19,8 @@ The last command, `save Cargo_new.toml`, is an output (sometimes called a "sink" The `$in` variable will collect the pipeline into a value for you, allowing you to access the whole stream as a parameter: ```nu -> [1 2 3] | $in.1 * $in.2 -6 +[1 2 3] | $in.1 * $in.2 +# => 6 ``` ## Multi-line pipelines @@ -40,7 +40,7 @@ let year = ( Take this example: ```nu -> line1; line2 | line3 +line1; line2 | line3 ``` Here, semicolons are used in conjunction with pipelines. When a semicolon is used, no output data is produced to be piped. As such, the `$in` variable will not work when used immediately after the semicolon. @@ -130,111 +130,109 @@ See: [Custom Commands -> Pipeline Input](custom_commands.html#pipeline-input) def echo_me [] { print $in } - - > true | echo_me - true + true | echo_me + # => true ``` - - **_Rule 1.5:_** This is true throughout the current scope. Even on subsequent lines in a closure or block, `$in` is the same value when used in the first position of _any pipeline_ inside that scope. - - Example: +- **_Rule 1.5:_** This is true throughout the current scope. Even on subsequent lines in a closure or block, `$in` is the same value when used in the first position of _any pipeline_ inside that scope. - ```nu - [ a b c ] | each { - print $in - print $in - $in - } - ``` + Example: - All three of the `$in` values are the same on each iteration, so this outputs: + ```nu + [ a b c ] | each { + print $in + print $in + $in + } + ``` - ```nu - a - a - b - b - c - c - ╭───┬───╮ - │ 0 │ a │ - │ 1 │ b │ - │ 2 │ c │ - ╰───┴───╯ - ``` + All three of the `$in` values are the same on each iteration, so this outputs: + + ```nu + a + a + b + b + c + c + ╭───┬───╮ + │ 0 │ a │ + │ 1 │ b │ + │ 2 │ c │ + ╰───┴───╯ + ``` -* **_Rule 2:_** When used anywhere else in a pipeline (other than the first position), `$in` refers to the previous expression's result: +- **_Rule 2:_** When used anywhere else in a pipeline (other than the first position), `$in` refers to the previous expression's result: Example: ```nushell - > 4 # Pipeline input - | $in * $in # $in is 4 in this expression - | $in / 2 # $in is now 16 in this expression - | $in # $in is now 8 - - 8 + 4 # Pipeline input + | $in * $in # $in is 4 in this expression + | $in / 2 # $in is now 16 in this expression + | $in # $in is now 8 + # => 8 ``` - - **_Rule 2.5:_** Inside a closure or block, Rule 2 usage occurs inside a new scope (a sub-expression) where that "new" `$in` value is valid. This means that Rule 1 and Rule 2 usage can coexist in the same closure or block. +- **_Rule 2.5:_** Inside a closure or block, Rule 2 usage occurs inside a new scope (a sub-expression) where that "new" `$in` value is valid. This means that Rule 1 and Rule 2 usage can coexist in the same closure or block. - Example: + Example: - ```nushell - 4 | do { - print $in # closure-scope $in is 4 + ```nushell + 4 | do { + print $in # closure-scope $in is 4 - let p = ( # explicit sub-expression, but one will be created regardless - $in * $in # initial-pipeline position $in is still 4 here - | $in / 2 # $in is now 16 - ) # $p is the result, 8 - Sub-expression scope ends + let p = ( # explicit sub-expression, but one will be created regardless + $in * $in # initial-pipeline position $in is still 4 here + | $in / 2 # $in is now 16 + ) # $p is the result, 8 - Sub-expression scope ends - print $in # At the closure-scope, the "original" $in is still 4 - print $p - } - ``` + print $in # At the closure-scope, the "original" $in is still 4 + print $p + } + ``` - So the output from the 3 `print` statements is: + So the output from the 3 `print` statements is: - ```nu - 4 - 4 - 8 - ``` + ```nu + 4 + 4 + 8 + ``` - Again, this would hold true even if the command above used the more compact, implicit sub-expression form: + Again, this would hold true even if the command above used the more compact, implicit sub-expression form: - Example: + Example: - ```nushell - 4 | do { - print $in # closure-scope $in is 4 - let p = $in * $in | $in / 2 # Implicit let sub-expression - print $in # At the closure-scope, $in is still 4 - print $p - } + ```nushell + 4 | do { + print $in # closure-scope $in is 4 + let p = $in * $in | $in / 2 # Implicit let sub-expression + print $in # At the closure-scope, $in is still 4 + print $p + } - 4 - 4 - 8 - ``` + 4 + 4 + 8 + ``` -* **_Rule 3:_** When used with no input, `$in` is null. +- **_Rule 3:_** When used with no input, `$in` is null. Example: ```nushell - > # Input - > 1 | do { $in | describe } - int - > "Hello, Nushell" | do { $in | describe } - string - > {||} | do { $in | describe } - closure - - > # No input - > do { $in | describe } - nothing + # Input + 1 | do { $in | describe } + # => int + "Hello, Nushell" | do { $in | describe } + # => string + {||} | do { $in | describe } + # => closure + + # No input + do { $in | describe } + # => nothing ``` * **_Rule 4:_** In a multi-statement line separated by semicolons, `$in` cannot be used to capture the results of the previous _statement_. @@ -242,15 +240,15 @@ See: [Custom Commands -> Pipeline Input](custom_commands.html#pipeline-input) This is the same as having no-input: ```nushell - > ls / | get name; $in | describe - nothing + ls / | get name; $in | describe + # => nothing ``` Instead, simply continue the pipeline: ```nushell - > ls / | get name | $in | describe - list + ls / | get name | $in | describe + # => list ``` ### Best practice for `$in` in Multiline Code @@ -267,10 +265,10 @@ def "date info" [] { print $'... was day ($day | format date '%j') of the year' } -> '2000-01-01' | date info - 1-Jan-2000 -... was a Saturday -... was day 001 of the year +'2000-01-01' | date info +# => 1-Jan-2000 +# => ... was a Saturday +# => ... was day 001 of the year ``` ### Collectability of `$in` @@ -305,35 +303,35 @@ You can check what a command supports with [`help `](/commands/doc For example, through `help first` we can see that the [`first` command](/commands/docs/first.md) supports multiple input and output types: ```nu -> help first -[…] -Input/output types: - ╭───┬───────────┬────────╮ - │ # │ input │ output │ - ├───┼───────────┼────────┤ - │ 0 │ list │ any │ - │ 1 │ binary │ binary │ - │ 2 │ range │ any │ - ╰───┴───────────┴────────╯ - -> [a b c] | first took 1ms -a - -> 1..4 | first took 21ms -1 +help first +# => […] +# => Input/output types: +# => ╭───┬───────────┬────────╮ +# => │ # │ input │ output │ +# => ├───┼───────────┼────────┤ +# => │ 0 │ list │ any │ +# => │ 1 │ binary │ binary │ +# => │ 2 │ range │ any │ +# => ╰───┴───────────┴────────╯ + +[a b c] | first took 1ms +# => a + +1..4 | first took 21ms +# => 1 ``` As another example, the [`ls` command](/commands/docs/ls.md) supports output but not input: ```nu -> help ls -[…] -Input/output types: - ╭───┬─────────┬────────╮ - │ # │ input │ output │ - ├───┼─────────┼────────┤ - │ 0 │ nothing │ table │ - ╰───┴─────────┴────────╯ +help ls +# => […] +# => Input/output types: +# => ╭───┬─────────┬────────╮ +# => │ # │ input │ output │ +# => ├───┼─────────┼────────┤ +# => │ 0 │ nothing │ table │ +# => ╰───┴─────────┴────────╯ ``` This means, for example, that attempting to pipe into `ls` (`echo .. | ls`) leads to unintended results. @@ -342,7 +340,7 @@ The input stream is ignored, and `ls` defaults to listing the current directory. To integrate a command like `ls` into a pipeline, you have to explicitly reference the input and pass it as a parameter: ```nu -> echo .. | ls $in +echo .. | ls $in ``` Note that this only works if `$in` matches the argument type. For example, `[dir1 dir2] | ls $in` will fail with the error `can't convert list to string`. @@ -352,27 +350,27 @@ Other commands without default behavior may fail in different ways, and with exp For example, `help sleep` tells us that [`sleep`](/commands/docs/sleep.md) supports no input and no output types: ```nu -> help sleep -[…] -Input/output types: - ╭───┬─────────┬─────────╮ - │ # │ input │ output │ - ├───┼─────────┼─────────┤ - │ 0 │ nothing │ nothing │ - ╰───┴─────────┴─────────╯ +help sleep +# => […] +# => Input/output types: +# => ╭───┬─────────┬─────────╮ +# => │ # │ input │ output │ +# => ├───┼─────────┼─────────┤ +# => │ 0 │ nothing │ nothing │ +# => ╰───┴─────────┴─────────╯ ``` When we erroneously pipe into it, instead of unintended behavior like in the `ls` example above, we receive an error: ```nu -> echo 1sec | sleep -Error: nu::parser::missing_positional - - × Missing required positional argument. - ╭─[entry #53:1:18] - 1 │ echo 1sec | sleep - ╰──── - help: Usage: sleep ...(rest) . Use `--help` for more information. +echo 1sec | sleep +# => Error: nu::parser::missing_positional +# => +# => × Missing required positional argument. +# => ╭─[entry #53:1:18] +# => 1 │ echo 1sec | sleep +# => ╰──── +# => help: Usage: sleep ...(rest) . Use `--help` for more information. ``` While there is no steadfast rule, Nu generally tries to copy established conventions in command behavior, @@ -388,13 +386,13 @@ You may have wondered how we see a table if [`ls`](/commands/docs/ls.md) is an i In effect, the command: ```nu -> ls +ls ``` And the pipeline: ```nu -> ls | table +ls | table ``` Are one and the same. @@ -416,44 +414,44 @@ Sometimes you want to output Nushell structured data to an external command for For example, you want to find a file named "tutor" under "/usr/share/vim/runtime" and check its ownership ```nu -> ls /usr/share/nvim/runtime/ -╭────┬───────────────────────────────────────┬──────┬─────────┬───────────────╮ -│ # │ name │ type │ size │ modified │ -├────┼───────────────────────────────────────┼──────┼─────────┼───────────────┤ -│ 0 │ /usr/share/nvim/runtime/autoload │ dir │ 4.1 KB │ 2 days ago │ -.......... -.......... -.......... - -│ 31 │ /usr/share/nvim/runtime/tools │ dir │ 4.1 KB │ 2 days ago │ -│ 32 │ /usr/share/nvim/runtime/tutor │ dir │ 4.1 KB │ 2 days ago │ -├────┼───────────────────────────────────────┼──────┼─────────┼───────────────┤ -│ # │ name │ type │ size │ modified │ -╰────┴───────────────────────────────────────┴──────┴─────────┴───────────────╯ +ls /usr/share/nvim/runtime/ +# => ╭────┬───────────────────────────────────────┬──────┬─────────┬───────────────╮ +# => │ # │ name │ type │ size │ modified │ +# => ├────┼───────────────────────────────────────┼──────┼─────────┼───────────────┤ +# => │ 0 │ /usr/share/nvim/runtime/autoload │ dir │ 4.1 KB │ 2 days ago │ +# => .......... +# => .......... +# => .......... +# => +# => │ 31 │ /usr/share/nvim/runtime/tools │ dir │ 4.1 KB │ 2 days ago │ +# => │ 32 │ /usr/share/nvim/runtime/tutor │ dir │ 4.1 KB │ 2 days ago │ +# => ├────┼───────────────────────────────────────┼──────┼─────────┼───────────────┤ +# => │ # │ name │ type │ size │ modified │ +# => ╰────┴───────────────────────────────────────┴──────┴─────────┴───────────────╯ ``` You decided to use `grep` and [pipe](https://www.nushell.sh/book/pipelines.html) the result to external `^ls` ```nu -> ls /usr/share/nvim/runtime/ | get name | ^grep tutor | ^ls -la $in -ls: cannot access ''$'\342\224\202'' 32 '$'\342\224\202'' /usr/share/nvim/runtime/tutor '$'\342\224\202\n': No such file or directory +ls /usr/share/nvim/runtime/ | get name | ^grep tutor | ^ls -la $in +# => ls: cannot access ''$'\342\224\202'' 32 '$'\342\224\202'' /usr/share/nvim/runtime/tutor '$'\342\224\202\n': No such file or directory ``` What's wrong? Nushell renders lists and tables (by adding a border with characters like `╭`,`─`,`┬`,`╮`) before piping them as text to external commands. If that's not the behavior you want, you must explicitly convert the data to a string before piping it to an external. For example, you can do so with [`to text`](/commands/docs/to_text.md): ```nu -> ls /usr/share/nvim/runtime/ | get name | to text | ^grep tutor | tr -d '\n' | ^ls -la $in -total 24 -drwxr-xr-x@ 5 pengs admin 160 14 Nov 13:12 . -drwxr-xr-x@ 4 pengs admin 128 14 Nov 13:42 en --rw-r--r--@ 1 pengs admin 5514 14 Nov 13:42 tutor.tutor --rw-r--r--@ 1 pengs admin 1191 14 Nov 13:42 tutor.tutor.json +ls /usr/share/nvim/runtime/ | get name | to text | ^grep tutor | tr -d '\n' | ^ls -la $in +# => total 24 +# => drwxr-xr-x@ 5 pengs admin 160 14 Nov 13:12 . +# => drwxr-xr-x@ 4 pengs admin 128 14 Nov 13:42 en +# => -rw-r--r--@ 1 pengs admin 5514 14 Nov 13:42 tutor.tutor +# => -rw-r--r--@ 1 pengs admin 1191 14 Nov 13:42 tutor.tutor.json ``` (Actually, for this simple usage you can just use [`find`](/commands/docs/find.md)) ```nu -> ls /usr/share/nvim/runtime/ | get name | find tutor | ^ls -al $in +ls /usr/share/nvim/runtime/ | get name | find tutor | ansi strip | ^ls -al ...$in ``` ## Command Output in Nushell @@ -461,7 +459,7 @@ drwxr-xr-x@ 4 pengs admin 128 14 Nov 13:42 en Unlike external commands, Nushell commands are akin to functions. Most Nushell commands do not print anything to `stdout` and instead just return data. ```nu -> do { ls; ls; ls; "What?!" } +do { ls; ls; ls; "What?!" } ``` This means that the above code will not display the files under the current directory three times. @@ -470,13 +468,13 @@ In fact, running this in the shell will only display `"What?!"` because that is Knowing when data is displayed is important when using configuration variables that affect the display output of commands such as `table`. ```nu -> do { $env.config.table.mode = "none"; ls } +do { $env.config.table.mode = "none"; ls } ``` For instance, the above example sets the `$env.config.table.mode` configuration variable to `none`, which causes the `table` command to render data without additional borders. However, as it was shown earlier, the command is effectively equivalent to ```nu -> do { $env.config.table.mode = "none"; ls } | table +do { $env.config.table.mode = "none"; ls } | table ``` Because Nushell `$env` variables are [scoped](https://www.nushell.sh/book/environment.html#scoping), this means that the `table` command in the example is not affected by the @@ -485,6 +483,6 @@ environment modification inside the `do` block and the data will not be shown wi When displaying data early is desired, it is possible to explicitly apply `| table` inside the scope, or use the `print` command. ```nu -> do { $env.config.table.mode = "none"; ls | table } -> do { $env.config.table.mode = "none"; print (ls) } +do { $env.config.table.mode = "none"; ls | table } +do { $env.config.table.mode = "none"; print (ls) } ``` diff --git a/book/quick_tour.md b/book/quick_tour.md index e0b3267d385..7d68e530187 100644 --- a/book/quick_tour.md +++ b/book/quick_tour.md @@ -155,6 +155,7 @@ Nushell commands can extend across multiple lines for readability. The above is ls | sort-by size | reverse | first | get name | cp $in ~ ``` +See Also: [Multi-line Editing](./line_editor.md#multi-line-editing) ::: The first three lines are the same commands we used in the second example above, so let's examine the last three: diff --git a/book/scripts.md b/book/scripts.md index a521ffba6d5..28aed8626ef 100644 --- a/book/scripts.md +++ b/book/scripts.md @@ -3,13 +3,13 @@ In Nushell, you can write and run scripts in the Nushell language. To run a script, you can pass it as an argument to the `nu` commandline application: ```nu -> nu myscript.nu +nu myscript.nu ``` This will run the script to completion in a new instance of Nu. You can also run scripts inside the _current_ instance of Nu using [`source`](/commands/docs/source.md): ```nu -> source myscript.nu +source myscript.nu ``` Let's look at an example script file: @@ -69,8 +69,8 @@ def main [x: int] { ``` ```nu -> nu myscript.nu 100 -110 +nu myscript.nu 100 +# => 110 ``` ## Argument Type Interpretation @@ -94,11 +94,11 @@ def main [x: string] { ``` ```nu -> nu implicit_type.nu +1 -Hello int 1 +nu implicit_type.nu +1 +# => Hello int 1 -> nu explicit_type.nu +1 -Hello string +1 +nu explicit_type.nu +1 +# => Hello string +1 ``` ## Subcommands @@ -123,12 +123,12 @@ def main [] { You can then execute the script's subcommands when calling it: ```nu -> nu myscript.nu -hello from myscript! -> nu myscript.nu build -building -> nu myscript.nu run -running +nu myscript.nu +# => hello from myscript! +nu myscript.nu build +# => building +nu myscript.nu run +# => running ``` [Unlike modules](modules.html#main), `main` does _not_ need to exported in order to be visible. In the above example, our `main` command is not `export def`, however it was still executed when running `nu myscript.nu`. If we had used myscript as a module by running `use myscript.nu`, rather than running `myscript.nu` as a script, trying to execute the `myscript` command would not work since `myscript` is not exported. @@ -147,8 +147,8 @@ def "main build" [] { ``` ```nu -> nu myscript.nu build -> nu myscript.nu run +nu myscript.nu build +nu myscript.nu run ``` This is a limitation of the way scripts are currently processed. If your script only has subcommands, you can add an empty `main` to expose the subcommands, like so: @@ -167,8 +167,8 @@ On Linux and macOS you can optionally use a [shebang]( ./myscript -Hello World! +./myscript +# => Hello World! ``` For script to have access to standard input, `nu` should be invoked with `--stdin` flag: @@ -181,6 +181,6 @@ def main [] { ``` ```nu -> echo "Hello World!" | ./myscript -stdin: Hello World! +echo "Hello World!" | ./myscript +# => stdin: Hello World! ``` diff --git a/book/sorting.md b/book/sorting.md index f07d9ddf4ee..c605c517694 100644 --- a/book/sorting.md +++ b/book/sorting.md @@ -9,31 +9,31 @@ Nushell offers many ways of sorting data, and which method you reach for will de Sorting a basic list works exactly how you might expect: ```nu -> [9 3 8 1 4 6] | sort -╭───┬───╮ -│ 0 │ 1 │ -│ 1 │ 3 │ -│ 2 │ 4 │ -│ 3 │ 6 │ -│ 4 │ 8 │ -│ 5 │ 9 │ -╰───┴───╯ +[9 3 8 1 4 6] | sort +# => ╭───┬───╮ +# => │ 0 │ 1 │ +# => │ 1 │ 3 │ +# => │ 2 │ 4 │ +# => │ 3 │ 6 │ +# => │ 4 │ 8 │ +# => │ 5 │ 9 │ +# => ╰───┴───╯ ``` However, things get a bit more complex when you start combining types. For example, let's see what happens when we have a list with numbers _and_ strings: ```nu -> ["hello" 4 9 2 1 "foobar" 8 6] | sort -╭───┬────────╮ -│ 0 │ 1 │ -│ 1 │ 2 │ -│ 2 │ 4 │ -│ 3 │ 6 │ -│ 4 │ 8 │ -│ 5 │ 9 │ -│ 6 │ foobar │ -│ 7 │ hello │ -╰───┴────────╯ +["hello" 4 9 2 1 "foobar" 8 6] | sort +# => ╭───┬────────╮ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => │ 2 │ 4 │ +# => │ 3 │ 6 │ +# => │ 4 │ 8 │ +# => │ 5 │ 9 │ +# => │ 6 │ foobar │ +# => │ 7 │ hello │ +# => ╰───┴────────╯ ``` We can see that the numbers are sorted in order, and the strings are sorted to the end of the list, also in order. If you are coming from other programming languages, this may not be quite what you expect. In Nushell, as a general rule, **data can always be sorted without erroring**. @@ -45,13 +45,13 @@ If you _do_ want a sort containing differing types to error, see [strict sort](# Nushell's sort is also **stable**, meaning equal values will retain their original ordering relative to each other. This is illustrated here using the [case insensitive](#case-insensitive-sort) sort option: ```nu -> ["foo" "FOO" "BAR" "bar"] | sort -i -╭───┬─────╮ -│ 0 │ BAR │ -│ 1 │ bar │ -│ 2 │ foo │ -│ 3 │ FOO │ -╰───┴─────╯ +["foo" "FOO" "BAR" "bar"] | sort -i +# => ╭───┬─────╮ +# => │ 0 │ BAR │ +# => │ 1 │ bar │ +# => │ 2 │ foo │ +# => │ 3 │ FOO │ +# => ╰───┴─────╯ ``` Since this sort is case insensitive, `foo` and `FOO` are considered equal to each other, and the same is true for `bar` and `BAR`. In the result, the uppercase `BAR` precedes the lowercase `bar`, since the uppercase `BAR` also precedes the lowercase `bar` in the input. Similarly, the lowercase `foo` precedes the uppercase `FOO` in both the input and the result. @@ -62,22 +62,22 @@ Records can be sorted two ways: by key, and by value. By default, passing a reco ```nu {x: 123, a: hello!, foo: bar} | sort -╭─────┬────────╮ -│ a │ hello! │ -│ foo │ bar │ -│ x │ 123 │ -╰─────┴────────╯ +# => ╭─────┬────────╮ +# => │ a │ hello! │ +# => │ foo │ bar │ +# => │ x │ 123 │ +# => ╰─────┴────────╯ ``` To instead sort in order of values, use the `-v` flag: ```nu {x: 123, a: hello! foo: bar} | sort -v -╭─────┬────────╮ -│ x │ 123 │ -│ foo │ bar │ -│ a │ hello! │ -╰─────┴────────╯ +# => ╭─────┬────────╮ +# => │ x │ 123 │ +# => │ foo │ bar │ +# => │ a │ hello! │ +# => ╰─────┴────────╯ ``` ### Tables @@ -85,19 +85,19 @@ To instead sort in order of values, use the `-v` flag: Table rows are sorted by comparing rows by the columns in order. If two rows have equal values in their first column, they are sorted by their second column. This repeats until the rows are sorted different or all columns are equal. ```nu -> let items = [ +let items = [ {id: 100, quantity: 10, price: 5 } {id: 100, quantity: 5, price: 8 } {id: 100, quantity: 5, price: 1 } ] -> $items | sort -╭───┬─────┬──────────┬───────╮ -│ # │ id │ quantity │ price │ -├───┼─────┼──────────┼───────┤ -│ 0 │ 100 │ 5 │ 1 │ -│ 1 │ 100 │ 5 │ 8 │ -│ 2 │ 100 │ 10 │ 5 │ -╰───┴─────┴──────────┴───────╯ +$items | sort +# => ╭───┬─────┬──────────┬───────╮ +# => │ # │ id │ quantity │ price │ +# => ├───┼─────┼──────────┼───────┤ +# => │ 0 │ 100 │ 5 │ 1 │ +# => │ 1 │ 100 │ 5 │ 8 │ +# => │ 2 │ 100 │ 10 │ 5 │ +# => ╰───┴─────┴──────────┴───────╯ ``` In this example, the `id` column for all items is equal. Then, the two items with price `5` are sorted before the item with price `10`. Finally, the `item` with quantity `1` is sorted before the item with quantity `8`. @@ -111,29 +111,29 @@ In order to sort more complex types, such as tables, you can use the `sort-by` c Here's an example directory, sorted by filesize: ```nu -> ls | sort-by size -╭───┬─────────────────────┬──────┬──────────┬────────────────╮ -│ # │ name │ type │ size │ modified │ -├───┼─────────────────────┼──────┼──────────┼────────────────┤ -│ 0 │ my-secret-plans.txt │ file │ 100 B │ 10 minutes ago │ -│ 1 │ shopping_list.txt │ file │ 100 B │ 2 months ago │ -│ 2 │ myscript.nu │ file │ 1.1 KiB │ 2 weeks ago │ -│ 3 │ bigfile.img │ file │ 10.0 MiB │ 3 weeks ago │ -╰───┴─────────────────────┴──────┴──────────┴────────────────╯ +ls | sort-by size +# => ╭───┬─────────────────────┬──────┬──────────┬────────────────╮ +# => │ # │ name │ type │ size │ modified │ +# => ├───┼─────────────────────┼──────┼──────────┼────────────────┤ +# => │ 0 │ my-secret-plans.txt │ file │ 100 B │ 10 minutes ago │ +# => │ 1 │ shopping_list.txt │ file │ 100 B │ 2 months ago │ +# => │ 2 │ myscript.nu │ file │ 1.1 KiB │ 2 weeks ago │ +# => │ 3 │ bigfile.img │ file │ 10.0 MiB │ 3 weeks ago │ +# => ╰───┴─────────────────────┴──────┴──────────┴────────────────╯ ``` We can also provide multiple cell paths to `sort-by`, which will sort by each cell path in order of priority. You can think of providing multiple cell paths as a "tiebreaker" for elements which have equal values. Let's sort first by size, then by modification time: ```nu -> ls | sort-by size modified -╭───┬─────────────────────┬──────┬──────────┬────────────────╮ -│ # │ name │ type │ size │ modified │ -├───┼─────────────────────┼──────┼──────────┼────────────────┤ -│ 0 │ shopping_list.txt │ file │ 100 B │ 2 months ago │ -│ 1 │ my-secret-plans.txt │ file │ 100 B │ 10 minutes ago │ -│ 2 │ myscript.nu │ file │ 1.1 KiB │ 2 weeks ago │ -│ 3 │ bigfile.img │ file │ 10.0 MiB │ 3 weeks ago │ -╰───┴─────────────────────┴──────┴──────────┴────────────────╯ +ls | sort-by size modified +# => ╭───┬─────────────────────┬──────┬──────────┬────────────────╮ +# => │ # │ name │ type │ size │ modified │ +# => ├───┼─────────────────────┼──────┼──────────┼────────────────┤ +# => │ 0 │ shopping_list.txt │ file │ 100 B │ 2 months ago │ +# => │ 1 │ my-secret-plans.txt │ file │ 100 B │ 10 minutes ago │ +# => │ 2 │ myscript.nu │ file │ 1.1 KiB │ 2 weeks ago │ +# => │ 3 │ bigfile.img │ file │ 10.0 MiB │ 3 weeks ago │ +# => ╰───┴─────────────────────┴──────┴──────────┴────────────────╯ ``` This time, `shopping_list.txt` comes before `my-secret-plans.txt`, since it has an earlier modification time, but two larger files remain sorted after the `.txt` files. @@ -141,28 +141,28 @@ This time, `shopping_list.txt` comes before `my-secret-plans.txt`, since it has Furthermore, we can use more complex cell paths to sort nested data: ```nu -> let cities = [ +let cities = [ {name: 'New York', info: { established: 1624, population: 18_819_000 } } {name: 'Kyoto', info: { established: 794, population: 37_468_000 } } {name: 'São Paulo', info: { established: 1554, population: 21_650_000 } } ] -> $cities | sort-by info.established -╭───┬───────────┬────────────────────────────╮ -│ # │ name │ info │ -├───┼───────────┼────────────────────────────┤ -│ 0 │ Kyoto │ ╭─────────────┬──────────╮ │ -│ │ │ │ established │ 794 │ │ -│ │ │ │ population │ 37468000 │ │ -│ │ │ ╰─────────────┴──────────╯ │ -│ 1 │ São Paulo │ ╭─────────────┬──────────╮ │ -│ │ │ │ established │ 1554 │ │ -│ │ │ │ population │ 21650000 │ │ -│ │ │ ╰─────────────┴──────────╯ │ -│ 2 │ New York │ ╭─────────────┬──────────╮ │ -│ │ │ │ established │ 1624 │ │ -│ │ │ │ population │ 18819000 │ │ -│ │ │ ╰─────────────┴──────────╯ │ -╰───┴───────────┴────────────────────────────╯ +$cities | sort-by info.established +# => ╭───┬───────────┬────────────────────────────╮ +# => │ # │ name │ info │ +# => ├───┼───────────┼────────────────────────────┤ +# => │ 0 │ Kyoto │ ╭─────────────┬──────────╮ │ +# => │ │ │ │ established │ 794 │ │ +# => │ │ │ │ population │ 37468000 │ │ +# => │ │ │ ╰─────────────┴──────────╯ │ +# => │ 1 │ São Paulo │ ╭─────────────┬──────────╮ │ +# => │ │ │ │ established │ 1554 │ │ +# => │ │ │ │ population │ 21650000 │ │ +# => │ │ │ ╰─────────────┴──────────╯ │ +# => │ 2 │ New York │ ╭─────────────┬──────────╮ │ +# => │ │ │ │ established │ 1624 │ │ +# => │ │ │ │ population │ 18819000 │ │ +# => │ │ │ ╰─────────────┴──────────╯ │ +# => ╰───┴───────────┴────────────────────────────╯ ``` ### Sort by key closure @@ -170,35 +170,35 @@ Furthermore, we can use more complex cell paths to sort nested data: Sometimes, it's useful to sort data in a more complicated manner than "increasing" or "decreasing". Instead of using `sort-by` with a cell path, you can supply a [closure](types_of_data.html#closures), which will transform each value into a [sorting key](https://en.wikipedia.org/wiki/Collation#Sort_keys) _without changing the underlying data_. Here's an example of a key closure, where we want to sort a list of assignments by their average grade: ```nu -> let assignments = [ +let assignments = [ {name: 'Homework 1', grades: [97 89 86 92 89] } {name: 'Homework 2', grades: [91 100 60 82 91] } {name: 'Exam 1', grades: [78 88 78 53 90] } {name: 'Project', grades: [92 81 82 84 83] } ] -> $assignments | sort-by { get grades | math avg } -╭───┬────────────┬───────────────────────╮ -│ # │ name │ grades │ -├───┼────────────┼───────────────────────┤ -│ 0 │ Exam 1 │ [78, 88, 78, 53, 90] │ -│ 1 │ Project │ [92, 81, 82, 84, 83] │ -│ 2 │ Homework 2 │ [91, 100, 60, 82, 91] │ -│ 3 │ Homework 1 │ [97, 89, 86, 92, 89] │ -╰───┴────────────┴───────────────────────╯ +$assignments | sort-by { get grades | math avg } +# => ╭───┬────────────┬───────────────────────╮ +# => │ # │ name │ grades │ +# => ├───┼────────────┼───────────────────────┤ +# => │ 0 │ Exam 1 │ [78, 88, 78, 53, 90] │ +# => │ 1 │ Project │ [92, 81, 82, 84, 83] │ +# => │ 2 │ Homework 2 │ [91, 100, 60, 82, 91] │ +# => │ 3 │ Homework 1 │ [97, 89, 86, 92, 89] │ +# => ╰───┴────────────┴───────────────────────╯ ``` The value is passed into the pipeline input of the key closure, however, you can also use it as a parameter: ```nu -> let weight = {alpha: 10, beta: 5, gamma: 3} -> [alpha gamma beta gamma alpha] | sort-by {|val| $weight | get $val } -╭───┬───────╮ -│ 0 │ gamma │ -│ 1 │ gamma │ -│ 2 │ beta │ -│ 3 │ alpha │ -│ 4 │ alpha │ -╰───┴───────╯ +let weight = {alpha: 10, beta: 5, gamma: 3} +[alpha gamma beta gamma alpha] | sort-by {|val| $weight | get $val } +# => ╭───┬───────╮ +# => │ 0 │ gamma │ +# => │ 1 │ gamma │ +# => │ 2 │ beta │ +# => │ 3 │ alpha │ +# => │ 4 │ alpha │ +# => ╰───┴───────╯ ``` ### Custom sort order @@ -208,15 +208,15 @@ In addition to [key closures](#sort-by-key-closure), `sort-by` also supports clo For a simple example, we could rewrite a cell path sort as a custom sort. This can be read as "If $a.size is less than $b.size, a should appear before b in the sort order": ```nu -> ls | sort-by -c {|a, b| $a.size < $b.size } -╭───┬─────────────────────┬──────┬──────────┬────────────────╮ -│ # │ name │ type │ size │ modified │ -├───┼─────────────────────┼──────┼──────────┼────────────────┤ -│ 0 │ my-secret-plans.txt │ file │ 100 B │ 10 minutes ago │ -│ 1 │ shopping_list.txt │ file │ 100 B │ 2 months ago │ -│ 2 │ myscript.nu │ file │ 1.1 KiB │ 2 weeks ago │ -│ 3 │ bigfile.img │ file │ 10.0 MiB │ 3 weeks ago │ -╰───┴─────────────────────┴──────┴──────────┴────────────────╯ +ls | sort-by -c {|a, b| $a.size < $b.size } +# => ╭───┬─────────────────────┬──────┬──────────┬────────────────╮ +# => │ # │ name │ type │ size │ modified │ +# => ├───┼─────────────────────┼──────┼──────────┼────────────────┤ +# => │ 0 │ my-secret-plans.txt │ file │ 100 B │ 10 minutes ago │ +# => │ 1 │ shopping_list.txt │ file │ 100 B │ 2 months ago │ +# => │ 2 │ myscript.nu │ file │ 1.1 KiB │ 2 weeks ago │ +# => │ 3 │ bigfile.img │ file │ 10.0 MiB │ 3 weeks ago │ +# => ╰───┴─────────────────────┴──────┴──────────┴────────────────╯ ``` ::: tip @@ -229,13 +229,13 @@ The parameters are also passed to the custom closure as a two element list, so t Here's an example of a custom sort which couldn't be trivially written as a key sort. In this example, we have a queue of tasks with some amount of work time and a priority. We want to sort by priority (highest first). If a task has had zero work time, we want to schedule it immediately; otherwise, we ignore the work time. ```nu -> let queue = [ +let queue = [ {task: 139, work_time: 0, priority: 1 } {task: 52, work_time: 355, priority: 8 } {task: 948, work_time: 72, priority: 2 } {task: 583, work_time: 0, priority: 5 } ] -> let my_sort = {|a, b| +let my_sort = {|a, b| match [$a.work_time, $b.work_time] { [0, 0] => ($a.priority > $b.priority) # fall back to priority if equal work time [0, _] => true, # only a has 0 work time, so a comes before b in the sort order @@ -243,15 +243,7 @@ Here's an example of a custom sort which couldn't be trivially written as a key _ => ($a.priority > $b.priority) # both have non-zero work time, sort by priority } } -> $queue | sort-by -c $my_sort -╭───┬──────┬───────────┬──────────╮ -│ # │ task │ work_time │ priority │ -├───┼──────┼───────────┼──────────┤ -│ 0 │ 583 │ 0 │ 5 │ -│ 1 │ 139 │ 0 │ 1 │ -│ 2 │ 52 │ 355 │ 8 │ -│ 3 │ 948 │ 72 │ 2 │ -╰───┴──────┴───────────┴──────────╯ +$queue | sort-by -c $my_sort ``` ## Special sorts @@ -261,7 +253,7 @@ Here's an example of a custom sort which couldn't be trivially written as a key When using case insensitive sort, strings (and globs) which are the same except for different casing will be considered equal for sorting, while other types remain unaffected: ```nu -> let data = [ +let data = [ Nushell, foobar, 10, @@ -269,15 +261,15 @@ When using case insensitive sort, strings (and globs) which are the same except FoOBaR, 9 ] -> $data | sort -i -╭───┬─────────╮ -│ 0 │ 9 │ -│ 1 │ 10 │ -│ 2 │ foobar │ -│ 3 │ FoOBaR │ -│ 4 │ Nushell │ -│ 5 │ nushell │ -╰───┴─────────╯ +$data | sort -i +# => ╭───┬─────────╮ +# => │ 0 │ 9 │ +# => │ 1 │ 10 │ +# => │ 2 │ foobar │ +# => │ 3 │ FoOBaR │ +# => │ 4 │ Nushell │ +# => │ 5 │ nushell │ +# => ╰───┴─────────╯ ``` ### Natural sort @@ -285,45 +277,45 @@ When using case insensitive sort, strings (and globs) which are the same except The [natural sort option](https://en.wikipedia.org/wiki/Natural_sort_order) allows strings which contain numbers to be sorted in the same way that numbers are normally sorted. This works both for strings which consist solely of numbers, and strings which have numbers and letters: ```nu -> let data = ["10", "9", "foo123", "foo20", "bar123", "bar20"] -> $data | sort -╭───┬────────╮ -│ 0 │ 10 │ -│ 1 │ 9 │ -│ 2 │ bar123 │ -│ 3 │ bar20 │ -│ 4 │ foo123 │ -│ 5 │ foo20 │ -╰───┴────────╯ -> # "1" is sorted before "9", so "10" is sorted before "9" -> $data | sort -n -╭───┬────────╮ -│ 0 │ 9 │ -│ 1 │ 10 │ -│ 2 │ bar20 │ -│ 3 │ bar123 │ -│ 4 │ foo20 │ -│ 5 │ foo123 │ -╰───┴────────╯ +let data = ["10", "9", "foo123", "foo20", "bar123", "bar20"] +$data | sort +# => ╭───┬────────╮ +# => │ 0 │ 10 │ +# => │ 1 │ 9 │ +# => │ 2 │ bar123 │ +# => │ 3 │ bar20 │ +# => │ 4 │ foo123 │ +# => │ 5 │ foo20 │ +# => ╰───┴────────╯ +# "1" is sorted before "9", so "10" is sorted before "9" +$data | sort -n +# => ╭───┬────────╮ +# => │ 0 │ 9 │ +# => │ 1 │ 10 │ +# => │ 2 │ bar20 │ +# => │ 3 │ bar123 │ +# => │ 4 │ foo20 │ +# => │ 5 │ foo123 │ +# => ╰───┴────────╯ ``` Furthermore, natural sort allows you to sort numbers together with numeric strings: ```nu -> let data = [4, "6.2", 1, "10", 2, 8.1, "3", 5.5, "9", 7] -> $data | sort -n -╭───┬──────╮ -│ 0 │ 1 │ -│ 1 │ 2 │ -│ 2 │ 3 │ -│ 3 │ 4 │ -│ 4 │ 5.50 │ -│ 5 │ 6.2 │ -│ 6 │ 7 │ -│ 7 │ 8.10 │ -│ 8 │ 9 │ -│ 9 │ 10 │ -╰───┴──────╯ +let data = [4, "6.2", 1, "10", 2, 8.1, "3", 5.5, "9", 7] +$data | sort -n +# => ╭───┬──────╮ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => │ 2 │ 3 │ +# => │ 3 │ 4 │ +# => │ 4 │ 5.50 │ +# => │ 5 │ 6.2 │ +# => │ 6 │ 7 │ +# => │ 7 │ 8.10 │ +# => │ 8 │ 9 │ +# => │ 9 │ 10 │ +# => ╰───┴──────╯ ``` ### Sorting with mixed types @@ -350,48 +342,47 @@ If you need to sort data which may contain mixed types, consider one of the foll Custom sort closures also provide a simple way to sort data while ensuring only types with well-defined comparisons are sorted together. This takes advantage of [operators requiring compatible data types](operators.html#types): ```nu -> let compatible = [8 3.2 null 58 2] -> let incompatible = ["hello" 4 9 2 1 "meow" 8 6] -> $compatible | sort-by -c {|a, b| $a < $b | default ($a != null) } -╭───┬──────╮ -│ 0 │ 2 │ -│ 1 │ 3.20 │ -│ 2 │ 8 │ -│ 3 │ 58 │ -│ 4 │ │ -╰───┴──────╯ -> $incompatible | sort-by -c {|a, b| $a < $b | default ($a != null) } -Error: nu::shell::type_mismatch - - × Type mismatch during operation. - ╭─[entry #26:1:36] - 1 │ $incompatible | sort-by -c {|a, b| $a < $b | default ($a != null) } - · ─┬ ┬ ─┬ - · │ │ ╰── string - · │ ╰── type mismatch for operator - · ╰── int - ╰──── - +let compatible = [8 3.2 null 58 2] +let incompatible = ["hello" 4 9 2 1 "meow" 8 6] +$compatible | sort-by -c {|a, b| $a < $b | default ($a != null) } +# => ╭───┬──────╮ +# => │ 0 │ 2 │ +# => │ 1 │ 3.20 │ +# => │ 2 │ 8 │ +# => │ 3 │ 58 │ +# => │ 4 │ │ +# => ╰───┴──────╯ +$incompatible | sort-by -c {|a, b| $a < $b | default ($a != null) } +# => Error: nu::shell::type_mismatch +# => +# => × Type mismatch during operation. +# => ╭─[entry #26:1:36] +# => 1 │ $incompatible | sort-by -c {|a, b| $a < $b | default ($a != null) } +# => · ─┬ ┬ ─┬ +# => · │ │ ╰── string +# => · │ ╰── type mismatch for operator +# => · ╰── int +# => ╰──── ``` Special handling is required for `null` values, since comparison between any value and `null` returns `null`. To instead reject `null` values, try the following: ```nu -> let baddata = [8 3.2 null 58 2] -> let strict = {|a, b| +let baddata = [8 3.2 null 58 2] +let strict = {|a, b| match [$a, $b] { [null, _] => (error make {msg: "Attempt to sort null"}), [_, null] => (error make {msg: "Attempt to sort null"}), _ => ($a < $b) } } -> $baddata | sort-by -c $strict -Error: × Attempt to sort null - ╭─[entry #3:4:21] - 3 │ match [$a, $b] { - 4 │ [null, _] => (error make {msg: "Attempt to sort null"}), - · ─────┬──── - · ╰── originates from here - 5 │ [_, null] => (error make {msg: "Attempt to sort null"}), - ╰──── +$baddata | sort-by -c $strict +# => Error: × Attempt to sort null +# => ╭─[entry #3:4:21] +# => 3 │ match [$a, $b] { +# => 4 │ [null, _] => (error make {msg: "Attempt to sort null"}), +# => · ─────┬──── +# => · ╰── originates from here +# => 5 │ [_, null] => (error make {msg: "Attempt to sort null"}), +# => ╰──── ``` diff --git a/book/stdout_stderr_exit_codes.md b/book/stdout_stderr_exit_codes.md index cccd41d2205..4e9b9352165 100644 --- a/book/stdout_stderr_exit_codes.md +++ b/book/stdout_stderr_exit_codes.md @@ -9,7 +9,7 @@ The first of these important streams is stdout. Stdout is the way that most external apps will send data into the pipeline or to the screen. Data sent by an external app to its stdout is received by Nushell by default if it's part of a pipeline: ```nu -> external | str join +external | str join ``` The above would call the external named `external` and would redirect the stdout output stream into the pipeline. With this redirection, Nushell can then pass the data to the next command in the pipeline, here [`str join`](/commands/docs/str_join.md). @@ -27,8 +27,8 @@ Finally, external commands have an "exit code". These codes help give a hint to Nushell tracks the last exit code of the recently completed external in one of two ways. The first way is with the `LAST_EXIT_CODE` environment variable. ```nu -> do { external } -> $env.LAST_EXIT_CODE +do { external } +$env.LAST_EXIT_CODE ``` The second way is to use the [`complete`](/commands/docs/complete.md) command. @@ -40,12 +40,12 @@ The [`complete`](/commands/docs/complete.md) command allows you to run an extern If we try to run the external `cat` on a file that doesn't exist, we can see what [`complete`](/commands/docs/complete.md) does with the streams, including the redirected stderr: ```nu -> cat unknown.txt | complete -╭───────────┬─────────────────────────────────────────────╮ -│ stdout │ │ -│ stderr │ cat: unknown.txt: No such file or directory │ -│ exit_code │ 1 │ -╰───────────┴─────────────────────────────────────────────╯ +cat unknown.txt | complete +# => ╭───────────┬─────────────────────────────────────────────╮ +# => │ stdout │ │ +# => │ stderr │ cat: unknown.txt: No such file or directory │ +# => │ exit_code │ 1 │ +# => ╰───────────┴─────────────────────────────────────────────╯ ``` ## `echo`, `print`, and `log` commands @@ -130,6 +130,6 @@ Nushell attempts to convert to text using UTF-8. If at any time the conversion f If you want more control over the decoding of the byte stream, you can use the [`decode`](/commands/docs/decode.md) command. The [`decode`](/commands/docs/decode.md) command can be inserted into the pipeline after the external, or other raw stream-creating command, and will handle decoding the bytes based on the argument you give decode. For example, you could decode shift-jis text this way: ```nu -> 0x[8a 4c] | decode shift-jis -貝 +0x[8a 4c] | decode shift-jis +# => 貝 ``` diff --git a/book/thinking_in_nu.md b/book/thinking_in_nu.md index 24c675f1af3..898d4054bc1 100644 --- a/book/thinking_in_nu.md +++ b/book/thinking_in_nu.md @@ -162,6 +162,7 @@ echo 50 echo 60 ``` +See Also: [Multi-line Editing](./line_editor.md#multi-line-editing) ::: In all of the above: diff --git a/book/types_of_data.md b/book/types_of_data.md index ebe14b0c5c4..489d6b1fb69 100644 --- a/book/types_of_data.md +++ b/book/types_of_data.md @@ -9,8 +9,8 @@ Like many programming languages, Nu models data using a set of simple, structure The [`describe`](/commands/docs/describe.md) command returns the type of a data value: ```nu -> 42 | describe -int +42 | describe +# => int ``` ## Types at a Glance @@ -49,10 +49,10 @@ int Simple Example: ```nu -> 10 / 2 -5 -> 5 | describe -int +10 / 2 +# => 5 +5 | describe +# => int ``` ### Floats/Decimals @@ -67,16 +67,16 @@ int Simple Example: ```nu -> 2.5 / 5.0 -0.5 +2.5 / 5.0 +# => 0.5 ``` ::: tip As in most programming languages, decimal values in Nushell are approximate. ```nu -> 10.2 * 5.1 -52.01999999999999 +10.2 * 5.1 +# => 52.01999999999999 ``` ::: @@ -96,9 +96,9 @@ As with many languages, Nushell provides multiple ways to specify String values Simple (obligatory) example: ```nu -> let audience: string = "World" -> $"Hello, ($audience)" -Hello, World +let audience: string = "World" +$"Hello, ($audience)" +# => Hello, World ``` ### Booleans @@ -113,20 +113,20 @@ Hello, World Booleans are commonly the result of a comparison. For example: ```nu -> let mybool: bool = (2 > 1) -> $mybool -true -> let mybool: bool = ($env.HOME | path exists) -> $mybool -true +let mybool: bool = (2 > 1) +$mybool +# => true +let mybool: bool = ($env.HOME | path exists) +$mybool +# => true ``` A boolean result is commonly used to control the flow of execution: ```nu -> let num = -2 -> if $num < 0 { print "It's negative" } -It's negative +let num = -2 +if $num < 0 { print "It's negative" } +# => It's negative ``` ### Dates @@ -140,11 +140,11 @@ It's negative Simple example: ```nu -> date now -Mon, 12 Aug 2024 13:59:22 -0400 (now) +date now +# => Mon, 12 Aug 2024 13:59:22 -0400 (now) # Format as Unix epoch -> date now | format date '%s' -1723485562 +date now | format date '%s' +# => 1723485562 ``` ### Durations @@ -160,10 +160,10 @@ Durations support fractional values as well as calculations. Simple example: ```nu -> 3.14day -3day 3hr 21min -> 30day / 1sec # How many seconds in 30 days? -2592000 +3.14day +# => 3day 3hr 21min +30day / 1sec # How many seconds in 30 days? +# => 2592000 ``` ### File sizes @@ -179,12 +179,12 @@ Nushell also has a special type for file sizes. As with durations, Nushell supports fractional file sizes and calculations: ```nu -> 0.5kB -500 B -> 1GiB / 1B -1073741824 -> (1GiB / 1B) == 2 ** 30 -true +0.5kB +# => 500 B +1GiB / 1B +# => 1073741824 +(1GiB / 1B) == 2 ** 30 +# => true ``` See the [Language Reference](/lang-guide/chapters/types/basic_types/filesize.html) for a complete list of units and more detail. @@ -202,14 +202,14 @@ See the [Language Reference](/lang-guide/chapters/types/basic_types/filesize.htm Simple example: ```nu -> 1..5 -╭───┬───╮ -│ 0 │ 1 │ -│ 1 │ 2 │ -│ 2 │ 3 │ -│ 3 │ 4 │ -│ 4 │ 5 │ -╰───┴───╯ +1..5 +# => ╭───┬───╮ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => │ 2 │ 3 │ +# => │ 3 │ 4 │ +# => │ 4 │ 5 │ +# => ╰───┴───╯ ``` ::: tip @@ -230,10 +230,10 @@ You can also easily create lists of characters with a form similar to ranges wit Simple example: ```nu -> let cp = $.2 +let cp = $.2 # Return list item at index 2 -> [ foo bar goo glue ] | get $cp -goo +[ foo bar goo glue ] | get $cp +# => goo ``` ### Closures @@ -250,15 +250,15 @@ Simple example: This closure returns a boolean result of the comparison and then uses it in a `filter` command to return all values greater than 5. ```nu -> let compare_closure = {|a| $a > 5 } -> let original_list = [ 40 -4 0 8 12 16 -16 ] -> $original_list | filter $compare_closure -╭───┬────╮ -│ 0 │ 40 │ -│ 1 │ 8 │ -│ 2 │ 12 │ -│ 3 │ 16 │ -╰───┴────╯ +let compare_closure = {|a| $a > 5 } +let original_list = [ 40 -4 0 8 12 16 -16 ] +$original_list | filter $compare_closure +# => ╭───┬────╮ +# => │ 0 │ 40 │ +# => │ 1 │ 8 │ +# => │ 2 │ 12 │ +# => │ 3 │ 16 │ +# => ╰───┴────╯ ``` Closures are a useful way to represent code that can be executed on each row of data via [filters](/lang-guide/chapters/filters/00_filters_overview.md) @@ -279,11 +279,11 @@ Binary data, like the data from an image file, is a group of raw bytes. Simple example - Confirm that a JPEG file starts with the proper identifier: ```nu -> open nushell_logo.jpg - | into binary - | first 2 - | $in == 0x[ff d8] -true +open nushell_logo.jpg +| into binary +| first 2 +| $in == 0x[ff d8] +# => true ``` ## Structured Data Types @@ -303,12 +303,12 @@ Nushell includes a collection of structured data types that can contain the prim Simple example: ```nu -> [Sam Fred George] -╭───┬────────╮ -│ 0 │ Sam │ -│ 1 │ Fred │ -│ 2 │ George │ -╰───┴────────╯ +[Sam Fred George] +# => ╭───┬────────╮ +# => │ 0 │ Sam │ +# => │ 1 │ Fred │ +# => │ 2 │ George │ +# => ╰───┴────────╯ ``` ### Records @@ -324,18 +324,18 @@ Simple example: Simple example: ```nu -> let my_record = { - name: "Kylian" - rank: 99 - } -> $my_record -╭───────┬────────────╮ -│ name │ Kylian │ -│ rank │ 99 │ -╰───────┴────────────╯ - - > $my_record | get name - Kylian +let my_record = { + name: "Kylian" + rank: 99 +} +$my_record +# => ╭───────┬────────────╮ +# => │ name │ Kylian │ +# => │ rank │ 99 │ +# => ╰───────┴────────────╯ + +$my_record | get name +# => Kylian ``` ### Tables @@ -354,11 +354,11 @@ The table is a core data structure in Nushell. As you run commands, you'll see t Internally, tables are simply **lists of records**. This means that any command which extracts or isolates a specific row of a table will produce a record. For example, `get 0`, when used on a list, extracts the first value. But when used on a table (a list of records), it extracts a record: ```nu -> [{x:12, y:5}, {x:3, y:6}] | get 0 -╭───┬────╮ -│ x │ 12 │ -│ y │ 5 │ -╰───┴────╯ +[{x:12, y:5}, {x:3, y:6}] | get 0 +# => ╭───┬────╮ +# => │ x │ 12 │ +# => │ y │ 5 │ +# => ╰───┴────╯ ``` ::: @@ -386,7 +386,7 @@ Internally, tables are simply **lists of records**. This means that any command Simple example: ```nu -> if true { print "It's true" } +if true { print "It's true" } ``` The `{ print "It's true" }` portion above is a block. @@ -405,13 +405,13 @@ The `{ print "It's true" }` portion above is a block. Using the optional operator `?` returns `null` if the requested cell-path doesn't exist: ```nu -> let simple_record = { a: 5, b: 10 } -> $simple_record.a? -5 -> $simple_record.c? +let simple_record = { a: 5, b: 10 } +$simple_record.a? +# => 5 +$simple_record.c? # => Nothing is output -> $simple_record.c? | describe -nothing -> $simple_record.c? == null -true +$simple_record.c? | describe +# => nothing +$simple_record.c? == null +# => true ``` diff --git a/book/variables.md b/book/variables.md index e91b6d4ba6e..bb5ef249ce0 100644 --- a/book/variables.md +++ b/book/variables.md @@ -10,31 +10,31 @@ After creating a variable, we can refer to it using `$` followed by its name. An immutable variable cannot change its value after declaration. They are declared using the `let` keyword, ```nu -> let val = 42 -> $val -42 -> $val = 100 -Error: nu::shell::assignment_requires_mutable_variable - - × Assignment to an immutable variable. - ╭─[entry #10:1:1] - 1 │ $val = 100 - · ──┬─ - · ╰── needs to be a mutable variable - ╰──── +let val = 42 +$val +# => 42 +$val = 100 +# => Error: nu::shell::assignment_requires_mutable_variable +# => +# => × Assignment to an immutable variable. +# => ╭─[entry #10:1:1] +# => 1 │ $val = 100 +# => · ──┬─ +# => · ╰── needs to be a mutable variable +# => ╰──── ``` However, immutable variables can be 'shadowed'. Shadowing means that they are redeclared and their initial value cannot be used anymore within the same scope. ```nu -> let val = 42 # declare a variable -> do { let val = 101; $val } # in an inner scope, shadow the variable -101 -> $val # in the outer scope the variable remains unchanged -42 -> let val = $val + 1 # now, in the outer scope, shadow the original variable -> $val # in the outer scope, the variable is now shadowed, and -43 # its original value is no longer available. +let val = 42 # declare a variable +do { let val = 101; $val } # in an inner scope, shadow the variable +# => 101 +$val # in the outer scope the variable remains unchanged +# => 42 +let val = $val + 1 # now, in the outer scope, shadow the original variable +$val # in the outer scope, the variable is now shadowed, and +# => 43 # its original value is no longer available. ``` ### Mutable Variables @@ -42,10 +42,10 @@ However, immutable variables can be 'shadowed'. Shadowing means that they are re A mutable variable is allowed to change its value by assignment. These are declared using the `mut` keyword. ```nu -> mut val = 42 -> $val += 27 -> $val -69 +mut val = 42 +$val += 27 +$val +# => 69 ``` There are a couple of assignment operators used with mutable variables @@ -103,28 +103,28 @@ Many, if not most, use-cases for mutable variables in Nushell have a functional For instance, loop counters are a common pattern for mutable variables and are built into most iterating commands. For example, you can get both each item and the index of each item using [`each`](/commands/docs/each.md) with [`enumerate`](/commands/docs/enumerate.md): ```nu -> ls | enumerate | each { |elt| $"Item #($elt.index) is size ($elt.item.size)" } -╭───┬───────────────────────────╮ -│ 0 │ Item #0 is size 812 B │ -│ 1 │ Item #1 is size 3.4 KiB │ -│ 2 │ Item #2 is size 11.0 KiB │ -│ 3 │ ... │ -│ 4 │ Item #18 is size 17.8 KiB │ -│ 5 │ Item #19 is size 482 B │ -│ 6 │ Item #20 is size 4.0 KiB │ -╰───┴───────────────────────────╯ +ls | enumerate | each { |elt| $"Item #($elt.index) is size ($elt.item.size)" } +# => ╭───┬───────────────────────────╮ +# => │ 0 │ Item #0 is size 812 B │ +# => │ 1 │ Item #1 is size 3.4 KiB │ +# => │ 2 │ Item #2 is size 11.0 KiB │ +# => │ 3 │ ... │ +# => │ 4 │ Item #18 is size 17.8 KiB │ +# => │ 5 │ Item #19 is size 482 B │ +# => │ 6 │ Item #20 is size 4.0 KiB │ +# => ╰───┴───────────────────────────╯ ``` You can also use the [`reduce`](/commands/docs/reduce.md) command to work in the same way you might mutate a variable in a loop. For example, if you wanted to find the largest string in a list of strings, you might do: ```nu -> [one, two, three, four, five, six] | reduce {|current_item, max| - if ($current_item | str length) > ($max | str length) { - $current_item - } else { - $max - } +[one, two, three, four, five, six] | reduce {|current_item, max| + if ($current_item | str length) > ($max | str length) { + $current_item + } else { + $max } +} three ``` @@ -209,6 +209,6 @@ Variable names in Nushell come with a few restrictions as to what characters the It is common for some scripts to declare variables that start with `$`. This is allowed, and it is equivalent to the `$` not being there at all. ```nu -> let $var = 42 +let $var = 42 # identical to `let var = 42` ``` diff --git a/book/working_with_lists.md b/book/working_with_lists.md index 71b91f92249..acb4ca56680 100644 --- a/book/working_with_lists.md +++ b/book/working_with_lists.md @@ -4,11 +4,11 @@ Lists are equivalent to the individual columns of tables. You can think of a list as essentially being a "one-column table" (with no column name). Thus, any command which operates on a column _also_ operates on a list. For instance, [`where`](/commands/docs/where.md) can be used with lists: ```nu -> [bell book candle] | where ($it =~ 'b') -╭───┬──────╮ -│ 0 │ bell │ -│ 1 │ book │ -╰───┴──────╯ +[bell book candle] | where ($it =~ 'b') +# => ╭───┬──────╮ +# => │ 0 │ bell │ +# => │ 1 │ book │ +# => ╰───┴──────╯ ``` ::: @@ -28,15 +28,15 @@ Nushell lists are similar to JSON arrays. The same `[ "Item1", "Item2", "Item3" We can [`insert`](/commands/docs/insert.md) values into lists as they flow through the pipeline, for example let's insert the value `10` into the middle of a list: ```nu -> [1, 2, 3, 4] | insert 2 10 -# [1, 2, 10, 3, 4] +[1, 2, 3, 4] | insert 2 10 +# => [1, 2, 10, 3, 4] ``` We can also use [`update`](/commands/docs/update.md) to replace the 2nd element with the value `10`. ```nu -> [1, 2, 3, 4] | update 1 10 -# [1, 10, 3, 4] +[1, 2, 3, 4] | update 1 10 +# => [1, 10, 3, 4] ``` ## Removing or Adding Items from List @@ -51,7 +51,8 @@ let colors = ($colors | prepend red) let colors = ($colors | append purple) let colors = ($colors ++ "blue") let colors = ("black" ++ $colors) -$colors # [black red yellow green purple blue] +$colors +# => [black red yellow green purple blue] ``` In case you want to remove items from list, there are many ways. [`skip`](/commands/docs/skip.md) allows you skip first rows from input, while [`drop`](/commands/docs/drop.md) allows you to skip specific numbered rows from end of list. @@ -60,7 +61,8 @@ In case you want to remove items from list, there are many ways. [`skip`](/comma let colors = [red yellow green purple] let colors = ($colors | skip 1) let colors = ($colors | drop 2) -$colors # [yellow] +$colors +# => [yellow] ``` We also have [`last`](/commands/docs/last.md) and [`first`](/commands/docs/first.md) which allow you to [`take`](/commands/docs/take.md) from the end or beginning of the list, respectively. @@ -68,7 +70,8 @@ We also have [`last`](/commands/docs/last.md) and [`first`](/commands/docs/first ```nu let colors = [red yellow green purple black magenta] let colors = ($colors | last 3) -$colors # [purple black magenta] +$colors +# => [purple black magenta] ``` And from the beginning of a list, @@ -76,7 +79,8 @@ And from the beginning of a list, ```nu let colors = [yellow green purple] let colors = ($colors | first 2) -$colors # [yellow green] +$colors +# => [yellow green] ``` ### Using the Spread Operator @@ -85,19 +89,19 @@ To append one or more lists together, optionally with values interspersed in bet [spread operator](/book/operators#spread-operator) (`...`): ```nu -> let x = [1 2] -> [ - ...$x - 3 - ...(4..7 | take 2) - ] -╭───┬───╮ -│ 0 │ 1 │ -│ 1 │ 2 │ -│ 2 │ 3 │ -│ 3 │ 4 │ -│ 4 │ 5 │ -╰───┴───╯ +let x = [1 2] +[ + ...$x + 3 + ...(4..7 | take 2) +] +# => ╭───┬───╮ +# => │ 0 │ 1 │ +# => │ 1 │ 2 │ +# => │ 2 │ 3 │ +# => │ 3 │ 4 │ +# => │ 4 │ 5 │ +# => ╰───┴───╯ ``` ## Iterating over Lists diff --git a/book/working_with_records.md b/book/working_with_records.md index b0325577739..6d53f07c803 100644 --- a/book/working_with_records.md +++ b/book/working_with_records.md @@ -4,15 +4,15 @@ Records are roughly equivalent to the individual rows of a table. You can think of a record as essentially being a "one-row table". Thus, most commands which operate on a table row _also_ operates on a record. For instance, [`update`](/commands/docs/update.md) can be used with records: ```nu -> let my_record = { - name: "Sam" - age: 30 - } -> $my_record | update age { $in + 1 } -╭──────┬─────╮ -│ name │ Sam │ -│ age │ 31 │ -╰──────┴─────╯ +let my_record = { + name: "Sam" + age: 30 + } +$my_record | update age { $in + 1 } +# => ╭──────┬─────╮ +# => │ name │ Sam │ +# => │ age │ 31 │ +# => ╰──────┴─────╯ ``` ::: @@ -23,19 +23,19 @@ A record is a collection of zero or more key-value pair mappings. It is similar ```nu # Nushell -> { "apples": 543, "bananas": 411, "oranges": 0 } -╭─────────┬─────╮ -│ apples │ 543 │ -│ bananas │ 411 │ -│ oranges │ 0 │ -╰─────────┴─────╯ +{ "apples": 543, "bananas": 411, "oranges": 0 } +# => ╭─────────┬─────╮ +# => │ apples │ 543 │ +# => │ bananas │ 411 │ +# => │ oranges │ 0 │ +# => ╰─────────┴─────╯ # JSON -> '{ "apples": 543, "bananas": 411, "oranges": 0 }' | from json -╭─────────┬─────╮ -│ apples │ 543 │ -│ bananas │ 411 │ -│ oranges │ 0 │ -╰─────────┴─────╯ +'{ "apples": 543, "bananas": 411, "oranges": 0 }' | from json +# => ╭─────────┬─────╮ +# => │ apples │ 543 │ +# => │ bananas │ 411 │ +# => │ oranges │ 0 │ +# => ╰─────────┴─────╯ ``` In Nushell, the key-value pairs of a record can also be separated using spaces or line-breaks. @@ -44,11 +44,11 @@ In Nushell, the key-value pairs of a record can also be separated using spaces o As records can have many fields, they are, by default, displayed vertically rather than left-to-right. To display a record left-to-right, convert it to a nuon. For example: ```nu - > { - name: "Sam" - rank: 10 - } | to nuon - {name: Sam, rank: 10} + { + name: "Sam" + rank: 10 + } | to nuon + # => {name: Sam, rank: 10} ``` ::: @@ -58,26 +58,26 @@ As records can have many fields, they are, by default, displayed vertically rath As with lists, you can [`insert`](/commands/docs/insert.md) values in records. For example, let's add some pears: ```nu -> { "apples": 543, "bananas": 411, "oranges": 0 } - | insert pears { 21 } -╭─────────┬─────╮ -│ apples │ 543 │ -│ bananas │ 411 │ -│ oranges │ 0 │ -│ pears │ 21 │ -╰─────────┴─────╯ +{ "apples": 543, "bananas": 411, "oranges": 0 } +| insert pears { 21 } +# => ╭─────────┬─────╮ +# => │ apples │ 543 │ +# => │ bananas │ 411 │ +# => │ oranges │ 0 │ +# => │ pears │ 21 │ +# => ╰─────────┴─────╯ ``` You can also [`update`](/commands/docs/update.md) values: ```nu -> { "apples": 543, "bananas": 411, "oranges": 0 } - | update oranges { 100 } -╭─────────┬─────╮ -│ apples │ 543 │ -│ bananas │ 411 │ -│ oranges │ 100 │ -╰─────────┴─────╯ +{ "apples": 543, "bananas": 411, "oranges": 0 } +| update oranges { 100 } +# => ╭─────────┬─────╮ +# => │ apples │ 543 │ +# => │ bananas │ 411 │ +# => │ oranges │ 100 │ +# => ╰─────────┴─────╯ ``` To make a copy of a record with new fields, you can either: @@ -85,28 +85,28 @@ To make a copy of a record with new fields, you can either: - Use the [`merge`](/commands/docs/merge.md) command: ```nu - > let first_record = { name: "Sam", rank: 10 } - > $first_record | merge { title: "Mayor" } - ╭───────┬───────╮ - │ name │ Sam │ - │ rank │ 10 │ - │ title │ Mayor │ - ╰───────┴───────╯ + let first_record = { name: "Sam", rank: 10 } + $first_record | merge { title: "Mayor" } + # => ╭───────┬───────╮ + # => │ name │ Sam │ + # => │ rank │ 10 │ + # => │ title │ Mayor │ + # => ╰───────┴───────╯ ``` - Use the [spread operator](/book/operators#spread-operator) (`...`) to expand the first record inside a new record: ```nu - > let first_record = { name: "Sam", rank: 10 } - > { - ...$first_record - title: "Mayor" - } - ╭───────┬───────╮ - │ name │ Sam │ - │ rank │ 10 │ - │ title │ Mayor │ - ╰───────┴───────╯ + let first_record = { name: "Sam", rank: 10 } + { + ...$first_record + title: "Mayor" + } + # => ╭───────┬───────╮ + # => │ name │ Sam │ + # => │ rank │ 10 │ + # => │ title │ Mayor │ + # => ╰───────┴───────╯ ``` ## Iterating over a Record @@ -114,14 +114,14 @@ To make a copy of a record with new fields, you can either: You can iterate over the key-value pairs of a record by first transposing it into a table: ```nu -> { "apples": 543, "bananas": 411, "oranges": 0 } - | transpose fruit count - | each {|f| $"We have ($f.count) ($f.fruit)" } -╭───┬─────────────────────╮ -│ 0 │ We have 543 apples │ -│ 1 │ We have 411 bananas │ -│ 2 │ We have 0 oranges │ -╰───┴─────────────────────╯ +{ "apples": 543, "bananas": 411, "oranges": 0 } +| transpose fruit count +| each {|f| $"We have ($f.count) ($f.fruit)" } +# => ╭───┬─────────────────────╮ +# => │ 0 │ We have 543 apples │ +# => │ 1 │ We have 411 bananas │ +# => │ 2 │ We have 0 oranges │ +# => ╰───┴─────────────────────╯ ``` ## Accessing Record Values diff --git a/book/working_with_strings.md b/book/working_with_strings.md index 59639f7ac6a..fe27637f99d 100644 --- a/book/working_with_strings.md +++ b/book/working_with_strings.md @@ -20,12 +20,12 @@ and much more. Strings are so common that Nushell offers multiple string formats The simplest string in Nushell is the single-quoted string. This string uses the `'` character to surround some text. Here's the text for hello world as a single-quoted string: ```nu -> 'hello world' -hello world -> 'The +'hello world' +# => hello world +'The end' -The -end +# => The +# => end ``` Single-quoted strings don't do anything to the text they're given, making them ideal for holding a wide range of text data. @@ -37,9 +37,9 @@ For more complex strings, Nushell also offers double-quoted strings. These strin For example, we could write the text hello followed by a new line and then world, using escape characters and a double-quoted string: ```nu -> "hello\nworld" -hello -world +"hello\nworld" +# => hello +# => world ``` Escape characters let you quickly add in a character that would otherwise be hard to type. @@ -65,8 +65,8 @@ by a starting `r#'` and a closing `'#`. This syntax should look familiar to user of Rust. ```nu -> r#'Raw strings can contain 'quoted' text.'# -Raw strings can contain 'quoted' text. +r#'Raw strings can contain 'quoted' text.'# +# => Raw strings can contain 'quoted' text. ``` Additional `#` symbols can be added to the start and end of the raw string to enclose @@ -74,8 +74,8 @@ one less than the same number of `#` symbols next to a `'` symbol in the string. be used to nest raw strings: ```nu -> r###'r##'This is an example of a raw string.'##'### -r##'This is an example of a raw string.'## +r###'r##'This is an example of a raw string.'##'### +# => r##'This is an example of a raw string.'## ``` ## Bare Word Strings @@ -83,46 +83,46 @@ r##'This is an example of a raw string.'## Like other shell languages (but unlike most other programming languages) strings consisting of a single 'word' can also be written without any quotes: ```nu -> print hello -hello -> [hello] | describe -list +print hello +# => hello +[hello] | describe +# => list ``` But be careful - if you use a bare word plainly on the command line (that is, not inside a data structure or used as a command parameter) or inside round brackets `(` `)`, it will be interpreted as an external command: ```nu -> hello -Error: nu::shell::external_command - - × External command failed - ╭─[entry #5:1:1] - 1 │ hello - · ──┬── - · ╰── executable was not found - ╰──── - help: program not found +hello +# => Error: nu::shell::external_command +# => +# => × External command failed +# => ╭─[entry #5:1:1] +# => 1 │ hello +# => · ──┬── +# => · ╰── executable was not found +# => ╰──── +# => help: program not found ``` Also, many bare words have special meaning in nu, and so will not be interpreted as a string: ```nu -> true | describe -bool -> [true] | describe -list -> [trueX] | describe -list -> trueX | describe -Error: nu::shell::external_command - - × External command failed - ╭─[entry #5:1:1] - 1 │ trueX | describe - · ──┬── - · ╰── executable was not found - ╰──── - help: program not found +true | describe +# => bool +[true] | describe +# => list +[trueX] | describe +# => list +trueX | describe +# => Error: nu::shell::external_command +# => +# => × External command failed +# => ╭─[entry #5:1:1] +# => 1 │ trueX | describe +# => · ──┬── +# => · ╰── executable was not found +# => ╰──── +# => help: program not found ``` So, while bare strings are useful for informal command line usage, when programming more formally in nu, you should generally use quotes. @@ -155,10 +155,10 @@ ls `./my dir/*` Backtick-quoted strings cannot contain _unmatched_ backticks in the string itself. For example: `````nu -> echo ```` +echo ```` `` -> echo ``` +echo ``` # Unterminated string which will start a new line in the CLI ````` @@ -169,8 +169,8 @@ You can place the `^` sigil in front of any string (including a variable) to hav ```nu ^'C:\Program Files\exiftool.exe' -> let foo = 'C:\Program Files\exiftool.exe' -> ^$foo +let foo = 'C:\Program Files\exiftool.exe' +^$foo ``` You can also use the [`run-external`](/commands/docs/run-external.md) command for this purpose, which provides additional flags and options. @@ -216,9 +216,9 @@ String interpolation uses `$" "` and `$' '` as ways to wrap interpolated text. For example, let's say we have a variable called `$name` and we want to greet the name of the person contained in this variable: ```nu -> let name = "Alice" -> $"greetings, ($name)" -greetings, Alice +let name = "Alice" +$"greetings, ($name)" +# => greetings, Alice ``` By wrapping expressions in `()`, we can run them to completion and use the results to help build the string. @@ -228,8 +228,8 @@ String interpolation has both a single-quoted, `$' '`, and a double-quoted, `$" As of version 0.61, interpolated strings support escaping parentheses, so that the `(` and `)` characters may be used in a string without Nushell trying to evaluate what appears between them: ```nu -> $"2 + 2 is (2 + 2) \(you guessed it!)" -2 + 2 is 4 (you guessed it!) +$"2 + 2 is (2 + 2) \(you guessed it!)" +# => 2 + 2 is 4 (you guessed it!) ``` Interpolated strings can be evaluated at parse time, but if they include values whose formatting depends @@ -238,7 +238,7 @@ So if you have something like this in your `config.nu`, `x` will be `"2.0 KB"` e `MB` for all file sizes (datetimes will similarly use the default config). ```nu -> const x = $"(2kb)" +const x = $"(2kb)" ``` ## Splitting Strings @@ -246,36 +246,36 @@ So if you have something like this in your `config.nu`, `x` will be `"2.0 KB"` e The [`split row`](/commands/docs/split_row.md) command creates a list from a string based on a delimiter. ```nu -> "red,green,blue" | split row "," -╭───┬───────╮ -│ 0 │ red │ -│ 1 │ green │ -│ 2 │ blue │ -╰───┴───────╯ +"red,green,blue" | split row "," +# => ╭───┬───────╮ +# => │ 0 │ red │ +# => │ 1 │ green │ +# => │ 2 │ blue │ +# => ╰───┴───────╯ ``` The [`split column`](/commands/docs/split_column.md) command will create a table from a string based on a delimiter. This applies generic column names to the table. ```nu -> "red,green,blue" | split column "," -╭───┬─────────┬─────────┬─────────╮ -│ # │ column1 │ column2 │ column3 │ -├───┼─────────┼─────────┼─────────┤ -│ 0 │ red │ green │ blue │ -╰───┴─────────┴─────────┴─────────╯ +"red,green,blue" | split column "," +# => ╭───┬─────────┬─────────┬─────────╮ +# => │ # │ column1 │ column2 │ column3 │ +# => ├───┼─────────┼─────────┼─────────┤ +# => │ 0 │ red │ green │ blue │ +# => ╰───┴─────────┴─────────┴─────────╯ ``` Finally, the [`split chars`](/commands/docs/split_chars.md) command will split a string into a list of characters. ```nu -> 'aeiou' | split chars -╭───┬───╮ -│ 0 │ a │ -│ 1 │ e │ -│ 2 │ i │ -│ 3 │ o │ -│ 4 │ u │ -╰───┴───╯ +'aeiou' | split chars +# => ╭───┬───╮ +# => │ 0 │ a │ +# => │ 1 │ e │ +# => │ 2 │ i │ +# => │ 3 │ o │ +# => │ 4 │ u │ +# => ╰───┴───╯ ``` ## The [`str`](/commands/docs/str.md) command @@ -285,8 +285,8 @@ Many string functions are subcommands of the [`str`](/commands/docs/str.md) comm For example, you can look if a string contains a particular substring using [`str contains`](/commands/docs/str_contains.md): ```nu -> "hello world" | str contains "o wo" -true +"hello world" | str contains "o wo" +# => true ``` (You might also prefer, for brevity, the `=~` operator (described below).) @@ -296,8 +296,8 @@ true You can trim the sides of a string with the [`str trim`](/commands/docs/str_trim.md) command. By default, the [`str trim`](/commands/docs/str_trim.md) commands trims whitespace from both sides of the string. For example: ```nu -> ' My string ' | str trim -My string +' My string ' | str trim +# => My string ``` You can specify on which side the trimming occurs with the `--right` and `--left` options. (`-r` and `-l` being the short-form options respectively) @@ -307,8 +307,8 @@ To trim a specific character, use `--char ` or `-c ` to sp Here's an example of all the options in action: ```nu -> '=== Nu shell ===' | str trim -r -c '=' -=== Nu shell +'=== Nu shell ===' | str trim -r -c '=' +# => === Nu shell ``` ### Substrings @@ -316,12 +316,12 @@ Here's an example of all the options in action: Substrings are slices of a string. They have a startpoint and an endpoint. Here's an example of using a substring: ```nu -> 'Hello World!' | str index-of 'o' -4 -> 'Hello World!' | str index-of 'r' -8 -> 'Hello World!' | str substring 4..8 -o Wo +'Hello World!' | str index-of 'o' +# => 4 +'Hello World!' | str index-of 'r' +# => 8 +'Hello World!' | str substring 4..8 +# => o Wo ``` ### String Padding @@ -329,10 +329,10 @@ o Wo With the [`fill`](/commands/docs/fill.md) command you can add padding to a string. Padding adds characters to string until it's a certain length. For example: ```nu -> '1234' | fill -a right -c '0' -w 10 -0000001234 -> '1234' | fill -a left -c '0' -w 10 | str length -10 +'1234' | fill -a right -c '0' -w 10 +# => 0000001234 +'1234' | fill -a left -c '0' -w 10 | str length +# => 10 ``` ### Reversing Strings @@ -340,14 +340,14 @@ With the [`fill`](/commands/docs/fill.md) command you can add padding to a strin This can be done easily with the [`str reverse`](/commands/docs/str_reverse.md) command. ```nu -> 'Nushell' | str reverse -llehsuN -> ['Nushell' 'is' 'cool'] | str reverse -╭───┬─────────╮ -│ 0 │ llehsuN │ -│ 1 │ si │ -│ 2 │ looc │ -╰───┴─────────╯ +'Nushell' | str reverse +# => llehsuN +['Nushell' 'is' 'cool'] | str reverse +# => ╭───┬─────────╮ +# => │ 0 │ llehsuN │ +# => │ 1 │ si │ +# => │ 2 │ looc │ +# => ╰───┴─────────╯ ``` ## String Parsing @@ -355,42 +355,42 @@ llehsuN With the [`parse`](/commands/docs/parse.md) command you can parse a string into columns. For example: ```nu -> 'Nushell 0.80' | parse '{shell} {version}' -╭───┬─────────┬─────────╮ -│ # │ shell │ version │ -├───┼─────────┼─────────┤ -│ 0 │ Nushell │ 0.80 │ -╰───┴─────────┴─────────╯ -> 'where all data is structured!' | parse --regex '(?P\w*\s?\w+) is (?P\w+)' -╭───┬──────────┬────────────╮ -│ # │ subject │ adjective │ -├───┼──────────┼────────────┤ -│ 0 │ all data │ structured │ -╰───┴──────────┴────────────╯ +'Nushell 0.80' | parse '{shell} {version}' +# => ╭───┬─────────┬─────────╮ +# => │ # │ shell │ version │ +# => ├───┼─────────┼─────────┤ +# => │ 0 │ Nushell │ 0.80 │ +# => ╰───┴─────────┴─────────╯ +'where all data is structured!' | parse --regex '(?P\w*\s?\w+) is (?P\w+)' +# => ╭───┬──────────┬────────────╮ +# => │ # │ subject │ adjective │ +# => ├───┼──────────┼────────────┤ +# => │ 0 │ all data │ structured │ +# => ╰───┴──────────┴────────────╯ ``` If a string is known to contain comma-separated, tab-separated or multi-space-separated data, you can use [`from csv`](/commands/docs/from_csv.md), [`from tsv`](/commands/docs/from_tsv.md) or [`from ssv`](/commands/docs/from_ssv.md): ```nu -> "acronym,long\nAPL,A Programming Language" | from csv -╭───┬─────────┬────────────────────────╮ -│ # │ acronym │ long │ -├───┼─────────┼────────────────────────┤ -│ 0 │ APL │ A Programming Language │ -╰───┴─────────┴────────────────────────╯ -> "name duration\nonestop.mid 4:06" | from ssv -╭───┬─────────────┬──────────╮ -│ # │ name │ duration │ -├───┼─────────────┼──────────┤ -│ 0 │ onestop.mid │ 4:06 │ -╰───┴─────────────┴──────────╯ -> "rank\tsuit\nJack\tSpades\nAce\tClubs" | from tsv -╭───┬──────┬────────╮ -│ # │ rank │ suit │ -├───┼──────┼────────┤ -│ 0 │ Jack │ Spades │ -│ 1 │ Ace │ Clubs │ -╰───┴──────┴────────╯ +"acronym,long\nAPL,A Programming Language" | from csv +# => ╭───┬─────────┬────────────────────────╮ +# => │ # │ acronym │ long │ +# => ├───┼─────────┼────────────────────────┤ +# => │ 0 │ APL │ A Programming Language │ +# => ╰───┴─────────┴────────────────────────╯ +"name duration\nonestop.mid 4:06" | from ssv +# => ╭───┬─────────────┬──────────╮ +# => │ # │ name │ duration │ +# => ├───┼─────────────┼──────────┤ +# => │ 0 │ onestop.mid │ 4:06 │ +# => ╰───┴─────────────┴──────────╯ +"rank\tsuit\nJack\tSpades\nAce\tClubs" | from tsv +# => ╭───┬──────┬────────╮ +# => │ # │ rank │ suit │ +# => ├───┼──────┼────────┤ +# => │ 0 │ Jack │ Spades │ +# => │ 1 │ Ace │ Clubs │ +# => ╰───┴──────┴────────╯ ``` ## String Comparison @@ -400,19 +400,19 @@ In addition to the standard `==` and `!=` operators, a few operators exist for s Those familiar with Bash and Perl will recognise the regex comparison operators: ```nu -> 'APL' =~ '^\w{0,3}$' -true -> 'FORTRAN' !~ '^\w{0,3}$' -true +'APL' =~ '^\w{0,3}$' +# => true +'FORTRAN' !~ '^\w{0,3}$' +# => true ``` Two other operators exist for simpler comparisons: ```nu -> 'JavaScript' starts-with 'Java' -true -> 'OCaml' ends-with 'Caml' -true +'JavaScript' starts-with 'Java' +# => true +'OCaml' ends-with 'Caml' +# => true ``` ## Converting Strings @@ -433,8 +433,12 @@ There are multiple ways to convert strings to and from other types. You can color strings with the [`ansi`](/commands/docs/ansi.md) command. For example: ```nu -> $'(ansi purple_bold)This text is a bold purple!(ansi reset)' +$'(ansi purple_bold)This text is a bold purple!(ansi reset)' ``` `ansi purple_bold` makes the text a bold purple -`ansi reset` resets the coloring to the default. (Tip: You should always end colored strings with `ansi reset`) +`ansi reset` resets the coloring to the default. + +::: tip +You should always end colored strings with `ansi reset` +::: diff --git a/book/working_with_tables.md b/book/working_with_tables.md index 348a6f99463..255a697633a 100644 --- a/book/working_with_tables.md +++ b/book/working_with_tables.md @@ -9,18 +9,18 @@ One of the common ways of seeing data in Nu is through a table. Nu comes with a To start off, let's get a table that we can use: ```nu -> ls -───┬───────────────┬──────┬─────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────────┼──────┼─────────┼──────────── - 0 │ files.rs │ File │ 4.6 KB │ 5 days ago - 1 │ lib.rs │ File │ 330 B │ 5 days ago - 2 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago - 3 │ parse.rs │ File │ 49.8 KB │ 1 day ago - 4 │ path.rs │ File │ 2.1 KB │ 5 days ago - 5 │ shapes.rs │ File │ 4.7 KB │ 5 days ago - 6 │ signature.rs │ File │ 1.2 KB │ 5 days ago -───┴───────────────┴──────┴─────────┴──────────── +ls +# => ───┬───────────────┬──────┬─────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────────┼──────┼─────────┼──────────── +# => 0 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 1 │ lib.rs │ File │ 330 B │ 5 days ago +# => 2 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago +# => 3 │ parse.rs │ File │ 49.8 KB │ 1 day ago +# => 4 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 5 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => 6 │ signature.rs │ File │ 1.2 KB │ 5 days ago +# => ───┴───────────────┴──────┴─────────┴──────────── ``` ::: tip Changing how tables are displayed @@ -33,18 +33,18 @@ See [hooks](/book/hooks.md#changing-how-output-is-displayed) for more informatio We can sort a table by calling the [`sort-by`](/commands/docs/sort-by.md) command and telling it which columns we want to use in the sort. Let's say we wanted to sort our table by the size of the file: ```nu -> ls | sort-by size -───┬───────────────┬──────┬─────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────────┼──────┼─────────┼──────────── - 0 │ lib.rs │ File │ 330 B │ 5 days ago - 1 │ signature.rs │ File │ 1.2 KB │ 5 days ago - 2 │ path.rs │ File │ 2.1 KB │ 5 days ago - 3 │ files.rs │ File │ 4.6 KB │ 5 days ago - 4 │ shapes.rs │ File │ 4.7 KB │ 5 days ago - 5 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago - 6 │ parse.rs │ File │ 49.8 KB │ 1 day ago -───┴───────────────┴──────┴─────────┴──────────── +ls | sort-by size +# => ───┬───────────────┬──────┬─────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────────┼──────┼─────────┼──────────── +# => 0 │ lib.rs │ File │ 330 B │ 5 days ago +# => 1 │ signature.rs │ File │ 1.2 KB │ 5 days ago +# => 2 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 3 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 4 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => 5 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago +# => 6 │ parse.rs │ File │ 49.8 KB │ 1 day ago +# => ───┴───────────────┴──────┴─────────┴──────────── ``` We can sort a table by any column that can be compared. For example, we could also have sorted the above using the "name", "accessed", or "modified" columns. @@ -60,33 +60,33 @@ The following is a basic overview. For a more in-depth discussion of this topic, We can select data from a table by choosing to select specific columns or specific rows. Let's [`select`](/commands/docs/select.md) a few columns from our table to use: ```nu -> ls | select name size -───┬───────────────┬───────── - # │ name │ size -───┼───────────────┼───────── - 0 │ files.rs │ 4.6 KB - 1 │ lib.rs │ 330 B - 2 │ lite_parse.rs │ 6.3 KB - 3 │ parse.rs │ 49.8 KB - 4 │ path.rs │ 2.1 KB - 5 │ shapes.rs │ 4.7 KB - 6 │ signature.rs │ 1.2 KB -───┴───────────────┴───────── +ls | select name size +# => ───┬───────────────┬───────── +# => # │ name │ size +# => ───┼───────────────┼───────── +# => 0 │ files.rs │ 4.6 KB +# => 1 │ lib.rs │ 330 B +# => 2 │ lite_parse.rs │ 6.3 KB +# => 3 │ parse.rs │ 49.8 KB +# => 4 │ path.rs │ 2.1 KB +# => 5 │ shapes.rs │ 4.7 KB +# => 6 │ signature.rs │ 1.2 KB +# => ───┴───────────────┴───────── ``` This helps to create a table that's more focused on what we need. Next, let's say we want to only look at the 5 smallest files in this directory: ```nu -> ls | sort-by size | first 5 -───┬──────────────┬──────┬────────┬──────────── - # │ name │ type │ size │ modified -───┼──────────────┼──────┼────────┼──────────── - 0 │ lib.rs │ File │ 330 B │ 5 days ago - 1 │ signature.rs │ File │ 1.2 KB │ 5 days ago - 2 │ path.rs │ File │ 2.1 KB │ 5 days ago - 3 │ files.rs │ File │ 4.6 KB │ 5 days ago - 4 │ shapes.rs │ File │ 4.7 KB │ 5 days ago -───┴──────────────┴──────┴────────┴──────────── +ls | sort-by size | first 5 +# => ───┬──────────────┬──────┬────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼──────────────┼──────┼────────┼──────────── +# => 0 │ lib.rs │ File │ 330 B │ 5 days ago +# => 1 │ signature.rs │ File │ 1.2 KB │ 5 days ago +# => 2 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 3 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 4 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => ───┴──────────────┴──────┴────────┴──────────── ``` You'll notice we first sort the table by size to get to the smallest file, and then we use the `first 5` to return the first 5 rows of the table. @@ -94,14 +94,14 @@ You'll notice we first sort the table by size to get to the smallest file, and t You can also [`skip`](/commands/docs/skip.md) rows that you don't want. Let's skip the first two of the 5 rows we returned above: ```nu -> ls | sort-by size | first 5 | skip 2 -───┬───────────┬──────┬────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────┼──────┼────────┼──────────── - 0 │ path.rs │ File │ 2.1 KB │ 5 days ago - 1 │ files.rs │ File │ 4.6 KB │ 5 days ago - 2 │ shapes.rs │ File │ 4.7 KB │ 5 days ago -───┴───────────┴──────┴────────┴──────────── +ls | sort-by size | first 5 | skip 2 +# => ───┬───────────┬──────┬────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────┼──────┼────────┼──────────── +# => 0 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 1 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 2 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => ───┴───────────┴──────┴────────┴──────────── ``` We've narrowed it to three rows we care about. @@ -109,25 +109,25 @@ We've narrowed it to three rows we care about. Let's look at a few other commands for selecting data. You may have wondered why the rows of the table are numbers. This acts as a handy way to get to a single row. Let's sort our table by the file name and then pick one of the rows with the [`select`](/commands/docs/select.md) command using its row number: ```nu -> ls | sort-by name -───┬───────────────┬──────┬─────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────────┼──────┼─────────┼──────────── - 0 │ files.rs │ File │ 4.6 KB │ 5 days ago - 1 │ lib.rs │ File │ 330 B │ 5 days ago - 2 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago - 3 │ parse.rs │ File │ 49.8 KB │ 1 day ago - 4 │ path.rs │ File │ 2.1 KB │ 5 days ago - 5 │ shapes.rs │ File │ 4.7 KB │ 5 days ago - 6 │ signature.rs │ File │ 1.2 KB │ 5 days ago -───┴───────────────┴──────┴─────────┴──────────── - -> ls | sort-by name | select 5 -───┬───────────────┬──────┬─────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────────┼──────┼─────────┼──────────── - 0 │ shapes.rs │ File │ 4.7 KB │ 5 days ago -───┴───────────────┴──────┴─────────┴──────────── +ls | sort-by name +# => ───┬───────────────┬──────┬─────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────────┼──────┼─────────┼──────────── +# => 0 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 1 │ lib.rs │ File │ 330 B │ 5 days ago +# => 2 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago +# => 3 │ parse.rs │ File │ 49.8 KB │ 1 day ago +# => 4 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 5 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => 6 │ signature.rs │ File │ 1.2 KB │ 5 days ago +# => ───┴───────────────┴──────┴─────────┴──────────── + +ls | sort-by name | select 5 +# => ───┬───────────────┬──────┬─────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────────┼──────┼─────────┼──────────── +# => 0 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => ───┴───────────────┴──────┴─────────┴──────────── ``` ## Getting Data out of a Table @@ -135,16 +135,16 @@ Let's look at a few other commands for selecting data. You may have wondered why So far, we've worked with tables by trimming the table down to only what we need. Sometimes we may want to go a step further and only look at the values in the cells themselves rather than taking a whole column. Let's say, for example, we wanted to only get a list of the names of the files. For this, we use the [`get`](/commands/docs/get.md) command: ```nu -> ls | get name -───┬─────────────── - 0 │ files.rs - 1 │ lib.rs - 2 │ lite_parse.rs - 3 │ parse.rs - 4 │ path.rs - 5 │ shapes.rs - 6 │ signature.rs -───┴─────────────── +ls | get name +# => ───┬─────────────── +# => 0 │ files.rs +# => 1 │ lib.rs +# => 2 │ lite_parse.rs +# => 3 │ parse.rs +# => 4 │ path.rs +# => 5 │ shapes.rs +# => 6 │ signature.rs +# => ───┴─────────────── ``` We now have the values for each of the filenames. @@ -152,18 +152,18 @@ We now have the values for each of the filenames. This might look like the [`select`](/commands/docs/select.md) command we saw earlier, so let's put that here as well to compare the two: ```nu -> ls | select name -───┬─────────────── - # │ name -───┼─────────────── - 0 │ files.rs - 1 │ lib.rs - 2 │ lite_parse.rs - 3 │ parse.rs - 4 │ path.rs - 5 │ shapes.rs - 6 │ signature.rs -───┴─────────────── +ls | select name +# => ───┬─────────────── +# => # │ name +# => ───┼─────────────── +# => 0 │ files.rs +# => 1 │ lib.rs +# => 2 │ lite_parse.rs +# => 3 │ parse.rs +# => 4 │ path.rs +# => 5 │ shapes.rs +# => 6 │ signature.rs +# => ───┴─────────────── ``` These look very similar! Let's see if we can spell out the difference between these two commands to make it clear: @@ -187,12 +187,12 @@ We can concatenate tables using [`append`](/commands/docs/append.md): let first = [[a b]; [1 2]] let second = [[a b]; [3 4]] $first | append $second -───┬───┬─── - # │ a │ b -───┼───┼─── - 0 │ 1 │ 2 - 1 │ 3 │ 4 -───┴───┴─── +# => ───┬───┬─── +# => # │ a │ b +# => ───┼───┼─── +# => 0 │ 1 │ 2 +# => 1 │ 3 │ 4 +# => ───┴───┴─── ``` If the column names are not identical then additionally columns and values will be created as necessary: @@ -202,26 +202,26 @@ let first = [[a b]; [1 2]] let second = [[a b]; [3 4]] let third = [[a c]; [3 4]] $first | append $second | append $third -───┬───┬────┬──── - # │ a │ b │ c -───┼───┼────┼──── - 0 │ 1 │ 2 │ ❎ - 1 │ 3 │ 4 │ ❎ - 2 │ 3 │ ❎ │ 4 -───┴───┴────┴──── +# => ───┬───┬────┬──── +# => # │ a │ b │ c +# => ───┼───┼────┼──── +# => 0 │ 1 │ 2 │ ❎ +# => 1 │ 3 │ 4 │ ❎ +# => 2 │ 3 │ ❎ │ 4 +# => ───┴───┴────┴──── ``` You can also use the `++` operator as an inline replacement for `append`: ```nu $first ++ $second ++ $third -───┬───┬────┬──── - # │ a │ b │ c -───┼───┼────┼──── - 0 │ 1 │ 2 │ ❎ - 1 │ 3 │ 4 │ ❎ - 2 │ 3 │ ❎ │ 4 -───┴───┴────┴─── +# => ───┬───┬────┬──── +# => # │ a │ b │ c +# => ───┼───┼────┼──── +# => 0 │ 1 │ 2 │ ❎ +# => 1 │ 3 │ 4 │ ❎ +# => 2 │ 3 │ ❎ │ 4 +# => ───┴───┴────┴─── ``` ### Merging Tables @@ -232,39 +232,39 @@ We can use the [`merge`](/commands/docs/merge.md) command to merge two (or more) let first = [[a b]; [1 2]] let second = [[c d]; [3 4]] $first | merge $second -───┬───┬───┬───┬─── - # │ a │ b │ c │ d -───┼───┼───┼───┼─── - 0 │ 1 │ 2 │ 3 │ 4 -───┴───┴───┴───┴─── +# => ───┬───┬───┬───┬─── +# => # │ a │ b │ c │ d +# => ───┼───┼───┼───┼─── +# => 0 │ 1 │ 2 │ 3 │ 4 +# => ───┴───┴───┴───┴─── ``` Let's add a third table: ```nu -> let third = [[e f]; [5 6]] +let third = [[e f]; [5 6]] ``` We could join all three tables together like this: ```nu -> $first | merge $second | merge $third -───┬───┬───┬───┬───┬───┬─── - # │ a │ b │ c │ d │ e │ f -───┼───┼───┼───┼───┼───┼─── - 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 -───┴───┴───┴───┴───┴───┴─── +$first | merge $second | merge $third +# => ───┬───┬───┬───┬───┬───┬─── +# => # │ a │ b │ c │ d │ e │ f +# => ───┼───┼───┼───┼───┼───┼─── +# => 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 +# => ───┴───┴───┴───┴───┴───┴─── ``` Or we could use the [`reduce`](/commands/docs/reduce.md) command to dynamically merge all tables: ```nu -> [$first $second $third] | reduce {|elt, acc| $acc | merge $elt } -───┬───┬───┬───┬───┬───┬─── - # │ a │ b │ c │ d │ e │ f -───┼───┼───┼───┼───┼───┼─── - 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 -───┴───┴───┴───┴───┴───┴─── +[$first $second $third] | reduce {|elt, acc| $acc | merge $elt } +# => ───┬───┬───┬───┬───┬───┬─── +# => # │ a │ b │ c │ d │ e │ f +# => ───┼───┼───┼───┼───┼───┼─── +# => 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 +# => ───┴───┴───┴───┴───┴───┴─── ``` ### Adding a new Column @@ -272,53 +272,53 @@ Or we could use the [`reduce`](/commands/docs/reduce.md) command to dynamically We can use the [`insert`](/commands/docs/insert.md) command to add a new column to the table. Let's look at an example: ```nu -> open rustfmt.toml -─────────┬────── - edition │ 2018 -─────────┴────── +open rustfmt.toml +# => ─────────┬────── +# => edition │ 2018 +# => ─────────┴────── ``` Let's add a column called "next_edition" with the value 2021: ```nu -> open rustfmt.toml | insert next_edition 2021 -──────────────┬────── - edition │ 2018 - next_edition │ 2021 -──────────────┴────── +open rustfmt.toml | insert next_edition 2021 +# => ──────────────┬────── +# => edition │ 2018 +# => next_edition │ 2021 +# => ──────────────┴────── ``` This visual may be slightly confusing, because it looks like what we've just done is add a row. In this case, remember: rows have numbers, columns have names. If it still is confusing, note that appending one more row will make the table render as expected: ```nu -> open rustfmt.toml | insert next_edition 2021 | append {edition: 2021 next_edition: 2024} -───┬─────────┬────────────── - # │ edition │ next_edition -───┼─────────┼────────────── - 0 │ 2018 │ 2021 - 1 │ 2021 │ 2024 -───┴─────────┴────────────── +open rustfmt.toml | insert next_edition 2021 | append {edition: 2021 next_edition: 2024} +# => ───┬─────────┬────────────── +# => # │ edition │ next_edition +# => ───┼─────────┼────────────── +# => 0 │ 2018 │ 2021 +# => 1 │ 2021 │ 2024 +# => ───┴─────────┴────────────── ``` Notice that if we open the original file, the contents have stayed the same: ```nu -> open rustfmt.toml -─────────┬────── - edition │ 2018 -─────────┴────── +open rustfmt.toml +# => ─────────┬────── +# => edition │ 2018 +# => ─────────┴────── ``` Changes in Nu are functional changes, meaning that they work on values themselves rather than trying to cause a permanent change. This lets us do many different types of work in our pipeline until we're ready to write out the result with any changes we'd like if we choose to. Here we could write out the result using the [`save`](/commands/docs/save.md) command: ```nu -> open rustfmt.toml | insert next_edition 2021 | save rustfmt2.toml -> open rustfmt2.toml -──────────────┬────── - edition │ 2018 - next_edition │ 2021 -──────────────┴────── +open rustfmt.toml | insert next_edition 2021 | save rustfmt2.toml +open rustfmt2.toml +# => ──────────────┬────── +# => edition │ 2018 +# => next_edition │ 2021 +# => ──────────────┴────── ``` ### Updating a Column @@ -326,19 +326,19 @@ Changes in Nu are functional changes, meaning that they work on values themselve In a similar way to the [`insert`](/commands/docs/insert.md) command, we can also use the [`update`](/commands/docs/update.md) command to change the contents of a column to a new value. To see it in action let's open the same file: ```nu -> open rustfmt.toml -─────────┬────── - edition │ 2018 -─────────┴────── +open rustfmt.toml +# => ─────────┬────── +# => edition │ 2018 +# => ─────────┴────── ``` And now, let's update the edition to point at the next edition we hope to support: ```nu -> open rustfmt.toml | update edition 2021 -─────────┬────── - edition │ 2021 -─────────┴────── +open rustfmt.toml | update edition 2021 +# => ─────────┬────── +# => edition │ 2021 +# => ─────────┴────── ``` You can also use the [`upsert`](/commands/docs/upsert.md) command to insert or update depending on whether the column already exists. @@ -348,16 +348,16 @@ You can also use the [`upsert`](/commands/docs/upsert.md) command to insert or u You can use [`move`](/commands/docs/move.md) to move columns in the table. For example, if we wanted to move the "name" column from [`ls`](/commands/docs/ls.md) after the "size" column, we could do: ```nu -> ls | move name --after size -╭────┬──────┬─────────┬───────────────────┬──────────────╮ -│ # │ type │ size │ name │ modified │ -├────┼──────┼─────────┼───────────────────┼──────────────┤ -│ 0 │ dir │ 256 B │ Applications │ 3 days ago │ -│ 1 │ dir │ 256 B │ Data │ 2 weeks ago │ -│ 2 │ dir │ 448 B │ Desktop │ 2 hours ago │ -│ 3 │ dir │ 192 B │ Disks │ a week ago │ -│ 4 │ dir │ 416 B │ Documents │ 4 days ago │ -... +ls | move name --after size +# => ╭────┬──────┬─────────┬───────────────────┬──────────────╮ +# => │ # │ type │ size │ name │ modified │ +# => ├────┼──────┼─────────┼───────────────────┼──────────────┤ +# => │ 0 │ dir │ 256 B │ Applications │ 3 days ago │ +# => │ 1 │ dir │ 256 B │ Data │ 2 weeks ago │ +# => │ 2 │ dir │ 448 B │ Desktop │ 2 hours ago │ +# => │ 3 │ dir │ 192 B │ Disks │ a week ago │ +# => │ 4 │ dir │ 416 B │ Documents │ 4 days ago │ +# => ... ``` ### Renaming Columns @@ -365,16 +365,16 @@ You can use [`move`](/commands/docs/move.md) to move columns in the table. For e You can also [`rename`](/commands/docs/rename.md) columns in a table by passing it through the rename command. If we wanted to run [`ls`](/commands/docs/ls.md) and rename the columns, we can use this example: ```nu -> ls | rename filename filetype filesize date -╭────┬───────────────────┬──────────┬──────────┬──────────────╮ -│ # │ filename │ filetype │ filesize │ date │ -├────┼───────────────────┼──────────┼──────────┼──────────────┤ -│ 0 │ Applications │ dir │ 256 B │ 3 days ago │ -│ 1 │ Data │ dir │ 256 B │ 2 weeks ago │ -│ 2 │ Desktop │ dir │ 448 B │ 2 hours ago │ -│ 3 │ Disks │ dir │ 192 B │ a week ago │ -│ 4 │ Documents │ dir │ 416 B │ 4 days ago │ -... +ls | rename filename filetype filesize date +# => ╭────┬───────────────────┬──────────┬──────────┬──────────────╮ +# => │ # │ filename │ filetype │ filesize │ date │ +# => ├────┼───────────────────┼──────────┼──────────┼──────────────┤ +# => │ 0 │ Applications │ dir │ 256 B │ 3 days ago │ +# => │ 1 │ Data │ dir │ 256 B │ 2 weeks ago │ +# => │ 2 │ Desktop │ dir │ 448 B │ 2 hours ago │ +# => │ 3 │ Disks │ dir │ 192 B │ a week ago │ +# => │ 4 │ Documents │ dir │ 416 B │ 4 days ago │ +# => ... ``` ### Rejecting/Deleting Columns @@ -382,19 +382,19 @@ You can also [`rename`](/commands/docs/rename.md) columns in a table by passing You can also [`reject`](/commands/docs/reject.md) columns in a table by passing it through the reject command. If we wanted to run [`ls`](/commands/docs/ls.md) and delete the columns, we can use this example: ```nu -> ls -l / | reject readonly num_links inode created accessed modified -╭────┬────────┬─────────┬─────────┬───────────┬──────┬───────┬────────╮ -│ # │ name │ type │ target │ mode │ uid │ group │ size │ -├────┼────────┼─────────┼─────────┼───────────┼──────┼───────┼────────┤ -│ 0 │ /bin │ symlink │ usr/bin │ rwxrwxrwx │ root │ root │ 7 B │ -│ 1 │ /boot │ dir │ │ rwxr-xr-x │ root │ root │ 1.0 KB │ -│ 2 │ /dev │ dir │ │ rwxr-xr-x │ root │ root │ 4.1 KB │ -│ 3 │ /etc │ dir │ │ rwxr-xr-x │ root │ root │ 3.6 KB │ -│ 4 │ /home │ dir │ │ rwxr-xr-x │ root │ root │ 12 B │ -│ 5 │ /lib │ symlink │ usr/lib │ rwxrwxrwx │ root │ root │ 7 B │ -│ 6 │ /lib64 │ symlink │ usr/lib │ rwxrwxrwx │ root │ root │ 7 B │ -│ 7 │ /mnt │ dir │ │ rwxr-xr-x │ root │ root │ 0 B │ -... +ls -l / | reject readonly num_links inode created accessed modified +# => ╭────┬────────┬─────────┬─────────┬───────────┬──────┬───────┬────────╮ +# => │ # │ name │ type │ target │ mode │ uid │ group │ size │ +# => ├────┼────────┼─────────┼─────────┼───────────┼──────┼───────┼────────┤ +# => │ 0 │ /bin │ symlink │ usr/bin │ rwxrwxrwx │ root │ root │ 7 B │ +# => │ 1 │ /boot │ dir │ │ rwxr-xr-x │ root │ root │ 1.0 KB │ +# => │ 2 │ /dev │ dir │ │ rwxr-xr-x │ root │ root │ 4.1 KB │ +# => │ 3 │ /etc │ dir │ │ rwxr-xr-x │ root │ root │ 3.6 KB │ +# => │ 4 │ /home │ dir │ │ rwxr-xr-x │ root │ root │ 12 B │ +# => │ 5 │ /lib │ symlink │ usr/lib │ rwxrwxrwx │ root │ root │ 7 B │ +# => │ 6 │ /lib64 │ symlink │ usr/lib │ rwxrwxrwx │ root │ root │ 7 B │ +# => │ 7 │ /mnt │ dir │ │ rwxr-xr-x │ root │ root │ 0 B │ +# => ... ``` ### The # Index Column diff --git a/commands/categories/deprecated.md b/commands/categories/deprecated.md index 4b84bb96793..319829d2e33 100644 --- a/commands/categories/deprecated.md +++ b/commands/categories/deprecated.md @@ -20,7 +20,7 @@ Description - {{ command.title }} + {{ command.title }} {{ command.frontmatter.usage }} diff --git a/commands/docs/alias.md b/commands/docs/alias.md index a58b552b7f5..ee85622e5aa 100644 --- a/commands/docs/alias.md +++ b/commands/docs/alias.md @@ -2,7 +2,7 @@ title: alias categories: | core -version: 0.100.0 +version: 0.101.0 core: | Alias a command (with optional flags) to a new name. usage: | diff --git a/commands/docs/all.md b/commands/docs/all.md index 993074a8489..d0ab69f2b9a 100644 --- a/commands/docs/all.md +++ b/commands/docs/all.md @@ -2,7 +2,7 @@ title: all categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Test if every element of the input fulfills a predicate expression. usage: | diff --git a/commands/docs/ansi.md b/commands/docs/ansi.md index 43c0fdc8640..58c2c1ef01b 100644 --- a/commands/docs/ansi.md +++ b/commands/docs/ansi.md @@ -2,7 +2,7 @@ title: ansi categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Output ANSI codes to change color and style of text. usage: | diff --git a/commands/docs/ansi_gradient.md b/commands/docs/ansi_gradient.md index 2256cb053d8..2093ee2010f 100644 --- a/commands/docs/ansi_gradient.md +++ b/commands/docs/ansi_gradient.md @@ -2,7 +2,7 @@ title: ansi gradient categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Add a color gradient (using ANSI color codes) to the given string. usage: | diff --git a/commands/docs/ansi_link.md b/commands/docs/ansi_link.md index a95d214f98d..6f7b6e65bfa 100644 --- a/commands/docs/ansi_link.md +++ b/commands/docs/ansi_link.md @@ -2,7 +2,7 @@ title: ansi link categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Add a link (using OSC 8 escape sequence) to the given string. usage: | diff --git a/commands/docs/ansi_strip.md b/commands/docs/ansi_strip.md index 3b4b9e2690e..b46d68d5006 100644 --- a/commands/docs/ansi_strip.md +++ b/commands/docs/ansi_strip.md @@ -2,7 +2,7 @@ title: ansi strip categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Strip ANSI escape sequences from a string. usage: | diff --git a/commands/docs/any.md b/commands/docs/any.md index bf1c678d623..c6d1eabbde7 100644 --- a/commands/docs/any.md +++ b/commands/docs/any.md @@ -2,7 +2,7 @@ title: any categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Tests if any element of the input fulfills a predicate expression. usage: | diff --git a/commands/docs/append.md b/commands/docs/append.md index b32c52c6066..bffc303d928 100644 --- a/commands/docs/append.md +++ b/commands/docs/append.md @@ -2,7 +2,7 @@ title: append categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Append any number of rows to a table. usage: | diff --git a/commands/docs/ast.md b/commands/docs/ast.md index 40af81cc5a7..e9fb5be7c8f 100644 --- a/commands/docs/ast.md +++ b/commands/docs/ast.md @@ -2,7 +2,7 @@ title: ast categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Print the abstract syntax tree (ast) for a pipeline. usage: | @@ -20,8 +20,9 @@ usage: | ## Flags - - `--json, -j`: serialize to json - - `--minify, -m`: minify the nuon or json output + - `--json, -j`: Serialize to json + - `--minify, -m`: Minify the nuon or json output + - `--flatten, -f`: An easier to read version of the ast ## Parameters @@ -30,9 +31,9 @@ usage: | ## Input/output types: -| input | output | -| ------ | ------ | -| string | record | +| input | output | +| ------- | ------ | +| nothing | table | ## Examples @@ -65,3 +66,57 @@ Print the ast of a pipeline with an error, as json, minified > ast 'for x in 1..10 { echo $x ' --json --minify ``` + +Print the ast of a string flattened +```nu +> ast "'hello'" --flatten +╭───┬─────────┬──────────────┬───────────────╮ +│ # │ content │ shape │ span │ +├───┼─────────┼──────────────┼───────────────┤ +│ 0 │ 'hello' │ shape_string │ ╭───────┬───╮ │ +│ │ │ │ │ start │ 0 │ │ +│ │ │ │ │ end │ 7 │ │ +│ │ │ │ ╰───────┴───╯ │ +╰───┴─────────┴──────────────┴───────────────╯ + +``` + +Print the ast of a string flattened, as json, minified +```nu +> ast "'hello'" --flatten --json --minify +[{"content":"'hello'","shape":"shape_string","span":{"start":0,"end":7}}] +``` + +Print the ast of a pipeline flattened +```nu +> ast 'ls | sort-by type name -i' --flatten +╭───┬─────────┬────────────────────┬────────────────╮ +│ # │ content │ shape │ span │ +├───┼─────────┼────────────────────┼────────────────┤ +│ 0 │ ls │ shape_external │ ╭───────┬───╮ │ +│ │ │ │ │ start │ 0 │ │ +│ │ │ │ │ end │ 2 │ │ +│ │ │ │ ╰───────┴───╯ │ +│ 1 │ | │ shape_pipe │ ╭───────┬───╮ │ +│ │ │ │ │ start │ 3 │ │ +│ │ │ │ │ end │ 4 │ │ +│ │ │ │ ╰───────┴───╯ │ +│ 2 │ sort-by │ shape_internalcall │ ╭───────┬────╮ │ +│ │ │ │ │ start │ 5 │ │ +│ │ │ │ │ end │ 12 │ │ +│ │ │ │ ╰───────┴────╯ │ +│ 3 │ type │ shape_string │ ╭───────┬────╮ │ +│ │ │ │ │ start │ 13 │ │ +│ │ │ │ │ end │ 17 │ │ +│ │ │ │ ╰───────┴────╯ │ +│ 4 │ name │ shape_string │ ╭───────┬────╮ │ +│ │ │ │ │ start │ 18 │ │ +│ │ │ │ │ end │ 22 │ │ +│ │ │ │ ╰───────┴────╯ │ +│ 5 │ -i │ shape_flag │ ╭───────┬────╮ │ +│ │ │ │ │ start │ 23 │ │ +│ │ │ │ │ end │ 25 │ │ +│ │ │ │ ╰───────┴────╯ │ +╰───┴─────────┴────────────────────┴────────────────╯ + +``` diff --git a/commands/docs/banner.md b/commands/docs/banner.md index 6dcd3b91415..b54a6e11850 100644 --- a/commands/docs/banner.md +++ b/commands/docs/banner.md @@ -2,7 +2,7 @@ title: banner categories: | default -version: 0.100.0 +version: 0.101.0 default: | Print a banner for nushell with information about the project usage: | diff --git a/commands/docs/bits.md b/commands/docs/bits.md index f3469586383..aa2240eb104 100644 --- a/commands/docs/bits.md +++ b/commands/docs/bits.md @@ -2,7 +2,7 @@ title: bits categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Various commands for working with bits. usage: | diff --git a/commands/docs/bits_and.md b/commands/docs/bits_and.md index 1439677d720..b5e0ba2dcca 100644 --- a/commands/docs/bits_and.md +++ b/commands/docs/bits_and.md @@ -2,7 +2,7 @@ title: bits and categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Performs bitwise and for ints or binary values. usage: | diff --git a/commands/docs/bits_not.md b/commands/docs/bits_not.md index a831d9c6787..bd757353683 100644 --- a/commands/docs/bits_not.md +++ b/commands/docs/bits_not.md @@ -2,7 +2,7 @@ title: bits not categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Performs logical negation on each bit. usage: | diff --git a/commands/docs/bits_or.md b/commands/docs/bits_or.md index eb1cc9e3422..e18e24e2d95 100644 --- a/commands/docs/bits_or.md +++ b/commands/docs/bits_or.md @@ -2,7 +2,7 @@ title: bits or categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Performs bitwise or for ints or binary values. usage: | diff --git a/commands/docs/bits_rol.md b/commands/docs/bits_rol.md index 415f923260e..d843612d59b 100644 --- a/commands/docs/bits_rol.md +++ b/commands/docs/bits_rol.md @@ -2,7 +2,7 @@ title: bits rol categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Bitwise rotate left for ints or binary values. usage: | diff --git a/commands/docs/bits_ror.md b/commands/docs/bits_ror.md index e0eeb0af15f..f404fd08603 100644 --- a/commands/docs/bits_ror.md +++ b/commands/docs/bits_ror.md @@ -2,7 +2,7 @@ title: bits ror categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Bitwise rotate right for ints or binary values. usage: | diff --git a/commands/docs/bits_shl.md b/commands/docs/bits_shl.md index da16546e0f1..4d1b86c4693 100644 --- a/commands/docs/bits_shl.md +++ b/commands/docs/bits_shl.md @@ -2,7 +2,7 @@ title: bits shl categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Bitwise shift left for ints or binary values. usage: | diff --git a/commands/docs/bits_shr.md b/commands/docs/bits_shr.md index 4321e5ba3e1..1d9d5763003 100644 --- a/commands/docs/bits_shr.md +++ b/commands/docs/bits_shr.md @@ -2,7 +2,7 @@ title: bits shr categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Bitwise shift right for ints or binary values. usage: | diff --git a/commands/docs/bits_xor.md b/commands/docs/bits_xor.md index 42016a3494f..2f826d0091a 100644 --- a/commands/docs/bits_xor.md +++ b/commands/docs/bits_xor.md @@ -2,7 +2,7 @@ title: bits xor categories: | bits -version: 0.100.0 +version: 0.101.0 bits: | Performs bitwise xor for ints or binary values. usage: | diff --git a/commands/docs/break.md b/commands/docs/break.md index d630e2054c9..6e062109b04 100644 --- a/commands/docs/break.md +++ b/commands/docs/break.md @@ -2,7 +2,7 @@ title: break categories: | core -version: 0.100.0 +version: 0.101.0 core: | Break a loop. usage: | diff --git a/commands/docs/bytes.md b/commands/docs/bytes.md index ebd408ea84b..7dd6e90bb81 100644 --- a/commands/docs/bytes.md +++ b/commands/docs/bytes.md @@ -2,7 +2,7 @@ title: bytes categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Various commands for working with byte data. usage: | diff --git a/commands/docs/bytes_add.md b/commands/docs/bytes_add.md index f89d7f3f824..f46f6a4f347 100644 --- a/commands/docs/bytes_add.md +++ b/commands/docs/bytes_add.md @@ -2,7 +2,7 @@ title: bytes add categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Add specified bytes to the input. usage: | diff --git a/commands/docs/bytes_at.md b/commands/docs/bytes_at.md index 868980a3762..dba6cf4e297 100644 --- a/commands/docs/bytes_at.md +++ b/commands/docs/bytes_at.md @@ -2,7 +2,7 @@ title: bytes at categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Get bytes defined by a range. usage: | diff --git a/commands/docs/bytes_build.md b/commands/docs/bytes_build.md index 8b8c926cf0d..ced3e56713d 100644 --- a/commands/docs/bytes_build.md +++ b/commands/docs/bytes_build.md @@ -2,7 +2,7 @@ title: bytes build categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Create bytes from the arguments. usage: | diff --git a/commands/docs/bytes_collect.md b/commands/docs/bytes_collect.md index ddfb4d97455..f1f20656e82 100644 --- a/commands/docs/bytes_collect.md +++ b/commands/docs/bytes_collect.md @@ -2,7 +2,7 @@ title: bytes collect categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Concatenate multiple binary into a single binary, with an optional separator between each. usage: | diff --git a/commands/docs/bytes_ends-with.md b/commands/docs/bytes_ends-with.md index 98c945d7160..01edfcbd9a4 100644 --- a/commands/docs/bytes_ends-with.md +++ b/commands/docs/bytes_ends-with.md @@ -2,7 +2,7 @@ title: bytes ends-with categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Check if bytes ends with a pattern. usage: | diff --git a/commands/docs/bytes_index-of.md b/commands/docs/bytes_index-of.md index 34ba4e41777..5c2f7641729 100644 --- a/commands/docs/bytes_index-of.md +++ b/commands/docs/bytes_index-of.md @@ -2,7 +2,7 @@ title: bytes index-of categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Returns start index of first occurrence of pattern in bytes, or -1 if no match. usage: | diff --git a/commands/docs/bytes_length.md b/commands/docs/bytes_length.md index 13bf8eae557..c952be7a7e1 100644 --- a/commands/docs/bytes_length.md +++ b/commands/docs/bytes_length.md @@ -2,7 +2,7 @@ title: bytes length categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Output the length of any bytes in the pipeline. usage: | diff --git a/commands/docs/bytes_remove.md b/commands/docs/bytes_remove.md index f25f5ad88fa..94c2a490e1c 100644 --- a/commands/docs/bytes_remove.md +++ b/commands/docs/bytes_remove.md @@ -2,7 +2,7 @@ title: bytes remove categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Remove bytes. usage: | diff --git a/commands/docs/bytes_replace.md b/commands/docs/bytes_replace.md index 080fef8ffef..9dce8d457be 100644 --- a/commands/docs/bytes_replace.md +++ b/commands/docs/bytes_replace.md @@ -2,7 +2,7 @@ title: bytes replace categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Find and replace binary. usage: | diff --git a/commands/docs/bytes_reverse.md b/commands/docs/bytes_reverse.md index 40efe4b0e63..f27cbd6e316 100644 --- a/commands/docs/bytes_reverse.md +++ b/commands/docs/bytes_reverse.md @@ -2,7 +2,7 @@ title: bytes reverse categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Reverse the bytes in the pipeline. usage: | diff --git a/commands/docs/bytes_starts-with.md b/commands/docs/bytes_starts-with.md index f0f74925239..3a519ddf3b6 100644 --- a/commands/docs/bytes_starts-with.md +++ b/commands/docs/bytes_starts-with.md @@ -2,7 +2,7 @@ title: bytes starts-with categories: | bytes -version: 0.100.0 +version: 0.101.0 bytes: | Check if bytes starts with a pattern. usage: | diff --git a/commands/docs/cal.md b/commands/docs/cal.md index 13621891594..f9aaf2d233e 100644 --- a/commands/docs/cal.md +++ b/commands/docs/cal.md @@ -2,7 +2,7 @@ title: cal categories: | generators -version: 0.100.0 +version: 0.101.0 generators: | Display a calendar. usage: | diff --git a/commands/docs/cd.md b/commands/docs/cd.md index 34e3c44d3e4..4058d201b2e 100644 --- a/commands/docs/cd.md +++ b/commands/docs/cd.md @@ -2,7 +2,7 @@ title: cd categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Change directory. usage: | diff --git a/commands/docs/char.md b/commands/docs/char.md index 865510e4db6..c70fb1ff223 100644 --- a/commands/docs/char.md +++ b/commands/docs/char.md @@ -2,7 +2,7 @@ title: char categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Output special characters (e.g., 'newline'). usage: | diff --git a/commands/docs/chunk-by.md b/commands/docs/chunk-by.md new file mode 100644 index 00000000000..ef387833504 --- /dev/null +++ b/commands/docs/chunk-by.md @@ -0,0 +1,100 @@ +--- +title: chunk-by +categories: | + filters +version: 0.101.0 +filters: | + Divides a sequence into sub-sequences based on a closure. +usage: | + Divides a sequence into sub-sequences based on a closure. +--- + + +# `chunk-by` for [filters](/commands/categories/filters.md) + +
Divides a sequence into sub-sequences based on a closure.
+ +## Signature + +```> chunk-by {flags} (closure)``` + +## Parameters + + - `closure`: The closure to run. + + +## Input/output types: + +| input | output | +| --------- | --------------- | +| list\ | list\\> | +| range | list\\> | +## Examples + +Chunk data into runs of larger than zero or not. +```nu +> [1, 3, -2, -2, 0, 1, 2] | chunk-by {|it| $it >= 0 } +╭───┬────────────╮ +│ 0 │ ╭───┬───╮ │ +│ │ │ 0 │ 1 │ │ +│ │ │ 1 │ 3 │ │ +│ │ ╰───┴───╯ │ +│ 1 │ ╭───┬────╮ │ +│ │ │ 0 │ -2 │ │ +│ │ │ 1 │ -2 │ │ +│ │ ╰───┴────╯ │ +│ 2 │ ╭───┬───╮ │ +│ │ │ 0 │ 0 │ │ +│ │ │ 1 │ 1 │ │ +│ │ │ 2 │ 2 │ │ +│ │ ╰───┴───╯ │ +╰───┴────────────╯ + +``` + +Identify repetitions in a string +```nu +> [a b b c c c] | chunk-by { |it| $it } +╭───┬───────────╮ +│ 0 │ ╭───┬───╮ │ +│ │ │ 0 │ a │ │ +│ │ ╰───┴───╯ │ +│ 1 │ ╭───┬───╮ │ +│ │ │ 0 │ b │ │ +│ │ │ 1 │ b │ │ +│ │ ╰───┴───╯ │ +│ 2 │ ╭───┬───╮ │ +│ │ │ 0 │ c │ │ +│ │ │ 1 │ c │ │ +│ │ │ 2 │ c │ │ +│ │ ╰───┴───╯ │ +╰───┴───────────╯ + +``` + +Chunk values of range by predicate +```nu +> (0..8) | chunk-by { |it| $it // 3 } +╭───┬───────────╮ +│ 0 │ ╭───┬───╮ │ +│ │ │ 0 │ 0 │ │ +│ │ │ 1 │ 1 │ │ +│ │ │ 2 │ 2 │ │ +│ │ ╰───┴───╯ │ +│ 1 │ ╭───┬───╮ │ +│ │ │ 0 │ 3 │ │ +│ │ │ 1 │ 4 │ │ +│ │ │ 2 │ 5 │ │ +│ │ ╰───┴───╯ │ +│ 2 │ ╭───┬───╮ │ +│ │ │ 0 │ 6 │ │ +│ │ │ 1 │ 7 │ │ +│ │ │ 2 │ 8 │ │ +│ │ ╰───┴───╯ │ +╰───┴───────────╯ + +``` + +## Notes +chunk-by applies the given closure to each value of the input list, and groups +consecutive elements that share the same closure result value into lists. \ No newline at end of file diff --git a/commands/docs/chunks.md b/commands/docs/chunks.md index 6ab137c24e3..b1687781991 100644 --- a/commands/docs/chunks.md +++ b/commands/docs/chunks.md @@ -2,7 +2,7 @@ title: chunks categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Divide a list or table into chunks of `chunk_size`. usage: | diff --git a/commands/docs/clear.md b/commands/docs/clear.md index eb5e9a7aa92..1d4f612820f 100644 --- a/commands/docs/clear.md +++ b/commands/docs/clear.md @@ -2,7 +2,7 @@ title: clear categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Clear the terminal. usage: | diff --git a/commands/docs/collect.md b/commands/docs/collect.md index 0a819b37bc3..17f2f8cc483 100644 --- a/commands/docs/collect.md +++ b/commands/docs/collect.md @@ -2,7 +2,7 @@ title: collect categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Collect a stream into a value. usage: | diff --git a/commands/docs/columns.md b/commands/docs/columns.md index 421b97bc866..bdac3d5b6c0 100644 --- a/commands/docs/columns.md +++ b/commands/docs/columns.md @@ -2,7 +2,7 @@ title: columns categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Given a record or table, produce a list of its columns' names. usage: | diff --git a/commands/docs/commandline.md b/commands/docs/commandline.md index 78b905be71e..f090105e7c6 100644 --- a/commands/docs/commandline.md +++ b/commands/docs/commandline.md @@ -2,7 +2,7 @@ title: commandline categories: | core -version: 0.100.0 +version: 0.101.0 core: | View the current command line input buffer. usage: | diff --git a/commands/docs/commandline_edit.md b/commands/docs/commandline_edit.md index 4b6af4e6c03..96799c21ce9 100644 --- a/commands/docs/commandline_edit.md +++ b/commands/docs/commandline_edit.md @@ -2,7 +2,7 @@ title: commandline edit categories: | core -version: 0.100.0 +version: 0.101.0 core: | Modify the current command line input buffer. usage: | diff --git a/commands/docs/commandline_get-cursor.md b/commands/docs/commandline_get-cursor.md index ec034b46ae3..e7338f8df14 100644 --- a/commands/docs/commandline_get-cursor.md +++ b/commands/docs/commandline_get-cursor.md @@ -2,7 +2,7 @@ title: commandline get-cursor categories: | core -version: 0.100.0 +version: 0.101.0 core: | Get the current cursor position. usage: | diff --git a/commands/docs/commandline_set-cursor.md b/commands/docs/commandline_set-cursor.md index 79ca112d031..5138904a249 100644 --- a/commands/docs/commandline_set-cursor.md +++ b/commands/docs/commandline_set-cursor.md @@ -2,7 +2,7 @@ title: commandline set-cursor categories: | core -version: 0.100.0 +version: 0.101.0 core: | Set the current cursor position. usage: | diff --git a/commands/docs/compact.md b/commands/docs/compact.md index fc724340cb6..025d7089614 100644 --- a/commands/docs/compact.md +++ b/commands/docs/compact.md @@ -2,7 +2,7 @@ title: compact categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Creates a table with non-empty rows. usage: | diff --git a/commands/docs/complete.md b/commands/docs/complete.md index e9803fe1a22..dd0939952de 100644 --- a/commands/docs/complete.md +++ b/commands/docs/complete.md @@ -2,7 +2,7 @@ title: complete categories: | system -version: 0.100.0 +version: 0.101.0 system: | Capture the outputs and exit code from an external piped in command in a nushell table. usage: | diff --git a/commands/docs/config.md b/commands/docs/config.md index 9723bd9948c..891223287ad 100644 --- a/commands/docs/config.md +++ b/commands/docs/config.md @@ -2,7 +2,7 @@ title: config categories: | env -version: 0.100.0 +version: 0.101.0 env: | Edit nushell configuration files. usage: | @@ -30,8 +30,9 @@ You must use one of the following subcommands. Using this command as-is will onl ## Subcommands: -| name | description | type | -| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| [`config env`](/commands/docs/config_env.md) | Edit nu environment configurations. | built-in | -| [`config nu`](/commands/docs/config_nu.md) | Edit nu configurations. | built-in | -| [`config reset`](/commands/docs/config_reset.md) | Reset nushell environment configurations to default, and saves old config files in the config location as oldconfig.nu and oldenv.nu. | built-in | \ No newline at end of file +| name | description | type | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| [`config env`](/commands/docs/config_env.md) | Edit nu environment configurations. | built-in | +| [`config flatten`](/commands/docs/config_flatten.md) | Show the current configuration in a flattened form. | built-in | +| [`config nu`](/commands/docs/config_nu.md) | Edit nu configurations. | built-in | +| [`config reset`](/commands/docs/config_reset.md) | Reset nushell environment configurations to default, and saves old config files in the config location as oldconfig.nu and oldenv.nu. | built-in | \ No newline at end of file diff --git a/commands/docs/config_env.md b/commands/docs/config_env.md index 702733469c9..aa4f3a7436c 100644 --- a/commands/docs/config_env.md +++ b/commands/docs/config_env.md @@ -2,7 +2,7 @@ title: config env categories: | env -version: 0.100.0 +version: 0.101.0 env: | Edit nu environment configurations. usage: | @@ -20,7 +20,8 @@ usage: | ## Flags - - `--default, -d`: Print default `env.nu` file instead. + - `--default, -d`: Print the internal default `env.nu` file instead. + - `--doc, -s`: Print a commented `env.nu` with documentation instead. ## Input/output types: @@ -31,20 +32,20 @@ usage: | ## Examples -allow user to open and update nu env +open user's env.nu in the default editor ```nu > config env ``` -allow user to print default `env.nu` file +pretty-print a commented `env.nu` that explains common settings ```nu -> config env --default, +> config env --doc | nu-highlight, ``` -allow saving the default `env.nu` locally +pretty-print the internal `env.nu` file which is loaded before the user's environment ```nu -> config env --default | save -f ~/.config/nushell/default_env.nu +> config env --default | nu-highlight, ``` diff --git a/commands/docs/config_flatten.md b/commands/docs/config_flatten.md new file mode 100644 index 00000000000..fc5044f2e23 --- /dev/null +++ b/commands/docs/config_flatten.md @@ -0,0 +1,34 @@ +--- +title: config flatten +categories: | + debug +version: 0.101.0 +debug: | + Show the current configuration in a flattened form. +usage: | + Show the current configuration in a flattened form. +--- + + +# `config flatten` for [debug](/commands/categories/debug.md) + +
Show the current configuration in a flattened form.
+ +## Signature + +```> config flatten {flags} ``` + + +## Input/output types: + +| input | output | +| ------- | ------ | +| nothing | record | + +## Examples + +Show the current configuration in a flattened form +```nu +> config flatten + +``` diff --git a/commands/docs/config_nu.md b/commands/docs/config_nu.md index 7a094149259..4bb092b1c15 100644 --- a/commands/docs/config_nu.md +++ b/commands/docs/config_nu.md @@ -2,7 +2,7 @@ title: config nu categories: | env -version: 0.100.0 +version: 0.101.0 env: | Edit nu configurations. usage: | @@ -20,7 +20,8 @@ usage: | ## Flags - - `--default, -d`: Print default `config.nu` file instead. + - `--default, -d`: Print the internal default `config.nu` file instead. + - `--doc, -s`: Print a commented `config.nu` with documentation instead. ## Input/output types: @@ -31,20 +32,20 @@ usage: | ## Examples -allow user to open and update nu config +open user's config.nu in the default editor ```nu > config nu ``` -allow user to print default `config.nu` file +pretty-print a commented `config.nu` that explains common settings ```nu -> config nu --default, +> config nu --doc | nu-highlight ``` -allow saving the default `config.nu` locally +pretty-print the internal `config.nu` file which is loaded before user's config ```nu -> config nu --default | save -f ~/.config/nushell/default_config.nu +> config nu --default | nu-highlight ``` diff --git a/commands/docs/config_reset.md b/commands/docs/config_reset.md index 2ff16613291..426df0258df 100644 --- a/commands/docs/config_reset.md +++ b/commands/docs/config_reset.md @@ -2,7 +2,7 @@ title: config reset categories: | env -version: 0.100.0 +version: 0.101.0 env: | Reset nushell environment configurations to default, and saves old config files in the config location as oldconfig.nu and oldenv.nu. usage: | diff --git a/commands/docs/const.md b/commands/docs/const.md index 1fbfb874ecd..f83d391d5a3 100644 --- a/commands/docs/const.md +++ b/commands/docs/const.md @@ -2,7 +2,7 @@ title: const categories: | core -version: 0.100.0 +version: 0.101.0 core: | Create a parse-time constant. usage: | diff --git a/commands/docs/continue.md b/commands/docs/continue.md index 632f22db41f..d9f9d56ae1a 100644 --- a/commands/docs/continue.md +++ b/commands/docs/continue.md @@ -2,7 +2,7 @@ title: continue categories: | core -version: 0.100.0 +version: 0.101.0 core: | Continue a loop from the next iteration. usage: | diff --git a/commands/docs/cp.md b/commands/docs/cp.md index c09563fb015..ed40d38b646 100644 --- a/commands/docs/cp.md +++ b/commands/docs/cp.md @@ -2,7 +2,7 @@ title: cp categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Copy files using uutils/coreutils cp. usage: | diff --git a/commands/docs/date.md b/commands/docs/date.md index 021a8faaab5..096af90519a 100644 --- a/commands/docs/date.md +++ b/commands/docs/date.md @@ -2,7 +2,7 @@ title: date categories: | date -version: 0.100.0 +version: 0.101.0 date: | Date-related commands. usage: | diff --git a/commands/docs/date_format.md b/commands/docs/date_format.md index af01cf2bf48..3b35bdda10b 100644 --- a/commands/docs/date_format.md +++ b/commands/docs/date_format.md @@ -2,7 +2,7 @@ title: date format categories: | removed -version: 0.100.0 +version: 0.101.0 removed: | Removed command: use `format date` instead. usage: | diff --git a/commands/docs/date_humanize.md b/commands/docs/date_humanize.md index c4d57acbf59..367fe975384 100644 --- a/commands/docs/date_humanize.md +++ b/commands/docs/date_humanize.md @@ -2,7 +2,7 @@ title: date humanize categories: | date -version: 0.100.0 +version: 0.101.0 date: | Print a 'humanized' format for the date, relative to now. usage: | diff --git a/commands/docs/date_list-timezone.md b/commands/docs/date_list-timezone.md index 91c4c2cccc7..b7118f443aa 100644 --- a/commands/docs/date_list-timezone.md +++ b/commands/docs/date_list-timezone.md @@ -2,7 +2,7 @@ title: date list-timezone categories: | date -version: 0.100.0 +version: 0.101.0 date: | List supported time zones. usage: | diff --git a/commands/docs/date_now.md b/commands/docs/date_now.md index 4fa1063e7d9..666b26bb37c 100644 --- a/commands/docs/date_now.md +++ b/commands/docs/date_now.md @@ -2,7 +2,7 @@ title: date now categories: | date -version: 0.100.0 +version: 0.101.0 date: | Get the current date. usage: | diff --git a/commands/docs/date_to-record.md b/commands/docs/date_to-record.md index 37782090823..7dd9203bfcb 100644 --- a/commands/docs/date_to-record.md +++ b/commands/docs/date_to-record.md @@ -1,16 +1,16 @@ --- title: date to-record categories: | - date -version: 0.100.0 -date: | + deprecated +version: 0.101.0 +deprecated: | Convert the date into a record. usage: | Convert the date into a record. --- -# `date to-record` for [date](/commands/categories/date.md) +# `date to-record` for [deprecated](/commands/categories/deprecated.md)
Convert the date into a record.
diff --git a/commands/docs/date_to-table.md b/commands/docs/date_to-table.md index 342d72af2a5..c2821dde697 100644 --- a/commands/docs/date_to-table.md +++ b/commands/docs/date_to-table.md @@ -1,16 +1,16 @@ --- title: date to-table categories: | - date -version: 0.100.0 -date: | + deprecated +version: 0.101.0 +deprecated: | Convert the date into a structured table. usage: | Convert the date into a structured table. --- -# `date to-table` for [date](/commands/categories/date.md) +# `date to-table` for [deprecated](/commands/categories/deprecated.md)
Convert the date into a structured table.
diff --git a/commands/docs/date_to-timezone.md b/commands/docs/date_to-timezone.md index 16e7a086ccf..9aa8ad7fdfb 100644 --- a/commands/docs/date_to-timezone.md +++ b/commands/docs/date_to-timezone.md @@ -2,7 +2,7 @@ title: date to-timezone categories: | date -version: 0.100.0 +version: 0.101.0 date: | Convert a date to a given time zone. usage: | diff --git a/commands/docs/debug.md b/commands/docs/debug.md index 2aaf312c6d7..c5616045cff 100644 --- a/commands/docs/debug.md +++ b/commands/docs/debug.md @@ -2,7 +2,7 @@ title: debug categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Debug print the value(s) piped in. usage: | diff --git a/commands/docs/debug_info.md b/commands/docs/debug_info.md index cad605f8b85..5bcfb6e9f49 100644 --- a/commands/docs/debug_info.md +++ b/commands/docs/debug_info.md @@ -2,7 +2,7 @@ title: debug info categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | View process memory info. usage: | diff --git a/commands/docs/debug_profile.md b/commands/docs/debug_profile.md index bd8b1448f2f..21597429c56 100644 --- a/commands/docs/debug_profile.md +++ b/commands/docs/debug_profile.md @@ -2,7 +2,7 @@ title: debug profile categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Profile pipeline elements in a closure. usage: | @@ -23,8 +23,6 @@ usage: | - `--spans, -s`: Collect spans of profiled elements - `--expand-source, -e`: Collect full source fragments of profiled elements - `--values, -v`: Collect pipeline element output values - - `--expr, -x`: Collect expression types - - `--instructions, -i`: Collect IR instructions - `--lines, -l`: Collect line numbers - `--max-depth, -m {int}`: How many blocks/closures deep to step into (default 2) @@ -54,36 +52,51 @@ Profile config evaluation with more granularity ``` ## Notes -The profiler profiles every evaluated pipeline element inside a closure, stepping into all +The profiler profiles every evaluated instruction inside a closure, stepping into all commands calls and other blocks/closures. The output can be heavily customized. By default, the following columns are included: -- depth : Depth of the pipeline element. Each entered block adds one level of depth. How many +- depth : Depth of the instruction. Each entered block adds one level of depth. How many blocks deep to step into is controlled with the --max-depth option. -- id : ID of the pipeline element -- parent_id : ID of the parent element -- source : Source code of the pipeline element. If the element has multiple lines, only the - first line is used and `...` is appended to the end. Full source code can be shown - with the --expand-source flag. -- duration_ms : How long it took to run the pipeline element in milliseconds. -- (optional) span : Span of the element. Can be viewed via the `view span` command. Enabled with - the --spans flag. -- (optional) expr : The type of expression of the pipeline element. Enabled with the --expr flag. -- (optional) output : The output value of the pipeline element. Enabled with the --values flag. - -To illustrate the depth and IDs, consider `debug profile { if true { echo 'spam' } }`. There are -three pipeline elements: - -depth id parent_id - 0 0 0 debug profile { do { if true { 'spam' } } } - 1 1 0 if true { 'spam' } - 2 2 1 'spam' +- id : ID of the instruction +- parent_id : ID of the instruction that created the parent scope +- source : Source code that generated the instruction. If the source code has multiple lines, + only the first line is used and `...` is appended to the end. Full source code can + be shown with the --expand-source flag. +- pc : The index of the instruction within the block. +- instruction : The pretty printed instruction being evaluated. +- duration_ms : How long it took to run the instruction in milliseconds. +- (optional) span : Span associated with the instruction. Can be viewed via the `view span` + command. Enabled with the --spans flag. +- (optional) output : The output value of the instruction. Enabled with the --values flag. + +To illustrate the depth and IDs, consider `debug profile { do { if true { echo 'spam' } } }`. A unique ID is generated each time an instruction is executed, and there are two levels of depth: + +``` +depth id parent_id source pc instruction + 0 0 0 debug profile { do { if true { 'spam' } } } 0 + 1 1 0 { if true { 'spam' } } 0 load-literal %1, closure(2164) + 1 2 0 { if true { 'spam' } } 1 push-positional %1 + 1 3 0 { do { if true { 'spam' } } } 2 redirect-out caller + 1 4 0 { do { if true { 'spam' } } } 3 redirect-err caller + 1 5 0 do 4 call decl 7 "do", %0 + 2 6 5 true 0 load-literal %1, bool(true) + 2 7 5 if 1 not %1 + 2 8 5 if 2 branch-if %1, 5 + 2 9 5 'spam' 3 load-literal %0, string("spam") + 2 10 5 if 4 jump 6 + 2 11 5 { if true { 'spam' } } 6 return %0 + 1 12 0 { do { if true { 'spam' } } } 5 return %0 +``` Each block entered increments depth by 1 and each block left decrements it by one. This way you can -control the profiling granularity. Passing --max-depth=1 to the above would stop at -`if true { 'spam' }`. The id is used to identify each element. The parent_id tells you that 'spam' -was spawned from `if true { 'spam' }` which was spawned from the root `debug profile { ... }`. +control the profiling granularity. Passing --max-depth=1 to the above would stop inside the `do` +at `if true { 'spam' }`. The id is used to identify each element. The parent_id tells you that the +instructions inside the block are being executed because of `do` (5), which in turn was spawned from +the root `debug profile { ... }`. + +For a better understanding of how instructions map to source code, see the `view ir` command. -Note: In some cases, the ordering of piepeline elements might not be intuitive. For example, +Note: In some cases, the ordering of pipeline elements might not be intuitive. For example, `[ a bb cc ] | each { $in | str length }` involves some implicit collects and lazy evaluation confusing the id/parent_id hierarchy. The --expr flag is helpful for investigating these issues. \ No newline at end of file diff --git a/commands/docs/decode.md b/commands/docs/decode.md index 63ddf56eed6..86be670b732 100644 --- a/commands/docs/decode.md +++ b/commands/docs/decode.md @@ -2,7 +2,7 @@ title: decode categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Decode bytes into a string. usage: | diff --git a/commands/docs/decode_base32.md b/commands/docs/decode_base32.md index b7b78e90283..4420c1232b6 100644 --- a/commands/docs/decode_base32.md +++ b/commands/docs/decode_base32.md @@ -2,7 +2,7 @@ title: decode base32 categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Decode a Base32 value. usage: | diff --git a/commands/docs/decode_base32hex.md b/commands/docs/decode_base32hex.md index 5acb5a1793b..ad2d13d7b16 100644 --- a/commands/docs/decode_base32hex.md +++ b/commands/docs/decode_base32hex.md @@ -2,7 +2,7 @@ title: decode base32hex categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Encode a base32hex value. usage: | diff --git a/commands/docs/decode_base64.md b/commands/docs/decode_base64.md index 527ef3e20ac..aff61e69d0b 100644 --- a/commands/docs/decode_base64.md +++ b/commands/docs/decode_base64.md @@ -2,7 +2,7 @@ title: decode base64 categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Decode a Base64 value. usage: | diff --git a/commands/docs/decode_hex.md b/commands/docs/decode_hex.md index 437c911da72..a7c08c83dbe 100644 --- a/commands/docs/decode_hex.md +++ b/commands/docs/decode_hex.md @@ -2,7 +2,7 @@ title: decode hex categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Hex decode a value. usage: | diff --git a/commands/docs/def.md b/commands/docs/def.md index c7a31648101..1f4096bd64a 100644 --- a/commands/docs/def.md +++ b/commands/docs/def.md @@ -2,7 +2,7 @@ title: def categories: | core -version: 0.100.0 +version: 0.101.0 core: | Define a custom command. usage: | diff --git a/commands/docs/default.md b/commands/docs/default.md index 01ee90aef65..1f0090e6f37 100644 --- a/commands/docs/default.md +++ b/commands/docs/default.md @@ -2,7 +2,7 @@ title: default categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Sets a default value if a row's column is missing or null. usage: | diff --git a/commands/docs/describe.md b/commands/docs/describe.md index a2f297bcb96..a617a93bc52 100644 --- a/commands/docs/describe.md +++ b/commands/docs/describe.md @@ -2,7 +2,7 @@ title: describe categories: | core -version: 0.100.0 +version: 0.101.0 core: | Describe the type and structure of the value(s) piped in. usage: | diff --git a/commands/docs/detect_columns.md b/commands/docs/detect_columns.md index 9aed04aa6b9..529bda3a18e 100644 --- a/commands/docs/detect_columns.md +++ b/commands/docs/detect_columns.md @@ -2,7 +2,7 @@ title: detect columns categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Attempt to automatically split text into multiple columns. usage: | diff --git a/commands/docs/do.md b/commands/docs/do.md index cf4303b46fa..1ee8caa8cd8 100644 --- a/commands/docs/do.md +++ b/commands/docs/do.md @@ -2,7 +2,7 @@ title: do categories: | core -version: 0.100.0 +version: 0.101.0 core: | Run a closure, providing it with the pipeline input. usage: | @@ -58,18 +58,6 @@ Run the closure and ignore both shell and external program errors ``` -Run the closure and ignore shell errors -```nu -> do --ignore-shell-errors { thisisnotarealcommand } - -``` - -Run the closure and ignore external program errors -```nu -> do --ignore-program-errors { nu --commands 'exit 1' }; echo "I'll still run" - -``` - Abort the pipeline if a program returns a non-zero exit code ```nu > do --capture-errors { nu --commands 'exit 1' } | myscarycommand diff --git a/commands/docs/drop.md b/commands/docs/drop.md index f6eb534f7c2..981e33a0223 100644 --- a/commands/docs/drop.md +++ b/commands/docs/drop.md @@ -2,7 +2,7 @@ title: drop categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Remove items/rows from the end of the input list/table. Counterpart of `skip`. Opposite of `last`. usage: | diff --git a/commands/docs/drop_column.md b/commands/docs/drop_column.md index 17b9f3ad7e9..2d3a5045715 100644 --- a/commands/docs/drop_column.md +++ b/commands/docs/drop_column.md @@ -2,7 +2,7 @@ title: drop column categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Remove N columns at the right-hand end of the input table. To remove columns by name, use `reject`. usage: | diff --git a/commands/docs/drop_nth.md b/commands/docs/drop_nth.md index 8bbde9d7883..28f1bc9f6f0 100644 --- a/commands/docs/drop_nth.md +++ b/commands/docs/drop_nth.md @@ -2,7 +2,7 @@ title: drop nth categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Drop the selected rows. usage: | diff --git a/commands/docs/du.md b/commands/docs/du.md index 6a7cdea7ed7..3fa7438f081 100644 --- a/commands/docs/du.md +++ b/commands/docs/du.md @@ -2,7 +2,7 @@ title: du categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Find disk usage sizes of specified items. usage: | @@ -20,8 +20,8 @@ usage: | ## Flags - - `--all, -a`: Output file sizes as well as directory sizes - `--deref, -r`: Dereference symlinks to their targets for size + - `--long, -l`: Get underlying directories and files for each entry - `--exclude, -x {glob}`: Exclude these file names - `--max-depth, -d {int}`: Directory recursion limit - `--min-size, -m {int}`: Exclude files below this size diff --git a/commands/docs/each.md b/commands/docs/each.md index c9ee7a7aacf..dfc55f71134 100644 --- a/commands/docs/each.md +++ b/commands/docs/each.md @@ -2,7 +2,7 @@ title: each categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Run a closure on each row of the input list, creating a new list with the results. usage: | diff --git a/commands/docs/each_while.md b/commands/docs/each_while.md index cbab4cbf3ec..cbdd7fc4550 100644 --- a/commands/docs/each_while.md +++ b/commands/docs/each_while.md @@ -2,7 +2,7 @@ title: each while categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Run a closure on each row of the input list until a null is found, then create a new list with the results. usage: | diff --git a/commands/docs/echo.md b/commands/docs/echo.md index a910a94e4d4..5fc6273df9d 100644 --- a/commands/docs/echo.md +++ b/commands/docs/echo.md @@ -2,7 +2,7 @@ title: echo categories: | core -version: 0.100.0 +version: 0.101.0 core: | Returns its arguments, ignoring the piped-in value. usage: | diff --git a/commands/docs/encode.md b/commands/docs/encode.md index 643067a30f0..433d1b302b3 100644 --- a/commands/docs/encode.md +++ b/commands/docs/encode.md @@ -2,7 +2,7 @@ title: encode categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Encode a string into bytes. usage: | diff --git a/commands/docs/encode_base32.md b/commands/docs/encode_base32.md index d848b53b711..9c756eefd05 100644 --- a/commands/docs/encode_base32.md +++ b/commands/docs/encode_base32.md @@ -2,7 +2,7 @@ title: encode base32 categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Encode a string or binary value using Base32. usage: | diff --git a/commands/docs/encode_base32hex.md b/commands/docs/encode_base32hex.md index 1cc0ea90a0b..1c4f17534e1 100644 --- a/commands/docs/encode_base32hex.md +++ b/commands/docs/encode_base32hex.md @@ -2,7 +2,7 @@ title: encode base32hex categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Encode a binary value or a string using base32hex. usage: | diff --git a/commands/docs/encode_base64.md b/commands/docs/encode_base64.md index 81950becce4..0dd9615bfa9 100644 --- a/commands/docs/encode_base64.md +++ b/commands/docs/encode_base64.md @@ -2,7 +2,7 @@ title: encode base64 categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Encode a string or binary value using Base64. usage: | diff --git a/commands/docs/encode_hex.md b/commands/docs/encode_hex.md index 5c06c5586cc..db14dbefade 100644 --- a/commands/docs/encode_hex.md +++ b/commands/docs/encode_hex.md @@ -2,7 +2,7 @@ title: encode hex categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Hex encode a binary value or a string. usage: | diff --git a/commands/docs/enumerate.md b/commands/docs/enumerate.md index 7ee7791b565..68594e84275 100644 --- a/commands/docs/enumerate.md +++ b/commands/docs/enumerate.md @@ -2,7 +2,7 @@ title: enumerate categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Enumerate the elements in a stream. usage: | diff --git a/commands/docs/error_make.md b/commands/docs/error_make.md index 7f54558377c..5cfb1141365 100644 --- a/commands/docs/error_make.md +++ b/commands/docs/error_make.md @@ -2,7 +2,7 @@ title: error make categories: | core -version: 0.100.0 +version: 0.101.0 core: | Create an error. usage: | diff --git a/commands/docs/every.md b/commands/docs/every.md index c12ffb335b0..ad3e5eff424 100644 --- a/commands/docs/every.md +++ b/commands/docs/every.md @@ -2,7 +2,7 @@ title: every categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Show (or skip) every n-th row, starting from the first one. usage: | diff --git a/commands/docs/exec.md b/commands/docs/exec.md index b67c4fbc0cf..867e1a5d1a7 100644 --- a/commands/docs/exec.md +++ b/commands/docs/exec.md @@ -2,7 +2,7 @@ title: exec categories: | system -version: 0.100.0 +version: 0.101.0 system: | Execute a command, replacing or exiting the current process, depending on platform. usage: | diff --git a/commands/docs/exit.md b/commands/docs/exit.md index 28175f5106f..77bd8969734 100644 --- a/commands/docs/exit.md +++ b/commands/docs/exit.md @@ -2,7 +2,7 @@ title: exit categories: | shells -version: 0.100.0 +version: 0.101.0 shells: | Exit Nu. usage: | diff --git a/commands/docs/explain.md b/commands/docs/explain.md index 8e44289597b..98123679999 100644 --- a/commands/docs/explain.md +++ b/commands/docs/explain.md @@ -2,7 +2,7 @@ title: explain categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Explain closure contents. usage: | diff --git a/commands/docs/explore.md b/commands/docs/explore.md index 04ae758c730..a30179479ae 100644 --- a/commands/docs/explore.md +++ b/commands/docs/explore.md @@ -2,7 +2,7 @@ title: explore categories: | viewers -version: 0.100.0 +version: 0.101.0 viewers: | Explore acts as a table pager, just like `less` does for text. usage: | diff --git a/commands/docs/export-env.md b/commands/docs/export-env.md index 92dc1667972..eb0990afbe0 100644 --- a/commands/docs/export-env.md +++ b/commands/docs/export-env.md @@ -2,7 +2,7 @@ title: export-env categories: | env -version: 0.100.0 +version: 0.101.0 env: | Run a block and preserve its environment in a current scope. usage: | diff --git a/commands/docs/export.md b/commands/docs/export.md index 339ce917c54..c139e170978 100644 --- a/commands/docs/export.md +++ b/commands/docs/export.md @@ -2,7 +2,7 @@ title: export categories: | core -version: 0.100.0 +version: 0.101.0 core: | Export definitions or environment variables from a module. usage: | diff --git a/commands/docs/export_alias.md b/commands/docs/export_alias.md index 4ca61793527..a69308229f5 100644 --- a/commands/docs/export_alias.md +++ b/commands/docs/export_alias.md @@ -2,7 +2,7 @@ title: export alias categories: | core -version: 0.100.0 +version: 0.101.0 core: | Alias a command (with optional flags) to a new name and export it from a module. usage: | diff --git a/commands/docs/export_const.md b/commands/docs/export_const.md index 5709aadc08d..427da289eaa 100644 --- a/commands/docs/export_const.md +++ b/commands/docs/export_const.md @@ -2,7 +2,7 @@ title: export const categories: | core -version: 0.100.0 +version: 0.101.0 core: | Use parse-time constant from a module and export them from this module. usage: | diff --git a/commands/docs/export_def.md b/commands/docs/export_def.md index f51ecb981ec..d049b9631b8 100644 --- a/commands/docs/export_def.md +++ b/commands/docs/export_def.md @@ -2,7 +2,7 @@ title: export def categories: | core -version: 0.100.0 +version: 0.101.0 core: | Define a custom command and export it from a module. usage: | diff --git a/commands/docs/export_extern.md b/commands/docs/export_extern.md index 6a2bb3bc60d..34e641b6e48 100644 --- a/commands/docs/export_extern.md +++ b/commands/docs/export_extern.md @@ -2,7 +2,7 @@ title: export extern categories: | core -version: 0.100.0 +version: 0.101.0 core: | Define an extern and export it from a module. usage: | diff --git a/commands/docs/export_module.md b/commands/docs/export_module.md index d05274e680a..8e0c6e29c2e 100644 --- a/commands/docs/export_module.md +++ b/commands/docs/export_module.md @@ -2,7 +2,7 @@ title: export module categories: | core -version: 0.100.0 +version: 0.101.0 core: | Export a custom module from a module. usage: | diff --git a/commands/docs/export_use.md b/commands/docs/export_use.md index b96a62eb805..fce5a1fa523 100644 --- a/commands/docs/export_use.md +++ b/commands/docs/export_use.md @@ -2,7 +2,7 @@ title: export use categories: | core -version: 0.100.0 +version: 0.101.0 core: | Use definitions from a module and export them from this module. usage: | diff --git a/commands/docs/extern.md b/commands/docs/extern.md index 8b811253ddb..7662d01f416 100644 --- a/commands/docs/extern.md +++ b/commands/docs/extern.md @@ -2,7 +2,7 @@ title: extern categories: | core -version: 0.100.0 +version: 0.101.0 core: | Define a signature for an external command. usage: | diff --git a/commands/docs/fill.md b/commands/docs/fill.md index 2c2205a69e0..9cfae812689 100644 --- a/commands/docs/fill.md +++ b/commands/docs/fill.md @@ -2,7 +2,7 @@ title: fill categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Fill and Align. usage: | diff --git a/commands/docs/filter.md b/commands/docs/filter.md index 3863600828a..ae036c29e1b 100644 --- a/commands/docs/filter.md +++ b/commands/docs/filter.md @@ -2,7 +2,7 @@ title: filter categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Filter values based on a predicate closure. usage: | diff --git a/commands/docs/find.md b/commands/docs/find.md index 56ab27dae32..0ad57f710b8 100644 --- a/commands/docs/find.md +++ b/commands/docs/find.md @@ -2,7 +2,7 @@ title: find categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Searches terms in the input. usage: | diff --git a/commands/docs/first.md b/commands/docs/first.md index 1642f3081ec..d0473284b22 100644 --- a/commands/docs/first.md +++ b/commands/docs/first.md @@ -2,7 +2,7 @@ title: first categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Return only the first several rows of the input. Counterpart of `last`. Opposite of `skip`. usage: | diff --git a/commands/docs/flatten.md b/commands/docs/flatten.md index 14d6f998065..a6667bb323e 100644 --- a/commands/docs/flatten.md +++ b/commands/docs/flatten.md @@ -2,7 +2,7 @@ title: flatten categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Flatten the table. usage: | diff --git a/commands/docs/fmt.md b/commands/docs/fmt.md index 089270075bf..9329b9bf617 100644 --- a/commands/docs/fmt.md +++ b/commands/docs/fmt.md @@ -2,7 +2,7 @@ title: fmt categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Format a number. usage: | diff --git a/commands/docs/for.md b/commands/docs/for.md index db3e9bbcb83..f33121ab49b 100644 --- a/commands/docs/for.md +++ b/commands/docs/for.md @@ -2,7 +2,7 @@ title: for categories: | core -version: 0.100.0 +version: 0.101.0 core: | Loop over a range. usage: | diff --git a/commands/docs/format.md b/commands/docs/format.md index 478173d1ccb..fd1244627cc 100644 --- a/commands/docs/format.md +++ b/commands/docs/format.md @@ -2,7 +2,7 @@ title: format categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Various commands for formatting data. usage: | diff --git a/commands/docs/format_date.md b/commands/docs/format_date.md index 2d91a457cb7..5ca26eeec05 100644 --- a/commands/docs/format_date.md +++ b/commands/docs/format_date.md @@ -2,7 +2,7 @@ title: format date categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Format a given date using a format string. usage: | diff --git a/commands/docs/format_duration.md b/commands/docs/format_duration.md index 5d812fad934..192b7821c27 100644 --- a/commands/docs/format_duration.md +++ b/commands/docs/format_duration.md @@ -2,7 +2,7 @@ title: format duration categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Outputs duration with a specified unit of time. usage: | diff --git a/commands/docs/format_filesize.md b/commands/docs/format_filesize.md index 333495e7533..02579dbb3d1 100644 --- a/commands/docs/format_filesize.md +++ b/commands/docs/format_filesize.md @@ -2,7 +2,7 @@ title: format filesize categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Converts a column of filesizes to some specified format. usage: | diff --git a/commands/docs/format_pattern.md b/commands/docs/format_pattern.md index 144cacd360e..1a653e349f0 100644 --- a/commands/docs/format_pattern.md +++ b/commands/docs/format_pattern.md @@ -2,7 +2,7 @@ title: format pattern categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Format columns into a string using a simple pattern. usage: | diff --git a/commands/docs/from.md b/commands/docs/from.md index 060341caac8..e34cabab790 100644 --- a/commands/docs/from.md +++ b/commands/docs/from.md @@ -2,7 +2,7 @@ title: from categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse a string or binary data into structured data. usage: | diff --git a/commands/docs/from_csv.md b/commands/docs/from_csv.md index 2581535eb34..892e585bd7a 100644 --- a/commands/docs/from_csv.md +++ b/commands/docs/from_csv.md @@ -2,7 +2,7 @@ title: from csv categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .csv and create table. usage: | @@ -50,6 +50,22 @@ Convert comma-separated data to a table ``` +Convert comma-separated data to a table, allowing variable number of columns per row +```nu +> "ColA,ColB +1,2 +3,4,5 +6" | from csv --flexible +╭───┬──────┬──────┬─────────╮ +│ # │ ColA │ ColB │ column2 │ +├───┼──────┼──────┼─────────┤ +│ 0 │ 1 │ 2 │ ❎ │ +│ 1 │ 3 │ 4 │ 5 │ +│ 2 │ 6 │ ❎ │ ❎ │ +╰───┴──────┴──────┴─────────╯ + +``` + Convert comma-separated data to a table, ignoring headers ```nu > open data.txt | from csv --noheaders diff --git a/commands/docs/from_eml.md b/commands/docs/from_eml.md index 86fd5ffca33..a8555aee9a6 100644 --- a/commands/docs/from_eml.md +++ b/commands/docs/from_eml.md @@ -2,7 +2,7 @@ title: from eml categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .eml and create record. usage: | diff --git a/commands/docs/from_ics.md b/commands/docs/from_ics.md index 579ae12564b..6736c3480e5 100644 --- a/commands/docs/from_ics.md +++ b/commands/docs/from_ics.md @@ -2,7 +2,7 @@ title: from ics categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .ics and create table. usage: | @@ -38,10 +38,11 @@ Converts ics formatted string to table ```nu > 'BEGIN:VCALENDAR END:VCALENDAR' | from ics -╭───┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────╮ -│ # │ properties │ events │ alarms │ to-Dos │ journals │ free-busys │ timezones │ -├───┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┤ -│ 0 │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ -╰───┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────╯ +╭───┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬───────────╮ +│ # │ properties │ events │ alarms │ to-Dos │ journals │ free-busys │ timezones │ +├───┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼───────────┤ +│ 0 │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 │ +│ │ │ │ │ │ │ │ items] │ +╰───┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴───────────╯ ``` diff --git a/commands/docs/from_ini.md b/commands/docs/from_ini.md index e601c85dc52..f862e6d791a 100644 --- a/commands/docs/from_ini.md +++ b/commands/docs/from_ini.md @@ -2,7 +2,7 @@ title: from ini categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .ini and create table. usage: | diff --git a/commands/docs/from_json.md b/commands/docs/from_json.md index ca4bc24591f..76771e178c7 100644 --- a/commands/docs/from_json.md +++ b/commands/docs/from_json.md @@ -2,7 +2,7 @@ title: from json categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert from json to structured data. usage: | diff --git a/commands/docs/from_msgpack.md b/commands/docs/from_msgpack.md index 5f58a5a0c0a..33122c59cf9 100644 --- a/commands/docs/from_msgpack.md +++ b/commands/docs/from_msgpack.md @@ -2,7 +2,7 @@ title: from msgpack categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert MessagePack data into Nu values. usage: | diff --git a/commands/docs/from_msgpackz.md b/commands/docs/from_msgpackz.md index 43a53a476d4..000070bee98 100644 --- a/commands/docs/from_msgpackz.md +++ b/commands/docs/from_msgpackz.md @@ -2,7 +2,7 @@ title: from msgpackz categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert brotli-compressed MessagePack data into Nu values. usage: | diff --git a/commands/docs/from_nuon.md b/commands/docs/from_nuon.md index 9fbfd98a9fc..ffa7d5d1ae6 100644 --- a/commands/docs/from_nuon.md +++ b/commands/docs/from_nuon.md @@ -2,7 +2,7 @@ title: from nuon categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert from nuon to structured data. usage: | diff --git a/commands/docs/from_ods.md b/commands/docs/from_ods.md index 8f890ad773e..624e11cacd1 100644 --- a/commands/docs/from_ods.md +++ b/commands/docs/from_ods.md @@ -2,7 +2,7 @@ title: from ods categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse OpenDocument Spreadsheet(.ods) data and create table. usage: | diff --git a/commands/docs/from_plist.md b/commands/docs/from_plist.md index 5d68671780f..252cf9713c7 100644 --- a/commands/docs/from_plist.md +++ b/commands/docs/from_plist.md @@ -2,7 +2,7 @@ title: from plist categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert plist to Nushell values usage: | diff --git a/commands/docs/from_ssv.md b/commands/docs/from_ssv.md index 0551715962a..66106c58935 100644 --- a/commands/docs/from_ssv.md +++ b/commands/docs/from_ssv.md @@ -2,7 +2,7 @@ title: from ssv categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as space-separated values and create a table. The default minimum number of spaces counted as a separator is 2. usage: | diff --git a/commands/docs/from_toml.md b/commands/docs/from_toml.md index 141dc9ade1a..5cf95a43687 100644 --- a/commands/docs/from_toml.md +++ b/commands/docs/from_toml.md @@ -2,7 +2,7 @@ title: from toml categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .toml and create record. usage: | diff --git a/commands/docs/from_tsv.md b/commands/docs/from_tsv.md index 67e4cd5fa00..54ca102e91f 100644 --- a/commands/docs/from_tsv.md +++ b/commands/docs/from_tsv.md @@ -2,7 +2,7 @@ title: from tsv categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .tsv and create table. usage: | @@ -49,6 +49,19 @@ Convert tab-separated data to a table ``` +Convert comma-separated data to a table, allowing variable number of columns per row and ignoring headers +```nu +> "value 1 +value 2 description 2" | from tsv --flexible --noheaders +╭───┬─────────┬───────────────╮ +│ # │ column0 │ column1 │ +├───┼─────────┼───────────────┤ +│ 0 │ value 1 │ ❎ │ +│ 1 │ value 2 │ description 2 │ +╰───┴─────────┴───────────────╯ + +``` + Create a tsv file with header columns and open it ```nu > $'c1(char tab)c2(char tab)c3(char nl)1(char tab)2(char tab)3' | save tsv-data | open tsv-data | from tsv diff --git a/commands/docs/from_url.md b/commands/docs/from_url.md index 4e6c19e9728..65daad1d6ee 100644 --- a/commands/docs/from_url.md +++ b/commands/docs/from_url.md @@ -2,7 +2,7 @@ title: from url categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse url-encoded string as a record. usage: | diff --git a/commands/docs/from_vcf.md b/commands/docs/from_vcf.md index a9ca8377f55..8036363b456 100644 --- a/commands/docs/from_vcf.md +++ b/commands/docs/from_vcf.md @@ -2,7 +2,7 @@ title: from vcf categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .vcf and create table. usage: | diff --git a/commands/docs/from_xlsx.md b/commands/docs/from_xlsx.md index 24247f4965d..2bf8b2f0cda 100644 --- a/commands/docs/from_xlsx.md +++ b/commands/docs/from_xlsx.md @@ -2,7 +2,7 @@ title: from xlsx categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse binary Excel(.xlsx) data and create table. usage: | diff --git a/commands/docs/from_xml.md b/commands/docs/from_xml.md index 971cdfca8d0..615e5b1b898 100644 --- a/commands/docs/from_xml.md +++ b/commands/docs/from_xml.md @@ -2,7 +2,7 @@ title: from xml categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .xml and create record. usage: | diff --git a/commands/docs/from_yaml.md b/commands/docs/from_yaml.md index cf985c2a10d..0d9553736db 100644 --- a/commands/docs/from_yaml.md +++ b/commands/docs/from_yaml.md @@ -2,7 +2,7 @@ title: from yaml categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .yaml/.yml and create table. usage: | diff --git a/commands/docs/from_yml.md b/commands/docs/from_yml.md index 2545d95c038..ddabb80c6dd 100644 --- a/commands/docs/from_yml.md +++ b/commands/docs/from_yml.md @@ -2,7 +2,7 @@ title: from yml categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Parse text as .yaml/.yml and create table. usage: | diff --git a/commands/docs/generate.md b/commands/docs/generate.md index 84bdef8fb7b..80f8a02fa76 100644 --- a/commands/docs/generate.md +++ b/commands/docs/generate.md @@ -2,7 +2,7 @@ title: generate categories: | generators -version: 0.100.0 +version: 0.101.0 generators: | Generate a list of values by successively invoking a closure. usage: | diff --git a/commands/docs/get.md b/commands/docs/get.md index b86a38afbc8..bec6b2eb949 100644 --- a/commands/docs/get.md +++ b/commands/docs/get.md @@ -2,7 +2,7 @@ title: get categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Extract data using a cell path. usage: | diff --git a/commands/docs/glob.md b/commands/docs/glob.md index 7c1f6686ec7..4640d8ad17a 100644 --- a/commands/docs/glob.md +++ b/commands/docs/glob.md @@ -2,7 +2,7 @@ title: glob categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Creates a list of files and/or folders based on the glob pattern provided. usage: | diff --git a/commands/docs/grid.md b/commands/docs/grid.md index 2ddb16cd237..be41a206706 100644 --- a/commands/docs/grid.md +++ b/commands/docs/grid.md @@ -2,7 +2,7 @@ title: grid categories: | viewers -version: 0.100.0 +version: 0.101.0 viewers: | Renders the output to a textual terminal grid. usage: | diff --git a/commands/docs/group-by.md b/commands/docs/group-by.md index bf8892fa102..aef6ee9fe38 100644 --- a/commands/docs/group-by.md +++ b/commands/docs/group-by.md @@ -2,7 +2,7 @@ title: group-by categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Splits a list or table into groups, and returns a record containing those groups. usage: | @@ -16,7 +16,7 @@ usage: | ## Signature -```> group-by {flags} (grouper)``` +```> group-by {flags} ...rest``` ## Flags @@ -24,7 +24,7 @@ usage: | ## Parameters - - `grouper`: The path to the column to group on. + - `...rest`: The path to the column to group on. ## Input/output types: @@ -119,6 +119,69 @@ Group bools, whether they are strings or actual bools ╰───────┴───────────────╯ ``` +Group items by multiple columns' values +```nu +> [ + [name, lang, year]; + [andres, rb, "2019"], + [jt, rs, "2019"], + [storm, rs, "2021"] + ] + | group-by lang year +╭────┬─────────────────────────────────────────╮ +│ │ ╭──────┬──────────────────────────────╮ │ +│ rb │ │ │ ╭───┬────────┬──────┬──────╮ │ │ +│ │ │ 2019 │ │ # │ name │ lang │ year │ │ │ +│ │ │ │ ├───┼────────┼──────┼──────┤ │ │ +│ │ │ │ │ 0 │ andres │ rb │ 2019 │ │ │ +│ │ │ │ ╰───┴────────┴──────┴──────╯ │ │ +│ │ ╰──────┴──────────────────────────────╯ │ +│ │ ╭──────┬─────────────────────────────╮ │ +│ rs │ │ │ ╭───┬──────┬──────┬──────╮ │ │ +│ │ │ 2019 │ │ # │ name │ lang │ year │ │ │ +│ │ │ │ ├───┼──────┼──────┼──────┤ │ │ +│ │ │ │ │ 0 │ jt │ rs │ 2019 │ │ │ +│ │ │ │ ╰───┴──────┴──────┴──────╯ │ │ +│ │ │ │ ╭───┬───────┬──────┬──────╮ │ │ +│ │ │ 2021 │ │ # │ name │ lang │ year │ │ │ +│ │ │ │ ├───┼───────┼──────┼──────┤ │ │ +│ │ │ │ │ 0 │ storm │ rs │ 2021 │ │ │ +│ │ │ │ ╰───┴───────┴──────┴──────╯ │ │ +│ │ ╰──────┴─────────────────────────────╯ │ +╰────┴─────────────────────────────────────────╯ +``` + +Group items by multiple columns' values +```nu +> [ + [name, lang, year]; + [andres, rb, "2019"], + [jt, rs, "2019"], + [storm, rs, "2021"] + ] + | group-by lang year --to-table +╭───┬──────┬──────┬──────────────────────────────╮ +│ # │ lang │ year │ items │ +├───┼──────┼──────┼──────────────────────────────┤ +│ 0 │ rb │ 2019 │ ╭───┬────────┬──────┬──────╮ │ +│ │ │ │ │ # │ name │ lang │ year │ │ +│ │ │ │ ├───┼────────┼──────┼──────┤ │ +│ │ │ │ │ 0 │ andres │ rb │ 2019 │ │ +│ │ │ │ ╰───┴────────┴──────┴──────╯ │ +│ 1 │ rs │ 2019 │ ╭───┬──────┬──────┬──────╮ │ +│ │ │ │ │ # │ name │ lang │ year │ │ +│ │ │ │ ├───┼──────┼──────┼──────┤ │ +│ │ │ │ │ 0 │ jt │ rs │ 2019 │ │ +│ │ │ │ ╰───┴──────┴──────┴──────╯ │ +│ 2 │ rs │ 2021 │ ╭───┬───────┬──────┬──────╮ │ +│ │ │ │ │ # │ name │ lang │ year │ │ +│ │ │ │ ├───┼───────┼──────┼──────┤ │ +│ │ │ │ │ 0 │ storm │ rs │ 2021 │ │ +│ │ │ │ ╰───┴───────┴──────┴──────╯ │ +╰───┴──────┴──────┴──────────────────────────────╯ + +``` + ## Notes the group-by command makes some assumptions: - if the input data is not a string, the grouper will convert the key to string but the values will remain in their original format. e.g. with bools, "true" and true would be in the same group (see example). diff --git a/commands/docs/gstat.md b/commands/docs/gstat.md index ac1a47ea74d..6d24c9c3015 100644 --- a/commands/docs/gstat.md +++ b/commands/docs/gstat.md @@ -2,7 +2,7 @@ title: gstat categories: | prompt -version: 0.100.0 +version: 0.101.0 prompt: | Get the git status of a repo usage: | diff --git a/commands/docs/hash.md b/commands/docs/hash.md index 5f77dd5581e..c8d26f84883 100644 --- a/commands/docs/hash.md +++ b/commands/docs/hash.md @@ -2,7 +2,7 @@ title: hash categories: | hash -version: 0.100.0 +version: 0.101.0 hash: | Apply hash function. usage: | diff --git a/commands/docs/hash_md5.md b/commands/docs/hash_md5.md index 4165a47d796..06705ab72a8 100644 --- a/commands/docs/hash_md5.md +++ b/commands/docs/hash_md5.md @@ -2,7 +2,7 @@ title: hash md5 categories: | hash -version: 0.100.0 +version: 0.101.0 hash: | Hash a value using the md5 hash algorithm. usage: | diff --git a/commands/docs/hash_sha256.md b/commands/docs/hash_sha256.md index a59d8bc2760..5c9dadec383 100644 --- a/commands/docs/hash_sha256.md +++ b/commands/docs/hash_sha256.md @@ -2,7 +2,7 @@ title: hash sha256 categories: | hash -version: 0.100.0 +version: 0.101.0 hash: | Hash a value using the sha256 hash algorithm. usage: | diff --git a/commands/docs/headers.md b/commands/docs/headers.md index c8fc61fdb05..21214f9f1fc 100644 --- a/commands/docs/headers.md +++ b/commands/docs/headers.md @@ -2,7 +2,7 @@ title: headers categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Use the first row of the table as column names. usage: | diff --git a/commands/docs/help.md b/commands/docs/help.md index 0d394cd6c1b..632fb33e270 100644 --- a/commands/docs/help.md +++ b/commands/docs/help.md @@ -2,7 +2,7 @@ title: help categories: | core -version: 0.100.0 +version: 0.101.0 core: | Display help information about different parts of Nushell. usage: | diff --git a/commands/docs/help_aliases.md b/commands/docs/help_aliases.md index 3930f1fc971..39d2d0ffb23 100644 --- a/commands/docs/help_aliases.md +++ b/commands/docs/help_aliases.md @@ -2,7 +2,7 @@ title: help aliases categories: | core -version: 0.100.0 +version: 0.101.0 core: | Show help on nushell aliases. usage: | diff --git a/commands/docs/help_commands.md b/commands/docs/help_commands.md index 8f2711cf7c2..4a43b109ac0 100644 --- a/commands/docs/help_commands.md +++ b/commands/docs/help_commands.md @@ -2,7 +2,7 @@ title: help commands categories: | core -version: 0.100.0 +version: 0.101.0 core: | Show help on nushell commands. usage: | diff --git a/commands/docs/help_escapes.md b/commands/docs/help_escapes.md index e0c31440987..35384799aab 100644 --- a/commands/docs/help_escapes.md +++ b/commands/docs/help_escapes.md @@ -2,7 +2,7 @@ title: help escapes categories: | core -version: 0.100.0 +version: 0.101.0 core: | Show help on nushell string escapes. usage: | diff --git a/commands/docs/help_externs.md b/commands/docs/help_externs.md index 63b62d999de..796154775da 100644 --- a/commands/docs/help_externs.md +++ b/commands/docs/help_externs.md @@ -2,7 +2,7 @@ title: help externs categories: | core -version: 0.100.0 +version: 0.101.0 core: | Show help on nushell externs. usage: | diff --git a/commands/docs/help_modules.md b/commands/docs/help_modules.md index 4524a7fa4aa..64cc1f87e5f 100644 --- a/commands/docs/help_modules.md +++ b/commands/docs/help_modules.md @@ -2,7 +2,7 @@ title: help modules categories: | core -version: 0.100.0 +version: 0.101.0 core: | Show help on nushell modules. usage: | diff --git a/commands/docs/help_operators.md b/commands/docs/help_operators.md index fe25ec4b234..065a6b3f916 100644 --- a/commands/docs/help_operators.md +++ b/commands/docs/help_operators.md @@ -2,7 +2,7 @@ title: help operators categories: | core -version: 0.100.0 +version: 0.101.0 core: | Show help on nushell operators. usage: | diff --git a/commands/docs/hide-env.md b/commands/docs/hide-env.md index 206fde8ae6c..8a0459b8178 100644 --- a/commands/docs/hide-env.md +++ b/commands/docs/hide-env.md @@ -2,7 +2,7 @@ title: hide-env categories: | core -version: 0.100.0 +version: 0.101.0 core: | Hide environment variables in the current scope. usage: | diff --git a/commands/docs/hide.md b/commands/docs/hide.md index 7ed8f5d7fdd..a3e5b69f5e6 100644 --- a/commands/docs/hide.md +++ b/commands/docs/hide.md @@ -2,7 +2,7 @@ title: hide categories: | core -version: 0.100.0 +version: 0.101.0 core: | Hide definitions in the current scope. usage: | diff --git a/commands/docs/histogram.md b/commands/docs/histogram.md index 933c896f416..79f1fcc7b5e 100644 --- a/commands/docs/histogram.md +++ b/commands/docs/histogram.md @@ -2,7 +2,7 @@ title: histogram categories: | chart -version: 0.100.0 +version: 0.101.0 chart: | Creates a new table with a histogram based on the column name passed in. usage: | @@ -51,12 +51,12 @@ Compute a histogram for the types of files, with frequency column named freq Compute a histogram for a list of numbers ```nu > [1 2 1] | histogram -╭───┬───────┬───────┬──────────┬────────────┬────────────────────────────────────────────────────────────────────╮ -│ # │ value │ count │ quantile │ percentage │ frequency │ -├───┼───────┼───────┼──────────┼────────────┼────────────────────────────────────────────────────────────────────┤ -│ 0 │ 1 │ 2 │ 0.67 │ 66.67% │ ****************************************************************** │ -│ 1 │ 2 │ 1 │ 0.33 │ 33.33% │ ********************************* │ -╰───┴───────┴───────┴──────────┴────────────┴────────────────────────────────────────────────────────────────────╯ +╭────┬────────┬────────┬───────────┬─────────────┬────────────────────────────────────────────────────────────────────╮ +│ # │ value │ count │ quantile │ percentage │ frequency │ +├────┼────────┼────────┼───────────┼─────────────┼────────────────────────────────────────────────────────────────────┤ +│ 0 │ 1 │ 2 │ 0.67 │ 66.67% │ ****************************************************************** │ +│ 1 │ 2 │ 1 │ 0.33 │ 33.33% │ ********************************* │ +╰────┴────────┴────────┴───────────┴─────────────┴────────────────────────────────────────────────────────────────────╯ ``` diff --git a/commands/docs/history.md b/commands/docs/history.md index b323645fd5f..50eb3c7d828 100644 --- a/commands/docs/history.md +++ b/commands/docs/history.md @@ -2,7 +2,7 @@ title: history categories: | history -version: 0.100.0 +version: 0.101.0 history: | Get the command history. usage: | diff --git a/commands/docs/history_import.md b/commands/docs/history_import.md index 59bb8235790..d40ae02e9fe 100644 --- a/commands/docs/history_import.md +++ b/commands/docs/history_import.md @@ -2,7 +2,7 @@ title: history import categories: | history -version: 0.100.0 +version: 0.101.0 history: | Import command line history usage: | diff --git a/commands/docs/history_session.md b/commands/docs/history_session.md index 959a0615fdf..9ca309b765e 100644 --- a/commands/docs/history_session.md +++ b/commands/docs/history_session.md @@ -2,7 +2,7 @@ title: history session categories: | history -version: 0.100.0 +version: 0.101.0 history: | Get the command history session. usage: | diff --git a/commands/docs/http.md b/commands/docs/http.md index 27ab349c23e..18184768243 100644 --- a/commands/docs/http.md +++ b/commands/docs/http.md @@ -2,7 +2,7 @@ title: http categories: | network -version: 0.100.0 +version: 0.101.0 network: | Various commands for working with http methods. usage: | diff --git a/commands/docs/http_delete.md b/commands/docs/http_delete.md index e8b827ee9c9..31f5fa3aa1a 100644 --- a/commands/docs/http_delete.md +++ b/commands/docs/http_delete.md @@ -2,7 +2,7 @@ title: http delete categories: | network -version: 0.100.0 +version: 0.101.0 network: | Delete the specified resource. usage: | diff --git a/commands/docs/http_get.md b/commands/docs/http_get.md index c5afcbe4628..28816ddefef 100644 --- a/commands/docs/http_get.md +++ b/commands/docs/http_get.md @@ -2,7 +2,7 @@ title: http get categories: | network -version: 0.100.0 +version: 0.101.0 network: | Fetch the contents from a URL. usage: | diff --git a/commands/docs/http_head.md b/commands/docs/http_head.md index 222a65ce089..983cd343bbd 100644 --- a/commands/docs/http_head.md +++ b/commands/docs/http_head.md @@ -2,7 +2,7 @@ title: http head categories: | network -version: 0.100.0 +version: 0.101.0 network: | Get the headers from a URL. usage: | diff --git a/commands/docs/http_options.md b/commands/docs/http_options.md index 239a3739895..8991ae1c195 100644 --- a/commands/docs/http_options.md +++ b/commands/docs/http_options.md @@ -2,7 +2,7 @@ title: http options categories: | network -version: 0.100.0 +version: 0.101.0 network: | Requests permitted communication options for a given URL. usage: | diff --git a/commands/docs/http_patch.md b/commands/docs/http_patch.md index e4b1760a730..3dcacb05711 100644 --- a/commands/docs/http_patch.md +++ b/commands/docs/http_patch.md @@ -2,7 +2,7 @@ title: http patch categories: | network -version: 0.100.0 +version: 0.101.0 network: | Patch a body to a URL. usage: | diff --git a/commands/docs/http_post.md b/commands/docs/http_post.md index 956a00b8397..88c011ace86 100644 --- a/commands/docs/http_post.md +++ b/commands/docs/http_post.md @@ -2,7 +2,7 @@ title: http post categories: | network -version: 0.100.0 +version: 0.101.0 network: | Post a body to a URL. usage: | diff --git a/commands/docs/http_put.md b/commands/docs/http_put.md index a21fba77170..cecbd92445b 100644 --- a/commands/docs/http_put.md +++ b/commands/docs/http_put.md @@ -2,7 +2,7 @@ title: http put categories: | network -version: 0.100.0 +version: 0.101.0 network: | Put a body to a URL. usage: | diff --git a/commands/docs/if.md b/commands/docs/if.md index fa22e74f75f..0c164cc932a 100644 --- a/commands/docs/if.md +++ b/commands/docs/if.md @@ -2,7 +2,7 @@ title: if categories: | core -version: 0.100.0 +version: 0.101.0 core: | Conditionally run a block. usage: | diff --git a/commands/docs/ignore.md b/commands/docs/ignore.md index edf574a81e2..023a84bc4ad 100644 --- a/commands/docs/ignore.md +++ b/commands/docs/ignore.md @@ -2,7 +2,7 @@ title: ignore categories: | core -version: 0.100.0 +version: 0.101.0 core: | Ignore the output of the previous command in the pipeline. usage: | diff --git a/commands/docs/inc.md b/commands/docs/inc.md index 9ef4866f248..1a144fb5bae 100644 --- a/commands/docs/inc.md +++ b/commands/docs/inc.md @@ -2,7 +2,7 @@ title: inc categories: | default -version: 0.100.0 +version: 0.101.0 default: | Increment a value or version. Optionally use the column of a table. usage: | diff --git a/commands/docs/input.md b/commands/docs/input.md index 972f8ec082e..e40a16d8b35 100644 --- a/commands/docs/input.md +++ b/commands/docs/input.md @@ -2,7 +2,7 @@ title: input categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Get input from the user. usage: | @@ -22,6 +22,7 @@ usage: | - `--bytes-until-any, -u {string}`: read bytes (not text) until any of the given stop bytes is seen - `--numchar, -n {int}`: number of characters to read; suppresses output + - `--default, -d {string}`: default value if no input is provided - `--suppress-output, -s`: don't print keystroke values ## Parameters @@ -49,6 +50,12 @@ Get two characters from the user, and assign to a variable ``` +Get input from the user with default value, and assign to a variable +```nu +> let user_input = (input --default 10) + +``` + ## Subcommands: diff --git a/commands/docs/input_list.md b/commands/docs/input_list.md index 5c040345c9f..8cc55a5dbe3 100644 --- a/commands/docs/input_list.md +++ b/commands/docs/input_list.md @@ -2,7 +2,7 @@ title: input list categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Interactive list selection. usage: | diff --git a/commands/docs/input_listen.md b/commands/docs/input_listen.md index 64b6552b140..90096561f4d 100644 --- a/commands/docs/input_listen.md +++ b/commands/docs/input_listen.md @@ -2,7 +2,7 @@ title: input listen categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Listen for user interface event. usage: | diff --git a/commands/docs/insert.md b/commands/docs/insert.md index 9bf972661ba..e28db6bc541 100644 --- a/commands/docs/insert.md +++ b/commands/docs/insert.md @@ -2,7 +2,7 @@ title: insert categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Insert a new column, using an expression or closure to create each row's values. usage: | diff --git a/commands/docs/inspect.md b/commands/docs/inspect.md index 36fae946880..30a7a23c080 100644 --- a/commands/docs/inspect.md +++ b/commands/docs/inspect.md @@ -2,7 +2,7 @@ title: inspect categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Inspect pipeline results while running a pipeline. usage: | diff --git a/commands/docs/interleave.md b/commands/docs/interleave.md index c58c391fc5f..4c3804acb13 100644 --- a/commands/docs/interleave.md +++ b/commands/docs/interleave.md @@ -2,7 +2,7 @@ title: interleave categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Read multiple streams in parallel and combine them into one stream. usage: | diff --git a/commands/docs/into.md b/commands/docs/into.md index 8a354458a22..2e2359a3143 100644 --- a/commands/docs/into.md +++ b/commands/docs/into.md @@ -2,7 +2,7 @@ title: into categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Commands to convert data from one type to another. usage: | diff --git a/commands/docs/into_binary.md b/commands/docs/into_binary.md index fcb09578239..edbbb9137a8 100644 --- a/commands/docs/into_binary.md +++ b/commands/docs/into_binary.md @@ -2,7 +2,7 @@ title: into binary categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to a binary primitive. usage: | diff --git a/commands/docs/into_bits.md b/commands/docs/into_bits.md index a115812ff5d..f369af29205 100644 --- a/commands/docs/into_bits.md +++ b/commands/docs/into_bits.md @@ -2,7 +2,7 @@ title: into bits categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to a binary primitive. usage: | diff --git a/commands/docs/into_bool.md b/commands/docs/into_bool.md index 5a5b84b94e8..0e18be908da 100644 --- a/commands/docs/into_bool.md +++ b/commands/docs/into_bool.md @@ -2,7 +2,7 @@ title: into bool categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to boolean. usage: | diff --git a/commands/docs/into_cell-path.md b/commands/docs/into_cell-path.md index 9a698006947..7006a964d1e 100644 --- a/commands/docs/into_cell-path.md +++ b/commands/docs/into_cell-path.md @@ -2,7 +2,7 @@ title: into cell-path categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to a cell-path. usage: | diff --git a/commands/docs/into_datetime.md b/commands/docs/into_datetime.md index 21191d626b3..68d94d877ea 100644 --- a/commands/docs/into_datetime.md +++ b/commands/docs/into_datetime.md @@ -2,7 +2,7 @@ title: into datetime categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert text or timestamp into a datetime. usage: | @@ -63,7 +63,7 @@ Sat, 27 Feb 2021 13:55:40 +0000 (3 years ago) Convert non-standard timestamp string, without timezone offset, to datetime with custom formatting ```nu > '16.11.1984 8:00 am' | into datetime --format '%d.%m.%Y %H:%M %P' -Fri, 16 Nov 1984 08:00:00 +0000 (40 years ago) +Fri, 16 Nov 1984 08:00:00 +0800 (40 years ago) ``` Convert nanosecond-precision unix timestamp to a datetime with offset from UTC diff --git a/commands/docs/into_duration.md b/commands/docs/into_duration.md index b1311931f1d..32e22c9b38d 100644 --- a/commands/docs/into_duration.md +++ b/commands/docs/into_duration.md @@ -2,7 +2,7 @@ title: into duration categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to duration. usage: | diff --git a/commands/docs/into_filesize.md b/commands/docs/into_filesize.md index 5ab10a439fe..32d5550b168 100644 --- a/commands/docs/into_filesize.md +++ b/commands/docs/into_filesize.md @@ -2,7 +2,7 @@ title: into filesize categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to filesize. usage: | diff --git a/commands/docs/into_float.md b/commands/docs/into_float.md index ae28d6cdb39..4bee3b1fee5 100644 --- a/commands/docs/into_float.md +++ b/commands/docs/into_float.md @@ -2,7 +2,7 @@ title: into float categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert data into floating point number. usage: | diff --git a/commands/docs/into_glob.md b/commands/docs/into_glob.md index db2bd705fc3..db0f18c6275 100644 --- a/commands/docs/into_glob.md +++ b/commands/docs/into_glob.md @@ -2,7 +2,7 @@ title: into glob categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to glob. usage: | diff --git a/commands/docs/into_int.md b/commands/docs/into_int.md index 7c7b6391435..133ad0ed533 100644 --- a/commands/docs/into_int.md +++ b/commands/docs/into_int.md @@ -2,7 +2,7 @@ title: into int categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to integer. usage: | diff --git a/commands/docs/into_record.md b/commands/docs/into_record.md index c72fa7127e9..0123ad2d302 100644 --- a/commands/docs/into_record.md +++ b/commands/docs/into_record.md @@ -2,7 +2,7 @@ title: into record categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to record. usage: | @@ -92,3 +92,9 @@ convert date to record │ timezone │ +02:00 │ ╰─────────────┴────────╯ ``` + +convert date components to table columns +```nu +> 2020-04-12T22:10:57+02:00 | into record | transpose | transpose -r + +``` diff --git a/commands/docs/into_sqlite.md b/commands/docs/into_sqlite.md index 25a79705b3e..99ce2b3bddc 100644 --- a/commands/docs/into_sqlite.md +++ b/commands/docs/into_sqlite.md @@ -2,7 +2,7 @@ title: into sqlite categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert table into a SQLite database. usage: | diff --git a/commands/docs/into_string.md b/commands/docs/into_string.md index f2bac1f4a92..0e744d84601 100644 --- a/commands/docs/into_string.md +++ b/commands/docs/into_string.md @@ -2,7 +2,7 @@ title: into string categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Convert value to string. usage: | diff --git a/commands/docs/into_value.md b/commands/docs/into_value.md index 8061d830fa6..824817523ba 100644 --- a/commands/docs/into_value.md +++ b/commands/docs/into_value.md @@ -2,7 +2,7 @@ title: into value categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Infer Nushell datatype for each cell. usage: | diff --git a/commands/docs/is-admin.md b/commands/docs/is-admin.md index 3e0f050d249..30a9e825a8f 100644 --- a/commands/docs/is-admin.md +++ b/commands/docs/is-admin.md @@ -2,7 +2,7 @@ title: is-admin categories: | core -version: 0.100.0 +version: 0.101.0 core: | Check if nushell is running with administrator or root privileges. usage: | diff --git a/commands/docs/is-empty.md b/commands/docs/is-empty.md index a0df2a68185..d92383b3dc4 100644 --- a/commands/docs/is-empty.md +++ b/commands/docs/is-empty.md @@ -2,7 +2,7 @@ title: is-empty categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Check for empty values. usage: | diff --git a/commands/docs/is-not-empty.md b/commands/docs/is-not-empty.md index 980825d7324..a6ab6adadb9 100644 --- a/commands/docs/is-not-empty.md +++ b/commands/docs/is-not-empty.md @@ -2,7 +2,7 @@ title: is-not-empty categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Check for non-empty values. usage: | diff --git a/commands/docs/is-terminal.md b/commands/docs/is-terminal.md index ed21f91c528..d718f8091ab 100644 --- a/commands/docs/is-terminal.md +++ b/commands/docs/is-terminal.md @@ -2,7 +2,7 @@ title: is-terminal categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Check if stdin, stdout, or stderr is a terminal. usage: | diff --git a/commands/docs/items.md b/commands/docs/items.md index 16c0c07f77d..f8cd65c3a78 100644 --- a/commands/docs/items.md +++ b/commands/docs/items.md @@ -2,7 +2,7 @@ title: items categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Given a record, iterate on each pair of column name and associated value. usage: | diff --git a/commands/docs/join.md b/commands/docs/join.md index a95b2aca207..a50242af8f7 100644 --- a/commands/docs/join.md +++ b/commands/docs/join.md @@ -2,7 +2,7 @@ title: join categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Join two tables. usage: | diff --git a/commands/docs/keybindings.md b/commands/docs/keybindings.md index ad4000b9ed8..d24215817b2 100644 --- a/commands/docs/keybindings.md +++ b/commands/docs/keybindings.md @@ -2,7 +2,7 @@ title: keybindings categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Keybindings related commands. usage: | diff --git a/commands/docs/keybindings_default.md b/commands/docs/keybindings_default.md index d28062eb52d..86d8e3a7804 100644 --- a/commands/docs/keybindings_default.md +++ b/commands/docs/keybindings_default.md @@ -2,7 +2,7 @@ title: keybindings default categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | List default keybindings. usage: | diff --git a/commands/docs/keybindings_list.md b/commands/docs/keybindings_list.md index 1007213f0f9..6df7f13a8bb 100644 --- a/commands/docs/keybindings_list.md +++ b/commands/docs/keybindings_list.md @@ -2,7 +2,7 @@ title: keybindings list categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | List available options that can be used to create keybindings. usage: | diff --git a/commands/docs/keybindings_listen.md b/commands/docs/keybindings_listen.md index 0f3c601a578..efdd297d185 100644 --- a/commands/docs/keybindings_listen.md +++ b/commands/docs/keybindings_listen.md @@ -2,7 +2,7 @@ title: keybindings listen categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Get input from the user. usage: | diff --git a/commands/docs/kill.md b/commands/docs/kill.md index 4267aef7176..4639c7d67b5 100644 --- a/commands/docs/kill.md +++ b/commands/docs/kill.md @@ -2,7 +2,7 @@ title: kill categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Kill a process using the process id. usage: | diff --git a/commands/docs/last.md b/commands/docs/last.md index e8ebb93504c..211647ee676 100644 --- a/commands/docs/last.md +++ b/commands/docs/last.md @@ -2,7 +2,7 @@ title: last categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Return only the last several rows of the input. Counterpart of `first`. Opposite of `drop`. usage: | diff --git a/commands/docs/length.md b/commands/docs/length.md index 2776c1740a3..9f4bd3aacc6 100644 --- a/commands/docs/length.md +++ b/commands/docs/length.md @@ -2,7 +2,7 @@ title: length categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Count the number of items in an input list, rows in a table, or bytes in binary data. usage: | @@ -25,6 +25,7 @@ usage: | | --------- | ------ | | binary | int | | list\ | int | +| nothing | int | ## Examples Count the number of items in a list @@ -44,3 +45,9 @@ Count the number of bytes in binary data > 0x[01 02] | length 2 ``` + +Count the length a null value +```nu +> null | length +0 +``` diff --git a/commands/docs/let-env.md b/commands/docs/let-env.md index 2127b1b3d11..e7a3f646f0c 100644 --- a/commands/docs/let-env.md +++ b/commands/docs/let-env.md @@ -2,7 +2,7 @@ title: let-env categories: | removed -version: 0.100.0 +version: 0.101.0 removed: | `let-env FOO = ...` has been removed, use `$env.FOO = ...` instead. usage: | diff --git a/commands/docs/let.md b/commands/docs/let.md index 372016ef54b..c3496136c0b 100644 --- a/commands/docs/let.md +++ b/commands/docs/let.md @@ -2,7 +2,7 @@ title: let categories: | core -version: 0.100.0 +version: 0.101.0 core: | Create a variable and give it a value. usage: | diff --git a/commands/docs/lines.md b/commands/docs/lines.md index bb3e3ff497d..866130bc750 100644 --- a/commands/docs/lines.md +++ b/commands/docs/lines.md @@ -2,7 +2,7 @@ title: lines categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Converts input to lines. usage: | diff --git a/commands/docs/load-env.md b/commands/docs/load-env.md index fde2ab55e44..bde70d3a4fc 100644 --- a/commands/docs/load-env.md +++ b/commands/docs/load-env.md @@ -2,7 +2,7 @@ title: load-env categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Loads an environment update from a record. usage: | diff --git a/commands/docs/loop.md b/commands/docs/loop.md index b86227a3948..6ba3b67eaf9 100644 --- a/commands/docs/loop.md +++ b/commands/docs/loop.md @@ -2,7 +2,7 @@ title: loop categories: | core -version: 0.100.0 +version: 0.101.0 core: | Run a block in a loop. usage: | diff --git a/commands/docs/ls.md b/commands/docs/ls.md index 0d76cf1fdce..8e0798e9972 100644 --- a/commands/docs/ls.md +++ b/commands/docs/ls.md @@ -2,7 +2,7 @@ title: ls categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | List the filenames, sizes, and modification times of items in a directory. usage: | diff --git a/commands/docs/match.md b/commands/docs/match.md index cbf54d7d423..889666bfa51 100644 --- a/commands/docs/match.md +++ b/commands/docs/match.md @@ -2,7 +2,7 @@ title: match categories: | core -version: 0.100.0 +version: 0.101.0 core: | Conditionally run a block on a matched value. usage: | diff --git a/commands/docs/math.md b/commands/docs/math.md index d4b1f8e2027..6bbf5955d31 100644 --- a/commands/docs/math.md +++ b/commands/docs/math.md @@ -2,7 +2,7 @@ title: math categories: | math -version: 0.100.0 +version: 0.101.0 math: | Use mathematical functions as aggregate functions on a list of numbers or tables. usage: | diff --git a/commands/docs/math_abs.md b/commands/docs/math_abs.md index 9817f6c2543..8140977bf1d 100644 --- a/commands/docs/math_abs.md +++ b/commands/docs/math_abs.md @@ -2,7 +2,7 @@ title: math abs categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the absolute value of a number. usage: | diff --git a/commands/docs/math_arccos.md b/commands/docs/math_arccos.md index 900fde5585a..bbd1897845e 100644 --- a/commands/docs/math_arccos.md +++ b/commands/docs/math_arccos.md @@ -2,7 +2,7 @@ title: math arccos categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the arccosine of the number. usage: | diff --git a/commands/docs/math_arccosh.md b/commands/docs/math_arccosh.md index ee48a73fff2..ef5b467baff 100644 --- a/commands/docs/math_arccosh.md +++ b/commands/docs/math_arccosh.md @@ -2,7 +2,7 @@ title: math arccosh categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the inverse of the hyperbolic cosine function. usage: | diff --git a/commands/docs/math_arcsin.md b/commands/docs/math_arcsin.md index f82a70f27df..5716cfdbef0 100644 --- a/commands/docs/math_arcsin.md +++ b/commands/docs/math_arcsin.md @@ -2,7 +2,7 @@ title: math arcsin categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the arcsine of the number. usage: | diff --git a/commands/docs/math_arcsinh.md b/commands/docs/math_arcsinh.md index c3ed1ad0a59..ce386c7e58f 100644 --- a/commands/docs/math_arcsinh.md +++ b/commands/docs/math_arcsinh.md @@ -2,7 +2,7 @@ title: math arcsinh categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the inverse of the hyperbolic sine function. usage: | diff --git a/commands/docs/math_arctan.md b/commands/docs/math_arctan.md index a0b6659ffc0..54c7f39ad49 100644 --- a/commands/docs/math_arctan.md +++ b/commands/docs/math_arctan.md @@ -2,7 +2,7 @@ title: math arctan categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the arctangent of the number. usage: | diff --git a/commands/docs/math_arctanh.md b/commands/docs/math_arctanh.md index bc344682ac9..0564b16f73c 100644 --- a/commands/docs/math_arctanh.md +++ b/commands/docs/math_arctanh.md @@ -2,7 +2,7 @@ title: math arctanh categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the inverse of the hyperbolic tangent function. usage: | diff --git a/commands/docs/math_avg.md b/commands/docs/math_avg.md index 6ef2f6e20ae..5a3a81b2717 100644 --- a/commands/docs/math_avg.md +++ b/commands/docs/math_avg.md @@ -2,7 +2,7 @@ title: math avg categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the average of a list of numbers. usage: | diff --git a/commands/docs/math_ceil.md b/commands/docs/math_ceil.md index c5357239dc9..804be7d5f48 100644 --- a/commands/docs/math_ceil.md +++ b/commands/docs/math_ceil.md @@ -2,7 +2,7 @@ title: math ceil categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the ceil of a number (smallest integer greater than or equal to that number). usage: | diff --git a/commands/docs/math_cos.md b/commands/docs/math_cos.md index 5203f78e58e..bcba7ba6970 100644 --- a/commands/docs/math_cos.md +++ b/commands/docs/math_cos.md @@ -2,7 +2,7 @@ title: math cos categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the cosine of the number. usage: | diff --git a/commands/docs/math_cosh.md b/commands/docs/math_cosh.md index be0a5cd5084..bf9006174a8 100644 --- a/commands/docs/math_cosh.md +++ b/commands/docs/math_cosh.md @@ -2,7 +2,7 @@ title: math cosh categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the hyperbolic cosine of the number. usage: | diff --git a/commands/docs/math_exp.md b/commands/docs/math_exp.md index 2f0064a5963..3fb426f64e4 100644 --- a/commands/docs/math_exp.md +++ b/commands/docs/math_exp.md @@ -2,7 +2,7 @@ title: math exp categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns e raised to the power of x. usage: | diff --git a/commands/docs/math_floor.md b/commands/docs/math_floor.md index 5655e0182b8..d5f7cb30a4b 100644 --- a/commands/docs/math_floor.md +++ b/commands/docs/math_floor.md @@ -2,7 +2,7 @@ title: math floor categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the floor of a number (largest integer less than or equal to that number). usage: | diff --git a/commands/docs/math_ln.md b/commands/docs/math_ln.md index f1e36bb74a0..4f825ed609f 100644 --- a/commands/docs/math_ln.md +++ b/commands/docs/math_ln.md @@ -2,7 +2,7 @@ title: math ln categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the natural logarithm. Base: (math e). usage: | diff --git a/commands/docs/math_log.md b/commands/docs/math_log.md index 719e4d88c76..6b3b0a4af78 100644 --- a/commands/docs/math_log.md +++ b/commands/docs/math_log.md @@ -2,7 +2,7 @@ title: math log categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the logarithm for an arbitrary base. usage: | diff --git a/commands/docs/math_max.md b/commands/docs/math_max.md index 73b2ac00e1c..635bc6db3de 100644 --- a/commands/docs/math_max.md +++ b/commands/docs/math_max.md @@ -2,7 +2,7 @@ title: math max categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the maximum of a list of values, or of columns in a table. usage: | diff --git a/commands/docs/math_median.md b/commands/docs/math_median.md index a38bed5079f..4883728aae4 100644 --- a/commands/docs/math_median.md +++ b/commands/docs/math_median.md @@ -2,7 +2,7 @@ title: math median categories: | math -version: 0.100.0 +version: 0.101.0 math: | Computes the median of a list of numbers. usage: | diff --git a/commands/docs/math_min.md b/commands/docs/math_min.md index 8980693a54a..95fe633fd3f 100644 --- a/commands/docs/math_min.md +++ b/commands/docs/math_min.md @@ -2,7 +2,7 @@ title: math min categories: | math -version: 0.100.0 +version: 0.101.0 math: | Finds the minimum within a list of values or tables. usage: | diff --git a/commands/docs/math_mode.md b/commands/docs/math_mode.md index 5d8d61bd0e1..1ae7c55d6f5 100644 --- a/commands/docs/math_mode.md +++ b/commands/docs/math_mode.md @@ -2,7 +2,7 @@ title: math mode categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the most frequent element(s) from a list of numbers or tables. usage: | diff --git a/commands/docs/math_product.md b/commands/docs/math_product.md index da1fb43a023..b8851e5f764 100644 --- a/commands/docs/math_product.md +++ b/commands/docs/math_product.md @@ -2,7 +2,7 @@ title: math product categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the product of a list of numbers or the products of each column of a table. usage: | diff --git a/commands/docs/math_round.md b/commands/docs/math_round.md index c7bfcdeb019..17f1677a2d2 100644 --- a/commands/docs/math_round.md +++ b/commands/docs/math_round.md @@ -2,7 +2,7 @@ title: math round categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the input number rounded to the specified precision. usage: | diff --git a/commands/docs/math_sin.md b/commands/docs/math_sin.md index 9358683285c..65cdd67567a 100644 --- a/commands/docs/math_sin.md +++ b/commands/docs/math_sin.md @@ -2,7 +2,7 @@ title: math sin categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the sine of the number. usage: | diff --git a/commands/docs/math_sinh.md b/commands/docs/math_sinh.md index cc855e73163..a0b676ee104 100644 --- a/commands/docs/math_sinh.md +++ b/commands/docs/math_sinh.md @@ -2,7 +2,7 @@ title: math sinh categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the hyperbolic sine of the number. usage: | diff --git a/commands/docs/math_sqrt.md b/commands/docs/math_sqrt.md index 1eda85fcfa7..112e01c4cf8 100644 --- a/commands/docs/math_sqrt.md +++ b/commands/docs/math_sqrt.md @@ -2,7 +2,7 @@ title: math sqrt categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the square root of the input number. usage: | diff --git a/commands/docs/math_stddev.md b/commands/docs/math_stddev.md index f069744fdcf..b689c5d232e 100644 --- a/commands/docs/math_stddev.md +++ b/commands/docs/math_stddev.md @@ -2,7 +2,7 @@ title: math stddev categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the standard deviation of a list of numbers, or of each column in a table. usage: | diff --git a/commands/docs/math_sum.md b/commands/docs/math_sum.md index 14391e1591e..d58a2e45f2b 100644 --- a/commands/docs/math_sum.md +++ b/commands/docs/math_sum.md @@ -2,7 +2,7 @@ title: math sum categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the sum of a list of numbers or of each column in a table. usage: | diff --git a/commands/docs/math_tan.md b/commands/docs/math_tan.md index a58f92048d0..6cac18fbeaa 100644 --- a/commands/docs/math_tan.md +++ b/commands/docs/math_tan.md @@ -2,7 +2,7 @@ title: math tan categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the tangent of the number. usage: | diff --git a/commands/docs/math_tanh.md b/commands/docs/math_tanh.md index 93019fc14df..e7de8550621 100644 --- a/commands/docs/math_tanh.md +++ b/commands/docs/math_tanh.md @@ -2,7 +2,7 @@ title: math tanh categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the hyperbolic tangent of the number. usage: | diff --git a/commands/docs/math_variance.md b/commands/docs/math_variance.md index fad23a35261..adc8de7e0b0 100644 --- a/commands/docs/math_variance.md +++ b/commands/docs/math_variance.md @@ -2,7 +2,7 @@ title: math variance categories: | math -version: 0.100.0 +version: 0.101.0 math: | Returns the variance of a list of numbers or of each column in a table. usage: | diff --git a/commands/docs/merge.md b/commands/docs/merge.md index 105dccdc1c5..ea0fb044fe4 100644 --- a/commands/docs/merge.md +++ b/commands/docs/merge.md @@ -2,7 +2,7 @@ title: merge categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Merge the input with a record or table, overwriting values in matching columns. usage: | @@ -70,4 +70,10 @@ You may provide a column structure to merge When merging tables, row 0 of the input table is overwritten with values from row 0 of the provided table, then -repeating this process with row 1, and so on. \ No newline at end of file +repeating this process with row 1, and so on. + +## Subcommands: + +| name | description | type | +| -------------------------------------------- | --------------------------------------------------------------------------------------- | -------- | +| [`merge deep`](/commands/docs/merge_deep.md) | Merge the input with a record or table, recursively merging values in matching columns. | built-in | diff --git a/commands/docs/merge_deep.md b/commands/docs/merge_deep.md new file mode 100644 index 00000000000..fbba9a79064 --- /dev/null +++ b/commands/docs/merge_deep.md @@ -0,0 +1,103 @@ +--- +title: merge deep +categories: | + filters +version: 0.101.0 +filters: | + Merge the input with a record or table, recursively merging values in matching columns. +usage: | + Merge the input with a record or table, recursively merging values in matching columns. +--- + + +# `merge deep` for [filters](/commands/categories/filters.md) + +
Merge the input with a record or table, recursively merging values in matching columns.
+ +## Signature + +```> merge deep {flags} (value)``` + +## Flags + + - `--strategy, -s {string}`: The list merging strategy to use. One of: table (default), overwrite, append, prepend + +## Parameters + + - `value`: The new value to merge with. + + +## Input/output types: + +| input | output | +| ------ | ------ | +| record | record | +| table | table | +## Examples + +Merge two records recursively +```nu +> {a: 1, b: {c: 2, d: 3}} | merge deep {b: {d: 4, e: 5}} +╭───┬───────────╮ +│ a │ 1 │ +│ │ ╭───┬───╮ │ +│ b │ │ c │ 2 │ │ +│ │ │ d │ 4 │ │ +│ │ │ e │ 5 │ │ +│ │ ╰───┴───╯ │ +╰───┴───────────╯ +``` + +Merge two tables +```nu +> [{columnA: 0, columnB: [{B1: 1}]}] | merge deep [{columnB: [{B2: 2}]}] +╭───┬─────────┬─────────────────╮ +│ # │ columnA │ columnB │ +├───┼─────────┼─────────────────┤ +│ 0 │ 0 │ ╭───┬────┬────╮ │ +│ │ │ │ # │ B1 │ B2 │ │ +│ │ │ ├───┼────┼────┤ │ +│ │ │ │ 0 │ 1 │ 2 │ │ +│ │ │ ╰───┴────┴────╯ │ +╰───┴─────────┴─────────────────╯ + +``` + +Merge two records and their inner tables +```nu +> {inner: [{a: 1}, {b: 2}]} | merge deep {inner: [{c: 3}]} +╭───────┬──────────────────────╮ +│ │ ╭───┬────┬────┬────╮ │ +│ inner │ │ # │ a │ c │ b │ │ +│ │ ├───┼────┼────┼────┤ │ +│ │ │ 0 │ 1 │ 3 │ ❎ │ │ +│ │ │ 1 │ ❎ │ ❎ │ 2 │ │ +│ │ ╰───┴────┴────┴────╯ │ +╰───────┴──────────────────────╯ +``` + +Merge two records, appending their inner tables +```nu +> {inner: [{a: 1}, {b: 2}]} | merge deep {inner: [{c: 3}]} --strategy=append +╭───────┬──────────────────────╮ +│ │ ╭───┬────┬────┬────╮ │ +│ inner │ │ # │ a │ b │ c │ │ +│ │ ├───┼────┼────┼────┤ │ +│ │ │ 0 │ 1 │ ❎ │ ❎ │ │ +│ │ │ 1 │ ❎ │ 2 │ ❎ │ │ +│ │ │ 2 │ ❎ │ ❎ │ 3 │ │ +│ │ ╰───┴────┴────┴────╯ │ +╰───────┴──────────────────────╯ +``` + +## Notes +The way that key-value pairs which exist in both the input and the argument are merged depends on their types. + +Scalar values (like numbers and strings) in the input are overwritten by the corresponding value from the argument. +Records in the input are merged similarly to the merge command, but recursing rather than overwriting inner records. + +The way lists and tables are merged is controlled by the `--strategy` flag: + - table: Merges tables element-wise, similarly to the merge command. Non-table lists are overwritten. + - overwrite: Lists and tables are overwritten with their corresponding value from the argument, similarly to scalars. + - append: Lists and tables in the input are appended with the corresponding list from the argument. + - prepend: Lists and tables in the input are prepended with the corresponding list from the argument. \ No newline at end of file diff --git a/commands/docs/metadata.md b/commands/docs/metadata.md index 06a03f74ee0..ac98882913a 100644 --- a/commands/docs/metadata.md +++ b/commands/docs/metadata.md @@ -2,7 +2,7 @@ title: metadata categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Get the metadata for items in the stream. usage: | diff --git a/commands/docs/metadata_access.md b/commands/docs/metadata_access.md index eab15c9b532..7d5e52378ac 100644 --- a/commands/docs/metadata_access.md +++ b/commands/docs/metadata_access.md @@ -2,7 +2,7 @@ title: metadata access categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Access the metadata for the input stream within a closure. usage: | diff --git a/commands/docs/metadata_set.md b/commands/docs/metadata_set.md index 0e7d614b2b4..0762e9aef2e 100644 --- a/commands/docs/metadata_set.md +++ b/commands/docs/metadata_set.md @@ -2,7 +2,7 @@ title: metadata set categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Set the metadata for items in the stream. usage: | diff --git a/commands/docs/mkdir.md b/commands/docs/mkdir.md index 18e09bb9d7a..c12398c8228 100644 --- a/commands/docs/mkdir.md +++ b/commands/docs/mkdir.md @@ -2,7 +2,7 @@ title: mkdir categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Create directories, with intermediary directories if required using uutils/coreutils mkdir. usage: | diff --git a/commands/docs/mktemp.md b/commands/docs/mktemp.md index 867ea2857b9..030b2d5fc88 100644 --- a/commands/docs/mktemp.md +++ b/commands/docs/mktemp.md @@ -2,7 +2,7 @@ title: mktemp categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Create temporary files or directories using uutils/coreutils mktemp. usage: | diff --git a/commands/docs/module.md b/commands/docs/module.md index b89b9cde094..0b10a054087 100644 --- a/commands/docs/module.md +++ b/commands/docs/module.md @@ -2,7 +2,7 @@ title: module categories: | core -version: 0.100.0 +version: 0.101.0 core: | Define a custom module. usage: | diff --git a/commands/docs/move.md b/commands/docs/move.md index 849449c7035..82d3c956d57 100644 --- a/commands/docs/move.md +++ b/commands/docs/move.md @@ -2,7 +2,7 @@ title: move categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Move columns before or after other columns. usage: | diff --git a/commands/docs/mut.md b/commands/docs/mut.md index 401a5c15851..a587f71e6d2 100644 --- a/commands/docs/mut.md +++ b/commands/docs/mut.md @@ -2,7 +2,7 @@ title: mut categories: | core -version: 0.100.0 +version: 0.101.0 core: | Create a mutable variable and give it a value. usage: | diff --git a/commands/docs/mv.md b/commands/docs/mv.md index 653c0370fef..f4680276e2c 100644 --- a/commands/docs/mv.md +++ b/commands/docs/mv.md @@ -2,7 +2,7 @@ title: mv categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Move files or directories using uutils/coreutils mv. usage: | diff --git a/commands/docs/nu-check.md b/commands/docs/nu-check.md index 82e866feadc..fda1d13e0a4 100644 --- a/commands/docs/nu-check.md +++ b/commands/docs/nu-check.md @@ -2,7 +2,7 @@ title: nu-check categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Validate and parse input content. usage: | diff --git a/commands/docs/nu-highlight.md b/commands/docs/nu-highlight.md index ce06671aae6..6d8e19a8a3b 100644 --- a/commands/docs/nu-highlight.md +++ b/commands/docs/nu-highlight.md @@ -2,7 +2,7 @@ title: nu-highlight categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Syntax highlight the input string. usage: | diff --git a/commands/docs/open.md b/commands/docs/open.md index 75f893e3548..e4399ddc58e 100644 --- a/commands/docs/open.md +++ b/commands/docs/open.md @@ -2,7 +2,7 @@ title: open categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Load a file into a cell, converting to table if possible (avoid by appending '--raw'). usage: | diff --git a/commands/docs/overlay.md b/commands/docs/overlay.md index d6c1325721b..73937d70d62 100644 --- a/commands/docs/overlay.md +++ b/commands/docs/overlay.md @@ -2,7 +2,7 @@ title: overlay categories: | core -version: 0.100.0 +version: 0.101.0 core: | Commands for manipulating overlays. usage: | diff --git a/commands/docs/overlay_hide.md b/commands/docs/overlay_hide.md index 31e34c132d7..3b78b62b493 100644 --- a/commands/docs/overlay_hide.md +++ b/commands/docs/overlay_hide.md @@ -2,7 +2,7 @@ title: overlay hide categories: | core -version: 0.100.0 +version: 0.101.0 core: | Hide an active overlay. usage: | diff --git a/commands/docs/overlay_list.md b/commands/docs/overlay_list.md index ee81ea373a1..e4a68bc55bb 100644 --- a/commands/docs/overlay_list.md +++ b/commands/docs/overlay_list.md @@ -2,7 +2,7 @@ title: overlay list categories: | core -version: 0.100.0 +version: 0.101.0 core: | List all active overlays. usage: | diff --git a/commands/docs/overlay_new.md b/commands/docs/overlay_new.md index a42d40372e9..ea02970408c 100644 --- a/commands/docs/overlay_new.md +++ b/commands/docs/overlay_new.md @@ -2,7 +2,7 @@ title: overlay new categories: | core -version: 0.100.0 +version: 0.101.0 core: | Create an empty overlay. usage: | diff --git a/commands/docs/overlay_use.md b/commands/docs/overlay_use.md index f26fd2147db..23faab65a93 100644 --- a/commands/docs/overlay_use.md +++ b/commands/docs/overlay_use.md @@ -2,7 +2,7 @@ title: overlay use categories: | core -version: 0.100.0 +version: 0.101.0 core: | Use definitions from a module as an overlay. usage: | diff --git a/commands/docs/panic.md b/commands/docs/panic.md index 67cdcce2bb0..2c01741ec1a 100644 --- a/commands/docs/panic.md +++ b/commands/docs/panic.md @@ -2,7 +2,7 @@ title: panic categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Causes nushell to panic. usage: | diff --git a/commands/docs/par-each.md b/commands/docs/par-each.md index fbc9dbe9033..05ce604e53b 100644 --- a/commands/docs/par-each.md +++ b/commands/docs/par-each.md @@ -2,7 +2,7 @@ title: par-each categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Run a closure on each row of the input list in parallel, creating a new list with the results. usage: | diff --git a/commands/docs/parse.md b/commands/docs/parse.md index 32059b230b8..775dc312b95 100644 --- a/commands/docs/parse.md +++ b/commands/docs/parse.md @@ -2,7 +2,7 @@ title: parse categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Parse columns from string data using a simple pattern or a supplied regular expression. usage: | diff --git a/commands/docs/path.md b/commands/docs/path.md index bffb2de15a5..89fe9500e93 100644 --- a/commands/docs/path.md +++ b/commands/docs/path.md @@ -2,7 +2,7 @@ title: path categories: | path -version: 0.100.0 +version: 0.101.0 path: | Explore and manipulate paths. usage: | @@ -43,14 +43,15 @@ the path literal. ## Subcommands: -| name | description | type | -| -------------------------------------------------------- | ----------------------------------------------------------------------- | -------- | -| [`path basename`](/commands/docs/path_basename.md) | Get the final component of a path. | built-in | -| [`path dirname`](/commands/docs/path_dirname.md) | Get the parent directory of a path. | built-in | -| [`path exists`](/commands/docs/path_exists.md) | Check whether a path exists. | built-in | -| [`path expand`](/commands/docs/path_expand.md) | Try to expand a path to its absolute form. | built-in | -| [`path join`](/commands/docs/path_join.md) | Join a structured path or a list of path parts. | built-in | -| [`path parse`](/commands/docs/path_parse.md) | Convert a path into structured data. | built-in | -| [`path relative-to`](/commands/docs/path_relative-to.md) | Express a path as relative to another path. | built-in | -| [`path split`](/commands/docs/path_split.md) | Split a path into a list based on the system's path separator. | built-in | -| [`path type`](/commands/docs/path_type.md) | Get the type of the object a path refers to (e.g., file, dir, symlink). | built-in | \ No newline at end of file +| name | description | type | +| -------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------- | +| [`path basename`](/commands/docs/path_basename.md) | Get the final component of a path. | built-in | +| [`path dirname`](/commands/docs/path_dirname.md) | Get the parent directory of a path. | built-in | +| [`path exists`](/commands/docs/path_exists.md) | Check whether a path exists. | built-in | +| [`path expand`](/commands/docs/path_expand.md) | Try to expand a path to its absolute form. | built-in | +| [`path join`](/commands/docs/path_join.md) | Join a structured path or a list of path parts. | built-in | +| [`path parse`](/commands/docs/path_parse.md) | Convert a path into structured data. | built-in | +| [`path relative-to`](/commands/docs/path_relative-to.md) | Express a path as relative to another path. | built-in | +| [`path self`](/commands/docs/path_self.md) | Get the absolute path of the script or module containing this command at parse time. | built-in | +| [`path split`](/commands/docs/path_split.md) | Split a path into a list based on the system's path separator. | built-in | +| [`path type`](/commands/docs/path_type.md) | Get the type of the object a path refers to (e.g., file, dir, symlink). | built-in | \ No newline at end of file diff --git a/commands/docs/path_basename.md b/commands/docs/path_basename.md index b34d8a8ef6c..57a83e622db 100644 --- a/commands/docs/path_basename.md +++ b/commands/docs/path_basename.md @@ -2,7 +2,7 @@ title: path basename categories: | path -version: 0.100.0 +version: 0.101.0 path: | Get the final component of a path. usage: | diff --git a/commands/docs/path_dirname.md b/commands/docs/path_dirname.md index 194524fba6c..d0ab9b07bd4 100644 --- a/commands/docs/path_dirname.md +++ b/commands/docs/path_dirname.md @@ -2,7 +2,7 @@ title: path dirname categories: | path -version: 0.100.0 +version: 0.101.0 path: | Get the parent directory of a path. usage: | diff --git a/commands/docs/path_exists.md b/commands/docs/path_exists.md index bdc32303b0a..770764f4dca 100644 --- a/commands/docs/path_exists.md +++ b/commands/docs/path_exists.md @@ -2,7 +2,7 @@ title: path exists categories: | path -version: 0.100.0 +version: 0.101.0 path: | Check whether a path exists. usage: | diff --git a/commands/docs/path_expand.md b/commands/docs/path_expand.md index 2d80ee1f2e2..a4cabcb7fc2 100644 --- a/commands/docs/path_expand.md +++ b/commands/docs/path_expand.md @@ -2,7 +2,7 @@ title: path expand categories: | path -version: 0.100.0 +version: 0.101.0 path: | Try to expand a path to its absolute form. usage: | diff --git a/commands/docs/path_join.md b/commands/docs/path_join.md index 962f6ce3c47..e645de22ee0 100644 --- a/commands/docs/path_join.md +++ b/commands/docs/path_join.md @@ -2,7 +2,7 @@ title: path join categories: | path -version: 0.100.0 +version: 0.101.0 path: | Join a structured path or a list of path parts. usage: | diff --git a/commands/docs/path_parse.md b/commands/docs/path_parse.md index 7af164c8690..ed80700b373 100644 --- a/commands/docs/path_parse.md +++ b/commands/docs/path_parse.md @@ -2,7 +2,7 @@ title: path parse categories: | path -version: 0.100.0 +version: 0.101.0 path: | Convert a path into structured data. usage: | diff --git a/commands/docs/path_relative-to.md b/commands/docs/path_relative-to.md index 99a0c0b70ca..037c4390a58 100644 --- a/commands/docs/path_relative-to.md +++ b/commands/docs/path_relative-to.md @@ -2,7 +2,7 @@ title: path relative-to categories: | path -version: 0.100.0 +version: 0.101.0 path: | Express a path as relative to another path. usage: | diff --git a/commands/docs/path_self.md b/commands/docs/path_self.md new file mode 100644 index 00000000000..4c8e8b2247e --- /dev/null +++ b/commands/docs/path_self.md @@ -0,0 +1,50 @@ +--- +title: path self +categories: | + path +version: 0.101.0 +path: | + Get the absolute path of the script or module containing this command at parse time. +usage: | + Get the absolute path of the script or module containing this command at parse time. +--- + + +# `path self` for [path](/commands/categories/path.md) + +
Get the absolute path of the script or module containing this command at parse time.
+ +## Signature + +```> path self {flags} (path)``` + +## Parameters + + - `path`: Path to get instead of the current file. + + +## Input/output types: + +| input | output | +| ------- | ------ | +| nothing | string | + +## Examples + +Get the path of the current file +```nu +> const current_file = path self + +``` + +Get the path of the directory containing the current file +```nu +> const current_file = path self . + +``` + +Get the absolute form of a path relative to the current file +```nu +> const current_file = path self ../foo + +``` diff --git a/commands/docs/path_split.md b/commands/docs/path_split.md index 2480acd84ed..26049d399ce 100644 --- a/commands/docs/path_split.md +++ b/commands/docs/path_split.md @@ -2,7 +2,7 @@ title: path split categories: | path -version: 0.100.0 +version: 0.101.0 path: | Split a path into a list based on the system's path separator. usage: | diff --git a/commands/docs/path_type.md b/commands/docs/path_type.md index b3ac0d35a0a..50cf26d5fd6 100644 --- a/commands/docs/path_type.md +++ b/commands/docs/path_type.md @@ -2,7 +2,7 @@ title: path type categories: | path -version: 0.100.0 +version: 0.101.0 path: | Get the type of the object a path refers to (e.g., file, dir, symlink). usage: | diff --git a/commands/docs/plugin.md b/commands/docs/plugin.md index 864269bd5dc..01546dbd18c 100644 --- a/commands/docs/plugin.md +++ b/commands/docs/plugin.md @@ -2,7 +2,7 @@ title: plugin categories: | plugin -version: 0.100.0 +version: 0.101.0 plugin: | Commands for managing plugins. usage: | diff --git a/commands/docs/plugin_add.md b/commands/docs/plugin_add.md index a1138f0e984..2757f33617f 100644 --- a/commands/docs/plugin_add.md +++ b/commands/docs/plugin_add.md @@ -2,7 +2,7 @@ title: plugin add categories: | plugin -version: 0.100.0 +version: 0.101.0 plugin: | Add a plugin to the plugin registry file. usage: | diff --git a/commands/docs/plugin_list.md b/commands/docs/plugin_list.md index 7acd9eba370..68c2793430f 100644 --- a/commands/docs/plugin_list.md +++ b/commands/docs/plugin_list.md @@ -2,7 +2,7 @@ title: plugin list categories: | plugin -version: 0.100.0 +version: 0.101.0 plugin: | List loaded and installed plugins. usage: | @@ -39,7 +39,7 @@ List installed plugins. ╭───┬──────┬─────────┬─────────┬────────┬───────────────────────────────┬───────┬─────────────╮ │ # │ name │ version │ status │ pid │ filename │ shell │ commands │ ├───┼──────┼─────────┼─────────┼────────┼───────────────────────────────┼───────┼─────────────┤ -│ 0 │ inc │ 0.100.0 │ running │ 106480 │ /opt/nu/plugins/nu_plugin_inc │ │ ╭───┬─────╮ │ +│ 0 │ inc │ 0.100.1 │ running │ 106480 │ /opt/nu/plugins/nu_plugin_inc │ │ ╭───┬─────╮ │ │ │ │ │ │ │ │ │ │ 0 │ inc │ │ │ │ │ │ │ │ │ │ ╰───┴─────╯ │ ╰───┴──────┴─────────┴─────────┴────────┴───────────────────────────────┴───────┴─────────────╯ diff --git a/commands/docs/plugin_rm.md b/commands/docs/plugin_rm.md index ee103685aff..71ce141b514 100644 --- a/commands/docs/plugin_rm.md +++ b/commands/docs/plugin_rm.md @@ -2,7 +2,7 @@ title: plugin rm categories: | plugin -version: 0.100.0 +version: 0.101.0 plugin: | Remove a plugin from the plugin registry file. usage: | diff --git a/commands/docs/plugin_stop.md b/commands/docs/plugin_stop.md index 98564b47a1a..f2977d27f29 100644 --- a/commands/docs/plugin_stop.md +++ b/commands/docs/plugin_stop.md @@ -2,7 +2,7 @@ title: plugin stop categories: | plugin -version: 0.100.0 +version: 0.101.0 plugin: | Stop an installed plugin if it was running. usage: | diff --git a/commands/docs/plugin_use.md b/commands/docs/plugin_use.md index 57916daba96..df935b41107 100644 --- a/commands/docs/plugin_use.md +++ b/commands/docs/plugin_use.md @@ -2,7 +2,7 @@ title: plugin use categories: | plugin -version: 0.100.0 +version: 0.101.0 plugin: | Load a plugin from the plugin registry file into scope. usage: | diff --git a/commands/docs/polars.md b/commands/docs/polars.md index 8593b0925bf..7bf9e074467 100644 --- a/commands/docs/polars.md +++ b/commands/docs/polars.md @@ -2,7 +2,7 @@ title: polars categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Operate with data in a dataframe format. usage: | @@ -37,120 +37,118 @@ You must use one of the following subcommands. Using this command as-is will onl ## Subcommands: -| name | description | type | -| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -| [`polars agg`](/commands/docs/polars_agg.md) | Performs a series of aggregations from a group-by. | plugin | -| [`polars agg-groups`](/commands/docs/polars_agg-groups.md) | Creates an agg_groups expression. | plugin | -| [`polars all-false`](/commands/docs/polars_all-false.md) | Returns true if all values are false. | plugin | -| [`polars all-true`](/commands/docs/polars_all-true.md) | Returns true if all values are true. | plugin | -| [`polars append`](/commands/docs/polars_append.md) | Appends a new dataframe. | plugin | -| [`polars arg-max`](/commands/docs/polars_arg-max.md) | Return index for max value in series. | plugin | -| [`polars arg-min`](/commands/docs/polars_arg-min.md) | Return index for min value in series. | plugin | -| [`polars arg-sort`](/commands/docs/polars_arg-sort.md) | Returns indexes for a sorted series. | plugin | -| [`polars arg-true`](/commands/docs/polars_arg-true.md) | Returns indexes where values are true. | plugin | -| [`polars arg-unique`](/commands/docs/polars_arg-unique.md) | Returns indexes for unique values. | plugin | -| [`polars arg-where`](/commands/docs/polars_arg-where.md) | Creates an expression that returns the arguments where expression is true. | plugin | -| [`polars as`](/commands/docs/polars_as.md) | Creates an alias expression. | plugin | -| [`polars as-date`](/commands/docs/polars_as-date.md) | Converts string to date. | plugin | -| [`polars as-datetime`](/commands/docs/polars_as-datetime.md) | Converts string to datetime. | plugin | -| [`polars cache`](/commands/docs/polars_cache.md) | Caches operations in a new LazyFrame. | plugin | -| [`polars cast`](/commands/docs/polars_cast.md) | Cast a column to a different dtype. | plugin | -| [`polars col`](/commands/docs/polars_col.md) | Creates a named column expression. | plugin | -| [`polars collect`](/commands/docs/polars_collect.md) | Collect lazy dataframe into eager dataframe. | plugin | -| [`polars columns`](/commands/docs/polars_columns.md) | Show dataframe columns. | plugin | -| [`polars concat`](/commands/docs/polars_concat.md) | Concatenate two or more dataframes. | plugin | -| [`polars concat-str`](/commands/docs/polars_concat-str.md) | Creates a concat string expression. | plugin | -| [`polars contains`](/commands/docs/polars_contains.md) | Checks if a pattern is contained in a string. | plugin | -| [`polars count`](/commands/docs/polars_count.md) | Returns the number of non-null values in the column. | plugin | -| [`polars count-null`](/commands/docs/polars_count-null.md) | Counts null values. | plugin | -| [`polars cumulative`](/commands/docs/polars_cumulative.md) | Cumulative calculation for a column or series. | plugin | -| [`polars datepart`](/commands/docs/polars_datepart.md) | Creates an expression for capturing the specified datepart in a column. | plugin | -| [`polars decimal`](/commands/docs/polars_decimal.md) | Converts a string column into a decimal column | plugin | -| [`polars drop`](/commands/docs/polars_drop.md) | Creates a new dataframe by dropping the selected columns. | plugin | -| [`polars drop-duplicates`](/commands/docs/polars_drop-duplicates.md) | Drops duplicate values in dataframe. | plugin | -| [`polars drop-nulls`](/commands/docs/polars_drop-nulls.md) | Drops null values in dataframe. | plugin | -| [`polars dummies`](/commands/docs/polars_dummies.md) | Creates a new dataframe with dummy variables. | plugin | -| [`polars explode`](/commands/docs/polars_explode.md) | Explodes a dataframe or creates a explode expression. | plugin | -| [`polars expr-not`](/commands/docs/polars_expr-not.md) | Creates a not expression. | plugin | -| [`polars fetch`](/commands/docs/polars_fetch.md) | Collects the lazyframe to the selected rows. | plugin | -| [`polars fill-nan`](/commands/docs/polars_fill-nan.md) | Replaces NaN values with the given expression. | plugin | -| [`polars fill-null`](/commands/docs/polars_fill-null.md) | Replaces NULL values with the given expression. | plugin | -| [`polars filter`](/commands/docs/polars_filter.md) | Filter dataframe based in expression. | plugin | -| [`polars filter-with`](/commands/docs/polars_filter-with.md) | Filters dataframe using a mask or expression as reference. | plugin | -| [`polars first`](/commands/docs/polars_first.md) | Show only the first number of rows or create a first expression | plugin | -| [`polars flatten`](/commands/docs/polars_flatten.md) | An alias for polars explode. | plugin | -| [`polars get`](/commands/docs/polars_get.md) | Creates dataframe with the selected columns. | plugin | -| [`polars get-day`](/commands/docs/polars_get-day.md) | Gets day from date. | plugin | -| [`polars get-hour`](/commands/docs/polars_get-hour.md) | Gets hour from date. | plugin | -| [`polars get-minute`](/commands/docs/polars_get-minute.md) | Gets minute from date. | plugin | -| [`polars get-month`](/commands/docs/polars_get-month.md) | Gets month from date. | plugin | -| [`polars get-nanosecond`](/commands/docs/polars_get-nanosecond.md) | Gets nanosecond from date. | plugin | -| [`polars get-ordinal`](/commands/docs/polars_get-ordinal.md) | Gets ordinal from date. | plugin | -| [`polars get-second`](/commands/docs/polars_get-second.md) | Gets second from date. | plugin | -| [`polars get-week`](/commands/docs/polars_get-week.md) | Gets week from date. | plugin | -| [`polars get-weekday`](/commands/docs/polars_get-weekday.md) | Gets weekday from date. | plugin | -| [`polars get-year`](/commands/docs/polars_get-year.md) | Gets year from date. | plugin | -| [`polars group-by`](/commands/docs/polars_group-by.md) | Creates a group-by object that can be used for other aggregations. | plugin | -| [`polars implode`](/commands/docs/polars_implode.md) | Aggregates values into a list. | plugin | -| [`polars integer`](/commands/docs/polars_integer.md) | Converts a string column into a integer column | plugin | -| [`polars into-df`](/commands/docs/polars_into-df.md) | Converts a list, table or record into a dataframe. | plugin | -| [`polars into-lazy`](/commands/docs/polars_into-lazy.md) | Converts a dataframe into a lazy dataframe. | plugin | -| [`polars into-nu`](/commands/docs/polars_into-nu.md) | Converts a dataframe or an expression into nushell value for access and exploration. | plugin | -| [`polars is-duplicated`](/commands/docs/polars_is-duplicated.md) | Creates mask indicating duplicated values. | plugin | -| [`polars is-in`](/commands/docs/polars_is-in.md) | Creates an is-in expression or checks to see if the elements are contained in the right series | plugin | -| [`polars is-not-null`](/commands/docs/polars_is-not-null.md) | Creates mask where value is not null. | plugin | -| [`polars is-null`](/commands/docs/polars_is-null.md) | Creates mask where value is null. | plugin | -| [`polars is-unique`](/commands/docs/polars_is-unique.md) | Creates mask indicating unique values. | plugin | -| [`polars join`](/commands/docs/polars_join.md) | Joins a lazy frame with other lazy frame. | plugin | -| [`polars last`](/commands/docs/polars_last.md) | Creates new dataframe with tail rows or creates a last expression. | plugin | -| [`polars len`](/commands/docs/polars_len.md) | Return the number of rows in the context. This is similar to COUNT(*) in SQL. | plugin | -| [`polars lit`](/commands/docs/polars_lit.md) | Creates a literal expression. | plugin | -| [`polars lowercase`](/commands/docs/polars_lowercase.md) | Lowercase the strings in the column. | plugin | -| [`polars max`](/commands/docs/polars_max.md) | Creates a max expression or aggregates columns to their max value. | plugin | -| [`polars mean`](/commands/docs/polars_mean.md) | Creates a mean expression for an aggregation or aggregates columns to their mean value. | plugin | -| [`polars median`](/commands/docs/polars_median.md) | Median value from columns in a dataframe or creates expression for an aggregation | plugin | -| [`polars min`](/commands/docs/polars_min.md) | Creates a min expression or aggregates columns to their min value. | plugin | -| [`polars n-unique`](/commands/docs/polars_n-unique.md) | Counts unique values. | plugin | -| [`polars not`](/commands/docs/polars_not.md) | Inverts boolean mask. | plugin | -| [`polars open`](/commands/docs/polars_open.md) | Opens CSV, JSON, NDJSON/JSON lines, arrow, avro, or parquet file to create dataframe. A lazy dataframe will be created by default, if supported. | plugin | -| [`polars otherwise`](/commands/docs/polars_otherwise.md) | Completes a when expression. | plugin | -| [`polars pivot`](/commands/docs/polars_pivot.md) | Pivot a DataFrame from wide to long format. | plugin | -| [`polars profile`](/commands/docs/polars_profile.md) | Profile a lazy dataframe. This will run the query and return a record containing the materialized DataFrame and a DataFrame that contains profiling information of each node that is executed. - -The units of the timings are microseconds. | plugin | -| [`polars quantile`](/commands/docs/polars_quantile.md) | Aggregates the columns to the selected quantile. | plugin | -| [`polars query`](/commands/docs/polars_query.md) | Query dataframe using SQL. Note: The dataframe is always named 'df' in your query's from clause. | plugin | -| [`polars rename`](/commands/docs/polars_rename.md) | Rename a dataframe column. | plugin | -| [`polars replace`](/commands/docs/polars_replace.md) | Replace the leftmost (sub)string by a regex pattern. | plugin | -| [`polars replace-all`](/commands/docs/polars_replace-all.md) | Replace all (sub)strings by a regex pattern. | plugin | -| [`polars reverse`](/commands/docs/polars_reverse.md) | Reverses the LazyFrame | plugin | -| [`polars rolling`](/commands/docs/polars_rolling.md) | Rolling calculation for a series. | plugin | -| [`polars sample`](/commands/docs/polars_sample.md) | Create sample dataframe. | plugin | -| [`polars save`](/commands/docs/polars_save.md) | Saves a dataframe to disk. For lazy dataframes a sink operation will be used if the file type supports it (parquet, ipc/arrow, csv, and ndjson). | plugin | -| [`polars schema`](/commands/docs/polars_schema.md) | Show schema for a dataframe. | plugin | -| [`polars select`](/commands/docs/polars_select.md) | Selects columns from lazyframe. | plugin | -| [`polars set`](/commands/docs/polars_set.md) | Sets value where given mask is true. | plugin | -| [`polars set-with-idx`](/commands/docs/polars_set-with-idx.md) | Sets value in the given index. | plugin | -| [`polars shape`](/commands/docs/polars_shape.md) | Shows column and row size for a dataframe. | plugin | -| [`polars shift`](/commands/docs/polars_shift.md) | Shifts the values by a given period. | plugin | -| [`polars slice`](/commands/docs/polars_slice.md) | Creates new dataframe from a slice of rows. | plugin | -| [`polars sort-by`](/commands/docs/polars_sort-by.md) | Sorts a lazy dataframe based on expression(s). | plugin | -| [`polars std`](/commands/docs/polars_std.md) | Creates a std expression for an aggregation of std value from columns in a dataframe. | plugin | -| [`polars store-get`](/commands/docs/polars_store-get.md) | Gets a Dataframe or other object from the plugin cache. | plugin | -| [`polars store-ls`](/commands/docs/polars_store-ls.md) | Lists stored polars objects. | plugin | -| [`polars store-rm`](/commands/docs/polars_store-rm.md) | Removes a stored Dataframe or other object from the plugin cache. | plugin | -| [`polars str-join`](/commands/docs/polars_str-join.md) | Concatenates strings within a column or dataframes | plugin | -| [`polars str-lengths`](/commands/docs/polars_str-lengths.md) | Get lengths of all strings. | plugin | -| [`polars str-slice`](/commands/docs/polars_str-slice.md) | Slices the string from the start position until the selected length. | plugin | -| [`polars strftime`](/commands/docs/polars_strftime.md) | Formats date based on string rule. | plugin | -| [`polars sum`](/commands/docs/polars_sum.md) | Creates a sum expression for an aggregation or aggregates columns to their sum value. | plugin | -| [`polars summary`](/commands/docs/polars_summary.md) | For a dataframe, produces descriptive statistics (summary statistics) for its numeric columns. | plugin | -| [`polars take`](/commands/docs/polars_take.md) | Creates new dataframe using the given indices. | plugin | -| [`polars unique`](/commands/docs/polars_unique.md) | Returns unique values from a dataframe. | plugin | -| [`polars unnest`](/commands/docs/polars_unnest.md) | Decompose struct columns into separate columns for each of their fields. The new columns will be inserted into the dataframe at the location of the struct column. | plugin | -| [`polars unpivot`](/commands/docs/polars_unpivot.md) | Unpivot a DataFrame from wide to long format. | plugin | -| [`polars uppercase`](/commands/docs/polars_uppercase.md) | Uppercase the strings in the column. | plugin | -| [`polars value-counts`](/commands/docs/polars_value-counts.md) | Returns a dataframe with the counts for unique values in series. | plugin | -| [`polars var`](/commands/docs/polars_var.md) | Create a var expression for an aggregation. | plugin | -| [`polars when`](/commands/docs/polars_when.md) | Creates and modifies a when expression. | plugin | -| [`polars with-column`](/commands/docs/polars_with-column.md) | Adds a series to the dataframe. | plugin | \ No newline at end of file +| name | description | type | +| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | +| [`polars agg`](/commands/docs/polars_agg.md) | Performs a series of aggregations from a group-by. | plugin | +| [`polars agg-groups`](/commands/docs/polars_agg-groups.md) | Creates an agg_groups expression. | plugin | +| [`polars all-false`](/commands/docs/polars_all-false.md) | Returns true if all values are false. | plugin | +| [`polars all-true`](/commands/docs/polars_all-true.md) | Returns true if all values are true. | plugin | +| [`polars append`](/commands/docs/polars_append.md) | Appends a new dataframe. | plugin | +| [`polars arg-max`](/commands/docs/polars_arg-max.md) | Return index for max value in series. | plugin | +| [`polars arg-min`](/commands/docs/polars_arg-min.md) | Return index for min value in series. | plugin | +| [`polars arg-sort`](/commands/docs/polars_arg-sort.md) | Returns indexes for a sorted series. | plugin | +| [`polars arg-true`](/commands/docs/polars_arg-true.md) | Returns indexes where values are true. | plugin | +| [`polars arg-unique`](/commands/docs/polars_arg-unique.md) | Returns indexes for unique values. | plugin | +| [`polars arg-where`](/commands/docs/polars_arg-where.md) | Creates an expression that returns the arguments where expression is true. | plugin | +| [`polars as`](/commands/docs/polars_as.md) | Creates an alias expression. | plugin | +| [`polars as-date`](/commands/docs/polars_as-date.md) | Converts string to date. | plugin | +| [`polars as-datetime`](/commands/docs/polars_as-datetime.md) | Converts string to datetime. | plugin | +| [`polars cache`](/commands/docs/polars_cache.md) | Caches operations in a new LazyFrame. | plugin | +| [`polars cast`](/commands/docs/polars_cast.md) | Cast a column to a different dtype. | plugin | +| [`polars col`](/commands/docs/polars_col.md) | Creates a named column expression. | plugin | +| [`polars collect`](/commands/docs/polars_collect.md) | Collect lazy dataframe into eager dataframe. | plugin | +| [`polars columns`](/commands/docs/polars_columns.md) | Show dataframe columns. | plugin | +| [`polars concat`](/commands/docs/polars_concat.md) | Concatenate two or more dataframes. | plugin | +| [`polars concat-str`](/commands/docs/polars_concat-str.md) | Creates a concat string expression. | plugin | +| [`polars contains`](/commands/docs/polars_contains.md) | Checks if a pattern is contained in a string. | plugin | +| [`polars count`](/commands/docs/polars_count.md) | Returns the number of non-null values in the column. | plugin | +| [`polars count-null`](/commands/docs/polars_count-null.md) | Counts null values. | plugin | +| [`polars cumulative`](/commands/docs/polars_cumulative.md) | Cumulative calculation for a column or series. | plugin | +| [`polars datepart`](/commands/docs/polars_datepart.md) | Creates an expression for capturing the specified datepart in a column. | plugin | +| [`polars decimal`](/commands/docs/polars_decimal.md) | Converts a string column into a decimal column | plugin | +| [`polars drop`](/commands/docs/polars_drop.md) | Creates a new dataframe by dropping the selected columns. | plugin | +| [`polars drop-duplicates`](/commands/docs/polars_drop-duplicates.md) | Drops duplicate values in dataframe. | plugin | +| [`polars drop-nulls`](/commands/docs/polars_drop-nulls.md) | Drops null values in dataframe. | plugin | +| [`polars dummies`](/commands/docs/polars_dummies.md) | Creates a new dataframe with dummy variables. | plugin | +| [`polars explode`](/commands/docs/polars_explode.md) | Explodes a dataframe or creates a explode expression. | plugin | +| [`polars expr-not`](/commands/docs/polars_expr-not.md) | Creates a not expression. | plugin | +| [`polars fetch`](/commands/docs/polars_fetch.md) | Collects the lazyframe to the selected rows. | plugin | +| [`polars fill-nan`](/commands/docs/polars_fill-nan.md) | Replaces NaN values with the given expression. | plugin | +| [`polars fill-null`](/commands/docs/polars_fill-null.md) | Replaces NULL values with the given expression. | plugin | +| [`polars filter`](/commands/docs/polars_filter.md) | Filter dataframe based in expression. | plugin | +| [`polars filter-with`](/commands/docs/polars_filter-with.md) | Filters dataframe using a mask or expression as reference. | plugin | +| [`polars first`](/commands/docs/polars_first.md) | Show only the first number of rows or create a first expression | plugin | +| [`polars flatten`](/commands/docs/polars_flatten.md) | An alias for polars explode. | plugin | +| [`polars get`](/commands/docs/polars_get.md) | Creates dataframe with the selected columns. | plugin | +| [`polars get-day`](/commands/docs/polars_get-day.md) | Gets day from date. | plugin | +| [`polars get-hour`](/commands/docs/polars_get-hour.md) | Gets hour from date. | plugin | +| [`polars get-minute`](/commands/docs/polars_get-minute.md) | Gets minute from date. | plugin | +| [`polars get-month`](/commands/docs/polars_get-month.md) | Gets month from date. | plugin | +| [`polars get-nanosecond`](/commands/docs/polars_get-nanosecond.md) | Gets nanosecond from date. | plugin | +| [`polars get-ordinal`](/commands/docs/polars_get-ordinal.md) | Gets ordinal from date. | plugin | +| [`polars get-second`](/commands/docs/polars_get-second.md) | Gets second from date. | plugin | +| [`polars get-week`](/commands/docs/polars_get-week.md) | Gets week from date. | plugin | +| [`polars get-weekday`](/commands/docs/polars_get-weekday.md) | Gets weekday from date. | plugin | +| [`polars get-year`](/commands/docs/polars_get-year.md) | Gets year from date. | plugin | +| [`polars group-by`](/commands/docs/polars_group-by.md) | Creates a group-by object that can be used for other aggregations. | plugin | +| [`polars implode`](/commands/docs/polars_implode.md) | Aggregates values into a list. | plugin | +| [`polars integer`](/commands/docs/polars_integer.md) | Converts a string column into a integer column | plugin | +| [`polars into-df`](/commands/docs/polars_into-df.md) | Converts a list, table or record into a dataframe. | plugin | +| [`polars into-lazy`](/commands/docs/polars_into-lazy.md) | Converts a dataframe into a lazy dataframe. | plugin | +| [`polars into-nu`](/commands/docs/polars_into-nu.md) | Converts a dataframe or an expression into nushell value for access and exploration. | plugin | +| [`polars is-duplicated`](/commands/docs/polars_is-duplicated.md) | Creates mask indicating duplicated values. | plugin | +| [`polars is-in`](/commands/docs/polars_is-in.md) | Creates an is-in expression or checks to see if the elements are contained in the right series | plugin | +| [`polars is-not-null`](/commands/docs/polars_is-not-null.md) | Creates mask where value is not null. | plugin | +| [`polars is-null`](/commands/docs/polars_is-null.md) | Creates mask where value is null. | plugin | +| [`polars is-unique`](/commands/docs/polars_is-unique.md) | Creates mask indicating unique values. | plugin | +| [`polars join`](/commands/docs/polars_join.md) | Joins a lazy frame with other lazy frame. | plugin | +| [`polars last`](/commands/docs/polars_last.md) | Creates new dataframe with tail rows or creates a last expression. | plugin | +| [`polars len`](/commands/docs/polars_len.md) | Return the number of rows in the context. This is similar to COUNT(*) in SQL. | plugin | +| [`polars lit`](/commands/docs/polars_lit.md) | Creates a literal expression. | plugin | +| [`polars lowercase`](/commands/docs/polars_lowercase.md) | Lowercase the strings in the column. | plugin | +| [`polars max`](/commands/docs/polars_max.md) | Creates a max expression or aggregates columns to their max value. | plugin | +| [`polars mean`](/commands/docs/polars_mean.md) | Creates a mean expression for an aggregation or aggregates columns to their mean value. | plugin | +| [`polars median`](/commands/docs/polars_median.md) | Median value from columns in a dataframe or creates expression for an aggregation | plugin | +| [`polars min`](/commands/docs/polars_min.md) | Creates a min expression or aggregates columns to their min value. | plugin | +| [`polars n-unique`](/commands/docs/polars_n-unique.md) | Counts unique values. | plugin | +| [`polars not`](/commands/docs/polars_not.md) | Inverts boolean mask. | plugin | +| [`polars open`](/commands/docs/polars_open.md) | Opens CSV, JSON, NDJSON/JSON lines, arrow, avro, or parquet file to create dataframe. A lazy dataframe will be created by default, if supported. | plugin | +| [`polars otherwise`](/commands/docs/polars_otherwise.md) | Completes a when expression. | plugin | +| [`polars pivot`](/commands/docs/polars_pivot.md) | Pivot a DataFrame from wide to long format. | plugin | +| [`polars profile`](/commands/docs/polars_profile.md) | Profile a lazy dataframe. | plugin | +| [`polars quantile`](/commands/docs/polars_quantile.md) | Aggregates the columns to the selected quantile. | plugin | +| [`polars query`](/commands/docs/polars_query.md) | Query dataframe using SQL. Note: The dataframe is always named 'df' in your query's from clause. | plugin | +| [`polars rename`](/commands/docs/polars_rename.md) | Rename a dataframe column. | plugin | +| [`polars replace`](/commands/docs/polars_replace.md) | Replace the leftmost (sub)string by a regex pattern. | plugin | +| [`polars replace-all`](/commands/docs/polars_replace-all.md) | Replace all (sub)strings by a regex pattern. | plugin | +| [`polars reverse`](/commands/docs/polars_reverse.md) | Reverses the LazyFrame | plugin | +| [`polars rolling`](/commands/docs/polars_rolling.md) | Rolling calculation for a series. | plugin | +| [`polars sample`](/commands/docs/polars_sample.md) | Create sample dataframe. | plugin | +| [`polars save`](/commands/docs/polars_save.md) | Saves a dataframe to disk. For lazy dataframes a sink operation will be used if the file type supports it (parquet, ipc/arrow, csv, and ndjson). | plugin | +| [`polars schema`](/commands/docs/polars_schema.md) | Show schema for a dataframe. | plugin | +| [`polars select`](/commands/docs/polars_select.md) | Selects columns from lazyframe. | plugin | +| [`polars set`](/commands/docs/polars_set.md) | Sets value where given mask is true. | plugin | +| [`polars set-with-idx`](/commands/docs/polars_set-with-idx.md) | Sets value in the given index. | plugin | +| [`polars shape`](/commands/docs/polars_shape.md) | Shows column and row size for a dataframe. | plugin | +| [`polars shift`](/commands/docs/polars_shift.md) | Shifts the values by a given period. | plugin | +| [`polars slice`](/commands/docs/polars_slice.md) | Creates new dataframe from a slice of rows. | plugin | +| [`polars sort-by`](/commands/docs/polars_sort-by.md) | Sorts a lazy dataframe based on expression(s). | plugin | +| [`polars std`](/commands/docs/polars_std.md) | Creates a std expression for an aggregation of std value from columns in a dataframe. | plugin | +| [`polars store-get`](/commands/docs/polars_store-get.md) | Gets a Dataframe or other object from the plugin cache. | plugin | +| [`polars store-ls`](/commands/docs/polars_store-ls.md) | Lists stored polars objects. | plugin | +| [`polars store-rm`](/commands/docs/polars_store-rm.md) | Removes a stored Dataframe or other object from the plugin cache. | plugin | +| [`polars str-join`](/commands/docs/polars_str-join.md) | Concatenates strings within a column or dataframes | plugin | +| [`polars str-lengths`](/commands/docs/polars_str-lengths.md) | Get lengths of all strings. | plugin | +| [`polars str-slice`](/commands/docs/polars_str-slice.md) | Slices the string from the start position until the selected length. | plugin | +| [`polars strftime`](/commands/docs/polars_strftime.md) | Formats date based on string rule. | plugin | +| [`polars sum`](/commands/docs/polars_sum.md) | Creates a sum expression for an aggregation or aggregates columns to their sum value. | plugin | +| [`polars summary`](/commands/docs/polars_summary.md) | For a dataframe, produces descriptive statistics (summary statistics) for its numeric columns. | plugin | +| [`polars take`](/commands/docs/polars_take.md) | Creates new dataframe using the given indices. | plugin | +| [`polars unique`](/commands/docs/polars_unique.md) | Returns unique values from a dataframe. | plugin | +| [`polars unnest`](/commands/docs/polars_unnest.md) | Decompose struct columns into separate columns for each of their fields. The new columns will be inserted into the dataframe at the location of the struct column. | plugin | +| [`polars unpivot`](/commands/docs/polars_unpivot.md) | Unpivot a DataFrame from wide to long format. | plugin | +| [`polars uppercase`](/commands/docs/polars_uppercase.md) | Uppercase the strings in the column. | plugin | +| [`polars value-counts`](/commands/docs/polars_value-counts.md) | Returns a dataframe with the counts for unique values in series. | plugin | +| [`polars var`](/commands/docs/polars_var.md) | Create a var expression for an aggregation. | plugin | +| [`polars when`](/commands/docs/polars_when.md) | Creates and modifies a when expression. | plugin | +| [`polars with-column`](/commands/docs/polars_with-column.md) | Adds a series to the dataframe. | plugin | \ No newline at end of file diff --git a/commands/docs/polars_agg-groups.md b/commands/docs/polars_agg-groups.md index f6033e3eb5c..052356ef1a9 100644 --- a/commands/docs/polars_agg-groups.md +++ b/commands/docs/polars_agg-groups.md @@ -2,7 +2,7 @@ title: polars agg-groups categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates an agg_groups expression. usage: | @@ -34,7 +34,7 @@ See the [Plugins](/book/plugins.html) chapter in the book for more information. ## Examples -Get the groiup index of the group by operations. +Get the group index of the group by operations. ```nu > [[group value]; [one 94] [one 95] [one 96] [two 97] [two 98] [two 99]] | polars into-df diff --git a/commands/docs/polars_agg.md b/commands/docs/polars_agg.md index f782533999f..b292252bd24 100644 --- a/commands/docs/polars_agg.md +++ b/commands/docs/polars_agg.md @@ -2,7 +2,7 @@ title: polars agg categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Performs a series of aggregations from a group-by. usage: | diff --git a/commands/docs/polars_all-false.md b/commands/docs/polars_all-false.md index 22c95f942ae..686f339b02f 100644 --- a/commands/docs/polars_all-false.md +++ b/commands/docs/polars_all-false.md @@ -2,7 +2,7 @@ title: polars all-false categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Returns true if all values are false. usage: | diff --git a/commands/docs/polars_all-true.md b/commands/docs/polars_all-true.md index 8a6823d4b57..3593755598f 100644 --- a/commands/docs/polars_all-true.md +++ b/commands/docs/polars_all-true.md @@ -2,7 +2,7 @@ title: polars all-true categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Returns true if all values are true. usage: | diff --git a/commands/docs/polars_append.md b/commands/docs/polars_append.md index 21c6e52d92e..cd05ec5c22e 100644 --- a/commands/docs/polars_append.md +++ b/commands/docs/polars_append.md @@ -2,7 +2,7 @@ title: polars append categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Appends a new dataframe. usage: | diff --git a/commands/docs/polars_arg-max.md b/commands/docs/polars_arg-max.md index b4a3165b437..afd48980a5e 100644 --- a/commands/docs/polars_arg-max.md +++ b/commands/docs/polars_arg-max.md @@ -2,7 +2,7 @@ title: polars arg-max categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Return index for max value in series. usage: | diff --git a/commands/docs/polars_arg-min.md b/commands/docs/polars_arg-min.md index fb0d482d845..86cf78b6005 100644 --- a/commands/docs/polars_arg-min.md +++ b/commands/docs/polars_arg-min.md @@ -2,7 +2,7 @@ title: polars arg-min categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Return index for min value in series. usage: | diff --git a/commands/docs/polars_arg-sort.md b/commands/docs/polars_arg-sort.md index e588265f48b..43c6b7be4b9 100644 --- a/commands/docs/polars_arg-sort.md +++ b/commands/docs/polars_arg-sort.md @@ -2,7 +2,7 @@ title: polars arg-sort categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Returns indexes for a sorted series. usage: | diff --git a/commands/docs/polars_arg-true.md b/commands/docs/polars_arg-true.md index 13f570610b2..221b5bcc3f3 100644 --- a/commands/docs/polars_arg-true.md +++ b/commands/docs/polars_arg-true.md @@ -2,7 +2,7 @@ title: polars arg-true categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Returns indexes where values are true. usage: | diff --git a/commands/docs/polars_arg-unique.md b/commands/docs/polars_arg-unique.md index ec72c9ba28a..e8703cf46b0 100644 --- a/commands/docs/polars_arg-unique.md +++ b/commands/docs/polars_arg-unique.md @@ -2,7 +2,7 @@ title: polars arg-unique categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Returns indexes for unique values. usage: | diff --git a/commands/docs/polars_arg-where.md b/commands/docs/polars_arg-where.md index 256447c7209..139df390e1c 100644 --- a/commands/docs/polars_arg-where.md +++ b/commands/docs/polars_arg-where.md @@ -2,7 +2,7 @@ title: polars arg-where categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Creates an expression that returns the arguments where expression is true. usage: | diff --git a/commands/docs/polars_as-date.md b/commands/docs/polars_as-date.md index 01f019fb616..ad138efe25d 100644 --- a/commands/docs/polars_as-date.md +++ b/commands/docs/polars_as-date.md @@ -2,7 +2,7 @@ title: polars as-date categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Converts string to date. usage: | diff --git a/commands/docs/polars_as-datetime.md b/commands/docs/polars_as-datetime.md index a064e44f396..e23aa0d993a 100644 --- a/commands/docs/polars_as-datetime.md +++ b/commands/docs/polars_as-datetime.md @@ -2,7 +2,7 @@ title: polars as-datetime categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Converts string to datetime. usage: | diff --git a/commands/docs/polars_as.md b/commands/docs/polars_as.md index c1c678374da..b71b00a6caa 100644 --- a/commands/docs/polars_as.md +++ b/commands/docs/polars_as.md @@ -2,7 +2,7 @@ title: polars as categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Creates an alias expression. usage: | diff --git a/commands/docs/polars_cache.md b/commands/docs/polars_cache.md index f426ac8ed01..45ba587fbd8 100644 --- a/commands/docs/polars_cache.md +++ b/commands/docs/polars_cache.md @@ -2,7 +2,7 @@ title: polars cache categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Caches operations in a new LazyFrame. usage: | diff --git a/commands/docs/polars_cast.md b/commands/docs/polars_cast.md index 7f1f3e530b5..b98cbdbe169 100644 --- a/commands/docs/polars_cast.md +++ b/commands/docs/polars_cast.md @@ -2,7 +2,7 @@ title: polars cast categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Cast a column to a different dtype. usage: | diff --git a/commands/docs/polars_col.md b/commands/docs/polars_col.md index a23541059bc..0d562ff9513 100644 --- a/commands/docs/polars_col.md +++ b/commands/docs/polars_col.md @@ -2,7 +2,7 @@ title: polars col categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Creates a named column expression. usage: | diff --git a/commands/docs/polars_collect.md b/commands/docs/polars_collect.md index 45265cfa922..9d18fa6d726 100644 --- a/commands/docs/polars_collect.md +++ b/commands/docs/polars_collect.md @@ -2,7 +2,7 @@ title: polars collect categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Collect lazy dataframe into eager dataframe. usage: | diff --git a/commands/docs/polars_columns.md b/commands/docs/polars_columns.md index f0cc70573c5..e022981959c 100644 --- a/commands/docs/polars_columns.md +++ b/commands/docs/polars_columns.md @@ -2,7 +2,7 @@ title: polars columns categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Show dataframe columns. usage: | diff --git a/commands/docs/polars_concat-str.md b/commands/docs/polars_concat-str.md index 4fdc6f55ed9..6d0cdc6d889 100644 --- a/commands/docs/polars_concat-str.md +++ b/commands/docs/polars_concat-str.md @@ -2,7 +2,7 @@ title: polars concat-str categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Creates a concat string expression. usage: | diff --git a/commands/docs/polars_concat.md b/commands/docs/polars_concat.md index 45b495714bd..bd5dad14b00 100644 --- a/commands/docs/polars_concat.md +++ b/commands/docs/polars_concat.md @@ -2,7 +2,7 @@ title: polars concat categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Concatenate two or more dataframes. usage: | diff --git a/commands/docs/polars_contains.md b/commands/docs/polars_contains.md index 608efc15028..c06a0c9785c 100644 --- a/commands/docs/polars_contains.md +++ b/commands/docs/polars_contains.md @@ -2,7 +2,7 @@ title: polars contains categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Checks if a pattern is contained in a string. usage: | diff --git a/commands/docs/polars_count-null.md b/commands/docs/polars_count-null.md index a5b4dd5155c..13d4aa0b2f8 100644 --- a/commands/docs/polars_count-null.md +++ b/commands/docs/polars_count-null.md @@ -2,7 +2,7 @@ title: polars count-null categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Counts null values. usage: | diff --git a/commands/docs/polars_count.md b/commands/docs/polars_count.md index 4fae4c18f9f..4ae4ac04814 100644 --- a/commands/docs/polars_count.md +++ b/commands/docs/polars_count.md @@ -2,7 +2,7 @@ title: polars count categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Returns the number of non-null values in the column. usage: | diff --git a/commands/docs/polars_cumulative.md b/commands/docs/polars_cumulative.md index dc2947832df..910245d27a8 100644 --- a/commands/docs/polars_cumulative.md +++ b/commands/docs/polars_cumulative.md @@ -2,7 +2,7 @@ title: polars cumulative categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Cumulative calculation for a column or series. usage: | diff --git a/commands/docs/polars_datepart.md b/commands/docs/polars_datepart.md index e0bf65d976b..5dfedd89662 100644 --- a/commands/docs/polars_datepart.md +++ b/commands/docs/polars_datepart.md @@ -2,7 +2,7 @@ title: polars datepart categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Creates an expression for capturing the specified datepart in a column. usage: | @@ -59,10 +59,10 @@ Creates an expression to capture multiple date parts (polars col datetime | polars datepart minute | polars as datetime_minute ), (polars col datetime | polars datepart second | polars as datetime_second ), (polars col datetime | polars datepart nanosecond | polars as datetime_ns ) ] -╭───┬─────────────┬───────────────┬────────────────┬──────────────┬───────────────┬─────────────────┬─────────────────┬─────────────╮ -│ # │ datetime │ datetime_year │ datetime_month │ datetime_day │ datetime_hour │ datetime_minute │ datetime_second │ datetime_ns │ -├───┼─────────────┼───────────────┼────────────────┼──────────────┼───────────────┼─────────────────┼─────────────────┼─────────────┤ -│ 0 │ 2 years ago │ 2021 │ 12 │ 30 │ 1 │ 2 │ 3 │ 123456789 │ -╰───┴─────────────┴───────────────┴────────────────┴──────────────┴───────────────┴─────────────────┴─────────────────┴─────────────╯ +╭─────┬───────────────┬─────────────────┬──────────────────┬───────────────┬────────────────┬──────────────────┬──────╮ +│ # │ datetime │ datetime_year │ datetime_month │ datetime_day │ datetime_hour │ datetime_minute │ ... │ +├─────┼───────────────┼─────────────────┼──────────────────┼───────────────┼────────────────┼──────────────────┼──────┤ +│ 0 │ 2 years ago │ 2021 │ 12 │ 30 │ 1 │ 2 │ ... │ +╰─────┴───────────────┴─────────────────┴──────────────────┴───────────────┴────────────────┴──────────────────┴──────╯ ``` diff --git a/commands/docs/polars_decimal.md b/commands/docs/polars_decimal.md index cb872e0b4e2..91a0e7388b0 100644 --- a/commands/docs/polars_decimal.md +++ b/commands/docs/polars_decimal.md @@ -2,7 +2,7 @@ title: polars decimal categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Converts a string column into a decimal column usage: | diff --git a/commands/docs/polars_drop-duplicates.md b/commands/docs/polars_drop-duplicates.md index b803fb6a095..5496bf71d82 100644 --- a/commands/docs/polars_drop-duplicates.md +++ b/commands/docs/polars_drop-duplicates.md @@ -2,7 +2,7 @@ title: polars drop-duplicates categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Drops duplicate values in dataframe. usage: | diff --git a/commands/docs/polars_drop-nulls.md b/commands/docs/polars_drop-nulls.md index 387b85367e8..39a9b209657 100644 --- a/commands/docs/polars_drop-nulls.md +++ b/commands/docs/polars_drop-nulls.md @@ -2,7 +2,7 @@ title: polars drop-nulls categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Drops null values in dataframe. usage: | diff --git a/commands/docs/polars_drop.md b/commands/docs/polars_drop.md index 4f8b2f502bb..429b9c2628d 100644 --- a/commands/docs/polars_drop.md +++ b/commands/docs/polars_drop.md @@ -2,7 +2,7 @@ title: polars drop categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates a new dataframe by dropping the selected columns. usage: | diff --git a/commands/docs/polars_dummies.md b/commands/docs/polars_dummies.md index 24e5156ee97..38fb6296afb 100644 --- a/commands/docs/polars_dummies.md +++ b/commands/docs/polars_dummies.md @@ -2,7 +2,7 @@ title: polars dummies categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates a new dataframe with dummy variables. usage: | diff --git a/commands/docs/polars_explode.md b/commands/docs/polars_explode.md index 071e7eab4d5..8b7da366ee6 100644 --- a/commands/docs/polars_explode.md +++ b/commands/docs/polars_explode.md @@ -2,7 +2,7 @@ title: polars explode categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Explodes a dataframe or creates a explode expression. usage: | diff --git a/commands/docs/polars_expr-not.md b/commands/docs/polars_expr-not.md index 7b84bad569d..27619e1229a 100644 --- a/commands/docs/polars_expr-not.md +++ b/commands/docs/polars_expr-not.md @@ -2,7 +2,7 @@ title: polars expr-not categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates a not expression. usage: | diff --git a/commands/docs/polars_fetch.md b/commands/docs/polars_fetch.md index 6f386b00d6b..137280959f3 100644 --- a/commands/docs/polars_fetch.md +++ b/commands/docs/polars_fetch.md @@ -2,7 +2,7 @@ title: polars fetch categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Collects the lazyframe to the selected rows. usage: | diff --git a/commands/docs/polars_fill-nan.md b/commands/docs/polars_fill-nan.md index 2d8ff5b6ff1..755c1602c63 100644 --- a/commands/docs/polars_fill-nan.md +++ b/commands/docs/polars_fill-nan.md @@ -2,7 +2,7 @@ title: polars fill-nan categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Replaces NaN values with the given expression. usage: | diff --git a/commands/docs/polars_fill-null.md b/commands/docs/polars_fill-null.md index 5990ee09291..e5247074f6b 100644 --- a/commands/docs/polars_fill-null.md +++ b/commands/docs/polars_fill-null.md @@ -2,7 +2,7 @@ title: polars fill-null categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Replaces NULL values with the given expression. usage: | diff --git a/commands/docs/polars_filter-with.md b/commands/docs/polars_filter-with.md index f190f3f6774..d99c691a5fa 100644 --- a/commands/docs/polars_filter-with.md +++ b/commands/docs/polars_filter-with.md @@ -2,7 +2,7 @@ title: polars filter-with categories: | dataframe or lazyframe -version: 0.100.0 +version: 0.101.0 dataframe_or_lazyframe: | Filters dataframe using a mask or expression as reference. usage: | diff --git a/commands/docs/polars_filter.md b/commands/docs/polars_filter.md index ab82c7d3c1a..8bb267dc98f 100644 --- a/commands/docs/polars_filter.md +++ b/commands/docs/polars_filter.md @@ -2,7 +2,7 @@ title: polars filter categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Filter dataframe based in expression. usage: | diff --git a/commands/docs/polars_first.md b/commands/docs/polars_first.md index 6f95f7cb4ec..fa6103c751b 100644 --- a/commands/docs/polars_first.md +++ b/commands/docs/polars_first.md @@ -2,7 +2,7 @@ title: polars first categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Show only the first number of rows or create a first expression usage: | diff --git a/commands/docs/polars_flatten.md b/commands/docs/polars_flatten.md index 367f0915d52..334f854f445 100644 --- a/commands/docs/polars_flatten.md +++ b/commands/docs/polars_flatten.md @@ -2,7 +2,7 @@ title: polars flatten categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | An alias for polars explode. usage: | diff --git a/commands/docs/polars_get-day.md b/commands/docs/polars_get-day.md index 7342b8f85a0..c6077d215e5 100644 --- a/commands/docs/polars_get-day.md +++ b/commands/docs/polars_get-day.md @@ -2,7 +2,7 @@ title: polars get-day categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets day from date. usage: | diff --git a/commands/docs/polars_get-hour.md b/commands/docs/polars_get-hour.md index 6a288f8e18e..fee59c9c396 100644 --- a/commands/docs/polars_get-hour.md +++ b/commands/docs/polars_get-hour.md @@ -2,7 +2,7 @@ title: polars get-hour categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets hour from date. usage: | diff --git a/commands/docs/polars_get-minute.md b/commands/docs/polars_get-minute.md index 862f54a2ef5..46fc5ea4679 100644 --- a/commands/docs/polars_get-minute.md +++ b/commands/docs/polars_get-minute.md @@ -2,7 +2,7 @@ title: polars get-minute categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets minute from date. usage: | diff --git a/commands/docs/polars_get-month.md b/commands/docs/polars_get-month.md index 964c6cec05c..30eecef781b 100644 --- a/commands/docs/polars_get-month.md +++ b/commands/docs/polars_get-month.md @@ -2,7 +2,7 @@ title: polars get-month categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets month from date. usage: | diff --git a/commands/docs/polars_get-nanosecond.md b/commands/docs/polars_get-nanosecond.md index 7428f282227..ba88e2d53e8 100644 --- a/commands/docs/polars_get-nanosecond.md +++ b/commands/docs/polars_get-nanosecond.md @@ -2,7 +2,7 @@ title: polars get-nanosecond categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets nanosecond from date. usage: | diff --git a/commands/docs/polars_get-ordinal.md b/commands/docs/polars_get-ordinal.md index e0e32ddf491..75b16320828 100644 --- a/commands/docs/polars_get-ordinal.md +++ b/commands/docs/polars_get-ordinal.md @@ -2,7 +2,7 @@ title: polars get-ordinal categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets ordinal from date. usage: | diff --git a/commands/docs/polars_get-second.md b/commands/docs/polars_get-second.md index 8df36be16d5..809fcdc7e6d 100644 --- a/commands/docs/polars_get-second.md +++ b/commands/docs/polars_get-second.md @@ -2,7 +2,7 @@ title: polars get-second categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets second from date. usage: | diff --git a/commands/docs/polars_get-week.md b/commands/docs/polars_get-week.md index 41ae6ca44cc..29f13188b02 100644 --- a/commands/docs/polars_get-week.md +++ b/commands/docs/polars_get-week.md @@ -2,7 +2,7 @@ title: polars get-week categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets week from date. usage: | diff --git a/commands/docs/polars_get-weekday.md b/commands/docs/polars_get-weekday.md index 08bfc2366b1..0cd51c9bb65 100644 --- a/commands/docs/polars_get-weekday.md +++ b/commands/docs/polars_get-weekday.md @@ -2,7 +2,7 @@ title: polars get-weekday categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets weekday from date. usage: | diff --git a/commands/docs/polars_get-year.md b/commands/docs/polars_get-year.md index c7db47089f0..7be5f375b69 100644 --- a/commands/docs/polars_get-year.md +++ b/commands/docs/polars_get-year.md @@ -2,7 +2,7 @@ title: polars get-year categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets year from date. usage: | diff --git a/commands/docs/polars_get.md b/commands/docs/polars_get.md index 41e92aa5a8d..f286e31114c 100644 --- a/commands/docs/polars_get.md +++ b/commands/docs/polars_get.md @@ -2,7 +2,7 @@ title: polars get categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates dataframe with the selected columns. usage: | diff --git a/commands/docs/polars_group-by.md b/commands/docs/polars_group-by.md index 161a7655d42..2827cffb38c 100644 --- a/commands/docs/polars_group-by.md +++ b/commands/docs/polars_group-by.md @@ -2,7 +2,7 @@ title: polars group-by categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Creates a group-by object that can be used for other aggregations. usage: | diff --git a/commands/docs/polars_implode.md b/commands/docs/polars_implode.md index c5ab8a38fdc..d6eb30d1f4c 100644 --- a/commands/docs/polars_implode.md +++ b/commands/docs/polars_implode.md @@ -2,7 +2,7 @@ title: polars implode categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Aggregates values into a list. usage: | diff --git a/commands/docs/polars_integer.md b/commands/docs/polars_integer.md index 6f5624fe6ef..5965943e8c7 100644 --- a/commands/docs/polars_integer.md +++ b/commands/docs/polars_integer.md @@ -2,7 +2,7 @@ title: polars integer categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Converts a string column into a integer column usage: | diff --git a/commands/docs/polars_into-df.md b/commands/docs/polars_into-df.md index 7fc18e5bc65..d8ef326623f 100644 --- a/commands/docs/polars_into-df.md +++ b/commands/docs/polars_into-df.md @@ -2,7 +2,7 @@ title: polars into-df categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Converts a list, table or record into a dataframe. usage: | diff --git a/commands/docs/polars_into-lazy.md b/commands/docs/polars_into-lazy.md index 2df2dbaf263..8e6fbacbbba 100644 --- a/commands/docs/polars_into-lazy.md +++ b/commands/docs/polars_into-lazy.md @@ -2,7 +2,7 @@ title: polars into-lazy categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Converts a dataframe into a lazy dataframe. usage: | diff --git a/commands/docs/polars_into-nu.md b/commands/docs/polars_into-nu.md index 0248a9eb847..17d512ec9da 100644 --- a/commands/docs/polars_into-nu.md +++ b/commands/docs/polars_into-nu.md @@ -2,7 +2,7 @@ title: polars into-nu categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Converts a dataframe or an expression into nushell value for access and exploration. usage: | diff --git a/commands/docs/polars_is-duplicated.md b/commands/docs/polars_is-duplicated.md index 24537dbba22..38bfd615065 100644 --- a/commands/docs/polars_is-duplicated.md +++ b/commands/docs/polars_is-duplicated.md @@ -2,7 +2,7 @@ title: polars is-duplicated categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates mask indicating duplicated values. usage: | diff --git a/commands/docs/polars_is-in.md b/commands/docs/polars_is-in.md index 09383f33460..4d93fa9f2d3 100644 --- a/commands/docs/polars_is-in.md +++ b/commands/docs/polars_is-in.md @@ -2,7 +2,7 @@ title: polars is-in categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Creates an is-in expression or checks to see if the elements are contained in the right series usage: | diff --git a/commands/docs/polars_is-not-null.md b/commands/docs/polars_is-not-null.md index d2b751c817b..25e70891a63 100644 --- a/commands/docs/polars_is-not-null.md +++ b/commands/docs/polars_is-not-null.md @@ -2,7 +2,7 @@ title: polars is-not-null categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates mask where value is not null. usage: | diff --git a/commands/docs/polars_is-null.md b/commands/docs/polars_is-null.md index cbde451b402..d6cc5be2b12 100644 --- a/commands/docs/polars_is-null.md +++ b/commands/docs/polars_is-null.md @@ -2,7 +2,7 @@ title: polars is-null categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates mask where value is null. usage: | diff --git a/commands/docs/polars_is-unique.md b/commands/docs/polars_is-unique.md index 4018f36ec88..0d85c1b32df 100644 --- a/commands/docs/polars_is-unique.md +++ b/commands/docs/polars_is-unique.md @@ -2,7 +2,7 @@ title: polars is-unique categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates mask indicating unique values. usage: | diff --git a/commands/docs/polars_join.md b/commands/docs/polars_join.md index c0f677b9ac5..53d3a75a1b5 100644 --- a/commands/docs/polars_join.md +++ b/commands/docs/polars_join.md @@ -2,7 +2,7 @@ title: polars join categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Joins a lazy frame with other lazy frame. usage: | @@ -31,6 +31,7 @@ See the [Plugins](/book/plugins.html) chapter in the book for more information. - `--left, -l`: left join between lazyframes - `--full, -f`: full join between lazyframes - `--cross, -c`: cross join between lazyframes + - `--coalesce-columns`: Sets the join coalesce strategy to colesce columns. Most useful when used with --full, which will not otherwise coalesce. - `--suffix, -s {string}`: Suffix to use on columns with same name ## Parameters @@ -50,8 +51,8 @@ See the [Plugins](/book/plugins.html) chapter in the book for more information. Join two lazy dataframes ```nu -> let df_a = ([[a b c];[1 "a" 0] [2 "b" 1] [1 "c" 2] [1 "c" 3]] | polars into-lazy); - let df_b = ([["foo" "bar" "ham"];[1 "a" "let"] [2 "c" "var"] [3 "c" "const"]] | polars into-lazy); +> let df_a = ([[a b c];[1 "a" 0] [2 "b" 1] [1 "c" 2] [1 "c" 3]] | polars into-lazy) + let df_b = ([["foo" "bar" "ham"];[1 "a" "let"] [2 "c" "var"] [3 "c" "const"]] | polars into-lazy) $df_a | polars join $df_b a foo | polars collect ╭───┬───┬───┬───┬─────┬─────╮ │ # │ a │ b │ c │ bar │ ham │ @@ -66,8 +67,8 @@ Join two lazy dataframes Join one eager dataframe with a lazy dataframe ```nu -> let df_a = ([[a b c];[1 "a" 0] [2 "b" 1] [1 "c" 2] [1 "c" 3]] | polars into-df); - let df_b = ([["foo" "bar" "ham"];[1 "a" "let"] [2 "c" "var"] [3 "c" "const"]] | polars into-lazy); +> let df_a = ([[a b c];[1 "a" 0] [2 "b" 1] [1 "c" 2] [1 "c" 3]] | polars into-df) + let df_b = ([["foo" "bar" "ham"];[1 "a" "let"] [2 "c" "var"] [3 "c" "const"]] | polars into-lazy) $df_a | polars join $df_b a foo ╭───┬───┬───┬───┬─────┬─────╮ │ # │ a │ b │ c │ bar │ ham │ @@ -79,3 +80,36 @@ Join one eager dataframe with a lazy dataframe ╰───┴───┴───┴───┴─────┴─────╯ ``` + +Perform a full join of two dataframes and coalesce columns +```nu +> let table1 = [[A B]; ["common" "common"] ["table1" "only"]] | polars into-df + let table2 = [[A C]; ["common" "common"] ["table2" "only"]] | polars into-df + $table1 | polars join -f $table2 --coalesce-columns A A +╭───┬────────┬────────┬────────╮ +│ # │ A │ B │ C │ +├───┼────────┼────────┼────────┤ +│ 0 │ common │ common │ common │ +│ 1 │ table2 │ │ only │ +│ 2 │ table1 │ only │ │ +╰───┴────────┴────────┴────────╯ + +``` + +Join one eager dataframe with another using a cross join +```nu +> let tokens = [[monopoly_token]; [hat] [shoe] [boat]] | polars into-df + let players = [[name, cash]; [Alice, 78] [Bob, 135]] | polars into-df + $players | polars select (polars col name) | polars join --cross $tokens | polars collect +╭───┬───────┬────────────────╮ +│ # │ name │ monopoly_token │ +├───┼───────┼────────────────┤ +│ 0 │ Alice │ hat │ +│ 1 │ Alice │ shoe │ +│ 2 │ Alice │ boat │ +│ 3 │ Bob │ hat │ +│ 4 │ Bob │ shoe │ +│ 5 │ Bob │ boat │ +╰───┴───────┴────────────────╯ + +``` diff --git a/commands/docs/polars_last.md b/commands/docs/polars_last.md index 465b4d36764..cd0e9483802 100644 --- a/commands/docs/polars_last.md +++ b/commands/docs/polars_last.md @@ -2,7 +2,7 @@ title: polars last categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates new dataframe with tail rows or creates a last expression. usage: | diff --git a/commands/docs/polars_len.md b/commands/docs/polars_len.md index 3c1dbe52213..e499b577bae 100644 --- a/commands/docs/polars_len.md +++ b/commands/docs/polars_len.md @@ -2,7 +2,7 @@ title: polars len categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Return the number of rows in the context. This is similar to COUNT(*) in SQL. usage: | diff --git a/commands/docs/polars_lit.md b/commands/docs/polars_lit.md index 53d23410045..a5b2efa327b 100644 --- a/commands/docs/polars_lit.md +++ b/commands/docs/polars_lit.md @@ -2,7 +2,7 @@ title: polars lit categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Creates a literal expression. usage: | diff --git a/commands/docs/polars_lowercase.md b/commands/docs/polars_lowercase.md index 50a0978065c..a7e34bbe853 100644 --- a/commands/docs/polars_lowercase.md +++ b/commands/docs/polars_lowercase.md @@ -2,7 +2,7 @@ title: polars lowercase categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Lowercase the strings in the column. usage: | diff --git a/commands/docs/polars_max.md b/commands/docs/polars_max.md index 93fe80f56bc..1417f1af1d1 100644 --- a/commands/docs/polars_max.md +++ b/commands/docs/polars_max.md @@ -2,7 +2,7 @@ title: polars max categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates a max expression or aggregates columns to their max value. usage: | diff --git a/commands/docs/polars_mean.md b/commands/docs/polars_mean.md index 9ab16bc825c..7777a7e5e99 100644 --- a/commands/docs/polars_mean.md +++ b/commands/docs/polars_mean.md @@ -2,7 +2,7 @@ title: polars mean categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates a mean expression for an aggregation or aggregates columns to their mean value. usage: | diff --git a/commands/docs/polars_median.md b/commands/docs/polars_median.md index 40c888d2793..cf1e9e8ae59 100644 --- a/commands/docs/polars_median.md +++ b/commands/docs/polars_median.md @@ -2,7 +2,7 @@ title: polars median categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Median value from columns in a dataframe or creates expression for an aggregation usage: | diff --git a/commands/docs/polars_min.md b/commands/docs/polars_min.md index aeb249899fa..e33618c3603 100644 --- a/commands/docs/polars_min.md +++ b/commands/docs/polars_min.md @@ -2,7 +2,7 @@ title: polars min categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates a min expression or aggregates columns to their min value. usage: | diff --git a/commands/docs/polars_n-unique.md b/commands/docs/polars_n-unique.md index 54587910a5a..103c98efa9a 100644 --- a/commands/docs/polars_n-unique.md +++ b/commands/docs/polars_n-unique.md @@ -2,7 +2,7 @@ title: polars n-unique categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Counts unique values. usage: | diff --git a/commands/docs/polars_not.md b/commands/docs/polars_not.md index 11f1dd46912..37b334db5d1 100644 --- a/commands/docs/polars_not.md +++ b/commands/docs/polars_not.md @@ -2,7 +2,7 @@ title: polars not categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Inverts boolean mask. usage: | diff --git a/commands/docs/polars_open.md b/commands/docs/polars_open.md index a1c91ccb3e6..f12ebefe176 100644 --- a/commands/docs/polars_open.md +++ b/commands/docs/polars_open.md @@ -2,7 +2,7 @@ title: polars open categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Opens CSV, JSON, NDJSON/JSON lines, arrow, avro, or parquet file to create dataframe. A lazy dataframe will be created by default, if supported. usage: | diff --git a/commands/docs/polars_otherwise.md b/commands/docs/polars_otherwise.md index f307dec58ab..a73e3a76135 100644 --- a/commands/docs/polars_otherwise.md +++ b/commands/docs/polars_otherwise.md @@ -2,7 +2,7 @@ title: polars otherwise categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Completes a when expression. usage: | diff --git a/commands/docs/polars_pivot.md b/commands/docs/polars_pivot.md index d9ebda68002..8ca0cf7f2ed 100644 --- a/commands/docs/polars_pivot.md +++ b/commands/docs/polars_pivot.md @@ -2,7 +2,7 @@ title: polars pivot categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Pivot a DataFrame from wide to long format. usage: | diff --git a/commands/docs/polars_profile.md b/commands/docs/polars_profile.md index b61581f73db..376be925536 100644 --- a/commands/docs/polars_profile.md +++ b/commands/docs/polars_profile.md @@ -2,21 +2,17 @@ title: polars profile categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | - Profile a lazy dataframe. This will run the query and return a record containing the materialized DataFrame and a DataFrame that contains profiling information of each node that is executed. - - The units of the timings are microseconds. + Profile a lazy dataframe. usage: | - Profile a lazy dataframe. This will run the query and return a record containing the materialized DataFrame and a DataFrame that contains profiling information of each node that is executed. - - The units of the timings are microseconds. + Profile a lazy dataframe. --- # `polars profile` for [dataframe](/commands/categories/dataframe.md) -
Profile a lazy dataframe. This will run the query and return a record containing the materialized DataFrame and a DataFrame that contains profiling information of each node that is executed.

The units of the timings are microseconds.
+
Profile a lazy dataframe.
::: warning This command requires a plugin The `polars profile` command resides in the `polars` plugin. @@ -52,3 +48,8 @@ Profile a lazy dataframe ``` + +## Notes +This will run the query and return a record containing the materialized DataFrame and a DataFrame that contains profiling information of each node that is executed. + +The units of the timings are microseconds. \ No newline at end of file diff --git a/commands/docs/polars_quantile.md b/commands/docs/polars_quantile.md index 6529d122578..c0d83ef873a 100644 --- a/commands/docs/polars_quantile.md +++ b/commands/docs/polars_quantile.md @@ -2,7 +2,7 @@ title: polars quantile categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Aggregates the columns to the selected quantile. usage: | diff --git a/commands/docs/polars_query.md b/commands/docs/polars_query.md index 61395a89e18..fea3f548201 100644 --- a/commands/docs/polars_query.md +++ b/commands/docs/polars_query.md @@ -2,7 +2,7 @@ title: polars query categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Query dataframe using SQL. Note: The dataframe is always named 'df' in your query's from clause. usage: | diff --git a/commands/docs/polars_rename.md b/commands/docs/polars_rename.md index 606661ef424..5fadc1c599e 100644 --- a/commands/docs/polars_rename.md +++ b/commands/docs/polars_rename.md @@ -2,7 +2,7 @@ title: polars rename categories: | dataframe or lazyframe -version: 0.100.0 +version: 0.101.0 dataframe_or_lazyframe: | Rename a dataframe column. usage: | diff --git a/commands/docs/polars_replace-all.md b/commands/docs/polars_replace-all.md index 0e4b2170baa..5f0e43dc04a 100644 --- a/commands/docs/polars_replace-all.md +++ b/commands/docs/polars_replace-all.md @@ -2,7 +2,7 @@ title: polars replace-all categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Replace all (sub)strings by a regex pattern. usage: | diff --git a/commands/docs/polars_replace.md b/commands/docs/polars_replace.md index 34af6f802d0..5c79c4d46ad 100644 --- a/commands/docs/polars_replace.md +++ b/commands/docs/polars_replace.md @@ -2,7 +2,7 @@ title: polars replace categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Replace the leftmost (sub)string by a regex pattern. usage: | diff --git a/commands/docs/polars_reverse.md b/commands/docs/polars_reverse.md index 7cb707baa80..1261d5e65f1 100644 --- a/commands/docs/polars_reverse.md +++ b/commands/docs/polars_reverse.md @@ -2,7 +2,7 @@ title: polars reverse categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Reverses the LazyFrame usage: | diff --git a/commands/docs/polars_rolling.md b/commands/docs/polars_rolling.md index 9bc58aeac4c..66ac2b95f68 100644 --- a/commands/docs/polars_rolling.md +++ b/commands/docs/polars_rolling.md @@ -2,7 +2,7 @@ title: polars rolling categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Rolling calculation for a series. usage: | diff --git a/commands/docs/polars_sample.md b/commands/docs/polars_sample.md index 0526a7d606f..576413320db 100644 --- a/commands/docs/polars_sample.md +++ b/commands/docs/polars_sample.md @@ -2,7 +2,7 @@ title: polars sample categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Create sample dataframe. usage: | diff --git a/commands/docs/polars_save.md b/commands/docs/polars_save.md index 15a60e0d7ea..0e49ca6bf39 100644 --- a/commands/docs/polars_save.md +++ b/commands/docs/polars_save.md @@ -2,7 +2,7 @@ title: polars save categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Saves a dataframe to disk. For lazy dataframes a sink operation will be used if the file type supports it (parquet, ipc/arrow, csv, and ndjson). usage: | diff --git a/commands/docs/polars_schema.md b/commands/docs/polars_schema.md index 99e729c9d73..10b79a2b644 100644 --- a/commands/docs/polars_schema.md +++ b/commands/docs/polars_schema.md @@ -2,7 +2,7 @@ title: polars schema categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Show schema for a dataframe. usage: | diff --git a/commands/docs/polars_select.md b/commands/docs/polars_select.md index 4370d39f239..520c24ad095 100644 --- a/commands/docs/polars_select.md +++ b/commands/docs/polars_select.md @@ -2,7 +2,7 @@ title: polars select categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Selects columns from lazyframe. usage: | diff --git a/commands/docs/polars_set-with-idx.md b/commands/docs/polars_set-with-idx.md index 7c5cb94d8b1..dd23f57a5f9 100644 --- a/commands/docs/polars_set-with-idx.md +++ b/commands/docs/polars_set-with-idx.md @@ -2,7 +2,7 @@ title: polars set-with-idx categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Sets value in the given index. usage: | diff --git a/commands/docs/polars_set.md b/commands/docs/polars_set.md index 859a2fd8441..502465cf5d0 100644 --- a/commands/docs/polars_set.md +++ b/commands/docs/polars_set.md @@ -2,7 +2,7 @@ title: polars set categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Sets value where given mask is true. usage: | diff --git a/commands/docs/polars_shape.md b/commands/docs/polars_shape.md index 7e3716f60f1..0180a8754c7 100644 --- a/commands/docs/polars_shape.md +++ b/commands/docs/polars_shape.md @@ -2,7 +2,7 @@ title: polars shape categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Shows column and row size for a dataframe. usage: | diff --git a/commands/docs/polars_shift.md b/commands/docs/polars_shift.md index b4b20042abe..136fc7e65db 100644 --- a/commands/docs/polars_shift.md +++ b/commands/docs/polars_shift.md @@ -2,7 +2,7 @@ title: polars shift categories: | dataframe or lazyframe -version: 0.100.0 +version: 0.101.0 dataframe_or_lazyframe: | Shifts the values by a given period. usage: | diff --git a/commands/docs/polars_slice.md b/commands/docs/polars_slice.md index 6b2b2e655df..cb36768308b 100644 --- a/commands/docs/polars_slice.md +++ b/commands/docs/polars_slice.md @@ -2,7 +2,7 @@ title: polars slice categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates new dataframe from a slice of rows. usage: | diff --git a/commands/docs/polars_sort-by.md b/commands/docs/polars_sort-by.md index 4af0a35e109..4d6cbcf610b 100644 --- a/commands/docs/polars_sort-by.md +++ b/commands/docs/polars_sort-by.md @@ -2,7 +2,7 @@ title: polars sort-by categories: | lazyframe -version: 0.100.0 +version: 0.101.0 lazyframe: | Sorts a lazy dataframe based on expression(s). usage: | diff --git a/commands/docs/polars_std.md b/commands/docs/polars_std.md index 58872ede9b7..0ad4ca504d0 100644 --- a/commands/docs/polars_std.md +++ b/commands/docs/polars_std.md @@ -2,7 +2,7 @@ title: polars std categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates a std expression for an aggregation of std value from columns in a dataframe. usage: | diff --git a/commands/docs/polars_store-get.md b/commands/docs/polars_store-get.md index 1c24308980a..a94f12850c3 100644 --- a/commands/docs/polars_store-get.md +++ b/commands/docs/polars_store-get.md @@ -2,7 +2,7 @@ title: polars store-get categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Gets a Dataframe or other object from the plugin cache. usage: | diff --git a/commands/docs/polars_store-ls.md b/commands/docs/polars_store-ls.md index 0f208288bb0..d190810b6e4 100644 --- a/commands/docs/polars_store-ls.md +++ b/commands/docs/polars_store-ls.md @@ -2,7 +2,7 @@ title: polars store-ls categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Lists stored polars objects. usage: | diff --git a/commands/docs/polars_store-rm.md b/commands/docs/polars_store-rm.md index ba6ad7f0905..22b1e895115 100644 --- a/commands/docs/polars_store-rm.md +++ b/commands/docs/polars_store-rm.md @@ -2,7 +2,7 @@ title: polars store-rm categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Removes a stored Dataframe or other object from the plugin cache. usage: | diff --git a/commands/docs/polars_str-join.md b/commands/docs/polars_str-join.md index f7b119db1eb..f495f640969 100644 --- a/commands/docs/polars_str-join.md +++ b/commands/docs/polars_str-join.md @@ -2,7 +2,7 @@ title: polars str-join categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Concatenates strings within a column or dataframes usage: | diff --git a/commands/docs/polars_str-lengths.md b/commands/docs/polars_str-lengths.md index 856e4dc0aad..78d1f6d03f8 100644 --- a/commands/docs/polars_str-lengths.md +++ b/commands/docs/polars_str-lengths.md @@ -2,7 +2,7 @@ title: polars str-lengths categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Get lengths of all strings. usage: | diff --git a/commands/docs/polars_str-slice.md b/commands/docs/polars_str-slice.md index 310ef500aff..50a8b7d377e 100644 --- a/commands/docs/polars_str-slice.md +++ b/commands/docs/polars_str-slice.md @@ -2,7 +2,7 @@ title: polars str-slice categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Slices the string from the start position until the selected length. usage: | diff --git a/commands/docs/polars_strftime.md b/commands/docs/polars_strftime.md index f423ef664dc..863e4cec6e0 100644 --- a/commands/docs/polars_strftime.md +++ b/commands/docs/polars_strftime.md @@ -2,7 +2,7 @@ title: polars strftime categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Formats date based on string rule. usage: | diff --git a/commands/docs/polars_sum.md b/commands/docs/polars_sum.md index 449b8324b40..a596240143e 100644 --- a/commands/docs/polars_sum.md +++ b/commands/docs/polars_sum.md @@ -2,7 +2,7 @@ title: polars sum categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates a sum expression for an aggregation or aggregates columns to their sum value. usage: | diff --git a/commands/docs/polars_summary.md b/commands/docs/polars_summary.md index 10630200a9a..a3e7dc78e9d 100644 --- a/commands/docs/polars_summary.md +++ b/commands/docs/polars_summary.md @@ -2,7 +2,7 @@ title: polars summary categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | For a dataframe, produces descriptive statistics (summary statistics) for its numeric columns. usage: | diff --git a/commands/docs/polars_take.md b/commands/docs/polars_take.md index 0a0e110e7a4..53c455a2203 100644 --- a/commands/docs/polars_take.md +++ b/commands/docs/polars_take.md @@ -2,7 +2,7 @@ title: polars take categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Creates new dataframe using the given indices. usage: | diff --git a/commands/docs/polars_unique.md b/commands/docs/polars_unique.md index 5aef050c423..ac496b9d598 100644 --- a/commands/docs/polars_unique.md +++ b/commands/docs/polars_unique.md @@ -2,7 +2,7 @@ title: polars unique categories: | dataframe or lazyframe -version: 0.100.0 +version: 0.101.0 dataframe_or_lazyframe: | Returns unique values from a dataframe. usage: | diff --git a/commands/docs/polars_unnest.md b/commands/docs/polars_unnest.md index 597317173f2..8279feea263 100644 --- a/commands/docs/polars_unnest.md +++ b/commands/docs/polars_unnest.md @@ -2,7 +2,7 @@ title: polars unnest categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Decompose struct columns into separate columns for each of their fields. The new columns will be inserted into the dataframe at the location of the struct column. usage: | diff --git a/commands/docs/polars_unpivot.md b/commands/docs/polars_unpivot.md index 1deb948a2f2..de6c4bce81e 100644 --- a/commands/docs/polars_unpivot.md +++ b/commands/docs/polars_unpivot.md @@ -2,7 +2,7 @@ title: polars unpivot categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Unpivot a DataFrame from wide to long format. usage: | diff --git a/commands/docs/polars_uppercase.md b/commands/docs/polars_uppercase.md index 78d3eb10f46..bc9824824e2 100644 --- a/commands/docs/polars_uppercase.md +++ b/commands/docs/polars_uppercase.md @@ -2,7 +2,7 @@ title: polars uppercase categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Uppercase the strings in the column. usage: | diff --git a/commands/docs/polars_value-counts.md b/commands/docs/polars_value-counts.md index 9a2481693a2..c32a38ac157 100644 --- a/commands/docs/polars_value-counts.md +++ b/commands/docs/polars_value-counts.md @@ -2,7 +2,7 @@ title: polars value-counts categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Returns a dataframe with the counts for unique values in series. usage: | @@ -27,7 +27,7 @@ See the [Plugins](/book/plugins.html) chapter in the book for more information. ## Flags - - `--column, -c {string}`: Provide a custom name for the coutn column + - `--column, -c {string}`: Provide a custom name for the count column - `--sort, -s`: Whether or not values should be sorted - `--parallel, -p`: Use multiple threads when processing - `--normalize, -n {string}`: Normalize the counts diff --git a/commands/docs/polars_var.md b/commands/docs/polars_var.md index 73fe57625a6..ddf354747a3 100644 --- a/commands/docs/polars_var.md +++ b/commands/docs/polars_var.md @@ -2,7 +2,7 @@ title: polars var categories: | dataframe -version: 0.100.0 +version: 0.101.0 dataframe: | Create a var expression for an aggregation. usage: | diff --git a/commands/docs/polars_when.md b/commands/docs/polars_when.md index 782bc9012e4..59bd0215a73 100644 --- a/commands/docs/polars_when.md +++ b/commands/docs/polars_when.md @@ -2,7 +2,7 @@ title: polars when categories: | expression -version: 0.100.0 +version: 0.101.0 expression: | Creates and modifies a when expression. usage: | diff --git a/commands/docs/polars_with-column.md b/commands/docs/polars_with-column.md index d26c2410ed6..b88e473c827 100644 --- a/commands/docs/polars_with-column.md +++ b/commands/docs/polars_with-column.md @@ -2,7 +2,7 @@ title: polars with-column categories: | dataframe or lazyframe -version: 0.100.0 +version: 0.101.0 dataframe_or_lazyframe: | Adds a series to the dataframe. usage: | @@ -27,7 +27,7 @@ See the [Plugins](/book/plugins.html) chapter in the book for more information. ## Flags - - `--name, -n {string}`: new column name + - `--name, -n {string}`: New column name. For lazy dataframes and expressions syntax, use a `polars as` expression to name a column. ## Parameters diff --git a/commands/docs/port.md b/commands/docs/port.md index 442367affeb..e9f35cf61d4 100644 --- a/commands/docs/port.md +++ b/commands/docs/port.md @@ -2,7 +2,7 @@ title: port categories: | network -version: 0.100.0 +version: 0.101.0 network: | Get a free port from system. usage: | diff --git a/commands/docs/prepend.md b/commands/docs/prepend.md index c8673918b84..563ecb026b2 100644 --- a/commands/docs/prepend.md +++ b/commands/docs/prepend.md @@ -2,7 +2,7 @@ title: prepend categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Prepend any number of rows to a table. usage: | diff --git a/commands/docs/print.md b/commands/docs/print.md index 61cd85608dd..f9c5ddfefd3 100644 --- a/commands/docs/print.md +++ b/commands/docs/print.md @@ -2,7 +2,7 @@ title: print categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Print the given values to stdout. usage: | diff --git a/commands/docs/ps.md b/commands/docs/ps.md index 81c3b37210f..f189f664ea2 100644 --- a/commands/docs/ps.md +++ b/commands/docs/ps.md @@ -2,7 +2,7 @@ title: ps categories: | system -version: 0.100.0 +version: 0.101.0 system: | View information about system processes. usage: | diff --git a/commands/docs/pwd.md b/commands/docs/pwd.md index 33de1c141dc..0117a5bbedd 100644 --- a/commands/docs/pwd.md +++ b/commands/docs/pwd.md @@ -2,7 +2,7 @@ title: pwd categories: | default -version: 0.100.0 +version: 0.101.0 default: | Return the current working directory usage: | diff --git a/commands/docs/query.md b/commands/docs/query.md index 3f1902a2b6d..a8a983c9996 100644 --- a/commands/docs/query.md +++ b/commands/docs/query.md @@ -2,7 +2,7 @@ title: query categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Show all the query commands usage: | diff --git a/commands/docs/query_db.md b/commands/docs/query_db.md index e77ae782f20..6ea35b9695b 100644 --- a/commands/docs/query_db.md +++ b/commands/docs/query_db.md @@ -2,7 +2,7 @@ title: query db categories: | database -version: 0.100.0 +version: 0.101.0 database: | Query a database using SQL. usage: | diff --git a/commands/docs/query_json.md b/commands/docs/query_json.md index 7d0bb8a5d8c..3b1c01ba55d 100644 --- a/commands/docs/query_json.md +++ b/commands/docs/query_json.md @@ -2,7 +2,7 @@ title: query json categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | execute json query on json file (open --raw | query json 'query string') usage: | diff --git a/commands/docs/query_web.md b/commands/docs/query_web.md index 7f209beccaa..7cc00a21608 100644 --- a/commands/docs/query_web.md +++ b/commands/docs/query_web.md @@ -2,7 +2,7 @@ title: query web categories: | network -version: 0.100.0 +version: 0.101.0 network: | execute selector query on html/web usage: | diff --git a/commands/docs/query_webpage-info.md b/commands/docs/query_webpage-info.md index bbab3a2f3d7..a6546531f61 100644 --- a/commands/docs/query_webpage-info.md +++ b/commands/docs/query_webpage-info.md @@ -2,7 +2,7 @@ title: query webpage-info categories: | network -version: 0.100.0 +version: 0.101.0 network: | uses the webpage crate to extract info from html: title, description, language, links, RSS feeds, Opengraph, Schema.org, and more usage: | diff --git a/commands/docs/query_xml.md b/commands/docs/query_xml.md index 338ccb8aa10..15003294401 100644 --- a/commands/docs/query_xml.md +++ b/commands/docs/query_xml.md @@ -2,7 +2,7 @@ title: query xml categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | execute xpath query on xml usage: | diff --git a/commands/docs/random.md b/commands/docs/random.md index 251ef29f0b6..907db1d9a39 100644 --- a/commands/docs/random.md +++ b/commands/docs/random.md @@ -2,7 +2,7 @@ title: random categories: | random -version: 0.100.0 +version: 0.101.0 random: | Generate a random value. usage: | diff --git a/commands/docs/random_binary.md b/commands/docs/random_binary.md index 022bdb84d9b..e0fb13fa3a3 100644 --- a/commands/docs/random_binary.md +++ b/commands/docs/random_binary.md @@ -2,7 +2,7 @@ title: random binary categories: | random -version: 0.100.0 +version: 0.101.0 random: | Generate random bytes. usage: | diff --git a/commands/docs/random_bool.md b/commands/docs/random_bool.md index 9e0739872d4..116119eb8a0 100644 --- a/commands/docs/random_bool.md +++ b/commands/docs/random_bool.md @@ -2,7 +2,7 @@ title: random bool categories: | random -version: 0.100.0 +version: 0.101.0 random: | Generate a random boolean value. usage: | diff --git a/commands/docs/random_chars.md b/commands/docs/random_chars.md index 8aad5f90409..eac6d316bd0 100644 --- a/commands/docs/random_chars.md +++ b/commands/docs/random_chars.md @@ -2,7 +2,7 @@ title: random chars categories: | random -version: 0.100.0 +version: 0.101.0 random: | Generate random chars uniformly distributed over ASCII letters and numbers: a-z, A-Z and 0-9. usage: | diff --git a/commands/docs/random_dice.md b/commands/docs/random_dice.md index fde9bfdb9d5..61d5960edfa 100644 --- a/commands/docs/random_dice.md +++ b/commands/docs/random_dice.md @@ -2,7 +2,7 @@ title: random dice categories: | random -version: 0.100.0 +version: 0.101.0 random: | Generate a random dice roll. usage: | @@ -28,7 +28,7 @@ usage: | | input | output | | ------- | --------- | -| nothing | list\ | +| nothing | list\ | ## Examples diff --git a/commands/docs/random_float.md b/commands/docs/random_float.md index 4f0127cd42d..2f3c34b1d91 100644 --- a/commands/docs/random_float.md +++ b/commands/docs/random_float.md @@ -2,7 +2,7 @@ title: random float categories: | random -version: 0.100.0 +version: 0.101.0 random: | Generate a random float within a range [min..max]. usage: | diff --git a/commands/docs/random_int.md b/commands/docs/random_int.md index 0e0fa26dd73..b63edd8ded1 100644 --- a/commands/docs/random_int.md +++ b/commands/docs/random_int.md @@ -2,7 +2,7 @@ title: random int categories: | random -version: 0.100.0 +version: 0.101.0 random: | Generate a random integer [min..max]. usage: | diff --git a/commands/docs/random_uuid.md b/commands/docs/random_uuid.md index ebe763362dd..b485a784eab 100644 --- a/commands/docs/random_uuid.md +++ b/commands/docs/random_uuid.md @@ -2,7 +2,7 @@ title: random uuid categories: | random -version: 0.100.0 +version: 0.101.0 random: | Generate a random uuid4 string. usage: | diff --git a/commands/docs/range.md b/commands/docs/range.md index 395dcf04e79..d44b6db2457 100644 --- a/commands/docs/range.md +++ b/commands/docs/range.md @@ -2,7 +2,7 @@ title: range categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Return only the selected rows. usage: | diff --git a/commands/docs/reduce.md b/commands/docs/reduce.md index b0bf42d4894..5745e8e73c6 100644 --- a/commands/docs/reduce.md +++ b/commands/docs/reduce.md @@ -2,7 +2,7 @@ title: reduce categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Aggregate a list (starting from the left) to a single value using an accumulator closure. usage: | @@ -83,3 +83,13 @@ Concatenate a string with itself, using a range to determine the number of times > let s = "Str"; 0..2 | reduce --fold '' {|it, acc| $acc + $s} StrStrStr ``` + +Merge multiple records together, making use of the fact that the accumulated value is also supplied as pipeline input to the closure. +```nu +> [{a: 1} {b: 2} {c: 3}] | reduce {|it| merge $it} +╭───┬───╮ +│ a │ 1 │ +│ b │ 2 │ +│ c │ 3 │ +╰───┴───╯ +``` diff --git a/commands/docs/registry_query.md b/commands/docs/registry_query.md index cfc0cdbd594..e339c8f927b 100644 --- a/commands/docs/registry_query.md +++ b/commands/docs/registry_query.md @@ -2,7 +2,7 @@ title: registry query categories: | system -version: 0.100.0 +version: 0.101.0 system: | Query the Windows registry. usage: | diff --git a/commands/docs/reject.md b/commands/docs/reject.md index 92e4fb292cf..1128b58a2ad 100644 --- a/commands/docs/reject.md +++ b/commands/docs/reject.md @@ -2,7 +2,7 @@ title: reject categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Remove the given columns or rows from the table. Opposite of `select`. usage: | diff --git a/commands/docs/rename.md b/commands/docs/rename.md index 7019a269d87..d7f56e6d715 100644 --- a/commands/docs/rename.md +++ b/commands/docs/rename.md @@ -2,7 +2,7 @@ title: rename categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Creates a new table with columns renamed. usage: | diff --git a/commands/docs/return.md b/commands/docs/return.md index cbed26cfa52..44d8162839a 100644 --- a/commands/docs/return.md +++ b/commands/docs/return.md @@ -2,7 +2,7 @@ title: return categories: | core -version: 0.100.0 +version: 0.101.0 core: | Return early from a function. usage: | diff --git a/commands/docs/reverse.md b/commands/docs/reverse.md index 3f36f572903..0a2947cc742 100644 --- a/commands/docs/reverse.md +++ b/commands/docs/reverse.md @@ -2,7 +2,7 @@ title: reverse categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Reverses the input list or table. usage: | diff --git a/commands/docs/rm.md b/commands/docs/rm.md index 09975704f64..f5efa27c089 100644 --- a/commands/docs/rm.md +++ b/commands/docs/rm.md @@ -2,7 +2,7 @@ title: rm categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Remove files and directories. usage: | diff --git a/commands/docs/roll.md b/commands/docs/roll.md index 8bb32584703..8313e251f38 100644 --- a/commands/docs/roll.md +++ b/commands/docs/roll.md @@ -2,7 +2,7 @@ title: roll categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Rolling commands for tables. usage: | diff --git a/commands/docs/roll_down.md b/commands/docs/roll_down.md index 1130684dc37..a67b7e822e9 100644 --- a/commands/docs/roll_down.md +++ b/commands/docs/roll_down.md @@ -2,7 +2,7 @@ title: roll down categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Roll table rows down. usage: | diff --git a/commands/docs/roll_left.md b/commands/docs/roll_left.md index 3970800972f..ba90ac43dcc 100644 --- a/commands/docs/roll_left.md +++ b/commands/docs/roll_left.md @@ -2,7 +2,7 @@ title: roll left categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Roll record or table columns left. usage: | diff --git a/commands/docs/roll_right.md b/commands/docs/roll_right.md index 35f78cdde78..deb3cd3c749 100644 --- a/commands/docs/roll_right.md +++ b/commands/docs/roll_right.md @@ -2,7 +2,7 @@ title: roll right categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Roll table columns right. usage: | diff --git a/commands/docs/roll_up.md b/commands/docs/roll_up.md index 16bbba56a2d..ff0c93cd1f6 100644 --- a/commands/docs/roll_up.md +++ b/commands/docs/roll_up.md @@ -2,7 +2,7 @@ title: roll up categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Roll table rows up. usage: | diff --git a/commands/docs/rotate.md b/commands/docs/rotate.md index b394843f6fa..d927521bb9c 100644 --- a/commands/docs/rotate.md +++ b/commands/docs/rotate.md @@ -2,7 +2,7 @@ title: rotate categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Rotates a table or record clockwise (default) or counter-clockwise (use --ccw flag). usage: | diff --git a/commands/docs/run-external.md b/commands/docs/run-external.md index dc54b76463a..ea38423d825 100644 --- a/commands/docs/run-external.md +++ b/commands/docs/run-external.md @@ -2,7 +2,7 @@ title: run-external categories: | system -version: 0.100.0 +version: 0.101.0 system: | Runs external command. usage: | diff --git a/commands/docs/save.md b/commands/docs/save.md index 23e568fa646..142c7b39906 100644 --- a/commands/docs/save.md +++ b/commands/docs/save.md @@ -2,7 +2,7 @@ title: save categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Save a file. usage: | diff --git a/commands/docs/schema.md b/commands/docs/schema.md index fb9d16817bd..d83b66ac540 100644 --- a/commands/docs/schema.md +++ b/commands/docs/schema.md @@ -2,7 +2,7 @@ title: schema categories: | database -version: 0.100.0 +version: 0.101.0 database: | Show the schema of a SQLite database. usage: | diff --git a/commands/docs/scope.md b/commands/docs/scope.md index 6439507cc46..8029817b846 100644 --- a/commands/docs/scope.md +++ b/commands/docs/scope.md @@ -2,7 +2,7 @@ title: scope categories: | core -version: 0.100.0 +version: 0.101.0 core: | Commands for getting info about what is in scope. usage: | diff --git a/commands/docs/scope_aliases.md b/commands/docs/scope_aliases.md index 55857de885f..a4f0f5f0572 100644 --- a/commands/docs/scope_aliases.md +++ b/commands/docs/scope_aliases.md @@ -2,7 +2,7 @@ title: scope aliases categories: | core -version: 0.100.0 +version: 0.101.0 core: | Output info on the aliases in the current scope. usage: | diff --git a/commands/docs/scope_commands.md b/commands/docs/scope_commands.md index 387be508a4b..67478e29526 100644 --- a/commands/docs/scope_commands.md +++ b/commands/docs/scope_commands.md @@ -2,7 +2,7 @@ title: scope commands categories: | core -version: 0.100.0 +version: 0.101.0 core: | Output info on the commands in the current scope. usage: | diff --git a/commands/docs/scope_engine-stats.md b/commands/docs/scope_engine-stats.md index e3d661f3239..ed1fd382c10 100644 --- a/commands/docs/scope_engine-stats.md +++ b/commands/docs/scope_engine-stats.md @@ -2,7 +2,7 @@ title: scope engine-stats categories: | core -version: 0.100.0 +version: 0.101.0 core: | Output stats on the engine in the current state. usage: | diff --git a/commands/docs/scope_externs.md b/commands/docs/scope_externs.md index 252a4b8483b..a5e09440656 100644 --- a/commands/docs/scope_externs.md +++ b/commands/docs/scope_externs.md @@ -2,7 +2,7 @@ title: scope externs categories: | core -version: 0.100.0 +version: 0.101.0 core: | Output info on the known externals in the current scope. usage: | diff --git a/commands/docs/scope_modules.md b/commands/docs/scope_modules.md index ed83439c704..0caa26b3477 100644 --- a/commands/docs/scope_modules.md +++ b/commands/docs/scope_modules.md @@ -2,7 +2,7 @@ title: scope modules categories: | core -version: 0.100.0 +version: 0.101.0 core: | Output info on the modules in the current scope. usage: | diff --git a/commands/docs/scope_variables.md b/commands/docs/scope_variables.md index 07d2c2dd794..f83ef1c8ae3 100644 --- a/commands/docs/scope_variables.md +++ b/commands/docs/scope_variables.md @@ -2,7 +2,7 @@ title: scope variables categories: | core -version: 0.100.0 +version: 0.101.0 core: | Output info on the variables in the current scope. usage: | diff --git a/commands/docs/select.md b/commands/docs/select.md index 16327b23b02..d3735f3400f 100644 --- a/commands/docs/select.md +++ b/commands/docs/select.md @@ -2,7 +2,7 @@ title: select categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Select only these columns or rows from the input. Opposite of `reject`. usage: | diff --git a/commands/docs/seq.md b/commands/docs/seq.md index 52663886e85..299491e1e16 100644 --- a/commands/docs/seq.md +++ b/commands/docs/seq.md @@ -2,7 +2,7 @@ title: seq categories: | generators -version: 0.100.0 +version: 0.101.0 generators: | Output sequences of numbers. usage: | diff --git a/commands/docs/seq_char.md b/commands/docs/seq_char.md index ac056a8ff85..fe2cd6a9712 100644 --- a/commands/docs/seq_char.md +++ b/commands/docs/seq_char.md @@ -2,7 +2,7 @@ title: seq char categories: | generators -version: 0.100.0 +version: 0.101.0 generators: | Print a sequence of ASCII characters. usage: | @@ -45,7 +45,7 @@ sequence a to e ``` -sequence a to e, and put the characters in a pipe-separated string +Sequence a to e, and join the characters with a pipe ```nu > seq char a e | str join '|' diff --git a/commands/docs/seq_date.md b/commands/docs/seq_date.md index 940e403ab04..6533db336c8 100644 --- a/commands/docs/seq_date.md +++ b/commands/docs/seq_date.md @@ -2,7 +2,7 @@ title: seq date categories: | generators -version: 0.100.0 +version: 0.101.0 generators: | Print sequences of dates. usage: | diff --git a/commands/docs/shuffle.md b/commands/docs/shuffle.md index 1aca4876ccd..649412f08b7 100644 --- a/commands/docs/shuffle.md +++ b/commands/docs/shuffle.md @@ -2,7 +2,7 @@ title: shuffle categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Shuffle rows randomly. usage: | diff --git a/commands/docs/skip.md b/commands/docs/skip.md index 2716d353541..09475c7082e 100644 --- a/commands/docs/skip.md +++ b/commands/docs/skip.md @@ -2,7 +2,7 @@ title: skip categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Skip the first several rows of the input. Counterpart of `drop`. Opposite of `first`. usage: | diff --git a/commands/docs/skip_until.md b/commands/docs/skip_until.md index 0d2cc8b8ddf..79d39b754c1 100644 --- a/commands/docs/skip_until.md +++ b/commands/docs/skip_until.md @@ -2,7 +2,7 @@ title: skip until categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Skip elements of the input until a predicate is true. usage: | diff --git a/commands/docs/skip_while.md b/commands/docs/skip_while.md index 70ed08cd2c0..cb772bf3925 100644 --- a/commands/docs/skip_while.md +++ b/commands/docs/skip_while.md @@ -2,7 +2,7 @@ title: skip while categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Skip elements of the input while a predicate is true. usage: | diff --git a/commands/docs/sleep.md b/commands/docs/sleep.md index 311d1d2b15e..a1a1b1e821b 100644 --- a/commands/docs/sleep.md +++ b/commands/docs/sleep.md @@ -2,7 +2,7 @@ title: sleep categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Delay for a specified amount of time. usage: | @@ -38,9 +38,9 @@ Sleep for 1sec ``` -Sleep for 3sec +Use multiple arguments to write a duration with multiple units, which is unsupported by duration literals ```nu -> sleep 1sec 1sec 1sec +> sleep 1min 30sec ``` diff --git a/commands/docs/sort-by.md b/commands/docs/sort-by.md index 67c3d2640dd..fccc974b16d 100644 --- a/commands/docs/sort-by.md +++ b/commands/docs/sort-by.md @@ -2,7 +2,7 @@ title: sort-by categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Sort by the given cell path or closure. usage: | diff --git a/commands/docs/sort.md b/commands/docs/sort.md index 4054ae31889..75a6fa1349e 100644 --- a/commands/docs/sort.md +++ b/commands/docs/sort.md @@ -2,7 +2,7 @@ title: sort categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Sort in increasing order. usage: | diff --git a/commands/docs/source-env.md b/commands/docs/source-env.md index 93d15a4a224..04f60554e37 100644 --- a/commands/docs/source-env.md +++ b/commands/docs/source-env.md @@ -2,7 +2,7 @@ title: source-env categories: | core -version: 0.100.0 +version: 0.101.0 core: | Source the environment from a source file into the current environment. usage: | diff --git a/commands/docs/source.md b/commands/docs/source.md index 720375e9faa..e44d26f9685 100644 --- a/commands/docs/source.md +++ b/commands/docs/source.md @@ -2,7 +2,7 @@ title: source categories: | core -version: 0.100.0 +version: 0.101.0 core: | Runs a script file in the current context. usage: | diff --git a/commands/docs/split-by.md b/commands/docs/split-by.md index 8d971ec6944..6a8802cce29 100644 --- a/commands/docs/split-by.md +++ b/commands/docs/split-by.md @@ -1,16 +1,16 @@ --- title: split-by categories: | - filters -version: 0.100.0 -filters: | + deprecated +version: 0.101.0 +deprecated: | Split a record into groups. usage: | Split a record into groups. --- -# `split-by` for [filters](/commands/categories/filters.md) +# `split-by` for [deprecated](/commands/categories/deprecated.md)
Split a record into groups.
diff --git a/commands/docs/split.md b/commands/docs/split.md index 1910d7ccc20..b8d1db049c4 100644 --- a/commands/docs/split.md +++ b/commands/docs/split.md @@ -2,7 +2,7 @@ title: split categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Split contents across desired subcommand (like row, column) via the separator. usage: | diff --git a/commands/docs/split_cell-path.md b/commands/docs/split_cell-path.md index 606dd768285..f34182a126c 100644 --- a/commands/docs/split_cell-path.md +++ b/commands/docs/split_cell-path.md @@ -2,7 +2,7 @@ title: split cell-path categories: | conversions -version: 0.100.0 +version: 0.101.0 conversions: | Split a cell-path into its components. usage: | diff --git a/commands/docs/split_chars.md b/commands/docs/split_chars.md index 2fea6dc0879..82483272c24 100644 --- a/commands/docs/split_chars.md +++ b/commands/docs/split_chars.md @@ -2,7 +2,7 @@ title: split chars categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Split a string into a list of characters. usage: | diff --git a/commands/docs/split_column.md b/commands/docs/split_column.md index 9d2a0d17e90..58a943aa3eb 100644 --- a/commands/docs/split_column.md +++ b/commands/docs/split_column.md @@ -2,7 +2,7 @@ title: split column categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Split a string into multiple columns using a separator. usage: | diff --git a/commands/docs/split_list.md b/commands/docs/split_list.md index fa7a4eaa127..a474e6d778d 100644 --- a/commands/docs/split_list.md +++ b/commands/docs/split_list.md @@ -2,7 +2,7 @@ title: split list categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Split a list into multiple lists using a separator. usage: | diff --git a/commands/docs/split_row.md b/commands/docs/split_row.md index d47cdfdd8c2..25e23042821 100644 --- a/commands/docs/split_row.md +++ b/commands/docs/split_row.md @@ -2,7 +2,7 @@ title: split row categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Split a string into multiple rows using a separator. usage: | diff --git a/commands/docs/split_words.md b/commands/docs/split_words.md index 0ec8198d8cc..bb63a6f4850 100644 --- a/commands/docs/split_words.md +++ b/commands/docs/split_words.md @@ -2,7 +2,7 @@ title: split words categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Split a string's words into separate rows. usage: | diff --git a/commands/docs/start.md b/commands/docs/start.md index 15d313020c6..e04d2097e35 100644 --- a/commands/docs/start.md +++ b/commands/docs/start.md @@ -2,7 +2,7 @@ title: start categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Open a folder, file or website in the default application or viewer. usage: | diff --git a/commands/docs/stor.md b/commands/docs/stor.md index 0546af06f28..14a0a80d53f 100644 --- a/commands/docs/stor.md +++ b/commands/docs/stor.md @@ -2,7 +2,7 @@ title: stor categories: | database -version: 0.100.0 +version: 0.101.0 database: | Various commands for working with the in-memory sqlite database. usage: | diff --git a/commands/docs/stor_create.md b/commands/docs/stor_create.md index d2a07161a9f..868decbd519 100644 --- a/commands/docs/stor_create.md +++ b/commands/docs/stor_create.md @@ -2,7 +2,7 @@ title: stor create categories: | database -version: 0.100.0 +version: 0.101.0 database: | Create a table in the in-memory sqlite database. usage: | diff --git a/commands/docs/stor_delete.md b/commands/docs/stor_delete.md index ac036b8afb2..4b428987c78 100644 --- a/commands/docs/stor_delete.md +++ b/commands/docs/stor_delete.md @@ -2,7 +2,7 @@ title: stor delete categories: | database -version: 0.100.0 +version: 0.101.0 database: | Delete a table or specified rows in the in-memory sqlite database. usage: | diff --git a/commands/docs/stor_export.md b/commands/docs/stor_export.md index 6b12a1f401f..9f44b44a859 100644 --- a/commands/docs/stor_export.md +++ b/commands/docs/stor_export.md @@ -2,7 +2,7 @@ title: stor export categories: | database -version: 0.100.0 +version: 0.101.0 database: | Export the in-memory sqlite database to a sqlite database file. usage: | diff --git a/commands/docs/stor_import.md b/commands/docs/stor_import.md index 8587ce6be0e..5030ffe6c8a 100644 --- a/commands/docs/stor_import.md +++ b/commands/docs/stor_import.md @@ -2,7 +2,7 @@ title: stor import categories: | database -version: 0.100.0 +version: 0.101.0 database: | Import a sqlite database file into the in-memory sqlite database. usage: | diff --git a/commands/docs/stor_insert.md b/commands/docs/stor_insert.md index 4af7f436b67..45c38a233f9 100644 --- a/commands/docs/stor_insert.md +++ b/commands/docs/stor_insert.md @@ -2,7 +2,7 @@ title: stor insert categories: | database -version: 0.100.0 +version: 0.101.0 database: | Insert information into a specified table in the in-memory sqlite database. usage: | diff --git a/commands/docs/stor_open.md b/commands/docs/stor_open.md index 5e8eb420ad1..2d618311f6f 100644 --- a/commands/docs/stor_open.md +++ b/commands/docs/stor_open.md @@ -2,7 +2,7 @@ title: stor open categories: | database -version: 0.100.0 +version: 0.101.0 database: | Opens the in-memory sqlite database. usage: | diff --git a/commands/docs/stor_reset.md b/commands/docs/stor_reset.md index a2b2f8ed767..6b81e8b3dcc 100644 --- a/commands/docs/stor_reset.md +++ b/commands/docs/stor_reset.md @@ -2,7 +2,7 @@ title: stor reset categories: | database -version: 0.100.0 +version: 0.101.0 database: | Reset the in-memory database by dropping all tables. usage: | diff --git a/commands/docs/stor_update.md b/commands/docs/stor_update.md index 626127f1f4b..0ca45e32704 100644 --- a/commands/docs/stor_update.md +++ b/commands/docs/stor_update.md @@ -2,7 +2,7 @@ title: stor update categories: | database -version: 0.100.0 +version: 0.101.0 database: | Update information in a specified table in the in-memory sqlite database. usage: | diff --git a/commands/docs/str.md b/commands/docs/str.md index bbd8b4263ba..245f383ff44 100644 --- a/commands/docs/str.md +++ b/commands/docs/str.md @@ -2,7 +2,7 @@ title: str categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Various commands for working with string data. usage: | diff --git a/commands/docs/str_camel-case.md b/commands/docs/str_camel-case.md index 83375b4dd62..a2d1f770f39 100644 --- a/commands/docs/str_camel-case.md +++ b/commands/docs/str_camel-case.md @@ -2,7 +2,7 @@ title: str camel-case categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Convert a string to camelCase. usage: | diff --git a/commands/docs/str_capitalize.md b/commands/docs/str_capitalize.md index 2fd369d5009..d1dc1e0fc8c 100644 --- a/commands/docs/str_capitalize.md +++ b/commands/docs/str_capitalize.md @@ -2,7 +2,7 @@ title: str capitalize categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Capitalize first letter of text. usage: | diff --git a/commands/docs/str_contains.md b/commands/docs/str_contains.md index 2fb1a076d20..8b7f5c79ebe 100644 --- a/commands/docs/str_contains.md +++ b/commands/docs/str_contains.md @@ -2,7 +2,7 @@ title: str contains categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Checks if string input contains a substring. usage: | diff --git a/commands/docs/str_distance.md b/commands/docs/str_distance.md index 2105eea2b89..71b65b93e29 100644 --- a/commands/docs/str_distance.md +++ b/commands/docs/str_distance.md @@ -2,7 +2,7 @@ title: str distance categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Compare two strings and return the edit distance/Levenshtein distance. usage: | diff --git a/commands/docs/str_downcase.md b/commands/docs/str_downcase.md index fd208bfc12a..88671d2c3ff 100644 --- a/commands/docs/str_downcase.md +++ b/commands/docs/str_downcase.md @@ -2,7 +2,7 @@ title: str downcase categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Make text lowercase. usage: | diff --git a/commands/docs/str_ends-with.md b/commands/docs/str_ends-with.md index 6f4785f9ff4..5ea033ba439 100644 --- a/commands/docs/str_ends-with.md +++ b/commands/docs/str_ends-with.md @@ -2,7 +2,7 @@ title: str ends-with categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Check if an input ends with a string. usage: | diff --git a/commands/docs/str_expand.md b/commands/docs/str_expand.md index 7ca9115540d..ebacccfc59c 100644 --- a/commands/docs/str_expand.md +++ b/commands/docs/str_expand.md @@ -2,7 +2,7 @@ title: str expand categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Generates all possible combinations defined in brace expansion syntax. usage: | diff --git a/commands/docs/str_index-of.md b/commands/docs/str_index-of.md index 359824e207d..1c01f6a5ace 100644 --- a/commands/docs/str_index-of.md +++ b/commands/docs/str_index-of.md @@ -2,7 +2,7 @@ title: str index-of categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Returns start index of first occurrence of string in input, or -1 if no match. usage: | diff --git a/commands/docs/str_join.md b/commands/docs/str_join.md index ad4f80cd919..55146571111 100644 --- a/commands/docs/str_join.md +++ b/commands/docs/str_join.md @@ -2,7 +2,7 @@ title: str join categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Concatenate multiple strings into a single string, with an optional separator between each. usage: | diff --git a/commands/docs/str_kebab-case.md b/commands/docs/str_kebab-case.md index 277c5572988..ac4ffc694c6 100644 --- a/commands/docs/str_kebab-case.md +++ b/commands/docs/str_kebab-case.md @@ -2,7 +2,7 @@ title: str kebab-case categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Convert a string to kebab-case. usage: | diff --git a/commands/docs/str_length.md b/commands/docs/str_length.md index e6689145bf4..a126bbae21e 100644 --- a/commands/docs/str_length.md +++ b/commands/docs/str_length.md @@ -2,7 +2,7 @@ title: str length categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Output the length of any strings in the pipeline. usage: | diff --git a/commands/docs/str_pascal-case.md b/commands/docs/str_pascal-case.md index 7db341bfe0b..f27d428e944 100644 --- a/commands/docs/str_pascal-case.md +++ b/commands/docs/str_pascal-case.md @@ -2,7 +2,7 @@ title: str pascal-case categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Convert a string to PascalCase. usage: | diff --git a/commands/docs/str_replace.md b/commands/docs/str_replace.md index c608779a86a..e9edba82a28 100644 --- a/commands/docs/str_replace.md +++ b/commands/docs/str_replace.md @@ -2,7 +2,7 @@ title: str replace categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Find and replace text. usage: | diff --git a/commands/docs/str_reverse.md b/commands/docs/str_reverse.md index d61a3a6717b..5a7f410a0ae 100644 --- a/commands/docs/str_reverse.md +++ b/commands/docs/str_reverse.md @@ -2,7 +2,7 @@ title: str reverse categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Reverse every string in the pipeline. usage: | diff --git a/commands/docs/str_screaming-snake-case.md b/commands/docs/str_screaming-snake-case.md index 8f48259951e..9d4646bd892 100644 --- a/commands/docs/str_screaming-snake-case.md +++ b/commands/docs/str_screaming-snake-case.md @@ -2,7 +2,7 @@ title: str screaming-snake-case categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Convert a string to SCREAMING_SNAKE_CASE. usage: | diff --git a/commands/docs/str_snake-case.md b/commands/docs/str_snake-case.md index 6708ac19433..70407e00d38 100644 --- a/commands/docs/str_snake-case.md +++ b/commands/docs/str_snake-case.md @@ -2,7 +2,7 @@ title: str snake-case categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Convert a string to snake_case. usage: | diff --git a/commands/docs/str_starts-with.md b/commands/docs/str_starts-with.md index cbc675c4aee..a49e53aa8d0 100644 --- a/commands/docs/str_starts-with.md +++ b/commands/docs/str_starts-with.md @@ -2,7 +2,7 @@ title: str starts-with categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Check if an input starts with a string. usage: | diff --git a/commands/docs/str_stats.md b/commands/docs/str_stats.md index 1ff06775c40..95732831d04 100644 --- a/commands/docs/str_stats.md +++ b/commands/docs/str_stats.md @@ -2,7 +2,7 @@ title: str stats categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Gather word count statistics on the text. usage: | diff --git a/commands/docs/str_substring.md b/commands/docs/str_substring.md index e6e4acb2307..85d786bfcb0 100644 --- a/commands/docs/str_substring.md +++ b/commands/docs/str_substring.md @@ -2,7 +2,7 @@ title: str substring categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Get part of a string. Note that the first character of a string is index 0. usage: | diff --git a/commands/docs/str_title-case.md b/commands/docs/str_title-case.md index 3d082da5828..02d3391c071 100644 --- a/commands/docs/str_title-case.md +++ b/commands/docs/str_title-case.md @@ -2,7 +2,7 @@ title: str title-case categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Convert a string to Title Case. usage: | diff --git a/commands/docs/str_trim.md b/commands/docs/str_trim.md index d6432ae5bd4..1626b4f4274 100644 --- a/commands/docs/str_trim.md +++ b/commands/docs/str_trim.md @@ -2,7 +2,7 @@ title: str trim categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Trim whitespace or specific character. usage: | diff --git a/commands/docs/str_upcase.md b/commands/docs/str_upcase.md index 0c47803177e..41f97ca6ad1 100644 --- a/commands/docs/str_upcase.md +++ b/commands/docs/str_upcase.md @@ -2,7 +2,7 @@ title: str upcase categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Make text uppercase. usage: | diff --git a/commands/docs/sys.md b/commands/docs/sys.md index 6e5409608a2..912f5b78374 100644 --- a/commands/docs/sys.md +++ b/commands/docs/sys.md @@ -2,7 +2,7 @@ title: sys categories: | system -version: 0.100.0 +version: 0.101.0 system: | View information about the system. usage: | diff --git a/commands/docs/sys_cpu.md b/commands/docs/sys_cpu.md index a01cd67999f..a76baa683ed 100644 --- a/commands/docs/sys_cpu.md +++ b/commands/docs/sys_cpu.md @@ -2,7 +2,7 @@ title: sys cpu categories: | system -version: 0.100.0 +version: 0.101.0 system: | View information about the system CPUs. usage: | @@ -18,6 +18,10 @@ usage: | ```> sys cpu {flags} ``` +## Flags + + - `--long, -l`: Get all available columns (slower, needs to sample CPU over time) + ## Input/output types: diff --git a/commands/docs/sys_disks.md b/commands/docs/sys_disks.md index ee3f751245d..f8b4a218462 100644 --- a/commands/docs/sys_disks.md +++ b/commands/docs/sys_disks.md @@ -2,7 +2,7 @@ title: sys disks categories: | system -version: 0.100.0 +version: 0.101.0 system: | View information about the system disks. usage: | diff --git a/commands/docs/sys_host.md b/commands/docs/sys_host.md index ec795d8de8b..5af9f1b8e26 100644 --- a/commands/docs/sys_host.md +++ b/commands/docs/sys_host.md @@ -2,7 +2,7 @@ title: sys host categories: | system -version: 0.100.0 +version: 0.101.0 system: | View information about the system host. usage: | diff --git a/commands/docs/sys_mem.md b/commands/docs/sys_mem.md index dbc4af66b39..dfe4dc6c930 100644 --- a/commands/docs/sys_mem.md +++ b/commands/docs/sys_mem.md @@ -2,7 +2,7 @@ title: sys mem categories: | system -version: 0.100.0 +version: 0.101.0 system: | View information about the system memory. usage: | diff --git a/commands/docs/sys_net.md b/commands/docs/sys_net.md index 0c5194b9764..4138d4ba6e1 100644 --- a/commands/docs/sys_net.md +++ b/commands/docs/sys_net.md @@ -2,7 +2,7 @@ title: sys net categories: | system -version: 0.100.0 +version: 0.101.0 system: | View information about the system network interfaces. usage: | diff --git a/commands/docs/sys_temp.md b/commands/docs/sys_temp.md index 1c56e513876..1215553acef 100644 --- a/commands/docs/sys_temp.md +++ b/commands/docs/sys_temp.md @@ -2,7 +2,7 @@ title: sys temp categories: | system -version: 0.100.0 +version: 0.101.0 system: | View the temperatures of system components. usage: | diff --git a/commands/docs/sys_users.md b/commands/docs/sys_users.md index 157f1a9a56e..c3f169fc686 100644 --- a/commands/docs/sys_users.md +++ b/commands/docs/sys_users.md @@ -2,7 +2,7 @@ title: sys users categories: | system -version: 0.100.0 +version: 0.101.0 system: | View information about the users on the system. usage: | diff --git a/commands/docs/table.md b/commands/docs/table.md index 83ef33d26aa..748aeb3b0af 100644 --- a/commands/docs/table.md +++ b/commands/docs/table.md @@ -2,7 +2,7 @@ title: table categories: | viewers -version: 0.100.0 +version: 0.101.0 viewers: | Render the table. usage: | diff --git a/commands/docs/take.md b/commands/docs/take.md index 0a8730510af..0176720d2c4 100644 --- a/commands/docs/take.md +++ b/commands/docs/take.md @@ -2,7 +2,7 @@ title: take categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Take only the first n elements of a list, or the first n bytes of a binary value. usage: | diff --git a/commands/docs/take_until.md b/commands/docs/take_until.md index 6c8123d87fa..bcd57d0259d 100644 --- a/commands/docs/take_until.md +++ b/commands/docs/take_until.md @@ -2,7 +2,7 @@ title: take until categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Take elements of the input until a predicate is true. usage: | diff --git a/commands/docs/take_while.md b/commands/docs/take_while.md index dfc6136e56a..61fa5595a34 100644 --- a/commands/docs/take_while.md +++ b/commands/docs/take_while.md @@ -2,7 +2,7 @@ title: take while categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Take elements of the input while a predicate is true. usage: | diff --git a/commands/docs/tee.md b/commands/docs/tee.md index 85fcc2c833c..fe73025c11a 100644 --- a/commands/docs/tee.md +++ b/commands/docs/tee.md @@ -2,7 +2,7 @@ title: tee categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Copy a stream to another command in parallel. usage: | diff --git a/commands/docs/term.md b/commands/docs/term.md new file mode 100644 index 00000000000..a772e7afea2 --- /dev/null +++ b/commands/docs/term.md @@ -0,0 +1,36 @@ +--- +title: term +categories: | + platform +version: 0.101.0 +platform: | + Commands for querying information about the terminal. +usage: | + Commands for querying information about the terminal. +--- + + +# `term` for [platform](/commands/categories/platform.md) + +
Commands for querying information about the terminal.
+ +## Signature + +```> term {flags} ``` + + +## Input/output types: + +| input | output | +| ------- | ------ | +| nothing | string | + +## Notes +You must use one of the following subcommands. Using this command as-is will only produce this help message. + +## Subcommands: + +| name | description | type | +| -------------------------------------------- | -------------------------------------------------------------------------------------------- | -------- | +| [`term query`](/commands/docs/term_query.md) | Query the terminal for information. | built-in | +| [`term size`](/commands/docs/term_size.md) | Returns a record containing the number of columns (width) and rows (height) of the terminal. | built-in | \ No newline at end of file diff --git a/commands/docs/term_query.md b/commands/docs/term_query.md new file mode 100644 index 00000000000..e8b810e6889 --- /dev/null +++ b/commands/docs/term_query.md @@ -0,0 +1,73 @@ +--- +title: term query +categories: | + platform +version: 0.101.0 +platform: | + Query the terminal for information. +usage: | + Query the terminal for information. +--- + + +# `term query` for [platform](/commands/categories/platform.md) + +
Query the terminal for information.
+ +## Signature + +```> term query {flags} (query)``` + +## Flags + + - `--prefix, -p {one_of(binary, string)}`: Prefix sequence for the expected reply. + - `--terminator, -t {one_of(binary, string)}`: Terminator sequence for the expected reply. + - `--keep, -k`: Include prefix and terminator in the output. + +## Parameters + + - `query`: The query that will be printed to stdout. + + +## Input/output types: + +| input | output | +| ------- | ------ | +| nothing | binary | + +## Examples + +Get cursor position. +```nu +> term query (ansi cursor_position) --prefix (ansi csi) --terminator 'R' + +``` + +Get terminal background color. +```nu +> term query $'(ansi osc)10;?(ansi st)' --prefix $'(ansi osc)10;' --terminator (ansi st) + +``` + +Get terminal background color. (some terminals prefer `char bel` rather than `ansi st` as string terminator) +```nu +> term query $'(ansi osc)10;?(char bel)' --prefix $'(ansi osc)10;' --terminator (char bel) + +``` + +Read clipboard content on terminals supporting OSC-52. +```nu +> term query $'(ansi osc)52;c;?(ansi st)' --prefix $'(ansi osc)52;c;' --terminator (ansi st) + +``` + +## Notes +Print the given query, and read the immediate result from stdin. + +The standard input will be read right after `query` is printed, and consumed until the `terminator` +sequence is encountered. The `terminator` is not included in the output. + +If `terminator` is not supplied, input will be read until Ctrl-C is pressed. + +If `prefix` is supplied, input's initial bytes will be validated against it. +The `prefix` is not included in the output. \ No newline at end of file diff --git a/commands/docs/term_size.md b/commands/docs/term_size.md index 534ad309523..e2d9f8ed7d3 100644 --- a/commands/docs/term_size.md +++ b/commands/docs/term_size.md @@ -2,7 +2,7 @@ title: term size categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Returns a record containing the number of columns (width) and rows (height) of the terminal. usage: | diff --git a/commands/docs/timeit.md b/commands/docs/timeit.md index 7dac9d3e9c7..79756a22eb3 100644 --- a/commands/docs/timeit.md +++ b/commands/docs/timeit.md @@ -2,17 +2,17 @@ title: timeit categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | - Time the running time of a block. + Time how long it takes a closure to run. usage: | - Time the running time of a block. + Time how long it takes a closure to run. --- # `timeit` for [debug](/commands/categories/debug.md) -
Time the running time of a block.
+
Time how long it takes a closure to run.
## Signature @@ -20,7 +20,7 @@ usage: | ## Parameters - - `command`: The command or block to run. + - `command`: The closure to run. ## Input/output types: @@ -31,20 +31,31 @@ usage: | | nothing | duration | ## Examples -Times a command within a closure +Time a closure containing one command ```nu > timeit { sleep 500ms } ``` -Times a command using an existing input +Time a closure with an input value ```nu -> http get https://www.nushell.sh/book/ | timeit { split chars } +> 'A really long string' | timeit { split chars } ``` -Times a command invocation +Time a closure with an input stream ```nu -> timeit ls -la +> open some_file.txt | collect | timeit { split chars } ``` + +Time a closure containing a pipeline +```nu +> timeit { open some_file.txt | split chars } + +``` + +## Notes +Any pipeline input given to this command is passed to the closure. Note that streaming inputs may affect timing results, and it is recommended to add a `collect` command before this if the input is a stream. + +This command will bubble up any errors encountered when running the closure. The return pipeline of the closure is collected into a value and then discarded. \ No newline at end of file diff --git a/commands/docs/to.md b/commands/docs/to.md index 007805955b9..ce334c26035 100644 --- a/commands/docs/to.md +++ b/commands/docs/to.md @@ -2,7 +2,7 @@ title: to categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Translate structured data to a format. usage: | diff --git a/commands/docs/to_csv.md b/commands/docs/to_csv.md index 2948bf77bf1..c675196c619 100644 --- a/commands/docs/to_csv.md +++ b/commands/docs/to_csv.md @@ -2,7 +2,7 @@ title: to csv categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert table into .csv text . usage: | diff --git a/commands/docs/to_html.md b/commands/docs/to_html.md index 92631e5ee76..442b61155cc 100644 --- a/commands/docs/to_html.md +++ b/commands/docs/to_html.md @@ -2,7 +2,7 @@ title: to html categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert table into simple HTML. usage: | diff --git a/commands/docs/to_json.md b/commands/docs/to_json.md index e4c3c71dcf9..0fd5c8c7fda 100644 --- a/commands/docs/to_json.md +++ b/commands/docs/to_json.md @@ -2,7 +2,7 @@ title: to json categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Converts table data into JSON text. usage: | diff --git a/commands/docs/to_md.md b/commands/docs/to_md.md index 825b7b3578d..38b69d441ba 100644 --- a/commands/docs/to_md.md +++ b/commands/docs/to_md.md @@ -2,7 +2,7 @@ title: to md categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert table into simple Markdown. usage: | diff --git a/commands/docs/to_msgpack.md b/commands/docs/to_msgpack.md index a6febc8d256..6ced502c8b4 100644 --- a/commands/docs/to_msgpack.md +++ b/commands/docs/to_msgpack.md @@ -2,7 +2,7 @@ title: to msgpack categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert Nu values into MessagePack. usage: | diff --git a/commands/docs/to_msgpackz.md b/commands/docs/to_msgpackz.md index 70885582142..57a48b7a541 100644 --- a/commands/docs/to_msgpackz.md +++ b/commands/docs/to_msgpackz.md @@ -2,7 +2,7 @@ title: to msgpackz categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert Nu values into brotli-compressed MessagePack. usage: | diff --git a/commands/docs/to_nuon.md b/commands/docs/to_nuon.md index b0247488cd0..d3a549e6eeb 100644 --- a/commands/docs/to_nuon.md +++ b/commands/docs/to_nuon.md @@ -2,7 +2,7 @@ title: to nuon categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Converts table data into Nuon (Nushell Object Notation) text. usage: | diff --git a/commands/docs/to_plist.md b/commands/docs/to_plist.md index 68d0b26490e..f9c936e1ed1 100644 --- a/commands/docs/to_plist.md +++ b/commands/docs/to_plist.md @@ -2,7 +2,7 @@ title: to plist categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert Nu values into plist usage: | diff --git a/commands/docs/to_text.md b/commands/docs/to_text.md index 431aa74add1..7f5cc40cf31 100644 --- a/commands/docs/to_text.md +++ b/commands/docs/to_text.md @@ -2,7 +2,7 @@ title: to text categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Converts data into simple text. usage: | diff --git a/commands/docs/to_toml.md b/commands/docs/to_toml.md index 055cdeecc47..6f8bbc02ec4 100644 --- a/commands/docs/to_toml.md +++ b/commands/docs/to_toml.md @@ -2,7 +2,7 @@ title: to toml categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert record into .toml text. usage: | diff --git a/commands/docs/to_tsv.md b/commands/docs/to_tsv.md index b374c58043c..804d45d21c2 100644 --- a/commands/docs/to_tsv.md +++ b/commands/docs/to_tsv.md @@ -2,7 +2,7 @@ title: to tsv categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert table into .tsv text. usage: | diff --git a/commands/docs/to_xml.md b/commands/docs/to_xml.md index 119bb686f39..0aced66ded2 100644 --- a/commands/docs/to_xml.md +++ b/commands/docs/to_xml.md @@ -2,7 +2,7 @@ title: to xml categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert special record structure into .xml text. usage: | diff --git a/commands/docs/to_yaml.md b/commands/docs/to_yaml.md index b255b16ee62..56eb7ad20f9 100644 --- a/commands/docs/to_yaml.md +++ b/commands/docs/to_yaml.md @@ -2,7 +2,7 @@ title: to yaml categories: | formats -version: 0.100.0 +version: 0.101.0 formats: | Convert table into .yaml/.yml text. usage: | diff --git a/commands/docs/touch.md b/commands/docs/touch.md index 415f2a70265..2f3dd7fc33d 100644 --- a/commands/docs/touch.md +++ b/commands/docs/touch.md @@ -2,7 +2,7 @@ title: touch categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Creates one or more files. usage: | diff --git a/commands/docs/transpose.md b/commands/docs/transpose.md index 39a18110bbd..a08b070c887 100644 --- a/commands/docs/transpose.md +++ b/commands/docs/transpose.md @@ -2,7 +2,7 @@ title: transpose categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Transposes the table contents so rows become columns and columns become rows. usage: | diff --git a/commands/docs/try.md b/commands/docs/try.md index ba5b23b40ec..49dc9849d15 100644 --- a/commands/docs/try.md +++ b/commands/docs/try.md @@ -2,7 +2,7 @@ title: try categories: | core -version: 0.100.0 +version: 0.101.0 core: | Try to run a block, if it fails optionally run a catch closure. usage: | diff --git a/commands/docs/tutor.md b/commands/docs/tutor.md index 14c773bcb5c..47d854da971 100644 --- a/commands/docs/tutor.md +++ b/commands/docs/tutor.md @@ -2,7 +2,7 @@ title: tutor categories: | misc -version: 0.100.0 +version: 0.101.0 misc: | Run the tutorial. To begin, run: tutor. usage: | diff --git a/commands/docs/ulimit.md b/commands/docs/ulimit.md index 44960660480..9a8d914d6b9 100644 --- a/commands/docs/ulimit.md +++ b/commands/docs/ulimit.md @@ -2,7 +2,7 @@ title: ulimit categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Set or get resource usage limits. usage: | @@ -25,20 +25,11 @@ usage: | - `--all, -a`: Prints all current limits - `--core-size, -c`: Maximum size of core files created - `--data-size, -d`: Maximum size of a process's data segment - - `--nice, -e`: Controls of maximum nice priority - `--file-size, -f`: Maximum size of files created by the shell - - `--pending-signals, -i`: Maximum number of pending signals - - `--lock-size, -l`: Maximum size that may be locked into memory - - `--resident-set-size, -m`: Maximum resident set size - `--file-descriptor-count, -n`: Maximum number of open file descriptors - - `--queue-size, -q`: Maximum bytes in POSIX message queues - - `--realtime-priority, -r`: Maximum realtime scheduling priority - `--stack-size, -s`: Maximum stack size - `--cpu-time, -t`: Maximum amount of CPU time in seconds - - `--process-count, -u`: Maximum number of processes available to the current user - `--virtual-memory-size, -v`: Maximum amount of virtual memory available to each process - - `--file-locks, -x`: Maximum number of file locks - - `--realtime-maxtime, -y`: Maximum contiguous realtime CPU time ## Parameters diff --git a/commands/docs/uname.md b/commands/docs/uname.md index 9178c87b52e..bc84deeedb1 100644 --- a/commands/docs/uname.md +++ b/commands/docs/uname.md @@ -2,7 +2,7 @@ title: uname categories: | system -version: 0.100.0 +version: 0.101.0 system: | Print certain system information using uutils/coreutils uname. usage: | diff --git a/commands/docs/uniq-by.md b/commands/docs/uniq-by.md index e1589209be2..9b5dc8a0834 100644 --- a/commands/docs/uniq-by.md +++ b/commands/docs/uniq-by.md @@ -2,7 +2,7 @@ title: uniq-by categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Return the distinct values in the input by the given column(s). usage: | diff --git a/commands/docs/uniq.md b/commands/docs/uniq.md index 92bd5bdea37..8626df5fffa 100644 --- a/commands/docs/uniq.md +++ b/commands/docs/uniq.md @@ -2,7 +2,7 @@ title: uniq categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Return the distinct values in the input. usage: | diff --git a/commands/docs/update.md b/commands/docs/update.md index f16e570edb4..fc2d96702d0 100644 --- a/commands/docs/update.md +++ b/commands/docs/update.md @@ -2,7 +2,7 @@ title: update categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Update an existing column to have a new value. usage: | diff --git a/commands/docs/update_cells.md b/commands/docs/update_cells.md index afd8e855108..d7e6d19eedd 100644 --- a/commands/docs/update_cells.md +++ b/commands/docs/update_cells.md @@ -2,7 +2,7 @@ title: update cells categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Update the table cells. usage: | @@ -47,11 +47,11 @@ Update the zero value cells to empty strings. $value } } -╭───┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────╮ -│ # │ 2021-04-16 │ 2021-06-10 │ 2021-09-18 │ 2021-10-15 │ 2021-11-16 │ 2021-11-17 │ 2021-11-18 │ -├───┼────────────┼────────────┼────────────┼────────────┼────────────┼────────────┼────────────┤ -│ 0 │ 37 │ │ │ │ 37 │ │ │ -╰───┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────╯ +╭──────┬───────────────┬───────────────┬───────────────┬───────────────┬───────────────┬───────────────┬──────────────╮ +│ # │ 2021-04-16 │ 2021-06-10 │ 2021-09-18 │ 2021-10-15 │ 2021-11-16 │ 2021-11-17 │ 2021-11-18 │ +├──────┼───────────────┼───────────────┼───────────────┼───────────────┼───────────────┼───────────────┼──────────────┤ +│ 0 │ 37 │ │ │ │ 37 │ │ │ +╰──────┴───────────────┴───────────────┴───────────────┴───────────────┴───────────────┴───────────────┴──────────────╯ ``` @@ -67,10 +67,10 @@ Update the zero value cells to empty strings in 2 last columns. $value } } -╭───┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────╮ -│ # │ 2021-04-16 │ 2021-06-10 │ 2021-09-18 │ 2021-10-15 │ 2021-11-16 │ 2021-11-17 │ 2021-11-18 │ -├───┼────────────┼────────────┼────────────┼────────────┼────────────┼────────────┼────────────┤ -│ 0 │ 37 │ 0 │ 0 │ 0 │ 37 │ │ │ -╰───┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────╯ +╭──────┬───────────────┬───────────────┬───────────────┬───────────────┬───────────────┬───────────────┬──────────────╮ +│ # │ 2021-04-16 │ 2021-06-10 │ 2021-09-18 │ 2021-10-15 │ 2021-11-16 │ 2021-11-17 │ 2021-11-18 │ +├──────┼───────────────┼───────────────┼───────────────┼───────────────┼───────────────┼───────────────┼──────────────┤ +│ 0 │ 37 │ 0 │ 0 │ 0 │ 37 │ │ │ +╰──────┴───────────────┴───────────────┴───────────────┴───────────────┴───────────────┴───────────────┴──────────────╯ ``` diff --git a/commands/docs/upsert.md b/commands/docs/upsert.md index 0d0f153697a..0034576266e 100644 --- a/commands/docs/upsert.md +++ b/commands/docs/upsert.md @@ -2,7 +2,7 @@ title: upsert categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Update an existing column to have a new value, or insert a new column. usage: | diff --git a/commands/docs/url.md b/commands/docs/url.md index 36c320ad9da..1747d304916 100644 --- a/commands/docs/url.md +++ b/commands/docs/url.md @@ -2,7 +2,7 @@ title: url categories: | network -version: 0.100.0 +version: 0.101.0 network: | Various commands for working with URLs. usage: | diff --git a/commands/docs/url_build-query.md b/commands/docs/url_build-query.md index 12813de622d..10d87f4f761 100644 --- a/commands/docs/url_build-query.md +++ b/commands/docs/url_build-query.md @@ -2,7 +2,7 @@ title: url build-query categories: | network -version: 0.100.0 +version: 0.101.0 network: | Converts record or table into query string applying percent-encoding. usage: | diff --git a/commands/docs/url_decode.md b/commands/docs/url_decode.md index a5c7138c7b4..22422e54066 100644 --- a/commands/docs/url_decode.md +++ b/commands/docs/url_decode.md @@ -2,7 +2,7 @@ title: url decode categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Converts a percent-encoded web safe string to a string. usage: | diff --git a/commands/docs/url_encode.md b/commands/docs/url_encode.md index c9f73b5d513..3ff1bd37c74 100644 --- a/commands/docs/url_encode.md +++ b/commands/docs/url_encode.md @@ -2,7 +2,7 @@ title: url encode categories: | strings -version: 0.100.0 +version: 0.101.0 strings: | Converts a string to a percent encoded web safe string. usage: | diff --git a/commands/docs/url_join.md b/commands/docs/url_join.md index 4bd595c7624..d9441be8753 100644 --- a/commands/docs/url_join.md +++ b/commands/docs/url_join.md @@ -2,7 +2,7 @@ title: url join categories: | network -version: 0.100.0 +version: 0.101.0 network: | Converts a record to url. usage: | diff --git a/commands/docs/url_parse.md b/commands/docs/url_parse.md index d2993e1e0cc..a8d8570bf6f 100644 --- a/commands/docs/url_parse.md +++ b/commands/docs/url_parse.md @@ -2,7 +2,7 @@ title: url parse categories: | network -version: 0.100.0 +version: 0.101.0 network: | Parses a url. usage: | diff --git a/commands/docs/url_split-query.md b/commands/docs/url_split-query.md index 6e2a3889d45..d2eced92988 100644 --- a/commands/docs/url_split-query.md +++ b/commands/docs/url_split-query.md @@ -2,7 +2,7 @@ title: url split-query categories: | network -version: 0.100.0 +version: 0.101.0 network: | Converts query string into table applying percent-decoding. usage: | diff --git a/commands/docs/use.md b/commands/docs/use.md index 78e9e4d03a2..97d89a269a6 100644 --- a/commands/docs/use.md +++ b/commands/docs/use.md @@ -2,7 +2,7 @@ title: use categories: | core -version: 0.100.0 +version: 0.101.0 core: | Use definitions from a module, making them available in your shell. usage: | diff --git a/commands/docs/utouch.md b/commands/docs/utouch.md new file mode 100644 index 00000000000..b89ff9788bc --- /dev/null +++ b/commands/docs/utouch.md @@ -0,0 +1,90 @@ +--- +title: utouch +categories: | + filesystem +version: 0.101.0 +filesystem: | + Creates one or more files. +usage: | + Creates one or more files. +--- + + +# `utouch` for [filesystem](/commands/categories/filesystem.md) + +
Creates one or more files.
+ +## Signature + +```> utouch {flags} ...rest``` + +## Flags + + - `--reference, -r {path}`: Use the access and modification times of the reference file/directory instead of the current time + - `--timestamp, -t {datetime}`: Use the given timestamp instead of the current time + - `--date, -d {string}`: Use the given time instead of the current time. This can be a full timestamp or it can be relative to either the current time or reference file time (if given). For more information, see https://www.gnu.org/software/coreutils/manual/html_node/touch-invocation.html + - `--modified, -m`: Change only the modification time (if used with -a, access time is changed too) + - `--access, -a`: Change only the access time (if used with -m, modification time is changed too) + - `--no-create, -c`: Don't create the file if it doesn't exist + - `--no-deref, -s`: Affect each symbolic link instead of any referenced file (only for systems that can change the timestamps of a symlink). Ignored if touching stdout + +## Parameters + + - `...rest`: The file(s) to create. '-' is used to represent stdout. + + +## Input/output types: + +| input | output | +| ------- | ------- | +| nothing | nothing | + +## Examples + +Creates "fixture.json" +```nu +> utouch fixture.json + +``` + +Creates files a, b and c +```nu +> utouch a b c + +``` + +Changes the last modified time of "fixture.json" to today's date +```nu +> utouch -m fixture.json + +``` + +Changes the last accessed and modified times of files a, b and c to the current time but yesterday +```nu +> utouch -d "yesterday" a b c + +``` + +Changes the last modified time of files d and e to "fixture.json"'s last modified time +```nu +> utouch -m -r fixture.json d e + +``` + +Changes the last accessed time of "fixture.json" to a datetime +```nu +> utouch -a -t 2019-08-24T12:30:30 fixture.json + +``` + +Change the last accessed and modified times of stdout +```nu +> utouch - + +``` + +Changes the last accessed and modified times of file a to 1 month before "fixture.json"'s last modified time +```nu +> utouch -r fixture.json -d "-1 month" a + +``` diff --git a/commands/docs/values.md b/commands/docs/values.md index c71717aa31a..c198d208330 100644 --- a/commands/docs/values.md +++ b/commands/docs/values.md @@ -2,7 +2,7 @@ title: values categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Given a record or table, produce a list of its columns' values. usage: | diff --git a/commands/docs/version.md b/commands/docs/version.md index 265693f0fe4..5cad03570ca 100644 --- a/commands/docs/version.md +++ b/commands/docs/version.md @@ -2,7 +2,7 @@ title: version categories: | core -version: 0.100.0 +version: 0.101.0 core: | Display Nu version, and its build configuration. usage: | diff --git a/commands/docs/view.md b/commands/docs/view.md index aef24356ab0..5154a3c596c 100644 --- a/commands/docs/view.md +++ b/commands/docs/view.md @@ -2,7 +2,7 @@ title: view categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | Various commands for viewing debug information. usage: | @@ -30,9 +30,10 @@ You must use one of the following subcommands. Using this command as-is will onl ## Subcommands: -| name | description | type | -| ---------------------------------------------- | ---------------------------------------------------------- | -------- | -| [`view files`](/commands/docs/view_files.md) | View the files registered in nushell's EngineState memory. | built-in | -| [`view ir`](/commands/docs/view_ir.md) | View the compiled IR code for a block of code. | built-in | -| [`view source`](/commands/docs/view_source.md) | View a block, module, or a definition. | built-in | -| [`view span`](/commands/docs/view_span.md) | View the contents of a span. | built-in | \ No newline at end of file +| name | description | type | +| ---------------------------------------------- | ----------------------------------------------------------- | -------- | +| [`view blocks`](/commands/docs/view_blocks.md) | View the blocks registered in nushell's EngineState memory. | built-in | +| [`view files`](/commands/docs/view_files.md) | View the files registered in nushell's EngineState memory. | built-in | +| [`view ir`](/commands/docs/view_ir.md) | View the compiled IR code for a block of code. | built-in | +| [`view source`](/commands/docs/view_source.md) | View a block, module, or a definition. | built-in | +| [`view span`](/commands/docs/view_span.md) | View the contents of a span. | built-in | \ No newline at end of file diff --git a/commands/docs/view_blocks.md b/commands/docs/view_blocks.md new file mode 100644 index 00000000000..3dc9f43aea8 --- /dev/null +++ b/commands/docs/view_blocks.md @@ -0,0 +1,37 @@ +--- +title: view blocks +categories: | + debug +version: 0.101.0 +debug: | + View the blocks registered in nushell's EngineState memory. +usage: | + View the blocks registered in nushell's EngineState memory. +--- + + +# `view blocks` for [debug](/commands/categories/debug.md) + +
View the blocks registered in nushell's EngineState memory.
+ +## Signature + +```> view blocks {flags} ``` + + +## Input/output types: + +| input | output | +| ------- | ----------------------------------------------------------- | +| nothing | table\ | + +## Examples + +View the blocks registered in Nushell's EngineState memory +```nu +> view blocks + +``` + +## Notes +These are blocks parsed and loaded at runtime as well as any blocks that accumulate in the repl. \ No newline at end of file diff --git a/commands/docs/view_files.md b/commands/docs/view_files.md index a4a9dfcc2cc..0c9a140a711 100644 --- a/commands/docs/view_files.md +++ b/commands/docs/view_files.md @@ -2,7 +2,7 @@ title: view files categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | View the files registered in nushell's EngineState memory. usage: | diff --git a/commands/docs/view_ir.md b/commands/docs/view_ir.md index 98dc9db00b8..18da54f57bb 100644 --- a/commands/docs/view_ir.md +++ b/commands/docs/view_ir.md @@ -2,7 +2,7 @@ title: view ir categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | View the compiled IR code for a block of code. usage: | diff --git a/commands/docs/view_source.md b/commands/docs/view_source.md index 4c1673ae242..160c9f2a4af 100644 --- a/commands/docs/view_source.md +++ b/commands/docs/view_source.md @@ -2,7 +2,7 @@ title: view source categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | View a block, module, or a definition. usage: | diff --git a/commands/docs/view_span.md b/commands/docs/view_span.md index 62a82dac792..ded3c0ec5e8 100644 --- a/commands/docs/view_span.md +++ b/commands/docs/view_span.md @@ -2,7 +2,7 @@ title: view span categories: | debug -version: 0.100.0 +version: 0.101.0 debug: | View the contents of a span. usage: | diff --git a/commands/docs/watch.md b/commands/docs/watch.md index 62bff49289c..70e5d1962a9 100644 --- a/commands/docs/watch.md +++ b/commands/docs/watch.md @@ -2,7 +2,7 @@ title: watch categories: | filesystem -version: 0.100.0 +version: 0.101.0 filesystem: | Watch for file changes and execute Nu code when they happen. usage: | diff --git a/commands/docs/where.md b/commands/docs/where.md index 36d8f05cd43..39355daf8d0 100644 --- a/commands/docs/where.md +++ b/commands/docs/where.md @@ -2,7 +2,7 @@ title: where categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Filter values based on a row condition. usage: | diff --git a/commands/docs/which.md b/commands/docs/which.md index fcf012187d2..adfd095dc12 100644 --- a/commands/docs/which.md +++ b/commands/docs/which.md @@ -2,7 +2,7 @@ title: which categories: | system -version: 0.100.0 +version: 0.101.0 system: | Finds a program file, alias or custom command. usage: | diff --git a/commands/docs/while.md b/commands/docs/while.md index 2628996dc8b..2e501d93a72 100644 --- a/commands/docs/while.md +++ b/commands/docs/while.md @@ -2,7 +2,7 @@ title: while categories: | core -version: 0.100.0 +version: 0.101.0 core: | Conditionally run a block in a loop. usage: | diff --git a/commands/docs/whoami.md b/commands/docs/whoami.md index 31d3a6c89a3..eed33f55387 100644 --- a/commands/docs/whoami.md +++ b/commands/docs/whoami.md @@ -2,7 +2,7 @@ title: whoami categories: | platform -version: 0.100.0 +version: 0.101.0 platform: | Get the current username using uutils/coreutils whoami. usage: | diff --git a/commands/docs/window.md b/commands/docs/window.md index da005e47b0b..af4e88beccc 100644 --- a/commands/docs/window.md +++ b/commands/docs/window.md @@ -2,7 +2,7 @@ title: window categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Creates a sliding window of `window_size` that slide by n rows/elements across input. usage: | diff --git a/commands/docs/with-env.md b/commands/docs/with-env.md index 67bbc55d863..963a4330152 100644 --- a/commands/docs/with-env.md +++ b/commands/docs/with-env.md @@ -2,7 +2,7 @@ title: with-env categories: | env -version: 0.100.0 +version: 0.101.0 env: | Runs a block with an environment variable set. usage: | diff --git a/commands/docs/wrap.md b/commands/docs/wrap.md index b0a762cbd2e..66674d0a7bf 100644 --- a/commands/docs/wrap.md +++ b/commands/docs/wrap.md @@ -2,7 +2,7 @@ title: wrap categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Wrap the value into a column. usage: | diff --git a/commands/docs/zip.md b/commands/docs/zip.md index 580cb488ed2..51abd93d2e6 100644 --- a/commands/docs/zip.md +++ b/commands/docs/zip.md @@ -2,7 +2,7 @@ title: zip categories: | filters -version: 0.100.0 +version: 0.101.0 filters: | Combine a stream with the input. usage: | diff --git a/contributor-book/plugins.md b/contributor-book/plugins.md index 41ccbed9bea..d38259de24a 100644 --- a/contributor-book/plugins.md +++ b/contributor-book/plugins.md @@ -37,14 +37,14 @@ Let's create our project. For this example, we'll create a simple `len` command First off, we'll create our plugin: ```sh -> cargo new nu_plugin_len -> cd nu_plugin_len +cargo new nu_plugin_len +cd nu_plugin_len ``` Next, we'll add `nu` to our project's dependencies. ```sh -> cargo add nu-plugin nu-protocol +cargo add nu-plugin nu-protocol ``` The `Cargo.toml` file should now look something like the following. diff --git a/de/book/3rdpartyprompts.md b/de/book/3rdpartyprompts.md index acafab58c49..e1e97285e7f 100644 --- a/de/book/3rdpartyprompts.md +++ b/de/book/3rdpartyprompts.md @@ -22,7 +22,7 @@ Wenn [oh-my-posh](https://ohmyposh.dev/) verwendet werden soll, kann dies in wen 3. Die Umgebungsvariable `PROMPT_COMMAND` durch hinzufügen der folgenden Zeile in `~/.config/nushell/config.nu` setzen. Den Style `M365Princess.omp.json` kann man entsprechend der [Demo](https://ohmyposh.dev/docs/themes) beliebig ändern . ```nu -> $env.PROMPT_COMMAND = { oh-my-posh --config ~/.poshthemes/M365Princess.omp.json } +$env.PROMPT_COMMAND = { oh-my-posh --config ~/.poshthemes/M365Princess.omp.json } ``` ## Starship diff --git a/de/book/aliases.md b/de/book/aliases.md index bdcb7355976..33a2b82a63a 100644 --- a/de/book/aliases.md +++ b/de/book/aliases.md @@ -5,19 +5,19 @@ Aliase in Nushell bieten eine einfache Möglichkeit, um Texte zur ersetzen. Dami Beispielsweise kann ein Alias namens `ll` definiert werden, der den längeren Befehl `ls -l` ersetzt: ``` -> alias ll = ls -l +alias ll = ls -l ``` Nun kann der Alias aufgerufen werden: ``` -> ll +ll ``` Wenn das getan wird, wirkt es, als sei `ls -l` aufgerufen worden. Das bietet auch die Möglichkeit weitere Parameter anzugeben. So kann auch geschrieben werden: ``` -> ll -a +ll -a ``` Das ist äquivalent zu `ls -l -a`. Deutlich kürzer. diff --git a/de/book/coloring_and_theming.md b/de/book/coloring_and_theming.md index f058f0868ab..4be74e5893c 100644 --- a/de/book/coloring_and_theming.md +++ b/de/book/coloring_and_theming.md @@ -17,7 +17,7 @@ Tabellen Rahmen werden mit der Einstellung `table_mode` in der `config.nu` konfi Hier ein Beispiel: ```nu -> $env.config = { +$env.config = { table_mode: rounded } ``` @@ -273,7 +273,7 @@ Hier die aktuelle Liste von Primitiven Typen. Nicht alle davon sind konfigurierb Hier ein kleines Beispiel, wie diese Werte angewendet werden können. ```nu -> let config = { +let config = { color_config: { separator: purple leading_trailing_space_bg: "#ffffff" @@ -298,7 +298,7 @@ Hier ein kleines Beispiel, wie diese Werte angewendet werden können. Hier ein anderes Beispiel, welches mehrere Farben Schreibweisen sowie Kommentare verwendet. ```nu -> let config = { +let config = { color_config: { separator: "#88b719" # Dies setzt nur die Vordergrundsfarbe wie in PR #486 leading_trailing_space_bg: white # Dies setzt nur die Vordergrundsfarbe im ursprünglichen Stil @@ -352,7 +352,7 @@ Hier die aktuelle Formen Liste. Hier ein kleines Beispiel wie Farben auf diese Teile angewendet werden. Was nicht spezifiziert wird, erhält die Standardfarbe. ```nu -> $env.config = { +$env.config = { color_config: { shape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b} shape_bool: green @@ -375,13 +375,13 @@ Der Nushell Prompt ist konfigurierbar mit diesen Umgebungsvariablen: Beispiel: Für einen einfachen Prompt wäre folgendes mögllich. Hinweis `PROMPT_COMMAND` benötigt einen `block` wogegen die anderen einen `string` erwarten. ```nu -> $env.PROMPT_COMMAND = { build-string (date now | format date '%m/%d/%Y %I:%M:%S%.3f') ': ' (pwd | path basename) } +$env.PROMPT_COMMAND = { build-string (date now | format date '%m/%d/%Y %I:%M:%S%.3f') ': ' (pwd | path basename) } ``` Soll der standard `PROMPT_INDICATOR` geändert werden, sieht das so aus. ```nu -> $env.PROMPT_INDICATOR = "> " +$env.PROMPT_INDICATOR = "> " ``` Den Prompt einfärben wird duch den `block` `PROMPT_COMMAND` kontrolliert und individualisiert. diff --git a/de/book/configuration.md b/de/book/configuration.md index 4ce6f06da7f..b64fdd7646b 100644 --- a/de/book/configuration.md +++ b/de/book/configuration.md @@ -45,7 +45,7 @@ Um Nushell als Login-Shell zu verwenden, muss die `$env` Variable konfiguriert w Der komplette Satz an Umgebungsvariablen kann erzeugt werden, wenn Nu in einer anderen Shell, wie beispielsweise Bash, ausgeführt wird. In diese Nu-Sitzung kann ein Befehl wie der folgende verwendet werden, um `$env` zu setzen: ``` -> env | each { echo $"$env.($it.name) = '($it.raw)'" } | str join (char nl) +env | each { echo $"$env.($it.name) = '($it.raw)'" } | str join (char nl) ``` Das gibt Zeilen aus um `$env` in `env.nu` zu setzen - eine für jede Umgebungsvariable - inklusive der nötigen Werte. @@ -53,15 +53,15 @@ Das gibt Zeilen aus um `$env` in `env.nu` zu setzen - eine für jede Umgebungsva Als nächstes, muss auf manchen Distributionen sichergestellt werden, dass Nu in der Liste der Shells in /etc/shells ist: ``` -> cat /etc/shells -# /etc/shells: valid login shells -/bin/sh -/bin/dash -/bin/bash -/bin/rbash -/usr/bin/screen -/usr/bin/fish -/home/sophia/.cargo/bin/nu +cat /etc/shells +# => # /etc/shells: valid login shells +# => /bin/sh +# => /bin/dash +# => /bin/bash +# => /bin/rbash +# => /usr/bin/screen +# => /usr/bin/fish +# => /home/sophia/.cargo/bin/nu ``` Damit sollte es möglich sein, Nu als Login-Shell mit `chsh` festzulegen. Nach dem Ausloggen und erneutem Einloggen sollte Nu als Shell grüßen. diff --git a/de/book/custom_commands.md b/de/book/custom_commands.md index 61e8da6258b..0117e50b0b9 100644 --- a/de/book/custom_commands.md +++ b/de/book/custom_commands.md @@ -17,7 +17,7 @@ In dieser Definition, wird ein Befehl `greet` beschrieben, der einen Parameter ` Um den obigen Befehl auszuführen wird er wie ein eingebauter Befehl aufgerufen: ``` -> greet "world" +greet "world" ``` Wenn das getan wird, wird eine Ausgabe erzeugt, die wie die der eingebauten Befehle aussieht: @@ -48,7 +48,7 @@ def "str mycommand" [] { Jetzt kann der eigene Unterbefehl aufgerufen werden, als ob er ein eingebauter Befehl von `str` wäre: ``` -> str mycommand +str mycommand ``` ## Typen von Parametern @@ -130,19 +130,19 @@ In der obigen Definition von `greet`, werden ein fester Parameter `name` und ein Das obige Beispiel kann wie folgt aufgerufen werden: ``` -> greet world --age 10 +greet world --age 10 ``` Oder: ``` -> greet --age 10 world +greet --age 10 world ``` Oder gleich ganz ohne Flag: ``` -> greet world +greet world ``` Flags können auch so definiert werden, dass es eine Kurzform gibt. Das erlaubt es sowohl eine kurze als auch eine einfach lesbare lange Flag für die selbe Aufgabe zu haben. @@ -163,7 +163,7 @@ _Hinweis:_ Flags sind benannt nach der langen Form des Namens. Im obigen Beispie Nun kann diese neue Version von `greet` wie folgt aufgerufen werden: ``` -> greet -a 10 hello +greet -a 10 hello ``` ## Dokumentation für den eigenen Befehl diff --git a/de/book/custom_completions.md b/de/book/custom_completions.md index 73ed1c0cb89..ad73d2ae424 100644 --- a/de/book/custom_completions.md +++ b/de/book/custom_completions.md @@ -13,10 +13,10 @@ Dem Befehl, der die Vervollständigung bereitstellt, und die Verknüpfung mit de Hier ein Beispiel: ``` -> def tiere [] { ["katze", "hund", "aal" ] } -> def my-command [tier: string@tiere] { print $tier } ->| my-command -katze hund aal +def tiere [] { ["katze", "hund", "aal" ] } +def my-command [tier: string@tiere] { print $tier } +| my-command +# => katze hund aal ``` In der ersten Zeile wird ein eigener Befehl erstellt, der eine Liste von drei verschiedenen Tieren zurückgibt. diff --git a/de/book/environment.md b/de/book/environment.md index dea25df4c2b..8f082c08009 100644 --- a/de/book/environment.md +++ b/de/book/environment.md @@ -36,7 +36,7 @@ Umgebungsvariablen werden als Felder der Variable `$env` gesetzt. Um die Umgebungsvariable `FOO` zu setzen kann direkt der Wert zu `$env.FOO` zugewiesen werden. ``` -> $env.FOO = 'BAR' +$env.FOO = 'BAR' ``` Um zum Beispiel die `PATH` Variable zu ergänzen, wird folgendes eingegeben: @@ -54,7 +54,7 @@ Wenn mehrere Umgebungsvariablen gesetzt werden sollen, so kann `load-env` eine g Diese besteht aus name/value Paaren, welche alle auf einmal geladen werden: ``` -> load-env { "BOB": "FOO", "JAY": "BAR" } +load-env { "BOB": "FOO", "JAY": "BAR" } ``` ### Einmalig verwendete Umgebungsvariablen @@ -77,14 +77,14 @@ Wenn eine Umgebungsvariable gesetzt wird, ist sie nur in ihrem Gültigkeitsberei Hier ein kleines Beispiel um den Gültigkeitsbereich zu demonstrieren: ``` -> $env.FOO = "BAR" -> do { +$env.FOO = "BAR" +do { $env.FOO = "BAZ" $env.FOO == "BAZ" } -true -> $env.FOO == "BAR" -true +# => true +$env.FOO == "BAR" +# => true ``` ## Verzeichnis Wechsel @@ -98,15 +98,15 @@ Dies wiederum folgt den gleichen Regeln wie das setzen anderer Umgebungsvariable Eine praktische Möglichkeit eine Umgebungsvariable einmalig zu setzen, ist inspiriert von Bash und anderen Shells: ``` -> FOO=BAR echo $env.FOO -BAR +FOO=BAR echo $env.FOO +# => BAR ``` Es kann auch [`with-env`](/commands/docs/with-env.md) verwendet werden um expliziter zu sein: ``` -> with-env { FOO: BAR } { echo $env.FOO } -BAR +with-env { FOO: BAR } { echo $env.FOO } +# => BAR ``` Der [`with-env`](/commands/docs/with-env.md) Befehl setzt die Umgebungsvariable temporär (hier wird die Variable "FOO" auf den Wert "BAR" gesetzt) @@ -129,14 +129,14 @@ Wird sie jedoch mit [`def --env`](/commands/docs/def.md) anstatt [`def`](/comman (Gilt auch für `export def`, siehe [Modules (EN)](/book/modules.md)) ``` -> def --env foo [] { +def --env foo [] { $env.FOO = 'BAR' } -> foo +foo -> $env.FOO -BAR +$env.FOO +# => BAR ``` ## Umgebungsvariablen konvertieren @@ -166,26 +166,26 @@ $env.ENV_CONVERSIONS = { In einer Nushell Instanz gilt nun: ``` -> with-env { FOO : 'a-b-c' } { nu } # runs Nushell with FOO env. var. set to 'a-b-c' +with-env { FOO : 'a-b-c' } { nu } # runs Nushell with FOO env. var. set to 'a-b-c' -> $env.FOO - 0 a - 1 b - 2 c +$env.FOO +# => 0 a +# => 1 b +# => 2 c ``` Wie zu sehen ist `$env.FOO` nun eine Liste in einer neuen Nushell Instanz mit der neuen config. Die Konvertierung kann auch manuell getestet werden mit: ``` -> do $env.ENV_CONVERSIONS.FOO.from_string 'a-b-c' +do $env.ENV_CONVERSIONS.FOO.from_string 'a-b-c' ``` Um die Konvertierun list -> string zu testen: ``` -> nu -c '$env.FOO' -a-b-c +nu -c '$env.FOO' +# => a-b-c ``` Weil `nu` selber ein externer Befehl ist, übersetzt Nushell die `[ a b c ]` Liste gemäss `ENV_CONVERSIONS.FOO.to_string` und übergibt sie dem `nu` Prozess. @@ -208,21 +208,21 @@ Alle Umgebungsvariablen in env.nu und config.nu sind immer noch Strings solange Umgebungsvariablen können im aktuellen Gültigkeitsbereich entfernt werden via [`hide`](/commands/docs/hide.md): ``` -> $env.FOO = 'BAR' -... -> hide FOO +$env.FOO = 'BAR' +# => ... +hide FOO ``` Dieses Verstecken im Gültigkeitsbereich erlaubt es gleichzeitig temporär eine Variabel zu entfernen ohne dass man die höher gelegene Umgebung modifiziert wird: ``` -> $env.FOO = 'BAR' -> do { +$env.FOO = 'BAR' +do { hide FOO # $env.FOO does not exist } -> $env.FOO -BAR +$env.FOO +# => BAR ``` Mehr Informationen über Verstecken findet sich im Kapitel [Modules](/book/modules.md) diff --git a/de/book/escaping.md b/de/book/escaping.md index 031d3124c7b..809cc6214d8 100644 --- a/de/book/escaping.md +++ b/de/book/escaping.md @@ -5,11 +5,11 @@ Nushell stellt einen identischen Satz an Befehlen für verschiedene Systeme zur Nushell Befehl: ``` -> ls +ls ``` Aufruf des Systembefehls: ``` -> ^ls +^ls ``` diff --git a/de/book/hooks.md b/de/book/hooks.md index 38a752058e0..444ce3fd2f0 100644 --- a/de/book/hooks.md +++ b/de/book/hooks.md @@ -89,12 +89,12 @@ Umgebungsvariablen im Hook **Block** werden in ähnlicher Weise wie [`def --env` Folgendes Beispiel zeigt dies: ``` -> $env.config = ($env.config | upsert hooks { +$env.config = ($env.config | upsert hooks { pre_prompt: { $env.SPAM = "eggs" } }) -> $env.SPAM -eggs +$env.SPAM +# => eggs ``` Die Hookblöcke folgen ansonsten den allgemeinen Scoping-Regeln, d.h. Befehle, Aliase, etc., die innerhalb des Blocks definiert sind, @@ -152,11 +152,11 @@ Dies funktioniert, als ob der String in den REPL eingeben und Enter gedrückt wi So kann der Hook aus dem vorherigen Abschnitt auch geschrieben werden als: ``` -> $env.config = ($env.config | upsert hooks { +$env.config = ($env.config | upsert hooks { pre_prompt: '$env.SPAM = "eggs"' }) -> $env.SPAM +$env.SPAM eggs ``` Dieses Feature kann z.B. verwendet werden, um abhängig vom aktuellen Verzeichnis Definitionen einzubringen: diff --git a/de/book/loading_data.md b/de/book/loading_data.md index 1996f88fcfd..8f00aa30729 100644 --- a/de/book/loading_data.md +++ b/de/book/loading_data.md @@ -23,8 +23,8 @@ Soll nur die Version aus dem Projekt angezeigt werden, kann mit dem [`get`](/com direkt diese Information herausgelesen werden. ``` -> open editors/vscode/package.json | get version -1.0.0 +open editors/vscode/package.json | get version +# => 1.0.0 ``` Nu unterstützt aktuell die folgenden Formate um Daten direkt als Tabelle zu öffnen: @@ -48,7 +48,7 @@ Nu unterstützt aktuell die folgenden Formate um Daten direkt als Tabelle zu öf Was aber passiert, wenn eine Text Datei geladen wird, die keinem der angegebenen Formate entspricht? ``` -> open README.md +# => open README.md ``` Die Datei wird wie gewohnt als Text ausgegeben. @@ -64,10 +64,10 @@ Oft werden diese Daten als String repräsentiert. Zum Beispiel wie in dieser Datei: ``` -> open people.txt -Octavia | Butler | Writer -Bob | Ross | Painter -Antonio | Vivaldi | Composer +open people.txt +# => Octavia | Butler | Writer +# => Bob | Ross | Painter +# => Antonio | Vivaldi | Composer ``` Jeder Datenpunkt ist durch ein pipe ('|') Symbol getrennt. Und jede Person steht auf einer @@ -77,12 +77,12 @@ weshalb diese Datei von Hand geparst werden muss. Zuerst wird die Datei so geladen, dass jede Zeile für sich verarbeitet werden kann: ``` -> open people.txt | lines -───┬────────────────────────────── - 0 │ Octavia | Butler | Writer - 1 │ Bob | Ross | Painter - 2 │ Antonio | Vivaldi | Composer -───┴────────────────────────────── +open people.txt | lines +# => ───┬────────────────────────────── +# => 0 │ Octavia | Butler | Writer +# => 1 │ Bob | Ross | Painter +# => 2 │ Antonio | Vivaldi | Composer +# => ───┴────────────────────────────── ``` Dadurch wird bereits wieder eine Liste ausgegeben. Im nächsten Schritt sollen die Zeilen @@ -93,67 +93,67 @@ Mit dem `column` Unterbefehl wird der Inhalt über mehrere Spalten aufgeteilt. Als Parameter reicht das Trennzeichen, der Rest ist automatisch: ``` -> open people.txt | lines | split column "|" -───┬──────────┬───────────┬─────────── - # │ column1 │ column2 │ column3 -───┼──────────┼───────────┼─────────── - 0 │ Octavia │ Butler │ Writer - 1 │ Bob │ Ross │ Painter - 2 │ Antonio │ Vivaldi │ Composer -───┴──────────┴───────────┴─────────── +open people.txt | lines | split column "|" +# => ───┬──────────┬───────────┬─────────── +# => # │ column1 │ column2 │ column3 +# => ───┼──────────┼───────────┼─────────── +# => 0 │ Octavia │ Butler │ Writer +# => 1 │ Bob │ Ross │ Painter +# => 2 │ Antonio │ Vivaldi │ Composer +# => ───┴──────────┴───────────┴─────────── ``` Das sieht _fast_ korrekt aus.Es sieht so aus, als ob sich noch eine zusätzliche Lücke eingeschlichen hat. Mit dem [`trim`](/commands/docs/str_trim.md) Befehl wird dieser beseitigt: ``` -> open people.txt | lines | split column "|" | str trim -───┬─────────┬─────────┬────────── - # │ column1 │ column2 │ column3 -───┼─────────┼─────────┼────────── - 0 │ Octavia │ Butler │ Writer - 1 │ Bob │ Ross │ Painter - 2 │ Antonio │ Vivaldi │ Composer -───┴─────────┴─────────┴────────── +open people.txt | lines | split column "|" | str trim +# => ───┬─────────┬─────────┬────────── +# => # │ column1 │ column2 │ column3 +# => ───┼─────────┼─────────┼────────── +# => 0 │ Octavia │ Butler │ Writer +# => 1 │ Bob │ Ross │ Painter +# => 2 │ Antonio │ Vivaldi │ Composer +# => ───┴─────────┴─────────┴────────── ``` Nicht schlecht. Der [`split`](/commands/docs/split.md) Befehl gibt nicht nur brauchbare Daten zurück, sondern bezeichnet auch noch standardmässig die Spaltennamen: ``` -> open people.txt | lines | split column "|" | str trim | get column1 -───┬───────── - 0 │ Octavia - 1 │ Bob - 2 │ Antonio -───┴───────── +open people.txt | lines | split column "|" | str trim | get column1 +# => ───┬───────── +# => 0 │ Octavia +# => 1 │ Bob +# => 2 │ Antonio +# => ───┴───────── ``` Die Spalten können jedoch auch benannt werden: ``` -> open people.txt | lines | split column "|" first_name last_name job | str trim -───┬────────────┬───────────┬────────── - # │ first_name │ last_name │ job -───┼────────────┼───────────┼────────── - 0 │ Octavia │ Butler │ Writer - 1 │ Bob │ Ross │ Painter - 2 │ Antonio │ Vivaldi │ Composer -───┴────────────┴───────────┴────────── +open people.txt | lines | split column "|" first_name last_name job | str trim +# => ───┬────────────┬───────────┬────────── +# => # │ first_name │ last_name │ job +# => ───┼────────────┼───────────┼────────── +# => 0 │ Octavia │ Butler │ Writer +# => 1 │ Bob │ Ross │ Painter +# => 2 │ Antonio │ Vivaldi │ Composer +# => ───┴────────────┴───────────┴────────── ``` Jetzt da die Daten in einer Tabelle sind, können alle Befehle, die wir davor schon auf Tabellen angewendet haben wiederverwenden: ``` -> open people.txt | lines | split column "|" first_name last_name job | str trim | sort-by first_name -───┬────────────┬───────────┬────────── - # │ first_name │ last_name │ job -───┼────────────┼───────────┼────────── - 0 │ Antonio │ Vivaldi │ Composer - 1 │ Bob │ Ross │ Painter - 2 │ Octavia │ Butler │ Writer -───┴────────────┴───────────┴────────── +open people.txt | lines | split column "|" first_name last_name job | str trim | sort-by first_name +# => ───┬────────────┬───────────┬────────── +# => # │ first_name │ last_name │ job +# => ───┼────────────┼───────────┼────────── +# => 0 │ Antonio │ Vivaldi │ Composer +# => 1 │ Bob │ Ross │ Painter +# => 2 │ Octavia │ Butler │ Writer +# => ───┴────────────┴───────────┴────────── ``` Weitere Befehle, mit denen Texte aus Strings bearbeitet werden können sind: @@ -166,12 +166,12 @@ Es gibt ausserdem einige Hilfsbefehle, die verwendet werden können um mit Daten die Nu eigentlich verstehen sollte. Zum Beispiel wenn eine Rust lock Datei geöffnet wird: ``` -> open Cargo.lock -# This file is automatically @generated by Cargo. -# It is not intended for manual editing. -[[package]] -name = "adhoc_derive" -version = "0.1.2" +open Cargo.lock +# => # This file is automatically @generated by Cargo. +# => # It is not intended for manual editing. +# => [[package]] +# => name = "adhoc_derive" +# => version = "0.1.2" ``` Eine "Cargo.lock" Datei ist eigentlich eine .toml Datei, aber die Dateiendung ist nicht .toml. @@ -189,12 +189,13 @@ ist dies nicht immer gewünscht. Um den darunter liegenden Text zu erhalten, kan [`open`](/commands/docs/open.md) Befehl das Flag `--raw` mitgegeben werden: ``` -> open Cargo.toml --raw -[package] name = "nu" -version = "0.1.3" -authors = ["Yehuda Katz ", "Sophia Turner <547158+sophiajt@users.noreply.github.com>"] -description = "A shell for the GitHub era" -license = "MIT" +open Cargo.toml --raw +# => [package] +# => name = "nu" +# => version = "0.1.3" +# => authors = ["Yehuda Katz ", "Sophia Turner <547158+sophiajt@users.noreply.github.com>"] +# => description = "A shell for the GitHub era" +# => license = "MIT" ``` ## URLs abrufen diff --git a/de/book/metadata.md b/de/book/metadata.md index aa2a9ecbe9c..f2e582f9413 100644 --- a/de/book/metadata.md +++ b/de/book/metadata.md @@ -3,14 +3,14 @@ Bei der Verwendung von Nu ist es Ihnen vielleicht schon einmal passiert, dass Sie das Gefühl hatten, dass hinter den Kulissen noch etwas anderes vor sich geht. Nehmen wir zum Beispiel an, Sie versuchen, eine Datei zu öffnen, die Nu unterstützt, und vergessen es dann und versuchen erneut, sie zu konvertieren: ```nu -> open Cargo.toml | from toml -error: Expected a string from pipeline -- shell:1:18 -1 | open Cargo.toml | from toml - | ^^^^^^^^^ requires string input -- shell:1:5 -1 | open Cargo.toml | from toml - | ---------- object originates from here +open Cargo.toml | from toml +# => error: Expected a string from pipeline +# => - shell:1:18 +# => 1 | open Cargo.toml | from toml +# => | ^^^^^^^^^ requires string input +# => - shell:1:5 +# => 1 | open Cargo.toml | from toml +# => | ---------- object originates from here ``` Die Fehlermeldung sagt uns nicht nur, dass das, was wir [`from toml`](/commands/docs/from_toml.md) angegeben haben, keine Zeichenkette war, sondern auch, woher der Wert ursprünglich kam. Woher sollte es das wissen? @@ -20,20 +20,20 @@ Werte, die in Nu durch eine Pipeline fließen, sind oft mit einer Reihe von zus Führen wir den Befehl [`open`](/commands/docs/open.md) noch einmal aus, aber dieses Mal schauen wir uns die Tags an, die er zurückgibt: ```nu -> metadata (open Cargo.toml) -╭──────┬───────────────────╮ -│ span │ {record 2 fields} │ -╰──────┴───────────────────╯ +metadata (open Cargo.toml) +# => ╭──────┬───────────────────╮ +# => │ span │ {record 2 fields} │ +# => ╰──────┴───────────────────╯ ``` Derzeit verfolgen wir nur die Spanne, aus der die Werte stammen. Schauen wir uns das einmal genauer an: ```nu -> metadata (open Cargo.toml) | get span -╭───────┬────────╮ -│ start │ 212970 │ -│ end │ 212987 │ -╰───────┴────────╯ +metadata (open Cargo.toml) | get span +# => ╭───────┬────────╮ +# => │ start │ 212970 │ +# => │ end │ 212987 │ +# => ╰───────┴────────╯ ``` Die Bereiche "start" und "end" geben an, wo die Unterstreichung in der Zeile sein wird. Wenn Sie über 5 und dann bis 15 zählen, werden Sie sehen, dass die Zeile mit dem Dateinamen "Cargo.toml" übereinstimmt. So wusste der Fehler, den wir vorhin gesehen haben, was unterstrichen werden sollte. diff --git a/de/book/operators.md b/de/book/operators.md index db05c6b9f48..af2439c2b0a 100644 --- a/de/book/operators.md +++ b/de/book/operators.md @@ -56,8 +56,8 @@ Mathematische Operationen werden in der folgenden Reihenfolge ausgewertet (von d - Zuweisungs Operationen ``` -> 3 * (1 + 2) -9 +3 * (1 + 2) +# => 9 ``` ## Typen @@ -65,18 +65,18 @@ Mathematische Operationen werden in der folgenden Reihenfolge ausgewertet (von d Nicht alle Operationen ergeben für alle Datentypen Sinn. Wenn eine Operation auf einen nicht kompatiblen Datentyp angewendet werden soll, wird ein Fehler ausgegeben, der erklären soll, was falsch gelaufen ist: ``` -> "spam" - 1 -Error: nu::parser::unsupported_operation (link) - - × Types mismatched for operation. - ╭─[entry #49:1:1] - 1 │ "spam" - 1 - · ───┬── ┬ ┬ - · │ │ ╰── int - · │ ╰── doesn't support these values. - · ╰── string - ╰──── - help: Change string or int to be the right types and try again. +"spam" - 1 +# => Error: nu::parser::unsupported_operation (link) +# => +# => × Types mismatched for operation. +# => ╭─[entry #49:1:1] +# => 1 │ "spam" - 1 +# => · ───┬── ┬ ┬ +# => · │ │ ╰── int +# => · │ ╰── doesn't support these values. +# => · ╰── string +# => ╰──── +# => help: Change string or int to be the right types and try again. ``` Die Regeln fühlen sich oft strickt an. Auf der anderen Seite sollten sich jedoch weniger unerwünschte Nebeneffekte einschleichen. diff --git a/de/book/pipeline.md b/de/book/pipeline.md index 37690d06e41..cf861ebc638 100644 --- a/de/book/pipeline.md +++ b/de/book/pipeline.md @@ -8,7 +8,7 @@ So wie Nu die Arbeit mit Texten als dem Basis Datentyp in Unix erweitert, erweit Eine Pipeline besteht aus drei Teilen: Dem Input, dem Filter und dem Output. ``` -> open "Cargo.toml" | inc package.version --minor | save "Cargo_new.toml" +open "Cargo.toml" | inc package.version --minor | save "Cargo_new.toml" ``` Der erste Befehl, `open "Cargo.toml"`, ist der Input (manchmal auch als "source" oder "producer" bezeichnet). @@ -25,8 +25,8 @@ Andere Arten von Output geben die Daten aus der Pipeline zum Beispiel auf der Ko Die `$in` Variable sammelt die Daten in der Pipeline in einen Wert, um den ganzen Strom als Parameter verwenden zu können: ```nushell -> echo 1 2 3 | $in.1 * $in.2 -6 +echo 1 2 3 | $in.1 * $in.2 +# => 6 ``` ## Mehrzeilen Pipelines @@ -73,13 +73,13 @@ Der [`table`](/commands/docs/table.md) Befehl wird an jede Pipeline angefügt, d Dies erlaubt es den Output in dieser Form zu sehen. Tatsächlich ist der Befehl: ``` -> ls +ls ``` und die Pipeline, ``` -> ls +ls ``` ein und dasselbe. diff --git a/de/book/plugins.md b/de/book/plugins.md index ffeb32c2d1d..245a1bcaa37 100644 --- a/de/book/plugins.md +++ b/de/book/plugins.md @@ -7,11 +7,11 @@ Um ein Plugin hinzuzufügen, muss es erstellt werden und dann der Befehl `plugin Ein Beispiel: ``` -> plugin add ./my_plugins/nu-plugin-inc -e capnp +plugin add ./my_plugins/nu-plugin-inc -e capnp ``` Wenn der Befehl registriert wurde, kann er als Teil der internen Befehle verwendet werden. ``` -> inc --help +inc --help ``` diff --git a/de/book/scripts.md b/de/book/scripts.md index b6b4e47720e..764b97214ff 100644 --- a/de/book/scripts.md +++ b/de/book/scripts.md @@ -4,14 +4,14 @@ In Nushell können Skripte geschrieben und ausgeführt werden, welche in der Nus Um ein Skript auszuführen, wird es dem Befehl `nu` als Argument übergeben: ``` -> nu myscript.nu +nu myscript.nu ``` Dies wird das Skript bis zum Ende in einer neuen Nuinstanz ausführen. Das Skript kann auch in der _aktuellen_ Instanz ausgeführt werden mit dem [`source`](/commands/docs/source.md) Befehl: ``` -> source myscript.nu +source myscript.nu ``` Hier ein Beispiel einer Skript Datei: @@ -75,8 +75,8 @@ def main [x: int] { ``` ``` -> nu myscript.nu 100 -110 +nu myscript.nu 100 +# => 110 ``` ## Shebangs (`#!`) @@ -91,6 +91,6 @@ echo "Hello World!" ``` ``` -> ./myscript -Hello World! +./myscript +# => Hello World! ``` diff --git a/de/book/thinking_in_nushell.md b/de/book/thinking_in_nushell.md index 6a465ba9363..80b6efdab39 100644 --- a/de/book/thinking_in_nushell.md +++ b/de/book/thinking_in_nushell.md @@ -11,21 +11,21 @@ Nushell ist sowohl eine Programmiersprache, als auch eine Shell. Deswegen hat si Einiges ist jedoch so modelliert, wie es auch von anderen Shells her bekannt ist. Zum Beispiel Pipelines verbinden zwei Befehle: ``` -> ls | length +ls | length ``` Nushell hat auch andere Fähigkeiten, wie, aufnehmen des exit codes eines zuvor ausgeführten Befehls. Trotz dieser Vorzüge ist Nushell nicht Bash. In einer Bash, oder bei POSIX kompatiblen Shells ganz generell, verwendet man z.B.: ``` -> echo "hello" > output.txt +echo "hello" > output.txt ``` In Nushell is das `>` ein grösser-als Operator, was eher dem Programmiersprachen Aspekt von Nushell entspricht. Stattdessen wird eine Pipe zu einem Befehl geführt, der die Aufgabe des Speicherns übernimmt: ``` -> echo "hello" | save output.txt +echo "hello" | save output.txt ``` **Denken in Nushell:** In Nushell werden die Daten durch die Pipeline weitergereicht, bis sie den Benutzer oder einen abschliessenden Befehl erreichen. @@ -52,7 +52,7 @@ bevor sie ausgeführt werden kann, können die drei Zeilen nicht im voraus `komp Ein anderes Problem ist, einen Dateinamen dynamisch erzeugen zu wollen um ihn auszuführen: ``` -> source $"($my_path)/common.nu" +source $"($my_path)/common.nu" ``` Dies würde voraussetzen, dass Nushell die Eingabe auswerten kann um sie dann auszuführen, jedoch wird diese Information zur Kompilierzeit benötigt. @@ -88,14 +88,14 @@ Schleifenzähler sind ein anderes häufiges Muster für veränderliche Variablen Zum Beispiel kann sowohl jedes Element wie auch dessen Index mit dem `-n` Flag von [`each`](/commands/docs/each.md) erreicht werden: ``` -> ls | enumerate | each { |row| $"Number ($row.index) is size ($row.item.size)" } +ls | enumerate | each { |row| $"Number ($row.index) is size ($row.item.size)" } ``` Mit dem [`reduce`](/commands/docs/reduce.md) kann eine ähnliche Funktionalität erreicht werden wie man es von Variablen in Schleifen kennt. Zum Beispiel, wenn der längste Text in einer Liste von Texten gesucht wird: ``` -> [one, two, three, four, five, six] | reduce {|curr, max| +[one, two, three, four, five, six] | reduce {|curr, max| if ($curr | str length) > ($max | str length) { $curr } else { @@ -119,7 +119,7 @@ In der Praxis ist damit präziserer Code möglich, um zum Beispiel mit Unterverz erstellt werden soll: ``` -> ls | each { |elt| +ls | each { |elt| cd $elt.name make } diff --git a/de/book/types_of_data.md b/de/book/types_of_data.md index ed5c32d45cf..33e74f6db74 100644 --- a/de/book/types_of_data.md +++ b/de/book/types_of_data.md @@ -45,23 +45,23 @@ Einfache Anführungszeichen ergeben ebenfalls einen Text zurück. Der Unterschie Nushell unterstützt Text Erweiterung, was es erlaubt, Unterausdrücke innerhalb eines Textes zu verwenden. Diese werden mit `$` ausgedrückt: ``` -> echo $"6 x 7 = (6 * 7)" -6 x 7 = 42 +echo $"6 x 7 = (6 * 7)" +# => 6 x 7 = 42 ``` ``` -> ls | each { |row| echo $"($row.name) is ($row.size)" } -───┬───────────────────── - 0 │ genawait is 4.1 KB - 1 │ learncpp is 4.1 KB - 2 │ nuscripts is 4.1 KB -───┴───────────────────── +ls | each { |row| echo $"($row.name) is ($row.size)" } +# => ───┬───────────────────── +# => 0 │ genawait is 4.1 KB +# => 1 │ learncpp is 4.1 KB +# => 2 │ nuscripts is 4.1 KB +# => ───┴───────────────────── ``` **blosse Texte** ``` -> echo hello +echo hello ``` Eine spezielle Eigenschaft von Nushell ist, dass ein Text mit nur einem Wort auch ganz ohne Anführungszeichen erstellt werden kann. @@ -69,7 +69,7 @@ Eine spezielle Eigenschaft von Nushell ist, dass ein Text mit nur einem Wort auc Der Text oben ist das selbe als wäre geschrieben: ``` -> echo "hello" +echo "hello" ``` Siehe auch [Handling Strings](https://www.nushell.sh/book/loading_data.html#handling-strings). @@ -187,9 +187,9 @@ Binärdaten wie der Inhalt einer Bilddatei entspricht einer Gruppe von rohen (ra Binär kann explizit wörtlich geschrieben werden in einer der Formen `0x[...]`, `0b[...]`, or `0o[...]`: ``` -> 0x[1F FF] # Hexadecimal -> 0b[1 1010] # Binary -> 0o[377] # Octal +0x[1F FF] # Hexadecimal +0b[1 1010] # Binary +0o[377] # Octal ``` Nicht vollständige bytes werden links mit Nullen aufgefüllt (left-padded) @@ -207,23 +207,23 @@ Wertepaare werden auch als key-value pairs bezeichnet, ähnlich wie sie von JSON werden Wertepaar von oben unten anstatt links-rechts dargestellt: ``` -> echo {name: sam, rank: 10} -╭──────┬─────╮ -│ name │ sam │ -│ rank │ 10 │ -╰──────┴─────╯ +echo {name: sam, rank: 10} +# => ╭──────┬─────╮ +# => │ name │ sam │ +# => │ rank │ 10 │ +# => ╰──────┴─────╯ ``` Über Wertepaare kann iteriert werden wenn sie zuerst in eine Tabelle transponiert werden: ``` -> echo {name: sam, rank: 10} | transpose key value -╭───┬──────┬───────╮ -│ # │ key │ value │ -├───┼──────┼───────┤ -│ 0 │ name │ sam │ -│ 1 │ rank │ 10 │ -╰───┴──────┴───────╯ +echo {name: sam, rank: 10} | transpose key value +# => ╭───┬──────┬───────╮ +# => │ # │ key │ value │ +# => ├───┼──────┼───────┤ +# => │ 0 │ name │ sam │ +# => │ 1 │ rank │ 10 │ +# => ╰───┴──────┴───────╯ ``` ## Listen (lists) @@ -234,12 +234,12 @@ was man eine Tabelle (table) nennt. Beispiel: Eine Liste von Texten ``` -> echo [sam fred george] -───┬──────── - 0 │ sam - 1 │ fred - 2 │ george -───┴──────── +echo [sam fred george] +# => ───┬──────── +# => 0 │ sam +# => 1 │ fred +# => 2 │ george +# => ───┴──────── ``` ## Tabellen (tables) @@ -250,36 +250,36 @@ Eine Tabelle besteht immer aus Zeilen und Spalten. Eine Tabelle wird ähnlich erstellt wie eine Liste. Weil diese auch Spalten und nicht nur Werte enthält, geben wir die Spalten zuerst an: ``` -> echo [[column1, column2]; [Value1, Value2]] -───┬─────────┬───────── - # │ column1 │ column2 -───┼─────────┼───────── - 0 │ Value1 │ Value2 -───┴─────────┴───────── +echo [[column1, column2]; [Value1, Value2]] +# => ───┬─────────┬───────── +# => # │ column1 │ column2 +# => ───┼─────────┼───────── +# => 0 │ Value1 │ Value2 +# => ───┴─────────┴───────── ``` Eine Tabelle mit mehreren Zeilen sieht dann so aus: ``` -> echo [[column1, column2]; [Value1, Value2] [Value3, Value4]] -───┬─────────┬───────── - # │ column1 │ column2 -───┼─────────┼───────── - 0 │ Value1 │ Value2 - 1 │ Value3 │ Value4 -───┴─────────┴───────── +echo [[column1, column2]; [Value1, Value2] [Value3, Value4]] +# => ───┬─────────┬───────── +# => # │ column1 │ column2 +# => ───┼─────────┼───────── +# => 0 │ Value1 │ Value2 +# => 1 │ Value3 │ Value4 +# => ───┴─────────┴───────── ``` Oder aus einer Liste von Wertepaaren: ``` -> echo [{name: sam, rank: 10}, {name: bob, rank: 7}] -╭───┬──────┬──────╮ -│ # │ name │ rank │ -├───┼──────┼──────┤ -│ 0 │ sam │ 10 │ -│ 1 │ bob │ 7 │ -╰───┴──────┴──────╯ +echo [{name: sam, rank: 10}, {name: bob, rank: 7}] +# => ╭───┬──────┬──────╮ +# => │ # │ name │ rank │ +# => ├───┼──────┼──────┤ +# => │ 0 │ sam │ 10 │ +# => │ 1 │ bob │ 7 │ +# => ╰───┴──────┴──────╯ ``` ## Blöcke (blocks) diff --git a/de/book/variables_and_subexpressions.md b/de/book/variables_and_subexpressions.md index 9f60586f4e1..235e86b7962 100644 --- a/de/book/variables_and_subexpressions.md +++ b/de/book/variables_and_subexpressions.md @@ -9,9 +9,9 @@ Die einfachere Variante der auszuwertenden Ausdrücke ist die Variable. Während Wenn eine Variable erzeugt wurde, kann der Inhalt dieser Variable ausgegeben werden, indem `$` vor dem Variablennamen verwendet wird: ``` -> let my_value = 4 -> echo $my_value -4 +let my_value = 4 +echo $my_value +# => 4 ``` ## Pfade von Variablen @@ -19,14 +19,14 @@ Wenn eine Variable erzeugt wurde, kann der Inhalt dieser Variable ausgegeben wer Ein Pfad einer Variable funktioniert ähnlich wie ein strukturierter Datentyp. Es kann mittels Referenzen auf den Inhalt der Variable beziehungsweise die Spalten in der Variable zugegriffen werden, um final bei einem bestimmten Wert zu landen. Wenn beispielsweise anstatt der `4` im obigen Beispiel, der Variablen eine Tabelle zugewiesen wurde: ``` -> let my_value = [[name]; [testuser]] +let my_value = [[name]; [testuser]] ``` Hier kann ein Pfad der Variable `$my_value` verwendet werden, um den Wert der Spalte `name` in nur einem Schritt zu bekommen: ``` -> echo $my_value.name -testuser +echo $my_value.name +# => testuser ``` ## Unterausdrücke @@ -38,14 +38,14 @@ Die Klammern enthalten eine Pipeline, die bis zum Ende durchlaufen wird und dere Unterausdrücke können auch ganze Pipelines statt nur einzelner Befehle enthalten. Um eine Liste von Dateien mit einer Größe größer als 10 Kilobytes zu bekommen, kann die folgende Pipeline verwendet und einer Variable zugewiesen werden: ``` -> let names_of_big_files = (ls | where size > 10kb) -> echo $names_of_big_files -───┬────────────┬──────┬──────────┬────────────── - # │ name │ type │ size │ modified -───┼────────────┼──────┼──────────┼────────────── - 0 │ Cargo.lock │ File │ 155.3 KB │ 17 hours ago - 1 │ README.md │ File │ 15.9 KB │ 17 hours ago -───┴────────────┴──────┴──────────┴────────────── +let names_of_big_files = (ls | where size > 10kb) +echo $names_of_big_files +# => ───┬────────────┬──────┬──────────┬────────────── +# => # │ name │ type │ size │ modified +# => ───┼────────────┼──────┼──────────┼────────────── +# => 0 │ Cargo.lock │ File │ 155.3 KB │ 17 hours ago +# => 1 │ README.md │ File │ 15.9 KB │ 17 hours ago +# => ───┴────────────┴──────┴──────────┴────────────── ``` ## Unterausdrücke und Pfade @@ -53,13 +53,13 @@ Unterausdrücke können auch ganze Pipelines statt nur einzelner Befehle enthalt Unterausdrücke unterstützen auch Pfade. Um beispielsweise eine Liste der Dateinamen im aktuellen Ordner zu bekommen, kann diese Pipeline verwendet werden: ``` -> ls | get name +ls | get name ``` Dasselbe Ergebnis kann auch in nur einem Schritt erreicht werden, indem ein Unterausdruck mit Pfad verwendet wird: ``` -> echo (ls).name +echo (ls).name ``` Welcher Stil gewählt wird, hängt vom Anwendungsfall und den persönlichen Vorlieben ab. @@ -69,15 +69,15 @@ Welcher Stil gewählt wird, hängt vom Anwendungsfall und den persönlichen Vorl Nushell erlaubt den Zugriff auf Spalten in Tabellen in Unterausdrücken durch einfache Short-Hands. Wenn beispielsweise nur Zeilen in `ls` angezeigt werden sollen, in der die Größe der Datei größer als 10 Kilobytes ist, kann der folgende Befehl verwendet werden: ``` -> ls | where size > 10kb +ls | where size > 10kb ``` `where size > 10kb` ist ein Befehl mit zwei Teilen: Dem Befehlsnamen `where` und dem short-hand Ausdruck `size > 10kb`. Hier wird auch klar, warum das Ganze short-hand heißt: `size` ist hier die gekürzte Version von `$it.size`. Das Ganze könnte auch mit einer der folgenden ausführlicheren Varianten erreicht werden: ``` -> ls | where $it.size > 10kb -> ls | where ($it.size > 10kb) -> ls | where {|$it| $it.size > 10kb } +ls | where $it.size > 10kb +ls | where ($it.size > 10kb) +ls | where {|$it| $it.size > 10kb } ``` Damit diese short-hand Syntax funktioniert, muss der Name der Spalte auf der linken Seite der Operation sein (wie bei `size` in `size > 10kb`). diff --git a/de/book/working_with_lists.md b/de/book/working_with_lists.md index 29d26688ab2..8eae42e714f 100644 --- a/de/book/working_with_lists.md +++ b/de/book/working_with_lists.md @@ -13,15 +13,15 @@ Mit den zwei Befehlen `update` und `insert` können Listen in einer Pipeline ver zum Beispiel fügt folgende Zeile den Wert `10` in der Mitte, also an Stelle 2 ein. ```nu -> [1, 2, 3, 4] | insert 2 10 -# [1, 2, 10, 3, 4] +[1, 2, 3, 4] | insert 2 10 +# => [1, 2, 10, 3, 4] ``` Mit dem Befehl `update` ersetzen wir hingegen das 2. Element mit dem Wert `10`. ```nu -> [1, 2, 3, 4] | update 1 10 -# [1, 10, 3, 4] +[1, 2, 3, 4] | update 1 10 +# => [1, 10, 3, 4] ``` Zusätzlich zu `insert` und `update` stehen die Befehle `prepend` und `append` zu Verfügung. diff --git a/de/book/working_with_strings.md b/de/book/working_with_strings.md index a505688377c..0b383688446 100644 --- a/de/book/working_with_strings.md +++ b/de/book/working_with_strings.md @@ -11,8 +11,8 @@ Der einfachste Text in Nushell ist der in einfachen Anführungszeichen. Er wird mit dem `'` Zeichen umgeben. Hier der Text als Hallo Welt. ```nu -> 'Hallo Welt' -Hallo Welt +'Hallo Welt' +# => Hallo Welt ``` Text in einfachen Anführungszeichen belassen den Text wie er ist, @@ -30,9 +30,9 @@ Hallo gefolgt von einen `\n` um eine neue Linie zu erzeugen, dann Welt. Das ganze in doppelten Anführungszeichen. ```nu -> "Hallo\nWelt" -Hallo -Welt +"Hallo\nWelt" +# => Hallo +# => Welt ``` Escape Zeichen werden verwendet um Zeichen einzugeben, die ansonsten @@ -64,9 +64,9 @@ Soll zum Beispiel eine Person per Namen gegrüsst werden, deren Namen in einer V dann sieht das so aus: ```nu -> let name = "Alice" -> $"greetings, ($name)" -greetings, Alice +let name = "Alice" +$"greetings, ($name)" +# => greetings, Alice ``` Ein Ausdruck in `()` wird zuerst fertig ausgeführt. Das Ergebnis wird zur Bildung @@ -81,8 +81,8 @@ So können die Zeichen `(` und `)` in einem Text verwendet werden, ohne dass Nus auswerten will, was sich dazwischen befindet. ```nu -> $"2 + 2 is (2 + 2) \(you guessed it!)" -2 + 2 is 4 (you guessed it!) +$"2 + 2 is (2 + 2) \(you guessed it!)" +# => 2 + 2 is 4 (you guessed it!) ``` ## Texte aufsplitten @@ -108,8 +108,8 @@ Mit `help str` wirden alle Sub-Befehle ausgegeben. Zum Beispiel kann geprüft werden, ob sich ein Zeichen in einem Text befindet mit `str contains`: ```nu -> "Hallo Welt" | str contains "W" -true +"Hallo Welt" | str contains "W" +# => true ``` ### Texte schneiden @@ -119,8 +119,8 @@ geschnitten. Standardmässig schneidet der [`str trim`](/commands/docs/str_trim. Leerraum von beiden Seiten des Textes. Zum Beispiel: ```nu -> ' My string ' | str trim -My string +' My string ' | str trim +# => My string ``` Mit den Optionen `--right` und `--left` kann die Seite angegeben werden, @@ -130,8 +130,8 @@ Um ein spezifisches Zeichen weg zu schneiden, wird `--char ` verwende Hier ein Beispiel mit dieser Option: ```nu -> '=== Nu shell ===' | str trim -r -c '=' -=== Nu shell +'=== Nu shell ===' | str trim -r -c '=' +# => === Nu shell ``` ### Subtexte @@ -140,12 +140,12 @@ Subtexte sind Stücke von Texten. Sie haben einen Start- und einen Endpunkt. Hier ein Beispiel eines Substrings: ```nu -> 'Hallo Welt!' | str index-of 'o' -4 -> 'Hallo Welt!' | str index-of 'l' -8 -> 'Hallo Welt!' | str substring 4..8 -o We +'Hallo Welt!' | str index-of 'o' +# => 4 +'Hallo Welt!' | str index-of 'l' +# => 8 +'Hallo Welt!' | str substring 4..8 +# => o We ``` ### Texte ausrichten (padding) @@ -153,10 +153,10 @@ o We Verwende [`fill`](/commands/docs/fill.md): ```nu -> '1234' | fill -a right -c '0' -w 10 -0000001234 -> '1234' | fill -a left -c '0' -w 10 | str length -10 +'1234' | fill -a right -c '0' -w 10 +# => 0000001234 +'1234' | fill -a left -c '0' -w 10 | str length +# => 10 ``` ### Texte umkehren @@ -164,14 +164,14 @@ Verwende [`fill`](/commands/docs/fill.md): Dies kann mit dem [`str reverse`](/commands/docs/str_reverse.md) Befehl ganz einfach erreicht werden. ```nu -> 'Nushell' | str reverse -llehsuN -> ['Nushell' 'is' 'cool'] | str reverse -╭───┬─────────╮ -│ 0 │ llehsuN │ -│ 1 │ si │ -│ 2 │ looc │ -╰───┴─────────╯ +'Nushell' | str reverse +# => llehsuN +['Nushell' 'is' 'cool'] | str reverse +# => ╭───┬─────────╮ +# => │ 0 │ llehsuN │ +# => │ 1 │ si │ +# => │ 2 │ looc │ +# => ╰───┴─────────╯ ``` ## Texte parsen @@ -180,18 +180,18 @@ Mit dem [`parse`](/commands/docs/parse.md) Befehl können Texte in Spalten gepar Zum Beispiel: ```nu -> 'Nushell is the best' | parse '{shell} is {type}' -╭───┬─────────┬──────────╮ -│ # │ shell │ type │ -├───┼─────────┼──────────┤ -│ 0 │ Nushell │ the best │ -╰───┴─────────┴──────────╯ -> 'Bash is kinda cringe' | parse --regex '(?P\w+) is (?P[\w\s]+)' -╭───┬───────┬──────────────╮ -│ # │ shell │ type │ -├───┼───────┼──────────────┤ -│ 0 │ Bash │ kinda cringe │ -╰───┴───────┴──────────────╯ +'Nushell is the best' | parse '{shell} is {type}' +# => ╭───┬─────────┬──────────╮ +# => │ # │ shell │ type │ +# => ├───┼─────────┼──────────┤ +# => │ 0 │ Nushell │ the best │ +# => ╰───┴─────────┴──────────╯ +'Bash is kinda cringe' | parse --regex '(?P\w+) is (?P[\w\s]+)' +# => ╭───┬───────┬──────────────╮ +# => │ # │ shell │ type │ +# => ├───┼───────┼──────────────┤ +# => │ 0 │ Bash │ kinda cringe │ +# => ╰───┴───────┴──────────────╯ ``` ## Texte konvertieren diff --git a/de/book/working_with_tables.md b/de/book/working_with_tables.md index a02b970186f..8cd4b099817 100644 --- a/de/book/working_with_tables.md +++ b/de/book/working_with_tables.md @@ -6,18 +6,18 @@ um mit Tabelle auf einfache Art die Daten zu finden und zu filtern, die benötig Um zu starten, wird eine Tabelle benötigt wie diese: ``` -> ls -───┬───────────────┬──────┬─────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────────┼──────┼─────────┼──────────── - 0 │ files.rs │ File │ 4.6 KB │ 5 days ago - 1 │ lib.rs │ File │ 330 B │ 5 days ago - 2 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago - 3 │ parse.rs │ File │ 49.8 KB │ 1 day ago - 4 │ path.rs │ File │ 2.1 KB │ 5 days ago - 5 │ shapes.rs │ File │ 4.7 KB │ 5 days ago - 6 │ signature.rs │ File │ 1.2 KB │ 5 days ago -───┴───────────────┴──────┴─────────┴──────────── +ls +# => ───┬───────────────┬──────┬─────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────────┼──────┼─────────┼──────────── +# => 0 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 1 │ lib.rs │ File │ 330 B │ 5 days ago +# => 2 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago +# => 3 │ parse.rs │ File │ 49.8 KB │ 1 day ago +# => 4 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 5 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => 6 │ signature.rs │ File │ 1.2 KB │ 5 days ago +# => ───┴───────────────┴──────┴─────────┴──────────── ``` ## Daten sortieren @@ -26,18 +26,18 @@ Um eine Tabelle zu sortieren, wird der [`sort-by`](/commands/docs/sort-by.md) Be Hier wird sortiert nach der Grösse der Dateien: ``` -> ls | sort-by size -───┬───────────────┬──────┬─────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────────┼──────┼─────────┼──────────── - 0 │ lib.rs │ File │ 330 B │ 5 days ago - 1 │ signature.rs │ File │ 1.2 KB │ 5 days ago - 2 │ path.rs │ File │ 2.1 KB │ 5 days ago - 3 │ files.rs │ File │ 4.6 KB │ 5 days ago - 4 │ shapes.rs │ File │ 4.7 KB │ 5 days ago - 5 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago - 6 │ parse.rs │ File │ 49.8 KB │ 1 day ago -───┴───────────────┴──────┴─────────┴──────────── +ls | sort-by size +# => ───┬───────────────┬──────┬─────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────────┼──────┼─────────┼──────────── +# => 0 │ lib.rs │ File │ 330 B │ 5 days ago +# => 1 │ signature.rs │ File │ 1.2 KB │ 5 days ago +# => 2 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 3 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 4 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => 5 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago +# => 6 │ parse.rs │ File │ 49.8 KB │ 1 day ago +# => ───┴───────────────┴──────┴─────────┴──────────── ``` Es kann nach allen Spalten sortiert werden, die einen Vergleich erlauben. @@ -49,34 +49,34 @@ Von einer Tabelle können einzelne Spalten und Zeilen ausgewählt werden. Mit dem [`select`](/commands/docs/select.md) Befehl werden hier einige Spalten gewählt. ``` -> ls | select name size -───┬───────────────┬───────── - # │ name │ size -───┼───────────────┼───────── - 0 │ files.rs │ 4.6 KB - 1 │ lib.rs │ 330 B - 2 │ lite_parse.rs │ 6.3 KB - 3 │ parse.rs │ 49.8 KB - 4 │ path.rs │ 2.1 KB - 5 │ shapes.rs │ 4.7 KB - 6 │ signature.rs │ 1.2 KB -───┴───────────────┴───────── +ls | select name size +# => ───┬───────────────┬───────── +# => # │ name │ size +# => ───┼───────────────┼───────── +# => 0 │ files.rs │ 4.6 KB +# => 1 │ lib.rs │ 330 B +# => 2 │ lite_parse.rs │ 6.3 KB +# => 3 │ parse.rs │ 49.8 KB +# => 4 │ path.rs │ 2.1 KB +# => 5 │ shapes.rs │ 4.7 KB +# => 6 │ signature.rs │ 1.2 KB +# => ───┴───────────────┴───────── ``` Damit wird eine Tabelle kreiert, die sich auf das Wesentliche beschränkt. Als nächstes sollen nur die 5 kleinsten Dateien aus diesem Verzeichnis enthalten sein: ``` -> ls | sort-by size | first 5 -───┬──────────────┬──────┬────────┬──────────── - # │ name │ type │ size │ modified -───┼──────────────┼──────┼────────┼──────────── - 0 │ lib.rs │ File │ 330 B │ 5 days ago - 1 │ signature.rs │ File │ 1.2 KB │ 5 days ago - 2 │ path.rs │ File │ 2.1 KB │ 5 days ago - 3 │ files.rs │ File │ 4.6 KB │ 5 days ago - 4 │ shapes.rs │ File │ 4.7 KB │ 5 days ago -───┴──────────────┴──────┴────────┴──────────── +ls | sort-by size | first 5 +# => ───┬──────────────┬──────┬────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼──────────────┼──────┼────────┼──────────── +# => 0 │ lib.rs │ File │ 330 B │ 5 days ago +# => 1 │ signature.rs │ File │ 1.2 KB │ 5 days ago +# => 2 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 3 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 4 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => ───┴──────────────┴──────┴────────┴──────────── ``` Zuerst wird die Tabelle nach grösse sortiert, um die kleinsten Dateien zuoberst zu erhalten, danach werden mit `first 5` die ersten 5 Zeilen ausgegeben. @@ -84,14 +84,14 @@ Zuerst wird die Tabelle nach grösse sortiert, um die kleinsten Dateien zuoberst Mit `skip` können ebenfalls Zeilen entfernt werden, die unerwünscht sind. Hier die ersten 2 der 5 aus dem obigen Beispiel: ``` -> ls | sort-by size | first 5 | skip 2 -───┬───────────┬──────┬────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────┼──────┼────────┼──────────── - 0 │ path.rs │ File │ 2.1 KB │ 5 days ago - 1 │ files.rs │ File │ 4.6 KB │ 5 days ago - 2 │ shapes.rs │ File │ 4.7 KB │ 5 days ago -───┴───────────┴──────┴────────┴──────────── +ls | sort-by size | first 5 | skip 2 +# => ───┬───────────┬──────┬────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────┼──────┼────────┼──────────── +# => 0 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 1 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 2 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => ───┴───────────┴──────┴────────┴──────────── ``` So konnten die 3 Zeilen extrahiert werden, die uns interessieren. @@ -100,25 +100,25 @@ In allen Tabellen sind die Zeilen nummeriert. Dies ermöglicht eine einfache Art Im folgenden wird zuerst nach dem Namen sortiert, und dann die 5. Zeile mit dem `select` Befehl über die Zeilennummer ausgewählt: ``` -> ls | sort-by name -───┬───────────────┬──────┬─────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────────┼──────┼─────────┼──────────── - 0 │ files.rs │ File │ 4.6 KB │ 5 days ago - 1 │ lib.rs │ File │ 330 B │ 5 days ago - 2 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago - 3 │ parse.rs │ File │ 49.8 KB │ 1 day ago - 4 │ path.rs │ File │ 2.1 KB │ 5 days ago - 5 │ shapes.rs │ File │ 4.7 KB │ 5 days ago - 6 │ signature.rs │ File │ 1.2 KB │ 5 days ago -───┴───────────────┴──────┴─────────┴──────────── +ls | sort-by name +# => ───┬───────────────┬──────┬─────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────────┼──────┼─────────┼──────────── +# => 0 │ files.rs │ File │ 4.6 KB │ 5 days ago +# => 1 │ lib.rs │ File │ 330 B │ 5 days ago +# => 2 │ lite_parse.rs │ File │ 6.3 KB │ 5 days ago +# => 3 │ parse.rs │ File │ 49.8 KB │ 1 day ago +# => 4 │ path.rs │ File │ 2.1 KB │ 5 days ago +# => 5 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => 6 │ signature.rs │ File │ 1.2 KB │ 5 days ago +# => ───┴───────────────┴──────┴─────────┴──────────── -> ls | sort-by name | select 5 -───┬───────────────┬──────┬─────────┬──────────── - # │ name │ type │ size │ modified -───┼───────────────┼──────┼─────────┼──────────── - 0 │ shapes.rs │ File │ 4.7 KB │ 5 days ago -───┴───────────────┴──────┴─────────┴──────────── +ls | sort-by name | select 5 +# => ───┬───────────────┬──────┬─────────┬──────────── +# => # │ name │ type │ size │ modified +# => ───┼───────────────┼──────┼─────────┼──────────── +# => 0 │ shapes.rs │ File │ 4.7 KB │ 5 days ago +# => ───┴───────────────┴──────┴─────────┴──────────── ``` ## Daten aus der Tabelle herausziehen @@ -128,16 +128,16 @@ Im nächsten Schritt soll angeschaut werden, wie wir den Inhalt anstelle der Tab Zum Beispiel wenn eine Liste der Namen aller Dateien erstellt werden soll. Dafür steht der [`get`](/commands/docs/get.md) Befehl bereit: ``` -> ls | get name -───┬─────────────── - 0 │ files.rs - 1 │ lib.rs - 2 │ lite_parse.rs - 3 │ parse.rs - 4 │ path.rs - 5 │ shapes.rs - 6 │ signature.rs -───┴─────────────── +ls | get name +# => ───┬─────────────── +# => 0 │ files.rs +# => 1 │ lib.rs +# => 2 │ lite_parse.rs +# => 3 │ parse.rs +# => 4 │ path.rs +# => 5 │ shapes.rs +# => 6 │ signature.rs +# => ───┴─────────────── ``` Damit erhalten wir die Werte aller Dateinamen als Liste. @@ -145,18 +145,18 @@ Damit erhalten wir die Werte aller Dateinamen als Liste. Dies sieht fast so aus, wie der [`select`](/commands/docs/select.md) Befehl weiter oben, deshalb hier die beiden nebeneinander: ``` -> ls | select name -───┬─────────────── - # │ name -───┼─────────────── - 0 │ files.rs - 1 │ lib.rs - 2 │ lite_parse.rs - 3 │ parse.rs - 4 │ path.rs - 5 │ shapes.rs - 6 │ signature.rs -───┴─────────────── +ls | select name +# => ───┬─────────────── +# => # │ name +# => ───┼─────────────── +# => 0 │ files.rs +# => 1 │ lib.rs +# => 2 │ lite_parse.rs +# => 3 │ parse.rs +# => 4 │ path.rs +# => 5 │ shapes.rs +# => 6 │ signature.rs +# => ───┴─────────────── ``` Diese sehen wirklich sehr ähnlich aus! Was also ist der Unterschied: @@ -179,15 +179,15 @@ In Nu wird dadurch nicht die Tabelle direkt geändert, sondern jeder Befehl gene Mit [`append`](/commands/docs/append.md) können Spalten gleichen Namens zusammengeführt werden: ``` -> let $first = [[a b]; [1 2]] -> let $second = [[a b]; [3 4]] -> $first | append $second -───┬───┬─── - # │ a │ b -───┼───┼─── - 0 │ 1 │ 2 - 1 │ 3 │ 4 -───┴───┴─── +let $first = [[a b]; [1 2]] +let $second = [[a b]; [3 4]] +$first | append $second +# => ───┬───┬─── +# => # │ a │ b +# => ───┼───┼─── +# => 0 │ 1 │ 2 +# => 1 │ 3 │ 4 +# => ───┴───┴─── ``` ### Tabellen mergen @@ -195,42 +195,42 @@ Mit [`append`](/commands/docs/append.md) können Spalten gleichen Namens zusamme Mit dem [`merge`](/commands/docs/merge.md) Befehl werden zwei oder mehr Tabellen zusammengeführt. ``` -> let $first = [[a b]; [1 2]] -> let $second = [[c d]; [3 4]] -> $first | merge { $second } -───┬───┬───┬───┬─── - # │ a │ b │ c │ d -───┼───┼───┼───┼─── - 0 │ 1 │ 2 │ 3 │ 4 -───┴───┴───┴───┴─── +let $first = [[a b]; [1 2]] +let $second = [[c d]; [3 4]] +$first | merge { $second } +# => ───┬───┬───┬───┬─── +# => # │ a │ b │ c │ d +# => ───┼───┼───┼───┼─── +# => 0 │ 1 │ 2 │ 3 │ 4 +# => ───┴───┴───┴───┴─── ``` Wird eine dritte Tabelle generiert: ``` -> let $third = [[e f]; [5 6]] +let $third = [[e f]; [5 6]] ``` Können nun alle drei Tabellen zusammengeführt werden wie hier: ``` -> $first | merge { $second } | merge { $third } -───┬───┬───┬───┬───┬───┬─── - # │ a │ b │ c │ d │ e │ f -───┼───┼───┼───┼───┼───┼─── - 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 -───┴───┴───┴───┴───┴───┴─── +$first | merge { $second } | merge { $third } +# => ───┬───┬───┬───┬───┬───┬─── +# => # │ a │ b │ c │ d │ e │ f +# => ───┼───┼───┼───┼───┼───┼─── +# => 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 +# => ───┴───┴───┴───┴───┴───┴─── ``` Oder mit dem [`reduce`](/commands/docs/reduce.md) Befehl alle dynamisch gemerged: ``` -> [$first $second $third] | reduce {|elt, acc| $acc|merge { $elt }} -───┬───┬───┬───┬───┬───┬─── - # │ a │ b │ c │ d │ e │ f -───┼───┼───┼───┼───┼───┼─── - 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 -───┴───┴───┴───┴───┴───┴─── +[$first $second $third] | reduce {|elt, acc| $acc|merge { $elt }} +# => ───┬───┬───┬───┬───┬───┬─── +# => # │ a │ b │ c │ d │ e │ f +# => ───┼───┼───┼───┼───┼───┼─── +# => 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 +# => ───┴───┴───┴───┴───┴───┴─── ``` ### Eine Spalte hinzufügen @@ -239,29 +239,29 @@ Mit dem [`insert`](/commands/docs/insert.md) Befehl wird eine neue Spalte hinzug Wie zum Beispiel: ``` -> open rustfmt.toml -─────────┬────── - edition │ 2018 -─────────┴────── +open rustfmt.toml +# => ─────────┬────── +# => edition │ 2018 +# => ─────────┴────── ``` wird eine Spalte namens "next_edition" mit dem Wert 2021 hinzugefügt: ``` -> open rustfmt.toml | insert next_edition 2021 -──────────────┬────── - edition │ 2018 - next_edition │ 2021 -──────────────┴────── +open rustfmt.toml | insert next_edition 2021 +# => ──────────────┬────── +# => edition │ 2018 +# => next_edition │ 2021 +# => ──────────────┴────── ``` Öffnen wir die originale Datei erneut, bleibt der Inhalt der alte: ``` -> open rustfmt.toml -─────────┬────── - edition │ 2018 -─────────┴────── +open rustfmt.toml +# => ─────────┬────── +# => edition │ 2018 +# => ─────────┴────── ``` Änderungen in Nu sind funktionale Änderungen, was bedeutet, dass Werte geändert werden, ohne permanente Änderungen zu bewirken. @@ -269,12 +269,12 @@ Es ist deshalb möglich, mehrere Änderungen in der Pipeline vorzunehmen, bevor Zum Sichern können wir, wie in diesem Beispiel, den [`save`](/commands/docs/save.md) Befehl verwenden: ``` -> open rustfmt.toml | insert next_edition 2021 | save rustfmt2.toml -> open rustfmt2.toml -──────────────┬────── - edition │ 2018 - next_edition │ 2021 -──────────────┴────── +open rustfmt.toml | insert next_edition 2021 | save rustfmt2.toml +open rustfmt2.toml +# => ──────────────┬────── +# => edition │ 2018 +# => next_edition │ 2021 +# => ──────────────┴────── ``` ### Eine Spalte updaten @@ -283,19 +283,19 @@ Zum Sichern können wir, wie in diesem Beispiel, den [`save`](/commands/docs/sav Auf die selbe Datei angewendet, sieht das so aus: ``` -> open rustfmt.toml -─────────┬────── - edition │ 2018 -─────────┴────── +open rustfmt.toml +# => ─────────┬────── +# => edition │ 2018 +# => ─────────┴────── ``` Und nun das Update auf die nächste Edition, die unterstützt werden soll: ``` -> open rustfmt.toml | update edition 2021 -─────────┬────── - edition │ 2021 -─────────┴────── +open rustfmt.toml | update edition 2021 +# => ─────────┬────── +# => edition │ 2021 +# => ─────────┴────── ``` Mit dem [`upsert`](/commands/docs/upsert.md) Befehl wird der Wert enweder eingefügt oder updatet abhängig davon, ob er bereits existriet. @@ -306,16 +306,16 @@ Mit [`move`](/commands/docs/move.md) werden Spalten in de Tabelle verschoben. Um erschienen zu lassen, schreibt man: ``` -> ls | move name --after size -╭────┬──────┬─────────┬───────────────────┬──────────────╮ -│ # │ type │ size │ name │ modified │ -├────┼──────┼─────────┼───────────────────┼──────────────┤ -│ 0 │ dir │ 256 B │ Applications │ 3 days ago │ -│ 1 │ dir │ 256 B │ Data │ 2 weeks ago │ -│ 2 │ dir │ 448 B │ Desktop │ 2 hours ago │ -│ 3 │ dir │ 192 B │ Disks │ a week ago │ -│ 4 │ dir │ 416 B │ Documents │ 4 days ago │ -... +ls | move name --after size +# => ╭────┬──────┬─────────┬───────────────────┬──────────────╮ +# => │ # │ type │ size │ name │ modified │ +# => ├────┼──────┼─────────┼───────────────────┼──────────────┤ +# => │ 0 │ dir │ 256 B │ Applications │ 3 days ago │ +# => │ 1 │ dir │ 256 B │ Data │ 2 weeks ago │ +# => │ 2 │ dir │ 448 B │ Desktop │ 2 hours ago │ +# => │ 3 │ dir │ 192 B │ Disks │ a week ago │ +# => │ 4 │ dir │ 416 B │ Documents │ 4 days ago │ +# => ... ``` ### Spalten umbenennen @@ -324,14 +324,14 @@ Um Spalten einen neuen Name zu geben, wird der Befehl [`rename`](/commands/docs/ Wie zum Beispiel hier nach der Verwendung von `ls`. ``` -> ls | rename filename filetype filesize date -╭────┬───────────────────┬──────────┬──────────┬──────────────╮ -│ # │ filename │ filetype │ filesize │ date │ -├────┼───────────────────┼──────────┼──────────┼──────────────┤ -│ 0 │ Applications │ dir │ 256 B │ 3 days ago │ -│ 1 │ Data │ dir │ 256 B │ 2 weeks ago │ -│ 2 │ Desktop │ dir │ 448 B │ 2 hours ago │ -│ 3 │ Disks │ dir │ 192 B │ a week ago │ -│ 4 │ Documents │ dir │ 416 B │ 4 days ago │ +ls | rename filename filetype filesize date +# => ╭────┬───────────────────┬──────────┬──────────┬──────────────╮ +# => │ # │ filename │ filetype │ filesize │ date │ +# => ├────┼───────────────────┼──────────┼──────────┼──────────────┤ +# => │ 0 │ Applications │ dir │ 256 B │ 3 days ago │ +# => │ 1 │ Data │ dir │ 256 B │ 2 weeks ago │ +# => │ 2 │ Desktop │ dir │ 448 B │ 2 hours ago │ +# => │ 3 │ Disks │ dir │ 192 B │ a week ago │ +# => │ 4 │ Documents │ dir │ 416 B │ 4 days ago │ ... ``` diff --git a/lang-guide/chapters/types/basic_types/range.md b/lang-guide/chapters/types/basic_types/range.md index 8c3c79d57ef..e141a4f8a86 100644 --- a/lang-guide/chapters/types/basic_types/range.md +++ b/lang-guide/chapters/types/basic_types/range.md @@ -115,7 +115,7 @@ ╰───┴───╯ ``` -1. Conversion - A ranges may be converted to a `list` using: +1. Conversion - A range may be converted to a `list` using: ```nu 1..5 | each {||}