.. ---------------------------------------------------------------------------------------------- Copyright (c) The Einsums Developers. All rights reserved. Licensed under the MIT License. See LICENSE.txt in the project root for license information. ---------------------------------------------------------------------------------------------- .. _cppapi_IR — bound declarations: ======================= IR — bound declarations ======================= .. note:: Generated from the C++ headers by ``apiary --emit-cpp-docs-json``. .. cpp:namespace:: apiary .. cpp:type:: DirectiveList A list of parsed annotation directives. .. cpp:class:: BoundClass A bound class or struct, with its members and nested entities. .. cpp:member:: bool is_template True for class templates. .. cpp:member:: bool is_external True for annotated classes seen in headers OUTSIDE the current module's source filter. Captured purely for cross-module name resolution in the .pyi emitter — the C++ emitter ignores them (their bindings live in the owning module's TU). .. cpp:member:: std::vector template_param_names Template parameter names, e.g. ["T", "rank"] for ``template ``. .. cpp:member:: std::vector bases Base class names. .. cpp:member:: std::vector ctors Bound constructors. .. cpp:member:: std::vector methods Bound methods. .. cpp:member:: std::vector fields Bound public fields. .. cpp:member:: std::vector nested_enums Nested enums. .. cpp:member:: std::vector nested_classes Nested classes. .. cpp:member:: std::vector instantiations Requested template instantiations. .. cpp:member:: std::vector properties /@setter pairs collapsed into properties. Computed by the post-IR pass in Properties.hpp; empty until the pass has run. .. cpp:class:: BoundConcept A C++20 concept. Captured in docs mode for ``cpp:concept`` declarations. .. cpp:member:: std::vector template_param_names Template parameter names of the concept. .. cpp:class:: BoundEntityCommon Common metadata every bound declaration carries. Inherited by the concrete bound-* structs below so the emitter can write generic code against this base when convenient. .. cpp:member:: std::string name Unqualified name. .. cpp:member:: std::string qualified_name Fully qualified name, e.g. ``::ns::Class::method``. .. cpp:member:: DirectiveList directives Annotation directives attached to this entity. .. cpp:member:: std::string doc Raw doxygen text, or empty. .. cpp:member:: SourceLocation location Source location of the declaration. .. cpp:member:: std::optional submodule Resolved Python submodule path (from a per-entity or inherited APIARY_MODULE directive on an enclosing namespace). Empty when the entity belongs to the top-level module. The .pyi emitter uses this to decide which `.pyi` file an entity belongs to (e.g. einsums.linalg, einsums.graph). .. cpp:class:: BoundEnum A bound enumeration. .. cpp:member:: bool is_scoped True for scoped enums (`enum class`). .. cpp:member:: std::string underlying_type C++ underlying type as written. .. cpp:member:: std::string underlying_py_type Python-stub form of the underlying type. .. cpp:member:: std::vector enumerators The enum's enumerators. .. cpp:class:: BoundEnumerator A single enumerator within a bound enum. .. cpp:member:: std::string name Enumerator name. .. cpp:member:: std::int64_t value Enumerator integer value. .. cpp:member:: std::string doc Raw doxygen text, or empty. .. cpp:class:: BoundField A bound public data member (field) of a class. .. cpp:member:: std::string type C++ type of the field. .. cpp:member:: std::string py_type Python-stub form of the type. .. cpp:member:: bool is_static True for static data members. .. cpp:class:: BoundFunction A bound free function. .. cpp:member:: std::string return_type C++ return type as written. .. cpp:member:: std::string return_type_canonical Canonical (typedef-expanded) form of the return type. For per-instantiation .pyi emission we substitute and look up the canonical form so a function returning the typedef alias ``RuntimeTensor`` resolves to the same Python class as the underlying ``GeneralRuntimeTensor>``. .. cpp:member:: std::string return_py_type Python-stub form of the return type. .. cpp:member:: std::vector params Parameters of the function. .. cpp:member:: bool is_template True for function templates. .. cpp:member:: std::vector template_param_names Names of the function template's template parameters (e.g. ``["AType", "BType", "CType"]`` for ``template ``). Used by the emitter to substitute concrete types from per-instantiation type_args into return/parameter types when emitting a static_cast<> to disambiguate overloads. .. cpp:member:: std::vector template_kwargs Python kwarg names for the leading bool template parameters, from ``APIARY_TEMPLATE_KWARGS``. Empty for functions without that directive. The emitter generates a runtime dispatcher with these as keyword-only arguments when non-empty. .. cpp:member:: std::vector instantiations One per ``APIARY_INSTANTIATE_AS`` directive on a templated free function. Empty for non-templated functions and for templated functions without explicit instantiation directives (those skip emission with a TODO comment). .. cpp:member:: std::vector python_overloads Logical Python-facing entries for this function, computed by a post-IR pass (see PythonOverloads.hpp). The C++ emitter dispatches on each entry's `kind` to choose dispatcher style; the .pyi emitter renders one `def` (with `@overload` decorators if needed) per entry. Empty when the pass hasn't run yet. .. cpp:class:: BoundInstantiation One concrete template instantiation requested by an @instantiate or _as directive. The emitter produces both an explicit ``template class Foo;`` declaration and a per-instantiation ``py::class_>(m, py_name)`` binding block from this. .. cpp:member:: std::string py_name Python identifier (sanitized or user-supplied). .. cpp:member:: std::string type_args Type arguments ready to paste between < and >, e.g. "float, 2". .. cpp:class:: BoundMacro A documented preprocessor macro. Macros are not AST declarations, so these are gathered by a raw-text scan of the module header for a doc comment immediately preceding a ``#define`` (docs mode only). Rendered as ``c:macro`` in the C++ reference. .. cpp:member:: bool is_function_like True for function-like macros. .. cpp:member:: std::vector params Parameter names for function-like macros. .. cpp:class:: BoundMethod A bound class method, constructor, or destructor. .. cpp:member:: std::string return_type C++ return type as written. .. cpp:member:: std::string return_type_canonical Canonical (typedef-expanded) form of the return type. Same role as ``BoundFunction::return_type_canonical``: the .pyi emitter substitutes member-template bindings on this and re-resolves so per-directive overloads emit concrete return types. .. cpp:member:: std::string return_py_type Python-stub form of the return type. .. cpp:member:: std::vector params Parameters of the method. .. cpp:member:: bool is_const True for const-qualified methods. .. cpp:member:: bool is_static True for static methods. .. cpp:member:: bool is_virtual True for virtual methods. .. cpp:member:: bool is_template True for member function templates. .. cpp:member:: std::vector template_param_names Its template parameters (docs mode). .. cpp:member:: bool is_pure_virtual True for pure-virtual methods. .. cpp:member:: bool is_constructor True if this method is a constructor. .. cpp:member:: bool is_destructor True if this method is a destructor. .. cpp:member:: bool is_operator True if this method is an operator overload. .. cpp:member:: bool is_deleted True if this method is deleted (`= delete`). .. cpp:member:: bool has_variadic_pack Whether the last parameter is a variadic pack (set by APIARY_VARIADIC_FROM). Set by APIARY_VARIADIC_FROM: the last parameter is a pack expansion whose arity comes from the named template parameter, and each expanded slot has type ``variadic_element_type``. When emitting a per-instantiation binding, the pack slot is replaced with N copies of ``(variadic_element_type, dim_)``. .. cpp:member:: std::string variadic_from_param Name of the template parameter that supplies the pack arity. .. cpp:member:: std::string variadic_element_type Element type of each expanded pack slot. .. cpp:class:: BoundParam A single function parameter. Default-value text is captured verbatim from the AST so the emitter can re-emit it as a `py::arg("x") = ...`. .. note:: `py_type` and `default_value_py` carry the Python-stub forms — a best-effort translation populated alongside the C++ form. The .pyi emitter consumes these; the C++ emitter ignores them. .. cpp:member:: std::string name Parameter name. .. cpp:member:: std::string type C++ type as written. .. cpp:member:: std::string type_canonical Canonical (typedef-expanded) C++ type, populated alongside ``type``. Same purpose as ``BoundFunction::return_type_canonical`` — lets the .pyi emitter substitute and resolve through typedef aliases like ``RuntimeTensor`` ↔ ``GeneralRuntimeTensor>``. .. cpp:member:: std::string py_type Python-stub form of the type. .. cpp:member:: std::optional default_value Default-value text as written, or empty. .. cpp:member:: std::optional default_value_py Python-stub form of the default value. .. cpp:class:: BoundProperty A property aggregated from @getter / @setter directives on class methods. Computed by a post-IR pass (Properties.hpp) that walks BoundClass.methods. The .pyi emitter consumes this directly; the pybind11 C++ emitter still derives the same merge inline (kept separate to avoid churning the working emit code). .. cpp:member:: std::string py_name Python attribute name from @getter("name"). .. cpp:member:: std::string type Getter's C++ return type, ref/cv stripped. .. cpp:member:: std::string py_type Python form (translated from type). .. cpp:member:: std::string doc Doxygen text from getter. .. cpp:member:: bool has_setter True when a matching @setter exists. .. cpp:member:: std::size_t getter_index Index into BoundClass.methods for the getter. .. cpp:member:: std::size_t setter_index Index into BoundClass.methods for the setter. .. note:: Valid only when has_setter is true. .. cpp:class:: BoundTypedef A typedef / using-alias. Captured in docs mode so the C++ reference can emit a ``cpp:type`` declaration — which makes references to the alias (e.g. ``einsums::blas::int_t`` in a function signature) resolve instead of dangling. `underlying_type` is the aliased type as written. .. cpp:member:: std::string underlying_type The aliased type as written. .. cpp:member:: bool is_template True for alias templates. .. cpp:member:: std::vector template_param_names Template parameter names for alias templates. .. cpp:class:: Directive One parsed annotation directive. The AnnotationParser splits the raw "apiary:[:[:...]]" payload into this form so the emitter can switch on `name` cleanly. .. cpp:member:: std::string name Directive name (the ```` token). .. cpp:member:: std::vector args Directive arguments (the ```` tokens). .. cpp:class:: Module The full IR for one bound module. .. cpp:member:: std::vector classes Bound classes and structs. .. cpp:member:: std::vector functions Bound free functions. .. cpp:member:: std::vector enums Bound enums. .. cpp:member:: std::vector typedefs Bound typedefs / aliases (docs mode only). .. cpp:member:: std::vector concepts Bound concepts (docs mode only). .. cpp:member:: std::vector macros Bound macros (docs mode only). .. cpp:class:: PythonOverload One logical Python-facing entry on a free function or method. Computed by a post-IR pass (PythonOverloads.hpp) that groups raw BoundInstantiation entries according to the merge rules pybind11 expects: * NonTemplate — function has no templates; one m.def, one stub * SingleInstantiation — one instantiation with this py_name; one m.def * DtypeDispatcher — N instantiations sharing arg signature, only return type varies; collapse into one m.def taking ``dtype="..."`` kwarg * TemplateKwargsDispatcher — 2^N instantiations from APIARY_INSTANTIATE_BOOLS collapse into one m.def with N bool kwargs * OverloadSet — multiple instantiations with the same py_name that DON'T merge into a dispatcher; pybind11 picks at runtime via overload resolution .. note:: Both the C++ emitter and the .pyi emitter consume this view so the merge rules live in one place. .. cpp:member:: Kind kind Which merge rule applies to this entry. .. cpp:member:: std::string py_name Python name of this entry. .. cpp:member:: std::vector instantiation_indices Indices into the owning entity's `instantiations` vector for this entry. Empty for NonTemplate (which uses the function itself directly). .. cpp:member:: std::vector dtype_values For DtypeDispatcher: the C++ scalar type each instantiation contributes. Parallel to instantiation_indices. .. cpp:member:: std::string default_dtype For DtypeDispatcher: the picked default dtype string (e.g. "float64"). .. cpp:member:: std::vector kwarg_names For TemplateKwargsDispatcher: parallel to f.template_kwargs. .. cpp:enum-class:: Kind How the instantiations merge into a Python-facing entry. .. cpp:enumerator:: NonTemplate .. cpp:enumerator:: SingleInstantiation .. cpp:enumerator:: DtypeDispatcher .. cpp:enumerator:: TemplateKwargsDispatcher .. cpp:enumerator:: OverloadSet .. cpp:class:: SourceLocation Source position (file, line, column) of a captured declaration. .. cpp:member:: std::string file Source file path. .. cpp:member:: unsigned int line 1-based line number. .. cpp:member:: unsigned int column 1-based column number. .. cpp:function:: std::string dump(const Module &module_) Produce a deterministic textual dump of the IR. For golden-output testing and diagnostics. Phase 3's emitter produces the actual pybind11 C++; this function exists so Phase 2 has something testable. :param module_: The IR module to dump. :returns: The textual dump.