Class DocTranslatorObj

Class DocTranslatorObj#

Inheritance Relationships#

Base Type#

  • public ffi::Object

Class Documentation#

class DocTranslatorObj : public ffi::Object#

Eager translation context shared by registered hooks. Hooks construct Docs, use explicit lexical scopes, and attach origins when emitting. 

ffi::Optional<ExprDoc> Hook(DocTranslatorObj* d, ffi::AnyView value,
const ffi::Object* destination) {
  ExprDoc rhs = LiteralDoc::Str("value", std::nullopt);
if (!destination) return rhs;
auto var = ffi::GetRef<Var>(static_cast<const VarObj*>(destination));
  IdDoc lhs(d->VarGetOrAllocId(var, true)->name);
  d->Emit(AssignDoc(lhs, rhs, std::nullopt), var);
return std::nullopt;
}
// Register with TypeAttrDef<Node>().attr(kDocTranslate, FDocTranslate::FromNative<&Hook>()).

Public Functions

inline ffi::Optional<ExprDoc> Translate(ffi::AnyView value, const ffi::Optional<Var> bind_var = std::nullopt)#

Translate a value with an optional pre-mapped binding variable.

Parameters:

  • value – The input value.

  • bind_var – The binding variable, or None when no binding is requested.

Returns:

An expression for the caller, or None when emission completed the request. Callers requiring an expression use value(); for a specific Doc subtype, use value().as_or_throw<T>().

inline void Emit(const Doc &doc, ffi::Optional<ffi::ObjectRef> origin = std::nullopt)#

Append a completed Doc and record its optional origin.

Parameters:

  • doc – The emitted Doc.

  • origin – The original IR object represented by this emission.

inline IdDoc VarGetOrAllocId(const Var &var, bool explicit_def)#

Reuse or allocate a variable’s stable identifier.

Parameters:

  • var – The variable to name.

  • explicit_def – Whether this occurrence defines the variable.

Returns:

The binding’s IdDoc, with explicit definitions removed from pending entries.

inline IdDoc AllocId(const ffi::String &hint)#

Reserve a fresh identifier without mapping a variable.

Parameters:

hint – The preferred name.

Returns:

The allocated identifier.

inline ffi::Dict<Var, IdDoc> GetImplicitDefs()#

Get the current variable scope’s pending definitions.

Returns:

The live mutable dictionary of variables and their identifiers.

template<typename T>
inline T GetExtraConfig(const ffi::String &name, T fallback) const#

Read a typed extension option.

Template Parameters:

T – The option type.

Parameters:

  • name – The option name.

  • fallback – The value to use when absent.

Returns:

The typed option or fallback, rejecting an existing wrong type.

template<typename T>
inline T GetOrCreateExtraState(const ffi::String &name)#

Get or initialize typed extension state.

Template Parameters:

T – The state type, default constructed when absent.

Parameters:

name – The state name.

Returns:

The stored value, rejecting an existing wrong type; mutable handles share storage.

inline void SetExtraState(const ffi::String &name, std::optional<ffi::Any> value)#

Replace or remove extension state.

Parameters:

  • name – The state name.

  • value – The replacement value, or nullopt to remove the entry.

inline void BeginVarScope()#

Begin a lexical variable scope independent of Doc collection.

inline void EndVarScope()#

End the latest naming region, retaining the root region. Explicit local bindings expire. Unresolved implicit references and their identifiers remain pending in the enclosing region, preserving captures shared by sibling functions.

template<typename Callback>
inline decltype(auto) WithVarScope(Callback &&callback)#

Run a callback in a balanced lexical variable scope without collecting Docs.

Note

Automatic cleanup on return or exception discards scope-close errors. Explicit EndVarScope calls remain checked.

Template Parameters:

Callback – The callable type.

Parameters:

callback – The callback run inside the scope.

Returns:

The callback result, preserving void, value and reference results.

template<typename T, typename Callback>
inline decltype(auto) WithExtraStateScope(const ffi::String &name, T value, Callback &&callback)#

Run a callback with temporarily replaced typed extension state.

Note

Restore the saved value on return or exception. This does not collect Docs.

Template Parameters:

  • T – The state type, default constructed when absent.

  • Callback – The callable type.

Parameters:

  • name – The state name, checked for an existing incompatible type.

  • value – The temporary state value.

  • callback – The callback run with the temporary state.

Returns:

The callback result, preserving void, value and reference results.

inline void BeginDocScope()#

Push an empty Doc collection.

inline ffi::List<Doc> EndDocScope()#

Pop the latest Doc collection.

Returns:

The collected Docs.

inline ffi::List<Doc> CurrentScopeDocs() const#

Get the current Doc collection without popping it.

Returns:

A mutable handle sharing the active collection’s storage.

template<typename Callback>
inline ffi::List<Doc> WithDocScope(Callback &&callback)#

Run a callback in a balanced Doc collection scope.

Template Parameters:

Callback – The callable type.

Parameters:

callback – The callback that emits Docs.

Returns:

The collected Docs.

inline ffi::Dict<Doc, ffi::ObjectRef> GetDocOrigins() const#

Get the owned Doc-to-original-object associations.

Returns:

A mutable handle sharing the origin dictionary’s storage.

inline void RecordOrigin(const Doc &doc, const ffi::ObjectRef &origin)#

Set a Doc’s original IR object, replacing any previous association.

Parameters:

  • doc – The constructed Doc.

  • origin – The original IR object.

inline ffi::Optional<ExprDoc> DefaultTranslate(ffi::AnyView value, const ffi::Object *destination = nullptr)#

Dispatch to a registered hook, or reflect an unhandled Type constructor.

Parameters:

  • value – The input value.

  • destination – A borrowed Var, or nullptr when no binding is requested.

Returns:

An expression for the caller, or None after completed emission.

ExprDoc DefaultTypeTranslate(const Type &type)#

Translate a Type constructor from its reflected fields and fixed defaults.

Public Static Functions

static inline int32_t _GetOrAllocRuntimeTypeIndex()#
static inline int32_t RuntimeTypeIndex() noexcept#

Protected Functions

inline explicit DocTranslatorObj(const DocTranslatorVTable *vtable, ffi::Map<ffi::String, ffi::Any> extra_config = {})#

Initialize an engine’s translation context.

Parameters:

  • vtable – The engine callbacks, valid for this object’s lifetime.

  • extra_config – The owned configuration snapshot.

Protected Attributes

ffi::List<ffi::List<Doc>> doc_scopes_#

Active Doc collections, independent of lexical variable scopes.