conf/
lib.rs

1//! A `derive`-based config parser aimed at the practically-minded developer building large web projects and applications.
2//!
3//! To use `conf`, use the `#[derive(Conf)]` proc macro on your configuration struct.
4//! Then call a [`Conf`] trait function to parse your configuration struct.
5//! Proc macro attributes are documented there.
6//!
7//! For hierarchical config, add the `#[conf(serde)]` annotation to your configuration struct.
8//! Then use [`Conf::conf_builder`] to get a builder object, and call [`ConfBuilder::doc`]
9//! to supply a serde "document" representing the config file in any serde-compatible format.
10//! A typical example might be a `serde_json::Value`.
11//! Then call [`ConfBuilder::parse`] or similar on the builder.
12//!
13//! See the [readme] for an overview.
14#![deny(unsafe_code)]
15#![deny(missing_docs)]
16
17pub mod readme;
18
19mod builder;
20#[cfg(feature = "completion")]
21pub mod completion;
22mod conf_context;
23mod error;
24mod find_parameter;
25pub mod introspection;
26#[doc(hidden)]
27pub mod lazybuf;
28mod parse_env;
29mod parser;
30mod program_option;
31mod str_to_bool;
32mod styles;
33mod traits;
34
35// These are not needed by users or by generated code
36use conf_context::FlattenedOptionalDebugInfo;
37use parse_env::parse_env;
38use parser::ParsedArgs;
39use str_to_bool::str_to_bool;
40
41// These exports represent public API.
42pub use builder::ConfBuilder;
43pub use error::Error;
44pub use find_parameter::find_parameter;
45pub use styles::Styles;
46pub use traits::{Conf, Subcommands};
47
48// Re-export anstyle for users to create Style objects
49pub use anstyle;
50
51// Export conf_derive proc-macros unconditionally. Their docs are on the traits that they
52// produce implementations for.
53#[doc(hidden)]
54pub use conf_derive::{self, *};
55
56// The derive macro needs these other types, so they are exported, but doc(hidden).
57#[doc(hidden)]
58pub use conf_context::{ConfContext, ConfValueSource};
59#[doc(hidden)]
60pub use error::InnerError;
61#[doc(hidden)]
62pub use parse_env::ParsedEnv;
63#[doc(hidden)]
64pub use parser::{Parser, ParserConfig};
65#[doc(hidden)]
66pub use program_option::{DisplayFn, ParseType, ProgramOption};
67
68// The serde feature brings in some more types and traits
69#[cfg(feature = "serde")]
70mod conf_serde;
71// The ConfSerde trait and builder are publicly documented
72#[cfg(feature = "serde")]
73pub use conf_serde::{ConfSerde, ConfSerdeBuilder};
74// These are internals used by the derive macro.
75#[doc(hidden)]
76#[cfg(feature = "serde")]
77pub use conf_serde::{
78    ConfSerdeContext, ConfSerdeSeed, IdentString, InitializationStateMachine, NextValueProducer,
79    OptionalStateMachine, PrefixStrippingStateMachine, SubcommandsSerde,
80};
81// Re-export serde crate for the proc macro
82#[doc(hidden)]
83#[cfg(feature = "serde")]
84pub use serde::{self, *};
85
86// CowStr is used internally mainly because using it allows us to construct ProgramOption in a const
87// way from string literals, but also to modify them if they have to be flattened into something.
88// In the future we could use a rope or something instead, but this is fine.
89type CowStr = std::borrow::Cow<'static, str>;
90
91// Helper for some of the proc-macro code-gen
92// This lets you get the inner-type of a Vec<T> no matter how Vec<T> is spelled
93// (Vec, std::vec::Vec, alloc::vec::Vec) or aliased by user code.
94// This is normally difficult to do directly from a proc-macro, which can only see the tokens.
95#[doc(hidden)]
96pub trait InnerTypeHelper {
97    type Ty;
98}
99
100impl<T> InnerTypeHelper for Vec<T> {
101    type Ty = T;
102}
conf/lib.rs

conf/
lib.rs
