Repository navigation
Expand file tree
/
Copy pathmessagepack.script_api
More file actions
114 lines (106 loc) · 4.65 KB
/
Copy pathmessagepack.script_api
File metadata and controls
114 lines (106 loc) · 4.65 KB
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
- name: messagepack
type: table
desc: |-
Encode Lua values and decode custom binary data in the
[MessagePack format](https://msgpack.org/index.html).
Decoding parses directly into Lua tables and strings without an intermediate
native tree. Container nesting is limited to 64 levels.
members:
- name: decode
type: function
desc: |-
Decode exactly one complete MessagePack value. Malformed, truncated,
trailing or unsupported data raises a Lua error.
Nil becomes Lua nil by default. Use `decode_null_as_userdata` to retain
null fields and array entries as `messagepack.null`. Arrays become
tables indexed from 1; maps become tables. Duplicate keys use the last
value. Keys must be representable in Lua; nil and NaN keys are rejected.
The null option also permits a MessagePack nil key as the sentinel.
All integer and floating formats become Lua numbers. Lua's double
precision representation can round integers beyond its exact integer
range. String and binary formats both become binary-safe Lua strings.
Empty arrays and maps both become empty tables. Extension types,
including timestamps, are unsupported.
parameters:
- name: bytes
type: string
desc: MessagePack bytes; embedded NUL bytes are supported.
- name: options
type: table
optional: true
desc: Optional decoding settings.
members:
- name: decode_null_as_userdata
type: boolean
optional: true
desc: Preserve nil values as messagepack.null. Defaults to false.
returns:
- name: value
type: ["nil", boolean, number, string, table, userdata]
desc: The decoded Lua value.
examples:
- desc: |-
```lua
local bytes = assert(sys.load_resource("/data/config.msgpack"))
local config = messagepack.decode(bytes)
```
- desc: |-
```lua
local bytes = messagepack.encode({1, messagepack.null, 3})
local values = messagepack.decode(bytes, {
decode_null_as_userdata = true
})
assert(values[2] == messagepack.null)
```
- name: encode
type: function
desc: |-
Encode one Lua value into a binary MessagePack string.
Dense tables with exactly the integer keys `1..n` become arrays.
Sparse, mixed-key and other tables become maps. Empty tables default
to maps; `encode_empty_table_as_map = false` changes all empty tables
in this call to arrays. Raw entries are used without table metamethods.
Map order is unspecified. Shared tables are serialized independently;
cyclic tables and nesting beyond 64 containers raise errors.
Exactly integral numbers within the signed/unsigned 64-bit ranges use
the smallest integer format. Other numbers use float64. Negative zero,
NaN and infinities are preserved. Lua strings use the MessagePack string
format and retain every byte; decoding and re-encoding a binary-format
value therefore changes its tag to a string tag.
Only `messagepack.null` (also `json.null`) is supported as userdata.
Functions, threads and other userdata raise errors.
parameters:
- name: value
type: ["nil", boolean, number, string, table, userdata]
desc: Value to encode; messagepack.null encodes as MessagePack nil.
- name: options
type: table
optional: true
desc: Optional encoding settings.
members:
- name: encode_empty_table_as_map
type: boolean
optional: true
desc: Encode empty tables as maps. Defaults to true; applies recursively.
returns:
- name: bytes
type: string
desc: A Lua-owned binary MessagePack string.
examples:
- desc: |-
```lua
local bytes = messagepack.encode({name = "player", position = {1, 2, 3}})
local value = messagepack.decode(bytes)
assert(value.position[2] == 2)
```
- desc: |-
```lua
local bytes = messagepack.encode({}, {encode_empty_table_as_map = false})
assert(bytes == string.char(0x90))
```
- name: "null"
type: userdata
desc: |-
Null light-userdata sentinel, identical to `json.null`. It encodes as
MessagePack nil. Decode with `decode_null_as_userdata = true` to retain
nil values in tables instead of dropping those Lua entries.