Skip to content

Commit 907bd3c

Browse files
committed
Add a message about needed to export hooks.
1 parent b6f9d2f commit 907bd3c

File tree

1 file changed

+22
-18
lines changed

1 file changed

+22
-18
lines changed

README.md

Lines changed: 22 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,11 @@ doAssert v.colorBlend == "red"
8686

8787
## Has hooks.
8888

89-
### `proc newHook()` Can be used to populate default values.
89+
Hooks are a powerful concept that allows you to parse json "your way" and is the main idea behind `jsony`!
90+
91+
* Note: that hooks need to be exported to where you are parsing the json so that the parsing system can pick them up.
92+
93+
### `proc newHook*()` Can be used to populate default values.
9094

9195
Sometimes the absence of a field means it should have a default value. Normally this would just be Nim's default value for the variable type but that isn't always what you want. With the newHook() you can initialize the object's defaults before the main parsing happens.
9296

@@ -95,7 +99,7 @@ type
9599
Foo5 = object
96100
visible: string
97101
id: string
98-
proc newHook(foo: var Foo5) =
102+
proc newHook*(foo: var Foo5) =
99103
# Populates the object before its fully deserialized.
100104
foo.visible = "yes"
101105
@@ -105,7 +109,7 @@ doAssert v.id == "123"
105109
doAssert v.visible == "yes"
106110
```
107111

108-
### `proc postHook()` Can be used to run code after the object is fully parsed.
112+
### `proc postHook*()` Can be used to run code after the object is fully parsed.
109113

110114
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:
111115

@@ -114,25 +118,25 @@ type Sizer = object
114118
size: int
115119
originalSize: int
116120
117-
proc postHook(v: var Sizer) =
121+
proc postHook*(v: var Sizer) =
118122
v.originalSize = v.size
119123
120124
var sizer = """{"size":10}""".fromJson(Sizer)
121125
doAssert sizer.size == 10
122126
doAssert sizer.originalSize == 10
123127
```
124128

125-
### `proc enumHook()` Can be used to parse enums.
129+
### `proc enumHook*()` Can be used to parse enums.
126130

127-
In the wild json enum names almost never match to Nim enum names which usually have a prefix. The enumHook() allows you to rename the enums to your internal names.
131+
In the wild json enum names almost never match to Nim enum names which usually have a prefix. The `enumHook*()` allows you to rename the enums to your internal names.
128132

129133
```nim
130134
type Color2 = enum
131135
c2Red
132136
c2Blue
133137
c2Green
134138
135-
proc enumHook(v: string): Color2 =
139+
proc enumHook*(v: string): Color2 =
136140
case v:
137141
of "RED": c2Red
138142
of "BLUE": c2Blue
@@ -144,37 +148,37 @@ doAssert """ "BLUE" """.fromJson(Color2) == c2Blue
144148
doAssert """ "GREEN" """.fromJson(Color2) == c2Green
145149
```
146150

147-
### `proc renameHook()` Can be used to rename fields at run time.
151+
### `proc renameHook*()` Can be used to rename fields at run time.
148152

149-
In the wild json field names can be reserved words such as type, class, or array. With the renameHook you can rename fields to what you want.
153+
In the wild json field names can be reserved words such as type, class, or array. With the `renameHook*()` you can rename fields to what you want.
150154

151155
```nim
152156
type Node = ref object
153157
kind: string
154158
155-
proc renameHook(v: var Node, fieldName: var string) =
159+
proc renameHook*(v: var Node, fieldName: var string) =
156160
if fieldName == "type":
157161
fieldName = "kind"
158162
159163
var node = """{"type":"root"}""".fromJson(Node)
160164
doAssert node.kind == "root"
161165
```
162166

163-
### `proc parseHook()` Can be used to do anything.
167+
### `proc parseHook*()` Can be used to do anything.
164168

165169
Json can't store dates, so they are usually stored as strings. You can use
166-
`parseHook()` to override default parsing and parse `DateTime` as a `string`:
170+
`parseHook*()` to override default parsing and parse `DateTime` as a `string`:
167171

168172
```nim
169-
proc parseHook(s: string, i: var int, v: var DateTime) =
173+
proc parseHook*(s: string, i: var int, v: var DateTime) =
170174
var str: string
171175
parseHook(s, i, str)
172176
v = parse(str, "yyyy-MM-dd hh:mm:ss")
173177
174178
var dt = """ "2020-01-01 00:00:00" """.fromJson(DateTime)
175179
```
176180

177-
Sometimes json gives you an object of entries with their id as keys, but you might want it as a sequence with ids inside the objects. You can handle this and many other scenarios with `parseHook()`:
181+
Sometimes json gives you an object of entries with their id as keys, but you might want it as a sequence with ids inside the objects. You can handle this and many other scenarios with `parseHook*()`:
178182

179183
```nim
180184
type Entry = object
@@ -188,7 +192,7 @@ let data = """{
188192
"3": {"count":99, "filled": 99}
189193
}"""
190194
191-
proc parseHook(s: string, i: var int, v: var seq[Entry]) =
195+
proc parseHook*(s: string, i: var int, v: var seq[Entry]) =
192196
var table: Table[string, Entry]
193197
parseHook(s, i, table)
194198
for k, entry in table.mpairs:
@@ -207,16 +211,16 @@ Gives us:
207211
]"""
208212
```
209213

210-
### `proc dumpHook()` Can be used to serializer into custom representation.
214+
### `proc dumpHook*()` Can be used to serializer into custom representation.
211215

212-
Just like reading custom data types you can also write data types with `dumpHook`.
216+
Just like reading custom data types you can also write data types with `dumpHook*()`.
213217

214218
```nim
215219
type Fraction = object
216220
numerator: int
217221
denominator: int
218222
219-
proc dumpHook(s: var string, v: Fraction) =
223+
proc dumpHook*(s: var string, v: Fraction) =
220224
## Output fraction type as a string "x/y".
221225
s.add '"'
222226
s.add $v.numerator

0 commit comments

Comments
 (0)