001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package edu.wpi.first.wpilibj2.command;
006
007import static edu.wpi.first.util.ErrorMessages.requireNonNullParam;
008
009import java.util.Map;
010import java.util.function.BooleanSupplier;
011import java.util.function.Supplier;
012
013/**
014 * Namespace for command factory methods.
015 *
016 * <p>For convenience, you might want to static import the members of this class.
017 */
018public final class Commands {
019  /**
020   * Constructs a command that does nothing, finishing immediately.
021   *
022   * @return the command
023   */
024  public static CommandBase none() {
025    return new InstantCommand();
026  }
027
028  // Action Commands
029
030  /**
031   * Constructs a command that runs an action once and finishes.
032   *
033   * @param action the action to run
034   * @param requirements subsystems the action requires
035   * @return the command
036   * @see InstantCommand
037   */
038  public static CommandBase runOnce(Runnable action, Subsystem... requirements) {
039    return new InstantCommand(action, requirements);
040  }
041
042  /**
043   * Constructs a command that runs an action every iteration until interrupted.
044   *
045   * @param action the action to run
046   * @param requirements subsystems the action requires
047   * @return the command
048   * @see RunCommand
049   */
050  public static CommandBase run(Runnable action, Subsystem... requirements) {
051    return new RunCommand(action, requirements);
052  }
053
054  /**
055   * Constructs a command that runs an action once and another action when the command is
056   * interrupted.
057   *
058   * @param start the action to run on start
059   * @param end the action to run on interrupt
060   * @param requirements subsystems the action requires
061   * @return the command
062   * @see StartEndCommand
063   */
064  public static CommandBase startEnd(Runnable start, Runnable end, Subsystem... requirements) {
065    return new StartEndCommand(start, end, requirements);
066  }
067
068  /**
069   * Constructs a command that runs an action every iteration until interrupted, and then runs a
070   * second action.
071   *
072   * @param run the action to run every iteration
073   * @param end the action to run on interrupt
074   * @param requirements subsystems the action requires
075   * @return the command
076   */
077  public static CommandBase runEnd(Runnable run, Runnable end, Subsystem... requirements) {
078    requireNonNullParam(end, "end", "Command.runEnd");
079    return new FunctionalCommand(
080        () -> {}, run, interrupted -> end.run(), () -> false, requirements);
081  }
082
083  /**
084   * Constructs a command that prints a message and finishes.
085   *
086   * @param message the message to print
087   * @return the command
088   * @see PrintCommand
089   */
090  public static CommandBase print(String message) {
091    return new PrintCommand(message);
092  }
093
094  // Idling Commands
095
096  /**
097   * Constructs a command that does nothing, finishing after a specified duration.
098   *
099   * @param seconds after how long the command finishes
100   * @return the command
101   * @see WaitCommand
102   */
103  public static CommandBase waitSeconds(double seconds) {
104    return new WaitCommand(seconds);
105  }
106
107  /**
108   * Constructs a command that does nothing, finishing once a condition becomes true.
109   *
110   * @param condition the condition
111   * @return the command
112   * @see WaitUntilCommand
113   */
114  public static CommandBase waitUntil(BooleanSupplier condition) {
115    return new WaitUntilCommand(condition);
116  }
117
118  // Selector Commands
119
120  /**
121   * Runs one of two commands, based on the boolean selector function.
122   *
123   * @param onTrue the command to run if the selector function returns true
124   * @param onFalse the command to run if the selector function returns false
125   * @param selector the selector function
126   * @return the command
127   * @see ConditionalCommand
128   */
129  public static CommandBase either(Command onTrue, Command onFalse, BooleanSupplier selector) {
130    return new ConditionalCommand(onTrue, onFalse, selector);
131  }
132
133  /**
134   * Runs one of several commands, based on the selector function.
135   *
136   * @param selector the selector function
137   * @param commands map of commands to select from
138   * @return the command
139   * @see SelectCommand
140   */
141  public static CommandBase select(Map<Object, Command> commands, Supplier<Object> selector) {
142    return new SelectCommand(commands, selector);
143  }
144
145  /**
146   * Runs a group of commands in series, one after the other.
147   *
148   * @param commands the commands to include
149   * @return the command group
150   * @see SequentialCommandGroup
151   */
152  public static CommandBase sequence(Command... commands) {
153    return new SequentialCommandGroup(commands);
154  }
155
156  // Command Groups
157
158  /**
159   * Runs a group of commands in series, one after the other. Once the last command ends, the group
160   * is restarted.
161   *
162   * @param commands the commands to include
163   * @return the command group
164   * @see SequentialCommandGroup
165   * @see Command#repeatedly()
166   */
167  public static CommandBase repeatingSequence(Command... commands) {
168    return sequence(commands).repeatedly();
169  }
170
171  /**
172   * Runs a group of commands at the same time. Ends once all commands in the group finish.
173   *
174   * @param commands the commands to include
175   * @return the command
176   * @see ParallelCommandGroup
177   */
178  public static CommandBase parallel(Command... commands) {
179    return new ParallelCommandGroup(commands);
180  }
181
182  /**
183   * Runs a group of commands at the same time. Ends once any command in the group finishes, and
184   * cancels the others.
185   *
186   * @param commands the commands to include
187   * @return the command group
188   * @see ParallelRaceGroup
189   */
190  public static CommandBase race(Command... commands) {
191    return new ParallelRaceGroup(commands);
192  }
193
194  /**
195   * Runs a group of commands at the same time. Ends once a specific command finishes, and cancels
196   * the others.
197   *
198   * @param deadline the deadline command
199   * @param commands the commands to include
200   * @return the command group
201   * @see ParallelDeadlineGroup
202   */
203  public static CommandBase deadline(Command deadline, Command... commands) {
204    return new ParallelDeadlineGroup(deadline, commands);
205  }
206
207  private Commands() {
208    throw new UnsupportedOperationException("This is a utility class");
209  }
210}