> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dairy.foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Commands are an interface, anything that implements the interface works as a
command, but in Mercurial implementing it by hand is rarely done.

Commands have the following components:

# Initialise

This runs when the command starts up. Its good to put run once or setup tasks in
here.
For instance:

* Setting a target position
* Logging that the command is starting
* Setting a motor power
* Storing a starting state
* Enabling another system (e.g. a Dairy Controller)
* Disabling another system (e.g. a Dairy Controller)

<CodeGroup>
  ```java Java theme={null}
  public void initialise();
  ```

  ```kt Kotlin theme={null}
  fun initialise();
  ```
</CodeGroup>

# Execute

This may run multiple times, and is guaranteed to run at least once, straight
after initialise. Its good to put code that needs to run an update here.
For instance:

* Updating a PID controller or similar
* Setting a motor power based on a changing input
* Updating internal state used to determine the finish condition

<CodeGroup>
  ```java Java theme={null}
  public void execute();
  ```

  ```kt Kotlin theme={null}
  fun execute()
  ```
</CodeGroup>

# End

This runs when the command ends, and gets told if the command was interrupted or
not. A command is interrupted if it comes to an end that was not due to its
finish or, some command group utilities will end a command early but not
interrupt it. We'll look more at interrupting later. Its good to put cleanup
tasks here.
For instance:

* Setting a target position
* Logging that the command is ending
* Setting a motor power
* Enabling another system (e.g. a Dairy Controller)
* Disabling another system (e.g. a Dairy Controller)

<CodeGroup>
  ```java Java theme={null}
  public void end(boolean interrupted);
  ```

  ```kt Kotlin theme={null}
  fun end(interrupted: Boolean)
  ```
</CodeGroup>

# The Contract

These three parts of a command are the most important. Commands are guaranteed
to run these three in order, with execute potentially being called many times.
This behaviour is unit tested in Mercurial, and all official command groups and
the scheduler are guaranteed to run commands like this, so if you write your own
group, you must adhere to this rule.

Finished is also important, it often runs after execute, but is not guaranteed
to be run.

# Finished

This may run multiple times, but is not guaranteed to, and is used by the
command scheduler and command groups to determine if a command is done.

A command should never rely on finished being run to function correctly, for
this reason, finished should not modify state, it should only check state to
perform the boolean check.

For instance:

* Is the encoder at the target position?
* Has enough time elapsed?
* Is the motor overcurrent?
* Has the sensor been triggered?

<CodeGroup>
  ```java Java theme={null}
  public boolean finished();
  ```

  ```kt Kotlin theme={null}
  fun finished(): Boolean
  ```
</CodeGroup>

# Requirements

The set of requirements. Requirements are 'lock' objects for commands, and
commands use them to declare things that they need exclusive access to. If a
command that has overlapping requirements with a currently scheduled command is
scheduled, the currently scheduled command is checked to see if it can be
interrupted, and if so, it is cancelled early.

Command groups don't look closely at requirements, so its assumed that the
user will do the right job there, but they do compute and report the union
set of all requirements of all commands they contain.

Mercurial doesn't require that subsystems are used as requirements, but usually
they are, or hardware objects are used, as both of these are commonly needed for
exclusive access.

Although this is accessed via a getter, its assumed that the contents don't
change for a command.

<CodeGroup>
  ```java Java theme={null}
  public Set<Object> getRequirements();
  ```

  ```kt Kotlin theme={null}
  val requirements: Set<Any>
  ```
</CodeGroup>

# RunStates

Run states are the states that a command is allowed to be scheduled in.

Most commands should not be able to be ran in Init, so this prevents that.

However, if a command has runstates of `OpModeState.INIT`, and it is started in
this OpModeState, and then it becomes `OpModeState.ACTIVE`, the command will not
finish prematurely.

Same as Requirements, this should not change.

<CodeGroup>
  ```java Java theme={null}
  public Set<OpModeState> getRunStates();
  ```

  ```kt Kotlin theme={null}
  val runStates: Set<OpModeState>
  ```
</CodeGroup>

# Interruptible

Also see Requirements. If a command is interruptible, that means that if another
command wishes to be scheduled, and there is a conflict of requirements, then
this should end early, and interrupted.

<CodeGroup>
  ```java Java theme={null}
  public boolean getInterruptible();
  ```

  ```kt Kotlin theme={null}
  val interruptible: Boolean
  ```
</CodeGroup>

# Schedule and Cancel

All commands can be scheduled and cancelled via `Command.schedule()` and
`Command.cancel()` these methods are the only ways to do so.

If you override these methods, you must include the super method from the
interface.

# Names and Stacktraces

Commands need to have a string representation, and a stack trace unwind
representation.

Don't worry too much about this if you are writing your own Command class that
isn't some group. However, if you are writing a group of some description, the
CommandGroup abstract class may be helpful, and will handle this automatically.

`Command.toString()` must return the name of the command, learn more about
command names and error messages in the next section.

# Composition

Commands all have decorator methods to easily compose them into the majority of
built in command groups.

We'll look at those when looking at the relevant command groups.