#flags #parse #argument #parser #command-line

nightly zcfg

No-frills library and binary configuration via command line or file

2 unstable releases

Uses old Rust 2015

0.2.0 Dec 1, 2017
0.1.0 Jul 15, 2017

#548 in Configuration

24 downloads per month
Used in zcfg_flag_parser

Apache-2.0

20KB
477 lines

zcfg

zcfg is a simple configuration library. It lets you define configurable values for your Rust library, without coupling you to a particular parsing format, or requiring plumbing in the binary.

Unlike other common configuration or flag libraries, you do not need to propagate internal details of your application into main, and you do not need to force users to configure internal details of your library if they choose not to.

It is inspired by gflags and similar global configuration systems.

Features

  • Define configuration values right where they're relevant
#![feature(used)]
#[macro_use]
extern crate lazy_static;
#[macro_use]
extern crate zcfg;

define_pub_cfg!(net_protocol_timeout_ms, u32, 20000,
                "How long the server or client should wait before considering \
                this connection timed out.")
  • Access the values while initializing your domain objects
struct NetProtocolClient {
  timeout_ms: u32,
}

impl Default for NetProtocolClient {
  fn default() -> NetProtocolClient {
    NetProtocolClient {
      timeout_ms: net_protocol_timeout_ms::CONFIG.get_value(),
    }
  }
}
  • Let binaries decide how they'd like to bring in config values
extern crate zcfg;
extern crate zcfg_flag_parser;

use zcfg_flag_parser::FlagParser;

fn main() {
  // Parse flags for all linked crates via command line
  FlagParser::new().parse_from_args(env::args().skip(1)).unwrap();
}
  • Make any of your types configurable
use zcfg::ConfigParsable;

enum BuildStrategy {
  Local,
  Remote {
    addr: String,
  }
}
impl ConfigParsable for BuildStrategy { ... }

define_cfg!(use_build_strategy, BuildStrategy, BuildStrategy::Local,
            "Defines how the build planner performs compilation. Options are \
             [Local] or [Remote(\"some_address\")].")

Best Practices

  • Limit access of configs to object initialization under default confitions to preserve testability
  • Consider define_pub_cfg if you'd like other modules to use the config.
  • Ensure that default values are useful -- users may not perform config population at all.

Roadmap

  • A "Help" functionality that emits config names, default values, and config descriptions for public consumption
  • Build on stable! zcfg currently depends on the experimental used feature to prevent config initializers from being dropped by the compiler.

How it works

Really dark stuff. zcfg uses a combination of linker flags and the used experimental feature to enqueue all flags defined in linked libraries in a global list, which main can populate without knowing about.

Dependencies

~14KB