Config Schema

This is the schema for the *.toml configuration files that are used with soagen, a command-line tool for generating SoA container classes for use in C++.

<root>

These options all belong at the root of the config file. They do not appear under any [headings].

allocator

The allocator your SoA classes will use. May be overridden on a per-class basis.

Type: string

Required: No

Default: soagen::allocator

Example:

allocator = 'foo::allocator'

namespace

The namespace your generated code will belong to.

Type: string

Required: No (but strongly recommended!)

Default: None

Example:

namespace = 'game'

hpp

These options relate to the generated .hpp file. They belong under the [hpp] heading.

banner

Text that will be injected right at the top of the .hpp file as a block of comments. Typically used for copyright notices and such.

Type: string

Required: No

Default: None

Example:

[hpp]
banner = 'Copyright (c) Codey McCodeface'

brief

A brief description of the file. Used to generate a @brief directive for Doxygen.

Type: string

Required: No

Default: A simple brief like "Contains the definitions of foo and bar" will be generated for you.

Example:

[hpp]
brief = 'This is where we keep the bodies.'

combined

Instructs soagen to combine the class definitions of all [structs] into one .hpp file, instead of making a separate .hpp file for each one.

Type: boolean

Required: No

Default: true

Example:

[hpp]
combined = false

footer

Code to be injected at the bottom of the file, after all the other definitions.

Type: string

Required: No

Default: None

Example:

[hpp]
footer = '''
{% namespace::start %}

void foo()
{
    //...
}

{% namespace::end %}
'''

header

Code to be injected near the top of the file, after the #includes and forward declarations. Typically you'd use this for constants and type aliases that are used in your structs.

Type: string

Required: No

Default: None

Example:

[hpp]
header = '''
{% namespace::start %}

inline constexpr float default_mass = 1.0f;

{% namespace::end %}
'''

includes

File paths to be added as #include directives.

internal includes will use the quoted form #include "foo"
external includes will use the angle-bracket form #include <foo>

Type: string, or array of strings

Required: No

Default: None

Example:

[hpp]
includes.internal = 'quaternion.hpp'
includes.external = [ 'string_view', 'cfloat' ]
'''

Code to be injected near the top of the file, immediately after the internal #includes, but before external #includes, forward declarations, or any other definitions. Typically you'd use this to override any config options that are configured via preprocessor macros.

Type: string

Required: No

Default: None

Example:

[hpp]
prologue = '''
#define SOAGEN_ALWAYS_INLINE inline // disable any forced-inlining
'''

structs

These options all relate to individual SoA 'structs'. They belong under a heading matching the name of your struct, e.g.

[structs.particles]
# ...

allocator

The allocator this particular struct will use. Overrides the root-level allocator.

Type: string

Required: No

Default: soagen::allocator

Example:

[structs.particles]
allocator = 'foo::allocator'

annotations

Annotations that will be added immediately before your class (i.e. on the line before the C++ keyword class), one per line. Use this to add things like Unreal Engine's UCLASS().

Type: string, or array of strings

Required: No

Default: None

Example:

[structs.particles]
annotations = [ 'UCLASS()' ]

attributes

Attributes that will be added to your class definition, immediately after the C++ keyword class. Use this to add things like alignas(N).

Type: string, or array of strings

Required: No

Default: None

Example:

[structs.particles]
attributes = [ 'alignas(32)' ]

brief

A brief description of the struct. Used to generate a @brief directive for Doxygen.

Type: string

Required: No

Default: A simple brief will be generated for you.

Example:

[structs.particles]
brief = 'Particles in the effects system.'

copyable

Used to disable the copy constructor + assignment operator if necessary.

Type: boolean

Required: No

Default: true (they are both = default;)

Example:

[structs.particles]
copyable = false

default_constructible

Used to disable the default constructor if necessary.

Type: boolean, or string value auto

Required: No

Default: true (default constructor is = default;)

Example:

[structs.particles]
default_constructible = false

details

A detailed description of the struct. Used to generate a @details directive for Doxygen.

Type: string

Required: No

Default: None

Example:

[structs.particles]
details = '''Lorem ipsum, et cetera.'''

epilogue

Code to be injected into the .hpp file directly after your class definition. This code at namespace scope.

Type: string

Required: No

Default: None

footer

Code to be injected at the bottom of the class, after all the type + function definitions. This code will be at class scope.

Type: string

Required: No

Default: None

header

Code to be injected at the top of the class, after the internal typedefs and constants. This code will be at class scope.

Type: string

Required: No

Default: None

mixins

List of type names to use as CRTP 'mixin' base classes. Each named type must be a template class that takes one type argument (additional template arguments are allowed but must be defaulted).

Type: string, or array of strings

Required: No

Default: None

Example:

[structs.particles]
mixins = 'foo::add_some_functionality'

Where foo::add_some_functionality is something like this:

namespace foo
{
    template <typename Derived>
    struct add_some_functionality
    {
        // ...
    };
}

movable

Used to disable the move constructor + assignment operator if necessary.

Type: boolean

Required: No

Default: true (they are both = default;)

Example:

[structs.particles]
movable = false

prologue

Code to be injected into the .hpp file directly before your class definition. This code will be at namespace scope.

Type: string

Required: No

Default: None

static_variables

Static variables to add as part of your class definition. See static_variables

swappable

Used to disable the generation of member and non-member swap() functions and typedefs if necessary.

Type: boolean

Required: No

Default: true

Example:

[structs.particles]
swappable = false

variables

Describes the variable 'columns' your struct will have. See variables

static_variables

These options are for specifying static variables to add as part of your class definition. They are all KVP's in individal tables in your struct's static_variables, e.g.:

[structs.particles]
static_variables = [
    { name = 'default_mass', type = 'float', ... }
]

access

The access level of the static variable.

Type: string - one of public, protected or private.

Required: No

Default: public

Example:

[structs.particles]
static_variables = [
    { ..., access = 'protected', ... }
]

brief

A brief description of the variable. Used to generate a @brief directive for Doxygen.

Type: string

Required: No

Default: None

Example:

[hpp]
    { ..., brief = 'The default mass used for particles.', ... }

const

The const-ness of the static variable.

Type: string - one of const, constexpr, or a boolean.

Required: No

Default: constexpr

Example:

[structs.particles]
static_variables = [
    { ..., const = false, ... }
]

name

The name of your static variable.

Type: string

Required: Yes

Example:

[structs.particles]
static_variables = [
    { ..., name = 'default_mass', ... }
]

type

The type of the static variable.

Type: string

Required: Yes

Example:

[structs.particles]
static_variables = [
    { ..., type = 'float', ... }
]

value

The value used to intialize the static variable.

Type: string, integer or float

Required: Yes

Example:

[structs.particles]
static_variable = [
    { ..., value = 1.0, ... }
]

variables

These options are for specifying the variable 'columns' your SoA class will have. They are all KVP's in individal tables in your struct's variables, e.g.:

[structs.particles]
variables = [
    { name = 'mass', type = 'float', ... }
]

alignment

The minimum memory alignment of this column's region in memory.

Type: integer

Required: No

Default: alignof(value_type)

default

The default value passed to parameters for this column in push_back() and friends.

Type: string, integer or float

Required: No

Default: None

Example:

[structs.particles]
variables = [
    { ..., default = '{}', ... }
]

name

The name of your variable 'column'.

Type: string

Required: Yes

Example:

[structs.particles]
variables = [
    { ..., name = 'position', ... }
]

param_type

The param_type of your column. Determines the type used to pass values for the column as a parameter to functions like push_back().

Type: string

Required: No

Default: soagen::param_type<value_type>

type

The value_type of your variable 'column'.

Type: string

Required: Yes

Example:

[structs.particles]
variables = [
    { ..., type = 'vec3', ... }
]