#configuration-management #config-file #toml-parser #flexible #extensible #settings #json

realme

A flexible and extensible configuration management library for Rust, designed to simplify the process of loading and managing configuration settings from various sources

13 releases

0.2.1 Oct 24, 2024
0.2.0 Oct 24, 2024
0.1.10 Oct 18, 2024
0.1.3 Sep 28, 2024

#694 in Parser implementations

Download history 338/week @ 2024-09-13 122/week @ 2024-09-20 212/week @ 2024-09-27 14/week @ 2024-10-04 793/week @ 2024-10-11 518/week @ 2024-10-18 115/week @ 2024-10-25 11/week @ 2024-11-01

1,439 downloads per month
Used in git-revise

GPL-3.0 license

180KB
4.5K SLoC

Realme

Build License: GPLv3 Latest Version codecov

Realme is a flexible and extensible configuration management library for Rust. It simplifies the process of loading and managing configuration settings from various sources. The name "Realme" is a play on "Realm" and "me," emphasizing its role in managing your application's configuration realm.

Features

  • Support for multiple configuration formats for file(etc. TOML, JSON ...) or string or env or even command line flags, and you can easily add support for more formats
  • Loosely typed — Serialization and deserialization of configuration data, configuration values may be read in any supported type, as long as there exists a reasonable conversion
  • Custom parser support and flexible adaptor system for different data sources, for example, you can check the cmd parser, which allows you to read configuration from command line flags with clap
  • Live watching and re-reading of config files

Installation

Add this to your Cargo.toml:

[dependencies]
realme = {version = "0.1.4", features = ["toml"]}

You can also enable other features, for example, to use hot reloading feature, you need to enable json andwatch feature:

realme = {version = "0.1.4", features = ["toml", "json", "watch"]}

Usage

Here's a simple example of how to use Realme:

    use realme::{Adaptor, Realme, StringSource, TomlParser};
    use serde::{Serialize, Deserialize};

    #[derive(Debug, Serialize, Deserialize)]
    struct Person {
        name: String,
        age: u32,
        birthday: chrono::DateTime<chrono::Utc>,
    }

    const CONFIGURATION1: &str = r#"
        name = "John"
        age = 30
        birthday = 1993-01-01T00:00:00Z
    "#;

fn main() {
    let realme = Realme::builder()
        .load(Adaptor::new(StringSource::<TomlParser>::new(
            CONFIGURATION1,
        )))
        .build()
        .expect("Building configuration object");

    let person: Person = realme.try_deserialize().unwrap();

    println!("{:?}", person);
    println!("{:?}", realme);
    
    assert_eq!(person.name, TryInto::<String>::try_into(realme.get("name").unwrap()).unwrap());
    assert_eq!(person.age, realme.get_as::<u32, _>("age").unwrap());
    assert_eq!(person.birthday, realme.get_as::<chrono::DateTime<chrono::Utc>, _>("birthday").unwrap());
}

For more detailed examples, check the examples directory.

For a real-world example, you can check the Rinkle project.

Compartion

I am impressed by the following libraries:

And compared to them, Realme has the following features:

  • Realme value conversion is all based on serde, so you can convert to any type that implements serde::Serialize and serde::Deserialize trait
  • Realme has a flexible adaptor system, you can easily add your own adaptor by implementing the Parser and Source trait
  • Realme supports file source hot reloading, you can reload the configuration file at runtime

But Realme has the following drawbacks:

  • Newer project, less documentations, less tests
  • It might have some breaking changes

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Copyright 2024 Jasper Zhang

Dependencies

~0.8–10MB
~111K SLoC