Document DeferredCommand and onlyIf/onlyWhile decorators #3130
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds comprehensive documentation for: - DeferredCommand and defer() factory for schedule-time command construction - onlyIf() decorator for conditional command execution - onlyWhile() decorator for commands that interrupt when condition becomes false Includes examples in Java, C++, and Python for all three decorators. Fixes wpilibsuite#2368 Fixes wpilibsuite#2252
katzuv
reviewed
Oct 11, 2025
|
|
||
| ```java | ||
| // Command will only run if the game piece is present | ||
| button.onTrue(command.onlyIf(() -> intake.hasGamePiece())); |
There was a problem hiding this comment.
Suggested change
| button.onTrue(command.onlyIf(() -> intake.hasGamePiece())); | |
| button.onTrue(command.onlyIf(intake::hasGamePiece)); |
|
|
||
| ```python | ||
| # Command will only run if the game piece is present | ||
| button.onTrue(command.onlyIf(lambda: intake.hasGamePiece())) |
There was a problem hiding this comment.
Suggested change
| button.onTrue(command.onlyIf(lambda: intake.hasGamePiece())) | |
| button.onTrue(command.onlyIf(intake.hasGamePiece)) |
@virtuald Is this suggested style for robotpy users?
There was a problem hiding this comment.
It looks like there's several more locations that need similar updates
Comment on lines
+270
to
+292
| ```java | ||
| // Selects one of two commands based on current sensor state when scheduled | ||
| Commands.defer( | ||
| () -> sensor.get() ? Commands.print("Sensor true") : Commands.print("Sensor false"), | ||
| Set.of() | ||
| ) | ||
| ``` | ||
|
|
||
| ```c++ | ||
| // Selects one of two commands based on current sensor state when scheduled | ||
| frc2::cmd::Defer( | ||
| [&sensor] { return sensor.Get() ? frc2::cmd::Print("Sensor true") : frc2::cmd::Print("Sensor false"); }, | ||
| {} | ||
| ) | ||
| ``` | ||
|
|
||
| ```python | ||
| # Selects one of two commands based on current sensor state when scheduled | ||
| commands2.cmd.defer( | ||
| lambda: commands2.cmd.print_("Sensor true") if sensor.get() else commands2.cmd.print_("Sensor false"), | ||
| [] | ||
| ) | ||
| ``` |
There was a problem hiding this comment.
In that case, I think you'd use ConditionalCommand, which also evaluates the predicate at runtime.
| button.onTrue(command.unless(lambda: not intake.isDeployed())) | ||
| ``` | ||
|
|
||
| The ``onlyIf()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyIf(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a73b3bb7908543e6ded5901adb0667c6d), :external:py:meth:`Python <commands2.Command.onlyIf>`) is similar to ``unless()`` but with inverted logic - the command will only run if the condition is true. |
There was a problem hiding this comment.
Suggested change
| The ``onlyIf()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyIf(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a73b3bb7908543e6ded5901adb0667c6d), :external:py:meth:`Python <commands2.Command.onlyIf>`) is similar to ``unless()`` but with inverted logic - the command will only run if the condition is true. | |
| The ``onlyIf()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyIf(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a0c1b9e9e7cedd134145ee3d808bd92d2), :external:py:meth:`Python <commands2.Command.onlyIf>`) is similar to ``unless()`` but with inverted logic - the command will only run if the condition is true. |
| button.onTrue(command.onlyIf(lambda: intake.hasGamePiece())) | ||
| ``` | ||
|
|
||
| The ``onlyWhile()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyWhile(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a0ef33b5e59bf0f0b42010c8d6bec4d00), :external:py:meth:`Python <commands2.Command.onlyWhile>`) composes a command with a condition that is continuously checked during execution. If the condition becomes false while the command is running, the command will be interrupted. This is backed by a ``ParallelRaceGroup`` with a ``WaitUntilCommand``. |
There was a problem hiding this comment.
Suggested change
| The ``onlyWhile()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyWhile(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a0ef33b5e59bf0f0b42010c8d6bec4d00), :external:py:meth:`Python <commands2.Command.onlyWhile>`) composes a command with a condition that is continuously checked during execution. If the condition becomes false while the command is running, the command will be interrupted. This is backed by a ``ParallelRaceGroup`` with a ``WaitUntilCommand``. | |
| The ``onlyWhile()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyWhile(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#ab4917ac5eb58bd08eb2412070d29ba1c), :external:py:meth:`Python <commands2.Command.onlyWhile>`) composes a command with a condition that is continuously checked during execution. If the condition becomes false while the command is running, the command will be interrupted. This is backed by a ``ParallelRaceGroup`` with a ``WaitUntilCommand``. |
|
|
||
| ``ProxyCommand`` described below also has a constructor overload ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ProxyCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_proxy_command.html), :external:py:class:`Python <commands2.ProxyCommand>`) that calls a command-returning lambda at schedule-time and runs the returned command by proxy. | ||
|
|
||
| The ``Defer`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#defer(java.util.function.Supplier,java.util.Set)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#a03fe6ddac82ad3a4e1c086b1c0c23422), :external:py:func:`Python <commands2.cmd.defer>`), backed by the ``DeferredCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/DeferredCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_deferred_command.html), :external:py:class:`Python <commands2.DeferredCommand>`), defers command construction to schedule-time by calling a lambda that returns a command. Unlike ``ProxyCommand``, the deferred command runs inline within the composition, keeping everything within the composition instead of delegating to the scheduler. This should generally be preferred over the deferred ``ProxyCommand`` constructor. |
There was a problem hiding this comment.
Suggested change
| The ``Defer`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#defer(java.util.function.Supplier,java.util.Set)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#a03fe6ddac82ad3a4e1c086b1c0c23422), :external:py:func:`Python <commands2.cmd.defer>`), backed by the ``DeferredCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/DeferredCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_deferred_command.html), :external:py:class:`Python <commands2.DeferredCommand>`), defers command construction to schedule-time by calling a lambda that returns a command. Unlike ``ProxyCommand``, the deferred command runs inline within the composition, keeping everything within the composition instead of delegating to the scheduler. This should generally be preferred over the deferred ``ProxyCommand`` constructor. | |
| The ``Defer`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#defer(java.util.function.Supplier,java.util.Set)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#ac177b5a1115cf55d575d5295c25ab7d1), :external:py:func:`Python <commands2.cmd.defer>`), backed by the ``DeferredCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/DeferredCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_deferred_command.html), :external:py:class:`Python <commands2.DeferredCommand>`), defers command construction to schedule-time by calling a lambda that returns a command. Unlike ``ProxyCommand``, the deferred command runs inline within the composition, keeping everything within the composition instead of delegating to the scheduler. This should generally be preferred over the deferred ``ProxyCommand`` constructor. |
|
See #2252 (comment)
Perhaps even merge their sections |
- Updated C++ onlyIf link to correct overload - Updated C++ onlyWhile link to correct overload - Updated C++ defer link to correct overload - Changed Java onlyIf example to use method reference (intake::hasGamePiece) - Changed Python onlyIf example to use method reference (intake.hasGamePiece) Co-authored-by: katzuv <[email protected]>
Remove broken intersphinx link to commands2.cmd.defer which is not found in Python API documentation. Keep plain text 'Python' reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds comprehensive documentation for three command decorators/factories that were missing from the command compositions documentation:
DeferredCommand/defer()factoryonlyIf()decoratoronlyWhile()decoratorChanges
defer()factory backed byDeferredCommandfor schedule-time command constructiononlyIf()decorator for conditional command execution (runs only if condition is true)onlyWhile()decorator for commands that interrupt when condition becomes falseFixes #2368
Fixes #2252