{"id":18003161,"url":"https://github.com/leptonyu/cfg-rs","last_synced_at":"2026-02-11T07:15:53.564Z","repository":{"id":57546482,"uuid":"396015057","full_name":"leptonyu/cfg-rs","owner":"leptonyu","description":"A Configuration Library for Rust Applications","archived":false,"fork":false,"pushed_at":"2025-03-11T02:24:43.000Z","size":281,"stargazers_count":39,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T11:11:24.689Z","etag":null,"topics":["config","configuration","environment","json","rust","settings","toml","yaml"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/cfg-rs","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leptonyu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-14T13:19:01.000Z","updated_at":"2025-03-11T02:24:46.000Z","dependencies_parsed_at":"2023-10-25T04:23:43.400Z","dependency_job_id":"e6cedbd3-1b13-4562-b2ae-8a5ae02c53fe","html_url":"https://github.com/leptonyu/cfg-rs","commit_stats":{"total_commits":199,"total_committers":3,"mean_commits":66.33333333333333,"dds":"0.25125628140703515","last_synced_commit":"7ca983b12ac58e735f25523547bbcd7c1b5a46d5"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leptonyu%2Fcfg-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leptonyu%2Fcfg-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leptonyu%2Fcfg-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leptonyu%2Fcfg-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leptonyu","download_url":"https://codeload.github.com/leptonyu/cfg-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332612,"owners_count":20921853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["config","configuration","environment","json","rust","settings","toml","yaml"],"created_at":"2024-10-29T23:25:45.766Z","updated_at":"2026-02-11T07:15:53.558Z","avatar_url":"https://github.com/leptonyu.png","language":"Rust","funding_links":[],"categories":["Libraries"],"sub_categories":["Configuration"],"readme":"# cfg-rs: A Configuration Library for Rust Applications\n\n[![Crates.io](https://img.shields.io/crates/v/cfg-rs?style=flat-square)](https://crates.io/crates/cfg-rs)\n[![Crates.io](https://img.shields.io/crates/d/cfg-rs?style=flat-square)](https://crates.io/crates/cfg-rs)\n[![Documentation](https://docs.rs/cfg-rs/badge.svg)](https://docs.rs/cfg-rs)\n[![dependency status](https://deps.rs/repo/github/leptonyu/cfg-rs/status.svg)](https://deps.rs/crate/cfg-rs)\n[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/leptonyu/cfg-rs/blob/master/LICENSE)\n[![Actions Status](https://github.com/leptonyu/cfg-rs/workflows/Rust/badge.svg)](https://github.com/leptonyu/cfg-rs/actions)\n[![Minimum supported Rust version](https://img.shields.io/badge/rustc-1.85+-green.svg)](#minimum-supported-rust-version)\n\ncfg-rs is a lightweight, flexible configuration loader for Rust applications. It composes multiple sources (files, env, inline maps, random, etc.), supports live refresh, placeholder expansion, and derive-based typed configs — all without a serde dependency.\n\nSee the [examples](https://github.com/leptonyu/cfg-rs/tree/main/examples) directory for end-to-end demos.\n\n## Features\n\n- Single call to load typed config: see [Configuration::get](struct.Configuration.html#method.get)\n- Derive your config types: see [FromConfig](derive.FromConfig.html)\n- Default values via field attributes: see [field attributes](derive.FromConfig.html#field-annotation-attribute)\n- Placeholder expansion like `${cfg.key}`: see [ConfigValue](enum.ConfigValue.html#placeholder-expression)\n- Random values under the `rand` feature (e.g. `configuration.get::\u003cu8\u003e(\"random.u8\")`)\n- Refreshable values via [RefValue](struct.RefValue.html) and refreshable [Configuration](struct.Configuration.html)\n- Pluggable sources with clear priority: see [register_source](struct.Configuration.html#method.register_source)[^priority]\n- No serde dependency\n\n[^priority]: Source precedence follows registration order — earlier registrations have higher priority.\n\n## Supported formats and feature flags\n\nBuilt-in file parsers (enable via Cargo features):\n\n- `toml`: extensions `.toml`, `.tml`\n- `yaml`: extensions `.yaml`, `.yml`\n- `json`: extension `.json`\n- `ini`: extension `.ini`\n\nOther useful features:\n\n- `rand`: random value provider (e.g. `random.u8`, `random.string`)\n- `log`: minimal logging integration for value parsing\n- `coarsetime`: coarse time helpers for time-related values\n- `regex`: regex validation support for `#[validate(regex = ...)]`\n\n## Installation\n\nAdd to your Cargo.toml with the features you need:\n\n```toml\n[dependencies]\ncfg-rs = { version = \"^0.6\", features = [\"toml\"] }\n```\n\nFor a batteries-included setup, use the convenience feature set:\n\n```toml\ncfg-rs = { version = \"^0.6\", features = [\"full\"] }\n```\n\n## Quick start\n\n### 1) One-liner with predefined sources\n\n```rust\nuse cfg_rs::*;\n\nlet configuration = Configuration::with_predefined().unwrap();\n// use configuration.get::\u003cT\u003e(\"your.key\") or derive types (see below)\n```\n\nSee [PredefinedConfigurationBuilder::init](struct.PredefinedConfigurationBuilder.html#method.init) for details.\n\n### 2) Customize predefined builder\n\n```rust,no_run\nuse cfg_rs::*;\ninit_cargo_env!();\n\nlet configuration = Configuration::with_predefined_builder()\n    .set_cargo_env(init_cargo_env())\n    .init()\n    .unwrap();\n```\n\n### 3) Compose your own sources (priority = registration order)\n\n```rust,no_run\nuse cfg_rs::*;\ninit_cargo_env!();\n\nlet mut configuration = Configuration::new()\n    // Layer 0: Cargo env source.\n    .register_source(init_cargo_env()).unwrap()\n    // Layer 1: Inline key-values.\n    .register_kv(\"inline\")\n        .set(\"hello\", \"world\")\n        .finish()\n        .unwrap();\n\n// Layer 2: Random values (feature = \"rand\").\n#[cfg(feature = \"rand\")]\n{\n    configuration = configuration.register_random().unwrap();\n}\n\n// Layer 3: All environment variables with prefix `CFG_`.\nconfiguration = configuration.register_prefix_env(\"CFG\").unwrap();\n\n// Layer 4: File(s) — extension inferred by feature (e.g. yaml).\nconfiguration = configuration.register_file(\"/conf/app.yaml\", true).unwrap();\n\n// Optional: register an inline file content (e.g. TOML) and merge.\n#[cfg(feature = \"toml\")]\n{\n    let toml = inline_source!(\"app.toml\").unwrap();\n    configuration = configuration.register_source(toml).unwrap();\n}\n\n// Finally use it.\n// let port: u16 = configuration.get(\"server.port\").unwrap();\n```\n\nSee [register_kv](struct.Configuration.html#method.register_kv), [register_file](struct.Configuration.html#method.register_file), [register_random](struct.Configuration.html#method.register_random), and [register_prefix_env](struct.Configuration.html#method.register_prefix_env).\n\n### 4) Handy helpers for tests and small apps\n\n- From inline map (macro):\n\n```rust\n#[derive(Debug, cfg_rs::FromConfig)]\nstruct AppCfg { port: u16, host: String }\n\nlet cfg: AppCfg = cfg_rs::from_static_map!(AppCfg, {\n    \"port\" =\u003e \"8080\",\n    \"host\" =\u003e \"localhost\",\n});\n```\n\n- From environment variables:\n\n```rust\n\n#[derive(Debug, cfg_rs::FromConfig)]\nstruct AppCfg { port: u16, host: String }\n\nunsafe {\n    std::env::set_var(\"CFG_APP_PORT\", \"8080\");\n    std::env::set_var(\"CFG_APP_HOST\", \"localhost\");\n}\nlet cfg: AppCfg = cfg_rs::from_env(\"CFG_APP\").unwrap();\n```\n\n## Derive typed configs\n\nImplement strong-typed configs via derive:\n\n```rust,no_run\n\n#[derive(Debug, cfg_rs::FromConfig)]\n#[config(prefix = \"cfg.app\")] // optional, implements FromConfigWithPrefix\nstruct AppCfg {\n    port: u16,              // required\n    #[config(default = true)]\n    enabled: bool,          // has default value\n    #[config(name = \"ip\")] // remap field name\n    host: String,\n}\n```\n\nAttributes summary:\n\n- `#[config(prefix = \"cfg.app\")]` on struct: implement `FromConfigWithPrefix`\n- `#[config(name = \"...\")]` on field: rename field key\n- `#[config(default = \u003cexpr\u003e)]` on field: default value when missing\n\nSee the full reference in [derive.FromConfig](derive.FromConfig.html).\n\n## Validation\n\nThe derive macro supports field-level validation via `#[validate(...)]`.\nThe rules are implemented in [src/validate.rs](src/validate.rs) and are\ninvoked after parsing field values.\n\nAvailable validators:\n\n- `range(min = \u003cexpr\u003e, max = \u003cexpr\u003e)` for comparable values\n- `length(min = \u003cusize\u003e, max = \u003cusize\u003e)` for string/collection/path length\n- `not_empty` for any type implementing `ValidateLength`\n- `regex = \"...\"` (feature = `regex`) for regex matching on strings (pattern can be a string literal or `const \u0026str`)\n- `custom = \"path::to::fn\"` for user-defined validation\n\nNote: `cfg(feature = \"...\")` checks features of your crate, not dependency features. If you want to gate regex/email fields, define a feature in your crate that enables `cfg-rs/regex` (e.g. `regex = [\"cfg-rs/regex\"]`) and use that feature in `#[cfg(...)]`.\n\nExample:\n\n```rust,no_run\n#[cfg(feature = \"regex\")]\nconst USER_RE: \u0026str = \"^u[a-z]+$\";\n\n#[derive(Debug, cfg_rs::FromConfig)]\n#[config(prefix = \"app\")]\nstruct AppCfg {\n    #[validate(range(min = 1, max = 65535))]\n    port: u16,\n    #[validate(length(min = 1, max = 32))]\n    name: String,\n    #[validate(custom = check_threads)]\n    threads: usize,\n    #[cfg(feature = \"regex\")]\n    #[validate(regex = USER_RE)]\n    user: String,\n}\n\nfn check_threads(v: \u0026usize) -\u003e Result\u003c(), String\u003e {\n    if *v == 0 {\n        return Err(\"threads must be \u003e 0\".to_string());\n    }\n    Ok(())\n}\n```\n\n## Placeholders, randoms, and refresh\n\n- Placeholder expansion: use `${some.key}` inside string values; see [ConfigValue](enum.ConfigValue.html#placeholder-expression)\n- Random values: under `rand`, keys like `random.u8`, `random.string` provide per-read randoms\n- Refreshing: `Configuration::refresh()` re-reads sources that allow refresh; `RefValue\u003cT\u003e` updates on refresh\n\n## Examples\n\nBrowse runnable examples covering common patterns:\n\n- `simple`: minimal setup (full feature set)\n- `profile`: working with profiles (requires `toml`)\n- `watch`: basic file watching and refresh (requires `yaml`)\n- `refresh`: manual refresh and `RefValue`\n- `logger`: logging integration (requires `full`)\n- `thread_pool`, `salak`, `test_suit`: larger samples and integrations\n\nhttps://github.com/leptonyu/cfg-rs/tree/main/examples\n\n## License\n\nMIT © contributors. See [LICENSE](https://github.com/leptonyu/cfg-rs/blob/main/LICENSE).\n\n## Minimum supported Rust version\nThis crate supports Rust **1.85** and newer. Older Rust versions are not guaranteed to compile or be tested.\n\n## Tips and notes\n\n- Source priority is deterministic: earlier registrations override later ones[^priority]\n- This crate intentionally does not depend on serde\n- Docs.rs builds enable all features for a comprehensive reference\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleptonyu%2Fcfg-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleptonyu%2Fcfg-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleptonyu%2Fcfg-rs/lists"}