TurtleBrains::Core::Debug Namespace Reference

Contains some functionality for creating a debug log, and in some cases (Windows) popping open a console window. More...

Classes
class	EmptyLogger
class	StreamLogger
class	LogChannel
class	ContinueEntry
class	StartOfEntry
class	EndOfEntry
class	LogWithColor
class	LogWithQuotes
class	LogChannelLevel
struct	GraphicsChannel
struct	GameplayChannel
struct	NetworkChannel
struct	PhysicsChannel
struct	tbInternalChannel
class	ScopedDebugInfo

Typedefs
using	LogGraphics = LogChannelLevel< GraphicsChannel >
using	LogGameplay = LogChannelLevel< GameplayChannel >
using	LogNetwork = LogChannelLevel< NetworkChannel >
using	LogPhysics = LogChannelLevel< PhysicsChannel >
using	tbInternalLog = LogChannelLevel< tbInternalChannel >

Enumerations
enum	LogLevel {   kAlways , kError , kWarning , kInfo ,   kDebug , kTrace }
enum class	LogColor {   Black , Red , Green , Yellow ,   Blue , Magenta , Cyan , White ,   Gray , BrightRed , BrightGreen , BrightYellow ,   BrightBlue , BrightMagenta , BrightCyan , BrightWhite ,   Reset }

Functions
void	OpenLog (const std::string &logFile, bool createConsoleWindow)
void	SaveLog (void)
void	CloseLog (void)
void	Log (const char *formattedMessage,...)
void	LogIf (const bool testResult, const char *formattedMessage,...)
void	LogHexDump (const char *message, const void *rawData, size_t dataSize)
StreamLogger &	TheLogger (void)
EmptyLogger &	TheEmptyLogger (void)
template<typename Type >
StreamLogger &	operator<< (StreamLogger &stream, const Type &value)
StreamLogger &	operator<< (StreamLogger &stream, const LogColor &color)
StreamLogger &	operator<< (StreamLogger &stream, const LogLevel &logLevel)
StreamLogger &	operator<< (StreamLogger &stream, const ContinueEntry &continueEntry)
StreamLogger &	operator<< (StreamLogger &stream, const StartOfEntry &startOfEntry)
StreamLogger &	operator<< (StreamLogger &stream, const EndOfEntry &endOfEntry)
StreamLogger &	operator<< (StreamLogger &stream, const Formatter &formatted)
StreamLogger &	operator<< (StreamLogger &stream, const LogWithColor &coloredMessage)
StreamLogger &	operator<< (StreamLogger &stream, const LogWithQuotes &quotedMessage)
void	SetCrashReportFilepath (const String &reportFilepath="crash_report.txt")
void	ProjectEntryPoint (void(*entryPoint)(void))
int	ProjectEntryPoint (int(*entryPoint)(const int argumentCount, const char *argumentValues[]), const int argumentCount, const char *argumentValues[])
const String &	DebugInfo (void)

Detailed Description

TODO: TurtleBrains: Documentation: This is still early in development and may become combined with Core.

Function Documentation

CloseLog()

void TurtleBrains::Core::Debug::CloseLog

(

void

)

Closes the log file after flushing any pending log messages, once closed any new log messages will not be written to the log file, only to the stdout.

Log()

void TurtleBrains::Core::Debug::Log	(	const char *	formattedMessage,
			...
	)

Writes a message into the log, the message can be a formatted string behaving exactly like printf would.

Parameters

formattedMessage	A string of characters of a formatted string that describes the variable arguments that follow. The formatted message and arguments are used exactly like printf() would be.
...	The variable arguments the fill in the formattedMessage string using the same printf() format.

Note

Prefer use of the macro tb_log so that nothing will happen, compiled out, if debugging is disabled by the tb_without_debug_set define fount in the tb_configuration.h file.

LogHexDump()

void TurtleBrains::Core::Debug::LogHexDump	(	const char *	message,
		const void *	rawData,
		size_t	dataSize
	)

TODO: TurtleBrains: Documentation: Teach user about this.

LogIf()

void TurtleBrains::Core::Debug::LogIf	(	const bool	testResult,
		const char *	formattedMessage,
			...
	)

Writes a message into the log, the message can be a formatted string behaving exactly like printf would, but does so only if the testResult is true. If test result is false no message gets displayed on stdout or the log.

Parameters

testResult	An expression that will result in a boolean, true or false, result. If true the message will output in the log and stdout, otherwise it will not be displayed.
formattedMessage	A string of characters of a formatted string that describes the variable arguments that follow. The formatted message and arguments are used exactly like printf() would be.
...	The variable arguments the fill in the formattedMessage string using the same printf() format.

Note

Prefer use of the macro tb_log so that nothing will happen, compiled out, if debugging is disabled by the tb_without_debug_set define fount in the tb_configuration.h file.

OpenLog()

void TurtleBrains::Core::Debug::OpenLog	(	const std::string &	logFile,
		bool	createConsoleWindow
	)

Opens a file to output the log at, and can, on Windows building with Visual CPP, open a console window for showing std out if the console parameter is passed as true.

Parameters

logFile	The filepath of the location to save the log file. This file will be cleared when loaded so the contents will only show a single run.
createConsoleWindow	Set to true this will attempt to create a console window. Currently only supported on Windows when building with Visual CPP.

ProjectEntryPoint() [1/2]

int TurtleBrains::Core::Debug::ProjectEntryPoint	(	int(*)(const int argumentCount, const char *argumentValues[])	entryPoint,
		const int	argumentCount,
		const char *	argumentValues[]
	)

Setups a special exception handler on Windows built with Visual CPP that will create a crash report with a callstack when an exception is thrown and caught within. For other platforms and compilers the exception will be caught but no crash report will be created as far as TurlteBrains v0.2.0. Hopeful future support.

Parameters

entryPoint	A function pointer to a function that takes an argumentCount and values parameters just like the would be passed to a main and returns an int: int foo(int c, char* v[]); that will be called after setting up an exception handler to create a crash report.
argumentCount	The number of values in the argumentValues array, typically just pass the same argumentCount you would get from main(int c, char* v[]);
argumentValues	The actual values of each argument as null-terminated strings, typically just pass the same argumentValues you would get from main(int c, char* v[]);

Note

Prefer use of the macro tb_debug_project_entry_point_with so that nothing will happen, compiled out, if debugging is disabled by the tb_without_debug_set define fount in the tb_configuration.h file.

ProjectEntryPoint() [2/2]

void TurtleBrains::Core::Debug::ProjectEntryPoint

(

void(*)(void)

entryPoint

)

Setups a special exception handler on Windows built with Visual CPP that will create a crash report with a callstack when an exception is thrown and caught within. For other platforms and compilers the exception will be caught but no crash report will be created as far as TurlteBrains v0.2.0. Hopeful future support.

Underneath this simply calls the Debug::ProjectEntryPoint() function, however the define should be preferred when you want to have the option of turning off all logging with the tb_without_debug_set define in the tb_configuration.h file.

Parameters

entryPoint

A function pointer to a function that takes no parameters and returns no parameters, void foo(void); that will be called after setting up an exception handler to create a crash report.

Note

Prefer use of the macro tb_debug_project_entry_point so that nothing will happen, compiled out, if debugging is disabled by the tb_without_debug_set define fount in the tb_configuration.h file.

SaveLog()

void TurtleBrains::Core::Debug::SaveLog

(

void

)

Saves the log file to disk to make sure any log messages have been flushed.

SetCrashReportFilepath()

void TurtleBrains::Core::Debug::SetCrashReportFilepath

(

const String &

reportFilepath = "crash_report.txt"

)

Changes the name and/or location the crash report will be saved to in the event of big unhandled issue. By default it is next to the executable as crash_report.txt. This should be set before ProjectEntryPoint is called, or the macro version.