Create a When system param wrapper for skipping systems that fail validation

[chescock]

Objective

Create a When system param wrapper for skipping systems that fail validation.

Currently, the Single and Populated parameters cause systems to skip when they fail validation, while the Res family causes systems to error. Generalize this so that any fallible parameter can be used either to skip a system or to raise an error. A parameter used directly will always raise an error, and a parameter wrapped in When<P> will always cause the system to be silently skipped.

Note that this changes the behavior for Single and Populated. The current behavior will be available using When<Single> and When<Populated>.

Fixes #18516

Solution

Create a When system param wrapper that wraps an inner parameter and converts all validation errors to skipped.

Change the behavior of Single and Populated to fail by default.

Replace in-engine use of Single with When<Single>. I updated the fallible_systems example, but not all of the others. The other examples I looked at appeared to always have one matching entity, and it seemed more clear to use the simpler type in those cases.

[alice-i-cecile]

Change the behavior of Single and Populated to fail by default.

I really don't think we should do this, and would prefer to spin this out into a separate PR. These are useful, terse helpers for a common pattern and I would really like to stop changing their semantics in breaking ways.

[chescock]

I really don't think we should do this, and would prefer to spin this out into a separate PR. These are useful, terse helpers for a common pattern and I would really like to stop changing their semantics in breaking ways.

Sure, I'll remove that from this PR.

I do still think it's worth doing, though! The panicking version of Single is valuable for the same reason panicking Res is: to encode invariants that should always be true. I expect things like Single<D, With<Player>> to be especially common. And having a simple and consistent story for when systems panic vs skip is valuable, so that users only have to learn one thing, and it works for both Single and Res (and everything else).

But I will feel really bad for all the folks trying to use Single for skipping if we pull the run out from under them again :).

[chescock]

And having a simple and consistent story for when systems panic vs skip is valuable, so that users only have to learn one thing, and it works for both Single and Res (and everything else).

... the other way to get consistency is to make Res skip by default, and have a wrapper type to convert skips to panics, like Assert<Res<R>>. I'm not sure whether that would be more or less controversial :).

[alice-i-cecile]

But I will feel really bad for all the folks trying to use Single for skipping if we pull the run out from under them again :).

Mhmm :) This is too late in the 0.16 cycle for this to land, so I'm reluctant to change the behavior yet again.

Thanks for splitting it out though; this is a much simpler and uncontroversial helper on its own.

[bushrat011899]

Love it, just a suggestion for documentation. Not blocking at all.