LightSOPLang Syntax

Statements and Variable Declarations

Every statement begins with the at-sign followed by a variable name. The interpreter treats the portion between the at-sign and the first space as the variable identifier. The next token is the command name. Remaining tokens become arguments. The parser in lightSOPLang/parser.mjs stores the declaration signature so the interpreter can determine when a subsequent update changes a variable.

@input capture           # variable + command, no args
@note annotate "with spaces"   # quoted literal
@result combine $input $note tag-123   # variables and unquoted literal

Arguments and Literals

Arguments that start with a dollar sign are references to variables defined earlier in the script. The interpreter replaces them with the public value of the referenced variable before invoking the registry. Arguments that do not start with a dollar sign are treated as literals. Literal tokens preserve original casing and punctuation. Quoted strings (single or double) are supported and required when a literal contains spaces; the tokenizer also accepts escaped characters inside quotes. When no spaces are needed, write literals unquoted (e.g., data-fetch).

@search query "status:open" urgent
@echo emit $search "echoed message"

Dependency Notation

Referencing a variable with the dollar prefix creates a dependency. The interpreter records these dependencies so it can compute a topological execution order. If a variable depends on another variable that has not been defined the interpreter throws a descriptive error while loading the script. Each variable may appear as an argument multiple times in the same statement; the interpreter treats every reference as a dependency.

@raw fetch
@clean normalize $raw
@analyze analyze $clean
@final final-answer $analyze "done"

English Mode

Scripts may begin with the #!english directive. When present, the interpreter calls LLMAgent.executePrompt to translate the following natural language instructions into LightSOPLang code. The first invocation requests an initial script. If commands fail the interpreter asks the LLM to revise the script, passing failures, variable snapshots, and the previous code as context. The translation loop continues until failures disappear or the configured maximum number of regeneration rounds is reached.

Command Registry Interface

After parsing a statement, the interpreter constructs a payload that contains the command name, a list of argument values, the raw token string, the variable name, and the underlying variable state. Registries receive this payload together with a responder that can emit success, failure, or cancellation values. This payload format is shared by orchestration skills and MCP skills alike. Sample payloads can be observed during the test run when LightSOPLang commands call inventoryLookup or nested skills.