Command Authoring

This page describes production-grade handler design for both String and Byte engines.

Handler signatures

String handler

func(*engine.StringEngine, stringParsing.ParsedNode) error

Byte handler

func(*engine.ByteEngine, byteParsing.ParsedBytes) error

Design principles

1. Deterministic behavior for identical inputs.
2. Explicit validation before execution.
3. Minimal hidden side effects.
4. Clear error messages with command context.
5. Stable writes to known pipeline points.

Recommended handler structure

1. Decode and validate node metadata/args.
2. Resolve runtime dependencies from scope.
3. Execute semantic action.
4. Emit output via generator.
5. Return contextual error on failure.

String command pattern

• Command identity comes from ParsedNode.Switch.
• Metadata schema should be parser-defined and versioned.
• Unknown command behavior should be explicit at integration layer.

Byte command pattern

• Decode binary args by your contract.
• For control flow instructions:
  • disable auto shift for that opcode,
  • mutate bytecode pointer manually.
• Make pointer movement explicit and testable.

Error discipline

Prefer:

• domain errors,
• wrapped context (fmt.Errorf("cmd <name>: %w", err)).

Avoid:

• panics in normal runtime paths,
• silent no-op behavior for critical commands.