# Key Value Parser
A Rust library for parsing simple key-value text files into `HashMap<Box<str>, Box<str>>`.
## Format
The parser reads text files where each non-empty line contains a key-value pair separated by whitespace:
- Keys and values are separated by the **first** whitespace character on each line
- Keys cannot contain whitespace
- Values can contain any characters including whitespace (leading/trailing whitespace is trimmed)
- Empty lines and lines without whitespace are ignored
- Keys must be unique (duplicate keys result in an error)
## Usage
Add to your `Cargo.toml`:
```toml
[dependencies]
kv-parser = "0.2.0"
```
```rust
use std::path::Path;
use kv_parser::{Error, file_to_key_value_map};
fn main() -> Result<(), Error> {
let path = Path::new("savedata.sav");
let save_data = file_to_key_value_map(path)?;
if let Some(level) = save_data.get("current-level") {
println!("Current level: {level}");
}
Ok(())
}
```
## Error Handling
The function returns `Result<HashMap<Box<str>, Box<str>>, Error>` where `Error` can be:
- `Error::OpeningFile` - Failed to open the file
- `Error::ReadingFile` - I/O error while reading lines
- `Error::MultipleKeys(key)` - Duplicate key found in file
## Example
Given a file `savedata.sav`:
```
current-level vulcano
start-point 3
player-upgrades super-jump climbing lava-suit bombs
```
The parsed result:
```rust
use std::{collections::HashMap, path::Path};
use kv_parser::file_to_key_value_map;
let mut expected = HashMap::new();
expected.insert("current-level".into(), "vulcano".into());
expected.insert("start-point".into(), "3".into());
expected.insert(
"player-upgrades".into(),
"super-jump climbing lava-suit bombs".into(),
);
let result = file_to_key_value_map(Path::new("savedata.sav"))?;
assert_eq!(expected, result);
```
## Performance
- Uses `Box<str>` instead of `String` for reduced memory overhead
- Efficient line-by-line reading with `BufReader`
- Early termination on duplicate keys or I/O errors