diff options
Diffstat (limited to 'doc/online/log.html')
| -rwxr-xr-x | doc/online/log.html | 105 |
1 files changed, 105 insertions, 0 deletions
diff --git a/doc/online/log.html b/doc/online/log.html new file mode 100755 index 0000000..59e9627 --- /dev/null +++ b/doc/online/log.html @@ -0,0 +1,105 @@ +<!doctype html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<link rel="stylesheet" href="/fonts/fonts.css"> +<link rel="stylesheet" href="/css/main.css"> +<link rel="apple-touch-icon" sizes="180x180" href="/favicon/apple-touch-icon.png"> +<link rel="icon" type="image/png" sizes="32x32" href="/favicon/favicon-32x32.png"> +<link rel="icon" type="image/png" sizes="16x16" href="/favicon/favicon-16x16.png"> +<link rel="manifest" href="/favicon/site.webmanifest"> +<title>log.lp — DistressNetwork°</title> +<style>h3,.lp-ref {font-family: neue-haas-grotesk-text, var(--fs-sans); font-size: 1rem; font-weight: normal; font-style: italic;} h3 {margin: 1rem;}</style> +</head> +<body> +<div class="contentlevel"> +<main> +<div class="leading">log.lp</div> +<hr> +<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="lp-ref">(License)</span> + +<span class="lp-ref">(Imports)</span> + +<span class="lp-ref">(Level setting)</span> + +<span class="lp-ref">(Logging function)</span> +</code></pre> + +<h3 id="license">License:</h3> + +<pre><code>// Copyright 2022 DistressNetwork° <uplink@distress.network> +// 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://mozilla.org/MPL/2.0/. +</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="lp-ref">(Compare with level threshold)</span> + + <span class="lp-ref">(Define message string)</span> + + <span class="lp-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> +</main> +<nav> +</nav> +</div> +<footer> +<p><a href="/info">About.</a> <a href="mailto:uplink@distress.network">Contact.</a> <a href="/cw.html">Content Warning.</a> <a href="https://git.distress.network">Git.</a> <a href="/meta/sitemap">Sitemap.</a> <a href="https://creativecommons.org/licenses/by-sa/4.0">CC BY-SA 4.0.</a></p> +<img src="/media/distressnetwork-w.svg" alt=""> +</footer> +</body> +</html> |