diff options
| author | eudoxia <uplink@distress.network> | 2022-03-31 10:19:21 -0400 |
|---|---|---|
| committer | eudoxia <uplink@distress.network> | 2022-03-31 10:19:21 -0400 |
| commit | 27f4773b122a2758cfaf88537c9e1a8ad5df7e69 (patch) | |
| tree | f6a31476fee7208d1ceb49186b243b106b09a5bd /doc/log.html | |
initial
Diffstat (limited to 'doc/log.html')
| -rw-r--r-- | doc/log.html | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/doc/log.html b/doc/log.html new file mode 100644 index 0000000..f82d41e --- /dev/null +++ b/doc/log.html @@ -0,0 +1,102 @@ +<!doctype html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<style> +* {box-sizing: border-box;} +html { +--fs-sans: Helvetica, "Helvetica Neue", Arial, "San Francisco", sans; +--fs-mono: jetbrains-mono-regular, Consolas, Menlo, monospace; +font-size: 16px; +} +body {background-color: #111; color: #ddd; margin: 2rem calc(50% - 32rem); font-family: var(--fs-sans); font-size: 1rem; font-style: normal;} +body * {line-height: 1.5; text-align: justify; text-justify: inter-word;} +h1,h2 {font-family: var(--fs-sans); margin: 2rem 0 1rem; font-weight: bold; line-height: 1;} +h1 {font-size: 3rem;} +h2 {font-size: 2rem;} +h3 {margin: 1rem; font-size: 1rem; font-weight: normal; font-style: italic;} +code,code * {font-family: var(--fs-mono); hyphens: none; line-height: 1.25rem;} +body>pre {background-color: #000; margin: 1rem; padding: 1rem; white-space: pre-wrap; border-radius: 0.25rem;} +ul,ol {margin: 1rem 0; padding: 0 0 0 2rem;} +ul ul,ol ol {margin: 0;} +.ref {font-family: var(--fs-sans); font-style: italic;} +@media screen and (max-width: 68rem) {body {margin: 2rem calc(50% - 24rem);}} +@media screen and (max-width: 52rem) {body {margin: 2rem calc(50% - 16rem);}} +@media screen and (max-width: 36rem) {body {margin: 2rem; hyphens: auto;} h3,body>pre {margin: 1rem 0}} +</style> +</head> + +<body> +<h1 id="log.zig">log.zig</h1> + +<p>This file contains a simple logging function. It is a modified version of the example logging function implementation provided in <code>std.log</code>.</p> + +<h3 id="section">*:</h3> + +<pre><code><span class="ref" >(Imports)</span> + +<span class="ref" >(Level setting)</span> + +<span class="ref" >(Logging function)</span> +</code></pre> + +<p>We first import the standard library, and the <code>Level</code> type which is an enum representing the possible log levels.</p> + +<h3 id="imports">Imports:</h3> + +<pre><code>const std = @import("std"); +const Level = std.log.Level; +</code></pre> + +<p>The logging function is structured such that only log messages equal to or above a certain severity threshold will be printed to the console. This threshold can then be globally modified during development. The threshold constant is defined below.</p> + +<h3 id="level-setting">Level setting:</h3> + +<pre><code>pub const log_level: Level = .warn; +</code></pre> + +<p>We then define the logging function itself, which accepts a <code>Level</code> value and the format string and argument struct to be passed to the inner print function.</p> + +<h3 id="logging-function">Logging function:</h3> + +<pre><code>pub fn log( + comptime level: Level, + comptime format: []const u8, + args: anytype, +) void { + <span class="ref" >(Compare with level threshold)</span> + + <span class="ref" >(Define message string)</span> + + <span class="ref" >(Print to console)</span> +} +</code></pre> + +<p>First the comparison against the severity threshold is made. (A lower integer value signifies a higher severity.) If the severity is lower than the threshold, the function immediately exits.</p> + +<h3 id="compare-with-level-threshold">Compare with level threshold:</h3> + +<pre><code>if (@enumToInt(level) > @enumToInt(log_level)) return; +</code></pre> + +<p>Next the message string is created. The unformatted content of this string is evaluated at compile-time, before being formatted by the print function at runtime. The “info” and “error” log levels use custom names, whereas all other levels use their default display names.</p> + +<h3 id="define-message-string">Define message string:</h3> + +<pre><code>const msg = "[" ++ switch (level) { + .info => "ok", + .err => "err", + else => level.asText(), +} ++ "]\t" ++ format ++ "\n"; +</code></pre> + +<p>Finally, the message is printed to the console. If an error is returned by the <code>print()</code> call, the logging function silently exits.</p> + +<h3 id="print-to-console">Print to console:</h3> + +<pre><code>const stderr = std.io.getStdErr().writer(); +nosuspend stderr.print(msg, args) catch return; +</code></pre> +</body> +</html>
\ No newline at end of file |