All fifteen directives — xmlsquish user manual

`xs:pack`

Project structure

Final distributable archive root. Collects compiled entry products and complete asset bytes into a reproducible ZIP .pack.

Allowed in

Document root of a pack target.

Allowed content

Module imports, asset/include directives and macro expansion.

Attributes

—

Valid syntax

<xs:pack xmlns:xs="https://xmlsquish.moesegfault.dev/ns">
  <xs:include path="instructions.xml"/>
  <xs:asset path="scripts/check.py"/>
</xs:pack>

Constraints

An include must target an entry, never a module.
Archive member names must remain inside the archive root and cannot silently collide.

`xs:sopack`

Project structure

Relocatable compiled library root. Preserves IR, compiled modules, macros, assets and metadata, without final products.

Allowed in

Document root of a SOPack target.

Allowed content

Module imports, macro declarations and assets.

Attributes

—

Valid syntax

<xs:sopack xmlns:xs="https://xmlsquish.moesegfault.dev/ns">
  <xs:import src="macros.xml"/>
  <xs:asset path="schema.json"/>
</xs:sopack>

Constraints

No include, including inside macros.
Consumers treat the archive as immutable; source identities relocate on loading.

`xs:asset`

Definitions and calls

Preserve one complete file as bytes. Carries code or static resources without XML parsing, transcoding or prompt whitespace processing.

Allowed in

Pack or SOPack resource construction, including macro bodies.

Allowed content

Empty.

Attributes

pathrequired: File path relative to the defining source.
nameoptional: Archive member name; defaults to the relative path.

Valid syntax

<xs:asset path="scripts/check.py" name="scripts/check.py"/>

Constraints

Macro asset paths belong to the definition, not the caller.
Unsafe member paths or conflicting names are errors.

`xs:include`

Definitions and calls

Compile and include one entry. Adds an entry product to a pack rather than copying its XML source.

Allowed in

Pack construction only; not SOPack.

Allowed content

Empty.

Attributes

pathrequired: Entry path relative to the defining source.
nameoptional: Archive member name; defaults to the source stem plus .prompt.

Valid syntax

<xs:include path="instructions.xml" name="instructions.prompt"/>

Constraints

Target must be an entry, not a module.
SOPack cannot include final products.

`xs:entry`

Project structure

Build root for one output document. Accepts declarations, then constructs the final document.

Allowed in

The document root of a build target; never an import target.

Allowed content

Leading xs:import and xs:param declarations, then ordinary XML, xs:expand, xs:insert, and xs:ifr.

Attributes

—

Valid syntax

<xs:entry xmlns:xs="https://xmlsquish.moesegfault.dev/ns">
  <Prompt>Hello</Prompt>
</xs:entry>

Constraints

Declarations must precede the construction body.
Cannot define macros or root slots, and cannot be expanded as a macro.

`xs:module`

Project structure

Reusable macro library. Registers definitions but has no executable body.

Allowed in

The document root of an imported source unit.

Allowed content

xs:import and xs:macro only; they may be interleaved.

Attributes

—

Valid syntax

<xs:module xmlns:xs="https://xmlsquish.moesegfault.dev/ns"
           xmlns:app="urn:example:app">
  <xs:macro name="app:hello"/>
</xs:module>

Constraints

Ordinary XML, non-whitespace text, top-level xs:param, and expansion are invalid.
A module cannot be built as an entry and has no implicit main.

`xs:import`

Project structure

Load definitions from a module. Freezes another source unit into the symbol closure without executing it.

Allowed in

Direct child of xs:module, or the declaration region of xs:entry.

Allowed content

Empty.

Attributes

srcrequired: Static source reference resolved relative to the declaring file.

Valid syntax

<xs:import src="./macros.xml"/>

Constraints

The target must be a module, never an entry.
Produces no output, frame, arg, or fill; each source identity is loaded once.

`xs:macro`

Definitions and calls

Define an immutable named macro. Publishes one namespace-qualified symbol.

Allowed in

Direct child of xs:module; macro definitions cannot nest.

Allowed content

Leading xs:param declarations, then ordinary XML and composition directives.

Attributes

namerequired: Prefixed lexical QName resolved at the definition site.

Valid syntax

<xs:macro name="app:hello">
  <Message>Hello</Message>
</xs:macro>

Constraints

The expanded QName cannot be redefined anywhere in the frozen closure.
The body runs with definition-site file.* and explicit call inputs only.

`xs:param`

Definitions and calls

Declare a required string input. Adds one immutable Unicode-string contract.

Allowed in

At the start of xs:macro or the declaration region of xs:entry.

Allowed content

Empty.

Attributes

namerequired: Name unique within the containing macro or entry.

Valid syntax

<xs:param name="title"/>

Constraints

All parameters are required and must be supplied exactly once.
Missing, unknown, or duplicate call arguments are hard errors.

`xs:expand`

Definitions and calls

Invoke a statically resolved macro. Evaluates explicit inputs once and returns an ordered XML node sequence.

Allowed in

A construction body where output nodes are allowed.

Allowed content

xs:arg and xs:fill call inputs only.

Attributes

refrequired: Static prefixed QName of a macro already in the frozen symbol table.

Valid syntax

<xs:expand ref="app:hello">
  <xs:arg name="title" value="Hello"/>
</xs:expand>

Constraints

ref cannot come from a binding, concatenation, or regular-expression capture.
A new frame does not inherit caller arg.*, match.*, or slots.

`xs:arg`

Values and XML content

Provide one immutable string. Evaluates in the caller before the callee frame exists.

Allowed in

Direct child of xs:expand.

Allowed content

Empty for value/get forms; the body form may compose text-producing content.

Attributes

namerequired: Declared parameter name in the target macro.
valueexclusive choice: Literal string form.
getexclusive choice: Existing scalar binding form.

Valid syntax

<xs:arg name="title" get="arg.heading"/>

Constraints

Choose exactly one of value, get, or body.
A body must evaluate only to character data; whitespace is preserved and XML nodes are an error.

`xs:fill`

Values and XML content

Provide an XML node sequence. Evaluates in the caller, freezes the sequence, then supplies a slot.

Allowed in

Direct child of xs:expand.

Allowed content

Any valid construction body producing an XML node sequence.

Attributes

namerequired: Slot name declared by the target macro.

Valid syntax

<xs:fill name="body"><Message>Hello</Message></xs:fill>

Constraints

Unknown slot names and duplicate fills in one call are hard errors.
A fill is evaluated exactly once and cannot be read as a string.

`xs:slot`

Values and XML content

Insert caller-provided XML content. Marks a named insertion point inside one macro.

Allowed in

Inside an xs:macro construction body.

Allowed content

Empty.

Attributes

namerequired: Slot name unique within the containing macro.
requiredoptional · default: false: Boolean flag; true requires a matching fill.

Valid syntax

<xs:slot name="body" required="true"/>

Constraints

Missing required fills are hard errors; an unfilled optional slot emits nothing.
Slots cannot be read through get, xs:insert, or regular expressions.

`xs:insert`

Values and XML content

Emit one scalar as escaped text. Creates a text node without reparsing markup.

Allowed in

A construction body or a text-only xs:arg body.

Allowed content

Empty.

Attributes

getrequired: Existing file.*, arg.*, or in-scope match.* binding.

Valid syntax

<xs:insert get="arg.name"/>

Constraints

A missing binding is a hard error, not an empty string.
Characters such as <, >, and & are escaped and never interpreted as XML markup.

`xs:ifr`

Control

Match a string and conditionally emit. Exposes lexical named captures while its body runs.

Allowed in

A construction body, including nested macro and ifr bodies.

Allowed content

Any valid construction body evaluated only after a successful match.

Attributes

getexclusive choice: Existing scalar binding input.
strexclusive choice: Literal string input.
patternrequired: Unicode regular expression using the supported subset.

Valid syntax

<xs:ifr get="arg.value" pattern="^(?&lt;head&gt;.)$">
  <xs:insert get="match.head"/>
</xs:ifr>

Constraints

Choose exactly one of get or str; a failed match emits nothing.
Only named captures are exposed. Positional capture groups, look-around, and backreferences are forbidden; use (?:…) for non-capturing groups.
match.* bindings end with the lexical block; unmatched optional captures do not exist.