Generator Script Interface

class pystencilssfg.SourceFileGenerator(sfg_config=None)

Context manager that controls the code generation process in generator scripts.

Usage: The SourceFileGenerator must be used as a context manager by calling it within a with statement in the top-level code of a generator script (see Generator Scripts). Upon entry to its context, it creates an SfgComposer which can be used to populate the generated files. When the managed region finishes, the code files are generated and written to disk at the locations defined by the configuration. Existing copies of the target files are deleted on entry to the managed region, and if an exception occurs within the managed region, no files are exported.

Configuration: The SourceFileGenerator optionally takes a user-defined configuration object which is merged with configuration obtained from the build system; for details on configuration sources, refer to SfgConfiguration.

Parameters:

sfg_config (Optional[SfgConfiguration]) – User configuration for the code generator

class pystencilssfg.SfgConfiguration(config_source=None, header_extension=None, impl_extension=None, output_mode=None, outer_namespace=None, codestyle=None, output_directory=None, project_info=None)

Configuration for the SfgSourceFileGenerator.

The source file generator draws configuration from a total of four sources:

  • The default configuration (pystencilssfg.configuration.DEFAULT_CONFIG);

  • The project configuration;

  • Command-line arguments;

  • The user configuration passed to the constructor of SourceFileGenerator.

They take precedence in the following way:

  • Project configuration overrides the default configuration

  • Command line arguments override the project configuration

  • User configuration overrides default and project configuration, and must not conflict with command-line arguments; otherwise, an error is thrown.

Project Configuration via Configurator Script

Currently, the only way to define the project configuration is via a configuration module. A configurator module is a Python file defining the following function at the top-level:

from pystencilssfg import SfgConfiguration

def sfg_config() -> SfgConfiguration:
    # ...
    return SfgConfiguration(
        # ...
    )

The configuration module is passed to the code generation script via the command-line argument –sfg-config-module.

Parameters:

  • config_source (InitVar[SfgConfigSource | None]) –

  • header_extension (str | None) –

  • impl_extension (str | None) –

  • output_mode (SfgOutputMode | None) –

  • outer_namespace (str | None) –

  • codestyle (SfgCodeStyle | None) –

  • output_directory (str | None) –

  • project_info (Any) –

header_extension: str | None = None

File extension for generated header file.

impl_extension: str | None = None

File extension for generated implementation file.

output_mode: SfgOutputMode | None = None

The generator’s output mode; defines which files to generate, and the set of legal file extensions.

outer_namespace: str | None = None

The outermost namespace in the generated file. May be a valid C++ nested namespace qualifier (like a::b::c) or None if no outer namespace should be generated.

codestyle: SfgCodeStyle | None = None

Code style that should be used by the code generator.

output_directory: str | None = None

Directory to which the generated files should be written.

project_info: Any = None

Object for managing project-specific information. To be set by the configurator script.

configuration.DEFAULT_CONFIG = SfgConfiguration(header_extension='h', impl_extension='cpp', output_mode=<SfgOutputMode.STANDALONE: 1>, outer_namespace=None, codestyle=SfgCodeStyle(indent_width=2, code_style='file', force_clang_format=False, clang_format_binary='clang-format'), output_directory='.', project_info=None)