.. Copyright Shroud Project Developers. See LICENSE file for details. SPDX-License-Identifier: (BSD-3-Clause) Reference ========= Command Line Options -------------------- .. option:: --help Show this help message and exit. .. option:: --version Show program's version number and exit. .. option:: --outdir OUTDIR Directory for output files. Defaults to current directory. .. option:: --outdir-c-fortran OUTDIR_C_FORTRAN Directory for C/Fortran wrapper output files, overrides ``--outdir``. .. option:: --outdir-python OUTDIR_PYTHON Directory for Python wrapper output files, overrides ``--outdir``. .. option:: --outdir-lua OUTDIR_LUA Directory for Lua wrapper output files, overrides ``--outdir``. .. option:: --outdir-yaml OUTDIR_YAML Directory for YAML output files, overrides ``--outdir``. .. option:: --logdir LOGDIR Directory for log files. Defaults to current directory. .. option:: --cfiles CFILES Output file with list of C and C++ files created. .. option:: --ffiles FFILES Output file with list of Fortran created. .. option:: --path PATH Colon delimited paths to search for splicer files, may be supplied multiple times to append to path. .. option:: --sitedir Return the installation directory of shroud and exit. This path can be used to find cmake/SetupShroud.cmake. .. option:: --write-helpers BASE Write files which contain the available helper functions into the files BASE.c and BASE.f. .. option:: --write-statements BASE Write a file which contain the statements tree. Used for debugging. .. option:: --write-version, --nowrite-version Write Shroud version into generated files. ``--nowrite-version`` will not write the version and is used by the testsuite to avoid changing every reference file when the version changes. .. option:: --yaml-types FILE Write a YAML file with the default types. Global Fields ------------- copyright A list of lines to add to the top of each generate file. Do not include any language specific comment characters since Shroud will add the appropriate comment delimiters for each language. classes A list of classes. Each class may have fields as detailed in `Class Fields`_. cxx_header Blank delimited list of header files which will be included in the implementation file. The order will be preserved when generating wrapper files. format Dictionary of Format fields for the library. Described in `Format Fields`_. language The language of the library to wrap. Valid values are ``c`` and ``c++``. The default is ``c++``. library The name of the library. Used to name output files and modules. The first three letters are used as the default for **C_prefix** option. Defaults to *library*. Each YAML file is intended to wrap a single library. options Dictionary of option fields for the library. Described in `Options`_ patterns Code blocks to insert into generated code. Described in `Patterns`_. splicer A dictionary mapping file suffix to a list of splicer files to read: .. code-block:: yaml splicer: c: - filename1.c - filename2.c types A dictionary of user define types. Each type is a dictionary of members describing how to map a type between languages. Described in :ref:`TypemapsAnchor` and `Types Map`_. .. _ClassFields: Class Fields ------------ cxx_header C++ header file name which will be included in the implementation file. If unset then the global *cxx_header* will be used. format Format fields for the class. Creates scope within library. Described in `Format Fields`_. declarations A list of declarations in the class. Each function is defined by `Function Fields`_ fields: A dictionary of fields used to update the typemap. options Options fields for the class. Creates scope within library. Described in `Options`_ Function Fields --------------- Each function can define fields to define the function and how it should be wrapped. These fields apply only to a single function i.e. they are not inherited. C_prototype XXX override prototype of generated C function cxx_template A list that define how each templated argument should be instantiated: .. code-block:: yaml decl: void Function7(ArgType arg) cxx_template: - instantiation: - instantiation: decl Function declaration. Parsed to extract function name, type and arguments descriptions. default_arg_suffix A list of suffixes to apply to C and Fortran functions generated when wrapping a C++ function with default arguments. The first entry is for the function with the fewest arguments and the final entry should be for all of the arguments. format Format fields for the function. Creates scope within container (library or class). Described in `Format Fields`_. fortran_generic A list of dictionaries that define generic functions which will be created. This allows different types to be passed to the function. This feature is provided by the C language which will promote arguments. However, Fortran requires that the exact type-kind-rank argument be passed. Each generic function will have a suffix which defaults to an underscore plus a sequence number. This can be changed by adding *function_suffix* for a declaration. .. code-block:: yaml decl: void GenericReal(double arg) fortran_generic: - decl: (float arg) function_suffix: suffix1 - decl: (double arg) A full example is at :ref:`GenericReal `. options Options fields for the function. Creates scope within container (library or class). Described in `Options`_ return_this If true, the C++ function returns a reference to ``this``. This feature can be used to chain calls. This idiom does not translate to C and Fortran. This can only be set on class methods which return a pointer to the class instance. Options ------- C_API_case Controls mangling of C++ library names to C names via the format field *C_name_api*. Possible values are *lower*, *upper*, *underscore*, or *preserve*. Defaults to *preserve* and will be combined with *C_prefix*. For example, **C_name_template** includes ``{C_prefix}{C_name_scope}{C_name_api}``. - preserve - Do not change the name. - lower - Convert entire name to lowercase. - upper - Convert entire name to uppercase. - underscore - Words are separated by underscore. `TypeID` to `type_id`. Often refered to as snake case. C_extern_C Set to *true* when the C++ routine is ``extern "C"``. Defaults to *false*. C_force_wrapper If *true*, always create an explicit C wrapper. When *language* is c++ a C wrapper is always created. When wrapping C, the wrapper is automatically created if there is work for it to do. For example, pre_call or post_call is defined. The user should set this option when wrapping C and the function is really a macro or a function pointer variable. This forces a function to be created allowing Fortran to use the macro or function pointer. C_line_length Control length of output line for generated C. This is not an exact line width, but is instead a hint of where to break lines. A value of 0 will give the shortest possible lines. Defaults to 72. C_shadow_result If *true*, the api attribute for the function result will be set to *capptr*, otherwise it will be set to *capsule*. In both cases, the result is passed to the C wrapper as an additional argument. With *C_shadow_result* true, a pointer to the capsule is returned as the function result. If *false*, the C wrapper is a ``void`` function. *capptr* acts more like C library functions such as ``strcpy`` which return a pointer to the result. This does not impact the C wrappers used by the Fortran wrapper. They will always used *+api(capsule)*. class_baseclass Used to define a baseclass for a struct for *wrap_struct_as=class*". The baseclase must already be defined earlier in the YAML file. It must be in the same namespace as the struct. .. example from struct.yaml .. code-block:: yaml - decl: struct Cstruct_as_class options: wrap_struct_as: class - decl: struct Cstruct_as_subclass options: wrap_struct_as: class class_baseclass: Cstruct_as_class This is equivelent to the C++ code .. code-block:: c++ class Cstruct_as_class; class Cstruct_as_subclass : public Cstruct_as_class; The corresponding Fortran wrapper will have .. code-block:: fortran type cstruct_as_class type(STR_SHROUD_capsule_data) :: cxxmem end type cstruct_as_class type, extends(cstruct_as_class) :: cstruct_as_class end type cstruct_as_subclass class_ctor Indicates that this function is a constructor for a struct. The value is the name of the struct. Useful for *wrap_struct_as=class* when used with C. Defaults attribute *+owner(caller)*. .. code-block:: yaml - decl: struct Cstruct_as_class { int x1; int y1; }; options: wrap_struct_as: class - decl: Cstruct_as_class *Create_Cstruct_as_class(void) options: class_ctor: Cstruct_as_class class_method Indicates that this function is a method for a struct. CXX_standard C++ standard. Defaults to *2011*. See *nullptr*. debug Print additional comments in generated files that may be useful for debugging. Useful to help identify which statement groups Shroud is using to create the wrapper. Defaults to *false*. If a function does not require a Fortran wrapper and can be called via an interface only, the wrapper will still be generated but within an ``#if 0`` / ``#endif`` block requiring the use of the C preprocessor to compile the Fortran file. debug_index Print index number of function and relationships between C and Fortran wrappers in the wrappers and json file. The number changes whenever a new function is inserted and introduces lots of meaningless differenences in the test answers. This option is used to avoid the clutter and is intended for developers. If needed for debugging, then set to *true*. **debug** must also be *true*. Defaults to *false*. default_owner Used to default the *owner* attribute. Used when *deref* is *pointer* or *raw*. Defaults to *library*. doxygen If True, create doxygen comments. flatten_namespace Do not create a new Fortran or Python module for the namespace. Instead add the declarations into the parent namespace. The names will be mangled to include namespace so it is still possible to have duplicate names. F_API_case Controls mangling of C++ library names to Fortran names via the format field *F_name_api*. Possible values are *lower*, *upper*, *underscore*, or *preserve*. Defaults to *underscore* to convert ``CamelCase`` to ``camel_case``. Since Fortran is case insensitive, users are not required to respect the case of the C++ name. Using *underscore* makes the names easier to read regardless of the case. See **C_API_case** for a description of the options. F_assumed_rank_min Minimum rank of argument with assumed-rank. Defaults to 0 (scalar). F_assumed_rank_max Maximum rank of argument with assumed-rank. Defaults to 7. F_blanknull Default value of attribute *+blanknull* for ``const char *`` arguments. This attribute will convert blank Fortran strings to a ``NULL`` pointer. F_CFI Use the C Fortran Interface provided by *Futher Interoperability with C* from Fortran 2018 (initially defined in TS29113 2012). F_assignment_api Declare the API to be used when creating a function which overloads the assignment operator. basic The assignment operator will not be overloaded. swig Use code derived from :program:`swig`. rca Reference counting architecture. Reqires a Fortran compiler which fully supports ``FINAL``. Added as a format field with a prefix of *option_*. To be used to help select helpers. F_create_bufferify_function Defaults to *true* which will create a C wrapper if necessary for the Fortran wrapper to call. If a splicer is provided for the function, the Fortran wrapper may not need to call any C wrapper. In this case setting to *false* will prevent the C bufferify wrapper from being created. F_create_generic Controls creation of a generic interface. It defaults to *true* for most cases but will be set to *False* if a function is templated on the return type since Fortran does not distinguish generics based on return type (similar to overloaded functions based on return type in C++). .. XXX should also be set to false when the templated argument in cxx_template is part of the implementation and not the interface. F_default_args Decide how to handle C++ default argument functions. See :ref:`DefaultArguments`. generic Create a wrapper for each variation from all arguments to no arguments defaulted. In Fortran, create a generic interface. optional Make each default argument as a Fortran ``OPTIONAL`` argument. require Require all arguments to be provided to the wrapper. F_deref_arg_array Used with *intent(out)* or *intent(inout)* arguments which return a pointer to a pointer or a reference ex ``int**`` or ``int*&``. And where the *dimension* attribute is set. Defaults to ``pointer``. F_deref_arg_character Used with *intent(out)* or *intent(inout)* arguments which return a pointer to a pointer or a reference ex ``char **`` or ``std::string*&``. Defaults to ``copy``. F_deref_arg_implied_array Used with *intent(out)* or *intent(inout)* arguments of types such as ``std::vector``. Defaults to ``copy``. F_deref_arg_scalar Used with *intent(out)* or *intent(inout)* arguments which return a pointer to a pointer or a reference ex ``int**`` or ``int*&``. And where *dimension* attribute is not set. Defaults to ``pointer``. F_deref_func_array Used with single indirection to a POD type, ex ``int *`` where *dimension* attribute is set. Defaults to ``pointer``. F_deref_func_character Used with ``char *`` and ``std::string`` function results. Multiple indirections default to ``raw``. Defaults to ``allocatable``. F_deref_func_implied_array Used with types such as ``std::vector``. Defaults to ``allocatable`` F_deref_func_scalar Used with single indirection to a POD type, ex ``int *`` where *dimension* attribute is not set. Defaults to ``pointer``. F_enum_type C type used to represent enumerations in the Fortran wrapper. Defaults to ``int``. F_line_length Control length of output line for generated Fortran. This is not an exact line width, but is instead a hint of where to break lines. A value of 0 will give the shortest possible lines. Defaults to 72. F_force_wrapper If *true*, always create an explicit Fortran wrapper. If *false*, only create the wrapper when there is work for it to do; otherwise, call the C function directly. For example, a function which only deals with native numeric types does not need a wrapper since it can be called directly by defining the correct interface. The default is *false*. F_standard The fortran standard. Defaults to *2003*. This effects the ``mold`` argument of the ``allocate`` statement. F_return_fortran_pointer Use ``c_f_pointer`` in the Fortran wrapper to return a Fortran pointer instead of a ``type(C_PTR)`` in routines which return a pointer. It does not apply to ``char *``, ``void *``, and routines which return a pointer to a class instance. Defaults to *true*. F_string_len_trim For each function with a ``std::string`` argument, create another C function which accepts a buffer and length. The C wrapper will call the ``std::string`` constructor, instead of the Fortran wrapper creating a ``NULL`` terminated string using ``trim``. This avoids copying the string in the Fortran wrapper. Defaults to *true*. F_struct_getter_setter If true, a getter and setter will be created for struct members which are a pointer to native type. This allows a Fortran pointer to be used with the field instead of having to deal with the ``type(C_PTR)`` directly. Default to *true* F_trim_char_in Controls code generation for ``const char *`` arguments. If *True*, the Fortran wrapper calls ``TRIM`` on the argument and concatenates ``C_NULL_CHAR``. If *False*, it will be done in C. If the only need for the C wrapper is to null-terminate a string (wrapping a C library and no other argument requires a wrapper), then the C wrapper can be avoid by moving the null-termination action to Fortran. Default is *True*. .. XXX how to decide length of pointer This sets the meta-attribute *ftrim_char_in* literalinclude Write some text lines which can be used with Sphinx's literalinclude directive. This is used to insert the generated code into the documentation. Can be applied at the top level or any declaration. Setting *literalinclude* at the top level implies *literalinclude2*. literalinclude2 Write some text lines which can be used with Sphinx's literalinclude directive. Only effects some entities which do not map to a declarations such as some helper functions or types. Only effective at the top level. Each Fortran interface will be enclosed in its own ``interface`` block. This is to provide the interface context when code is added to the documentation. LUA_API_case Controls mangling of C++ library names to Lua names via the format field *LUA_name_api*. Possible values are *lower*, *upper*, *underscore*, or *preserve*. Defaults to *preserve*. PY_create_generic Controls creation of a multi-dispatch function with overloaded/templated functions. It defaults to *true* for most cases but will be set to *False* if a function is templated on the return type since Fortran does not distiuguish generics based on return type (similar to overloaded functions based on return type in C++). .. XXX should also be set to false when the templated argument in cxx_template is part of the implementation and not the interface. PY_write_helper_in_util When *True* helper functions will be written into the utility file *PY_utility_filename*. Useful when there are lots of classes since helper functions may be duplicated in several files. The value of format *PY_helper_prefix* will have *C_prefix* append to create names that are unique to the library. Defaults to *False*. return_scalar_pointer Determines how to treat a function which returns a pointer to a scalar (it does not have the *dimension* or *rank* attribute). **scalar** return as a scalar or **pointer** to return as a pointer. This option does not effect the C or Fortran wrapper. For Python, **pointer** will return a NumPy scalar. Defaults to *pointer*. .. default_attr_deref .. bufferify show_splicer_comments If ``true`` show comments which delineate the splicer blocks; else, do not show the comments. Only the global level option is used. wrap_class_as Defines how a ``class`` should be wrapped. If *class*, wrap using a shadow type. If *struct*, wrap the same as a ``struct``. Default is *class*. wrap_struct_as Defines how a ``struct`` should be wrapped. If *struct*, wrap a struct as a Fortran derived-type. If *class*, wrap a struct the same as a class using a shadow type. Default is *struct*. wrap_c If *true*, create C wrappers. Defaults to *true*. Will not have an effect if ``language=c``. wrap_fortran If *true*, create Fortran wrappers. Defaults to *true*. wrap_python If *true*, create Python wrappers. Defaults to *false*. wrap_lua If *true*, create Lua wrappers. Defaults to *false*. .. _reference_option_templates: Option Templates ^^^^^^^^^^^^^^^^ Templates are set in options then expanded to assign to the format dictionary to create names in the generated code. C_capsule_data_type_template C_enum_type_template Name of enumeration in C wrapper. ``{C_prefix}{C_name_scope}{enum_name}`` C_enum_member_template Name of enumeration member in C wrapper. ``{C_prefix}{C_name_scope}{enum_member_name}`` C_header_filename_class_template ``wrap{file_scope}.{C_header_filename_suffix}`` C_header_filename_library_template ``wrap{library}.{C_header_filename_suffix}`` C_header_filename_namespace_template ``wrap{scope_file}.{C_header_filename_suffix}`` C_impl_filename_class_template ``wrap{file_scope}.{C_impl_filename_suffix}`` C_impl_filename_library_template ``wrap{library}.{C_impl_filename_suffix}`` C_impl_filename_namespace_template ``wrap{scope_file}.{C_impl_filename_suffix}`` C_memory_dtor_function_template Name of function used to delete memory allocated by C or C++. defaults to ``{C_prefix}SHROUD_memory_destructor``. C_name_template ``{C_prefix}{C_name_scope}{C_name_api}{function_suffix}{f_c_suffix}{template_suffix}`` C_name_shared_api_template Name of the smart pointer object created by group *smart_pointer*. The format field *smart_pointer* is taken from the Typemap for the smart pointer. ``{C_name_api}_{smart_pointer}`` C_name_typedef_template ``{C_prefix}{C_name_scope}{typedef_name}`` F_C_name_template ``{F_C_prefix}{F_name_scope}{F_name_api}{function_suffix}{f_c_suffix}{template_suffix}`` F_abstract_interface_argument_template The name of arguments for an abstract interface used with function pointers. Defaults to ``{F_name_api}_{argname}`` where *argname* is the name of the function argument. see :ref:`DeclAnchor_Function_Pointers`. F_abstract_interface_subprogram_template The name of the abstract interface subprogram which represents a function pointer. Defaults to ``arg{index}`` where *index* is the 0-based argument index. See :ref:`DeclAnchor_Function_Pointers`. F_array_type_template ``{C_prefix}SHROUD_array`` F_capsule_data_type_template Name of the derived type which is the ``BIND(C)`` equivalent of the struct used to implement a shadow class (**c_capsule_data_type**). All classes use the same derived type. Defaults to ``{C_prefix}SHROUD_capsule_data``. F_capsule_type_template ``{C_prefix}SHROUD_capsule`` F_derived_name_template Defaults to ``{F_name_api}``. F_enum_member_template Name of enumeration member in Fortran wrapper. ``{F_name_scope}{enum_member_lower}`` Note that *F_enum_template* does not exist since only the members are in the Fortran code, not the enum name itself. F_name_generic_template ``{F_name_api}`` F_impl_filename_library_template ``wrapf{library_lower}.{F_filename_suffix}`` F_name_impl_template ``{F_name_scope}{F_name_api}{function_suffix}{template_suffix}`` F_module_name_library_template ``{library_lower}_mod`` F_module_name_namespace_template ``{file_scope}_mod`` F_name_enum_template ``{F_name_scope}{F_name_api}`` F_name_function_template ``{F_name_api}{function_suffix}{template_suffix}`` F_name_typedef_template ``{F_name_scope}{F_name_api}`` LUA_class_reg_template Name of `luaL_Reg` array of function names for a class. ``{LUA_prefix}{cxx_class}_Reg`` LUA_ctor_name_template Name of constructor for a class. Added to the library's table. ``{cxx_class}`` LUA_header_filename_template ``lua{library}module.{LUA_header_filename_suffix}`` LUA_metadata_template Name of metatable for a class. ``{cxx_class}.metatable`` LUA_module_filename_template ``lua{library}module.{LUA_impl_filename_suffix}`` LUA_module_reg_template Name of `luaL_Reg` array of function names for a library. ``{LUA_prefix}{library}_Reg`` LUA_name_impl_template Name of implementation function. All overloaded function use the same Lua wrapper so *function_suffix* is not needed. ``{LUA_prefix}{C_name_scope}{LUA_name_api}`` LUA_name_template Name of function as know by Lua. All overloaded function use the same Lua wrapper so *function_suffix* is not needed. ``{function_name}`` LUA_userdata_type_template ``{LUA_prefix}{cxx_class}_Type`` LUA_userdata_member_template Name of pointer to class instance in userdata. ``self`` PY_array_arg How to wrap arrays - numpy or list. Applies to function arguments and to structs when **PY_struct_arg** is *class* (struct-as-class). Defaults to *numpy*. Added to fmt for functions. Useful for *c_helpers* in statements. .. code-block:: text c_helper="get_from_object_{c_type}_{PY_array_arg}", PY_module_filename_template ``py{library}module.{PY_impl_filename_suffix}`` PY_header_filename_template ``py{library}module.{PY_header_filename_suffix}`` PY_utility_filename_template ``py{library}util.{PY_impl_filename_suffix}`` PY_PyTypeObject_template ``{PY_prefix}{cxx_class}_Type`` PY_PyObject_template ``{PY_prefix}{cxx_class}`` PY_member_getter_template Name of descriptor getter method for a class variable. ``{PY_prefix}{cxx_class}_{variable_name}_getter`` PY_member_setter_template Name of descriptor setter method for a class variable. ``{PY_prefix}{cxx_class}_{variable_name}_setter`` PY_member_object_template Name of struct member of type `PyObject *` which contains the data for member pointer fields. ``{variable_name}_obj``. PY_name_impl_template ``{PY_prefix}{function_name}{function_suffix}{template_suffix}`` PY_numpy_array_capsule_name_template Name of ``PyCapsule object`` used as base object of NumPy arrays. Used to make sure a valid capsule is passed to *PY_numpy_array_dtor_function*. ``{PY_prefix}array_dtor`` PY_numpy_array_dtor_context_template Name of ``const char * []`` array used as the *context* field for *PY_numpy_array_dtor_function*. ``{PY_prefix}array_destructor_context`` PY_numpy_array_dtor_function_template Name of *destructor* in ``PyCapsule`` base object of NumPy arrays. ``{PY_prefix}array_destructor_function`` PY_struct_array_descr_create_template Name of C/C++ function to create a ``PyArray_Descr`` pointer for a structure. ``{PY_prefix}{cxx_class}_create_array_descr`` PY_struct_arg How to wrap structs - numpy, list or class. Defaults to *numpy*. PY_struct_array_descr_variable_template Name of C/C++ variable which is a pointer to a ``PyArray_Descr`` variable for a structure. ``{PY_prefix}{cxx_class}_array_descr`` PY_struct_array_descr_name_template Name of Python variable which is a ``numpy.dtype`` for a struct. Can be used to create instances of a C/C++ struct from Python. ``np.array((1,3.14), dtype=tutorial.struct1_dtype)`` ``{cxx_class}_dtype`` PY_type_filename_template ``py{file_scope}type.{PY_impl_filename_suffix}`` PY_type_impl_template Names of functions for type methods such as ``tp_init``. ``{PY_prefix}{cxx_class}_{PY_type_method}{function_suffix}{template_suffix}`` PY_use_numpy Allow NumPy arrays to be used in the module. For example, when assigning to a struct-as-class member. SH_class_getter_template Name of generated getter function for class members. The wrapped name will be mangled futher to distinguish scope. Defaults to ``get_{wrapped_name}``. SH_class_setter_template Name of generated setter function for class members. The wrapped name will be mangled futher to distinguish scope. Defaults to ``set_{wrapped_name}``. SH_struct_getter_template Name of generated getter function for struct members. The wrapped name will be mangled futher to distinguish scope. Defaults to ``{struct_name}_get_{wrapped_name}``. SH_struct_setter_template Name of generated setter function for struct members. The wrapped name will be mangled futher to distinguish scope. Defaults to ``{struct_name}_set_{wrapped_name}``. YAML_type_filename_template Default value for global field YAML_type_filename ``{library_lower}_types.yaml`` Format Fields ------------- Each scope (library, class, function) has its own format dictionary. If a value is not found in the dictionary, then the parent scopes will be recursively searched. Library ^^^^^^^ C_array_type Name of structure used to store metadata about an array such as its address and size. Defaults to *{C_prefix}SHROUD_array*. C_bufferify_suffix Suffix appended to generated routine which pass strings as buffers with explicit lengths. Defaults to *_bufferify* c_capsule_data_type Name of struct used to share memory information with Fortran. Defaults to *SHROUD_capsule_data*. C_header_filename Name of generated header file for the library. Defaulted from expansion of option *C_header_filename_library_template*. C_header_filename_suffix Suffix added to C header files. Defaults to ``h``. Other useful values might be ``hh`` or ``hxx``. C_header_utility A header file with shared Shroud internal typedefs for the library. Default is ``types{library}.{C_header_filename_suffix}``. C_impl_filename Name of generated C++ implementation file for the library. Defaulted from expansion of option *C_impl_filename_library_template*. C_impl_filename_suffix: Suffix added to C implementation files. Defaults to ``cpp``. Other useful values might be ``cc`` or ``cxx``. C_impl_utility A implementation file with shared Shroud helper functions. Typically routines which are implemented in C but called from Fortran via ``BIND(C)``. The must have global scope. Default is ``util{library}.{C_header_filename_suffix}``. C_local Prefix for C compatible local variable. Defaults to *SHC_*. C_memory_dtor_function Name of function used to delete memory allocated by C or C++. C_name_api Root name that is used to create various names in the C API. Defaulted by the **C_API_case** option with values *lower*, *upper*, *underscore*, or *preserve*. If set explicitly then **C_API_case** will have no effect. May be blank for namespaces to avoid adding the name to *C_name_scope*. C_name_assign Used to create name of method that controls assignment of shadow types. The assignment overload function created by Shroud is used to help manage C++ memory. This format field is uses as *C_name_api* in the option **C_name_template** while *function_suffix* is set the the right-hand side *cxx_class*. This creates names such as: .. code-block:: fortran interface assignment (=) module procedure object_assign_Object module procedure object_shared_assign_Object_shared module procedure object_shared_assign_Object module procedure object_weak_assign_Object_weak module procedure object_weak_assign_Object_shared end interface C_name_scope Underscore delimited name of namespace, class, enumeration. Used to *flatten* nested C++ names into global C identifiers. Ends with trailing underscore to allow the next scope to be appended. Does not include toplevel *namespace*. For example, **C_name_template** includes ``{C_prefix}{C_name_scope}{C_name_api}``. *C_name_scope* will replace *class_name* with the instantiated *class_name*. which will contain a template arguments. This is a computed using *C_name_api* and should not be set explicitly. C_result The name of the C wrapper's result variable. It must not be the same as any of the routines arguments. It defaults to *rv*. c_temp Prefix for wrapper temporary working variables. Defaults to *SHT_*. C_this Name of the C object argument. Defaults to ``self``. It may be necessary to set this if it conflicts with an argument name. CXX_local Prefix for C++ compatible local variable. Defaults to *SHCXX_*. CXX_this Name of the C++ object pointer set from the *C_this* argument. Defaults to ``SH_this``. file_scope Used in template options to set output filenames. F_array_type Name of derived type used to store metadata about an array such as its address and size. Default value from option *F_array_type_template* which defaults to *{C_prefix}SHROUD_array*. f_capsule_data_type Name of derived type used to share memory information with C or C++. Member of *F_array_type*. Default value from option *F_capsule_data_type_template* which defaults to *{C_prefix}SHROUD_capsule_data*. Each class has a similar derived type, but with a different name to enforce type safety. F_capsule_delete_function Name of type-bound function of *F_capsule_type* which will delete the memory in the capsule. Defaults to *SHROUD_capsule_delete*. F_capsule_final_function Name of function used was ``FINAL`` of *F_capsule_type*. The function is used to release memory allocated by C or C++. Defaults to *SHROUD_capsule_final*. F_capsule_type Name of derived type used to release memory allocated by C or C++. Default value from option *F_capsule_type_template* which defaults to *{C_prefix}SHROUD_capsule*. Contains a *F_capsule_data_type*. F_derived_member A *F_capsule_data_type* use to reference C++ memory. Defaults to *cxxmem*. F_derived_member_base The *F_derived_member* for the base class of a class. Only single inheritance is support via the ``EXTENDS`` keyword in Fortran. F_filename_suffix Suffix added to Fortran files. Defaults to ``f``. Other useful values might be ``F`` or ``f90``. F_module_name Name of module for Fortran interface for the library. Defaulted from expansion of option *F_module_name_library_template* which is **{library_lower}_mod**. Then converted to lower case. F_name_api Root name that is used to create various names in the Fortran API. Controlled by the **F_API_case** option with values *lower*, *upper*, *underscore* or *preserve*. Used with options **templates F_C_name_template**, **F_name_impl_template**, **F_name_function_template**, **F_name_generic_template**, **F_abstract_interface_subprogram_template**, **F_derived_name_template**, **F_name_enum_template**, **F_name_typedef_template**. F_name_assign Name of method that controls assignment of shadow types. Used to help with reference counting. F_name_scope Underscore delimited name of namespace, class, enumeration. Used with creating names in Fortran. Ends with trailing underscore to allow the next scope to be appended. Does not include toplevel *namespace*. This is a computed using *F_name_api* and should not be set explicitly. F_impl_filename Name of generated Fortran implementation file for the library. Defaulted from expansion of option *F_impl_filename_library_template*. F_result The name of the Fortran wrapper's result variable. It must not be the same as any of the routines arguments. It defaults to *SHT_rv* (Shroud temporary return value). F_this Name of the Fortran argument which is the derived type which represents a C++ class. It must not be the same as any of the routines arguments. Defaults to ``obj``. file_scope Used in filename creation to identify library, namespace, class. i_prefix Prefix added to name of generated Fortran interface for C routines. Defaults to **c_**. library The value of global **field** *library*. library_lower Lowercase version of *library*. library_upper Uppercase version of *library*. LUA_header_filename_suffix Suffix added to Lua header files. Defaults to ``h``. Other useful values might be ``hh`` or ``hxx``. LUA_impl_filename_suffix Suffix added to Lua implementation files. Defaults to ``cpp``. Other useful values might be ``cc`` or ``cxx``. LUA_module_name Name of Lua module for library. ``{library_lower}`` LUA_name_api Root name that is used to create various names in the Lua API. Defaulted by the **LUA_API_case** option with values *lower*, *upper*, *underscore*, or *preserve*. If set explicitly then **LUA_API_case** will have no effect. LUA_prefix Prefix added to Lua wrapper functions. LUA_result The name of the Lua wrapper's result variable. It defaults to *rv* (return value). LUA_state_var Name of argument in Lua wrapper functions for lua_State pointer. namespace_scope The current C++ namespace delimited with ``::`` and a trailing ``::``. Used when referencing identifiers: ``{namespace_scope}id``. nullptr Set to `NULL` or `nullptr` based on option *CXX_standard*. Always `NULL` when *language* is C. PY_ARRAY_UNIQUE_SYMBOL C preprocessor define used by NumPy to allow NumPy to be imported by several source files. PY_header_filename_suffix Suffix added to Python header files. Defaults to ``h``. Other useful values might be ``hh`` or ``hxx``. PY_impl_filename_suffix Suffix added to Python implementation files. Defaults to ``cpp``. Other useful values might be ``cc`` or ``cxx``. PY_local Variable prefix used with statement field *local*. Defaults to ``SH_``. PY_module_init Name of module and submodule initialization routine. library and namespaces delimited by ``_``. Setting *PY_module_name* will update *PY_module_init*. PY_module_name Name of generated Python module. Defaults to library name or namespace name. PY_module_scope Name of module and submodule initialization routine. library and namespaces delimited by ``.``. Setting *PY_module_name* will update *PY_module_scope*. PY_name_impl Name of Python wrapper implemenation function. Each class and namespace is implemented in its own function with file static functions. There is no need to include the class or namespace in this name. Defaults to *{PY_prefix}{function_name}{function_suffix}*. PY_prefix Prefix added to Python wrapper functions. PY_result The name of the Python wrapper's result variable. It defaults to *SHTPy_rv* (return value). If the function returns multiple values (due to *intent(out)*) and the function result is already an object (for example, a NumPy array) then **PY_result** will be **SHResult**. file_scope library plus any namespaces. The namespaces listed in the top level variable *namespace* is not included in the value. It is assumed that *library* will be used to generate unique names. Used in creating a filename. stdlib Name of C++ standard library prefix. blank when *language=c*. ``std::`` when *language=c++*. YAML_type_filename Output filename for type maps for classes. Enumeration ^^^^^^^^^^^ cxx_value Value of enum from YAML file. enum_name enum_member_lower enum_member_name enum_member_upper flat_name Scoped name of enumeration mapped to a legal C identifier. Scope operator `::` replaced with `_`. Used with *C_enum_template*. C_enum_member C name for enum member. Computed from option *C_enum_member_template*. C_enum_type The name of the generated C_enum when wrapping a C++ library. Used with *C_enum_type_template*. C_value Evalued value of enumeration. If the enum does not have an explict value, it will not be present. C_scope_name Set to *flat_name* with a trailing undersore. Except for non-scoped enumerations in which case it is blank. Used with *C_enum_member_template*. Does not include the enum name in member names for non-scoped enumerations. F_scope_name Value of *C_scope_name* converted to lower case. Used with *F_enum_member_template*. F_enum_member Fortran name for enum member. Computed from option *F_enum_member_template*. F_enum_kind Fortran ``INTEGER`` kind used to represent enumerations. F_name_typedef Default from ``F_name_enum_template``. F_value Evalued value of enumeration. If the enum does not have an explict value, it is the previous value plus one. Class ^^^^^ c_arglist An array of format fields for the C wrapper of the function and its arguments. Entry 0 is the function, 1 is the first argument, and so on. Allows the statement group of an argument to access another argument's format fields to coordinate behavior. For example, ``c_arglist[1].c_local_cxx``. C_header_filename Name of generated header file for the class. Defaulted from expansion of option *C_header_filename_class_template*. C_impl_file Name of generated C++ implementation file for the library. Defaulted from expansion of option *C_impl_filename_class_template*. baseclass An instance of ``BaseClassFormat`` to allow access to the base class' *typemap*. Used in format fields as ``{baseclass.cxx_type}``. f_arglist An array of format fields for the Fortran wrapper of the function and its arguments. Entry 0 is the function, 1 is the first argument, and so on. Allows the statement group of an argument to access another argument's format fields to coordinate behavior. For example, ``c_arglist[1].c_local_cxx``. F_derived_name Name of Fortran derived type for this class. Computed from option *F_derived_name_template*. F_name_associated Name of method to report if shadow type is associated. If the name is blank, no function is generated. F_name_final Name of function used in ``FINAL`` for a class. F_name_instance_get Name of method to get ``type(C_PTR)`` instance pointer from wrapped class. Defaults to *get_instance*. If the name is blank, no function is generated. F_name_instance_set Name of method to set ``type(C_PTR)`` instance pointer in wrapped class. Defaults to *set_instance*. If the name is blank, no function is generated. F_name_shared_use_count Name of ``use_count`` method added to ``std::shared_ptr`` when group *smart_pointer* is set on a class. If the name is blank, no function is generated. cxx_class The name of the C++ class from the YAML input file. Used in generating names for C and Fortran and filenames. When the class is templated, it will be converted to a legal identifier by adding the *template_suffix* or a sequence number. When *cxx_class* is set in the YAML file for a class, its value will be used in *class_scope*, *C_name_scope*, *F_name_scope* and *F_derived_name*. cxx_type The namespace qualified name of the C++ class, including information from *template_arguments*, ex. ``std::vector``. Same as *cxx_class* if *template_arguments* is not defined. Used in generating C++ code. class_scope Used to to access class static functions. Blank when not in a class. ``{cxx_class}::`` C_prefix Prefix for C wrapper functions. The prefix helps to ensure unique global names. Defaults to the first three letters of *library_upper*. PY_helper_prefix Prefix added to helper functions for the Python wrapper. This allows the helper functions to have names which will not conflict with any wrapped routines. When option *PY_write_helper_in_util* is *True*, *C_prefix* will be prefixed to the value to ensure the helper functions will not conflict with any routines in other wrapped libraries. PY_type_obj Name variable which points to C or C++ memory. Defaults to *obj*. PY_type_dtor Pointer to information used to release memory. PY_PyTypeObject Name of `PyTypeObject` variable for a C++ class. Computed from option *PY_PyTypeObject*. PY_PyTypeObject_base The name of `PyTypeObject` variable for base class of C++ class. Only single inheritance is support via the tp_base field of `PyTypeObject` struct. Function ^^^^^^^^ C_call_function Expression to call the function. ``{CXX_this_call}{function_name}{CXX_template}(\t{C_call_list})`` C_call_list Comma delimited list of function arguments. .. uses tabs C_name Name of the C wrapper function. Defaults to evaluation of option *C_name_template*. C_prototype C prototype for the function. Take from the statements field *c_prototype*. .. uses tabs C_return_type Return type of the C wrapper function. If the **return_this** field is true, then set to ``void``. Set to function's return type. CXX_template The template component of the function declaration. ``<{type}>`` CXX_this_call How to call the function. ``{CXX_this}->`` for instance methods and blank for library functions. F_arg_c_call Comma delimited arguments to call C function from Fortran. .. uses tabs F_arguments Set from option *F_arguments* or generated from YAML decl. .. uses tabs F_C_arguments Argument names to the ``bind(C)`` interface for the subprogram. Arguments are tab delimited to aid in creating continuations. F_C_call The name of the C function to call. Usually *F_C_name*, but it may be different if calling a generated routine. This can be done for functions with string arguments. F_C_name Name of the Fortran ``BIND(C)`` interface for a C function. Defaults to the lower case version of *F_C_name_template*. F_C_pure_clause TODO F_C_result_clause Result clause for the ``bind(C)`` interface. F_C_subprogram ``subroutine`` or ``function`` for the ``bind(C)`` interface. The C wrapper funtion may be different Fortran wrapper function since some function results may be converted into arguments. F_pure_clause For non-void function, ``pure`` if the *pure* annotation is added or the function is ``const`` and all arguments are ``intent(in)``. F_name_function The name of the *F_name_impl* subprogram when used as a type procedure. Defaults to evaluation of option *F_name_function_template*. F_name_generic The generic name for a function. Set with option *class_ctor* or *F_create_generic*. Defaults to evaluation of option *F_name_generic_template*. F_name_impl Name of the Fortran implementation function. Defaults to evaluation of option *F_name_impl_template* . F_result_clause `` result({F_result})`` for functions. Blank for subroutines. f_c_suffix Set by Shroud to allow the Fortran wrapper to call a C wrapper with additional mangling. Usually set to the value of *C_bufferify_suffix* or *C_cfi_suffix*. function_name Name of function in the YAML file. function_suffix String append to a generated function name. Useful to distinguish overloaded function and functions with default arguments. Defaults to a sequence number with a leading underscore (e.g. `_0`, `_1`, ...) but can be set by using the function field *function_suffix*. Multiple suffixes may be applied -- overloaded with default arguments. LUA_name Name of function as known by LUA. Defaults to evaluation of option *LUA_name_template*. template_suffix String which is append to the end of a generated function names to distinguish template instatiations. Default values generated by Shroud will include a leading underscore. i.e ``_int`` or ``_0``. Argument ^^^^^^^^ attr_len The value of the *len* attribute. It willl be evalued in the C wrapper. Defaults to 0 to indicate no length given. c_blanknull Used as argument to ``ShroudStrAlloc`` to determine if a blank string, trimmed length is 0, should be a NULL pointer instead of an empty C string -- ``'\0'``. Set via attribute *+blanknull* on a ``const char *`` argument. Should be ``0`` or ``1``. c_const ``const`` if argument has the *const* attribute. c_deref Used to dereference *c_var*. ``*`` if it is a pointer, else blank. c_helper_* Helper name for a function. Each name in statements *helper* field will create a format name which starts with *c_helper_* and end with the helper's *c_fmtname* field. It will contain the name of the C function for the helper. Used by statements *c_pre_call* and *c_post_call* statements. c_type The C type of the argument. c_var The C name of the argument. .. XXX these fields are creatd by the *temps* or *local* statements field. .. c_var_len Function argument generated from the *len* annotation. Used with char/string arguments. Set from option **C_var_len_template**. .. c_var_size Function argument generated from the *size* annotation. Used with array/std::vector arguments. Set from option **C_var_size_template**. .. c_var_trim c_local_trim Function argument generated from the *len_trim* annotation. Used with char/string arguments. Set from option **C_var_trim_template**. ci_type The C type of the argument for the Fortran interface. Used with enumerations and option *F_enum_type*. cxx_abstract_decl Includes the declaration and any declarators. For example, ``double *``. .. used with c_to_cxx static_cast cxx_addr Syntax to take address of argument. ``&`` or blank. cxx_nonconst_ptr A non-const pointer to *cxx_addr* using `const_cast` in C++ or a cast for C. cxx_member Syntax to access members of *cxx_var*. cxx_T The template parameters for templated arguments. ``std::vector<{cxx_T}>`` cxx_type The C++ type of the argument. cxx_var Name of the C++ variable. f_abstract_interface Name of abstract interface created for a function pointer. f_deref_attr The Fortran attribute when the *deref* attribute is *alloctable* or *pointer*. It is used in declaration of Fortran arguments. Possible values are ``, allocatable`` or ``, pointer``. Used as ``{f_type}{f_deref_attr} ::``. f_intent The value of the intent metaattribute. Converted to uppercase. Used with argument declarations: ``{f_type}, intent({f_intent})``. If the intent is *none*, the Fortran wrapper will not compile. Instead use *f_intent_attr*. f_intent_attr The value of the *intent* metaattribute converted into a Fortran attribute to be used in the Fortran wrapper. ex ``, intent(IN)``. Used with argument declarations: ``{f_type}{f_intent_attr} ::``. If *intent* is *none*, the format field will be blank. When a subroutine is converted into a function, it is necessary to explicitly set this attribute to ``, intent(OUT)``. f_kind The name of a parameter from *f_module_name* required to define *f_type*. Defaults to blank. f_module_name The name of the module required by *f_type*. Contains *f_kind*. Set from *typemap.f_module_name*. It defaults to ``-f_module_name-``, which is an illegal Fortran module name. Often used in statement field *f_module*. f_optional_attr The value of the *optional* metaattribute converted into a Fortran attribute. ex ``, optional``. Used with argument declarations: ``{f_type}{f_optional_attr} ::``. If *optional* is *False*, the format field will be blank. f_target_attr Can be set to ``, target`` to add the ``target`` atribute to a declaration via statement group *f_mixin_declare-fortran-arg*. f_type The Fortran type of the argument. Derived from the ``typemap.f_type``. If the attribute *+assumedtype* is set, then it will be ``type(*)``. `char` and `string` types also factor attribute *len* and *deref* into the value. f_value_attr The value of the *value* metaattribute converted into a Fortran attribute. ex ``, value``. Used with argument declarations: ``{f_type}{f_value_attr} ::``. If *value* is *False*, the format field will be blank. i_dimension Dimension of interface argument. ``char *`` and ``std::string`` become an array of ``CHAR`` with a dimension of ``(*)``. i_intent The intent of the argument from the *intent* attribute to be used with the Fortran interface. See *f_intent*. i_intent_attr The value of the *intent* metaattribute converted into a Fortran attribute to be used with the Fortran interface. ex ``, intent(IN)``. See *f_intent_attr*. The Fortran wrapper may pass the result as an argument to the C wrapper which will require explicitly setting the this format field. i_kind The bind(C) interface of the argument. Derived from the ``typemap.i_type`` for the argument. If it is not set, then use ``typemap.f_type``. i_module_name The bind(C) interface of the argument. Derived from the ``typemap.i_module_name`` for the argument. If it is not set, then use ``typemap.f_type`` if it is set. This makes it possible to define ``f_module_name`` as ``iso_c_binding`` and have it used with the interface as well. i_result_clause Added at the end of a function declaration to define the result variable. i_result_var Use in the *i_result_clause* for functions as ``result({i_result_var})`` i_type The Fortran interface type of the argument. Derived from the ``typemap.i_type``. If the attribute *+assumedtype* is set, then it will be ``type(*)``. size_var Name of variable which holds the size of an array in the Python wrapper. targs This is an array of objects, one for each template argument. For ``user_type`` the values *cxx_T* would be ``targs[0].cxx_T=int`` and ``targs[1].cxx_T=long *``. Other names are looked up in the typemap for the template argument. For example, ``targs[0].cxx_type`` and ``targs[0].f_kind``. fmtc """" Format strings used with C wrappers. Set for each argument. fmtf """" Format strings used with Fortran wrappers. Set for each argument. default_value The value of a C++ default value argument. .. XXX - only defined for native types (integer, real) gen.c_f_pointer_shape Shape of array for use with ``c_f_pointer``. For example, attribute *+dimension(10)* will create``,\t SHT_rv_cdesc%shape(1:1)``. The leading comma is used since scalar will not add a ``SHAPE`` argument to ``c_f_pointer``. gen.f_allocate_shape Fortran shape expression used with ``ALLOCATE`` statement when *dimension* attribute is set. For example, attribute *+dimension(10)* will create ``(10)``. f_assumed_shape Set when *rank* attribute is set to the corresponding shape. ``rank=1`` sets to ``(:)``, ``rank=2`` sets to ``(:,:)``, etc. May also be set to ``(..)`` when attribute *+dimension(..)* is used and option *F_CFI* is True. f_capsule_data_type The name of the derived type used to share memory information with C or C++. *F_capsule_data_type* for the argument type. gen.f_cdesc_shape Used to assign the rank of a Fortran variable to a cdesc variable. It will be blank for a scalar. ex: ``\nSHT_arg_cdesc%shape(1:1) = shape(arg)`` f_derived_type Derived type name for shadow class. f_dimension Dimension used in Fortran wrapper based on *dimension* or *rank* attribute. May be a literal shape, ``(10)``, assumed-shape, ``(:)`` or assumed-rank, ``(..)``. Assumed shape is used when the *deref(allocatable)* or *deref(pointer)* attribute is set. f_get_shape_array f_helper_* Helper name for a function. Each name in statements *helper* field will create a format name which starts with *f_helper_* and end with the helper's *f_fmtname* field. It will contain the name of the Fortran function for the helper. Used by statements *f_pre_call* and *f_post_call* statements. f_kind Value from typemap. ex ``C_INT``. Can be used in *CStmts.f_module*. f_size Expression to compute size of array argument using ``SIZE`` intrinsic. f_type Value from typemap. ex ``integer(C_INT)``. f_type_module Module name for *f_type*. f_var Fortran variable name for argument in Fortran wrapper. fc_var The name of the argument passed to the C wrapper. This is initially the same as *f_var* but when the statement field *c_local_var* is true, another name will be generated of the form ``SH_{f_var}``. Use with statement field *f_arg_call*. i_dimension Dimension used in ``bind(C)`` interface. May be assumed-size, ``(*)`` or assumed-rank, ``(..)``. i_type Used with Fortran interface. i_var Fortran variable name for argument in interface. Used with statement fields *i_result_decl*, *i_dummy_arg* and *i_dummy_decl*. fmtl """" Format strings used with Lua wrappers. fmtpy """"" Format strings used with Python wrappers. array_size Dimensions multipled together. ``dimension(2,3)`` creates ``(2)*(3)``. rank Attribute value for *rank*. Result ^^^^^^ Typedef ^^^^^^^ C_name_typedef Default from ``C_name_typedef_template`` .. ``{C_prefix}{C_name_scope}{typedef_name}`` F_name_typedef Default from ``F_name_typedef_template``. .. ``{F_name_scope}{F_name_api}`` F_name_scope includes template instantiation - vector_int_ Variable ^^^^^^^^ PY_struct_context Prefix used to to access struct/class variables. Includes trailing syntax to access member in a struct i.e. ``.`` or ``->``. ``self->obj->``. Types Map --------- Types describe how to handle arguments from Fortran to C to C++. Then how to convert return values from C++ to C to Fortran. Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a standardized way to generate procedure and derived-type declarations and global variables which are interoperable with C (ISO/IEC 9899:1999). The bind(C) attribute has been added to inform the compiler that a symbol shall be interoperable with C; also, some constraints are added. Note, however, that not all C features have a Fortran equivalent or vice versa. For instance, neither C's unsigned integers nor C's functions with variable number of arguments have an equivalent in Fortran. [#f1]_ .. list from util.py class Typedef forward Forward declaration. Defaults to *None*. typedef Initialize from existing type Defaults to *None*. f_return_code Fortran code used to call function and assign the return value. Defaults to *None*. f_to_c Expression to convert Fortran type to C type. If this field is set, it will be used before f_cast. Defaults to *None*. For example, to extract the *F_derived_member* before passing to C. Doxygen ------- Used to insert directives for doxygen for a function. brief Brief description. description Full description. return Description of return value. Patterns -------- C_error_pattern Inserted after the call to the C++ function in the C wrapper. Format is evaluated in the context of the result argument. *c_var*, *c_var_len* refer to the result argument. C_error_pattern_buf Inserted after the call to the C++ function in the buffer C wrapper for functions with string arguments. Format is evaluated in the context of the result argument. PY_error_pattern Inserted into Python wrapper. .. ...................................................................... .. rubric:: Footnotes .. [#f1] https://gcc.gnu.org/onlinedocs/gfortran/Interoperability-with-C.html