+/livesplit-wrapper

git clone https://git.julia.blue/+/livesplit-wrapper

P1n3appl3deploy: 9b9f353f3b0e319547cabc5dcadc542d5ab54386b0170e4

gh-pages
23.8 KiB213 linesraw
1<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="A lightweight logging facade."><meta name="keywords" content="rust, rustlang, rust-lang, log"><title>log - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" href="../normalize.css"><link rel="stylesheet" href="../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" href="../ayu.css" disabled><link rel="stylesheet" href="../dark.css" disabled><link rel="stylesheet" href="../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../storage.js"></script><script defer src="../crates.js"></script><script defer src="../main.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="icon" href="https://www.rust-lang.org/favicon.ico"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button><a class="sidebar-logo" href="../log/index.html"><div class="logo-container"><img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png" alt="logo"></div></a><h2 class="location"></h2></nav><nav class="sidebar"><a class="sidebar-logo" href="../log/index.html"><div class="logo-container">
2                    <img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png" alt="logo"></div></a><h2 class="location"><a href="#">Crate log</a></h2><div class="sidebar-elems"><div class="block"><ul><li class="version">Version 0.4.17</li><li><a id="all-types" href="all.html">All Items</a></li></ul></div><section><div class="block"><ul><li><a href="#macros">Macros</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#constants">Constants</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li></ul></div></section></div></nav><main><div class="width-limiter"><div class="sub-container"><a class="sub-logo-container" href="../log/index.html">
3                        <img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png" alt="logo"></a><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><button type="button">?</button></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../wheel.svg"></a></div></div></form></nav></div><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn"><span class="in-band">Crate <a class="mod" href="#">log</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../clipboard.svg" width="19" height="18" alt="Copy item path"></button></span></h1><span class="out-of-band"><a class="srclink" href="../src/log/lib.rs.html#11-1971">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">&#x2212;</span>]</a></span></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>A lightweight logging facade.</p>
4<p>The <code>log</code> crate provides a single logging API that abstracts over the
5actual logging implementation. Libraries can use the logging API provided
6by this crate, and the consumer of those libraries can choose the logging
7implementation that is most suitable for its use case.</p>
8<p>If no logging implementation is selected, the facade falls back to a “noop”
9implementation that ignores all log messages. The overhead in this case
10is very small - just an integer load, comparison and jump.</p>
11<p>A log request consists of a <em>target</em>, a <em>level</em>, and a <em>body</em>. A target is a
12string which defaults to the module path of the location of the log request,
13though that default may be overridden. Logger implementations typically use
14the target to filter requests based on some user configuration.</p>
15<h2 id="usage"><a href="#usage">Usage</a></h2>
16<p>The basic use of the log crate is through the five logging macros: <a href="./macro.error.html"><code>error!</code></a>,
17<a href="./macro.warn.html"><code>warn!</code></a>, <a href="./macro.info.html"><code>info!</code></a>, <a href="./macro.debug.html"><code>debug!</code></a> and <a href="./macro.trace.html"><code>trace!</code></a>
18where <code>error!</code> represents the highest-priority log messages
19and <code>trace!</code> the lowest. The log messages are filtered by configuring
20the log level to exclude messages with a lower priority.
21Each of these macros accept format strings similarly to <a href="https://doc.rust-lang.org/stable/std/macro.println.html"><code>println!</code></a>.</p>
22<h3 id="in-libraries"><a href="#in-libraries">In libraries</a></h3>
23<p>Libraries should link only to the <code>log</code> crate, and use the provided
24macros to log whatever information will be useful to downstream consumers.</p>
25<h4 id="examples"><a href="#examples">Examples</a></h4>
26<div class="example-wrap edition"><div class='tooltip' data-edition="2018">ⓘ</div><pre class="rust rust-example-rendered"><code><span class="kw">use </span>log::{info, warn};
27
28<span class="kw">pub fn </span>shave_the_yak(yak: <span class="kw-2">&amp;mut </span>Yak) {
29    <span class="macro">info!</span>(target: <span class="string">&quot;yak_events&quot;</span>, <span class="string">&quot;Commencing yak shaving for {:?}&quot;</span>, yak);
30
31    <span class="kw">loop </span>{
32        <span class="kw">match </span>find_a_razor() {
33            <span class="prelude-val">Ok</span>(razor) =&gt; {
34                <span class="macro">info!</span>(<span class="string">&quot;Razor located: {}&quot;</span>, razor);
35                yak.shave(razor);
36                <span class="kw">break</span>;
37            }
38            <span class="prelude-val">Err</span>(err) =&gt; {
39                <span class="macro">warn!</span>(<span class="string">&quot;Unable to locate a razor: {}, retrying&quot;</span>, err);
40            }
41        }
42    }
43}</code></pre></div>
44<h3 id="in-executables"><a href="#in-executables">In executables</a></h3>
45<p>Executables should choose a logging implementation and initialize it early in the
46runtime of the program. Logging implementations will typically include a
47function to do this. Any log messages generated before
48the implementation is initialized will be ignored.</p>
49<p>The executable itself may use the <code>log</code> crate to log as well.</p>
50<h4 id="warning"><a href="#warning">Warning</a></h4>
51<p>The logging system may only be initialized once.</p>
52<h3 id="structured-logging"><a href="#structured-logging">Structured logging</a></h3>
53<p>If you enable the <code>kv_unstable</code> feature you can associate structured values
54with your log records. If we take the example from before, we can include
55some additional context besides what’s in the formatted message:</p>
56
57<div class="example-wrap edition"><div class='tooltip' data-edition="2018">ⓘ</div><pre class="rust rust-example-rendered"><code><span class="kw">use </span>log::{info, warn, as_serde, as_error};
58
59<span class="kw">pub fn </span>shave_the_yak(yak: <span class="kw-2">&amp;mut </span>Yak) {
60    <span class="macro">info!</span>(target: <span class="string">&quot;yak_events&quot;</span>, yak = <span class="macro">as_serde!</span>(yak); <span class="string">&quot;Commencing yak shaving&quot;</span>);
61
62    <span class="kw">loop </span>{
63        <span class="kw">match </span>find_a_razor() {
64            <span class="prelude-val">Ok</span>(razor) =&gt; {
65                <span class="macro">info!</span>(razor = razor; <span class="string">&quot;Razor located&quot;</span>);
66                yak.shave(razor);
67                <span class="kw">break</span>;
68            }
69            <span class="prelude-val">Err</span>(err) =&gt; {
70                <span class="macro">warn!</span>(err = <span class="macro">as_error!</span>(err); <span class="string">&quot;Unable to locate a razor, retrying&quot;</span>);
71            }
72        }
73    }
74}</code></pre></div>
75<h2 id="available-logging-implementations"><a href="#available-logging-implementations">Available logging implementations</a></h2>
76<p>In order to produce log output executables have to use
77a logger implementation compatible with the facade.
78There are many available implementations to choose from,
79here are some of the most popular ones:</p>
80<ul>
81<li>Simple minimal loggers:
82<ul>
83<li><a href="https://docs.rs/env_logger/*/env_logger/">env_logger</a></li>
84<li><a href="https://github.com/borntyping/rust-simple_logger">simple_logger</a></li>
85<li><a href="https://github.com/drakulix/simplelog.rs">simplelog</a></li>
86<li><a href="https://docs.rs/pretty_env_logger/*/pretty_env_logger/">pretty_env_logger</a></li>
87<li><a href="https://docs.rs/stderrlog/*/stderrlog/">stderrlog</a></li>
88<li><a href="https://docs.rs/flexi_logger/*/flexi_logger/">flexi_logger</a></li>
89</ul>
90</li>
91<li>Complex configurable frameworks:
92<ul>
93<li><a href="https://docs.rs/log4rs/*/log4rs/">log4rs</a></li>
94<li><a href="https://docs.rs/fern/*/fern/">fern</a></li>
95</ul>
96</li>
97<li>Adaptors for other facilities:
98<ul>
99<li><a href="https://docs.rs/syslog/*/syslog/">syslog</a></li>
100<li><a href="https://docs.rs/slog-stdlog/*/slog_stdlog/">slog-stdlog</a></li>
101<li><a href="https://docs.rs/systemd-journal-logger/*/systemd_journal_logger/">systemd-journal-logger</a></li>
102<li><a href="https://docs.rs/android_log/*/android_log/">android_log</a></li>
103<li><a href="https://docs.rs/win_dbg_logger/*/win_dbg_logger/">win_dbg_logger</a></li>
104<li>[db_logger]</li>
105</ul>
106</li>
107<li>For WebAssembly binaries:
108<ul>
109<li><a href="https://docs.rs/console_log/*/console_log/">console_log</a></li>
110</ul>
111</li>
112<li>For dynamic libraries:
113<ul>
114<li>You may need to construct an FFI-safe wrapper over <code>log</code> to initialize in your libraries</li>
115</ul>
116</li>
117</ul>
118<h2 id="implementing-a-logger"><a href="#implementing-a-logger">Implementing a Logger</a></h2>
119<p>Loggers implement the <a href="trait.Log.html"><code>Log</code></a> trait. Here’s a very basic example that simply
120logs all messages at the <a href="enum.Level.html"><code>Error</code></a>, <a href="enum.Level.html"><code>Warn</code></a> or
121<a href="enum.Level.html"><code>Info</code></a> levels to stdout:</p>
122
123<div class="example-wrap edition"><div class='tooltip' data-edition="2018">ⓘ</div><pre class="rust rust-example-rendered"><code><span class="kw">use </span>log::{Record, Level, Metadata};
124
125<span class="kw">struct </span>SimpleLogger;
126
127<span class="kw">impl </span>log::Log <span class="kw">for </span>SimpleLogger {
128    <span class="kw">fn </span>enabled(<span class="kw-2">&amp;</span><span class="self">self</span>, metadata: <span class="kw-2">&amp;</span>Metadata) -&gt; bool {
129        metadata.level() &lt;= Level::Info
130    }
131
132    <span class="kw">fn </span>log(<span class="kw-2">&amp;</span><span class="self">self</span>, record: <span class="kw-2">&amp;</span>Record) {
133        <span class="kw">if </span><span class="self">self</span>.enabled(record.metadata()) {
134            <span class="macro">println!</span>(<span class="string">&quot;{} - {}&quot;</span>, record.level(), record.args());
135        }
136    }
137
138    <span class="kw">fn </span>flush(<span class="kw-2">&amp;</span><span class="self">self</span>) {}
139}
140</code></pre></div>
141<p>Loggers are installed by calling the <a href="fn.set_logger.html"><code>set_logger</code></a> function. The maximum
142log level also needs to be adjusted via the <a href="fn.set_max_level.html"><code>set_max_level</code></a> function. The
143logging facade uses this as an optimization to improve performance of log
144messages at levels that are disabled. It’s important to set it, as it
145defaults to <a href="enum.LevelFilter.html"><code>Off</code></a>, so no log messages will ever be captured!
146In the case of our example logger, we’ll want to set the maximum log level
147to <a href="enum.LevelFilter.html"><code>Info</code></a>, since we ignore any <a href="enum.Level.html"><code>Debug</code></a> or
148<a href="enum.Level.html"><code>Trace</code></a> level log messages. A logging implementation should
149provide a function that wraps a call to <a href="fn.set_logger.html"><code>set_logger</code></a> and
150<a href="fn.set_max_level.html"><code>set_max_level</code></a>, handling initialization of the logger:</p>
151
152<div class="example-wrap edition"><div class='tooltip' data-edition="2018">ⓘ</div><pre class="rust rust-example-rendered"><code><span class="kw">use </span>log::{SetLoggerError, LevelFilter};
153
154<span class="kw">static </span>LOGGER: SimpleLogger = SimpleLogger;
155
156<span class="kw">pub fn </span>init() -&gt; <span class="prelude-ty">Result</span>&lt;(), SetLoggerError&gt; {
157    log::set_logger(<span class="kw-2">&amp;</span>LOGGER)
158        .map(|()| log::set_max_level(LevelFilter::Info))
159}</code></pre></div>
160<p>Implementations that adjust their configurations at runtime should take care
161to adjust the maximum log level as well.</p>
162<h2 id="use-with-std"><a href="#use-with-std">Use with <code>std</code></a></h2>
163<p><code>set_logger</code> requires you to provide a <code>&amp;'static Log</code>, which can be hard to
164obtain if your logger depends on some runtime configuration. The
165<code>set_boxed_logger</code> function is available with the <code>std</code> Cargo feature. It is
166identical to <code>set_logger</code> except that it takes a <code>Box&lt;Log&gt;</code> rather than a
167<code>&amp;'static Log</code>:</p>
168
169<div class="example-wrap edition"><div class='tooltip' data-edition="2018">ⓘ</div><pre class="rust rust-example-rendered"><code><span class="kw">pub fn </span>init() -&gt; <span class="prelude-ty">Result</span>&lt;(), SetLoggerError&gt; {
170    log::set_boxed_logger(Box::new(SimpleLogger))
171        .map(|()| log::set_max_level(LevelFilter::Info))
172}</code></pre></div>
173<h2 id="compile-time-filters"><a href="#compile-time-filters">Compile time filters</a></h2>
174<p>Log levels can be statically disabled at compile time via Cargo features. Log invocations at
175disabled levels will be skipped and will not even be present in the resulting binary.
176This level is configured separately for release and debug builds. The features are:</p>
177<ul>
178<li><code>max_level_off</code></li>
179<li><code>max_level_error</code></li>
180<li><code>max_level_warn</code></li>
181<li><code>max_level_info</code></li>
182<li><code>max_level_debug</code></li>
183<li><code>max_level_trace</code></li>
184<li><code>release_max_level_off</code></li>
185<li><code>release_max_level_error</code></li>
186<li><code>release_max_level_warn</code></li>
187<li><code>release_max_level_info</code></li>
188<li><code>release_max_level_debug</code></li>
189<li><code>release_max_level_trace</code></li>
190</ul>
191<p>These features control the value of the <code>STATIC_MAX_LEVEL</code> constant. The logging macros check
192this value before logging a message. By default, no levels are disabled.</p>
193<p>Libraries should avoid using the max level features because they’re global and can’t be changed
194once they’re set.</p>
195<p>For example, a crate can disable trace level logs in debug builds and trace, debug, and info
196level logs in release builds with the following configuration:</p>
197<div class="example-wrap"><pre class="language-toml"><code>[dependencies]
198log = { version = &quot;0.4&quot;, features = [&quot;max_level_debug&quot;, &quot;release_max_level_warn&quot;] }</code></pre></div><h2 id="crate-feature-flags"><a href="#crate-feature-flags">Crate Feature Flags</a></h2>
199<p>The following crate feature flags are available in addition to the filters. They are
200configured in your <code>Cargo.toml</code>.</p>
201<ul>
202<li><code>std</code> allows use of <code>std</code> crate instead of the default <code>core</code>. Enables using <code>std::error</code> and
203<code>set_boxed_logger</code> functionality.</li>
204<li><code>serde</code> enables support for serialization and deserialization of <code>Level</code> and <code>LevelFilter</code>.</li>
205</ul>
206<div class="example-wrap"><pre class="language-toml"><code>[dependencies]
207log = { version = &quot;0.4&quot;, features = [&quot;std&quot;, &quot;serde&quot;] }</code></pre></div><h2 id="version-compatibility"><a href="#version-compatibility">Version compatibility</a></h2>
208<p>The 0.3 and 0.4 versions of the <code>log</code> crate are almost entirely compatible. Log messages
209made using <code>log</code> 0.3 will forward transparently to a logger implementation using <code>log</code> 0.4. Log
210messages made using <code>log</code> 0.4 will forward to a logger implementation using <code>log</code> 0.3, but the
211module path and file name information associated with the message will unfortunately be lost.</p>
212</div></details><h2 id="macros" class="small-section-header"><a href="#macros">Macros</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.debug.html" title="log::debug macro">debug</a></div><div class="item-right docblock-short">Logs a message at the debug level.</div></div><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.error.html" title="log::error macro">error</a></div><div class="item-right docblock-short">Logs a message at the error level.</div></div><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.info.html" title="log::info macro">info</a></div><div class="item-right docblock-short">Logs a message at the info level.</div></div><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.log.html" title="log::log macro">log</a></div><div class="item-right docblock-short">The standard logging macro.</div></div><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.log_enabled.html" title="log::log_enabled macro">log_enabled</a></div><div class="item-right docblock-short">Determines if a message logged at the specified level in that module will
213be logged.</div></div><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.trace.html" title="log::trace macro">trace</a></div><div class="item-right docblock-short">Logs a message at the trace level.</div></div><div class="item-row"><div class="item-left module-item"><a class="macro" href="macro.warn.html" title="log::warn macro">warn</a></div><div class="item-right docblock-short">Logs a message at the warn level.</div></div></div><h2 id="structs" class="small-section-header"><a href="#structs">Structs</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.Metadata.html" title="log::Metadata struct">Metadata</a></div><div class="item-right docblock-short">Metadata about a log message.</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.MetadataBuilder.html" title="log::MetadataBuilder struct">MetadataBuilder</a></div><div class="item-right docblock-short">Builder for <a href="struct.Metadata.html"><code>Metadata</code></a>.</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.ParseLevelError.html" title="log::ParseLevelError struct">ParseLevelError</a></div><div class="item-right docblock-short">The type returned by <a href="https://doc.rust-lang.org/std/str/trait.FromStr.html#tymethod.from_str"><code>from_str</code></a> when the string doesn’t match any of the log levels.</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.Record.html" title="log::Record struct">Record</a></div><div class="item-right docblock-short">The “payload” of a log message.</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.RecordBuilder.html" title="log::RecordBuilder struct">RecordBuilder</a></div><div class="item-right docblock-short">Builder for <a href="struct.Record.html"><code>Record</code></a>.</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.SetLoggerError.html" title="log::SetLoggerError struct">SetLoggerError</a></div><div class="item-right docblock-short">The type returned by <a href="fn.set_logger.html"><code>set_logger</code></a> if <a href="fn.set_logger.html"><code>set_logger</code></a> has already been called.</div></div></div><h2 id="enums" class="small-section-header"><a href="#enums">Enums</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.Level.html" title="log::Level enum">Level</a></div><div class="item-right docblock-short">An enum representing the available verbosity levels of the logger.</div></div><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.LevelFilter.html" title="log::LevelFilter enum">LevelFilter</a></div><div class="item-right docblock-short">An enum representing the available verbosity level filters of the logger.</div></div></div><h2 id="constants" class="small-section-header"><a href="#constants">Constants</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="constant" href="constant.STATIC_MAX_LEVEL.html" title="log::STATIC_MAX_LEVEL constant">STATIC_MAX_LEVEL</a></div><div class="item-right docblock-short">The statically resolved maximum log level.</div></div></div><h2 id="traits" class="small-section-header"><a href="#traits">Traits</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="trait" href="trait.Log.html" title="log::Log trait">Log</a></div><div class="item-right docblock-short">A trait encapsulating the operations required of a logger.</div></div></div><h2 id="functions" class="small-section-header"><a href="#functions">Functions</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.logger.html" title="log::logger fn">logger</a></div><div class="item-right docblock-short">Returns a reference to the logger.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.max_level.html" title="log::max_level fn">max_level</a></div><div class="item-right docblock-short">Returns the current maximum log level.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.set_logger.html" title="log::set_logger fn">set_logger</a></div><div class="item-right docblock-short">Sets the global logger to a <code>&amp;'static Log</code>.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.set_logger_racy.html" title="log::set_logger_racy fn">set_logger_racy</a><a title="unsafe function" href="#"><sup>⚠</sup></a></div><div class="item-right docblock-short">A thread-unsafe version of <a href="fn.set_logger.html"><code>set_logger</code></a>.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.set_max_level.html" title="log::set_max_level fn">set_max_level</a></div><div class="item-right docblock-short">Sets the global maximum log level.</div></div></div></section></div></main><div id="rustdoc-vars" data-root-path="../" data-current-crate="log" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (4a1467723 2022-09-23)" ></div></body></html>