mirror of
https://github.com/nushell/nushell.git
synced 2025-07-09 10:57:54 +02:00
0b202d55f0
<!-- if this PR closes one or more issues, you can automatically link the PR with them by using one of the [*linking keywords*](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword), e.g. - this PR should close #xxxx - fixes #xxxx you can also mention related issues, PRs or discussions! --> # Description <!-- Thank you for improving Nushell. Please, check our [contributing guide](../CONTRIBUTING.md) and talk to the core team before making major changes. Description of your pull request goes here. **Provide examples and/or screenshots** if your changes affect the user experience. --> This PR adds the `only` command to `std-rfc/iter`, which is a command I wrote a while ago that I've found so useful that I think it could have a place in the standard library. It acts similarly to `get 0`, but ensures that the value actually exists, and there aren't additional values. I find this most useful when chained with `where`, when you want to be certain that no additional elements are accidentally selected when you only mean to get a single element. I'll copy the help page here for additional explanation: > Get the only element of a list or table, ensuring it exists and there are no extra elements. > > Similar to `first` with no arguments, but errors if there are no additional > items when there should only be one item. This can help avoid issues when more > than one row than expected matches some criteria. > > This command is useful when chained with `where` to ensure that only one row > meets the given condition. > > If a cell path is provided as an argument, it will be accessed after the first > element. For example, `only foo` is roughly equivalent to `get 0.foo`, with > the guarantee that there are no additional elements. > > Note that this command currently collects streams. > Examples: > > Get the only item in a list, ensuring it exists and there's no additional items > ```nushell > [5] | only > # => 5 > ``` > > Get the `name` column of the only row in a table > ```nushell > [{name: foo, id: 5}] | only name > # => foo > ``` > > Get the modification time of the file named foo.txt > ```nushell > ls | where name == "foo.txt" | only modified > ``` Here's some additional examples showing the errors:   Most of the time I chain this with a simple `where`, but here's a couple other real world examples of how I've used this: [With `parse`, which outputs a table](https://git.ikl.sh/132ikl/dotfiles/src/branch/main/.scripts/manage-nu#L53): ```nushell let commit = $selection | parse "{start}.g{commit}-{end}" | only commit ``` [Ensuring that only one row in a table has a name that ends with a certain suffix](https://git.ikl.sh/132ikl/dotfiles/src/branch/main/.scripts/btconnect): ```nushell $devices | where ($chosen_name ends-with $it.name) | only ``` Unfortunately to get these nice errors I had to collect the stream (and I think the errors are more useful for this). This should be to be mitigated with (something like) #16014. Putting this in `std/iter` might be pushing it, but it seems *just* close enough that I can't really justify putting it in a different/new module. # User-Facing Changes <!-- List of all changes that impact the user experience here. This helps us keep track of breaking changes. --> * Adds the `only` command to `std-rfc/iter`, which can be used to ensure that a table or list only has a single element. # Tests + Formatting <!-- Don't forget to add tests that cover your changes. Make sure you've run and fixed any issues with these commands: - `cargo fmt --all -- --check` to check standard code formatting (`cargo fmt --all` applies these changes) - `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used` to check that you're using the standard code style - `cargo test --workspace` to check that all tests pass (on Windows make sure to [enable developer mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging)) - `cargo run -- -c "use toolkit.nu; toolkit test stdlib"` to run the tests for the standard library > **Note** > from `nushell` you can also use the `toolkit` as follows > ```bash > use toolkit.nu # or use an `env_change` hook to activate it automatically > toolkit check pr > ``` --> Added a few tests for `only` including error cases # After Submitting <!-- If your PR had any user-facing changes, update [the documentation](https://github.com/nushell/nushell.github.io) after the PR is merged, if necessary. This will help us keep the docs up to date. --> N/A --------- Co-authored-by: Bahex <Bahex@users.noreply.github.com>