Add an -Until script block parameter to Select-Object

[MatejKafka]

Summary of the new feature / enhancement

As a user, I want to stop processing input after encountering a specific value in the pipeline.

A simple example:

$NumbersUnder50 = 0..1000 | select -Until {$_ -eq 50} # stop after reaching 50

A more realistic example:

# list GitHub releases until a specific version
# with -FollowRelLink, this may result in saving a lot of HTTP requests under the hood, since otherwise all releases are listed
Invoke-RestMethod -FollowRelLink "https://api.github.com/repos/PowerShell/PowerShell/releases" `
    | % {$_} | select -Until {$_.tag_name -eq "v7.2.0"}

Since StopUpstreamCommandsException , which is internally used by Select-Object to implement its early-exit behavior is internal, I don't believe there's currently any way to implement this without reflecting PowerShell internals. Using something like ... | % {if (...) {break}; $_} may seem like an attractive option, but as documented, it terminates much more (the whole runspace) than a user would naively expect.

A more general solution could be to make StopUpstreamCommandsException public, so that users can write their own cmdlets with support for early exit, which is one of the possible solutions for #3821. However, even if that gets implemented, I believe the -Until parameter could still be valuable for simpler use cases.

Proposed technical implementation details (optional)

Add an -Until script block parameter to Select-Object, probably in a new parameter set, run the passed script block for each pipeline item and throw StopUpstreamCommandsException when the script block returns a truthy value.

I can open a PR if the feature is accepted. (although I'd kinda appreciate if someone found time to review my other PRs first, nudge nudge wink wink :) )

[SteveL-MSFT]

I wonder if it would be more generally useful to have a Stop-Pipeline cmdlet that emits the internal exception?

[MatejKafka]

@SteveL-MSFT It would definitely be more generally useful. However, there's already an open issue for that, and there doesn't seem to be will or time to design and implement that feature, and this might be a stepping stone that's easier to decide on and implement, and should be a useful addition on its own.

As an aside, I'd preferably make the exception public instead of creating a Stop-Pipeline cmdlet, so that it can be easily invoked from compiled cmdlets, not just from scripts.

[SteveL-MSFT]

@MatejKafka can you link to the other issue on this? I've queued this up for the WG-Cmdlets to discuss so a conclusion will be made

[mklement0]

@SteveL-MSFT, said issue is already linked to from the initial post:

• Allow user code to stop a pipeline on demand / to terminate upstream cmdlets. #3821.