rust-config-tree handbok

Detta ar den svenska handboken for rust-config-tree.

Börja med Introduktion, Snabbstart eller de korbara Exemplen.

Introduktion

rust-config-tree tillhandahaller ateranvandbar laddning av konfigurationstrad och CLI-hjalpare for Rust-program som anvander lagerindelade konfigurationsfiler.

Craten bygger pa en liten ansvarsfördelning:

confique ager schemadefinitioner, kodstandardvarden, validering och generering av konfigurationsmallar.
figment ager runtime-laddning och runtime-kallmetadata.
rust-config-tree ager rekursiv include-traversering, include-sokvagsupplosning, .env-laddning, upptackt av mallmal och ateranvandbara clap-kommandon.

Craten ar anvandbar nar ett program vill ha en naturlig filstruktur for konfiguration, till exempel:

include:
  - config/server.yaml
  - config/database.yaml

log:
  level: info

Varje inkluderad fil kan anvanda samma schemaform, och relativa include-sokvagar loses fran filen som deklarerade dem. Den slutliga konfigurationen ar fortfarande ett normalt confique-schemavarde.

Huvudfunktioner

Rekursiv include-traversering med cykeldetektering.
Relativa include-sokvagar loses fran deklarerande fil.
.env laddas innan miljo-providers utvarderas.
Schemadeklarerade miljovariabler utan delimitersplittring.
Figment-metadata for runtime-kallspArning.
KallspArningshandelser pa TRACE-niva via tracing.
Draft 7 JSON Schema-generering for editor-komplettering och grundlaggande schemakontroller.
Faltvardevalidering i programkod med #[config(validate = Self::validate)], kord via load_config eller config-validate.
Generering av YAML-, TOML-, JSON- och JSON5-mallar.
TOML #:schema, YAML Language Server-modelines och JSON/JSON5-$schema-falt for genererade mallar.
Opt-in YAML-malluppdelning for sektioner markerade med x-tree-split.
Inbyggda clap-underkommandon for konfigurationsmallar, JSON Schema och skalkompletteringar.
Ett lagre niva trad-API for anropare som inte anvander confique.

Publika inganger

Anvand dessa API:er for de flesta program:

load_config::<S>(path) laddar det slutliga schemat.
load_config_with_figment::<S>(path) laddar schemat och returnerar Figment-grafen som anvands for kallspArning.
write_config_templates::<S>(config_path, output_path) skriver rotmallen och rekursivt upptackta barnmallar.
write_config_schemas::<S>(output_path) skriver rot- och sektions-JSON Schemas enligt Draft 7.
handle_config_command::<Cli, S>(command, config_path) hanterar inbyggda clap-konfigurationskommandon.

Anvand load_config_tree nar du behover traverseringsprimitiven utan confique.

Snabbstart

Lagg till craten och de schema/runtime-bibliotek som programmet anvander:

[dependencies]
rust-config-tree = "0.1"
confique = { version = "0.4", features = ["yaml", "toml", "json5"] }
figment = { version = "0.10", features = ["yaml", "toml", "json", "env"] }
schemars = { version = "1", features = ["derive"] }
serde = { version = "1", features = ["derive"] }
clap = { version = "4", features = ["derive"] }

Definiera ett confique-schema och implementera ConfigSchema for rottypen:

#![allow(unused)]
fn main() {
use std::path::PathBuf;

use confique::Config;
use rust_config_tree::ConfigSchema;

#[derive(Debug, Config)]
struct AppConfig {
    #[config(default = [])]
    include: Vec<PathBuf>,

    #[config(nested)]
    server: ServerConfig,
}

#[derive(Debug, Config)]
struct ServerConfig {
    #[config(default = "127.0.0.1")]
    #[config(env = "APP_SERVER_BIND")]
    bind: String,

    #[config(default = 8080)]
    #[config(env = "APP_SERVER_PORT")]
    port: u16,
}

impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }
}
}

Ladda konfigurationen:

#![allow(unused)]
fn main() {
use rust_config_tree::load_config;

let config = load_config::<AppConfig>("config.yaml")?;
println!("{config:#?}");
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Anvand en rotfil med rekursiva includes:

# config.yaml
include:
  - config/server.yaml

# config/server.yaml
server:
  bind: 0.0.0.0
  port: 3000

Standardprioriteten for load_config ar:

environment variables
  > config files, with later merged files overriding earlier files
    > confique code defaults

Nar includes laddas av hog-niva-API:t har rotfilen hogsta filprioritet. Inkluderade filer ger lagre prioriterade varden och kan anvandas for standardvarden eller sektionsspecifika filer.

Kommandoradsargument ar programspecifika, sa load_config laser dem inte automatiskt. Slå samman CLI-overrides efter build_config_figment nar programmet har override-flaggor for konfiguration:

CLI-flaggornas namn valjs av programmet. De ar inte automatiskt a.b.c-konfigurationssokvagar. Foredra normala clap-flaggor som --server-port, och mappa dem sedan till en nastlad override-struktur. Den nastlade serialiserade formen styr vilken konfigurationsnyckel som skrivs over.

Endast varden som representeras i programmets CliOverrides-provider skriver over konfiguration. Detta ar anvandbart for parametrar som ofta andras for en enskild korning utan att redigera konfigurationsfilen. Stabila varden bor ligga i konfigurationsfiler.

#![allow(unused)]
fn main() {
use figment::providers::Serialized;
use serde::Serialize;
use rust_config_tree::{build_config_figment, load_config_from_figment};

#[derive(Debug, Serialize)]
struct CliOverrides {
    #[serde(skip_serializing_if = "Option::is_none")]
    server: Option<CliServerOverrides>,
}

#[derive(Debug, Serialize)]
struct CliServerOverrides {
    #[serde(skip_serializing_if = "Option::is_none")]
    port: Option<u16>,
}

let cli_overrides = CliOverrides {
    server: Some(CliServerOverrides { port: Some(9000) }),
};

let figment = build_config_figment::<AppConfig>("config.yaml")?
    .merge(Serialized::defaults(cli_overrides));

let config = load_config_from_figment::<AppConfig>(&figment)?;
let _ = config;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Med CLI-overrides sammanslagna pa detta satt ar full prioritet:

command-line overrides
  > environment variables
    > config files
      > confique code defaults

Konfigurationsschema

Programscheman ar vanliga confique-konfigurationstyper. Rotschemat maste implementera ConfigSchema sa rust-config-tree kan upptacka rekursiva includes fran det mellanliggande confique-lagret.

#![allow(unused)]
fn main() {
use std::path::PathBuf;

use confique::Config;
use schemars::JsonSchema;
use rust_config_tree::ConfigSchema;

#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(default = [])]
    include: Vec<PathBuf>,

    #[config(nested)]
    #[schemars(extend("x-tree-split" = true))]
    database: DatabaseConfig,
}

#[derive(Debug, Config, JsonSchema)]
struct DatabaseConfig {
    #[config(env = "APP_DATABASE_URL")]
    url: String,

    #[config(default = 16)]
    #[config(env = "APP_DATABASE_POOL_SIZE")]
    pool_size: u32,
}

impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }
}
}

Include-falt

Include-faltet kan ha vilket namn som helst. rust-config-tree kanner bara till det via ConfigSchema::include_paths.

Faltet bor normalt ha en tom standard:

#![allow(unused)]
fn main() {
#[config(default = [])]
include: Vec<PathBuf>,
}

Laddaren tar emot ett partiellt laddat lager for varje fil. Det gor att den kan upptacka barnkonfigurationsfiler innan det slutliga schemat slas samman och valideras.

Nastlade sektioner

Anvand #[config(nested)] for strukturerade sektioner. Nastlade sektioner anvands alltid for runtime-laddning. Lagg till #[schemars(extend("x-tree-split" = true))] nar ett nastlat falt ocksa ska genereras som egen *.yaml-mall och <section>.schema.json-schema:

#![allow(unused)]
fn main() {
#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(nested)]
    #[schemars(extend("x-tree-split" = true))]
    server: ServerConfig,
}
}

Den naturliga YAML-formen ar:

server:
  bind: 127.0.0.1
  port: 8080

Endast miljo-falt

Markera ett bladfalt med #[schemars(extend("x-env-only" = true))] nar vardet bara ska komma fran en miljovariabel och inte ska visas i genererade konfigurationsfiler. Genererade YAML-mallar och JSON Schemas utelamnar env-only-falt, och foralderobjekt som blir tomma tas bort.

#![allow(unused)]
fn main() {
#[config(env = "APP_SECRET")]
#[schemars(extend("x-env-only" = true))]
secret: String,
}

Faltvardevalidering

Genererade *.schema.json-filer ar bara for IDE-komplettering och grundlaggande editor-kontroller. De avgor inte om ett konkret faltvarde ar giltigt for programmet.

Faltvardevalidering ska implementeras i kod med #[config(validate = Self::validate)]. Validatorn kors nar den slutliga konfigurationen laddas med load_config eller kontrolleras med config-validate.

Overstyrning av mallsektioner

Nar en mallkalla saknar includes kan craten harleda barnmallfiler fran nastlade schemasektioner markerade med x-tree-split. Standardsokvagen pa toppniva ar <section>.yaml.

Overstyr den sokvagen med template_path_for_section:

#![allow(unused)]
fn main() {
impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }

    fn template_path_for_section(section_path: &[&str]) -> Option<PathBuf> {
        match section_path {
            ["database"] => Some(PathBuf::from("examples/database.yaml")),
            _ => None,
        }
    }
}
}

Runtime-laddning

Runtime-laddning ar avsiktligt uppdelad mellan Figment och confique:

figment:
  runtime file loading
  runtime environment loading
  runtime source metadata

confique:
  schema metadata
  defaults
  validation
  config templates

Huvud-API:t ar:

#![allow(unused)]
fn main() {
use rust_config_tree::load_config;

let config = load_config::<AppConfig>("config.yaml")?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Anvand load_config_with_figment nar programmet behover kallmetadata:

#![allow(unused)]
fn main() {
use rust_config_tree::load_config_with_figment;

let (config, figment) = load_config_with_figment::<AppConfig>("config.yaml")?;
let _ = (config, figment);
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Laddningssteg

Hog-niva-laddaren gor dessa steg:

Los rotkonfigurationssokvagen lexikalt.
Ladda den forsta .env-filen som hittas genom att ga uppat fran rotkonfigurationskatalogen.
Ladda varje konfigurationsfil som ett partiellt lager for att upptacka includes.
Bygg en Figment-graf fran de upptackta konfigurationsfilerna.
Slå samman ConfiqueEnvProvider med hogre prioritet an filer.
Slå eventuellt samman programspecifika CLI-overrides.
Extrahera ett confique-lager fran Figment.
Applicera confique-kodstandardvarden.
Validera och skapa det slutliga schemat.

load_config och load_config_with_figment utfor steg 1-5 och 7-9. Steg 6 ar programspecifikt eftersom denna crate inte kan avgora hur en CLI-flagga mappar till ett schemafalt.

Filformat

Runtime-filprovidern valjs fran konfigurationssokvagens filandelse:

.yaml och .yml anvander YAML.
.toml anvander TOML.
.json och .json5 anvander JSON.
okanda eller saknade filandelser anvander YAML.

Mallgenerering anvander fortfarande confiques mallrenderare for YAML, TOML och JSON5-kompatibel utdata.

Include-prioritet

Hog-niva-laddaren slar samman filproviders sa inkluderade filer har lagre prioritet an filen som inkluderade dem. Rotkonfigurationsfilen har hogsta filprioritet.

Miljovariabler har hogre prioritet an alla konfigurationsfiler. confique standardvarden anvands bara for varden som inte tillhandahalls av runtime-providers.

Nar CLI-overrides slas samman efter build_config_figment ar full prioritet:

command-line overrides
  > environment variables
    > config files
      > confique code defaults

Kommandoradssyntaxen definieras inte av rust-config-tree. En flagga som --server-port kan skriva over server.port om programmet mappar det parsade vardet till en nastlad serialiserad provider. En punktad syntax som --server.port eller a.b.c finns bara om programmet implementerar den.

Det betyder att CLI-prioritet bara galler nycklar som finns i programmets override-provider. Anvand det for operativa varden som ofta andras for en enda korning. Lamna varaktig konfiguration i filer.

#![allow(unused)]
fn main() {
use figment::providers::Serialized;
use serde::Serialize;
use rust_config_tree::{build_config_figment, load_config_from_figment};

#[derive(Debug, Serialize)]
struct CliOverrides {
    #[serde(skip_serializing_if = "Option::is_none")]
    server: Option<CliServerOverrides>,
}

#[derive(Debug, Serialize)]
struct CliServerOverrides {
    #[serde(skip_serializing_if = "Option::is_none")]
    port: Option<u16>,
}

let cli_overrides = CliOverrides {
    server: Some(CliServerOverrides { port: Some(9000) }),
};

let figment = build_config_figment::<AppConfig>("config.yaml")?
    .merge(Serialized::defaults(cli_overrides));

let config = load_config_from_figment::<AppConfig>(&figment)?;
let _ = config;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Miljovariabler

Miljovariabelnamn deklareras i schemat med confique:

#![allow(unused)]
fn main() {
#[derive(Debug, Config)]
struct DatabaseConfig {
    #[config(env = "APP_DATABASE_URL")]
    url: String,

    #[config(default = 16)]
    #[config(env = "APP_DATABASE_POOL_SIZE")]
    pool_size: u32,
}
}

rust-config-tree laser dessa namn fran confique::Config::META och bygger en Figment-provider som mappar varje miljovariabel till dess exakta faltvag.

Anvand inte delimiterbaserad Figment-miljomappning for denna crate:

#![allow(unused)]
fn main() {
// Do not use this pattern for rust-config-tree schemas.
Env::prefixed("APP_").split("_")
Env::prefixed("APP_").split("__")
}

split("_") behandlar understreck som separatorer for nastlade nycklar. Det gor att APP_DATABASE_POOL_SIZE blir en vag som database.pool.size, vilket krockar med Rust-faltnamn som pool_size.

Med ConfiqueEnvProvider ar mappningen explicit:

APP_DATABASE_POOL_SIZE -> database.pool_size

Enskilda understreck fortsatter vara en del av miljovariabelnamnet. Figment gissar ingen nastlingsregel.

Dotenv-laddning

Innan runtime-providers utvarderas letar laddaren efter en .env-fil genom att ga uppat fran rotkonfigurationsfilens katalog.

Befintliga processmiljovariabler bevaras. Varden fran .env fyller bara i saknade miljovariabler.

Exempel:

APP_SERVER_PORT=9000
APP_DATABASE_POOL_SIZE=64

Dessa variabler skriver over konfigurationsfilvarden nar schemat deklarerar matchande #[config(env = "...")]-attribut.

Parsning av varden

Bryggprovidern later Figment parsa miljovarden. Den anropar inte confique:s parse_env-hooks. Hall komplexa varden i konfigurationsfiler om inte Figments syntax for miljovarden passar typen.

KallspArning

Anvand load_config_with_figment for att behalla Figment-grafen som anvands av runtime-laddningen:

#![allow(unused)]
fn main() {
use rust_config_tree::load_config_with_figment;

let (config, figment) = load_config_with_figment::<AppConfig>("config.yaml")?;
let _ = config;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Det returnerade Figment-vardet kan besvara kallfragor for runtime-varden:

#![allow(unused)]
fn main() {
if let Some(metadata) = figment.find_metadata("database.pool_size") {
    let source = metadata.interpolate(
        &figment::Profile::Default,
        &["database", "pool_size"],
    );

    println!("database.pool_size came from {source}");
}
}

For varden som tillhandahalls av ConfiqueEnvProvider returnerar interpolation det ursprungliga miljovariabelnamnet som deklarerats i schemat:

database.pool_size came from APP_DATABASE_POOL_SIZE

TRACE-handelse

Laddaren skickar kallspArningshandelser med tracing::trace!. Den gor det bara nar TRACE ar aktiverat:

#![allow(unused)]
fn main() {
use rust_config_tree::{load_config_with_figment, trace_config_sources};

let (config, figment) = load_config_with_figment::<AppConfig>("config.yaml")?;

// If the tracing subscriber is initialized after config loading, emit the
// same source events again after installing the subscriber.
trace_config_sources::<AppConfig>(&figment);
let _ = config;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Varje handelse anvander target rust_config_tree::config och innehaller:

config_key: den punktade konfigurationsnyckeln.
source: renderad kallmetadata.

Varden som bara kommer fran confique-standardvarden saknar Figment-runtime-metadata. De rapporteras som confique default or unset optional field.

Mallgenerering

Mallar genereras fran samma confique-schema som anvands vid runtime. confique renderar sjalva mallinnehållet, inklusive dokumentationskommentarer, standardvarden, obligatoriska falt och deklarerade miljovariabelnamn.

Anvand write_config_templates:

#![allow(unused)]
fn main() {
use rust_config_tree::write_config_templates;

write_config_templates::<AppConfig>("config.yaml", "config.example.yaml")?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Generera Draft 7 JSON Schemas for rotkonfigurationen och delade nastlade sektioner:

#![allow(unused)]
fn main() {
use rust_config_tree::write_config_schemas;

write_config_schemas::<AppConfig>("schemas/myapp.schema.json")?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Markera ett nastlat falt med #[schemars(extend("x-tree-split" = true))] nar det ska genereras som en egen *.yaml-mall och ett eget <section>.schema.json-schema. Omarkerade nastlade falt stannar i foraldramallen och foraldraschemat.

Markera ett bladfalt med #[schemars(extend("x-env-only" = true))] nar vardet bara ska komma fran miljovariabler. Genererade mallar och JSON Schemas utelamnar env-only-falt, och foralderobjekt som blir tomma tas bort.

Genererade scheman utelamnar required-begransningar. IDE:er kan fortfarande erbjuda komplettering, men partiella filer som log.yaml rapporterar inte saknade rotfalt. Rotschemat kompletterar bara falt som hor hemma i rotfilen; delade sektionsfalt utelamnas dar och kompletteras av sina egna sektionsscheman. Befintliga falt kan fortfarande fa grundlaggande editor-kontroller, som typ, enum och okanda properties som stods av det genererade schemat. Genererade *.schema.json-filer avgor inte om ett konkret faltvarde ar giltigt for programmet. Faltvardevalidering ska implementeras i kod med #[config(validate = Self::validate)]; load_config och config-validate kor den runtime-valideringen.

Bind dessa scheman fran genererade TOML-, YAML-, JSON- och JSON5-mallar:

#![allow(unused)]
fn main() {
use rust_config_tree::write_config_templates_with_schema;

write_config_templates_with_schema::<AppConfig>(
    "config.toml",
    "config.example.toml",
    "schemas/myapp.schema.json",
)?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Rotmallar for TOML och YAML binder rotschemat och kompletterar inte delade barnsektioners falt. Delade YAML-sektionsmallar binder sina sektionsscheman. JSON- och JSON5-mallar far ett rotfalt $schema som VS Code kan kanna igen. VS Code json.schemas ar fortfarande en alternativ bindningsvag.

Utdataformatet harleds fran utdatasokvagen:

.yaml och .yml genererar YAML.
.toml genererar TOML.
.json och .json5 genererar JSON5-kompatibla mallar.
okanda eller saknade filandelser genererar YAML.

Schemabindningar

Med schemasokvagen schemas/myapp.schema.json anvander genererade rotmallar:

#:schema ./schemas/myapp.schema.json

# yaml-language-server: $schema=./schemas/myapp.schema.json

Genererade sektionsmallar binder sektionsscheman:

# log.yaml
# yaml-language-server: $schema=./schemas/log.schema.json

Genererade JSON- och JSON5-mallar skriver ett rotfalt $schema som VS Code kanner igen. Editor-installningar ar fortfarande valfria:

{
  "json.schemas": [
    {
      "fileMatch": [
        "/config.json",
        "/config.*.json"
      ],
      "url": "./schemas/myapp.schema.json"
    }
  ]
}

Val av mallkalla

Mallgenerering valjer sitt kalltrad i denna ordning:

Befintlig konfigurationssokvag.
Befintlig utdatasokvag for mall.
Utdatasokvagen behandlad som ett nytt tomt malltrad.

Det later ett projekt uppdatera mallar fran aktuella konfigurationsfiler, uppdatera en befintlig malluppsattning eller skapa en ny malluppsattning bara fran schemat.

Speglade include-trad

Om kallfilen deklarerar includes speglar genererade mallar dessa include-sokvagar under utdatakatalogen.

# config.yaml
include:
  - server.yaml

Generering av config.example.yaml skriver:

config.example.yaml
server.yaml

Relativa include-mal speglas under utdatafilens foraldrakatalog. Absoluta include-mal forblir absoluta.

Opt-in-sektionsuppdelning

Nar en kallfil saknar includes kan craten harleda include-mal fran nastlade schemasektioner markerade med x-tree-split. For ett schema med en markerad server-sektion kan en tom rotmallkalla producera:

config.example.yaml
server.yaml

Rotmallen far ett include-block, och server.yaml innehaller bara server-sektionen. Nastlade sektioner delas rekursivt bara nar de falten ocksa bar x-tree-split.

IDE-kompletteringar

Genererade JSON Schemas kan anvandas av TOML-, YAML-, JSON- och JSON5-konfigurationsfiler. De genereras fran samma Rust-typ som anvands av confique:

#![allow(unused)]
fn main() {
use confique::Config;
use schemars::JsonSchema;

#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(nested)]
    #[schemars(extend("x-tree-split" = true))]
    server: ServerConfig,
}
}

Generera dem med:

#![allow(unused)]
fn main() {
use rust_config_tree::write_config_schemas;

write_config_schemas::<AppConfig>("schemas/myapp.schema.json")?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Detta skriver rotschemat och sektionsscheman som schemas/server.schema.json. Genererade scheman utelamnar required-begransningar sa komplettering fungerar for partiella konfigurationsfiler utan diagnostik for saknade falt. Rotschemat utelamnar delade sektionsproperties, sa barnsektionskomplettering ar bara tillganglig i filer som binder matchande sektionsschema. Omarkerade nastlade sektioner stannar i rotschemat.

Falt markerade med x-env-only utelamnas fran genererade scheman, sa IDE:er foreslar inte secrets eller andra varden som bara ska komma fran miljovariabler.

IDE-scheman ar for komplettering och grundlaggande editor-kontroller, som typ, enum och okanda properties som stods av det genererade schemat. De avgor inte om ett konkret faltvarde ar giltigt for programmet. Faltvardevalidering ska implementeras i kod med #[config(validate = Self::validate)] och koras via load_config eller config-validate. Obligatoriska falt och slutlig sammanslagen konfigurationsvalidering anvander ocksa dessa runtime-vagar.

TOML

TOML-filer bor binda schemat med ett #:schema-direktiv hogst upp:

#:schema ./schemas/myapp.schema.json

[server]
bind = "0.0.0.0"
port = 3000

Anvand inte ett rot-$schema = "..."-falt i TOML. Det blir riktig konfigurationsdata och kan paverka runtime-deserialisering. write_config_templates_with_schema lagger automatiskt till #:schema- direktivet for TOML-mallar.

YAML

YAML-filer bor anvanda YAML Language Servers modeline:

# yaml-language-server: $schema=./schemas/myapp.schema.json

server:
  bind: 0.0.0.0
  port: 3000

write_config_templates_with_schema lagger automatiskt till denna modeline for YAML-mallar. Delade YAML-mallar binder sitt sektionsschema, till exempel binder log.yaml ./schemas/log.schema.json.

JSON

JSON- och JSON5-filer kan binda ett schema med ett rotfalt $schema. write_config_templates_with_schema lagger till det automatiskt for genererade JSON- och JSON5-mallar:

{
  "$schema": "./schemas/myapp.schema.json"
}

Editor-installningar ar fortfarande anvandbara nar ett projekt inte vill ha bindning i filen:

{
  "json.schemas": [
    {
      "fileMatch": [
        "/config.json",
        "/config.*.json",
        "/deploy/*.json"
      ],
      "url": "./schemas/myapp.schema.json"
    }
  ]
}

YAML kan ocksa bindas via VS Code-installningar:

{
  "yaml.schemas": {
    "./schemas/myapp.schema.json": [
      "config.yaml",
      "config.*.yaml",
      "deploy/*.yaml"
    ]
  }
}

Den slutliga layouten ar:

schemas/myapp.schema.json:
  Endast rotfilens falt

schemas/server.schema.json:
  Schema for sektionen server

config.toml:
  #:schema ./schemas/myapp.schema.json

config.yaml:
  # yaml-language-server: $schema=./schemas/myapp.schema.json

server.yaml:
  # yaml-language-server: $schema=./schemas/server.schema.json

config.json:
  "$schema": "./schemas/myapp.schema.json"

Referenser:

CLI-integrering

ConfigCommand tillhandahaller ateranvandbara clap-underkommandon:

config-template
config-schema
config-validate
completions
install-completions
uninstall-completions

Dessa inbyggda underkommandon ar separata fran programspecifika override-flaggor for konfiguration. Slå samman override-flaggor som Figment-providers i runtime-laddningsvagen.

Override-flaggor for konfiguration forblir en del av det konsumerande programmets CLI. Deras namn behover inte matcha punktade konfigurationssokvagar. Till exempel kan programmet parsa --server-port och mappa det till den nastlade konfigurationsnyckeln server.port. Endast flaggor som programmet mappar till CliOverrides paverkar konfigurationsvarden.

Platta ut det i ett programs kommandoenum:

Behall programmets egen Parser-typ.
Behall programmets egen Subcommand-enum.
Lagg till #[command(flatten)] Config(ConfigCommand) i den enumen.
Clap expanderar de utplattade ConfigCommand-varianterna till samma kommandoniva som programmets egna varianter.
Matcha varianten Config(command) och skicka den till handle_config_command.

use std::path::PathBuf;

use clap::{Parser, Subcommand};
use confique::Config;
use schemars::JsonSchema;
use rust_config_tree::{ConfigCommand, ConfigSchema, handle_config_command, load_config};

#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(default = [])]
    include: Vec<PathBuf>,
}

impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }
}

#[derive(Debug, Parser)]
#[command(name = "demo")]
struct Cli {
    #[arg(long, default_value = "config.yaml")]
    config: PathBuf,

    #[command(subcommand)]
    command: Command,
}

#[derive(Debug, Subcommand)]
enum Command {
    Run,

    #[command(flatten)]
    Config(ConfigCommand),
}

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let cli = Cli::parse();

    match cli.command {
        Command::Run => {
            let config = load_config::<AppConfig>(&cli.config)?;
            println!("{config:#?}");
        }
        Command::Config(command) => {
            handle_config_command::<Cli, AppConfig>(command, &cli.config)?;
        }
    }

    Ok(())
}

Konfigurationsmallar

demo config-template

Kommandot skriver mallar under config/<root_config_name>/. Om --output far en sokvag anvands bara filnamnet. Om inget utdatafilnamn anges skriver kommandot config/<root_config_name>/<root_config_name>.example.yaml. Lagg till --schema schemas/myapp.schema.json for att binda genererade TOML-, YAML-, JSON- och JSON5-mallar till genererade JSON Schemas. Delade YAML-mallar binder matchande sektionsschema. JSON- och JSON5-mallar far ett $schema-falt som VS Code kanner igen. Kommandot skriver ocksa rot- och sektionsscheman till den valda schemasokvagen.

demo config-template --output app_config.example.toml --schema schemas/myapp.schema.json

Generera rot- och sektions-JSON Schemas:

demo config-schema

Utan --output skriver config-schema rotschemat till config/<root_config_name>/<root_config_name>.schema.json.

Validera hela runtime-konfigurationstradet:

demo config-validate

Genererade editorscheman undviker avsiktligt required-field-diagnostik for delade filer. config-validate laddar includes, tillampar standardvarden och kor slutlig confique-validering, inklusive validatorer deklarerade med #[config(validate = Self::validate)]. Genererade *.schema.json-filer ar for IDE-komplettering och grundlaggande editor-kontroller, inte for faltvardelegalitet. Det skriver Configuration is ok nar valideringen lyckas.

Skalkompletteringar

Skriv kompletteringar till stdout:

demo completions zsh

Installera kompletteringar:

demo install-completions zsh

Avinstallera kompletteringar:

demo uninstall-completions zsh

Installeraren stoder Bash, Elvish, Fish, PowerShell och Zsh. Den skriver kompletteringsfilen under anvandarens hemkatalog och uppdaterar skalets startfil for skal som kraver det.

Innan en befintlig skalstartfil som ~/.zshrc, ~/.bashrc, en Elvish rc-fil eller en PowerShell-profil andras skriver kommandot en backup bredvid originalfilen:

<rc-file>.backup.by.<program-name>.<timestamp>

Exempel

Repositoryt innehaller korbara exempel for laddning av konfigurationstrad, CLI-overrides, inbyggda konfigurationskommandon, mallgenerering och det lagre niva trad-API:t.

Las repositoryts exempelindex:

examples/README.md

Kor exempel fran repository-roten:

cargo run --example basic_loading
cargo run --example cli_overrides -- --server-port 9000
cargo run --example config_commands -- config-template
cargo run --example config_commands -- config-schema
cargo run --example config_commands -- config-validate
cargo run --example generate_templates
cargo run --example tree_api

Trad-API

Anvand det lagre niva trad-API:t nar programmet inte anvander confique, eller nar det behover direkt atkomst till traverseringsresultat.

#![allow(unused)]
fn main() {
use std::{
    fs,
    io,
    path::{Path, PathBuf},
};

use rust_config_tree::{ConfigSource, load_config_tree};

fn load_source(path: &Path) -> io::Result<ConfigSource<String>> {
    let content = fs::read_to_string(path)?;
    let includes = content
        .lines()
        .filter_map(|line| line.strip_prefix("include: "))
        .map(PathBuf::from)
        .collect();

    Ok(ConfigSource::new(content, includes))
}

let tree = load_config_tree("config.yaml", load_source)?;

for node in tree.nodes() {
    println!("{}", node.path().display());
}
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Traverseringsregler

Tradladdaren:

normaliserar kallsokvagar lexikalt;
avvisar tomma include-sokvagar;
loser relativa includes fran filen som deklarerade dem;
bevarar absoluta include-sokvagar;
detekterar rekursiva include-cykler;
hoppar over filer som redan laddats via en annan include-gren.

ConfigTreeOptions kan vanda syskonens include-traversering:

#![allow(unused)]
fn main() {
use rust_config_tree::{ConfigTreeOptions, IncludeOrder};

let options = ConfigTreeOptions::default().include_order(IncludeOrder::Reverse);
let _ = options;
}

Sokvagshjalpare

Sokvagshjalparna ar bara lexikala. De loser inte symboliska lankar och kraver inte att sokvagar finns:

absolutize_lexical(path)
normalize_lexical(path)
resolve_include_path(parent_path, include_path)

GitHub Pages

Detta repository publicerar manualen med mdBook och GitHub Pages.

Manualerna ar fristaende mdBook-projekt. Varje sprak har sin egen SUMMARY.md, sa vanster sidofalt innehaller bara sidor for aktuellt sprak:

manual/
  en/
    book.toml
    SUMMARY.md
    introduction.md
    quick-start.md
    ...
  zh/
    book.toml
    SUMMARY.md
    introduction.md
    quick-start.md
    ...
  ja/
    book.toml
    SUMMARY.md
    introduction.md
    quick-start.md
    ...

Bygg lokalt med:

scripts/publish-pages.sh

Den genererade webbplatsen skrivs till:

target/mdbook

Publiceringsarbetsflode

Arbetsflodet i .github/workflows/pages.yml kors vid pushar till main och vid manuell dispatch. Det:

Checkar ut repositoryt.
Installerar mdBook.
Kor scripts/publish-pages.sh.
Laddar upp target/mdbook som Pages-artefakt.
Distribuerar artefakten till GitHub Pages.

Den publicerade URL:en ar:

https://developerworks.github.io/rust-config-tree/

Crate-release

For hela flodet med commit, push, Pages-distribution och crate-publicering:

scripts/release.sh --execute --message "Release 0.1.3"

Anvand crate-releasehjalparen fran repository-roten:

scripts/publish-crate.sh

Standardlaget kor kontroller och cargo publish --dry-run. For att publicera till crates.io efter att kontrollerna passerat. Om aktuell version redan finns pa crates.io hojer skriptet patch-versionen automatiskt:

scripts/publish-crate.sh --execute

Skriptanvandning sammanfattas i scripts/README.md.

Keyboard shortcuts

rust-config-tree handbok