porytiles::CParserFacade Class Reference

High-level facade for parsing C/C++ source files. More...

#include <c_parser_facade.hpp>

Public Member Functions
	CParserFacade (std::filesystem::path file_path, gsl::not_null< const TextFormatter * > format)
	Constructs a facade for parsing the specified file.
	CParserFacade (std::filesystem::path file_path, gsl::not_null< const TextFormatter * > format, std::unordered_map< std::string, std::int64_t > seed_symbols)
	Constructs a facade that seeds every parse with externally known macro values.
ChainableResult< std::vector< DefineStatement > >	parse_defines ()
	Parses all #define statements from the file.
ChainableResult< std::vector< EnumDeclaration > >	parse_enums ()
	Parses all enum declarations from the file.
ChainableResult< TolerantDefineScan >	parse_defines_tolerant ()
	Parses all #define statements, tolerating individual evaluation failures.
ChainableResult< TolerantEnumScan >	parse_enums_tolerant ()
	Parses all enum declarations, tolerating individual member evaluation failures.
const std::vector< std::string > &	scan_warnings () const
	Returns recoverable warnings accumulated across tolerant parse calls.
ChainableResult< std::vector< ArrayDeclaration > >	parse_pointer_arrays (const std::optional< std::string > &name_prefix=std::nullopt)
	Parses all pointer array declarations from the file.
ChainableResult< std::vector< FunctionDefinition > >	parse_functions (const std::optional< std::string > &name_prefix=std::nullopt)
	Parses function definitions from the file.
ChainableResult< std::vector< StructVariableDeclaration > >	parse_struct_variables (const std::optional< std::string > &name_prefix=std::nullopt)
	Parses struct variable declarations from the file.
ChainableResult< std::vector< StructInitializerDeclaration > >	parse_struct_initializers (const std::optional< std::string > &name_prefix=std::nullopt)
	Parses struct variable declarations with their designated initializer fields.
ChainableResult< std::vector< StructDefinition > >	parse_struct_definitions (const std::optional< std::string > &name_filter=std::nullopt)
	Parses struct type definitions from the file.
ChainableResult< std::vector< IncbinDeclaration > >	parse_incbin_arrays (const std::optional< std::string > &name_prefix=std::nullopt)
	Parses INCBIN array declarations from the file.
ChainableResult< std::vector< IndexedArrayDeclaration > >	parse_indexed_arrays (const std::optional< std::string > &name_prefix=std::nullopt)
	Parses designated (indexed) array declarations from the file.
ChainableResult< std::optional< DefineStatement > >	find_define (const std::string &define_name)
	Finds a specific #define statement by name.
const std::vector< std::string > &	file_lines () const
	Returns the cached file lines.

Detailed Description

High-level facade for parsing C/C++ source files.

CParserFacade orchestrates the complete parsing pipeline: file loading, lexing, and parsing. It owns the file content and provides rich error formatting through FileHighlightPrinter integration.

The facade provides a simple interface for extracting specific constructs from C/C++ source files:

• parse_defines() extracts all #define preprocessor directives
• parse_enums() extracts all enum declarations

Error handling uses ChainableResult with FormattableError, providing multi-line error messages with source code context highlighting showing exactly where errors occurred.

Example usage:

PlainTextFormatter formatter;
CParserFacade driver{"include/constants.h", &formatter};
 
auto defines_result = driver.parse_defines();
if (!defines_result.has_value()) {
    // Error chain contains rich formatted output with source highlighting
    for (const auto& err : defines_result.chain()) {
        for (const auto& line : err->details(formatter)) {
            std::cerr << line << '\n';
        }
    }
}

Definition at line 58 of file c_parser_facade.hpp.

Constructor & Destructor Documentation

CParserFacade() [1/2]

porytiles::CParserFacade::CParserFacade	(	std::filesystem::path	file_path,
		gsl::not_null< const TextFormatter * >	format
	)

Constructs a facade for parsing the specified file.

The file is not loaded until a parse method is called. This allows for efficient construction when the facade may not be used, or when multiple facades are created but only some are actually needed.

Parameters

file_path	Path to the C/C++ source file to parse
format	Formatter for error message styling (non-owning, must outlive facade)

Definition at line 48 of file c_parser_facade.cpp.

CParserFacade() [2/2]

porytiles::CParserFacade::CParserFacade	(	std::filesystem::path	file_path,
		gsl::not_null< const TextFormatter * >	format,
		std::unordered_map< std::string, std::int64_t >	seed_symbols
	)

Constructs a facade that seeds every parse with externally known macro values.

The facade creates a fresh Parser per parse call, so the seed map is merged into each one. This lets the file resolve references to symbols declared elsewhere, for example seeding a source file with the defines and enum member values gathered from its header.

Parameters

file_path	Path to the C/C++ source file to parse
format	Formatter for error message styling (non-owning, must outlive facade)
seed_symbols	Name-to-value pairs merged into each parser's symbol table before scanning

Definition at line 53 of file c_parser_facade.cpp.

Member Function Documentation

file_lines()

const std::vector< std::string > & porytiles::CParserFacade::file_lines

(

)

const

Returns the cached file lines.

Returns a const reference to the file lines loaded during parsing. If the file has not been loaded yet (no parse method called), returns an empty vector.

Returns

Const reference to the file lines vector

Definition at line 568 of file c_parser_facade.cpp.

find_define()

ChainableResult< std::optional< DefineStatement > > porytiles::CParserFacade::find_define

(

const std::string &

define_name

)

Finds a specific #define statement by name.

Searches for a #define directive with the specified name. On first call, parses all defines and caches them for efficient subsequent lookups. Returns std::nullopt if the define is not found (which is not an error).

Parameters

define_name

The name of the #define macro to find

Returns

The DefineStatement if found, std::nullopt if not found, or an error on parse failure

Definition at line 541 of file c_parser_facade.cpp.

parse_defines()

ChainableResult< std::vector< DefineStatement > > porytiles::CParserFacade::parse_defines

(

)

Parses all #define statements from the file.

Loads the file (if not already loaded), tokenizes it, and extracts all #define preprocessor directives. Returns a vector of DefineStatement objects containing the macro names and evaluated values.

On error (file not found, lexer error, parser error), returns a ChainableResult containing a FormattableError with multi-line source context highlighting.

Returns

A vector of DefineStatement on success, or an error chain on failure

Definition at line 117 of file c_parser_facade.cpp.

parse_defines_tolerant()

ChainableResult< TolerantDefineScan > porytiles::CParserFacade::parse_defines_tolerant

(

)

Parses all #define statements, tolerating individual evaluation failures.

Like parse_defines() but returns a scan that separates resolved defines from those whose value could not be evaluated. Only load and lex failures produce an error result; unevaluable defines are reported in the scan. Any recoverable scan warnings are appended to the facade's warning log (see scan_warnings()).

Returns

The tolerant define scan on success, or an error chain on load/lex failure

Definition at line 194 of file c_parser_facade.cpp.

parse_enums()

ChainableResult< std::vector< EnumDeclaration > > porytiles::CParserFacade::parse_enums

(

)

Parses all enum declarations from the file.

Loads the file (if not already loaded), tokenizes it, and extracts all enum declarations. Returns a vector of EnumDeclaration objects containing the enum names and members with their values.

On error (file not found, lexer error, parser error), returns a ChainableResult containing a FormattableError with multi-line source context highlighting.

Returns

A vector of EnumDeclaration on success, or an error chain on failure

Definition at line 150 of file c_parser_facade.cpp.

parse_enums_tolerant()

ChainableResult< TolerantEnumScan > porytiles::CParserFacade::parse_enums_tolerant

(

)

Parses all enum declarations, tolerating individual member evaluation failures.

Like parse_enums() but returns per-member values that may be absent when they could not be evaluated. Only load and lex failures produce an error result.

Returns

The tolerant enum scan on success, or an error chain on load/lex failure

Definition at line 220 of file c_parser_facade.cpp.

parse_functions()

ChainableResult< std::vector< FunctionDefinition > > porytiles::CParserFacade::parse_functions

(

const std::optional< std::string > &

name_prefix = std::nullopt

)

Parses function definitions from the file.

Loads the file (if not already loaded), tokenizes it, and extracts function definitions. Returns a vector of FunctionDefinition objects containing the function names and body tokens.

This is used by AnimCodeParser to extract queue and driver functions like:

static void QueueAnimTiles_General_Flower(u16 timer) {
    AppendTilesetAnimToBuffer(..., TILE_OFFSET_4BPP(12), 4 * TILE_SIZE_4BPP);
}

On error (file not found, lexer error, parser error), returns a ChainableResult containing a FormattableError with multi-line source context highlighting.

Parameters

name_prefix

Optional prefix to filter function names. If provided, only functions whose names start with this prefix are returned. For example, "QueueAnimTiles_" would match only queue functions.

Returns

A vector of FunctionDefinition on success, or an error chain on failure

Definition at line 296 of file c_parser_facade.cpp.

parse_incbin_arrays()

ChainableResult< std::vector< IncbinDeclaration > > porytiles::CParserFacade::parse_incbin_arrays

(

const std::optional< std::string > &

name_prefix = std::nullopt

)

Parses INCBIN array declarations from the file.

Loads the file (if not already loaded), tokenizes it, and extracts array declarations that use INCBIN macros. Returns a vector of IncbinDeclaration objects containing the variable name, macro name, and path(s).

Supports both single-path arrays and multi-path palette-style arrays:

// Single path:
const u32 gTilesetTiles_General[] = INCBIN_U32("data/tilesets/primary/general/tiles.4bpp");
 
// Multiple paths (palettes):
const u16 gTilesetPalettes_General[][16] = {
    INCBIN_U16("data/tilesets/primary/general/palettes/00.gbapal"),
    INCBIN_U16("data/tilesets/primary/general/palettes/01.gbapal"),
    ...
};

On error (file not found, lexer error, parser error), returns a ChainableResult containing a FormattableError with multi-line source context highlighting.

Parameters

name_prefix

Optional prefix to filter variable names. If provided, only INCBIN arrays whose names start with this prefix are returned. For example, "gTilesetTiles_" would match only tiles declarations.

Returns

A vector of IncbinDeclaration on success, or an error chain on failure

Definition at line 461 of file c_parser_facade.cpp.

parse_indexed_arrays()

ChainableResult< std::vector< IndexedArrayDeclaration > > porytiles::CParserFacade::parse_indexed_arrays

(

const std::optional< std::string > &

name_prefix = std::nullopt

)

Parses designated (indexed) array declarations from the file.

Loads the file (if not already loaded), tokenizes it, and extracts array declarations that use designated initializers of the form [index] = value. Value expressions are evaluated against any seeded symbols. This is used to read attribute mask/shift tables such as sMetatileAttrMasks from src/fieldmap.c.

Parameters

name_prefix

Optional prefix to filter array names. If provided, only arrays whose names start with this prefix are returned. An exact array name (with no other array sharing it as a prefix) selects just that array.

Returns

A vector of IndexedArrayDeclaration on success, or an error chain on failure

Definition at line 503 of file c_parser_facade.cpp.

parse_pointer_arrays()

ChainableResult< std::vector< ArrayDeclaration > > porytiles::CParserFacade::parse_pointer_arrays

(

const std::optional< std::string > &

name_prefix = std::nullopt

)

Parses all pointer array declarations from the file.

Loads the file (if not already loaded), tokenizes it, and extracts all pointer array declarations. Returns a vector of ArrayDeclaration objects containing the array names and their initializer elements.

This is used by AnimCodeParser to extract animation frame arrays like:

const u16 *const gTilesetAnims_General_Flower[] = {
    gTilesetAnims_General_Flower_Frame0,
    gTilesetAnims_General_Flower_Frame1
};

On error (file not found, lexer error, parser error), returns a ChainableResult containing a FormattableError with multi-line source context highlighting.

Parameters

name_prefix

Optional prefix to filter array names. If provided, only arrays whose names start with this prefix are returned. For example, "gTilesetAnims_General_" would match only General tileset arrays.

Returns

A vector of ArrayDeclaration on success, or an error chain on failure

Definition at line 255 of file c_parser_facade.cpp.

parse_struct_definitions()

ChainableResult< std::vector< StructDefinition > > porytiles::CParserFacade::parse_struct_definitions

(

const std::optional< std::string > &

name_filter = std::nullopt

)

Parses struct type definitions from the file.

Loads the file (if not already loaded), tokenizes it, and extracts named struct definitions with their pattern-matchable member declarations. Members outside the simple declarator shape (pointer-to-array members, array members, multiple declarators) are skipped tolerantly; see Parser::parse_struct_definitions().

This is used to read the pointed-to type of struct Tileset::metatileAttributes from a project's include/global.fieldmap.h:

struct Tileset
{
    /*0x00*/ u8 isCompressed:1;
    /*0x10*/ const u16 *metatileAttributes;
    /*0x14*/ TilesetCB callback;
};

On error (file not found, lexer error, parser error), returns a ChainableResult containing a FormattableError with multi-line source context highlighting.

Parameters

name_filter

Optional exact struct tag name to filter by. If provided, only definitions whose name equals the filter are returned. For example, "Tileset" selects just the Tileset definition.

Returns

A vector of StructDefinition on success, or an error chain on failure

Definition at line 421 of file c_parser_facade.cpp.

parse_struct_initializers()

ChainableResult< std::vector< StructInitializerDeclaration > > porytiles::CParserFacade::parse_struct_initializers

(

const std::optional< std::string > &

name_prefix = std::nullopt

)

Parses struct variable declarations with their designated initializer fields.

Loads the file (if not already loaded), tokenizes it, and extracts struct variable declarations including their designated initializer fields. Returns a vector of StructInitializerDeclaration objects containing the struct type, variable name, and all .field = value pairs.

This is used by ProjectTilesetMetadataProvider to extract tileset metadata from headers.h files:

const struct Tileset gTileset_General = {
    .isCompressed = TRUE,
    .isSecondary = FALSE,
    .tiles = gTilesetTiles_General,
    .palettes = gTilesetPalettes_General,
    .metatiles = gMetatiles_General,
    .metatileAttributes = gMetatileAttributes_General,
    .callback = InitTilesetAnim_General,
};

Unlike parse_struct_variables(), this method parses the initializer body to extract field values.

On error (file not found, lexer error, parser error), returns a ChainableResult containing a FormattableError with multi-line source context highlighting.

Parameters

name_prefix

Optional prefix to filter variable names. If provided, only struct variables whose names start with this prefix are returned. For example, "gTileset_" would match only tileset declarations.

Returns

A vector of StructInitializerDeclaration on success, or an error chain on failure

Definition at line 379 of file c_parser_facade.cpp.

parse_struct_variables()

ChainableResult< std::vector< StructVariableDeclaration > > porytiles::CParserFacade::parse_struct_variables

(

const std::optional< std::string > &

name_prefix = std::nullopt

)

Parses struct variable declarations from the file.

Loads the file (if not already loaded), tokenizes it, and extracts struct variable declarations. Returns a vector of StructVariableDeclaration objects containing the struct type and variable names.

This is used by ProjectTilesetMetadataProvider to extract tileset names from headers.h files like:

const struct Tileset gTileset_General = {
    .isCompressed = TRUE,
    .isSecondary = FALSE,
    ...
};

On error (file not found, lexer error, parser error), returns a ChainableResult containing a FormattableError with multi-line source context highlighting.

Parameters

name_prefix

Optional prefix to filter variable names. If provided, only struct variables whose names start with this prefix are returned. For example, "gTileset_" would match only tileset declarations.

Returns

A vector of StructVariableDeclaration on success, or an error chain on failure

Definition at line 337 of file c_parser_facade.cpp.

scan_warnings()

const std::vector< std::string > & porytiles::CParserFacade::scan_warnings ( ) const

inline

Returns recoverable warnings accumulated across tolerant parse calls.

Returns

A const reference to the accumulated warning messages

Definition at line 131 of file c_parser_facade.hpp.

---

The documentation for this class was generated from the following files:

• porytiles/include/porytiles/utilities/c_parser/c_parser_facade.hpp
• porytiles/lib/utilities/c_parser/c_parser_facade.cpp