[command] Rename PerpetualCommand to EndlessCommand (#4177)

wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/Command.java

@@ -252,11 +252,29 @@ public interface Command {
    * decorated without issue.
    *
    * @return the decorated command
+   * @deprecated use {@link #endlessly()} instead.
    */
+  @Deprecated(forRemoval = true, since = "2023")
   default PerpetualCommand perpetually() {
     return new PerpetualCommand(this);
   }
 
+  /**
+   * Decorates this command to run endlessly, ignoring its ordinary end conditions. The decorated
+   * command can still be interrupted or canceled.
+   *
+   * <p>Note: This decorator works by composing this command within a CommandGroup. The command
+   * cannot be used independently after being decorated, or be re-decorated with a different
+   * decorator, unless it is manually cleared from the list of grouped commands with {@link
+   * CommandGroupBase#clearGroupedCommand(Command)}. The decorated command can, however, be further
+   * decorated without issue.
+   *
+   * @return the decorated command
+   */
+  default EndlessCommand endlessly() {
+    return new EndlessCommand(this);
+  }
+
   /**
    * Decorates this command to run repeatedly, restarting it when it ends, until this command is
    * interrupted. The decorated command can still be canceled.

wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/EndlessCommand.java

@@ -0,0 +1,60 @@
+// 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 edu.wpi.first.wpilibj2.command;
+
+import static edu.wpi.first.wpilibj2.command.CommandGroupBase.registerGroupedCommands;
+import static edu.wpi.first.wpilibj2.command.CommandGroupBase.requireUngrouped;
+
+/**
+ * A command that runs another command endlessly, ignoring that command's end conditions. While this
+ * class does not extend {@link CommandGroupBase}, it is still considered a CommandGroup, as it
+ * allows one to compose another command within it; the command instances that are passed to it
+ * cannot be added to any other groups, or scheduled individually.
+ *
+ * <p>As a rule, CommandGroups require the union of the requirements of their component commands.
+ *
+ * <p>This class is provided by the NewCommands VendorDep
+ */
+public class EndlessCommand extends CommandBase {
+  protected final Command m_command;
+
+  /**
+   * Creates a new EndlessCommand. Will run another command endlessly, ignoring that command's end
+   * conditions, unless this command itself is interrupted.
+   *
+   * @param command the command to run endlessly
+   */
+  public EndlessCommand(Command command) {
+    requireUngrouped(command);
+    registerGroupedCommands(command);
+    m_command = command;
+    m_requirements.addAll(command.getRequirements());
+  }
+
+  @Override
+  public void initialize() {
+    m_command.initialize();
+  }
+
+  @Override
+  public void execute() {
+    m_command.execute();
+  }
+
+  @Override
+  public void end(boolean interrupted) {
+    m_command.end(interrupted);
+  }
+
+  @Override
+  public boolean runsWhenDisabled() {
+    return m_command.runsWhenDisabled();
+  }
+
+  @Override
+  public EndlessCommand endlessly() {
+    return this;
+  }
+}

wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/PerpetualCommand.java

@@ -16,7 +16,10 @@ import static edu.wpi.first.wpilibj2.command.CommandGroupBase.requireUngrouped;
  * <p>As a rule, CommandGroups require the union of the requirements of their component commands.
  *
  * <p>This class is provided by the NewCommands VendorDep
+ *
+ * @deprecated Replaced by {@link EndlessCommand}.
  */
+@Deprecated(forRemoval = true, since = "2023")
 public class PerpetualCommand extends CommandBase {
   protected final Command m_command;
 

wpilibNewCommands/src/main/native/cpp/frc2/command/Command.cpp

@@ -5,6 +5,7 @@
 #include "frc2/command/Command.h"
 
 #include "frc2/command/CommandScheduler.h"
+#include "frc2/command/EndlessCommand.h"
 #include "frc2/command/InstantCommand.h"
 #include "frc2/command/ParallelCommandGroup.h"
 #include "frc2/command/ParallelDeadlineGroup.h"
@@ -88,6 +89,10 @@ PerpetualCommand Command::Perpetually() && {
   return PerpetualCommand(std::move(*this).TransferOwnership());
 }
 
+EndlessCommand Command::Endlessly() && {
+  return EndlessCommand(std::move(*this).TransferOwnership());
+}
+
 RepeatCommand Command::Repeat() && {
   return RepeatCommand(std::move(*this).TransferOwnership());
 }

wpilibNewCommands/src/main/native/cpp/frc2/command/EndlessCommand.cpp

@@ -0,0 +1,32 @@
+// 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.
+
+#include "frc2/command/EndlessCommand.h"
+
+using namespace frc2;
+
+EndlessCommand::EndlessCommand(std::unique_ptr<Command>&& command) {
+  if (!CommandGroupBase::RequireUngrouped(*command)) {
+    return;
+  }
+  m_command = std::move(command);
+  m_command->SetGrouped(true);
+  AddRequirements(m_command->GetRequirements());
+}
+
+void EndlessCommand::Initialize() {
+  m_command->Initialize();
+}
+
+void EndlessCommand::Execute() {
+  m_command->Execute();
+}
+
+void EndlessCommand::End(bool interrupted) {
+  m_command->End(interrupted);
+}
+
+EndlessCommand EndlessCommand::Endlessly() && {
+  return std::move(*this);
+}

wpilibNewCommands/src/main/native/include/frc2/command/Command.h

@@ -23,6 +23,7 @@ std::string GetTypeName(const T& type) {
   return wpi::Demangle(typeid(type).name());
 }
 
+class EndlessCommand;
 class ParallelCommandGroup;
 class ParallelRaceGroup;
 class ParallelDeadlineGroup;
@@ -183,9 +184,19 @@ class Command {
    * conditions.  The decorated command can still be interrupted or canceled.
    *
    * @return the decorated command
+   * @deprecated replace with EndlessCommand
    */
+  WPI_DEPRECATED("Replace with Endlessly()")
   virtual PerpetualCommand Perpetually() &&;
 
+  /**
+   * Decorates this command to run endlessly, ignoring its ordinary end
+   * conditions. The decorated command can still be interrupted or canceled.
+   *
+   * @return the decorated command
+   */
+  virtual EndlessCommand Endlessly() &&;
+
   /**
    * Decorates this command to run repeatedly, restarting it when it ends, until
    * this command is interrupted. The decorated command can still be canceled.

wpilibNewCommands/src/main/native/include/frc2/command/EndlessCommand.h

@@ -0,0 +1,79 @@
+// 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.
+
+#pragma once
+
+#ifdef _WIN32
+#pragma warning(push)
+#pragma warning(disable : 4521)
+#endif
+
+#include <memory>
+#include <utility>
+
+#include "frc2/command/CommandBase.h"
+#include "frc2/command/CommandGroupBase.h"
+#include "frc2/command/CommandHelper.h"
+
+namespace frc2 {
+/**
+ * A command that runs another command endlessly, ignoring that command's
+ * end conditions.  While this class does not extend {@link CommandGroupBase},
+ * it is still considered a CommandGroup, as it allows one to compose another
+ * command within it; the command instances that are passed to it cannot be
+ * added to any other groups, or scheduled individually.
+ *
+ * <p>As a rule, CommandGroups require the union of the requirements of their
+ * component commands.
+ *
+ * This class is provided by the NewCommands VendorDep
+ */
+class EndlessCommand : public CommandHelper<CommandBase, EndlessCommand> {
+ public:
+  /**
+   * Creates a new EndlessCommand. Will run another command endlessly,
+   * ignoring that command's end conditions, unless this command itself is
+   * interrupted.
+   *
+   * @param command the command to run endlessly
+   */
+  explicit EndlessCommand(std::unique_ptr<Command>&& command);
+
+  /**
+   * Creates a new EndlessCommand. Will run another command endlessly,
+   * ignoring that command's end conditions, unless this command itself is
+   * interrupted.
+   *
+   * @param command the command to run endlessly
+   */
+  template <class T, typename = std::enable_if_t<std::is_base_of_v<
+                         Command, std::remove_reference_t<T>>>>
+  explicit EndlessCommand(T&& command)
+      : EndlessCommand(std::make_unique<std::remove_reference_t<T>>(
+            std::forward<T>(command))) {}
+
+  EndlessCommand(EndlessCommand&& other) = default;
+
+  // No copy constructors for command groups
+  EndlessCommand(const EndlessCommand& other) = delete;
+
+  // Prevent template expansion from emulating copy ctor
+  EndlessCommand(EndlessCommand&) = delete;
+
+  void Initialize() override;
+
+  void Execute() override;
+
+  void End(bool interrupted) override;
+
+  EndlessCommand Endlessly() && override;
+
+ private:
+  std::unique_ptr<Command> m_command;
+};
+}  // namespace frc2
+
+#ifdef _WIN32
+#pragma warning(pop)
+#endif

wpilibNewCommands/src/main/native/include/frc2/command/PerpetualCommand.h

@@ -28,8 +28,11 @@ namespace frc2 {
  * component commands.
  *
  * This class is provided by the NewCommands VendorDep
+ *
+ * @deprecated replace with EndlessCommand
  */
-class PerpetualCommand : public CommandHelper<CommandBase, PerpetualCommand> {
+class WPI_DEPRECATED("Replace with EndlessCommand") PerpetualCommand
+    : public CommandHelper<CommandBase, PerpetualCommand> {
  public:
   /**
    * Creates a new PerpetualCommand.  Will run another command in perpetuity,