Description

Functionality to debug/trace source code.

This system allows the programmer to insert traces inside portions of code (routines, methods, etc.) locally, i.e., activating/deactivating it independently in each portion. Also, all traces inside a given file can be deactivated globally if desired.

Usage:

For producing trace code, at the beginning of your .cpp, before including this header or any other that needs debugging, write:
#define ELE_PRE_TRACED
At the beginning of the piece of code you want to trace, place ELE_CODE_TRACE_ON;. Any routine to be traced needs this, i.e., both normal routines and lambdas.
At the point within that piece where you want to insert a trace, place ELE_CODE_TRACE({...RTTextWith...}, "...stream out sequence..."); or the simpler ELE_CODE_TRACEPOINT, if you need no message; or the most simple of all of ELE_CODE_TRACENUDE if you only need a message with no extra info.
At the point where you want to insert a pause for the user to enter anything, insert ELE_CODE_PAUSE({...RTTextWith...}, "... text ...");.
If you need some lines of code to be executed only in debugging mode, use ELE_CODE_TRACE_IF and ELE_CODE_TRACE_ENDIF to enclose them.
If, at a later time, you wish to deactivate just one of those traces, change ELE_CODE_TRACE by ELE_CODE_UNTRACE, ELE_CODE_TRACEPOINT by ELE_CODE_UNTRACEPOINT, or ELE_CODE_PAUSE by ELE_CODE_UNPAUSE. Also, an ELE_CODE_TRACE_IF can be individually disabled by substituting it by ELE_CODE_UNTRACE_IF.
For deactivating local traces within a piece of code without deleting them, use ELE_CODE_TRACE_OFF; instead of ELE_CODE_TRACE_ON;.
For deactivating all existing traces in a .cpp, comment out the #define ELE_PRE_TRACED at the beginning. This guarantess that no trace code will be included in the compiled program except the ones enclosed in ELE_CODE_TRACE_IF / ELE_CODE_TRACE_ENDIF.
These traces go to std::cout.

Example:

  \code
  "something.cpp":

  ...

  // This define has no effect in production mode:
  #define ELE_PRE_TRACED

  ...

  void afunction(void)
  {
  ELE_CODE_TRACE_ON; // This statement does not insert code here.

      // This trace may insert extra code even if ELE_CODE_TRACE_OFF:
      ELE_CODE_TRACE({RTTextWith::kTime},
                     "beginning with var = " << myvar);

      std::cout << "This routine is being traced..." << std::endl;

      // This particular trace has been deactivated, and does not
      // generate any code.
      ELE_CODE_UNTRACE({RTTextWith::kTime, RTTextWith::kThread},
                       "an old trace");
  }

  ...
  \endcode

Note: - In production mode (ELE_MAKE_PRODUCTION defined), all .cpp with ELE_PRE_TRACED defined will ignore those ELE_PRE_TRACED and will contain no tracing code at all.; - Not defining ELE_PRE_TRACED guarantees no trace code is generated in that .cpp, but setting ELE_CODE_TRACE_OFF locally may produce some code (e.g., previously to C++17; see the ELE_CODE_TRACE documentation). Anyway, ELE_CODE_UNTRACE never generates code, and the code enclosed in ELE_CODE_TRACE_IF / ENDIF will always be there although it may not execute, unless the compiler get rid of code guarded by an if (false).; - The piece of code being locally traced must be scoped, i.e., if it is not a routine, it must be enclosed within {}.; - ELE_CODE_TRACE_ON/OFF cannot be used more than once inside a piece of code.; - RTTextWith::kTime uses std::chrono::steady_clock as a clock and always shows time in microseconds.

See also: Errors

Author: Juan-Antonio Fernandez-Madrigal. http://jafma.net

Date: 2018-2019

Copyright: Copyright (c), Individual contributors, see AUTHORS file. This program is free for non-commercial uses. For the rest, contact the AUTHORS. Please include a mention in your programs to the main developer and the web page of the library.

Collaboration diagram for Debugging of code:

UTILITIES FOR SOURCE CODE INSPECTION IN RUN-TIME
constexpr char	elementa::base::kHiddenPlaceMsg [] = "place hidden in production"
	Constant text hiding runtime place when the program is in production. More...

	elementa::base::ELE_CLASS_ENUM (RTTextWith, kTime, kThread)
	Flags for selecting what to include in runtime text in addition to the place. More...

std::string	elementa::base::runtime_src_place (const std::string &place, const RTTextWithEnum::Combination &flags={}, const std::string &placepreff="Place:", const std::string &timepreff="Time:", const std::string &threadpreff="Thread:")
	Return a string with info about a place, time and thread during execution. More...

#define	ELE_PRE_FILELONGNAME std::string{__FILE__}
	Long name of the current source file, as a `std::string`. More...

#define	ELE_PRE_FILEBASENAME
	Base name of current src file (computed in runtime), as a `std::string`. More...

#define	ELE_CODE_PLACE
	Produces a `std::string` with the place of source where the macro is placed. More...

#define	ELE_CODE_LONGPLACE
	Produces a string with the place of source code where the macro is placed. More...

TRACING SYSTEM
#define	ELE_CODE_TRACE_ON
	Place this inside local scope (e.g., routine) to activate traces there. More...

#define	ELE_CODE_TRACE_OFF
	Place this inside local scope (e.g., routine) to deactivate traces there. More...

#define	ELE_CODE_TRACE_IF if (false) {
	Place this before a part of code that should be executed in debug only. More...

#define	ELE_CODE_TRACE_ELSE } else {
	Place this between if and endif. More...

#define	ELE_CODE_TRACE_ENDIF }
	Place this after a part of code that should be executed in debug only. More...

#define	ELE_PRE_TRACE_PREFFIX "--- TR : "
	Preffix added to any trace. More...

#define	ELE_CODE_TRACE(flags, ...) {}

#define	ELE_CODE_TRACEPOINT {}

#define	ELE_CODE_TRACENUDE(...) {}

#define	ELE_CODE_PAUSE(flags, ...) {}

#define	ELE_CODE_UNTRACE(flags, ...)
	Macro to use instead of an existing ELE_CODE_TRACE to deactivate that trace. More...

#define	ELE_CODE_UNTRACEPOINT
	Macro to use instead of an existing ELE_CODE_TRACEPOINT to deactivate it. More...

#define	ELE_CODE_UNPAUSE(flags, ...)
	Macro to use instead of an existing ELE_CODE_PAUSE to deactivate that trace. More...

#define	ELE_CODE_UNTRACE_IF if (false) {
	Macro to use instead of an existing ELE_CODE_TRACE_IF to deactivate it. More...

#define	ELE_CODE_UNTRACE_ELSE } else {
	Macro to use instead of an existing ELE_CODE_TRACE_ELSE to deactivate it. More...

#define	ELE_CODE_UNTRACE_ENDIF }
	Macro to use instead of an existing ELE_CODE_TRACE_ENDIF to deactivate it. More...

Macro Definition Documentation

◆ ELE_PRE_FILELONGNAME

#define ELE_PRE_FILELONGNAME std::string{__FILE__}

std::string elementa::base::runtime_src_place	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{}`,
		const std::string &	placepreff = `"Place:"`,
		const std::string &	timepreff = `"Time:"`,
		const std::string &	threadpreff = `"Thread:"`
	)

#define ELE_CODE_TRACE	(	flags,
		...
	)	{}

#define ELE_CODE_PAUSE	(	flags,
		...
	)	{}

#define ELE_CODE_UNTRACE	(	flags,
		...
	)

#define ELE_CODE_UNPAUSE	(	flags,
		...
	)

Description

UTILITIES FOR SOURCE CODE INSPECTION IN RUN-TIME

TRACING SYSTEM

Macro Definition Documentation

◆ ELE_PRE_FILELONGNAME

◆ ELE_PRE_FILEBASENAME

◆ ELE_CODE_PLACE

◆ ELE_CODE_LONGPLACE

◆ ELE_CODE_TRACE_ON

◆ ELE_CODE_TRACE_OFF

◆ ELE_CODE_TRACE_IF

◆ ELE_CODE_TRACE_ELSE

◆ ELE_CODE_TRACE_ENDIF

◆ ELE_PRE_TRACE_PREFFIX

◆ ELE_CODE_TRACE

◆ ELE_CODE_TRACEPOINT

◆ ELE_CODE_TRACENUDE

◆ ELE_CODE_PAUSE

◆ ELE_CODE_UNTRACE

◆ ELE_CODE_UNTRACEPOINT

◆ ELE_CODE_UNPAUSE

◆ ELE_CODE_UNTRACE_IF

◆ ELE_CODE_UNTRACE_ELSE

◆ ELE_CODE_UNTRACE_ENDIF

Function Documentation

◆ ELE_CLASS_ENUM()

◆ runtime_src_place()

Variable Documentation

◆ kHiddenPlaceMsg