bump to v0.13
This commit is contained in:
parent
7955ec197f
commit
fee6c60176
202 changed files with 8389 additions and 1262 deletions
202
docs/index.html
202
docs/index.html
|
|
@ -5,7 +5,7 @@
|
|||
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||||
<meta name="generator" content="Doxygen 1.8.17"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||||
<title>clutchlog: Clutchlog — versatile (de)clutchable logging</title>
|
||||
<title>clutchlog: Clutchlog — versatile (de)clutchable spatial logging</title>
|
||||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||||
<script type="text/javascript" src="jquery.js"></script>
|
||||
<script type="text/javascript" src="dynsections.js"></script>
|
||||
|
|
@ -28,7 +28,7 @@
|
|||
<td id="projectlogo"><img alt="Logo" src="clutchlog_logo.svg"/></td>
|
||||
<td id="projectalign" style="padding-left: 0.5em;">
|
||||
<div id="projectname">clutchlog
|
||||
 <span id="projectnumber">0.12</span>
|
||||
 <span id="projectnumber">0.13</span>
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
|
|
@ -85,7 +85,7 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
|
|||
|
||||
<div class="PageDoc"><div class="header">
|
||||
<div class="headertitle">
|
||||
<div class="title">Clutchlog — versatile (de)clutchable logging </div> </div>
|
||||
<div class="title">Clutchlog — versatile (de)clutchable spatial logging </div> </div>
|
||||
</div><!--header-->
|
||||
<div class="contents">
|
||||
<div class="toc"><h3>Table of Contents</h3>
|
||||
|
|
@ -98,34 +98,37 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
|
|||
<li class="level2"><a href="#autotoc_md7">Output Configuration</a><ul><li class="level3"><a href="#autotoc_md8">Log Format</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="level2"><a href="#autotoc_md9">Output style</a></li>
|
||||
<li class="level2"><a href="#autotoc_md9">Output style</a><ul><li class="level3"><a href="#autotoc_md10">Typographic Style</a></li>
|
||||
<li class="level3"><a href="#autotoc_md11">Colors</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="level1"><a href="#autotoc_md10">Advanced Usage</a><ul><li class="level2"><a href="#autotoc_md11">More Output Configuration</a><ul><li class="level3"><a href="#autotoc_md12">Dump Format</a></li>
|
||||
<li class="level3"><a href="#autotoc_md13">Stack Depth Mark</a></li>
|
||||
<li class="level3"><a href="#autotoc_md14">Horizontal Filling</a></li>
|
||||
<li class="level3"><a href="#autotoc_md15">Stack Depth</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="level2"><a href="#autotoc_md16">Disabled calls</a></li>
|
||||
<li class="level2"><a href="#autotoc_md17">Low-level API</a></li>
|
||||
<li class="level2"><a href="#autotoc_md18">(De)clutch any function call</a></li>
|
||||
<li class="level2"><a href="#autotoc_md19">(De)clutch any code section</a></li>
|
||||
<li class="level1"><a href="#autotoc_md12">Advanced Usage</a><ul><li class="level2"><a href="#autotoc_md13">More Output Configuration</a><ul><li class="level3"><a href="#autotoc_md14">Dump Format</a></li>
|
||||
<li class="level3"><a href="#autotoc_md15">Stack Depth Mark</a></li>
|
||||
<li class="level3"><a href="#autotoc_md16">Horizontal Filling</a></li>
|
||||
<li class="level3"><a href="#autotoc_md17">Stack Depth</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="level1"><a href="#autotoc_md20">Examples</a></li>
|
||||
<li class="level1"><a href="#autotoc_md21">Limitations</a><ul><ul><li class="level3"><a href="#autotoc_md22">System-dependent stack depth</a></li>
|
||||
<li class="level3"><a href="#autotoc_md23">System-dependent horizontal fill</a></li>
|
||||
<li class="level3"><a href="#autotoc_md24">Dependencies</a></li>
|
||||
<li class="level3"><a href="#autotoc_md25">Variable names within the CLUTCHLOG macro</a></li>
|
||||
<li class="level3"><a href="#autotoc_md26">Features</a></li>
|
||||
<li class="level2"><a href="#autotoc_md18">Disabled calls</a></li>
|
||||
<li class="level2"><a href="#autotoc_md19">Low-level API</a></li>
|
||||
<li class="level2"><a href="#autotoc_md20">(De)clutch any function call</a></li>
|
||||
<li class="level2"><a href="#autotoc_md21">(De)clutch any code section</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="level1"><a href="#autotoc_md22">Examples</a></li>
|
||||
<li class="level1"><a href="#autotoc_md23">Limitations</a><ul><ul><li class="level3"><a href="#autotoc_md24">System-dependent stack depth</a></li>
|
||||
<li class="level3"><a href="#autotoc_md25">System-dependent horizontal fill</a></li>
|
||||
<li class="level3"><a href="#autotoc_md26">Dependencies</a></li>
|
||||
<li class="level3"><a href="#autotoc_md27">Variable names within the CLUTCHLOG macro</a></li>
|
||||
<li class="level3"><a href="#autotoc_md28">Features</a></li>
|
||||
</ul>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="level1"><a href="#autotoc_md27">Build and tests</a></li>
|
||||
<li class="level1"><a href="#autotoc_md29">Build and tests</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="textblock"><p><em><b>Clutchlog is a logging system that targets versatile debugging.</b></em> <em><b>It allows to (de)clutch messages for a given: log level, source code location or call stack depth.</b></em></p>
|
||||
<div class="textblock"><p><em><b>Clutchlog is a <em>spatial</em> logging system that targets versatile debugging.</b></em> <em><b>It allows to (de)clutch messages for a given: log level, source code location or call stack depth.</b></em></p>
|
||||
<ul>
|
||||
<li><a href="https://github.com/nojhan/clutchlog">Project page on Github</a></li>
|
||||
<li><a href="https://nojhan.github.io/clutchlog/">Documentation</a></li>
|
||||
|
|
@ -239,21 +242,59 @@ Log Format</h3>
|
|||
<h2><a class="anchor" id="autotoc_md9"></a>
|
||||
Output style</h2>
|
||||
<p>Output lines can be colored differently depending on the log level. </p><div class="fragment"><div class="line"><span class="comment">// Print error messages in bold red:</span></div>
|
||||
<div class="line">log.style(clutchlog::level::error, <span class="comment">// First, the log level.</span></div>
|
||||
<div class="line"> clutchlog::fmt::fg::red, <span class="comment">// Then the styles, in any order...</span></div>
|
||||
<div class="line"> clutchlog::fmt::typo::bold);</div>
|
||||
<div class="line">log.style(level::error, <span class="comment">// First, the log level.</span></div>
|
||||
<div class="line"> fmt::fg::red, <span class="comment">// Then the styles, in any order...</span></div>
|
||||
<div class="line"> fmt::typo::bold);</div>
|
||||
</div><!-- fragment --><p>Or, if you want to declare some semantics beforehand: </p><div class="fragment"><div class="line"><span class="comment">// Print warning messages in bold magenta:</span></div>
|
||||
<div class="line"><span class="keyword">using</span> fmt = <a class="code" href="classclutchlog_1_1fmt.html">clutchlog::fmt</a>;</div>
|
||||
<div class="line">fmt warn(fmt::fg::magenta, fmt::typo::bold);</div>
|
||||
<div class="line">log.style(clutchlog::level::warning, warn);</div>
|
||||
<div class="line">log.style(level::warning, warn);</div>
|
||||
</div><!-- fragment --><p>Note: this inserts a style marker at the very beginning of the line. If you add other styles later on the line, they will take precedence.</p>
|
||||
<p>Colors can be specified in several different ways. The ANSI color mode will be automatically detected, depending on the types of arguments passed to styling functions:</p><ul>
|
||||
<li>named tags from <code><a class="el" href="group__colors16.html#ga4662a3ec3577c6a575a2c734636ed8a0" title="Foreground color codes.">clutchlog::fmt::fg</a></code> or <code><a class="el" href="group__colors16.html#ga1cf3e27e4041250ffea0a6d58010da1e" title="Background color codes.">clutchlog::fmt::bg</a></code> will encode a 16-colors mode,</li>
|
||||
<li>integers will encode a 256-colors mode,</li>
|
||||
<li>numeric triplets or web hex strings will encode a 16 million ("true") colors mode,</li>
|
||||
<li><code>clutchlog::fg::none</code> and <code>clutchlog::bg::none</code> can be passed in all modes.</li>
|
||||
</ul>
|
||||
<p>For example, all the following lines encode a bright red foreground for the critical level: </p><div class="fragment"><div class="line">log.style(level:critical,</div>
|
||||
<div class="line"> fmt::fg::red); <span class="comment">// 16-colors mode.</span></div>
|
||||
<div class="line">log.style(level:critical,</div>
|
||||
<div class="line"> 255); <span class="comment">// 256-colors mode.</span></div>
|
||||
<div class="line">log.style(level:critical,</div>
|
||||
<div class="line"> 255,0,0); <span class="comment">// 16M-colors mode.</span></div>
|
||||
<div class="line">log.style(level:critical,</div>
|
||||
<div class="line"> <span class="stringliteral">"#ff0000"</span>); <span class="comment">// 16M-colors mode again.</span></div>
|
||||
</div><!-- fragment --><p>You may use styling within the format message template itself, to add even more colors: </p><div class="fragment"><div class="line"><span class="keyword">using</span> fmt = <a class="code" href="classclutchlog_1_1fmt.html">clutchlog::fmt</a>;</div>
|
||||
<div class="line">std::ostringstream format;</div>
|
||||
<div class="line">fmt discreet(fmt::fg::blue);</div>
|
||||
<div class="line">format << <span class="stringliteral">"{level}: "</span></div>
|
||||
<div class="line"> << discreet(<span class="stringliteral">"{file}:"</span>) <span class="comment">// Used as a function (inserts a reset at the end).</span></div>
|
||||
<div class="line"> << fmt(fmt::fg::yellow) << <span class="stringliteral">"{line}"</span> <span class="comment">// Used as a tag (no reset inserted).</span></div>
|
||||
<div class="line"> << fmt(fmt::typo::reset) << <span class="stringliteral">" {msg}"</span> << std::endl; <span class="comment">// This is a reset.</span></div>
|
||||
<div class="line">log.format(format.str());</div>
|
||||
</div><!-- fragment --><p>Note: messages at the "critical", "error" and "warning" log levels are colored by default. You may want to set their style to <code>none</code> if you want to stay in control of inserted colors in the format template.</p>
|
||||
<p>The horizontal filling line (the <code>{hfill}</code> tag) can be configured separately with <code>clutchlog::hfill_style</code>, for example: </p><div class="fragment"><div class="line">log.hfill_style(fmt::fg::black);</div>
|
||||
</div><!-- fragment --><p>Note: this will actually reset any styling after the hfill, disabling any style you would have set for the whole message using <code><a class="el" href="classclutchlog.html#a656c277e074b64728cca871f2b484d1c" title="Set the template string.">clutchlog::format</a></code> for the remaining of the message.</p>
|
||||
<h3><a class="anchor" id="autotoc_md10"></a>
|
||||
Typographic Style</h3>
|
||||
<p>Available typographies:</p>
|
||||
<ul>
|
||||
<li>reset (remove any style),</li>
|
||||
<li>bold,</li>
|
||||
<li>underline,</li>
|
||||
<li>inverse,</li>
|
||||
<li>none.</li>
|
||||
</ul>
|
||||
<p>Typographic styles are always passed with the named tag (see <code><a class="el" href="classclutchlog_1_1fmt.html#a932f47b78fb7b10590d5613a1c4eab89" title="Typographic style codes.">clutchlog::fmt::typo</a></code>), whatever the color mode.</p>
|
||||
<h3><a class="anchor" id="autotoc_md11"></a>
|
||||
Colors</h3>
|
||||
<h4>16-colors mode</h4>
|
||||
<p>Using the <code><a class="el" href="classclutchlog_1_1fmt.html" title="Color and style formatter for ANSI terminal escape sequences.">clutchlog::fmt</a></code> class, you can style:</p>
|
||||
<ul>
|
||||
<li>the foreground color, passing a <code><a class="el" href="classclutchlog_1_1fmt.html#a4662a3ec3577c6a575a2c734636ed8a0" title="Foreground color codes.">clutchlog::fmt::fg</a></code>,</li>
|
||||
<li>the background color, passing a <code><a class="el" href="classclutchlog_1_1fmt.html#a1cf3e27e4041250ffea0a6d58010da1e" title="Background color codes.">clutchlog::fmt::bg</a></code>,</li>
|
||||
<li>some typographic style, passing a <code><a class="el" href="classclutchlog_1_1fmt.html#a932f47b78fb7b10590d5613a1c4eab89" title="Typographic style codes.">clutchlog::fmt::typo</a></code>.</li>
|
||||
<li>the foreground color, passing a <code><a class="el" href="group__colors16.html#ga4662a3ec3577c6a575a2c734636ed8a0" title="Foreground color codes.">clutchlog::fmt::fg</a></code>,</li>
|
||||
<li>the background color, passing a <code><a class="el" href="group__colors16.html#ga1cf3e27e4041250ffea0a6d58010da1e" title="Background color codes.">clutchlog::fmt::bg</a></code>.</li>
|
||||
</ul>
|
||||
<p>Any of the three arguments may be passed, in any order, if an argument is omitted, it defaults to no color/style.</p>
|
||||
<p>In 16-colors mode, any of the arguments may be passed, in any order, if an argument is omitted, it defaults to no color/style.</p>
|
||||
<p>Available colors are:</p>
|
||||
<ul>
|
||||
<li>black,</li>
|
||||
|
|
@ -264,49 +305,53 @@ Output style</h2>
|
|||
<li>magenta,</li>
|
||||
<li>cyan,</li>
|
||||
<li>white,</li>
|
||||
<li>bright_black,</li>
|
||||
<li>bright_red,</li>
|
||||
<li>bright_green,</li>
|
||||
<li>bright_yellow,</li>
|
||||
<li>bright_blue,</li>
|
||||
<li>bright_magenta,</li>
|
||||
<li>bright_cyan,</li>
|
||||
<li>bright_white,</li>
|
||||
<li>none.</li>
|
||||
</ul>
|
||||
<p>Available typographies:</p>
|
||||
<ul>
|
||||
<li>reset (remove any style),</li>
|
||||
<li>bold,</li>
|
||||
<li>underline,</li>
|
||||
<li>inverse,</li>
|
||||
<li>none.</li>
|
||||
<p>Note: some terminals allow the user to configure the actual encoding of those colors. You may thus notice some difference with the expected rendering of the same colors encoded in the other modes. Use the other color modes if you want to fully control the actual color rendering.</p>
|
||||
<h4>256-colors mode</h4>
|
||||
<p>For 256-colors mode, colors are expected to be passed as integers in [-1,255] or the <code>fg::none</code> and <code>bg::none</code> tags.</p>
|
||||
<p>In 256-colors mode, if you want to only encode the background color, you cannot just omit the foreground color, you have to bass a <code>fg::none</code> tag as first argument.</p>
|
||||
<div class="fragment"><div class="line">log.style(level::info, fg::none, 52); <span class="comment">// No color over dark red.</span></div>
|
||||
<div class="line">log.style(level::info, fg::none, 52, typo::bold); <span class="comment">// No color over bold dark red.</span></div>
|
||||
</div><!-- fragment --><h4>16 million colors mode (RGB)</h4>
|
||||
<p>For 16M-colors mode, colors can be encoded as:</p><ul>
|
||||
<li>three integer arguments,</li>
|
||||
<li>a "web color" hexadecimal triplet string, starting with a leading number sign (e.g. "#0055ff").</li>
|
||||
<li>the <code>fg::none</code> and <code>bg::none</code> tags.</li>
|
||||
</ul>
|
||||
<p>You may use styling within the format message template itself, to add even more colors: </p><div class="fragment"><div class="line"><span class="keyword">using</span> fmt = <a class="code" href="classclutchlog_1_1fmt.html">clutchlog::fmt</a>;</div>
|
||||
<div class="line">std::ostringstream format;</div>
|
||||
<div class="line">fmt discreet(fmt::fg::blue);</div>
|
||||
<div class="line">format << <span class="stringliteral">"{level}: "</span></div>
|
||||
<div class="line"> << discreet(<span class="stringliteral">"{file}:"</span>) <span class="comment">// Used as a function (inserts a reset at the end).</span></div>
|
||||
<div class="line"> << fmt(fmt::fg::yellow) << <span class="stringliteral">"{line}"</span> <span class="comment">// Used as a tag (no reset inserted).</span></div>
|
||||
<div class="line"> << fmt(fmt::typo::reset) << <span class="stringliteral">" {msg}"</span> << std::endl; <span class="comment">// This is a reset.</span></div>
|
||||
<div class="line">log.format(format.str());</div>
|
||||
</div><!-- fragment --><p>Note: messages at the "critical", "error" and "warning" log levels are colored by default. You may want to set their style to <code>none</code> if you want to stay in control of inserted colors in the format template.</p>
|
||||
<p>The horizontal filling line (the <code>{hfill}</code> tag) can be configured separately with <code>clutchlog::hfill_style</code>, for example: </p><div class="fragment"><div class="line">log.hfill_style(clutchlog::fmt::fg::black);</div>
|
||||
</div><!-- fragment --><p>Note: this will actually reset any styling after the hfill, disabling any style you would have set for the whole message using <code><a class="el" href="classclutchlog.html#a656c277e074b64728cca871f2b484d1c" title="Set the template string.">clutchlog::format</a></code> for the remaining of the message.</p>
|
||||
<h1><a class="anchor" id="autotoc_md10"></a>
|
||||
<p>In 16M-colors mode, if you want to only encode the background color, you cannot just omit the foreground color, you have to pass a <code>fg::none</code> tag as first argument.</p>
|
||||
<div class="fragment"><div class="line">log.style(level::info, fg::none, 100,0,0); <span class="comment">// No color over dark red.</span></div>
|
||||
<div class="line">log.style(level::info, fg::none, 100,0,0, typo::bold); <span class="comment">// No color over bold dark red.</span></div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md12"></a>
|
||||
Advanced Usage</h1>
|
||||
<h2><a class="anchor" id="autotoc_md11"></a>
|
||||
<h2><a class="anchor" id="autotoc_md13"></a>
|
||||
More Output Configuration</h2>
|
||||
<h3><a class="anchor" id="autotoc_md12"></a>
|
||||
<h3><a class="anchor" id="autotoc_md14"></a>
|
||||
Dump Format</h3>
|
||||
<p>The default format of the first line of comment added with the dump macro is <code>"# [{name}] {level} in {func} (at depth {depth}) @ {file}:{line}"</code>. It can be edited with the <code>format_comment</code> method. If it is set to an empty string, then no comment line is added. The default can be modified at compile time with <code>CLUTCHDUMP_DEFAULT_FORMAT</code>.</p>
|
||||
<p>By default, the separator between items in the container is a new line. To change this behaviour, you can change <code>CLUTCHDUMP_DEFAULT_SEP</code> or call the low-level <code>dump</code> method.</p>
|
||||
<p>By default, and if <code>CLUTCHDUMP_DEFAULT_FORMAT</code> is not defined, clutchlog will not put the location-related tags in the message formats (i.e. <code>{file}</code> and <code>{line}</code>) when not in Debug builds.</p>
|
||||
<h3><a class="anchor" id="autotoc_md13"></a>
|
||||
<h3><a class="anchor" id="autotoc_md15"></a>
|
||||
Stack Depth Mark</h3>
|
||||
<p>The mark used with the <code>{depth_marks}</code> tag can be configured with the <code>clutchlog::depth_mark</code> method, and its default with the <code>CLUTCHLOG_DEFAULT_DEPTH_MARK</code> macro: </p><div class="fragment"><div class="line">log.depth_mark(<a class="code" href="group___default_config.html#ga45c4c964fad4ad1641d5c9c28c4645b9">CLUTCHLOG_DEFAULT_DEPTH_MARK</a>); <span class="comment">// Defaults to ">".</span></div>
|
||||
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md14"></a>
|
||||
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md16"></a>
|
||||
Horizontal Filling</h3>
|
||||
<p>The character used with the <code>{hfill}</code> tag can be configured wth the <code>clutchlog::hfill_mark</code> method, and its default with the <code>CLUTCHLOG_DEFAULT_HFILL_MARK</code> macro: </p><div class="fragment"><div class="line">log.hfill_mark(<a class="code" href="group___default_config.html#ga4eda0c1bfded5df89351b8ce8b9c2805">CLUTCHLOG_DEFAULT_HFILL_MARK</a>); <span class="comment">// Defaults to '.'.</span></div>
|
||||
</div><!-- fragment --><p>Clutchlog measures the width of the <em>standard error</em> channel. If it is redirected, it may be measured as very large (or very small). Thus, the <code>clutchlog::hfill_min</code> <code>clutchlog::hfill_max</code> accessors allow to set a minimum and a maximum width (in number of characters). </p><div class="fragment"><div class="line">log.hfill_max(CLUTCHLOG_DEFAULT_HFILL_MAX); <span class="comment">// Defaults to 300.</span></div>
|
||||
<div class="line">log.hfill_max(CLUTCHLOG_DEFAULT_HFILL_MIN); <span class="comment">// Defaults to 150.</span></div>
|
||||
<div class="line">log.hfill_min(CLUTCHLOG_DEFAULT_HFILL_MIN); <span class="comment">// Defaults to 150.</span></div>
|
||||
</div><!-- fragment --><p>Note: clutchlog will use the measured width, unless it goes out of <code>[clutchlog::hfill_min,clutchlog::hfill_max]</code>, in which case it will be caped to those bounds.</p>
|
||||
<h3><a class="anchor" id="autotoc_md15"></a>
|
||||
<h3><a class="anchor" id="autotoc_md17"></a>
|
||||
Stack Depth</h3>
|
||||
<p>By default, clutchlog removes 5 levels of the calls stack, so that your <code>main</code> entrypoint corresponds to a depth of zero. You can change this behaviour by defining the <code>CLUTCHLOG_STRIP_CALLS</code> macro, or calling <code>clutchlog::strip_calls</code>. </p><div class="fragment"><div class="line">log.strip_calls(<a class="code" href="group___default_config.html#ga98f30d814d4913a8a7c93a8793f49adf">CLUTCHLOG_STRIP_CALLS</a>); <span class="comment">// Defaults to 5.</span></div>
|
||||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md16"></a>
|
||||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md18"></a>
|
||||
Disabled calls</h2>
|
||||
<p>By default, clutchlog is always enabled if the <code>NDEBUG</code> preprocessor variable is not defined (this variable is set by CMake in build types that differs from <code>Debug</code>).</p>
|
||||
<p>You can however force clutchlog to be enabled in any build type by setting the <code>WITH_CLUTCHLOG</code> preprocessor variable.</p>
|
||||
|
|
@ -315,7 +360,7 @@ Disabled calls</h2>
|
|||
<div class="line"><span class="preprocessor">#define CLUTCHLOG_DEFAULT_DEPTH_BUILT_NODEBUG clutchlog::level::xdebug</span></div>
|
||||
</div><!-- fragment --><p>Note that allowing a log level does not mean that it will actually output something. If the configured log level at runtime is lower than the log level of the message, it will still not be printed.</p>
|
||||
<p>This behavior intend to remove as many conditional statements as possible when not debugging, without having to use preprocessor guards around calls to clutchlog, thus saving run time at no readability cost.</p>
|
||||
<h2><a class="anchor" id="autotoc_md17"></a>
|
||||
<h2><a class="anchor" id="autotoc_md19"></a>
|
||||
Low-level API</h2>
|
||||
<p>All configuration setters have a getters counterpart, with the same name but taking no parameter, for example: </p><div class="fragment"><div class="line">std::string mark = log.depth_mark();</div>
|
||||
</div><!-- fragment --><p>To control more precisely the logging, one can use the low-level <code><a class="el" href="classclutchlog.html#a23dbb98f0d3c5cc21c232cde16cf317a" title="Print a log message IF the location matches the given one.">clutchlog::log</a></code> method: </p><div class="fragment"><div class="line">log.log(clutchlog::level::xdebug, <span class="stringliteral">"hello world"</span>, <span class="stringliteral">"main.cpp"</span>, <span class="stringliteral">"main"</span>, 122);</div>
|
||||
|
|
@ -323,18 +368,18 @@ Low-level API</h2>
|
|||
</div><!-- fragment --><p>A similar <code>dump</code> method exists: </p><div class="fragment"><div class="line">log.dump(clutchlog::level::xdebug, cont.begin(), cont.end(), <a class="code" href="group___use_macros.html#gae8911119d726a43b77f5781cb5a72813">CLUTCHLOC</a>, <span class="stringliteral">"dumped_{n}.dat"</span>, <span class="stringliteral">"\n"</span>);</div>
|
||||
<div class="line">log.dump(clutchlog::level::xdebug, cont.begin(), cont.end(), <span class="stringliteral">"main.cpp"</span>, <span class="stringliteral">"main"</span>, 122, <span class="stringliteral">"dumped.dat"</span>, <span class="stringliteral">"\n\n"</span>);</div>
|
||||
</div><!-- fragment --><p>You can access the identifier of log levels with <code><a class="el" href="classclutchlog.html#acebed8c9df9204f22bf8488e62e1cedd" title="Return the log level tag corresponding to the given pre-configured name.">clutchlog::level_of</a></code>: </p><div class="fragment"><div class="line">log.threshold( log.level_of(<span class="stringliteral">"XDebug"</span>) ); <span class="comment">// You have to know the exact string.</span></div>
|
||||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md18"></a>
|
||||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md20"></a>
|
||||
(De)clutch any function call</h2>
|
||||
<p>The <code>CLUTHFUNC</code> macro allows to wrap any function within the current logger.</p>
|
||||
<p>For instance, this can be useful if you want to (de)clutch calls to <code>assert</code>s. To do that, just declare your own macro: </p><div class="fragment"><div class="line"><span class="preprocessor">#define ASSERT(...) { CLUTCHFUNC(error, assert, __VA_ARGS__) }</span></div>
|
||||
</div><!-- fragment --><p>Thus, any call like <code>ASSERT(x > 3);</code> will be declutchable with the same configuration than a call to <code>CLUTCHLOG</code>.</p>
|
||||
<h2><a class="anchor" id="autotoc_md19"></a>
|
||||
<h2><a class="anchor" id="autotoc_md21"></a>
|
||||
(De)clutch any code section</h2>
|
||||
<p>The <code>CLUTCHCODE</code> macro allows to wrap any code within the current logger.</p>
|
||||
<p>For instance: </p><div class="fragment"><div class="line"><a class="code" href="group___use_macros.html#gaaf2e85e1153e6c88b458dd49e3c37c73">CLUTCHCODE</a>(info,</div>
|
||||
<div class="line"> std::clog << <span class="stringliteral">"We are clutched!\n"</span>;</div>
|
||||
<div class="line">);</div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md20"></a>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md22"></a>
|
||||
Examples</h1>
|
||||
<p>Here what you would do to setup clutchlog with the default configuration: </p><div class="fragment"><div class="line"><span class="keyword">auto</span>& log = <a class="code" href="classclutchlog.html#acfaceb77da01503b432644a3efaee4fa">clutchlog::logger</a>();</div>
|
||||
<div class="line">log.out(std::clog);</div>
|
||||
|
|
@ -381,28 +426,53 @@ Examples</h1>
|
|||
<div class="line"><span class="comment">// Declutchable asserts.</span></div>
|
||||
<div class="line"><span class="preprocessor">#define ASSERT(...) { CLUTCHFUNC(critical, assert, __VA_ARGS__) }</span></div>
|
||||
<div class="line"><span class="preprocessor">ASSERT(x>0);</span></div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md21"></a>
|
||||
</div><!-- fragment --><p>Here what you would do to setup clutchlog with the default configuration using 16M-colors mode: </p><div class="fragment"><div class="line"><span class="keyword">auto</span>& log = <a class="code" href="classclutchlog.html#acfaceb77da01503b432644a3efaee4fa">clutchlog::logger</a>();</div>
|
||||
<div class="line">log.out(std::clog);</div>
|
||||
<div class="line"><span class="comment">// Location filtering.</span></div>
|
||||
<div class="line">log.depth(std::numeric_limits<size_t>::max());</div>
|
||||
<div class="line">log.threshold(<span class="stringliteral">"Error"</span>);</div>
|
||||
<div class="line">log.file(<span class="stringliteral">".*"</span>);</div>
|
||||
<div class="line">log.func(<span class="stringliteral">".*"</span>);</div>
|
||||
<div class="line">log.line(<span class="stringliteral">".*"</span>);</div>
|
||||
<div class="line"><span class="comment">// Colors of the 3 firsts levels.</span></div>
|
||||
<div class="line">log.style(clutchlog::level::critical, <a class="code" href="classclutchlog_1_1fmt.html">clutchlog::fmt</a>(</div>
|
||||
<div class="line"> <span class="stringliteral">"#ff0000"</span>,</div>
|
||||
<div class="line"> clutchlog::fmt::typo::underline);</div>
|
||||
<div class="line">log.<a class="code" href="classclutchlog_1_1fmt.html#a2bb0fde65fcd264393e102314dd1610b">style</a>(clutchlog::level::error, <a class="code" href="classclutchlog_1_1fmt.html">clutchlog::fmt</a>(</div>
|
||||
<div class="line"> <span class="stringliteral">"#ff0000"</span>,</div>
|
||||
<div class="line"> clutchlog::fmt::typo::bold);</div>
|
||||
<div class="line">log.<a class="code" href="classclutchlog_1_1fmt.html#a2bb0fde65fcd264393e102314dd1610b">style</a>(clutchlog::level::warning, <a class="code" href="classclutchlog_1_1fmt.html">clutchlog::fmt</a>(</div>
|
||||
<div class="line"> <span class="stringliteral">"#ff00ff"</span>,</div>
|
||||
<div class="line"> clutchlog::fmt::typo::bold);</div>
|
||||
<div class="line"><span class="comment">// Assuming you are on a POSIX system.</span></div>
|
||||
<div class="line">log.format(<span class="stringliteral">"[{name}] {level_letter}:{depth_marks} {msg} {hfill} {func} @ {file}:{line}\n"</span>);</div>
|
||||
<div class="line">log.depth_mark(<span class="stringliteral">">"</span>);</div>
|
||||
<div class="line">log.strip_calls(5);</div>
|
||||
<div class="line">log.hfill_char(<span class="charliteral">'.'</span>);</div>
|
||||
<div class="line">log.hfill_max(300);</div>
|
||||
<div class="line">log.hfill_style(clutchlog::fmt::fg::none);</div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md23"></a>
|
||||
Limitations</h1>
|
||||
<h3><a class="anchor" id="autotoc_md22"></a>
|
||||
<h3><a class="anchor" id="autotoc_md24"></a>
|
||||
System-dependent stack depth</h3>
|
||||
<p>Because access to the call stack depth and program name are system-dependent, the features relying on the depth of the call stack and the display of the program name are only available for operating systems having the following headers: <code>execinfo.h</code>, <code>stdlib.h</code> and <code>libgen.h</code> (so far, tested with Linux).</p>
|
||||
<p>Clutchlog sets the <code>CLUTCHLOG_HAVE_UNIX_SYSINFO</code> to 1 if the headers are available, and to 0 if they are not. You can make portable code using something like: </p><div class="fragment"><div class="line"><span class="preprocessor">#if CLUTCHLOG_HAVE_UNIX_SYSINFO == 1</span></div>
|
||||
<div class="line"> log.depth( x );</div>
|
||||
<div class="line"><span class="preprocessor">#endif </span></div>
|
||||
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md23"></a>
|
||||
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md25"></a>
|
||||
System-dependent horizontal fill</h3>
|
||||
<p>Because access to the current terminal width is system-dependent, the <code>{hfill}</code> format tag feature is only available for operating systems having the following headers: <code>sys/ioctl.h</code>, <code>stdio.h</code> and <code>unistd.h</code> (so far, tested with Linux).</p>
|
||||
<p>Clutchlog sets the <code>CLUTCHLOG_HAVE_UNIX_SYSIOCTL</code> to 1 if the headers are available, and to 0 if they are not. You can make portable code using something like: </p><div class="fragment"><div class="line"><span class="preprocessor">#if CLUTCHLOG_HAVE_UNIX_SYSIOCTL == 1</span></div>
|
||||
<div class="line"> log.hfill_mark( <span class="charliteral">'_'</span> );</div>
|
||||
<div class="line"><span class="preprocessor">#endif </span></div>
|
||||
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md24"></a>
|
||||
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md26"></a>
|
||||
Dependencies</h3>
|
||||
<p>Some colors/styles may not be supported by some exotic terminal emulators.</p>
|
||||
<p>Clutchlog needs <code>C++-17</code> with the <code>filesystem</code> feature. You may need to indicate <code>-std=c++17 -lstdc++fs</code> to some compilers.</p>
|
||||
<h3><a class="anchor" id="autotoc_md25"></a>
|
||||
<h3><a class="anchor" id="autotoc_md27"></a>
|
||||
Variable names within the CLUTCHLOG macro</h3>
|
||||
<p>Calling the <code>CLUTCHLOG</code> macro with a message using a variable named <code>clutchlog__msg</code> will end in an error.</p>
|
||||
<h3><a class="anchor" id="autotoc_md26"></a>
|
||||
<h3><a class="anchor" id="autotoc_md28"></a>
|
||||
Features</h3>
|
||||
<p>What Clutchlog do not provide at the moment (but may in a near future):</p>
|
||||
<ul>
|
||||
|
|
@ -418,7 +488,7 @@ Features</h3>
|
|||
<li>Automatic argument parser (please, use a dedicated lib).</li>
|
||||
<li>Signal handling (WTF would you do that, anyway?).</li>
|
||||
</ul>
|
||||
<h1><a class="anchor" id="autotoc_md27"></a>
|
||||
<h1><a class="anchor" id="autotoc_md29"></a>
|
||||
Build and tests</h1>
|
||||
<p>To use clutchlog, just include its header in your code and either ensure that the <code>NDEBUG</code> preprocessor variable is not set, either define the <code>WITH_CLUTCHLOG</code> preprocessor variable.</p>
|
||||
<p>If you're using CMake (or another modern build system), it will unset <code>NDEBUG</code> —and thus enable clutchlog— only for the "Debug" build type, which is usually what you want if you use clutchlog, anyway.</p>
|
||||
|
|
@ -435,7 +505,7 @@ Build and tests</h1>
|
|||
<div class="ttc" id="aclassclutchlog_1_1fmt_html_a2bb0fde65fcd264393e102314dd1610b"><div class="ttname"><a href="classclutchlog_1_1fmt.html#a2bb0fde65fcd264393e102314dd1610b">clutchlog::fmt::style</a></div><div class="ttdeci">enum clutchlog::fmt::typo style</div><div class="ttdoc">Typographic style.</div></div>
|
||||
<div class="ttc" id="agroup___use_macros_html_ga572e3aa19d8b39e3ed0b9e91961104c2"><div class="ttname"><a href="group___use_macros.html#ga572e3aa19d8b39e3ed0b9e91961104c2">CLUTCHDUMP</a></div><div class="ttdeci">#define CLUTCHDUMP(LEVEL, CONTAINER, FILENAME)</div><div class="ttdoc">Dump the given container.</div><div class="ttdef"><b>Definition:</b> <a href="clutchlog_8h_source.html#l00098">clutchlog.h:98</a></div></div>
|
||||
<div class="ttc" id="aclassclutchlog_html_acfaceb77da01503b432644a3efaee4fa"><div class="ttname"><a href="classclutchlog.html#acfaceb77da01503b432644a3efaee4fa">clutchlog::logger</a></div><div class="ttdeci">static clutchlog & logger()</div><div class="ttdoc">Get the logger instance.</div><div class="ttdef"><b>Definition:</b> <a href="clutchlog_8h_source.html#l00296">clutchlog.h:296</a></div></div>
|
||||
<div class="ttc" id="aclassclutchlog_1_1fmt_html"><div class="ttname"><a href="classclutchlog_1_1fmt.html">clutchlog::fmt</a></div><div class="ttdoc">Color and style formatter for ANSI terminal escape sequences.</div><div class="ttdef"><b>Definition:</b> <a href="clutchlog_8h_source.html#l00314">clutchlog.h:314</a></div></div>
|
||||
<div class="ttc" id="aclassclutchlog_1_1fmt_html"><div class="ttname"><a href="classclutchlog_1_1fmt.html">clutchlog::fmt</a></div><div class="ttdoc">Color and style formatter for ANSI terminal escape sequences.</div><div class="ttdef"><b>Definition:</b> <a href="clutchlog_8h_source.html#l00366">clutchlog.h:366</a></div></div>
|
||||
<div class="ttc" id="agroup___use_macros_html_gae8911119d726a43b77f5781cb5a72813"><div class="ttname"><a href="group___use_macros.html#gae8911119d726a43b77f5781cb5a72813">CLUTCHLOC</a></div><div class="ttdeci">#define CLUTCHLOC</div><div class="ttdoc">Handy shortcuts to location.</div><div class="ttdef"><b>Definition:</b> <a href="clutchlog_8h_source.html#l00077">clutchlog.h:77</a></div></div>
|
||||
<div class="ttc" id="agroup___default_config_html_ga4eda0c1bfded5df89351b8ce8b9c2805"><div class="ttname"><a href="group___default_config.html#ga4eda0c1bfded5df89351b8ce8b9c2805">CLUTCHLOG_DEFAULT_HFILL_MARK</a></div><div class="ttdeci">#define CLUTCHLOG_DEFAULT_HFILL_MARK</div><div class="ttdoc">Character used as a filling for right-align the right part of messages with "{hfill}".</div><div class="ttdef"><b>Definition:</b> <a href="clutchlog_8h_source.html#l00260">clutchlog.h:260</a></div></div>
|
||||
<div class="ttc" id="agroup___use_macros_html_ga6f86187e2b35e7e1907d688f504a197d"><div class="ttname"><a href="group___use_macros.html#ga6f86187e2b35e7e1907d688f504a197d">CLUTCHLOG</a></div><div class="ttdeci">#define CLUTCHLOG(LEVEL, WHAT)</div><div class="ttdoc">Log a message at the given level.</div><div class="ttdef"><b>Definition:</b> <a href="clutchlog_8h_source.html#l00081">clutchlog.h:81</a></div></div>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue