prefer 0.3.2

A lightweight library for managing application configurations with support for multiple file formats
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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# prefer

[![CI](https://github.com/LimpidTech/prefer.rs/workflows/CI/badge.svg)](https://github.com/LimpidTech/prefer.rs/actions)
[![codecov](https://codecov.io/gh/LimpidTech/prefer.rs/branch/main/graph/badge.svg)](https://codecov.io/gh/LimpidTech/prefer.rs)
[![Crates.io](https://img.shields.io/crates/v/prefer.svg)](https://crates.io/crates/prefer)
[![Documentation](https://docs.rs/prefer/badge.svg)](https://docs.rs/prefer)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A library for managing application configurations with support for multiple file formats.

## Overview

`prefer` helps you manage application configurations while providing users the flexibility of using whatever configuration format fits their needs. It automatically discovers configuration files in standard system locations and supports JSON, JSON5, YAML, TOML, INI, and XML formats.

## Features

- **Format-agnostic**: Supports JSON, JSON5, YAML, TOML, INI, and XML
- **Automatic discovery**: Searches standard system paths for configuration files
- **Async by design**: Non-blocking operations for file I/O
- **File watching**: Monitor configuration files for changes
- **Dot-notation access**: Access nested values with simple key strings
- **Cross-platform**: Works on Linux, macOS, and Windows

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
prefer = "0.1"
```

## Usage

### Basic Example

```rust
use prefer::load;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = load("settings").await?;

    let username: String = config.get("auth.username").await?;
    let port: u16 = config.get("server.port").await?;

    println!("Username: {}", username);
    println!("Port: {}", port);

    Ok(())
}
```

### Watching for Changes

```rust
use prefer::watch;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut receiver = watch("settings").await?;

    while let Some(config) = receiver.recv().await {
        let port: u16 = config.get("server.port").await?;
        println!("Configuration updated! Port: {}", port);
    }

    Ok(())
}
```

## Supported Formats

The library automatically detects and parses the following formats:

- JSON (`.json`)
- JSON5 (`.json5`, `.jsonc`) - with comments and trailing commas
- YAML (`.yaml`, `.yml`)
- TOML (`.toml`)
- INI (`.ini`)
- XML (`.xml`)

## Configuration Discovery

`prefer` searches for configuration files in the following locations (in order):

### Unix/Linux/macOS
- Current directory
- `$XDG_CONFIG_HOME` (or `~/.config`)
- `$XDG_CONFIG_DIRS`
- `$HOME`
- `/usr/local/etc`
- `/usr/etc`
- `/etc`

### Windows
- Current directory
- `%USERPROFILE%`
- `%APPDATA%`
- `%ProgramData%`
- `%SystemRoot%`

## Features

By default, all format parsers are enabled. You can disable specific formats:

```toml
[dependencies]
prefer = { version = "0.1", default-features = false, features = ["json5"] }
```

Available features:
- `json5` - JSON5 format support
- `xml` - XML format support
- `ini` - INI format support

Note: JSON, YAML, and TOML are always available.

## Examples

See the [examples](examples/) directory for more usage examples:

- `basic.rs` - Basic configuration loading
- `watch.rs` - File watching for live updates

Run examples with:

```bash
cargo run --example basic
cargo run --example watch
```

## Related Projects

- [prefer.js](https://github.com/LimpidTech/prefer.js) - JavaScript/TypeScript version
- [prefer.py](https://github.com/LimpidTech/prefer.py) - Python version
- [prefer.go](https://github.com/LimpidTech/prefer.go) - Go version

## License

MIT