24. Wrappers

24.1 Compile-time transformation

CS-WRAP-001. A wrapper transforms an existing DirectSharp target or selected region at compile time. It receives restricted read-only target/source metadata and emits DirectSharp. The final expanded program undergoes ordinary parsing, binding, type checking and backend lowering. A wrapper template fragment need not be independently valid as a complete program; the final expansion must be.

CS-WRAP-002. Engine selection uses an explicit application input, otherwise the project's default_wrapper_engine, otherwise a diagnostic:

project
    default_wrapper_engine scriban
end project

wrap cached with engine: scriban

The second fragment is application metadata on a suitable declaration with an available cached wrapper and registered engine. Engines are supplied through referenced capabilities. Scriban is a possible engine, not a required language semantic dependency. Wrapper declarations use .ds; an external template asset keeps the engine's natural extension.

24.2 Targets and source fragments

CS-WRAP-003. A wrapper declares supported target kinds. Unsupported targets are rejected before rendering. Metadata describes the actual target's appropriate signature, contracts, type and source fragments; unsupported fields are errors, not fabricated values. The original target remains available even when expansion changes its form.

Fragments include the original full construct, header, body and footer. A consumed wrapper application is excluded from reusable fragments to avoid automatic recursive reapplication. Source/indentation helpers must preserve strings, multiline literals and comments.

CS-WRAP-004. block wrap selects a region to transform. Its default expanded form uses the body's source rather than necessarily retaining a generic lexical block. A wrapper can explicitly emit the original full block to retain that scope. Scoping follows the final DirectSharp source. Appending a statement does not make it execute after an early return or exception; ordinary generated finally is needed for guaranteed cleanup.

24.3 Order, identity and hygiene

CS-WRAP-005. Multiple wrappers at a site apply in written order; each receives the preceding expansion while retaining the stable original anchor. Consumed wrappers are not reapplied automatically to emitted copies. Explicit nested expansion is bounded; recursive/cyclic expansion is diagnosed.

Application metadata includes:

Project order is normalized project-relative path order followed by source order. Indexing occurs before expansion. Generated fragments do not renumber authored applications. Identity is reproducible for identical inputs, not permanent across refactoring/file moves. Generated application identities are deterministically derived where nested applications are supported.

CS-WRAP-006. Compiler temporaries must be hygienic. Generated public/member names are checked for ordinary collisions, not silently renamed. Default transformation preserves the original construct/body once; detectable accidental omission or duplication is diagnosed. A wrapper may create a sibling action tied to its target, but this does not establish general standalone generation grammar.

24.4 Diagnostics and source mapping

CS-WRAP-007. Expanded-source diagnostics preserve application/template/generated locations as far as practical. Expansion inspection exposes the final DirectSharp program. Engines receive restricted metadata/host APIs, not arbitrary compiler objects or unrestricted file/system access. Engine output may not bypass DirectSharp validation by generating C# directly.

The wrapper contract is expressed by the expanded program. There is no runtime proceed operation, implicit before/after callback protocol or interceptor object model.

Specification contents · Previous: 23. Features · Next: 25. Preprocessing and includes