# `BB.Dsl.CommandTransformer`
[🔗](https://github.com/beam-bots/bb/blob/main/lib/bb/dsl/command_transformer.ex#L5)

Generates convenience functions for commands on the robot module and
resolves arm/disarm command routing.

For each command defined in the DSL, this transformer generates a function
on the robot module that calls `BB.Robot.Runtime.execute/3`.

It also:

- Sets `arm: true` implicitly on commands whose handler is `BB.Command.Arm`,
  and `disarm: true` implicitly on commands using `BB.Command.Disarm`. This
  preserves the historical behaviour of `BB.Safety.arm/1`/`BB.Safety.disarm/2`
  for robots that use the built-in command modules: those calls now dispatch
  via the runtime instead of flipping safety state directly, while still
  producing the same observable outcome.
- Validates that at most one command in the DSL is `arm`-flagged and at most
  one is `disarm`-flagged, that no single command sets both, and that the
  `allowed_states` of flagged commands are compatible with the state(s) the
  command is supposed to transition out of.
- Injects `__bb_arm_command__/0` and `__bb_disarm_command__/0` lookup
  functions on the robot module, returning the name (atom) of the
  flagged command or `nil`. `BB.Safety` uses these to decide whether to
  route through the command pipeline or fall through to the safety
  controller's direct state-flip behaviour.

## Example

Given a command definition:

    commands do
      command :navigate_to_pose do
        handler NavigateToPoseHandler
        argument :target_pose, BB.Pose, required: true
        argument :tolerance, :float, default: 0.1
      end
    end

This transformer generates:

    @spec navigate_to_pose(keyword()) :: {:ok, pid()} | {:error, term()}
    def navigate_to_pose(goal \\ []) do
      BB.Robot.Runtime.execute(__MODULE__, :navigate_to_pose, Map.new(goal))
    end

The caller can then await the command to get the result:

    {:ok, cmd} = MyRobot.navigate_to_pose(target_pose: pose)
    {:ok, result} = BB.Command.await(cmd)

# `after_compile?`

---

*Consult [api-reference.md](api-reference.md) for complete listing*