Customization

Many customization options of the bindings generation are available, e.g. wrap only some functions and classes, choose template instantiation, and so on. This can be done

  • with code annotations or

  • with a TOML input file.

The choice between the two approaches depends on the project and needs.

Code annotations

clair’s behaviour can be modified by simple annotations in the code.

  • C2PY_IGNORE: Placed before a function or a class, clair ignores it.

  • C2PY_WRAP_AS_METHOD: Placed before a function, clair adds the function as a method to the first argument’s class object.

  • C2PY_MODULE_INIT: Placed before a function, clair uses this function as the module initialization function.

  • C2PY_RENAME(new_name): Placed before a function or a class, clair uses new_name as the name in Python.

These annotations overrule any filter options in the TOML file.

See Code annotations for examples.

TOML input file

The TOML file is required to have the same name as the C++ source file, except for the .cpp extension. For example, if the C++ source file given to clair-c2py is my_module.cpp, the TOML file should be called my_module.toml.

Here is an example TOML file showing and explaining the available options:

# Name of the package [optional].
# Name of the module will be package_name.module_filename
package_name = "my_package"

# The documentation string of the module. 
documentation = "This is an awesome module generated by c2py/clair."

# List of namespaces as a space separated string e.g. "A A::B"
# If non-empty, only the elements declared in EXACTLY these namespaces are wrapped.
# NB e.g. in previous example A::detail will be ignored, whatever match_names.
namespaces = "foo bar"

# Match/reject elements according to a regex (LLVM regex)
# If match_names/match_names are both set, the algorithm is 
#  for X of fully qualified name qname
#    if match_names and match_names does not match Qname : skip X
#    if reject_names and reject_names matches Qname : skip X
#    else keep X.
#
match_names = ""
reject_names = ""

# Only keep elements declared in files matching the pattern
match_files = "" # String must be a regex

# If true, transform methods with no arguments into a read only property
wrap_no_arg_methods_as_properties = false

# [Advanced] If yes (default), all elements (class/enum/functions)
# declared in headers included with -isystem are ignored for better performance.
exclude_system_headers = true

See TOML input file for how these options affect the generated bindings.