WPILibC++ 2024.3.2-10-g25ad6ea
frc2::Command Class Referenceabstract

A state machine representing a complete action to be performed by the robot. More...

#include <frc2/command/Command.h>

Inheritance diagram for frc2::Command:
wpi::Sendable wpi::SendableHelper< Command > frc2::CommandBase

Public Types

enum class  InterruptionBehavior { kCancelSelf , kCancelIncoming }
 An enum describing the command's behavior when another command with a shared requirement is scheduled. More...
 

Public Member Functions

 ~Command () override
 
 Command (const Command &)=default
 
Commandoperator= (const Command &rhs)
 
 Command (Command &&)=default
 
Commandoperator= (Command &&)=default
 
virtual void Initialize ()
 The initial subroutine of a command. More...
 
virtual void Execute ()
 The main body of a command. More...
 
virtual void End (bool interrupted)
 The action to take when the command ends. More...
 
virtual bool IsFinished ()
 Whether the command has finished. More...
 
virtual wpi::SmallSet< Subsystem *, 4 > GetRequirements () const
 Specifies the set of subsystems used by this command. More...
 
void AddRequirements (Requirements requirements)
 Adds the specified Subsystem requirements to the command. More...
 
void AddRequirements (wpi::SmallSet< Subsystem *, 4 > requirements)
 Adds the specified Subsystem requirements to the command. More...
 
void AddRequirements (Subsystem *requirement)
 Adds the specified Subsystem requirement to the command. More...
 
std::string GetName () const
 Gets the name of this Command. More...
 
void SetName (std::string_view name)
 Sets the name of this Command. More...
 
std::string GetSubsystem () const
 Gets the subsystem name of this Command. More...
 
void SetSubsystem (std::string_view subsystem)
 Sets the subsystem name of this Command. More...
 
CommandPtr WithTimeout (units::second_t duration) &&
 Decorates this command with a timeout. More...
 
CommandPtr Until (std::function< bool()> condition) &&
 Decorates this command with an interrupt condition. More...
 
CommandPtr OnlyWhile (std::function< bool()> condition) &&
 Decorates this command with a run condition. More...
 
CommandPtr BeforeStarting (std::function< void()> toRun, Requirements requirements={}) &&
 Decorates this command with a runnable to run before this command starts. More...
 
CommandPtr AndThen (std::function< void()> toRun, Requirements requirements={}) &&
 Decorates this command with a runnable to run after the command finishes. More...
 
CommandPtr Repeatedly () &&
 Decorates this command to run repeatedly, restarting it when it ends, until this command is interrupted. More...
 
CommandPtr AsProxy () &&
 Decorates this command to run "by proxy" by wrapping it in a ProxyCommand. More...
 
CommandPtr Unless (std::function< bool()> condition) &&
 Decorates this command to only run if this condition is not met. More...
 
CommandPtr OnlyIf (std::function< bool()> condition) &&
 Decorates this command to only run if this condition is met. More...
 
CommandPtr IgnoringDisable (bool doesRunWhenDisabled) &&
 Decorates this command to run or stop when disabled. More...
 
CommandPtr WithInterruptBehavior (Command::InterruptionBehavior interruptBehavior) &&
 Decorates this command to have a different interrupt behavior. More...
 
CommandPtr FinallyDo (std::function< void(bool)> end) &&
 Decorates this command with a lambda to call on interrupt or end, following the command's inherent Command::End(bool) method. More...
 
CommandPtr FinallyDo (std::function< void()> end) &&
 Decorates this command with a lambda to call on interrupt or end, following the command's inherent Command::End(bool) method. More...
 
CommandPtr HandleInterrupt (std::function< void()> handler) &&
 Decorates this command with a lambda to call on interrupt, following the command's inherent Command::End(bool) method. More...
 
CommandPtr WithName (std::string_view name) &&
 Decorates this Command with a name. More...
 
void Schedule ()
 Schedules this command. More...
 
void Cancel ()
 Cancels this command. More...
 
bool IsScheduled () const
 Whether or not the command is currently scheduled. More...
 
bool HasRequirement (Subsystem *requirement) const
 Whether the command requires a given subsystem. More...
 
bool IsComposed () const
 Whether the command is currently grouped in a command group. More...
 
void SetComposed (bool isComposed)
 Sets whether the command is currently composed in a command composition. More...
 
std::optional< std::string > GetPreviousCompositionSite () const
 Get the stacktrace of where this command was composed, or an empty optional. More...
 
virtual bool RunsWhenDisabled () const
 Whether the given command should run when the robot is disabled. More...
 
virtual InterruptionBehavior GetInterruptionBehavior () const
 How the command behaves when another command with a shared requirement is scheduled. More...
 
virtual CommandPtr ToPtr () &&=0
 Transfers ownership of this command to a unique pointer. More...
 
void InitSendable (wpi::SendableBuilder &builder) override
 Initializes this Sendable object. More...
 
- Public Member Functions inherited from wpi::Sendable
virtual ~Sendable ()=default
 
virtual void InitSendable (SendableBuilder &builder)=0
 Initializes this Sendable object. More...
 
- Public Member Functions inherited from wpi::SendableHelper< Command >
 SendableHelper (const SendableHelper &rhs)=default
 
 SendableHelper (SendableHelper &&rhs)
 
SendableHelperoperator= (const SendableHelper &rhs)=default
 
SendableHelperoperator= (SendableHelper &&rhs)
 

Protected Member Functions

 Command ()
 
virtual std::unique_ptr< CommandTransferOwnership () &&=0
 Transfers ownership of this command to a unique pointer. More...
 
- Protected Member Functions inherited from wpi::SendableHelper< Command >
 SendableHelper ()=default
 
 ~SendableHelper ()
 

Protected Attributes

wpi::SmallSet< Subsystem *, 4 > m_requirements
 Requirements set. More...
 
std::optional< std::string > m_previousComposition
 

Friends

class CommandPtr
 

Detailed Description

A state machine representing a complete action to be performed by the robot.

Commands are run by the CommandScheduler, and can be composed into CommandGroups to allow users to build complicated multi-step actions without the need to roll the state machine logic themselves.

Commands are run synchronously from the main robot loop; no multithreading is used, unless specified explicitly from the command implementation.

Note: ALWAYS create a subclass by extending CommandHelper<Base, Subclass>, or decorators will not function!

This class is provided by the NewCommands VendorDep

See also
CommandScheduler
CommandHelper

Member Enumeration Documentation

◆ InterruptionBehavior

An enum describing the command's behavior when another command with a shared requirement is scheduled.

Enumerator
kCancelSelf 

This command ends, End(true) is called, and the incoming command is scheduled normally.

This is the default behavior.

kCancelIncoming 

This command continues, and the incoming command is not scheduled.

Constructor & Destructor Documentation

◆ ~Command()

frc2::Command::~Command ( )
override

◆ Command() [1/3]

frc2::Command::Command ( const Command )
default

◆ Command() [2/3]

frc2::Command::Command ( Command &&  )
default

◆ Command() [3/3]

frc2::Command::Command ( )
protected

Member Function Documentation

◆ AddRequirements() [1/3]

void frc2::Command::AddRequirements ( Requirements  requirements)

Adds the specified Subsystem requirements to the command.

The scheduler will prevent two commands that require the same subsystem from being scheduled simultaneously.

Note that the scheduler determines the requirements of a command when it is scheduled, so this method should normally be called from the command's constructor.

While this overload can be used with AddRequirements({&subsystem1,
&subsystem2})
, AddRequirements({&subsystem}) selects the
AddRequirements(Subsystem*)
overload, which will function identically but may cause warnings about redundant braces.

Parameters
requirementsthe Subsystem requirements to add, which can be implicitly constructed from an initializer list or a span

◆ AddRequirements() [2/3]

void frc2::Command::AddRequirements ( Subsystem requirement)

Adds the specified Subsystem requirement to the command.

The scheduler will prevent two commands that require the same subsystem from being scheduled simultaneously.

Note that the scheduler determines the requirements of a command when it is scheduled, so this method should normally be called from the command's constructor.

Parameters
requirementthe Subsystem requirement to add

◆ AddRequirements() [3/3]

void frc2::Command::AddRequirements ( wpi::SmallSet< Subsystem *, 4 >  requirements)

Adds the specified Subsystem requirements to the command.

The scheduler will prevent two commands that require the same subsystem from being scheduled simultaneously.

Note that the scheduler determines the requirements of a command when it is scheduled, so this method should normally be called from the command's constructor.

Parameters
requirementsthe Subsystem requirements to add

◆ AndThen()

CommandPtr frc2::Command::AndThen ( std::function< void()>  toRun,
Requirements  requirements = {} 
) &&

Decorates this command with a runnable to run after the command finishes.

Parameters
toRunthe Runnable to run
requirementsthe required subsystems
Returns
the decorated command

◆ AsProxy()

CommandPtr frc2::Command::AsProxy ( ) &&

Decorates this command to run "by proxy" by wrapping it in a ProxyCommand.

This is useful for "forking off" from command groups when the user does not wish to extend the command's requirements to the entire command group.

This overload transfers command ownership to the returned CommandPtr.

Returns
the decorated command

◆ BeforeStarting()

CommandPtr frc2::Command::BeforeStarting ( std::function< void()>  toRun,
Requirements  requirements = {} 
) &&

Decorates this command with a runnable to run before this command starts.

Parameters
toRunthe Runnable to run
requirementsthe required subsystems
Returns
the decorated command

◆ Cancel()

void frc2::Command::Cancel ( )

Cancels this command.

Will call End(true). Commands will be canceled regardless of interruption behavior.

◆ End()

virtual void frc2::Command::End ( bool  interrupted)
virtual

The action to take when the command ends.

Called when either the command finishes normally, or when it interrupted/canceled.

Parameters
interruptedwhether the command was interrupted/canceled

◆ Execute()

virtual void frc2::Command::Execute ( )
virtual

The main body of a command.

Called repeatedly while the command is scheduled.

◆ FinallyDo() [1/2]

CommandPtr frc2::Command::FinallyDo ( std::function< void()>  end) &&

Decorates this command with a lambda to call on interrupt or end, following the command's inherent Command::End(bool) method.

The provided lambda will run identically in both interrupt and end cases.

Parameters
enda lambda to run when the command ends, whether or not it was interrupted.
Returns
the decorated command

◆ FinallyDo() [2/2]

CommandPtr frc2::Command::FinallyDo ( std::function< void(bool)>  end) &&

Decorates this command with a lambda to call on interrupt or end, following the command's inherent Command::End(bool) method.

Parameters
enda lambda accepting a boolean parameter specifying whether the command was interrupted.
Returns
the decorated command

◆ GetInterruptionBehavior()

virtual InterruptionBehavior frc2::Command::GetInterruptionBehavior ( ) const
inlinevirtual

How the command behaves when another command with a shared requirement is scheduled.

Returns
a variant of InterruptionBehavior, defaulting to kCancelSelf.

◆ GetName()

std::string frc2::Command::GetName ( ) const

Gets the name of this Command.

Returns
Name

◆ GetPreviousCompositionSite()

std::optional< std::string > frc2::Command::GetPreviousCompositionSite ( ) const

Get the stacktrace of where this command was composed, or an empty optional.

Intended for internal use.

Returns
optional string representation of the composition site stack trace.

◆ GetRequirements()

virtual wpi::SmallSet< Subsystem *, 4 > frc2::Command::GetRequirements ( ) const
virtual

Specifies the set of subsystems used by this command.

Two commands cannot use the same subsystem at the same time. If another command is scheduled that shares a requirement, GetInterruptionBehavior() will be checked and followed. If no subsystems are required, return an empty set.

Note: it is recommended that user implementations contain the requirements as a field, and return that field here, rather than allocating a new set every time this is called.

Returns
the set of subsystems that are required
See also
InterruptionBehavior

◆ GetSubsystem()

std::string frc2::Command::GetSubsystem ( ) const

Gets the subsystem name of this Command.

Returns
Subsystem name

◆ HandleInterrupt()

CommandPtr frc2::Command::HandleInterrupt ( std::function< void()>  handler) &&

Decorates this command with a lambda to call on interrupt, following the command's inherent Command::End(bool) method.

Parameters
handlera lambda to run when the command is interrupted
Returns
the decorated command

◆ HasRequirement()

bool frc2::Command::HasRequirement ( Subsystem requirement) const

Whether the command requires a given subsystem.

Named "HasRequirement" rather than "requires" to avoid confusion with Command::Requires(Subsystem) – this may be able to be changed in a few years.

Parameters
requirementthe subsystem to inquire about
Returns
whether the subsystem is required

◆ IgnoringDisable()

CommandPtr frc2::Command::IgnoringDisable ( bool  doesRunWhenDisabled) &&

Decorates this command to run or stop when disabled.

Parameters
doesRunWhenDisabledtrue to run when disabled.
Returns
the decorated command

◆ Initialize()

virtual void frc2::Command::Initialize ( )
virtual

The initial subroutine of a command.

Called once when the command is initially scheduled.

◆ InitSendable()

void frc2::Command::InitSendable ( wpi::SendableBuilder builder)
overridevirtual

Initializes this Sendable object.

Parameters
buildersendable builder

Implements wpi::Sendable.

◆ IsComposed()

bool frc2::Command::IsComposed ( ) const

Whether the command is currently grouped in a command group.

Used as extra insurance to prevent accidental independent use of grouped commands.

◆ IsFinished()

virtual bool frc2::Command::IsFinished ( )
inlinevirtual

Whether the command has finished.

Once a command finishes, the scheduler will call its end() method and un-schedule it.

Returns
whether the command has finished.

◆ IsScheduled()

bool frc2::Command::IsScheduled ( ) const

Whether or not the command is currently scheduled.

Note that this does not detect whether the command is in a composition, only whether it is directly being run by the scheduler.

Returns
Whether the command is scheduled.

◆ OnlyIf()

CommandPtr frc2::Command::OnlyIf ( std::function< bool()>  condition) &&

Decorates this command to only run if this condition is met.

If the command is already running and the condition changes to false, the command will not stop running. The requirements of this command will be kept for the new conditional command.

Parameters
conditionthe condition that will allow the command to run
Returns
the decorated command

◆ OnlyWhile()

CommandPtr frc2::Command::OnlyWhile ( std::function< bool()>  condition) &&

Decorates this command with a run condition.

If the specified condition becomes false before the command finishes normally, the command will be interrupted and un-scheduled.

Parameters
conditionthe run condition
Returns
the command with the run condition added

◆ operator=() [1/2]

Command & frc2::Command::operator= ( Command &&  )
default

◆ operator=() [2/2]

Command & frc2::Command::operator= ( const Command rhs)

◆ Repeatedly()

CommandPtr frc2::Command::Repeatedly ( ) &&

Decorates this command to run repeatedly, restarting it when it ends, until this command is interrupted.

The decorated command can still be canceled.

Returns
the decorated command

◆ RunsWhenDisabled()

virtual bool frc2::Command::RunsWhenDisabled ( ) const
inlinevirtual

Whether the given command should run when the robot is disabled.

Override to return true if the command should run when disabled.

Returns
whether the command should run when the robot is disabled

◆ Schedule()

void frc2::Command::Schedule ( )

Schedules this command.

◆ SetComposed()

void frc2::Command::SetComposed ( bool  isComposed)

Sets whether the command is currently composed in a command composition.

Can be used to "reclaim" a command if a composition is no longer going to use it. NOT ADVISED!

◆ SetName()

void frc2::Command::SetName ( std::string_view  name)

Sets the name of this Command.

Parameters
namename

◆ SetSubsystem()

void frc2::Command::SetSubsystem ( std::string_view  subsystem)

Sets the subsystem name of this Command.

Parameters
subsystemsubsystem name

◆ ToPtr()

virtual CommandPtr frc2::Command::ToPtr ( ) &&
pure virtual

Transfers ownership of this command to a unique pointer.

Used for decorator methods.

◆ TransferOwnership()

virtual std::unique_ptr< Command > frc2::Command::TransferOwnership ( ) &&
protectedpure virtual

Transfers ownership of this command to a unique pointer.

Used for decorator methods.

◆ Unless()

CommandPtr frc2::Command::Unless ( std::function< bool()>  condition) &&

Decorates this command to only run if this condition is not met.

If the command is already running and the condition changes to true, the command will not stop running. The requirements of this command will be kept for the new conditional command.

Parameters
conditionthe condition that will prevent the command from running
Returns
the decorated command

◆ Until()

CommandPtr frc2::Command::Until ( std::function< bool()>  condition) &&

Decorates this command with an interrupt condition.

If the specified condition becomes true before the command finishes normally, the command will be interrupted and un-scheduled.

Parameters
conditionthe interrupt condition
Returns
the command with the interrupt condition added

◆ WithInterruptBehavior()

CommandPtr frc2::Command::WithInterruptBehavior ( Command::InterruptionBehavior  interruptBehavior) &&

Decorates this command to have a different interrupt behavior.

Parameters
interruptBehaviorthe desired interrupt behavior
Returns
the decorated command

◆ WithName()

CommandPtr frc2::Command::WithName ( std::string_view  name) &&

Decorates this Command with a name.

Parameters
namename
Returns
the decorated Command

◆ WithTimeout()

CommandPtr frc2::Command::WithTimeout ( units::second_t  duration) &&

Decorates this command with a timeout.

If the specified timeout is exceeded before the command finishes normally, the command will be interrupted and un-scheduled.

Parameters
durationthe timeout duration
Returns
the command with the timeout added

Friends And Related Function Documentation

◆ CommandPtr

friend class CommandPtr
friend

Member Data Documentation

◆ m_previousComposition

std::optional<std::string> frc2::Command::m_previousComposition
protected

◆ m_requirements

wpi::SmallSet<Subsystem*, 4> frc2::Command::m_requirements
protected

The documentation for this class was generated from the following file: