json5 1.0.0

A Rust JSON5 serializer and deserializer which speaks Serde.
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

# JSON5

[![crates.io](https://img.shields.io/crates/v/json5.svg)](https://crates.io/crates/json5)
[![docs.rs](https://docs.rs/json5/badge.svg)](https://docs.rs/json5)

[JSON5][] is a superset of [JSON][] with an expanded syntax including some productions from
[ECMAScript 5.1][]. It aims to be easier to write and maintain by hand (e.g. for config files). It
is not intended to be used for machine-to-machine communication, for which you'd be better served by
[serde-rs/json][].

In particular, JSON5 allows comments, trailing commas, object keys without quotes, single quoted
strings, hexadecimal numbers, multi-line strings...

```json5
{
  // comments
  unquoted: "and you can quote me on that",
  singleQuotes: 'I can use "double quotes" here',
  lineBreaks: "Look, Mom! \
No \\n's!",
  hexadecimal: 0xdecaf,
  leadingDecimalPoint: 0.8675309,
  andTrailing: 8675309,
  positiveSign: +1,
  trailingComma: "in objects",
  andIn: ["arrays"],
  backwardsCompatible: "with JSON",
}
```

This crate provides functions for deserializing JSON5 text into a Rust datatype and for
serializing a Rust datatype as JSON5 text, both via the [Serde framework][].

## Deserialization

Implementing `serde::Deserialize` on your type will allow you to parse JSON5 text into a value of
that type with `from_str`.

```rust
use serde_derive::Deserialize;

#[derive(Debug, PartialEq, Deserialize)]
struct Config<'a> {
    foo: u32,
    bar: &'a str,
}

let config: Config = json5::from_str("
  {
    // Note unquoted keys, comments, and trailing commas.
    foo: 42,
    bar: 'baz',
  }
")?;

assert_eq!(config, Config{ foo: 42, bar: "baz" });
```

There are many ways to customize the deserialization (e.g. deserializing `camelCase` field names
into a struct with `snake_case` fields). See the Serde docs, especially the [Attributes][],
[Custom serialization][], and [Examples][] sections.

## Serialization

Similarly, implementing `serde::Serialize` on a Rust type allows you to produce a JSON5
serialization of values of that type with `to_string` or `to_writer`. The serializer will omit
quotes around object keys where possible and will indent nested objects and arrays, but is otherwise
fairly basic.

```rust
use serde_derive::Serialize;

#[derive(Serialize)]
struct Config<'a> {
    foo: u32,
    bar: &'a str,
}

let config = Config {
    foo: 42,
    bar: "baz",
};

assert_eq!(&json5::to_string(&config)?, "{
  foo: 42,
  bar: \"baz\",
}");
```

There are many ways to customize the serialization (e.g. serializing `snake_case` struct fields
as `camelCase`). See the Serde docs, especially the [Attributes][], [Custom serialization][] and
[Examples][] sections.

## Byte arrays

All the types of the [Serde data model][] are supported. Byte arrays are encoded as hex strings.
e.g.

```rust
use serde_bytes::{Bytes, ByteBuf};

let s = json5::to_string(&Bytes::new(b"JSON5"))?;
assert_eq!(&s, "\"4a534f4e35\"");
assert_eq!(json5::from_str::<ByteBuf>(&s)?, ByteBuf::from("JSON5"));
```

[Attributes]: https://serde.rs/attributes.html
[Custom serialization]: https://serde.rs/custom-serialization.html
[ECMAScript 5.1]: https://www.ecma-international.org/ecma-262/5.1/
[Examples]: https://serde.rs/examples.html
[JSON]: https://www.json.org/json-en.html
[JSON5]: https://json5.org/
[Serde data model]: https://serde.rs/data-model.html#types
[Serde framework]: https://serde.rs/
[serde-rs/json]: https://github.com/serde-rs/json