CEP-0027: Source Text and Value Reflection¶

Draft

Draft proposal for broad source-text access, public expression reflection, general value reflection, and extended scope inspection. V1 reflection exposes focused semantic metadata only.

Summary¶

Catalyst should eventually decide whether public reflection can expose source text, expression trees, general comptime-known values, or stack/scope inspection beyond the accepted direct caller/current scope metadata.

V1 keeps reflection focused on semantic metadata needed for diagnostics, docs, and tooling. It explicitly excludes public Type.Value, public Type.Expr, general value reflection, namespace enumeration, and direct source-text access.

Example¶

Possible future shape:

fn explain(comptime expr: Type.Expr) {
  const source = expr.source_text()
  const value = expr.eval_if_constant()
  @diagnostic.note("expression `{}` has constant value {}", source, value)
}

V1 exposes stable source locations and semantic metadata, but not direct source text, expression trees, or general reflected values.

Motivation¶

Source and value reflection can power documentation, code generation, serialization, and metaprogramming. It can also couple programs to syntax trivia, compiler internals, and unstable expression shapes.

Proposed Direction¶

The proposal should cover:

direct source-text access and capability boundaries;
public expression tree representation, if any;
general comptime-known value reflection;
namespace enumeration;
stack-frame or caller-chain inspection beyond direct Scope.caller() and Scope.current();
caching and resource behavior for source text;
diagnostics and docs rendering;
privacy and module-boundary rules.

V1 Compatibility¶

V1 source metadata exposes stable identity, paths, module information, and source locations where accepted. It does not expose direct source text or general reflected values.