doc/freestanding/log.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

<!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>log.lp</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" >(License)</span>

<span class="ref" >(Imports)</span>

<span class="ref" >(Level setting)</span>

<span class="ref" >(Logging function)</span>
</code></pre>

<h3 id="license">License:</h3>

<pre><code>&#47;&#47; Copyright 2022 DistressNetwork° &#60;uplink@distress.network&#62;
&#47;&#47; This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https:&#47;&#47;mozilla.org&#47;MPL&#47;2.0&#47;.
</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) &#62; @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 &#8216;info&#8217; and &#8216;error&#8217; 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 =&#62; "ok",
        .err =&#62; "err",
        else =&#62; 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>