parse_env_filter/
lib.rs

1//! Parsing support for a log target filter, as used by [env_logger] and [tracing::EnvFilter].
2//!
3//! We always support the extended tracing format, that is
4//!
5//! ```text
6//! target[span{field=value}]=level
7//! ```
8//!
9//! with the following validity rules:
10//!
11//! - All fields are optional, and MAY be omitted
12//! - All fields MUST NOT contain the syntax characters `[]{}=,"/`
13//!   - This may be relaxed in the future, to allow e.g. matched brackets in `value` and/or quoting values
14//! - Unlike env_logger/tracing::EnvFilter, we treat a bare level name as a target, not a level directive
15//!   - Adding this behavior back is simple — check if only a target is set and if so try it as a level
16//!
17//! Note that these rules do not trim whitespace; you'll likely want to yourself.
18//! If you want further verification, you can add it on after the parse step.
19//! This crate is merely intended to pull the directives out of the format, not
20//! to ensure that the directives are otherwise well-formed or meaningful.
21//!
22//! ## Features not supported
23//!
24//! - With tracing::EnvFilter, parsing is ad-hoc and can often allow odd edge cases through.
25//!   We instead opt to be strict and require exactly matching the syntax, rather than sloppy acceptance.
26//! - Along the same lines, tracing allows (and sometimes expects) using quotes in field filter values.
27//!   Quotes are currently reserved, such that a quoted syntax that allows syntax characters in filter
28//!   fields can be added in the future.
29//! - env_logger supports a global `/regex` directive to filter messages via a regex. This applies
30//!   separately and to all other earlier directives, and as such doesn't quite fit the filter
31//!   iterator design we've taken. However, we have reserved the `/` character for clarity
32//!   and such that a filter field can potentially be added with this syntax in the future.
33//! - tracing::EnvFilter interprets the value of field=value as a regular expression. We explicitly
34//!   leave that level of interpretation up to the consumer, as this library is just for parsing.
35//!
36//! [env_logger]: <https://docs.rs/env_logger/>
37//! [tracing::EnvFilter]: <https://docs.rs/tracing-subscriber/0.2/tracing_subscriber/filter/struct.EnvFilter.html>
38
39#![no_std]
40
41#[cfg(feature = "alloc")]
42pub mod eager;
43mod lazy;
44
45pub use lazy::*;
46
47#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
48#[non_exhaustive]
49pub enum ParseError {
50    ReservedSyntax,
51    BadSyntax,
52}
parse_env_filter/lib.rs

parse_env_filter/
lib.rs
