..
    ----------------------------------------------------------------------------------------------
     Copyright (c) The Einsums Developers. All rights reserved.
     Licensed under the MIT License. See LICENSE.txt in the project root for license information.
    ----------------------------------------------------------------------------------------------


.. _cppapi_Emitter:

=======
Emitter
=======

.. note::
   Generated from the C++ headers by ``apiary --emit-cpp-docs-json``.

.. cpp:namespace:: apiary

.. cpp:enum-class:: Target

   Selects which Python-binding library the emitter writes against.

   .. note::

      Pybind11 is the default, battle-tested target.

   .. note::

      Nanobind is newer, ~3-5× faster compile/binary/runtime. Mostly
      API-compatible with pybind11 but with renamed enums
      (``nb::rv_policy`` vs ``py::return_value_policy``), a different
      module macro (``NB_MODULE``), and a split STL header layout.

   .. warning::

      Nanobind has no direct ``def_buffer`` analog — buffer protocol
      directives are dropped under the nanobind target.


   .. cpp:enumerator:: Pybind11

   .. cpp:enumerator:: Nanobind


.. cpp:class:: DefReport

   Per-module tally of binding statements, for sizing `--max-defs-per-tu` before committing a budget.


   .. cpp:member:: int total_defs

      All binding statements (.def / .value / register_exception) the module
      would emit — the quantity `--max-defs-per-tu` is measured against.


   .. cpp:member:: int unit_count

      Number of indivisible emit units (one enum, one class *instantiation*,
      or one free function). Sharding splits between units, never within one.


   .. cpp:member:: int max_unit_defs

      Largest single unit's statement count. A shard can never be smaller
      than this, so a budget below it yields one oversized shard rather than
      a finer split.



.. cpp:class:: EmitOptions

   Configuration for a single emit pass.

   The emitter has two output shapes:

   .. note::

      Standalone module — emit ``PYBIND11_MODULE(<module_name>, m) { ... }``
      (or ``NB_MODULE``) producing a self-contained ``.so`` importable
      by name. Used by the standalone fixtures and goldens.

   .. note::

      Register function — emit ``void <register_function_name>(<ns>::module_ &m)
      { ... }`` which the aggregator main calls from a single
      module-macro block. Used by the einsums_add_module autogen path
      so every module ends up under one ``import einsums``.


   .. cpp:member:: std::string module_name

      module-macro arg (standalone form)


   .. cpp:member:: std::string register_function_name

      register-function symbol (aggregator form)


   .. cpp:member:: std::string source_path_for_format

      path used to discover .clang-format


   .. cpp:member:: std::vector<std::string> source_includes

      headers the bindings refer to (emitted as #include "...")


   .. cpp:member:: Target target

      Python-binding library target (defaults to Pybind11).



.. cpp:class:: ShardFile

   One generated shard: its output path and its formatted contents.


   .. cpp:member:: std::string path

   .. cpp:member:: std::string content


.. cpp:function:: std::string emit(const Module &module_, const EmitOptions &opts)

   Emit C++ binding code for `module_` and return it as a string.

   Output is post-clang-format using the project's .clang-format if one is
   found via `opts.source_path_for_format`; otherwise LLVM style is used.

   :param module_: The IR module to emit bindings for.
   :param opts: Emit configuration (output shape, target, formatting path, includes).
   :returns: The emitted, clang-formatted C++ binding source.


.. cpp:function:: std::vector<ShardFile> emit_shards(const Module &module_, const EmitOptions &opts, int max_defs, const std::string &base_output_path)

   Emit `module_`'s bindings split across several smaller TUs.

   The body is cut into contiguous, order-preserving shards so that no single
   translation unit exceeds roughly `max_defs` binding statements. Shard 0
   also carries a dispatcher (the register function, or the module macro in
   standalone form) that calls every `<base>__shard<k>` in order, so the
   ordering invariants of the single-TU path are preserved and consumers keep
   calling one symbol.

   When everything fits in a single shard the result is one file at
   `base_output_path` whose contents are byte-identical to `emit()`.

   :param module_: The IR module to emit bindings for.
   :param opts: Emit configuration (output shape, target, formatting path, includes).
   :param max_defs: Approximate per-TU budget in binding statements (> 0).
   :param base_output_path: The would-be single-TU path; shard names are derived from it as `<stem>.shard<k><ext>`.
   :returns: One entry per shard, each with its destination path and contents.


.. cpp:function:: std::vector<std::string> plan_shards(const Module &module_, const EmitOptions &opts, int max_defs, const std::string &base_output_path)

   Compute the shard output paths without emitting their contents.

   Runs the same partition as `emit_shards()` so a build system can learn the
   generated filenames at configure time. Returns `{ base_output_path }` when
   the module fits in a single TU.


.. cpp:function:: DefReport report_defs(const Module &module_, const EmitOptions &opts)

   Tally binding statements for `module_` without emitting code.

   Uses the same units and cost metric as `emit_shards()`, so the numbers are
   directly comparable to a `--max-defs-per-tu` budget.