Command.java

// Copyright (c) FIRST and other WPILib contributors.
// Open Source Software; you can modify and/or share it under the terms of
// the WPILib BSD license file in the root directory of this project.
 
package org.wpilib.command3;
 
import static org.wpilib.util.ErrorMessages.requireNonNullParam;
 
import java.util.Collection;
import java.util.Collections;
import java.util.Set;
import java.util.function.BooleanSupplier;
import java.util.function.Consumer;
import org.wpilib.annotation.NoDiscard;
import org.wpilib.units.measure.Time;

@NoDiscard("Commands must be used! Did you mean to fork it or bind it to a trigger?")
public interface Command {
  int DEFAULT_PRIORITY = 0;

  int LOWEST_PRIORITY = Integer.MIN_VALUE;

  int HIGHEST_PRIORITY = Integer.MAX_VALUE;

  void run(Coroutine coroutine);

  default void onCancel() {
    // NOP by default
  }

  default void onExit() {
    // NOP by default
  }

  @NoDiscard
  String name();

  @NoDiscard
  Set<Mechanism> requirements();

  @NoDiscard
  default int priority() {
    return DEFAULT_PRIORITY;
  }

  @NoDiscard
  default boolean isLowerPriorityThan(Command other) {
    requireNonNullParam(other, "other", "Command.isLowerPriorityThan");
 
    return priority() < other.priority();
  }

  @NoDiscard
  default boolean requires(Mechanism mechanism) {
    return requirements().contains(mechanism);
  }

  @NoDiscard
  default boolean conflictsWith(Command other) {
    requireNonNullParam(other, "other", "Command.conflictsWith");
 
    return !Collections.disjoint(requirements(), other.requirements());
  }

  default Command withTimeout(Time timeout) {
    requireNonNullParam(timeout, "timeout", "Command.withTimeout");
 
    return race(this, waitFor(timeout).named("Timeout: " + timeout.toLongString()))
        .named(name() + " [" + timeout.toLongString() + " timeout]");
  }

  static NeedsNameBuilderStage noRequirements(Consumer<Coroutine> body) {
    return new StagedCommandBuilder().noRequirements().executing(body);
  }

  static NeedsExecutionBuilderStage requiring(Mechanism requirement, Mechanism... rest) {
    // parameters will be null checked by the builder
    return new StagedCommandBuilder().requiring(requirement, rest);
  }

  static NeedsExecutionBuilderStage requiring(Collection<Mechanism> requirements) {
    // parameters will be null checked by the builder
    return new StagedCommandBuilder().requiring(requirements);
  }

  static ParallelGroupBuilder parallel(Command... commands) {
    // parameters will be null checked by the builder
    return new ParallelGroupBuilder().requiring(commands);
  }

  static ParallelGroupBuilder race(Command... commands) {
    // parameters will be null checked by the builder
    return new ParallelGroupBuilder().optional(commands);
  }

  static SequentialGroupBuilder sequence(Command... commands) {
    // parameters will be null checked by the builder
    return new SequentialGroupBuilder().andThen(commands);
  }

  static NeedsNameBuilderStage waitUntil(BooleanSupplier condition) {
    requireNonNullParam(condition, "condition", "Command.waitUntil");
 
    return noRequirements(coroutine -> coroutine.waitUntil(condition));
  }

  static NeedsNameBuilderStage waitFor(Time duration) {
    requireNonNullParam(duration, "duration", "Command.waitFor");
 
    return noRequirements(coroutine -> coroutine.wait(duration));
  }

  default ParallelGroupBuilder until(BooleanSupplier endCondition) {
    requireNonNullParam(endCondition, "endCondition", "Command.until");
 
    return new ParallelGroupBuilder()
        .optional(this, Command.waitUntil(endCondition).named("Until Condition"));
  }

  default SequentialGroupBuilder andThen(Command next) {
    // parameter will be null checked by the builder
    return new SequentialGroupBuilder().andThen(this).andThen(next);
  }

  default ParallelGroupBuilder alongWith(Command... parallel) {
    return new ParallelGroupBuilder().requiring(this).requiring(parallel);
  }

  default ParallelGroupBuilder raceWith(Command... parallel) {
    return new ParallelGroupBuilder().optional(this).optional(parallel);
  }
}