keyvalues-parser 0.2.2

A parser/renderer for vdf text
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

# _keyvalues-parser_

[![codecov](https://codecov.io/gh/CosmicHorrorDev/vdf-rs/branch/main/graph/badge.svg?token=L2FUD0098X)](https://codecov.io/gh/CosmicHorrorDev/vdf-rs)
[![build status](https://img.shields.io/github/actions/workflow/status/CosmicHorrorDev/vdf-rs/basic.yml?branch=main)](https://github.com/CosmicHorrorDev/vdf-rs/actions)
[![Crates.io](https://img.shields.io/crates/v/keyvalues-parser.svg)](https://crates.io/crates/keyvalues-parser)
[![Documentation](https://img.shields.io/docsrs/keyvalues-parser/latest)](https://docs.rs/keyvalues-parser/latest/keyvalues_parser/)

`keyvalues-parser` uses [`pest`](https://lib.rs/crates/pest) to parse
[VDF text v1](https://developer.valvesoftware.com/wiki/KeyValues)
files to an untyped Rust structure to ease manipulation and navigation. The
parser provides an untyped `Vdf` representation as well as a linear
`TokenStream`

The library is primarily used in conjunction with
[`keyvalues-serde`](https://github.com/CosmicHorrorDev/vdf-rs/tree/main/keyvalues-serde)
which provides a more ergonomic (yet more limiting) means of dealing with VDF
text.

## Installation

Just add the library to your `Cargo.toml`

```console
$ cargo add keyvalues-parser
```

## Quickstart

```rust
const LOGIN_USERS_VDF: &str = r#"
"users"
{
    "12345678901234567"
    {
        "AccountName"        "ACCOUNT_NAME"
        "PersonaName"        "PERSONA_NAME"
        "RememberPassword"    "1"
        "MostRecent"        "1"
        "Timestamp"        "1234567890"
    }
}
"#;

use keyvalues_parser::Vdf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let vdf = Vdf::parse(LOGIN_USERS_VDF)?;
    assert_eq!(
        "12345678901234567",
        vdf.value.unwrap_obj().keys().next().unwrap(),
    );

    Ok(())
}
```

## Limitations

<!-- TODO: This could use a lot of cleanup -->

VDF text is drastically underspecified. This leads to the following liberties
being taken

- Not respecting the ordering of key-value pairs, where the pairs are stored in a `BTreeMap` that sorts the values based on the key
- Because of limitations in representing sequences, an empty `Vec` of values will be rendered as a missing keyvalue pair

## `serde` support

`Deserialize` is implemented for a handful of traits with the caveat that
sequences can be problematic when going through the self-describing `serde`
API's. This is most commonly encountered when trying to `serde(flatten)` to
something like an `Obj` where it will fail deserializing any field that's _not_
a sequence (so most of them...).

## Benchmarks

A set of basic benchmarks can be found in the 
[benches directory](https://github.com/CosmicHorrorDev/vdf-rs/tree/main/keyvalues-parser/benches)

These just test timing and throughput for both parsing and rendering of a
fairly typical VDF file

## License

Licensed under either of

<!-- TODO: symlink these licenses and include in each crate -->

 - Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
 - MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.