guts
Loading...
Searching...
No Matches
Macros
gutsConventions.h File Reference

Common constants and console-formatting macros used across gutilities and related code. More...

#include <string>
Include dependency graph for gutsConventions.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define UNINITIALIZEDNUMBERQUANTITY   -123456
 Sentinel value representing an uninitialized numeric quantity.
 
#define UNINITIALIZEDSTRINGQUANTITY   "NULL"
 Sentinel string representing an uninitialized string quantity.
 
#define EC__FILENOTFOUND   301
 Process exit code used when an expected file cannot be opened or found.
 
#define EC__G4NUMBERERROR   302
 Process exit code used when parsing a Geant4-style numeric string fails.
 
#define KBOLD   "\x1B[1m"
 ANSI escape sequence for bold text.
 
#define KRED   "\x1B[31m"
 ANSI escape sequence for red foreground text.
 
#define KGRN   "\x1B[32m"
 ANSI escape sequence for green foreground text.
 
#define KYEL   "\x1B[33m"
 ANSI escape sequence for yellow foreground text.
 
#define KBLU   "\x1B[34m"
 ANSI escape sequence for blue foreground text.
 
#define KMAG   "\x1B[35m"
 ANSI escape sequence for magenta foreground text.
 
#define KCYN   "\x1B[36m"
 ANSI escape sequence for cyan foreground text.
 
#define KWHT   "\x1B[37m"
 ANSI escape sequence for white foreground text.
 
#define RST   "\x1B[0m"
 ANSI escape sequence to reset text formatting to defaults.
 
#define FRED(x)   KRED x RST
 Wrap x in red text and reset formatting afterwards.
 
#define FGRN(x)   KGRN x RST
 Wrap x in green text and reset formatting afterwards.
 
#define FYEL(x)   KYEL x RST
 Wrap x in yellow text and reset formatting afterwards.
 
#define FBLU(x)   KBLU x RST
 Wrap x in blue text and reset formatting afterwards.
 
#define FMAG(x)   KMAG x RST
 Wrap x in magenta text and reset formatting afterwards.
 
#define FCYN(x)   KCYN x RST
 Wrap x in cyan text and reset formatting afterwards.
 
#define FWHT(x)   KWHT x RST
 Wrap x in white text and reset formatting afterwards.
 
#define BOLD(x)   KBOLD x RST
 Wrap x in bold formatting and reset afterwards.
 
#define UNDL(x)   "\x1B[4m" x RST
 Wrap x in underline formatting and reset afterwards.
 
#define FATALERRORL   BOLD(FRED("Fatal Error: "))
 Standardized fatal error label prefix (bold red).
 
#define GWARNING   BOLD(FYEL("Warning: "))
 Standardized warning label prefix (bold yellow).
 
#define CONSTRUCTORLOG   "↑"
 Glyph used to annotate constructor log messages.
 
#define DESTRUCTORLOG   "↓"
 Glyph used to annotate destructor log messages.
 
#define POINTITEM   "•"
 Bullet glyph used for list formatting in console logs.
 
#define CIRCLEITEM   "◦"
 Hollow bullet glyph used for list formatting in console logs.
 
#define SQUAREITEM   "◻︎"
 Square glyph used for list formatting in console logs.
 
#define ARROWITEM   "➤"
 Arrow glyph used for list formatting in console logs.
 
#define GREENPOINTITEM   BOLD(FGRN(POINTITEM))
 Green point item.
 
#define GREENCIRCLEITEM   BOLD(FGRN(CIRCLEITEM))
 Green circle item.
 
#define GREENSQUAREITEM   BOLD(FGRN(SQUAREITEM))
 Green square item.
 
#define GREENARROWITEM   BOLD(FGRN(ARROWITEM))
 Green arrow item.
 
#define REDPOINTITEM   BOLD(FRED(POINTITEM))
 Red point item.
 
#define REDCIRCLEITEM   BOLD(FRED(CIRCLEITEM))
 Red circle item.
 
#define REDSQUAREITEM   BOLD(FRED(SQUAREITEM))
 Red square item.
 
#define REDARROWITEM   BOLD(FRED(ARROWITEM))
 Red arrow item.
 
#define GTAB   " "
 Standard indentation unit used by console-formatting macros.
 
#define GTABTAB   GTAB GTAB
 
#define GTABTABTAB   GTAB GTAB GTAB
 
#define GTABX4   GTABTABTAB GTAB
 
#define GTABX5   GTABX4 GTAB
 
#define GTABX6   GTABX5 GTAB
 
#define GTABX7   GTABX6 GTAB
 
#define GTABX8   GTABX7 GTAB
 
#define TPOINTITEM   GTAB POINTITEM
 Point item with single tab.
 
#define TCIRCLEITEM   GTAB CIRCLEITEM
 Circle item with single tab.
 
#define TSQUAREITEM   GTAB SQUAREITEM
 Square item with single tab.
 
#define TARROWITEM   GTAB ARROWITEM
 Arrow item with single tab.
 
#define TGREENPOINTITEM   GTAB GREENPOINTITEM
 Green point item with single tab.
 
#define TGREENCIRCLEITEM   GTAB GREENCIRCLEITEM
 Green circle item with single tab.
 
#define TGREENSQUAREITEM   GTAB GREENSQUAREITEM
 Green square item with single tab.
 
#define TGREENARROWITEM   GTAB GREENARROWITEM
 Green arrow item with single tab.
 
#define TREDPOINTITEM   GTAB REDPOINTITEM
 Red point item with single tab.
 
#define TREDCIRCLEITEM   GTAB REDCIRCLEITEM
 Red circle item with single tab.
 
#define TREDSQUAREITEM   GTAB REDSQUAREITEM
 Red square item with single tab.
 
#define TREDARROWITEM   GTAB REDARROWITEM
 Red arrow item with single tab.
 
#define TTPOINTITEM   GTABTAB POINTITEM
 Point item with double tab.
 
#define TTCIRCLEITEM   GTABTAB CIRCLEITEM
 Circle item with double tab.
 
#define TTSQUAREITEM   GTABTAB SQUAREITEM
 Square item with double tab.
 
#define TTARROWITEM   GTABTAB ARROWITEM
 Arrow item with double tab.
 
#define TTGREENPOINTITEM   GTABTAB GREENPOINTITEM
 Green point item with double tab.
 
#define TTGREENCIRCLEITEM   GTABTAB GREENCIRCLEITEM
 Green circle item with double tab.
 
#define TTGREENSQUAREITEM   GTABTAB GREENSQUAREITEM
 Green square item with double tab.
 
#define TTGREENARROWITEM   GTABTAB GREENARROWITEM
 Green arrow item with double tab.
 
#define TTREDPOINTITEM   GTABTAB REDPOINTITEM
 Red point item with double tab.
 
#define TTREDCIRCLEITEM   GTABTAB REDCIRCLEITEM
 Red circle item with double tab.
 
#define TTREDSQUAREITEM   GTABTAB REDSQUAREITEM
 Red square item with double tab.
 
#define TTREDARROWITEM   GTABTAB REDARROWITEM
 Red arrow item with double tab.
 
#define HHL   "⏵"
 Left highlight glyph.
 
#define HHR   "⏴"
 Right highlight glyph.
 
#define RSTHHR   HHR RST
 Reset highlight right.
 
#define GREENHHL   KGRN HHL
 Green highlight left.
 
#define REDHHL   KRED HHL
 Red highlight left.
 
#define YELLOWHHL   KYEL HHL
 Yellow highlight left.
 
#define BOLDWHHL   BOLD(HHL)
 Bold white highlight left.
 

Detailed Description

This header centralizes conventions that are intentionally shared across the project:

  • Sentinel values for "uninitialized" numeric and string quantities.
  • Exit codes used by fatal error handling paths.
  • ANSI escape sequences and helper macros for colored/bold/underlined console output.
  • Standardized glyphs used for list items and log decorations.

The goal is to keep error messages and console output consistent across all modules that rely on these utilities.

Note
These are macros on purpose: they are intended to be lightweight, header-only, and usable in low-level code paths (including error handling) without additional dependencies.

Definition in file gutsConventions.h.

Macro Definition Documentation

◆ ARROWITEM

#define ARROWITEM   "➤"

Symbol for arrow item.

Definition at line 252 of file gutsConventions.h.

◆ BOLD

#define BOLD ( x)    KBOLD x RST

Macro to wrap text in bold.

This is commonly composed with the color wrappers to produce prominent labels.

Definition at line 189 of file gutsConventions.h.

◆ BOLDWHHL

#define BOLDWHHL   BOLD(HHL)

Definition at line 331 of file gutsConventions.h.

◆ CIRCLEITEM

#define CIRCLEITEM   "◦"

Symbol for circle item.

Definition at line 240 of file gutsConventions.h.

◆ CONSTRUCTORLOG

#define CONSTRUCTORLOG   "↑"

Log symbol for constructor.

Definition at line 220 of file gutsConventions.h.

◆ DESTRUCTORLOG

#define DESTRUCTORLOG   "↓"

Log symbol for destructor.

Definition at line 226 of file gutsConventions.h.

◆ EC__FILENOTFOUND

#define EC__FILENOTFOUND   301

File not found error code.

This exit code is used by code paths that treat a missing file as fatal (i.e., cannot continue). It is intentionally stable so wrapper scripts and CI can classify failures.

Definition at line 59 of file gutsConventions.h.

◆ EC__G4NUMBERERROR

#define EC__G4NUMBERERROR   302

G4 number error code.

Used by utilities that parse "<number>*<unit>" style strings. Errors include:

  • Invalid numeric text
  • Missing or malformed separators
  • Structural format violations (e.g., multiple separators)

Definition at line 70 of file gutsConventions.h.

◆ FATALERRORL

#define FATALERRORL   BOLD(FRED("Fatal Error: "))

Fatal error label.

Typically used at the start of an error message sent to std::cerr, for example:

std::cerr << FATALERRORL << "something went wrong" << std::endl;
FATALERRORL
#define FATALERRORL
Standardized fatal error label prefix (bold red).
Definition gutsConventions.h:206

Definition at line 206 of file gutsConventions.h.

◆ FBLU

#define FBLU ( x)    KBLU x RST

Macro to wrap text in blue color.

Definition at line 163 of file gutsConventions.h.

◆ FCYN

#define FCYN ( x)    KCYN x RST

Macro to wrap text in cyan color.

Definition at line 175 of file gutsConventions.h.

◆ FGRN

#define FGRN ( x)    KGRN x RST

Macro to wrap text in green color.

Definition at line 151 of file gutsConventions.h.

◆ FMAG

#define FMAG ( x)    KMAG x RST

Macro to wrap text in magenta color.

Definition at line 169 of file gutsConventions.h.

◆ FRED

#define FRED ( x)    KRED x RST

Macro to wrap text in red color.

Parameters
xString literal to wrap (typically a short label).
Note
These macros operate on string literals; they are meant for building other labels and prefixes, not for formatting arbitrary runtime strings.

Definition at line 145 of file gutsConventions.h.

◆ FWHT

#define FWHT ( x)    KWHT x RST

Macro to wrap text in white color.

Definition at line 181 of file gutsConventions.h.

◆ FYEL

#define FYEL ( x)    KYEL x RST

Macro to wrap text in yellow color.

Definition at line 157 of file gutsConventions.h.

◆ GREENARROWITEM

#define GREENARROWITEM   BOLD(FGRN(ARROWITEM))

Definition at line 257 of file gutsConventions.h.

◆ GREENCIRCLEITEM

#define GREENCIRCLEITEM   BOLD(FGRN(CIRCLEITEM))

Definition at line 255 of file gutsConventions.h.

◆ GREENHHL

#define GREENHHL   KGRN HHL

Definition at line 328 of file gutsConventions.h.

◆ GREENPOINTITEM

#define GREENPOINTITEM   BOLD(FGRN(POINTITEM))

Definition at line 254 of file gutsConventions.h.

◆ GREENSQUAREITEM

#define GREENSQUAREITEM   BOLD(FGRN(SQUAREITEM))

Definition at line 256 of file gutsConventions.h.

◆ GTAB

#define GTAB   " "

Intended for human-readable, visually aligned console output. These are not meant to be used for machine-parsed logs.

Definition at line 272 of file gutsConventions.h.

◆ GTABTAB

#define GTABTAB   GTAB GTAB

Definition at line 273 of file gutsConventions.h.

◆ GTABTABTAB

#define GTABTABTAB   GTAB GTAB GTAB

Definition at line 274 of file gutsConventions.h.

◆ GTABX4

#define GTABX4   GTABTABTAB GTAB

Definition at line 275 of file gutsConventions.h.

◆ GTABX5

#define GTABX5   GTABX4 GTAB

Definition at line 276 of file gutsConventions.h.

◆ GTABX6

#define GTABX6   GTABX5 GTAB

Definition at line 277 of file gutsConventions.h.

◆ GTABX7

#define GTABX7   GTABX6 GTAB

Definition at line 278 of file gutsConventions.h.

◆ GTABX8

#define GTABX8   GTABX7 GTAB

Definition at line 279 of file gutsConventions.h.

◆ GWARNING

#define GWARNING   BOLD(FYEL("Warning: "))

Warning label.

Typically used at the start of a warning message sent to std::cerr.

Definition at line 214 of file gutsConventions.h.

◆ HHL

#define HHL   "⏵"

Highlight left symbol.

Used for lightweight highlighting in console output. Often paired with HHR.

Definition at line 317 of file gutsConventions.h.

◆ HHR

#define HHR   "⏴"

Highlight right symbol.

Used for lightweight highlighting in console output. Often paired with HHL.

Definition at line 325 of file gutsConventions.h.

◆ KBLU

#define KBLU   "\x1B[34m"

Definition at line 106 of file gutsConventions.h.

◆ KBOLD

#define KBOLD   "\x1B[1m"
Note
Bold support depends on the terminal emulator. On some terminals it may appear as increased brightness rather than a true bold weight.

Definition at line 82 of file gutsConventions.h.

◆ KCYN

#define KCYN   "\x1B[36m"

Definition at line 118 of file gutsConventions.h.

◆ KGRN

#define KGRN   "\x1B[32m"

Definition at line 94 of file gutsConventions.h.

◆ KMAG

#define KMAG   "\x1B[35m"

Definition at line 112 of file gutsConventions.h.

◆ KRED

#define KRED   "\x1B[31m"

Definition at line 88 of file gutsConventions.h.

◆ KWHT

#define KWHT   "\x1B[37m"

Definition at line 124 of file gutsConventions.h.

◆ KYEL

#define KYEL   "\x1B[33m"

Definition at line 100 of file gutsConventions.h.

◆ POINTITEM

#define POINTITEM   "•"

Symbol for point item.

Definition at line 234 of file gutsConventions.h.

◆ REDARROWITEM

#define REDARROWITEM   BOLD(FRED(ARROWITEM))

Definition at line 261 of file gutsConventions.h.

◆ REDCIRCLEITEM

#define REDCIRCLEITEM   BOLD(FRED(CIRCLEITEM))

Definition at line 259 of file gutsConventions.h.

◆ REDHHL

#define REDHHL   KRED HHL

Definition at line 329 of file gutsConventions.h.

◆ REDPOINTITEM

#define REDPOINTITEM   BOLD(FRED(POINTITEM))

Definition at line 258 of file gutsConventions.h.

◆ REDSQUAREITEM

#define REDSQUAREITEM   BOLD(FRED(SQUAREITEM))

Definition at line 260 of file gutsConventions.h.

◆ RST

#define RST   "\x1B[0m"

Use this after applying a color/attribute sequence to avoid "leaking" formatting into subsequent console output.

Definition at line 133 of file gutsConventions.h.

◆ RSTHHR

#define RSTHHR   HHR RST

Definition at line 327 of file gutsConventions.h.

◆ SQUAREITEM

#define SQUAREITEM   "◻︎"

Symbol for square item.

Definition at line 246 of file gutsConventions.h.

◆ TARROWITEM

#define TARROWITEM   GTAB ARROWITEM

Definition at line 285 of file gutsConventions.h.

◆ TCIRCLEITEM

#define TCIRCLEITEM   GTAB CIRCLEITEM

Definition at line 283 of file gutsConventions.h.

◆ TGREENARROWITEM

#define TGREENARROWITEM   GTAB GREENARROWITEM

Definition at line 289 of file gutsConventions.h.

◆ TGREENCIRCLEITEM

#define TGREENCIRCLEITEM   GTAB GREENCIRCLEITEM

Definition at line 287 of file gutsConventions.h.

◆ TGREENPOINTITEM

#define TGREENPOINTITEM   GTAB GREENPOINTITEM

Definition at line 286 of file gutsConventions.h.

◆ TGREENSQUAREITEM

#define TGREENSQUAREITEM   GTAB GREENSQUAREITEM

Definition at line 288 of file gutsConventions.h.

◆ TPOINTITEM

#define TPOINTITEM   GTAB POINTITEM

Definition at line 282 of file gutsConventions.h.

◆ TREDARROWITEM

#define TREDARROWITEM   GTAB REDARROWITEM

Definition at line 293 of file gutsConventions.h.

◆ TREDCIRCLEITEM

#define TREDCIRCLEITEM   GTAB REDCIRCLEITEM

Definition at line 291 of file gutsConventions.h.

◆ TREDPOINTITEM

#define TREDPOINTITEM   GTAB REDPOINTITEM

Definition at line 290 of file gutsConventions.h.

◆ TREDSQUAREITEM

#define TREDSQUAREITEM   GTAB REDSQUAREITEM

Definition at line 292 of file gutsConventions.h.

◆ TSQUAREITEM

#define TSQUAREITEM   GTAB SQUAREITEM

Definition at line 284 of file gutsConventions.h.

◆ TTARROWITEM

#define TTARROWITEM   GTABTAB ARROWITEM

Definition at line 299 of file gutsConventions.h.

◆ TTCIRCLEITEM

#define TTCIRCLEITEM   GTABTAB CIRCLEITEM

Definition at line 297 of file gutsConventions.h.

◆ TTGREENARROWITEM

#define TTGREENARROWITEM   GTABTAB GREENARROWITEM

Definition at line 303 of file gutsConventions.h.

◆ TTGREENCIRCLEITEM

#define TTGREENCIRCLEITEM   GTABTAB GREENCIRCLEITEM

Definition at line 301 of file gutsConventions.h.

◆ TTGREENPOINTITEM

#define TTGREENPOINTITEM   GTABTAB GREENPOINTITEM

Definition at line 300 of file gutsConventions.h.

◆ TTGREENSQUAREITEM

#define TTGREENSQUAREITEM   GTABTAB GREENSQUAREITEM

Definition at line 302 of file gutsConventions.h.

◆ TTPOINTITEM

#define TTPOINTITEM   GTABTAB POINTITEM

Definition at line 296 of file gutsConventions.h.

◆ TTREDARROWITEM

#define TTREDARROWITEM   GTABTAB REDARROWITEM

Definition at line 307 of file gutsConventions.h.

◆ TTREDCIRCLEITEM

#define TTREDCIRCLEITEM   GTABTAB REDCIRCLEITEM

Definition at line 305 of file gutsConventions.h.

◆ TTREDPOINTITEM

#define TTREDPOINTITEM   GTABTAB REDPOINTITEM

Definition at line 304 of file gutsConventions.h.

◆ TTREDSQUAREITEM

#define TTREDSQUAREITEM   GTABTAB REDSQUAREITEM

Definition at line 306 of file gutsConventions.h.

◆ TTSQUAREITEM

#define TTSQUAREITEM   GTABTAB SQUAREITEM

Definition at line 298 of file gutsConventions.h.

◆ UNDL

#define UNDL ( x)    "\x1B[4m" x RST

Macro to wrap text with underline.

Definition at line 195 of file gutsConventions.h.

◆ UNINITIALIZEDNUMBERQUANTITY

#define UNINITIALIZEDNUMBERQUANTITY   -123456

This constant is used when a numeric quantity is optional or not yet set and a distinct, easily-detectable value is needed. Typical examples include:

  • Configuration values that are optional and later validated.
  • "Not provided" values coming from parsing a text configuration.
Warning
Do not rely on this specific numeric value in persisted outputs; treat it as an internal sentinel only. If you need a persistent representation, serialize a dedicated "is set" flag or use a structured representation.

Definition at line 36 of file gutsConventions.h.

◆ UNINITIALIZEDSTRINGQUANTITY

#define UNINITIALIZEDSTRINGQUANTITY   "NULL"

This string literal is used as a conventional marker for unset/missing strings in configuration-like flows.

Matching rules across the utilities may treat common YAML "null" spellings (e.g., "null", "~") as equivalent; see the relevant parsing helpers for details.

Definition at line 48 of file gutsConventions.h.

◆ YELLOWHHL

#define YELLOWHHL   KYEL HHL

Definition at line 330 of file gutsConventions.h.