Class StagedCommandBuilder

java.lang.Object
org.wpilib.command3.StagedCommandBuilder
public final class StagedCommandBuilder extends Object
A builder class for commands. Command configuration is done in stages, where later stages have different configuration options than earlier stages. Commands may only be created after going through every stage, enforcing the presence of required options. All commands must have a set of requirements (which may be empty), a name, and an implementation. The builder stages are defined such that the final stage that creates a command can only be reached after going through the earlier stages to configure those required options.

Example usage: 

StagedCommandBuilder start = new StagedCommandBuilder();
NeedsExecutionBuilderStage withRequirements = start.requiring(mechanism1, mechanism2);
NeedsNameBuilderStage withExecution = withRequirements.executing(coroutine -> ...);
Command exampleCommand = withExecution.named("Example Command");

Because every method on the builders returns a builder object, these calls can be chained to cut down on verbosity and make the code easier to read. This is the recommended style: 

Command exampleCommand =
  new StagedCommandBuilder()
    .requiring(mechanism1, mechanism2)
    .executing(coroutine -> ...)
    .named("Example Command");

And can be cut down even further by using helper methods provided by the library: 

Command exampleCommand =
  Command
    .requiring(mechanism1, mechanism2)
    .executing(coroutine -> ...)
    .named("Example Command");

  • Constructor Details

    • StagedCommandBuilder

      public StagedCommandBuilder()
      Creates a new command builder. All required options must be set on each stage before a command is able to be created. Attempting to create a command without setting all required options will result in a compilation error.

  • Method Details

    • noRequirements

      public NeedsExecutionBuilderStage noRequirements()
      Explicitly marks the command as requiring no mechanisms. Unless overridden later with NeedsExecutionBuilderStage.requiring(Mechanism) or a similar method, the built command will not have ownership over any mechanisms when it runs. Use this for commands that don't need to own a mechanism, such as a gyro zeroing command, that does some kind of cleanup task without needing to control something.
      Returns:
      A builder object that can be used to further configure the command.

    • requiring

      public NeedsExecutionBuilderStage requiring(Mechanism requirement, Mechanism... extra)
      Marks the command as requiring one or more mechanisms. If only a single mechanism is required, prefer a factory function like Mechanism.run(Consumer) or similar - it will automatically require the mechanism, instead of it needing to be explicitly specified.
      Parameters:
      requirement - The first required mechanism. Cannot be null.
      extra - Any optional extra required mechanisms. May be empty, but cannot be null or contain null values.
      Returns:
      A builder object that can be used to further configure the command.

    • requiring

      public NeedsExecutionBuilderStage requiring(Collection<Mechanism> requirements)
      Marks the command as requiring zero or more mechanisms. If only a single mechanism is required, prefer a factory function like Mechanism.run(Consumer) or similar - it will automatically require the mechanism, instead of it needing to be explicitly specified.
      Parameters:
      requirements - A collection of required mechanisms. May be empty, but cannot be null or contain null values.
      Returns:
      A builder object that can be used to further configure the command.