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


.. _cppapi_InstantiateParser:

=================
InstantiateParser
=================

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

.. cpp:namespace:: apiary

.. cpp:class:: InstantiateAsSpec

   Parsed result of an @instantiate_as directive.


   .. cpp:member:: std::string py_name

      The Python-facing name (e.g. "Tensor2d").


   .. cpp:member:: std::string class_name

      The leading class name extracted from the type expression.


   .. cpp:member:: std::string type_args

      The angle-bracket payload emitted between `<` and `>`.



.. cpp:class:: InstantiateSpec

   Parsed result of an @instantiate directive: a class name and its parameter groups.


   .. cpp:member:: std::string class_name

      The class being instantiated (e.g. "Tensor").


   .. cpp:member:: std::vector<ParamGroup> groups

      Ordered keyword/values groups making up the cross product.



.. cpp:class:: ParamGroup

   One keyword/values group parsed from an @instantiate directive payload.

   .. note::

      The keyword is load-bearing — Visitor::collect_instantiations matches each
      keyword against the class's actual template-parameter names and refuses to emit
      bindings on mismatch, giving a clean diagnostic if a stray macro mangled the payload.


   .. cpp:member:: std::string keyword

      Template-parameter name this group binds (e.g. "T" or "Rank").


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

      The set of values to instantiate for this keyword.



.. cpp:function:: std::vector<std::string> cross_product(const std::vector<std::vector<std::string>> &lists)

   Expands an ordered list of value lists into every cross-product combination.

   Each combination is returned as a comma-joined string ready to paste between `<` and
   `>`, e.g. ([float,double], [1,2]) -> ["float, 1", "float, 2", "double, 1", "double, 2"].

   :param lists: The ordered value lists to combine.
   :returns: Every combination as a comma-joined string.


.. cpp:function:: InstantiateSpec parse_instantiate(const std::string &payload)

   Parses the payload of an @instantiate directive into an InstantiateSpec.

   The raw text after the macro expands (and after AnnotationParser strips the prefix)
   looks like `Tensor, T(float, double, std::complex<float>), Rank(1, 2, 3)`, which is
   split into a class name and per-keyword value groups. The parser respects nested
   `<>` and `()` so commas inside template arguments don't split the wrong list.

   :param payload: The raw directive payload text.
   :returns: The parsed class name and parameter groups.


.. cpp:function:: InstantiateAsSpec parse_instantiate_as(const std::string &py_name, const std::string &type_expr)

   Parses an @instantiate_as directive into an InstantiateAsSpec.

   The directive arrives with two well-defined args from AnnotationParser: the Python
   name (e.g. "Tensor2d") and a full concrete C++ type expression (e.g. "Tensor<double, 2>").
   The type expression is split into the angle-bracket payload and the leading class name.

   :param py_name: The Python-facing name for the instantiation.
   :param type_expr: The full concrete C++ type expression.
   :returns: The parsed Python name, class name, and type arguments.


.. cpp:function:: std::string sanitize_python_name(const std::string &base, const std::string &type_args)

   Builds a Python identifier from a class base name and a comma-joined argument string.

   Non-identifier characters collapse to underscores, so `Tensor` + `std::complex<float>, 2`
   becomes `Tensor_std_complex_float_2`.

   :param base: The class base name.
   :param type_args: The comma-joined argument string.
   :returns: A valid Python identifier.