Ratconfig

https://github.com/yazelix/ratconfig
Admin
Ratconfig is a reusable Rust crate for building project-agnostic Ratatui configuration editors over...
Tokens:5,463
Snippets:53
Trust Score:6
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Reporting Scoped Diagnostics in Rust

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Examples of reporting a nonblocking field-scoped diagnostic for preserved entries and a blocking source-scoped diagnostic for unsafe documents.

```rust
use ratconfig::{
    ConfigUiDiagnostic, ConfigUiDiagnosticScope, ConfigUiFieldId, ConfigUiModel,
};

fn report_preserved_entry(model: &mut ConfigUiModel) {
    model.diagnostics.push(ConfigUiDiagnostic {
        path: "plugins.opaque-native-entry".to_string(),
        status: "preserved".to_string(),
        headline: "Unmodeled native entry is preserved".to_string(),
        blocking: false,
        scope: ConfigUiDiagnosticScope::Field(ConfigUiFieldId::new(
            "native-config",
            "plugins.opaque-native-entry",
        )),
        detail_lines: vec!["The host leaves this entry unchanged when saving.".to_string()],
    });
}

fn report_unsafe_source(model: &mut ConfigUiModel) {
    model.diagnostics.push(ConfigUiDiagnostic {
        path: "native-config".to_string(),
        status: "invalid".to_string(),
        headline: "The native document cannot be updated safely".to_string(),
        blocking: true,
        scope: ConfigUiDiagnosticScope::Source {
            source_id: "native-config".to_string(),
        },
        detail_lines: Vec::new(),
    });
}
```

--------------------------------

### Define a Minimal ConfigUiModel and Patch TOML

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Demonstrates the construction of a ConfigUiModel with a single source and field, alongside a utility function for patching TOML configuration files.

```rust
use std::path::PathBuf;
use ratconfig::{
    ConfigUiApplyStatus, ConfigUiCapability, ConfigUiChoice, ConfigUiField,
    ConfigUiFieldSnapshot, ConfigUiModel, ConfigUiOverride, ConfigUiResolvedValue,
    ConfigUiSource, DEFAULT_CONFIG_SOURCE_ID,
    toml_adapter::{TomlPatchError, set_toml_value_text},
};
use serde_json::json;

fn model() -> ConfigUiModel {
    ConfigUiModel {
        sources: vec![ConfigUiSource {
            id: DEFAULT_CONFIG_SOURCE_ID.to_string(),
            label: "Settings".to_string(),
            path: PathBuf::from("settings.toml"),
            exists: true,
            owner_label: Some("user".to_string()),
            read_only: false,
        }],
        tabs: vec!["general".to_string()],
        operational_tab: None,
        tab_list_tables: std::collections::BTreeMap::new(),
        fields: vec![ConfigUiField {
            source_id: DEFAULT_CONFIG_SOURCE_ID.to_string(),
            path: "core.debug".to_string(),
            display_label: String::new(),
            section_label: String::new(),
            list_cells: Vec::new(),
            tab: "general".to_string(),
            type_label: Some("bool".to_string()),
            snapshot: ConfigUiFieldSnapshot {
                intent: ConfigUiOverride::Explicit(json!(false)),
                effective: Some(ConfigUiResolvedValue::new(json!(false))),
                baseline: Some(ConfigUiResolvedValue::new(json!(false))),
                external_manager: None,
            },
            description: "Enable debug logging".to_string(),
            validation: "bool".to_string(),
            rebuild_required: false,
            apply_status: ConfigUiApplyStatus {
                summary: "after restart".to_string(),
                label: "restart".to_string(),
                detail: "Reload the application to apply this value".to_string(),
                pending: false,
            },
            capability: ConfigUiCapability::Toggle {
                off: ConfigUiChoice::new(json!(false)),
                on: ConfigUiChoice::new(json!(true)),
            },
            can_unset: true,
        }],
        recommended_fields: None,
        file_actions: Vec::new(),
        sidecars: Vec::new(),
        native_config_statuses: Vec::new(),
        diagnostics: Vec::new(),
        theme_switcher: None,
    }
}

fn patch_toml() -> Result<String, TomlPatchError> {
    let outcome = set_toml_value_text(
        "[core]\ndebug = false\n",
        "core.debug",
        &serde_json::json!(true),
    )?;
    Ok(outcome.text)
}
```

--------------------------------

### Implement Crossterm Runner Callback

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Use run_config_ui to handle configuration intents such as setting fields, unsetting fields, and external text editing. The host is responsible for implementing the validation, file writing, and model reloading logic.

```rust
use ratconfig::{
    ConfigUiApp, ConfigUiIntent, ConfigUiModel, CrosstermRunnerError, run_config_ui,
};
use serde_json::Value;

fn run_editor(mut app: ConfigUiApp) -> Result<(), CrosstermRunnerError<std::io::Error>> {
    run_config_ui(&mut app, |app, intent| {
        match intent {
            ConfigUiIntent::SetField { field, value } => {
                host_validate_and_write(&field.source_id, &field.path, &value)?;
                let reloaded = host_reload_model()?;
                app.replace_model_after_success(reloaded, &field)
                    .map_err(std::io::Error::other)?;
            }
            ConfigUiIntent::UnsetField { field } => {
                host_unset(&field.source_id, &field.path)?;
                let reloaded = host_reload_model()?;
                app.replace_model_after_success(reloaded, &field)
                    .map_err(std::io::Error::other)?;
            }
            ConfigUiIntent::EditTextExternally { field, input } => {
                let edited = host_edit_text_buffer(&input)?;
                if let Err(message) = app.apply_external_text_edit(&field, edited) {
                    app.notice_error(message);
                }
            }
            ConfigUiIntent::OpenFile { path, create_if_missing, .. } => {
                host_open_file(&path, create_if_missing)?;
            }
            ConfigUiIntent::None | ConfigUiIntent::Exit => {}
        }
        Ok(())
    })
}

fn host_validate_and_write(
    _source_id: &str,
    _path: &str,
    _value: &Value,
) -> std::io::Result<()> {
    Ok(())
}

fn host_unset(
    _source_id: &str,
    _path: &str,
) -> std::io::Result<()> {
    Ok(())
}

fn host_reload_model() -> std::io::Result<ConfigUiModel> {
    unimplemented!("reload the host-owned config and build a fresh model")
}

fn host_edit_text_buffer(input: &str) -> std::io::Result<String> {
    Ok(input.to_string())
}

fn host_open_file(
    _path: &std::path::Path,
    _create_if_missing: bool,
) -> std::io::Result<()> {
    Ok(())
}
```

--------------------------------

### Recommend fields for the Overview UI

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Sets specific fields to appear in the Overview view by assigning a vector of ConfigUiFieldId to the model's recommended_fields property.

```rust
use ratconfig::{
    ConfigUiFieldId, ConfigUiModel, DEFAULT_CONFIG_SOURCE_ID,
};

fn recommend_fields(model: &mut ConfigUiModel) {
    model.recommended_fields = Some(vec![
        ConfigUiFieldId::new(DEFAULT_CONFIG_SOURCE_ID, "core.debug"),
        ConfigUiFieldId::new("editor", "theme"),
    ]);
}
```

--------------------------------

### Define and Reconcile Config Contracts

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Defines a ConfigContract with automatic and manual migration steps, and provides functions to adopt or reconcile existing configurations against that contract.

```rust
use ratconfig::{
    ConfigContract, ContractChange, ManualMigrationStep,
    contract::{
        join_toml_contract_text_from_version, reconcile_joined_toml_contract_text,
    },
    migration::MigrationOp,
};

fn contract() -> ConfigContract {
    ConfigContract {
        id: "example-app".to_string(),
        baseline_version: 1,
        current_version: 3,
        changes: vec![
            ContractChange::automatic(
                "rename-debug",
                1,
                2,
                vec![MigrationOp::Rename {
                    from: "debug".to_string(),
                    to: "core.debug".to_string(),
                }],
            ),
            ContractChange::manual(
                "split-theme",
                2,
                3,
                vec![ManualMigrationStep {
                    id: "choose-theme-palette".to_string(),
                    path: "theme.palette".to_string(),
                    reason: "The old theme value can map to more than one palette".to_string(),
                    remediation: "Choose a palette and set theme.palette explicitly".to_string(),
                }],
            ),
        ],
    }
}

fn adopt_old_config(raw: &str) -> Result<String, ratconfig::ContractError> {
    let outcome = join_toml_contract_text_from_version(
        raw,
        &contract(),
        "ratconfig.contract",
        1,
    )?;
    Ok(outcome.text)
}

fn reconcile_existing_config(raw: &str) -> Result<String, ratconfig::ContractError> {
    let outcome = reconcile_joined_toml_contract_text(
        raw,
        &contract(),
        "ratconfig.contract",
    )?;
    Ok(outcome.text)
}
```

--------------------------------

### Apply Default TOML Values

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Applies default values to a TOML configuration string using the provided adapter.

```rust
use ratconfig::toml_adapter::{TomlMigrationError, apply_toml_defaults_text};

fn complete_toml_defaults(raw: &str) -> Result<String, TomlMigrationError> {
    let outcome = apply_toml_defaults_text(
        raw,
        &[("open.log_level", serde_json::json!("info"))],
    )?;
    Ok(outcome.text)
}
```

--------------------------------

### Build TOML Document Fields and Patch Values

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Use build_toml_document_fields to inspect TOML files without a full schema and set_toml_value_text to modify TOML content.

```rust
use ratconfig::{
    ConfigUiApplyStatus, ConfigUiModel, ConfigUiTomlDocumentError, ConfigUiTomlDocumentSpec,
    build_toml_document_fields,
    toml_adapter::{TomlPatchError, set_toml_value_text},
};
use serde_json::Value;

fn add_native_toml_rows(
    model: &mut ConfigUiModel,
    raw: &str,
    baseline_raw: &str,
) -> Result<(), ConfigUiTomlDocumentError> {
    let document = build_toml_document_fields(ConfigUiTomlDocumentSpec {
        source_id: "helix-config",
        tab: "helix",
        section_label: "Editor settings",
        current_toml: raw,
        baseline_toml: Some(baseline_raw),
        validation: "host validates before writing",
        rebuild_required: false,
        apply_status: ConfigUiApplyStatus {
            summary: "after save".to_string(),
            label: "after save".to_string(),
            detail: "Reload the application to apply this file".to_string(),
            pending: true,
        },
    })?;
    model.tab_list_tables.insert("helix".to_string(), document.list_table);
    model.fields.extend(document.fields);
    Ok(())
}

fn patch_native_toml(raw: &str, path: &str, value: &Value) -> Result<String, TomlPatchError> {
    let outcome = set_toml_value_text(raw, path, value)?;
    Ok(outcome.text)
}
```

--------------------------------

### Configure Ratconfig Dependency

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Add the ratconfig dependency with the crossterm-runner feature enabled to your Cargo.toml.

```toml
ratconfig = { git = "https://github.com/Yazelix/ratconfig", branch = "main", features = ["crossterm-runner"] }
```

--------------------------------

### Define MultiChoice Field and Patch TOML

Source: https://github.com/yazelix/ratconfig/blob/main/README.md

Demonstrates defining a MultiChoice field with ordered selection and implementing a TOML patch function for configuration updates.

```rust
use ratconfig::{
    ConfigUiApplyStatus, ConfigUiCapability, ConfigUiChoice, ConfigUiField,
    ConfigUiFieldSpec,
    toml_adapter::{TomlPatchError, set_toml_value_text},
};
use serde_json::Value;

fn sections_field() -> ConfigUiField {
    ConfigUiFieldSpec {
        display_label: "Layout sections".to_string(),
        section_label: "Visible content".to_string(),
        ..ConfigUiFieldSpec::new(
            "settings",
            "layout.sections",
            "layout",
            "Choose visible layout sections",
            ConfigUiCapability::MultiChoice {
                choices: ["left", "center", "right"]
                    .into_iter()
                    .map(|value| ConfigUiChoice::new(serde_json::json!(value)))
                    .collect(),
                ordered: true,
            },
            "known layout section ids only",
            ConfigUiApplyStatus {
                summary: "after save".to_string(),
                label: "after save".to_string(),
                detail: "Reload the application to apply this value".to_string(),
                pending: true,
            },
        )
    }
    .build(
        "string list",
        Some(&serde_json::json!(["left", "center"])),
        Some(&serde_json::json!(["center"])),
    )
}

fn patch_sections_toml(raw: &str, value: &Value) -> Result<String, TomlPatchError> {
    let outcome = set_toml_value_text(raw, "layout.sections", value)?;
    Ok(outcome.text)
}
```
Tokens:
Raw