You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: serde/cbor/README.md
+13-10Lines changed: 13 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,18 @@
1
1
# nim-serde CBOR
2
2
3
-
This README details the usage of CBOR serialization and deserialization features offered by nim-serde, in compliance with [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949).
3
+
The CBOR module in nim-serde provides serialization and deserialization for Nim values following [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949.html). Unlike the JSON implementation, CBOR offers a stream-based API that enables direct binary serialization without intermediate representations.
4
+
5
+
> Note: While the JSON implementation supports serde modes via pragmas, the current CBOR implementation does not support the `serialize` and `deserialize` pragmas. The library will raise an assertion error if you try to use these pragmas with CBOR serialization.
6
+
4
7
5
8
## Table of Contents
6
9
-[nim-serde CBOR](#nim-serde-cbor)
7
10
-[Table of Contents](#table-of-contents)
8
11
-[Serialization API](#serialization-api)
9
-
-[Basic Serialization with Stream API](#basic-serialization-with-stream-api)
10
-
-[Object Serialization](#object-serialization)
11
-
-[Custom Type Serialization](#custom-type-serialization)
12
-
-[Converting to CBOR with`toCbor`](#converting-to-cbor-with-tocbor)
12
+
-[Stream API: Primitive Type and Sequence Serialization](#stream-api-primitive-type-and-sequence-serialization)
The `toCbor` function can be used to directly convert a Nim value to CBOR binary data:
120
123
@@ -363,7 +366,7 @@ For deserialization, the library parses CBOR data into a `CborNode` representati
363
366
364
367
### Current Limitations
365
368
366
-
While the JSON implementation supports serde modes via pragmas, the current CBOR implementation does not support the `serialize` and `deserialize` pragmas. The library will raise an assertion error if you try to use these pragmas with CBOR serialization.
369
+
This implementation does not support the `serialize` and `deserialize` pragmas. The library will raise an assertion error if you try to use these pragmas with CBOR serialization.
Explore JSON serialization and deserialization using nim-serde, an improved alternative to `std/json`.
3
+
The JSON module in nim-serde provides serialization and deserialization for Nim values, offering an improved alternative to the standard `std/json` library. Unlike the standard library, nim-serde JSON implements a flexible system of serialization/deserialization modes that give developers precise control over how Nim objects are converted to and from JSON.
4
4
5
5
## Table of Contents
6
6
-[nim-serde JSON](#nim-serde-json)
7
7
-[Table of Contents](#table-of-contents)
8
+
-[Serde Modes](#serde-modes)
9
+
-[Modes Overview](#modes-overview)
10
+
-[Default Modes](#default-modes)
11
+
-[Field Options](#field-options)
8
12
-[Serialization API](#serialization-api)
9
13
-[Basic Serialization with `%` operator](#basic-serialization-with--operator)
10
14
-[Object Serialization](#object-serialization)
11
-
-[Serialization with `%*`](#serialization-with-)
15
+
-[Inlining JSON Directly in Code with `%*`](#inlining-json-directly-in-code-with-)
12
16
-[Converting to JSON String with `toJson`](#converting-to-json-string-with-tojson)
13
17
-[Serialization Modes](#serialization-modes)
14
18
-[Field Customization for Serialization](#field-customization-for-serialization)
19
+
-[Custom Type Serialization](#custom-type-serialization)
15
20
-[Deserialization API](#deserialization-api)
16
21
-[Basic Deserialization with `fromJson`](#basic-deserialization-with-fromjson)
17
22
-[Error Handling](#error-handling)
18
23
-[Parsing JSON with `JsonNode.parse`](#parsing-json-with-jsonnodeparse)
19
24
-[Deserialization Modes](#deserialization-modes)
20
25
-[Field Customization for Deserialization](#field-customization-for-deserialization)
21
26
-[Using as a Drop-in Replacement for std/json](#using-as-a-drop-in-replacement-for-stdjson)
22
-
-[Custom Type Serialization](#custom-type-serialization)
This implementation supports three different modes to control de/serialization:
32
+
33
+
```nim
34
+
OptIn
35
+
OptOut
36
+
Strict
37
+
```
38
+
39
+
Modes can be set in the `{.serialize.}` and/or `{.deserialize.}` pragmas on type
40
+
definitions. Each mode has a different meaning depending on if the type is being
41
+
serialized or deserialized. Modes can be set by setting `mode` in the `serialize` or
42
+
`deserialize` pragma annotation, eg:
43
+
44
+
```nim
45
+
type MyType {.serialize(mode=Strict).} = object
46
+
field1: bool
47
+
field2: bool
48
+
```
49
+
50
+
### Modes Overview
51
+
52
+
| Mode | Serialize | Deserialize |
53
+
|:-----|:----------|:------------|
54
+
|`OptOut`| All object fields will be serialized, except fields marked with `{.serialize(ignore=true).}`. | All JSON keys will be deserialized, except fields marked with `{.deserialize(ignore=true).}`. No error if extra JSON fields exist. |
55
+
|`OptIn`| Only fields marked with `{.serialize.}` will be serialized. Fields marked with `{.serialize(ignore=true).}` will not be serialized. | Only fields marked with `{.deserialize.}` will be deserialized. Fields marked with `{.deserialize(ignore=true).}` will not be deserialized. A `SerdeError` is raised if the field is missing in JSON. |
56
+
|`Strict`| All object fields will be serialized, regardless if the field is marked with `{.serialize(ignore=true).}`. | Object fields and JSON fields must match exactly, otherwise a `SerdeError` is raised. |
57
+
58
+
### Default Modes
59
+
60
+
Types can be serialized and deserialized even without explicit annotations, using default modes. Without any pragmas, types are serialized in OptIn mode and deserialized in OptOut mode. When types have pragmas but no specific mode is set, OptOut mode is used for both serialization and deserialization.
61
+
62
+
63
+
| Context | Serialize | Deserialize |
64
+
|:--------|:----------|:------------|
65
+
| Default (no pragma) |`OptIn`|`OptOut`|
66
+
| Default (pragma, but no mode) |`OptOut`|`OptOut`|
67
+
68
+
```nim
69
+
# Type is not annotated
70
+
# A default mode of OptIn (for serialize) and OptOut (for deserialize) is assumed.
71
+
type MyObj1 = object
72
+
field1: bool
73
+
field2: bool
74
+
75
+
# Type is annotated, but mode not specified
76
+
# A default mode of OptOut is assumed for both serialize and deserialize.
77
+
type MyObj2 {.serialize, deserialize.} = object
78
+
field1: bool
79
+
field2: bool
80
+
```
81
+
82
+
### Field Options
83
+
84
+
Individual fields can be customized using the `{.serialize.}` and `{.deserialize.}` pragmas with additional options that control how each field is processed during serialization and deserialization
|`key`| aliases the field name in json | deserializes the field if json contains `key`|
90
+
|`ignore`| <li>**OptOut:** field not serialized</li><li>**OptIn:** field not serialized</li><li>**Strict:** field serialized</li> | <li>**OptOut:** field not deserialized</li><li>**OptIn:** field not deserialized</li><li>**Strict:** field deserialized</li> |
91
+
92
+
93
+
Example with field options:
94
+
95
+
```nim
96
+
import pkg/serde/json
97
+
98
+
type
99
+
Person {.serialize(mode=OptOut), deserialize(mode=OptIn).} = object
100
+
id {.serialize(ignore=true), deserialize(key="personid").}: int
101
+
name: string
102
+
birthYear: int
103
+
address: string
104
+
phone: string
105
+
106
+
let person = Person(
107
+
name: "Lloyd Christmas",
108
+
birthYear: 1970,
109
+
address: "123 Sesame Street, Providence, Rhode Island 12345",
110
+
phone: "555-905-justgivemethedamnnumber!⛽️🔥")
111
+
112
+
let createRequest = """{
113
+
"name": "Lloyd Christmas",
114
+
"birthYear": 1970,
115
+
"address": "123 Sesame Street, Providence, Rhode Island 12345",
0 commit comments