[commands] Add Commands v3 framework (#6518)

The framework fundamentally relies on the continuation API added in Java 21 (which is currently internal to the JDK). Continuations allow for call stacks to be saved to the heap and resumed later.

The async framework allows command bodies to be written in an imperative style. However, an async command will need to be actively cooperative and periodically call coroutine.yield() in loops to yield control back to the command scheduler to let it process other commands.

There are also some other additions like priority levels (as opposed to a blanket yes/no for ignoring incoming commands), factories requiring names be provided for commands, and the scheduler tracking all running commands and not just the highest-level groups. However, those changes aren't unique to an async framework, and could just as easily be used in a traditional command framework.

commandsv3/src/generate/main/java/commandhid.java.jinja

@@ -0,0 +1,148 @@
+// 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.
+
+// THIS FILE WAS AUTO-GENERATED BY ./commandsv3/generate_files.py. DO NOT MODIFY
+{% macro capitalize_first(string) -%}
+{{ string[0]|capitalize + string[1:] }}
+{%- endmacro %}
+package org.wpilib.commands3.button;
+
+import edu.wpi.first.wpilibj.{{ ConsoleName }}Controller;
+import edu.wpi.first.wpilibj.event.EventLoop;
+import org.wpilib.commands3.Scheduler;
+import org.wpilib.commands3.Trigger;
+
+/**
+ * A version of {@link {{ ConsoleName }}Controller} with {@link Trigger} factories for command-based.
+ *
+ * @see {{ ConsoleName }}Controller
+ */
+@SuppressWarnings("MethodName")
+public class Command{{ ConsoleName }}Controller extends CommandGenericHID {
+  private final {{ ConsoleName }}Controller m_hid;
+
+  /**
+   * Construct an instance of a controller. Commands bound to buttons on the controller will be
+   * scheduled on the {@link Scheduler#getDefault() default scheduler} using its default event loop.
+   *
+   * @param port The port index on the Driver Station that the controller is plugged into.
+   */
+  public Command{{ ConsoleName }}Controller(int port) {
+    super(port);
+    m_hid = new {{ ConsoleName }}Controller(port);
+  }
+
+  /**
+   * Construct an instance of a controller. Commands bound to buttons on the controller will be
+   * scheduled on the given scheduler using its default event loop.
+   *
+   * @param scheduler The scheduler that should execute the triggered commands.
+   * @param port The port index on the Driver Station that the controller is plugged into.
+   */
+  public Command{{ ConsoleName }}Controller(Scheduler scheduler, int port) {
+    super(scheduler, port);
+    m_hid = new {{ ConsoleName }}Controller(port);
+  }
+
+  /**
+   * Get the underlying GenericHID object.
+   *
+   * @return the wrapped GenericHID object
+   */
+  @Override
+  public {{ ConsoleName }}Controller getHID() {
+    return m_hid;
+  }
+{% for button in buttons %}
+  /**
+   * Constructs a Trigger instance around the {{ button.DocName|default(button.name) }} button's digital signal.
+   *
+   * @return a Trigger instance representing the {{ button.DocName|default(button.name) }} button's digital signal attached
+   *     to the {@link Scheduler#getDefaultEventLoop() default scheduler event loop} on the
+   *     scheduler passed to the controller's constructor, or the {@link Scheduler#getDefault
+   *     default scheduler} if a scheduler was not explicitly provided.
+   * @see #{{ button.name }}(EventLoop)
+   */
+  public Trigger {{ button.name }}() {
+    return {{ button.name }}(getScheduler().getDefaultEventLoop());
+  }
+
+  /**
+   * Constructs a Trigger instance around the {{ button.DocName|default(button.name) }} button's digital signal.
+   *
+   * @param loop the event loop instance to attach the event to.
+   * @return a Trigger instance representing the {{ button.DocName|default(button.name) }} button's digital signal attached
+   *     to the given loop.
+   */
+  public Trigger {{ button.name }}(EventLoop loop) {
+    return button({{ ConsoleName }}Controller.Button.k{{ capitalize_first(button.name) }}.value, loop);
+  }
+{% endfor -%}
+{% for trigger in triggers -%}
+{% if trigger.UseThresholdMethods %}
+  /**
+   * Constructs a Trigger instance around the axis value of the {{ trigger.DocName }}. The returned
+   * trigger will be true when the axis value is greater than {@code threshold}.
+   *
+   * @param threshold the minimum axis value for the returned {@link Trigger} to be true. This value
+   *     should be in the range [0, 1] where 0 is the unpressed state of the axis.
+   * @param loop the event loop instance to attach the Trigger to.
+   * @return a Trigger instance that is true when the {{ trigger.DocName }}'s axis exceeds the provided
+   *     threshold, attached to the given event loop
+   */
+  public Trigger {{ trigger.name }}(double threshold, EventLoop loop) {
+    return axisGreaterThan({{ ConsoleName }}Controller.Axis.k{{ capitalize_first(trigger.name) }}.value, threshold, loop);
+  }
+
+  /**
+   * Constructs a Trigger instance around the axis value of the {{ trigger.DocName }}. The returned
+   * trigger will be true when the axis value is greater than {@code threshold}.
+   *
+   * @param threshold the minimum axis value for the returned {@link Trigger} to be true. This value
+   *     should be in the range [0, 1] where 0 is the unpressed state of the axis.
+   * @return a Trigger instance that is true when the {{ trigger.DocName }}'s axis exceeds the provided
+   *     threshold, attached to the {@link Scheduler#getDefaultEventLoop() default scheduler event
+   *     loop} on the scheduler passed to the controller's constructor, or the {@link
+   *     Scheduler#getDefault default scheduler} if a scheduler was not explicitly provided.
+   */
+  public Trigger {{ trigger.name }}(double threshold) {
+    return {{ trigger.name }}(threshold, getScheduler().getDefaultEventLoop());
+  }
+
+  /**
+   * Constructs a Trigger instance around the axis value of the {{ trigger.DocName }}. The returned trigger
+   * will be true when the axis value is greater than 0.5.
+   *
+   * @return a Trigger instance that is true when the {{ trigger.DocName }}'s axis exceeds 0.5, attached to
+   *     the {@link Scheduler#getDefaultEventLoop() default scheduler event loop} on the
+   *     scheduler passed to the controller's constructor, or the {@link Scheduler#getDefault
+   *     default scheduler} if a scheduler was not explicitly provided.
+   */
+  public Trigger {{ trigger.name }}() {
+    return {{ trigger.name }}(0.5);
+  }
+{% endif -%}
+{% endfor -%}
+{% for stick in sticks %}
+  /**
+   * Get the {{ stick.NameParts[1] }} axis value of {{ stick.NameParts[0] }} side of the controller. {{ stick.PositiveDirection }} is positive.
+   *
+   * @return The axis value.
+   */
+  public double get{{ stick.NameParts|map("capitalize")|join }}() {
+    return m_hid.get{{ stick.NameParts|map("capitalize")|join }}();
+  }
+{% endfor -%}
+{% for trigger in triggers %}
+  /**
+   * Get the {{ trigger.DocName }} axis value of the controller. Note that this axis is bound to the
+   * range of [0, 1] as opposed to the usual [-1, 1].
+   *
+   * @return The axis value.
+   */
+  public double get{{ capitalize_first(trigger.name) }}Axis() {
+    return m_hid.get{{ capitalize_first(trigger.name) }}Axis();
+  }
+{% endfor -%}
+}