CLI 統合

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

ConfigCommand は reusable clap subcommands を提供します。

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

これらの built-in subcommands は application-specific config override flags とは 別のものです。config override flags は runtime loading path で Figment provider として merge します。

config override flags は consuming application の CLI に属します。名前は dotted config path に一致している必要はありません。たとえば application は --server-port を parse し、それを nested server.port config key に map できます。CliOverrides に map した flag だけが config value に影響します。

application command enum に flatten します。

1. application 自身の Parser type を保つ。
2. application 自身の Subcommand enum を保つ。
3. その enum に #[command(flatten)] Config(ConfigCommand) を追加する。
4. Clap は flattened ConfigCommand variants を application 自身の command と 同じ level に展開する。
5. Config(command) variant を match し、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(())
}

Config Templates

demo config-template

この command は config/<root_config_name>/ の下に template を書きます。 --output に path を渡した場合は file name だけを使います。output file name がない場合は config/<root_config_name>/<root_config_name>.example.yaml を書きます。 --schema schemas/myapp.schema.json を追加すると、generated TOML / YAML / JSON / JSON5 template を generated JSON Schema に bind します。split YAML template は matching section schema を bind します。JSON / JSON5 template は VS Code が認識する $schema field を受け取ります。この command は root / section schema も selected schema path に書きます。

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

root / section JSON Schema を生成します。

demo config-schema

--output がない場合、config-schema は root schema を config/<root_config_name>/<root_config_name>.schema.json に書きます。

完全な runtime config tree を validate します。

demo config-validate

generated editor schemas は split file で required-field diagnostic を避けるよう に作られます。config-validate は includes を読み込み、defaults を適用し、 final confique validation を実行します。これには #[config(validate = Self::validate)] で宣言した validator も含まれます。 生成された *.schema.json は IDE 補完と基本的な editor check のためのもので、 field value legality は判断しません。成功時は Configuration is ok を出力します。

Shell Completions

completion を stdout に出力します。

demo completions zsh

completion を install します。

demo install-completions zsh

completion を uninstall します。

demo uninstall-completions zsh

installer は Bash、Elvish、Fish、PowerShell、Zsh を support します。completion file を user home directory 以下に書き、必要な shell では startup file も更新 します。

既存の shell startup file、たとえば ~/.zshrc、~/.bashrc、Elvish rc file、 PowerShell profile を変更する前に、command は元ファイルの横に backup を書きます。

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