@@ -50,6 +50,179 @@ struct GonfigField {
5050 default : Option < String > ,
5151}
5252
53+ /// Derive macro for the `Gonfig` trait, enabling declarative configuration management.
54+ ///
55+ /// This macro generates configuration loading methods for your struct, supporting multiple
56+ /// configuration sources: environment variables, CLI arguments, and configuration files.
57+ ///
58+ /// # Generated Methods
59+ ///
60+ /// The macro generates three public methods on your struct:
61+ ///
62+ /// - `from_gonfig() -> Result<Self>` - Loads configuration from all enabled sources
63+ /// - `from_gonfig_with_builder(builder: ConfigBuilder) -> Result<Self>` - Advanced configuration with custom builder
64+ /// - `gonfig_builder() -> ConfigBuilder` - Returns a pre-configured builder for advanced use cases
65+ ///
66+ /// # Container Attributes
67+ ///
68+ /// ## `#[Gonfig(env_prefix = "PREFIX")]`
69+ /// Sets the prefix for environment variables. Field names are automatically uppercased and
70+ /// appended to the prefix.
71+ ///
72+ /// **Example:**
73+ /// ```rust,ignore
74+ /// #[derive(Gonfig, Deserialize)]
75+ /// #[Gonfig(env_prefix = "APP")]
76+ /// struct Config {
77+ /// database_url: String, // Environment variable: APP_DATABASE_URL
78+ /// port: u16, // Environment variable: APP_PORT
79+ /// }
80+ /// ```
81+ ///
82+ /// ## `#[Gonfig(allow_cli)]`
83+ /// Enables CLI argument parsing. Field names are converted to kebab-case.
84+ ///
85+ /// **Example:**
86+ /// ```rust,ignore
87+ /// #[derive(Gonfig, Deserialize)]
88+ /// #[Gonfig(allow_cli)]
89+ /// struct Config {
90+ /// max_connections: u32, // CLI argument: --max-connections
91+ /// }
92+ /// ```
93+ ///
94+ /// ## `#[Gonfig(allow_config)]`
95+ /// Enables automatic config file loading. Checks for `config.toml`, `config.yaml`, or
96+ /// `config.json` in the current directory.
97+ ///
98+ /// **Example:**
99+ /// ```rust,ignore
100+ /// #[derive(Gonfig, Deserialize)]
101+ /// #[Gonfig(allow_config)]
102+ /// struct Config {
103+ /// // Loads from config.toml, config.yaml, or config.json if present
104+ /// setting: String,
105+ /// }
106+ /// ```
107+ ///
108+ /// # Field Attributes
109+ ///
110+ /// ## `#[gonfig(env_name = "CUSTOM_NAME")]`
111+ /// Override the environment variable name for a specific field.
112+ ///
113+ /// **Example:**
114+ /// ```rust,ignore
115+ /// #[derive(Gonfig, Deserialize)]
116+ /// #[Gonfig(env_prefix = "APP")]
117+ /// struct Config {
118+ /// #[gonfig(env_name = "DATABASE_CONNECTION_STRING")]
119+ /// database_url: String, // Uses DATABASE_CONNECTION_STRING instead of APP_DATABASE_URL
120+ /// }
121+ /// ```
122+ ///
123+ /// ## `#[gonfig(cli_name = "custom-name")]`
124+ /// Override the CLI argument name for a specific field.
125+ ///
126+ /// **Example:**
127+ /// ```rust,ignore
128+ /// #[derive(Gonfig, Deserialize)]
129+ /// #[Gonfig(allow_cli)]
130+ /// struct Config {
131+ /// #[gonfig(cli_name = "db-url")]
132+ /// database_url: String, // CLI argument: --db-url instead of --database-url
133+ /// }
134+ /// ```
135+ ///
136+ /// ## `#[gonfig(default = "value")]`
137+ /// Specify a default value for a field. The value should be a JSON-compatible string.
138+ ///
139+ /// **Example:**
140+ /// ```rust,ignore
141+ /// #[derive(Gonfig, Deserialize)]
142+ /// struct Config {
143+ /// #[gonfig(default = "8080")]
144+ /// port: u16,
145+ ///
146+ /// #[gonfig(default = r#"["localhost"]"#)]
147+ /// allowed_hosts: Vec<String>,
148+ /// }
149+ /// ```
150+ ///
151+ /// ## `#[skip]` or `#[skip_gonfig]`
152+ /// Exclude a field from configuration loading. Useful for non-serializable fields or
153+ /// fields that should only be set at runtime.
154+ ///
155+ /// **Example:**
156+ /// ```rust,ignore
157+ /// #[derive(Gonfig, Deserialize)]
158+ /// struct Config {
159+ /// database_url: String,
160+ ///
161+ /// #[skip]
162+ /// #[serde(skip)]
163+ /// runtime_data: Option<String>, // Not loaded from config sources
164+ /// }
165+ /// ```
166+ ///
167+ /// # Configuration Priority
168+ ///
169+ /// Configuration sources are merged in the following priority order (later sources override earlier ones):
170+ ///
171+ /// 1. Default values (from `#[gonfig(default)]` attributes)
172+ /// 2. Configuration files (if `allow_config` is set)
173+ /// 3. Environment variables (always enabled)
174+ /// 4. CLI arguments (if `allow_cli` is set)
175+ ///
176+ /// # Complete Example
177+ ///
178+ /// ```rust,ignore
179+ /// use gonfig::Gonfig;
180+ /// use serde::Deserialize;
181+ ///
182+ /// #[derive(Debug, Deserialize, Gonfig)]
183+ /// #[Gonfig(env_prefix = "MYAPP", allow_cli, allow_config)]
184+ /// struct AppConfig {
185+ /// /// Database connection URL
186+ /// /// - Environment: MYAPP_DATABASE_URL
187+ /// /// - CLI: --database-url
188+ /// database_url: String,
189+ ///
190+ /// /// Server port (default: 8080)
191+ /// /// - Environment: MYAPP_PORT
192+ /// /// - CLI: --port
193+ /// #[gonfig(default = "8080")]
194+ /// port: u16,
195+ ///
196+ /// /// Custom environment variable name
197+ /// #[gonfig(env_name = "LOG_LEVEL")]
198+ /// log_level: String,
199+ ///
200+ /// /// Runtime field (not loaded from config)
201+ /// #[skip]
202+ /// #[serde(skip)]
203+ /// start_time: Option<std::time::Instant>,
204+ /// }
205+ ///
206+ /// fn main() -> gonfig::Result<()> {
207+ /// // Simple usage
208+ /// let config = AppConfig::from_gonfig()?;
209+ ///
210+ /// // Advanced usage with custom builder
211+ /// let mut builder = AppConfig::gonfig_builder();
212+ /// builder = builder.with_file("custom.toml")?;
213+ /// let config = AppConfig::from_gonfig_with_builder(builder)?;
214+ ///
215+ /// println!("Config: {:?}", config);
216+ /// Ok(())
217+ /// }
218+ /// ```
219+ ///
220+ /// # Supported Attributes
221+ ///
222+ /// - `gonfig` - Field-level attribute for configuration options
223+ /// - `skip_gonfig` - Field-level attribute to skip a field
224+ /// - `skip` - Alternative field-level skip attribute (compatible with serde)
225+ /// - `Gonfig` - Container-level attribute for struct-wide options
53226#[ proc_macro_derive( Gonfig , attributes( gonfig, skip_gonfig, skip, Gonfig ) ) ]
54227pub fn derive_gonfig ( input : TokenStream ) -> TokenStream {
55228 let input = parse_macro_input ! ( input as DeriveInput ) ;
0 commit comments