smallish 0.1.0

Lightweight, no-std syntax for configuration and scripting.
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

# smallish

[![GitHub Action: Test](https://github.com/agrif/smallish/actions/workflows/test.yaml/badge.svg)](https://github.com/agrif/smallish/actions/workflows/test.yaml)
[![crates.io](https://img.shields.io/crates/v/smallish.svg)](https://crates.io/crates/smallish)
[![docs.rs](https://docs.rs/smallish/badge.svg)](https://docs.rs/smallish)

Lightweight, no-std, no-alloc syntax for configuration and scripting.

## Deserializing

*smallish* is designed to be used with [serde][] to parse lists of
short instructions. For example, you can put your instructions inside
an enumeration, and then parse them with [from_str][].

 [serde]: https://serde.rs/
 [from_str]: https://agrif.github.io/smallish/smallish/fn.from_str.html

```rust
use smallish::{Flavor, from_str};

#[derive(Debug, PartialEq, Eq, serde::Deserialize)]
enum Instr<'a> {
    Print { msg: &'a str },
    SetMinMax(u16, u16),
}

let source = r#"
Print msg="hello" # comments work
SetMinMax 20 60
"#;

let instrs: Vec<Instr> = from_str(Flavor::List, source).unwrap();
assert_eq!(instrs, &[Instr::Print{ msg: "hello" }, Instr::SetMinMax(20, 60)]);
```

It is also possible to use [from_slice][] if your source is a
slice of bytes. Both of these methods have a fixed recursion depth. If
your data type is very deeply nested, you should use [Deserializer][]
directly.

 [from_slice]: https://agrif.github.io/smallish/smallish/fn.from_slice.html
 [Deserializer]: https://agrif.github.io/smallish/smallish/de/struct.Deserializer.html

## Syntax

The details of *smallish* syntax are outlined in the [syntax][] module
documentation. This also includes many examples.

*smallish* comes in a few slightly different [Flavors][Flavor].

 [syntax]: https://agrif.github.io/smallish/smallish/syntax/index.html
 [Flavor]: https://agrif.github.io/smallish/smallish/enum.Flavor.html

## Special Types

There are a few special types that modify how a value is deserialized
by *smallish*, for example by annotating it with source location, or
opting out of string escapes for guaranteed zero-copy behavior. These
types are documented in the [types][] module.

 [types]: https://agrif.github.io/smallish/smallish/types/index.html

## Feature Flags

These features are enabled by default:

 * **`custom-error-messages`** attaches a small space for custom error
   messages to the deserialization error type. This costs a small
   amount of space, but increases the usefulness of a few error
   messages generated by [serde][].

These features are optional:

 * **[`defmt`][defmt]** derives `defmt::Format` for all types, and
   uses `defmt::panic!` and friends instead of their standard
   counterparts.

 [defmt]: https://defmt.ferrous-systems.com/

## License

Licensed under the [MIT license][LICENSE]. Unless stated otherwise,
any contributions to this work will also be licensed this way, with no
additional terms or conditions.

 [LICENSE]: ./LICENSE