This is a simplistic C/C++-like preprocessor. More...

#include <OgreGLSLPreprocessor.h>

Classes
class	Macro
	A macro definition. More...

class	Token
	A input token. More...

Public Types
typedef void(*	ErrorHandlerFunc) (int iLine, const char iError, const Token iToken)
	Call the error handler. More...

Public Member Functions
	CPreprocessor (const Token &iToken, int iLine)
	Private constructor to re-parse a single token. More...

Token	GetToken (bool iExpand)
	Stateless tokenizer: Parse the input text and return the next token. More...

Token	HandleDirective (Token &iToken, int iLine)
	Handle a preprocessor directive. More...

bool	HandleDefine (Token &iBody, int iLine)
	Handle a #define directive. More...

bool	HandleUnDef (Token &iBody, int iLine)
	Undefine a previously defined macro. More...

bool	HandleIfDef (Token &iBody, int iLine)
	Handle an #ifdef directive. More...

bool	HandleIf (Token &iBody, int iLine)
	Handle an #if directive. More...

bool	HandleIf (bool val, int iLine)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

bool	HandleElif (Token &iBody, int iLine)
	Handle an #elif directive. More...

bool	HandleElse (Token &iBody, int iLine)
	Handle an #else directive. More...

bool	HandleEndIf (Token &iBody, int iLine)
	Handle an #endif directive. More...

Token	GetArgument (Token &oArg, bool iExpand, bool shouldAppendArg)
	Get a single function argument until next ',' or ')'. More...

Token	GetArguments (std::vector< Token > &oArgs, bool iExpand, bool shouldAppendArg)
	Get all the arguments of a macro: '(' arg1 { ',' arg2 { ',' ... }} ')'. More...

Token	GetExpression (Token &oResult, int iLine, int iOpPriority=0)
	Parse an expression, compute it and return the result. More...

bool	GetValue (const Token &iToken, long &oValue, int iLine)
	Get the numeric value of a token. More...

bool	GetValueDef (const Token &iToken, long &oValue, int iLine)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. same as above, but considers the defined() function. More...

Token	ExpandMacro (const Token &iToken)
	Expand the given macro, if it exists. More...

Macro *	IsDefined (const Token &iToken)
	Check if a macro is defined, and if so, return it. More...

Token	Parse (const Token &iSource)
	Parse the input string and return a token containing the whole output. More...

	CPreprocessor ()
	Create an empty preprocessor object. More...

virtual	~CPreprocessor ()
	Destroy the preprocessor object. More...

void	Define (const char iMacroName, size_t iMacroNameLen, const char iMacroValue, size_t iMacroValueLen)
	Define a macro without parameters. More...

void	Define (const char *iMacroName, size_t iMacroNameLen, long iMacroValue)
	Define a numerical macro. More...

bool	Undef (const char *iMacroName, size_t iMacroNameLen)
	Undefine a macro. More...

char *	Parse (const char *iSource, size_t iLength, size_t &oLength)
	Parse the input string and return a newly-allocated output string. More...

Static Public Member Functions
static Token	ExpandDefined (CPreprocessor *iParent, const std::vector< Token > &iArgs)
	The implementation of the defined() preprocessor function. More...

static void	Error (int iLine, const char iError, const Token iToken=NULL)
	Call the error handler. More...

Public Attributes
const char *	Source
	The current source text input. More...

const char *	SourceEnd
	The end of the source text. More...

int	Line
	Current line number. More...

bool	BOL
	True if we are at beginning of line. More...

unsigned	EnableOutput
	A stack of 32 booleans packed into one value :) More...

unsigned	EnableElif

std::forward_list< Macro >	MacroList
	The list of macros defined so far. More...

Static Public Attributes
static ErrorHandlerFunc	ErrorHandler = CPreprocessor::Error
	A pointer to the preprocessor's error handler. More...

Friends
class	CPreprocessor::Macro

Detailed Description

This is a simplistic C/C++-like preprocessor.

It takes an non-zero-terminated string on input and outputs a non-zero-terminated string buffer.

This preprocessor was designed specifically for GLSL shaders, so if you want to use it for other purposes you might want to check if the feature set it provides is enough for you.

Here's a list of supported features:

Fast memory allocation-less operation (mostly).
Line continuation (backslash-newline) is swallowed.
Line numeration is fully preserved by inserting empty lines where required. This is crucial if, say, GLSL compiler reports you an error with a line number.
#define: Parametrized and non-parametrized macros. Invoking a macro with less arguments than it takes assignes empty values to missing arguments.
#undef: Forget defined macros
#ifdef / #ifndef / #else / #endif: Conditional suppression of parts of code.
#if: Supports numeric expression of any complexity, also supports the defined() pseudo-function.

Member Typedef Documentation

◆ ErrorHandlerFunc

typedef void(* Ogre::CPreprocessor::ErrorHandlerFunc) (int iLine, const char *iError, const Token *iToken)

Call the error handler.

Parameters

iLine	The line at which the error happened.
iError	The error string.
iToken	If not NULL contains the erroneous token

Constructor & Destructor Documentation

◆ CPreprocessor() [1/2]

Ogre::CPreprocessor::CPreprocessor	(	const Token &	iToken,
		int	iLine
	)

Private constructor to re-parse a single token.

◆ CPreprocessor() [2/2]

Ogre::CPreprocessor::CPreprocessor ( )

inline

Create an empty preprocessor object.

◆ ~CPreprocessor()

Ogre::CPreprocessor::~CPreprocessor ( )

virtual

Destroy the preprocessor object.

Member Function Documentation

◆ Define() [1/2]

void Ogre::CPreprocessor::Define	(	const char *	iMacroName,
		size_t	iMacroNameLen,
		const char *	iMacroValue,
		size_t	iMacroValueLen
	)

Define a macro without parameters.

Parameters

iMacroName	The name of the defined macro
iMacroNameLen	The length of the name of the defined macro
iMacroValue	The value of the defined macro
iMacroValueLen	The length of the value of the defined macro

◆ Define() [2/2]

void Ogre::CPreprocessor::Define	(	const char *	iMacroName,
		size_t	iMacroNameLen,
		long	iMacroValue
	)

Define a numerical macro.

Parameters

iMacroName	The name of the defined macro
iMacroNameLen	The length of the name of the defined macro
iMacroValue	The value of the defined macro

◆ Error()

void Ogre::CPreprocessor::Error	(	int	iLine,
		const char *	iError,
		const Token *	iToken = `NULL`
	)

static

Call the error handler.

Parameters

iLine	The line at which the error happened.
iError	The error string.
iToken	If not NULL contains the erroneous token

◆ ExpandDefined()

CPreprocessor::Token Ogre::CPreprocessor::ExpandDefined	(	CPreprocessor *	iParent,
		const std::vector< Token > &	iArgs
	)

static

The implementation of the defined() preprocessor function.

Parameters

iParent	The parent preprocessor object
iArgs	The arguments themselves

Returns: The return value encapsulated in a token

◆ ExpandMacro()

CPreprocessor::Token Ogre::CPreprocessor::ExpandMacro ( const Token & iToken )

Expand the given macro, if it exists.

If macro has arguments, they are collected from source stream.

Parameters

iToken A KEYWORD token containing the (possible) macro name.

Returns: The expanded token or iToken if it is not a macro

◆ GetArgument()

CPreprocessor::Token Ogre::CPreprocessor::GetArgument	(	Token &	oArg,
		bool	iExpand,
		bool	shouldAppendArg
	)

Get a single function argument until next ',' or ')'.

Parameters

oArg	The argument is returned in this variable.
iExpand	If false, parameters are not expanded and no expressions are allowed; only a single keyword is expected per argument.
shouldAppendArg	When true, the argument will be appended the word word __arg_ e.g. #define myMacro(x) --> #define myMacro(x__arg_) This workaround a bug where calling myMacro( x ) would cause issues.

Returns: The first unhandled token after argument.

◆ GetArguments()

CPreprocessor::Token Ogre::CPreprocessor::GetArguments	(	std::vector< Token > &	oArgs,
		bool	iExpand,
		bool	shouldAppendArg
	)

Get all the arguments of a macro: '(' arg1 { ',' arg2 { ',' ... }} ')'.

Parameters

oArgs	This is set to a pointer to an array of parsed arguments.
shouldAppendArg	See GetArgument.
iExpand	If false, parameters are not expanded and no expressions are allowed; only a single keyword is expected per argument.

◆ GetExpression()

CPreprocessor::Token Ogre::CPreprocessor::GetExpression	(	Token &	oResult,
		int	iLine,
		int	iOpPriority = `0`
	)

Parse an expression, compute it and return the result.

Operator priority: 0: Whole expression 1: '(' ')' 2: || 3: && 4: | 5: ^ 6: & 7: '==' '!=' 8: '<' '<=' '>' '>=' 9: '<<' '>>' 10: '+' '-' 11: '*' '/' '' 12: unary '+' '-' '!' '~'.

Parameters

oResult	A token containing the result of expression
iLine	The line at which the expression starts (for error reports)
iOpPriority	Operator priority (at which operator we will stop if proceeding recursively – used internally. Parser stops when it encounters an operator with higher or equal priority).

Returns: The last unhandled token after the expression

◆ GetToken()

CPreprocessor::Token Ogre::CPreprocessor::GetToken ( bool iExpand )

Stateless tokenizer: Parse the input text and return the next token.

Parameters

iExpand If true, macros will be expanded to their values

Returns: The next token from the input stream

◆ GetValue()

bool Ogre::CPreprocessor::GetValue	(	const Token &	iToken,
		long &	oValue,
		int	iLine
	)

Get the numeric value of a token.

If the token was produced by expanding a macro, we will get an TEXT token which can contain a whole expression; in this case we will call GetExpression to parse it. Otherwise we just call the token's GetValue() method.

Parameters

iToken	The token to get the numeric value of
oValue	The variable to put the value into
iLine	The line where the directive begins (for error reports)

Returns: true if ok, false if not

◆ GetValueDef()

bool Ogre::CPreprocessor::GetValueDef	(	const Token &	iToken,
		long &	oValue,
		int	iLine
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. same as above, but considers the defined() function.

◆ HandleDefine()

bool Ogre::CPreprocessor::HandleDefine	(	Token &	iBody,
		int	iLine
	)

Handle a #define directive.

Parameters

iBody	The body of the directive (everything after the directive until end of line).
iLine	The line where the directive begins (for error reports)

Returns: true if everything went ok, false if not

◆ HandleDirective()

CPreprocessor::Token Ogre::CPreprocessor::HandleDirective	(	Token &	iToken,
		int	iLine
	)

Handle a preprocessor directive.

Parameters

iToken	The whole preprocessor directive line (until EOL)
iLine	The line where the directive begins (for error reports)

Returns: The last input token that was not proceeded.

◆ HandleElif()

bool Ogre::CPreprocessor::HandleElif	(	Token &	iBody,
		int	iLine
	)

Handle an #elif directive.

Parameters

iBody	The body of the directive (everything after the directive until end of line).
iLine	The line where the directive begins (for error reports)

Returns: true if everything went ok, false if not

◆ HandleElse()

bool Ogre::CPreprocessor::HandleElse	(	Token &	iBody,
		int	iLine
	)

Handle an #else directive.

Parameters

iBody	The body of the directive (everything after the directive until end of line).
iLine	The line where the directive begins (for error reports)

Returns: true if everything went ok, false if not

◆ HandleEndIf()

bool Ogre::CPreprocessor::HandleEndIf	(	Token &	iBody,
		int	iLine
	)

Handle an #endif directive.

Parameters

iBody	The body of the directive (everything after the directive until end of line).
iLine	The line where the directive begins (for error reports)

Returns: true if everything went ok, false if not

◆ HandleIf() [1/2]

bool Ogre::CPreprocessor::HandleIf	(	bool	val,
		int	iLine
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ HandleIf() [2/2]

bool Ogre::CPreprocessor::HandleIf	(	Token &	iBody,
		int	iLine
	)

Handle an #if directive.

Parameters

iBody	The body of the directive (everything after the directive until end of line).
iLine	The line where the directive begins (for error reports)

Returns: true if everything went ok, false if not

◆ HandleIfDef()

bool Ogre::CPreprocessor::HandleIfDef	(	Token &	iBody,
		int	iLine
	)

Handle an #ifdef directive.

Parameters

iBody	The body of the directive (everything after the directive until end of line).
iLine	The line where the directive begins (for error reports)

Returns: true if everything went ok, false if not

◆ HandleUnDef()

bool Ogre::CPreprocessor::HandleUnDef	(	Token &	iBody,
		int	iLine
	)

Undefine a previously defined macro.

Parameters

iBody	The body of the directive (everything after the directive until end of line).
iLine	The line where the directive begins (for error reports)

Returns: true if everything went ok, false if not

◆ IsDefined()

CPreprocessor::Macro * Ogre::CPreprocessor::IsDefined ( const Token & iToken )

Check if a macro is defined, and if so, return it.

Parameters

iToken Macro name

Returns: The macro object or NULL if a macro with this name does not exist

◆ Parse() [1/2]

char * Ogre::CPreprocessor::Parse	(	const char *	iSource,
		size_t	iLength,
		size_t &	oLength
	)

Parse the input string and return a newly-allocated output string.

Note: The returned preprocessed string is NOT zero-terminated (just like the input string).

Parameters

iSource	The source text
iLength	The length of the source text in characters
oLength	The length of the output string.

Returns: The output from preprocessor, allocated with malloc(). The parser can actually allocate more than needed for performance reasons, but this should not be a problem unless you will want to store the returned pointer for long time in which case you might want to realloc() it. If an error has been encountered, the function returns NULL. In some cases the function may return an unallocated address that's inside the source buffer. You must free() the result string only if the returned address is not inside the source text.

◆ Parse() [2/2]

CPreprocessor::Token Ogre::CPreprocessor::Parse ( const Token & iSource )

Parse the input string and return a token containing the whole output.

Parameters

iSource The source text enclosed in a token

Returns: The output text enclosed in a token

◆ Undef()

bool Ogre::CPreprocessor::Undef	(	const char *	iMacroName,
		size_t	iMacroNameLen
	)

Undefine a macro.

Parameters

iMacroName	The name of the macro to undefine
iMacroNameLen	The length of the name of the macro to undefine

Returns: true if the macro has been undefined, false if macro doesn't exist

Friends And Related Function Documentation

◆ CPreprocessor::Macro

friend class CPreprocessor::Macro

friend

Member Data Documentation

◆ BOL

bool Ogre::CPreprocessor::BOL

True if we are at beginning of line.

◆ EnableElif

unsigned Ogre::CPreprocessor::EnableElif

◆ EnableOutput

unsigned Ogre::CPreprocessor::EnableOutput

A stack of 32 booleans packed into one value :)

◆ ErrorHandler

CPreprocessor::ErrorHandlerFunc Ogre::CPreprocessor::ErrorHandler = CPreprocessor::Error

static

A pointer to the preprocessor's error handler.

You can assign the address of your own function to this variable and implement your own error handling (e.g. throwing an exception etc).

◆ Line

int Ogre::CPreprocessor::Line

Current line number.

◆ MacroList

std::forward_list<Macro> Ogre::CPreprocessor::MacroList

The list of macros defined so far.

◆ Source

const char* Ogre::CPreprocessor::Source

The current source text input.

◆ SourceEnd

const char* Ogre::CPreprocessor::SourceEnd

The end of the source text.

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

/home/docker/jenkins/workspace/technical-docs/source/third_party/ogre3d_preprocessor/OgreGLSLPreprocessor.h
/home/docker/jenkins/workspace/technical-docs/source/third_party/ogre3d_preprocessor/OgreGLSLPreprocessor.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ ErrorHandlerFunc

Constructor & Destructor Documentation

◆ CPreprocessor() [1/2]

◆ CPreprocessor() [2/2]

◆ ~CPreprocessor()

Member Function Documentation

◆ Define() [1/2]

◆ Define() [2/2]

◆ Error()

◆ ExpandDefined()

◆ ExpandMacro()

◆ GetArgument()

◆ GetArguments()

◆ GetExpression()

◆ GetToken()

◆ GetValue()

◆ GetValueDef()

◆ HandleDefine()

◆ HandleDirective()

◆ HandleElif()

◆ HandleElse()

◆ HandleEndIf()

◆ HandleIf() [1/2]

◆ HandleIf() [2/2]

◆ HandleIfDef()

◆ HandleUnDef()

◆ IsDefined()

◆ Parse() [1/2]

◆ Parse() [2/2]

◆ Undef()

Friends And Related Function Documentation

◆ CPreprocessor::Macro

Member Data Documentation

◆ BOL

◆ EnableElif

◆ EnableOutput

◆ ErrorHandler

◆ Line

◆ MacroList

◆ Source

◆ SourceEnd