Skip to content

Commit 26b40be

Browse files
treemantreeman
committed
doc: Runnable examples logging.
Also use //! Instead of /*! in liblog.
1 parent dee8423 commit 26b40be

File tree

2 files changed

+236
-141
lines changed

2 files changed

+236
-141
lines changed

‎src/liblog/lib.rs

+148-114
Original file line numberDiff line numberDiff line change
@@ -8,120 +8,154 @@
88
// option. This file may not be copied, modified, or distributed
99
// except according to those terms.
1010

11-
/*!
12-
13-
Utilities for program-wide and customizable logging
14-
15-
## Example
16-
17-
```
18-
#![feature(phase)]
19-
#[phase(plugin, link)] extern crate log;
20-
21-
fn main() {
22-
debug!("this is a debug {}", "message");
23-
error!("this is printed by default");
24-
25-
if log_enabled!(log::INFO) {
26-
let x = 3i * 4i; // expensive computation
27-
info!("the answer was: {}", x);
28-
}
29-
}
30-
```
31-
32-
## Logging Macros
33-
34-
There are five macros that the logging subsystem uses:
35-
36-
* `log!(level, ...)` - the generic logging macro, takes a level as a u32 and any
37-
related `format!` arguments
38-
* `debug!(...)` - a macro hard-wired to the log level of `DEBUG`
39-
* `info!(...)` - a macro hard-wired to the log level of `INFO`
40-
* `warn!(...)` - a macro hard-wired to the log level of `WARN`
41-
* `error!(...)` - a macro hard-wired to the log level of `ERROR`
42-
43-
All of these macros use the same style of syntax as the `format!` syntax
44-
extension. Details about the syntax can be found in the documentation of
45-
`std::fmt` along with the Rust tutorial/manual.
46-
47-
If you want to check at runtime if a given logging level is enabled (e.g. if the
48-
information you would want to log is expensive to produce), you can use the
49-
following macro:
50-
51-
* `log_enabled!(level)` - returns true if logging of the given level is enabled
52-
53-
## Enabling logging
54-
55-
Log levels are controlled on a per-module basis, and by default all logging is
56-
disabled except for `error!` (a log level of 1). Logging is controlled via the
57-
`RUST_LOG` environment variable. The value of this environment variable is a
58-
comma-separated list of logging directives. A logging directive is of the form:
59-
60-
```text
61-
path::to::module=log_level
62-
```
63-
64-
The path to the module is rooted in the name of the crate it was compiled for,
65-
so if your program is contained in a file `hello.rs`, for example, to turn on
66-
logging for this file you would use a value of `RUST_LOG=hello`.
67-
Furthermore, this path is a prefix-search, so all modules nested in the
68-
specified module will also have logging enabled.
69-
70-
The actual `log_level` is optional to specify. If omitted, all logging will be
71-
enabled. If specified, the it must be either a numeric in the range of 1-255, or
72-
it must be one of the strings `debug`, `error`, `info`, or `warn`. If a numeric
73-
is specified, then all logging less than or equal to that numeral is enabled.
74-
For example, if logging level 3 is active, error, warn, and info logs will be
75-
printed, but debug will be omitted.
76-
77-
As the log level for a module is optional, the module to enable logging for is
78-
also optional. If only a `log_level` is provided, then the global log level for
79-
all modules is set to this value.
80-
81-
Some examples of valid values of `RUST_LOG` are:
82-
83-
* `hello` turns on all logging for the 'hello' module
84-
* `info` turns on all info logging
85-
* `hello=debug` turns on debug logging for 'hello'
86-
* `hello=3` turns on info logging for 'hello'
87-
* `hello,std::option` turns on hello, and std's option logging
88-
* `error,hello=warn` turn on global error logging and also warn for hello
89-
90-
## Filtering results
91-
92-
A RUST_LOG directive may include a regex filter. The syntax is to append `/`
93-
followed by a regex. Each message is checked against the regex, and is only
94-
logged if it matches. Note that the matching is done after formatting the log
95-
string but before adding any logging meta-data. There is a single filter for all
96-
modules.
97-
98-
Some examples:
99-
100-
* `hello/foo` turns on all logging for the 'hello' module where the log message
101-
includes 'foo'.
102-
* `info/f.o` turns on all info logging where the log message includes 'foo',
103-
'f1o', 'fao', etc.
104-
* `hello=debug/foo*foo` turns on debug logging for 'hello' where the the log
105-
message includes 'foofoo' or 'fofoo' or 'fooooooofoo', etc.
106-
* `error,hello=warn/[0-9] scopes` turn on global error logging and also warn for
107-
hello. In both cases the log message must include a single digit number
108-
followed by 'scopes'
109-
110-
## Performance and Side Effects
111-
112-
Each of these macros will expand to code similar to:
113-
114-
```rust,ignore
115-
if log_level <= my_module_log_level() {
116-
::log::log(log_level, format!(...));
117-
}
118-
```
119-
120-
What this means is that each of these macros are very cheap at runtime if
121-
they're turned off (just a load and an integer comparison). This also means that
122-
if logging is disabled, none of the components of the log will be executed.
123-
124-
*/
11+
//! Utilities for program-wide and customizable logging
12+
//!
13+
//! ## Example
14+
//!
15+
//! ```
16+
//! #![feature(phase)]
17+
//! #[phase(plugin, link)] extern crate log;
18+
//!
19+
//! fn main() {
20+
//! debug!("this is a debug {}", "message");
21+
//! error!("this is printed by default");
22+
//!
23+
//! if log_enabled!(log::INFO) {
24+
//! let x = 3i * 4i; // expensive computation
25+
//! info!("the answer was: {}", x);
26+
//! }
27+
//! }
28+
//! ```
29+
//!
30+
//! Assumes the binary is `main`:
31+
//!
32+
//! ```{.bash}
33+
//! $ RUST_LOG=error ./main
34+
//! ERROR:main: this is printed by default
35+
//! ```
36+
//!
37+
//! ```{.bash}
38+
//! $ RUST_LOG=info ./main
39+
//! ERROR:main: this is printed by default
40+
//! INFO:main: the answer was: 12
41+
//! ```
42+
//!
43+
//! ```{.bash}
44+
//! $ RUST_LOG=debug ./main
45+
//! DEBUG:main: this is a debug message
46+
//! ERROR:main: this is printed by default
47+
//! INFO:main: the answer was: 12
48+
//! ```
49+
//!
50+
//! You can also set the log level on a per module basis:
51+
//!
52+
//! ```{.bash}
53+
//! $ RUST_LOG=main=info ./main
54+
//! ERROR:main: this is printed by default
55+
//! INFO:main: the answer was: 12
56+
//! ```
57+
//!
58+
//! And enable all logging:
59+
//!
60+
//! ```{.bash}
61+
//! $ RUST_LOG=main ./main
62+
//! DEBUG:main: this is a debug message
63+
//! ERROR:main: this is printed by default
64+
//! INFO:main: the answer was: 12
65+
//! ```
66+
//!
67+
//!
68+
//! ## Logging Macros
69+
//!
70+
//! There are five macros that the logging subsystem uses:
71+
//!
72+
//! * `log!(level, ...)` - the generic logging macro, takes a level as a u32 and any
73+
//! related `format!` arguments
74+
//! * `debug!(...)` - a macro hard-wired to the log level of `DEBUG`
75+
//! * `info!(...)` - a macro hard-wired to the log level of `INFO`
76+
//! * `warn!(...)` - a macro hard-wired to the log level of `WARN`
77+
//! * `error!(...)` - a macro hard-wired to the log level of `ERROR`
78+
//!
79+
//! All of these macros use the same style of syntax as the `format!` syntax
80+
//! extension. Details about the syntax can be found in the documentation of
81+
//! `std::fmt` along with the Rust tutorial/manual.
82+
//!
83+
//! If you want to check at runtime if a given logging level is enabled (e.g. if the
84+
//! information you would want to log is expensive to produce), you can use the
85+
//! following macro:
86+
//!
87+
//! * `log_enabled!(level)` - returns true if logging of the given level is enabled
88+
//!
89+
//! ## Enabling logging
90+
//!
91+
//! Log levels are controlled on a per-module basis, and by default all logging is
92+
//! disabled except for `error!` (a log level of 1). Logging is controlled via the
93+
//! `RUST_LOG` environment variable. The value of this environment variable is a
94+
//! comma-separated list of logging directives. A logging directive is of the form:
95+
//!
96+
//! ```text
97+
//! path::to::module=log_level
98+
//! ```
99+
//!
100+
//! The path to the module is rooted in the name of the crate it was compiled for,
101+
//! so if your program is contained in a file `hello.rs`, for example, to turn on
102+
//! logging for this file you would use a value of `RUST_LOG=hello`.
103+
//! Furthermore, this path is a prefix-search, so all modules nested in the
104+
//! specified module will also have logging enabled.
105+
//!
106+
//! The actual `log_level` is optional to specify. If omitted, all logging will be
107+
//! enabled. If specified, the it must be either a numeric in the range of 1-255, or
108+
//! it must be one of the strings `debug`, `error`, `info`, or `warn`. If a numeric
109+
//! is specified, then all logging less than or equal to that numeral is enabled.
110+
//! For example, if logging level 3 is active, error, warn, and info logs will be
111+
//! printed, but debug will be omitted.
112+
//!
113+
//! As the log level for a module is optional, the module to enable logging for is
114+
//! also optional. If only a `log_level` is provided, then the global log level for
115+
//! all modules is set to this value.
116+
//!
117+
//! Some examples of valid values of `RUST_LOG` are:
118+
//!
119+
//! * `hello` turns on all logging for the 'hello' module
120+
//! * `info` turns on all info logging
121+
//! * `hello=debug` turns on debug logging for 'hello'
122+
//! * `hello=3` turns on info logging for 'hello'
123+
//! * `hello,std::option` turns on hello, and std's option logging
124+
//! * `error,hello=warn` turn on global error logging and also warn for hello
125+
//!
126+
//! ## Filtering results
127+
//!
128+
//! A RUST_LOG directive may include a regex filter. The syntax is to append `/`
129+
//! followed by a regex. Each message is checked against the regex, and is only
130+
//! logged if it matches. Note that the matching is done after formatting the log
131+
//! string but before adding any logging meta-data. There is a single filter for all
132+
//! modules.
133+
//!
134+
//! Some examples:
135+
//!
136+
//! * `hello/foo` turns on all logging for the 'hello' module where the log message
137+
//! includes 'foo'.
138+
//! * `info/f.o` turns on all info logging where the log message includes 'foo',
139+
//! 'f1o', 'fao', etc.
140+
//! * `hello=debug/foo*foo` turns on debug logging for 'hello' where the the log
141+
//! message includes 'foofoo' or 'fofoo' or 'fooooooofoo', etc.
142+
//! * `error,hello=warn/[0-9] scopes` turn on global error logging and also warn for
143+
//! hello. In both cases the log message must include a single digit number
144+
//! followed by 'scopes'
145+
//!
146+
//! ## Performance and Side Effects
147+
//!
148+
//! Each of these macros will expand to code similar to:
149+
//!
150+
//! ```rust,ignore
151+
//! if log_level <= my_module_log_level() {
152+
//! ::log::log(log_level, format!(...));
153+
//! }
154+
//! ```
155+
//!
156+
//! What this means is that each of these macros are very cheap at runtime if
157+
//! they're turned off (just a load and an integer comparison). This also means that
158+
//! if logging is disabled, none of the components of the log will be executed.
125159
126160
#![crate_name = "log"]
127161
#![experimental]

0 commit comments

Comments
 (0)