Macros

Macros are a fundamental feature in SOP Lang Pipeline for creating abstractions and achieving modular programming. They allow grouping multiple SOP Lang Pipeline commands into a reusable unit, which can accept input parameters and return an explicit output value.

Macro Definition and Invocation

@world_val := "World"

@runTest macro hello world_param
  @res := $hello $world_param
  return $res
end

@intResult runTest "Hello" $world_val

A macro is defined as @MacroName macro parameter1 parameter2 ... end. The parameter names are plain identifiers; inside the body they are referenced with $. The return statement specifies the macro output.

Macros are expanded directly into the call location. Their generated variables are integrated into the same dependency graph and remain fully reactive. This model differs from traditional call-stack invocation: expansion instantiates command lines and variable declarations for each call site.

When invocation arguments change, expanded macro internals are re-evaluated, and the designated return output updates reactively.

If a macro path does not designate a valid return value, the resolved result may remain undefined. This is relevant for dependency tracking and is an area where runtime signalling mechanisms are continuously refined.

Custom Commands with JSDEF

SOP Lang Pipeline provides a mechanism to define custom commands using JavaScript via jsdef. This is structurally similar to macros, but the body is JavaScript code.

Parameters listed plainly are direct JavaScript variables, while context-bound parameters prefixed with ~ are accessible through this. The JavaScript return value is propagated back as the SOP-Lang Pipeline command output.

@concatAB jsdef a b
    console.debug(">>> Executing function:concatAB with args:", a, b, this.__currentDocId);
    return a + " " + b;
end

@hello := "Hello"
@world := "World"

@runTest jsdef hello ~world ~concatAB
    let res = this.concatAB(hello, this.world);
    return res;
end

@result1 concatAB $hello $world
@result2 runTest $hello

Commands defined with jsdef are reactive in the same way as other SOP-Lang Pipeline constructs: changes in direct arguments or in bound context variables trigger re-execution.

Context-Bound Parameters for Macros

Context-bound parameters, identified by the tilde prefix in a macro parameter list, are resolved against the macro definition context rather than the invocation context. This is particularly useful when a macro defined in one document is called from a different document.

By using these parameters, a macro can directly access variables from its home document without requiring explicit alias declarations at each call site.

@composeMessage macro ~modelRole userTopic
    @res := $modelRole " Topic: " $userTopic
    return $res
end

Advanced Macro Patterns

Macros represent a fundamental mechanism for extending SOP Lang Pipeline with custom primitives. By integrating them with map-like operations over collections, they support functional-style patterns and declarative generation of derived artefacts.

Macros are also relevant in orchestration scenarios where external callers trigger macro execution. In practical deployments, this capability is used by environments such as Achilles IDE and can be connected with higher-level agent workflows managed through libraries like AchillesAgentLib.

They are instrumental in reactive logic for external events and can orchestrate heterogeneous agents and tools in complex conversational systems, including scenarios where multiple LLMs and specialised knowledge layers are involved.