update and refactor doc
This commit is contained in:
parent
669525c1d4
commit
bd53f59dd9
2 changed files with 91 additions and 78 deletions
|
|
@ -77,14 +77,15 @@ $(function() {
|
|||
<li class="level2"><a href="#autotoc_md8">Output style</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="level1"><a href="#autotoc_md9">Advanced Usage</a><ul><li class="level2"><a href="#autotoc_md10">Disabled calls</a></li>
|
||||
<li class="level2"><a href="#autotoc_md11">Low-level API</a></li>
|
||||
<li class="level2"><a href="#autotoc_md12">(De)clutch any function call</a></li>
|
||||
<li class="level2"><a href="#autotoc_md13">(De)clutch any code section</a></li>
|
||||
<li class="level1"><a href="#autotoc_md9">Advanced Usage</a><ul><li class="level2"><a href="#autotoc_md10">More Output Configuration</a></li>
|
||||
<li class="level2"><a href="#autotoc_md11">Disabled calls</a></li>
|
||||
<li class="level2"><a href="#autotoc_md12">Low-level API</a></li>
|
||||
<li class="level2"><a href="#autotoc_md13">(De)clutch any function call</a></li>
|
||||
<li class="level2"><a href="#autotoc_md14">(De)clutch any code section</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="level1"><a href="#autotoc_md14">Examples</a></li>
|
||||
<li class="level1"><a href="#autotoc_md15">Build and tests</a></li>
|
||||
<li class="level1"><a href="#autotoc_md15">Examples</a></li>
|
||||
<li class="level1"><a href="#autotoc_md16">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>
|
||||
|
|
@ -118,13 +119,13 @@ Example</h1>
|
|||
<div class="line">log.threshold(<span class="stringliteral">"Info"</span>); <span class="comment">// Log only "info", "warning", "error" or "critical" messages.</span></div>
|
||||
<div class="line">log.file(<span class="stringliteral">"algebra/.*"</span>); <span class="comment">// Will match any file in the "algebra" directory.</span></div>
|
||||
<div class="line">log.func(<span class="stringliteral">"(mul|add|sub|div)"</span>); <span class="comment">// Will match "multiply", for instance.</span></div>
|
||||
</div><!-- fragment --><p>For more detailled examples, see the "API documentation" section below and the <code>tests</code> directory.</p>
|
||||
</div><!-- fragment --><p>For more detailled examples, see the "Usage" sections below and the <code>tests</code> directory.</p>
|
||||
<h1><a class="anchor" id="autotoc_md2"></a>
|
||||
Rationale</h1>
|
||||
<p>Most of existing logging systems targets service events storage, like fast queuing of transactions in a round-robin database. Their aim is to provide a simple interface to efficiently store messages somewhere, which is appropriated when you have a well known service running and you want to be able to trace complex users interactions across its states.</p>
|
||||
<p>Clutchlog, however, targets the debugging of a (typically single-run) program. While you develop your software, it's common practice to output several detailled informations on the internal states around the feature you are currently programming. However, once the feature is up and running, those detailled informations are only useful if you encounter a bug traversing this specific part.</p>
|
||||
<p>Clutchlog, however, targets the <em>debugging</em> of a (typically single-run) program. While you develop your software, it's common practice to output several detailled informations on the internal states around the feature you are currently programming. However, once the feature is up and running, those detailled informations are only useful if you encounter a bug traversing this specific part.</p>
|
||||
<p>While tracing a bug, it is tedious to uncomment old debugging code (and go on the build-test cycle) or to set up a full debugger session that displays all appropriate data (with ad-hoc fancy hooks).</p>
|
||||
<p>To solve this problem, Clutchlog allows to disengage your debug log messages in various parts of the program, allowing for the fast tracking of a bug across the execution.</p>
|
||||
<p>To solve this problem, Clutchlog allows to disengage <em>at runtime</em> your debug log messages in various parts of the program, allowing for the fast tracking of a bug across the execution.</p>
|
||||
<h1><a class="anchor" id="autotoc_md3"></a>
|
||||
Basic Usage</h1>
|
||||
<h2><a class="anchor" id="autotoc_md4"></a>
|
||||
|
|
@ -196,17 +197,6 @@ Output Configuration</h2>
|
|||
<h3>Log Format</h3>
|
||||
<p>The default log format is <code>"[{name}] {level_letter}:{depth_marks} {msg} {hfill} {func} @ {file}:{line}\n"</code>, it can be overriden at compile time by defining the <code>CLUTCHLOG_DEFAULT_FORMAT</code> macro.</p>
|
||||
<p>By default, and if <code>CLUTCHLOG_DEFAULT_FORMAT</code> is not defined, clutchlog will not put the location-related tags in the message formats (i.e. <code>{name}</code>, <code>{func}</code>, and <code>{line}</code>) when not in Debug builds.</p>
|
||||
<h3>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>Marks</h3>
|
||||
<p>The mark used with the <code>{depth_marks}</code> tag can be configured with the <code>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__UseMacros.html#ga45c4c964fad4ad1641d5c9c28c4645b9">CLUTCHLOG_DEFAULT_DEPTH_MARK</a>); <span class="comment">// Defaults to ">".</span></div>
|
||||
</div><!-- fragment --><p>The character used with the <code>{hfill}</code> tag can be configured wth the <code>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(CLUTCHLOG_DEFAULT_HFILL_MARK); <span class="comment">// Defaults to '.'.</span></div>
|
||||
</div><!-- fragment --><p>Clutchlog measures the width of the standard error channel. If it is redirected, it may be measured as very large. Thus, the <code>hfill_max</code> accessors allow to set 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><!-- fragment --><p>Note: clutchlog will select the minimum between <code>hfill_max</code> and the measured number of columns in the terminal, so that you may use <code>hfill_max</code> as a way to constraint the output width in any cases.</p>
|
||||
<h3>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.</p>
|
||||
<h2><a class="anchor" id="autotoc_md8"></a>
|
||||
Output style</h2>
|
||||
<p>The output 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>
|
||||
|
|
@ -257,6 +247,19 @@ Output style</h2>
|
|||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md9"></a>
|
||||
Advanced Usage</h1>
|
||||
<h2><a class="anchor" id="autotoc_md10"></a>
|
||||
More Output Configuration</h2>
|
||||
<h3>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>Marks</h3>
|
||||
<p>The mark used with the <code>{depth_marks}</code> tag can be configured with the <code>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__UseMacros.html#ga45c4c964fad4ad1641d5c9c28c4645b9">CLUTCHLOG_DEFAULT_DEPTH_MARK</a>); <span class="comment">// Defaults to ">".</span></div>
|
||||
</div><!-- fragment --><p>The character used with the <code>{hfill}</code> tag can be configured wth the <code>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(CLUTCHLOG_DEFAULT_HFILL_MARK); <span class="comment">// Defaults to '.'.</span></div>
|
||||
</div><!-- fragment --><p>Clutchlog measures the width of the standard error channel. If it is redirected, it may be measured as very large. Thus, the <code>hfill_max</code> accessors allow to set 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><!-- fragment --><p>Note: clutchlog will select the minimum between <code>hfill_max</code> and the measured number of columns in the terminal, so that you may use <code>hfill_max</code> as a way to constraint the output width in any cases.</p>
|
||||
<h3>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>strip_calls</code>. </p><div class="fragment"><div class="line">log.strip_calls(<a class="code" href="group__UseMacros.html#ga98f30d814d4913a8a7c93a8793f49adf">CLUTCHLOG_STRIP_CALLS</a>); <span class="comment">// Defaults to 5.</span></div>
|
||||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md11"></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>
|
||||
|
|
@ -265,7 +268,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_md11"></a>
|
||||
<h2><a class="anchor" id="autotoc_md12"></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>log</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>
|
||||
|
|
@ -273,18 +276,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__UseMacros.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>level_of</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_md12"></a>
|
||||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md13"></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_md13"></a>
|
||||
<h2><a class="anchor" id="autotoc_md14"></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__UseMacros.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_md14"></a>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md15"></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="group__UseMacros.html#gacfaceb77da01503b432644a3efaee4fa">clutchlog::logger</a>();</div>
|
||||
<div class="line">log.out(std::clog);</div>
|
||||
|
|
@ -293,6 +296,7 @@ Examples</h1>
|
|||
<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"> clutchlog::fmt::fg::red,</div>
|
||||
|
|
@ -357,7 +361,7 @@ Examples</h1>
|
|||
<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_md15"></a>
|
||||
<h1><a class="anchor" id="autotoc_md16"></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>
|
||||
|
|
@ -375,6 +379,7 @@ Build and tests</h1>
|
|||
<div class="ttc" id="agroup__UseMacros_html_ga2bb0fde65fcd264393e102314dd1610b"><div class="ttname"><a href="group__UseMacros.html#ga2bb0fde65fcd264393e102314dd1610b">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__UseMacros_html_gae8911119d726a43b77f5781cb5a72813"><div class="ttname"><a href="group__UseMacros.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> clutchlog.h:75</div></div>
|
||||
<div class="ttc" id="agroup__UseMacros_html_gaaf2e85e1153e6c88b458dd49e3c37c73"><div class="ttname"><a href="group__UseMacros.html#gaaf2e85e1153e6c88b458dd49e3c37c73">CLUTCHCODE</a></div><div class="ttdeci">#define CLUTCHCODE(LEVEL,...)</div><div class="ttdoc">Run any code if the scope matches.</div><div class="ttdef"><b>Definition:</b> clutchlog.h:134</div></div>
|
||||
<div class="ttc" id="agroup__UseMacros_html_ga98f30d814d4913a8a7c93a8793f49adf"><div class="ttname"><a href="group__UseMacros.html#ga98f30d814d4913a8a7c93a8793f49adf">CLUTCHLOG_STRIP_CALLS</a></div><div class="ttdeci">#define CLUTCHLOG_STRIP_CALLS</div><div class="ttdoc">Compile-time number of call stack levels to remove from depth display by default.</div><div class="ttdef"><b>Definition:</b> clutchlog.h:249</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> clutchlog.h:307</div></div>
|
||||
<div class="ttc" id="agroup__UseMacros_html_ga572e3aa19d8b39e3ed0b9e91961104c2"><div class="ttname"><a href="group__UseMacros.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> clutchlog.h:96</div></div>
|
||||
<!-- start footer part -->
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue