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: README.md
+25-22Lines changed: 25 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ This library has no dependencies other than the Nim standard library.
10
10
11
11
## About
12
12
13
-
Real world json is *never what you want*. It might have extra fields that you don't care about. It might have missing fields requiring default values. It might change or grow new fields at any moment. Json might use `camelCase` or `snake_case`. It might use inconsistent naming.
13
+
Real world json is _never what you want_. It might have extra fields that you don't care about. It might have missing fields requiring default values. It might change or grow new fields at any moment. Json might use `camelCase` or `snake_case`. It might use inconsistent naming.
14
14
15
15
With this library you can use json your way, from the mess you get to the objects you want.
16
16
@@ -21,14 +21,14 @@ With this library you can use json your way, from the mess you get to the object
21
21
22
22
## Fast.
23
23
24
-
Currently the Nim standard module first parses or serializes json into JsonNodes and then turns the JsonNodes into your objects with the `to()` macro. This is slower and creates unnecessary work for the garbage collector. This library skips the JsonNodes and creates the objects you want directly.
24
+
Currently, the Nim standard module first parses or serializes json into JsonNodes and then turns the JsonNodes into your objects with the `to()` macro. This is slower and creates unnecessary work for the garbage collector. This library skips the JsonNodes and creates the objects you want directly.
25
25
26
26
Another speed up comes from not using `StringStream`. Stream has a function dispatch overhead because it has to be able to switch between `StringStream` or `FileStream` at runtime. Jsony skips the overhead and just directly reads or writes to memory buffers.
27
27
28
28
Another speed up comes from parsing and readings its own numbers directly from memory buffer. This allows it to bypass `string` allocations that `parseInt` or `$` create.
29
29
30
-
31
30
### Serialize speed
31
+
32
32
```
33
33
name ............................... min time avg time std dv times
34
34
treeform/jsony ..................... 1.317 ms 1.365 ms ±0.054 x100
@@ -39,6 +39,7 @@ nim std/json ....................... 8.222 ms 8.510 ms ±0.123 x100
39
39
```
40
40
41
41
### Deserialize speed
42
+
42
43
```
43
44
name ............................... min time avg time std dv times
44
45
treeform/jsony ..................... 4.134 ms 4.196 ms ±0.052 x100
@@ -49,19 +50,19 @@ nim std/json ...................... 14.326 ms 14.473 ms ±0.113 x100
49
50
50
51
Note: If you find a faster nim json parser or serializer let me know!
51
52
52
-
## Can parse or serializer most types:
53
+
## Can parse or serialize most types:
53
54
54
-
* numbers and strings
55
-
* seq and arrays
56
-
* objects and ref objects
57
-
* options
58
-
* enums
59
-
* tuples
60
-
* characters
61
-
*`HashTable`s and `OrderedTable`s
62
-
*`HashSet`s and `OrderedSet`s
63
-
* json nodes
64
-
* and `parseHook()` enables you to parse any type!
55
+
- numbers and strings
56
+
- seq and arrays
57
+
- objects and ref objects
58
+
- options
59
+
- enums
60
+
- tuples
61
+
- characters
62
+
-`HashTable`s and `OrderedTable`s
63
+
-`HashSet`s and `OrderedSet`s
64
+
- json nodes
65
+
- and `parseHook()` enables you to parse any type!
65
66
66
67
## Not strict.
67
68
@@ -94,7 +95,7 @@ doAssert v.colorBlend == "red"
94
95
95
96
Hooks are a powerful concept that allows you to parse json "your way" and is the main idea behind `jsony`!
96
97
97
-
* Note: that hooks need to be exported to where you are parsing the json so that the parsing system can pick them up.
98
+
- Note: that hooks need to be exported to where you are parsing the json so that the parsing system can pick them up.
98
99
99
100
### `proc newHook*()` Can be used to populate default values.
100
101
@@ -117,7 +118,7 @@ doAssert v.visible == "yes"
117
118
118
119
### `proc postHook*()` Can be used to run code after the object is fully parsed.
119
120
120
-
Some times we need run some code after the object is created. For example to set other values based on values that where set but are not part of the json data. Maybe to sanitize the object or convert older versions to new versions. Here I need to retain the original size as I will be messing with the object's regular size:
121
+
Sometimes we need run some code after the object is created. For example to set other values based on values that were set but are not part of the json data. Maybe to sanitize the object or convert older versions to new versions. Here I need to retain the original size as I will be messing with the object's regular size:
121
122
122
123
```nim
123
124
type Sizer = object
@@ -211,6 +212,7 @@ let s = data.fromJson(seq[Entry])
211
212
```
212
213
213
214
Gives us:
215
+
214
216
```
215
217
@[
216
218
(id: "1", count: 12, filled: 11),
@@ -219,7 +221,7 @@ Gives us:
219
221
]"""
220
222
```
221
223
222
-
### `proc dumpHook*()` Can be used to serializer into custom representation.
224
+
### `proc dumpHook*()` Can be used to serialize into custom representation.
223
225
224
226
Just like reading custom data types you can also write data types with `dumpHook*()`.
225
227
The `dumpHook()` will receive the incomplete string representation of a given serialization (here `s`).
@@ -243,19 +245,20 @@ let s = f.toJson()
243
245
```
244
246
245
247
Gives us:
248
+
246
249
```
247
250
"10/13"
248
251
```
249
252
250
253
## Static writing with `toStaticJson`.
251
254
252
-
Some times you have or const json and you want to write it in a static way. There is a special function for that:
255
+
Sometimes you have some json, and you want to write it in a static way. There is a special function for that:
253
256
254
257
```nim
255
258
thing.toStaticJson()
256
259
```
257
260
258
-
Make sure `thing` is a `static` or a `const` value and you will get a compile time string with your JSON.
261
+
Make sure `thing` is a `static` or a `const` value, and you will get a compile time string with your JSON.
259
262
260
263
## Full support for case variant objects.
261
264
@@ -268,11 +271,11 @@ type RefNode = ref object
268
271
of nkFloat: floatVal: float
269
272
```
270
273
271
-
The discriminator do no have to come first, if they do come in the middle this library will scan the object, find the discriminator field, then rewind and parse the object normally.
274
+
The discriminator does not have to come first, if they do come in the middle this library will scan the object, find the discriminator field, then rewind and parse the object normally.
272
275
273
276
## Full support for json-in-json.
274
277
275
-
Some times your json objects could contain arbitrary json structures,
278
+
Sometimes your json objects could contain arbitrary json structures,
276
279
maybe event user defined, that could only be walked as json nodes. This library allows you to parse json-in-json were you parse some of the structure as real nim objects but leave some parts of it as Json Nodes to be walked later with code:
0 commit comments