object-introspection/types/README.md

# Container Type Definition Format

This document describes the format of the container definition files contained in this directory.

### info
- `type_name`

  The fully-qualified name of the container type. This is used to match against
  the names of types contained in an executable's debug information.

- `header`

  The name of the C++ header file in which this container is defined.

- `stub_template_params`

  The indexes of template parameters which do not represent types stored within
  this container. These parameters will not be recursed into and measured by OI.

- `underlying_container_index`

  Only used for container adapters. Points OI to the template parameter
  representing the underlying container to be measured.

- `required_features`

  A set of feature names such as `tree-builder-v2` which must be enabled for
  this container description to be included. Currently only supported with
  CodeGen v2 as that's their only use case and an implementation for CodeGen v1
  would be untested.

### codegen
- `decl`

  C++ code for the declaration of a `getSizeType` function for this container.

- `func`

  C++ code for the definition of a `getSizeType` function for this container.

- `processor.type`

  The static type that will be filled in by this particular processor. Multiple
  processors are allowed and recommended.

- `processor.func`

  C++ code for the function body of a function with this signature:
  `void(result::Element& el, std::stack<Inst>& ins, ParsedData d)` which is
  supplied with the data of the paired static type.

- `traversal_func`

  C++ code for the function body of a function with this signature:
  `static types::st::Unit<DB> getSizeType(const T& container, ST returnArg)`
  where `ST` defines the combined static type of each supplied processor.

- `scoped_extra`

  Extra C++ code to be included in the generated `TypeHandler` for this
  container.

- `extra`

  Any extra C++ code to be included directly. This code is not automatically
  wrapped in a namespace, so definitions from different container TOML files
  will collide if they share the same name.


## Changes introduced with TreeBuilder V2
- `decl` and `func` fields are ignored when using `-ftree-builder-v2`. The
  `TypeHandler` is constructed from `traversal_func` field and `processor`
  entries.

## Changes introduced with TypeGraph
- `typeName` and `matcher` fields have been merged into the single field `type_name`.
- `ns` namespace definition is no longer required.
- `underlyingContainerIndex` renamed to `underlying_container_index`
- The options for measuring / stubbing / removing template parameters have been reworked:
  - By default all parameters are now measured. This includes the tail parameters in a variadic template.
  - There is one option to specify template parameters which should not be measured: `stub_template_params`. The type graph code will automatically determine what type of stubbing to apply to each parameter in this list.

### Deprecated Options
- `ctype`

  A reference to the enum `ContainerTypeEnum` in OI's source code. This is no
  longer required with Tree Builder v2.

- `handler`

  C++ code for the definition of a `TypeHandler` class for this container. Now
  generated from `traversal_func` and `processor` entries.

- `numTemplateParams`

  The first `numTemplateParams` template parameters for this container represent
  the types for the data we want to process. If this is not set, use all a
  container's template parameters. All of a container's parameters will still be
  enumerated and output in CodeGen, regardless of this setting.

- `allocatorIndex`

  Index of a template parameter representing an allocator. It will be not be
  used when CodeGenning this container.

- `replaceTemplateParamIndex`

  Indexes of template parameters to be stubbed out, i.e. replaced with dummy
  structs of a given size. Used for custom hashers and comparers.