Crate structconf[][src]

Expand description

StructConf is a derive macro to combine argument parsing from clap and config file parsing from rust-ini at compile time. Here’s a very simple example (see more detailed examples on the GitHub repo):

use structconf::{clap, StructConf};

#[derive(Debug, StructConf)]
struct ServerConfig {
    #[conf(help = "The public key")]
    pub public_key: String,
    #[conf(no_file, long = "your-secret", help = "Your secret API key")]
    pub secret_key: String,
    #[conf(default = "100", help = "timeout in seconds")]
    pub timeout: i32,

let app = clap::App::new("demo");
let conf = ServerConfig::parse(app, "config.ini");

Any named struct that uses #[derive(StructConf)] will have the methods from structconf::StructConf available.

You can access the clap and ini crates inside structconf::clap and structconf::ini to avoid duplicate dependencies and not having to include them in your Cargo.toml.

Additional attributes can be added to its fields to customize how they are parsed:

General attributes

  • default = "...": a Rust expression that will be evaluated as a fallback value. For example, default = "1+2", or default = "String::from(\"hello\""). Otherwise, the value given by std::default::Default will be used, or in case the assigned type is Option<T>*, None.

* Note: the assigned type must be exactly Option<T> for this to work. std::option::Option<T> won’t work, for example.

Argument parser attributes

  • help = "...": the help message shown in the argument parser when --help is used.
  • long = "arg_name": a custom long argument name. Otherwise, it will be obtained directly from the field’s name. do_something will be --do-something.
  • no_long: don’t include the option as a long argument.
  • short = "x": a custom short argument name (only made up of a single character). Otherwise, it will be obtained directly from the field’s name. do_something will be -d.
  • no_short: don’t include the option as a short argument.
  • negated_arg: the flag’s value is the opposite:
use structconf::StructConf;

struct Bakery {
    // By default it's `true`, unless `--no-pancakes` is passed.
    #[conf(negated_arg, no_short, long = "no-pancakes")]
    pancakes: bool

If both no_long and no_short are provided, the option won’t be available in the argument parser at all.

Config file attributes

  • file = "...": set a custom name in the config file. Otherwise, it will be the same as the field’s identifier.
  • no_file: don’t include the option in the config file.
  • section: the section in the config file where the option will be. Otherwise, Default is used. For example, #[structconf(section = "Planes")] model_id: i32 will look like this in the config file:
model_id = 123


pub use clap;
pub use ini;


Small wrapper for the possible errors that may occur when parsing a StructConf-derived struct.


This trait implements the methods available after using #[derive(StructConf)].

Derive Macros