serpent-serializer 0.2.0

Serialize Lua values to round-trippable Lua source with cycle and shared-reference handling
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

# serpent-serializer

Serialize Lua values to round-trippable Lua source, and load that source back.

The output is Lua source code that Lua's `load` reads into an equivalent value
graph. It preserves shared references, reconstructs cyclic references, emits
arrays positionally, uses short notation for identifier keys, and writes the
special numbers as `1/0`, `-1/0`, and `0/0`.

## Installation

```toml
[dependencies]
serpent-serializer = "0.1"
```

## Entry points

- `dump` produces full serialization wrapped in a `do ... return _ end` block
  with a self-reference section. Compact and sparse by default.
- `line` produces single-line output. It is an expression, so prepend `return `
  to evaluate it. `load` does this for you.
- `block` produces multi-line indented output. Also an expression.
- `serialize` is the raw entry point that takes options as given.
- `load` parses serialized output back into a `Value`.

## Example

```rust
use serpent_serializer::{block, load, LoadOptions};
use serpent_serializer::value::{Key, Table, Value};

let t = Table::new();
t.push(Value::Str(b"a".to_vec()));
t.push(Value::Str(b"b".to_vec()));
t.set(Key::Str(b"x".to_vec()), Value::Number(1.0));

let src = block(&Value::Table(t)).unwrap();
let back = load(&src, &LoadOptions::default()).unwrap();
assert!(matches!(back, Value::Table(_)));
```

## Options

Build options over `Options::dump`, `Options::line`, or `Options::block`, then
override the fields you need. Supported options include `name`, `indent`,
`compact`, `sparse`, `fatal`, `maxnum`, `maxlevel`, `maxlength`, `nocode`,
`nohuge`, `comment`, `sortkeys`, a custom sort, `metatostring`, `numformat`, the
value and key ignore filters, and a custom table formatter.

## Safety

`load` runs in a sandbox by default. Any function call in the input is rejected
with "cannot call functions", and any global read or assignment resolves against
the sandbox, so it cannot reach real state. Set `safe` to `Some(false)` to
disable the call check.

Functions do not round-trip. The default output reloads a function through a
call, which the sandbox rejects, and `load` cannot run function bodies in any
case. Set `nocode` to emit an empty stub instead, which loads back as `nil`.

## License

Licensed under the [MIT license](LICENSE).