Aborting

AbortLine Signal

Sometimes it's necessary to abort an assembled line of BotActions. Perhaps the bot detects that a required button, to complete its task, is missing from the web page. Therefore, instead of letting the subsequent BotActions run and fail, from trying to click a button that doesn't exist, a BotAction can instead return an AbortLineSignal.

Copy
type AbortLineSignal = {
  brand: 'Abort_Signal',
  assembledLines: number,
  pipeValue?: PipeValue
}

AbortLine signals are created with the createAbortLineSignal() helper. As seen above, it's a simple JSON object with two to three properties.

Assembled Lines Count

The most important property of an AbortLine Signal is called assembledLines. It informs the higher-order assembler, how many assembled lines of BotActions, the signal should break.

When as assembler processes an AbortLine Signal, with a positive assembledLines count, it breaks its sub-line, then decreases the count by 1 before returning the signal for the next assembler to process.

The default count of assembledLines is one for both the abort() BotAction and the createAbortLineSignal() helper. It can be any positive number, including zero.

Infinity AbortLine Signal

It's possible to abort all lines of assembly without knowing how many there are by returning an Infinity AbortLine Signal.

Infinity AbortLines have assembledLines set to 0. When an assembler processes an Infinity AbortLine signal, it aborts what it's doing and returns the same signal without decreasing the assembledLines count.

Optional Pipe Value

AbortLineSignal has an optional param called pipeValue that carries a PipeValue back to the final aborted assembler for return.

The optional pipeValue param does not get returned by Chain, when it's the final assembler to process an AbortLine signal, because chains don't deal with pipe values. Use Pipe instead.

Process AbortLine Signal

Almost every assembler processes an AbortLine signal with the processAbortLineSignal() helper. It supports all main use-cases of assembledLines: 0, 1, and 2+.

Here is a table for the default assemblers' aborting behavior:

Each assembler will detect the value returned by the resolved BotAction for an AbortLine Signal. If it is an AbortLine Signal, it processes it to the effect listed above.

There are exceptions for some BotActions such as the Loops, Branching, Switch Pipe and Pipe Case(s). They implement slightly different behavior, to match their unique functionality to offer developers more control.

Unique Aborting behavior

Switch Pipe was created to supply a switch/case/break flow in Botmation. To accomplish that, it implements its own AbortLine Signal behavior, which treats the Abort BotAction like a break; statement in a switch case. When a Switch Pipe processes its assembled BotActions, and hasn't received a CasesSignal with its condition passed, it swallows up AbortLine Signals with one assembledLines, effectively ignoring them. By assembling Pipe Case(s) BotActions whose conditions pass, the Switch Pipe will STOP ignoring Abort BotActions. Therefore, mimicing the switch/case/break flow functionally. Here's an example. Once a pipeCase or pipeCases matches, the next abort() statement will stop remaining assembled BotActions from running.

The For All BotAction can have any loop iteration aborted without aborting the loop itself. A default AbortLine Signal will abort one loop iteration, while AbortLine Signals with assembledLines two or more will abort the entire loop.

All BotActions with unique aborting behavior have their aborting functionality explained in their respective documentation pages.