confy 2.0.0

Boilerplate-free configuration management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# confy

[![crates.io](https://img.shields.io/crates/v/confy)](https://crates.io/crates/confy)
[![docs.rs](https://img.shields.io/docsrs/confy)](https://docs.rs/confy/)
[![Discord](https://img.shields.io/badge/chat-Discord-informational)](https://discord.gg/dwq4Zme)

Zero-boilerplate configuration management.

Focus on storing the right data, instead of worrying about how or where to store it.

```rust
use serde_derive::{Serialize, Deserialize};

#[derive(Default, Debug, Serialize, Deserialize)]
struct MyConfig {
    version: u8,
    api_key: String,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cfg: MyConfig = confy::load("my-app-name", None)?;
    dbg!(cfg);
    Ok(())
}
```

## Confy's feature flags

`confy` can be used with either `TOML`, `YAML`, or `RON` files.
`TOML` is the default language used with `confy` but any of the other languages can be used by enabling them with feature flags as shown below.

Note: you can only use __one__ of these features at a time, so in order to use either of the optional features you have to disable default features.

### Using YAML

To use `YAML` files with `confy` you have to make sure you have enabled the `yaml_conf` feature and disabled both `toml_conf` and `ron_conf`.

Enable the feature in `Cargo.toml`:

```toml
[dependencies.confy]
features = ["yaml_conf"]
default-features = false
```

### Using RON

For using `RON` files with `confy` you have to make sure you have enabled the `ron_conf` feature and disabled both `toml_conf` and `yaml_conf`.

Enable the feature in `Cargo.toml`:

```toml
[dependencies.confy]
features = ["ron_conf"]
default-features = false
```

## Changing Error Messages

Information about adding context to error messages can be found at [Providing Context](https://rust-cli.github.io/book/tutorial/errors.html#providing-context)

## Config File Location

`confy` uses the [etcetera](https://docs.rs/etcetera/latest/etcetera/) crate to store your configuration files, the common locations for those depend on the stratgey usd [`App Strategy`](https://docs.rs/etcetera/latest/etcetera/#appstrategy) or [`Native Strategy`](https://docs.rs/etcetera/latest/etcetera/#native-strategy), below are the common OS paths, you can change the strategy using the built-in [`change_config_strategy`](https://docs.rs/confy/2.0.0/confy/fn.change_config_strategy.html) function.

### App Strategy

This is the default strategy in version `2.0.0`+. It uses the `XDG` format on both Linux and MacOS systems.

| Linux | macOS | Windows |
| --- | --- | --- |
| `$XDG_CONFIG_HOME`/`<project_path>` or `$HOME`/.config/`<project_path>` | `$HOME`/.config/`<project_path>` | `{FOLDERID_RoamingAppData}`/`<project_path>`/config |

Where the `<project_path>` will be `$MY_APP_NAME`.

### Native Strategy

You can change to this strategy which is provided for both backwards capability and for GUI applications on macOS which is more traditional and expects this format.

| Linux | macOS | Windows |
| --- | --- | --- |
| `$XDG_CONFIG_HOME`/`<project_path>` or `$HOME`/.config/`<project_path>` | `$HOME`/Library/Application Support/`<project_path>` | `{FOLDERID_RoamingAppData}`/`<project_path>`/config |

Where the `<project_path>` will be `rs.$MY_APP_NAME` on macOS and just `$MY_APP_NAME` elsewhere.

## Breaking changes

### Version 2.0.0

In version `2.0.0` we moved from the [`ProjectDirs`](https://github.com/dirs-dev/directories-rs?tab=readme-ov-file#projectdirs) crate to [`etcetera`](https://docs.rs/etcetera/latest/etcetera/) allowing for both uses of `XDG` or the OS's Native paths.

* From now on the default will be using `XDG` directories on macOS.

### Version 0.6.0

In this version we bumped several dependencies which have had changes with some of the default (de)serialization process:

* `serde_yaml` v0.8 -> v0.9: [v0.9 release notes](https://github.com/dtolnay/serde-yaml/releases/tag/0.9.0). There were several breaking changes to `v0.9.0` and are listed in this release tag. Especially cases where previously numbers were parsed and now return `String`. See the release notes for more details.
* `toml` v0.5 -> v0.8: [v0.8 CHANGELOG](https://github.com/toml-rs/toml/blob/main/crates/toml/CHANGELOG.md#compatibility-1). Breaking change to how tuple variants work in `toml`, from the notes: "Serialization and deserialization of tuple variants has changed from being an array to being a table with the key being the variant name and the value being the array".

### Version 0.5.0

* The base functions `load` and `store` have been added an optional parameter in the event multiples configurations are needed, or ones with different filename.
* The default configuration file is now named "default-config" instead of using the application's name. Put the second argument of `load` and `store` to be the same of the first one to keep the previous configuration file.
* It is now possible to save the configuration as `toml` or as `YAML`. The configuration's file name's extension depends on the format used.

### Version 0.4.0

Starting with version 0.4.0 the configuration file are stored in the expected place for your system. See the [`directories`] crates for more information.
Before version 0.4.0, the configuration file was written in the current directory.

[`directories`]: https://crates.io/crates/directories

## License

This work is triple-licensed under MIT, MIT/X11, or the Apache 2.0 (or any later version).
You may choose any one of these three licenses if you use this work.

`SPDX-License-Identifier: MIT OR X11 OR Apache-2.0+`