content/docs/userspace/full-stack/4-json.md · urbit.org

git.iko.soy/urbit.org

on 4fdc19d help sign in

urbit.org/content/docs/userspace/full-stack/4-json.md

357 lines 13 kB history raw

1+++

2title = "4. JSON"

3weight = 4

4template = "doc.html"

5+++

7Data sent between our agent and our front-end will all be encoded as JSON. In

8this section, we'll briefly look at how JSON works in Urbit, and write a library

9to convert our agent's structures to and from JSON for our front-end.

11JSON data comes into Eyre as a string, and Eyre parses it with the

12[`++de-json:html`](/docs/hoon/reference/zuse/2e_2-3#de-jsonhtml) function in

13[`zuse.hoon`](/docs/hoon/reference/zuse/table-of-contents). The

14hoon type it's parsed to is `$json`, which is defined as:

16```hoon

17+$ json :: normal json value

18 $@ ~ :: null

19 $% [%a p=(list json)] :: array

20 [%b p=?] :: boolean

21 [%o p=(map @t json)] :: object

22 [%n p=@ta] :: number

23 [%s p=@t] :: string

24 == ::

25```

27Once Eyre has converted the raw JSON string to a `$json` structure, it will be

28converted to the mark the web client specified and then delivered to the target

29agent (unless the mark specified is already `%json`, in which case it will be

30delivered directly). Outbound facts will go through the same process in

31reverse - converted from the agent's native mark to `$json`, then encoded in a

32string by Eyre using

33[`++en-json:html`](<(/docs/hoon/reference/zuse/2e_2-3#en-jsonhtml)>) and delivered

34to the web client. The basic flow for both inbound messages (pokes) and outbound

35messages (facts and scry results) looks like this:

37![eyre mark flow diagram](https://media.urbit.org/docs/userspace/full-stack-guide/eyre-mark-flow-diagram.svg)

39The mark conversion will be done by the corresponding mark file in `/mar` on the

40agent's desk. In our case it would be `/mar/journal/action.hoon` and

41`/mar/journal/update.hoon` in the `%journal` desk for our `%journal-action` and

42`%journal-update` marks, which are for the `$action` and `$update` structures we

43defined previously.

45Mark conversion functions can be included directly in the mark file, or they can

46be written in a separate library, then imported and called by the mark file. We

47will do the latter in this case, so before we create the mark files themselves,

48we'll write a library called `/lib/journal.hoon` with the conversion functions.

50## `$json` utilities

52[`zuse.hoon`](/docs/hoon/reference/zuse/table-of-contents) contains three main

53cores for converting to and from `$json`:

55- [`++enjs:format`](/docs/hoon/reference/zuse/2d_1-5#enjsformat) - Functions to

56 help encode data structures as `$json`.

57- [`++dejs:format`](/docs/hoon/reference/zuse/2d_6#dejsformat) - Functions to

58 decode `$json` to other data structures.

59- [`++dejs-soft:format`](/docs/hoon/reference/zuse/2d_7#dejs-softformat) -

60 Mostly the same as `++dejs:format` except the functions produce units which

61 are null if decoding fails, rather than just crashing.

63### `++enjs:format`

65This contains ten functions for encoding `$json`. Most of them are for specific

66hoon data types, such as `++tape:enjs:format`, `++ship:enjs:format`,

67`++path:enjs:format`, etc. We'll just have a look at the two most general and

68useful ones: `++frond:enjs:format` and `++pairs:enjs:format`.

70#### `++frond`

72This function is for forming a JSON object from a single key-value pair. For

73example:

75```

76> (frond:enjs:format 'foo' s+'bar')

77[%o p={[p='foo' q=[%s p='bar']]}]

78```

80When stringified by Eyre, this will look like:

82```json

83{ "foo": "bar" }

84```

86#### `++pairs`

88This is similar to `++frond` and also forms a JSON object, but it takes multiple

89key-value pairs rather than just one:

91```

92> (pairs:enjs:format ~[['foo' n+~.123] ['bar' s+'abc'] ['baz' b+&]])

93[%o p={[p='bar' q=[%s p='abc']] [p='baz' q=[%b p=%.y]] [p='foo' q=[%n p=~.123]]}]

94```

96When stringified by Eyre, this will look like:

98```json

99{

100 "foo": 123,

101 "baz": true,

102 "bar": "abc"

103}

104```

105

106Notice that we used a knot for the value of `foo` (`n+~.123`). Numbers in JSON

107can be signed or unsigned and integers or floating point values. The `$json`

108structure uses a knot so that you can decide whether a particular number should

109be treated as `@ud`, `@sd`, `@rs`, etc.

110

111### `++dejs:format`

112

113This core contains many functions for decoding `$json`. We'll touch on some

114useful families of `++dejs` functions in brief, but because there's so many, in

115practice you'll need to look through the [`++dejs`

116reference](/docs/hoon/reference/zuse/2d_6) to find the correct functions for

117your use case.

118

119#### Number functions

120

121- `++ne` - decode a number to a `@rd`.

122- `++ni` - decode a number to a `@ud`.

123- `++no` - decode a number to a `@ta`.

124- `++nu` - decode a hexadecimal string to a `@ux`.

125

126For example:

127

128```

129> (ni:dejs:format n+'123')

130123

131```

132

133#### String functions

134

135- `++sa` - decode a string to a `tape`.

136- `++sd` - decode a string containing a `@da` aura date value to a `@da`.

137- `++se` - decode a string containing the specified aura to that aura.

138- `++so` - decode a string to a `@t`.

139- `++su` - decode a string by parsing it with the given [parsing

140 rule](/docs/hoon/reference/stdlib/4f).

141

142#### Array functions

143

144`++ar`, `++as`, and `++at` decode a `$json` array to a `list`, `set`, and

145n-tuple respectively. These gates take other `++dejs` functions as an argument,

146producing a new gate that will then take the `$json` array. For example:

147

148```

149> ((ar so):dejs:format a+[s+'foo' s+'bar' s+'baz' ~])

150<|foo bar baz|>

151```

152

153Notice that `++so` is given as the argument to `++ar`. `++so` is a `++dejs`

154function that decodes a `$json` string to a `cord`. The gate resulting from `(ar so)` is then called with a `$json` array as its argument, and its product is a

155`(list @t)` of the elements of the array.

156

157Many `++dejs` functions take other `++dejs` functions as their arguments. A

158complex nested `$json` decoding function can be built up in this manner.

159

160#### Object functions

161

162- `++of` - decode an object containing a single key-value pair to a head-tagged

163 cell.

164- `++ot` - decode an object to a n-tuple.

165- `++ou` - decode an object to an n-tuple, replacing optional missing values

166 with a given value.

167- `++oj` - decode an object of arrays to a `jug`.

168- `++om` - decode an object to a `map`.

169- `++op` - decode an object to a `map`, and also parse the object keys with a

170 [parsing rule](/docs/hoon/reference/stdlib/4f).

171

172For example:

173

174```

175> =js %- need %- de-json:html

176 '''

177 {

178 "foo": "hello",

179 "baz": true,

180 "bar": 123

181 }

182 '''

183

184> %- (ot ~[foo+so bar+ni]):dejs:format js

185['hello' 123]

186```

187

188## Our types as JSON

189

190We need to decide how our `$action` and `$update` types will be represented as

191JSON in order to write our conversion functions. There are many ways to do this,

192but in this case we'll do it as follows:

193

194### Actions

195

196| JSON | Noun |

197| ------------------------------------------------- | ---------------------------------------------- |

198| `{"add":{"id":1648366311070,"txt":"some text"}}` | `[%add id=1.648.366.034.844 txt='some text']` |

199| `{"edit":{"id":1648366311070,"txt":"some text"}}` | `[%edit id=1.648.366.034.844 txt='some text']` |

200| `{"del":{"id":1648366311070}}` | `[%del id=1.648.366.034.844]` |

201

202### Updates

203

204| Noun | JSON |

205| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |

206| `[1.648.366.492.459 %add id=1.648.366.034.844 txt='some text']` | `{time:1648366481425,"add":{"id":1648366311070,"txt":"some text"}}` |

207| `[1.648.366.492.459 %edit id=1.648.366.034.844 txt='some text']` | `{time:1648366481425,"edit":{"id":1648366311070,"txt":"some text"}}` |

208| `[1.648.366.492.459 %del id=1.648.366.034.844]` | `{time:1648366481425,"del":{"id":1648366311070}}` |

209| `[1.648.366.492.459 %jrnl ~[[id=1.648.366.034.844 txt='some text'] ...]` | `{time:1648366481425,"entries":[{"id":1648366311070,"txt":"some text"},...]}` |

210| `[1.648.366.492.459 %logs ~[[1.648.366.492.459 %add id=1.648.366.034.844 txt='some text'] ...]` | `{time:1648366481425,"logs":[{time:1648366481425,"add":{id":1648366311070,"txt":"some text"}},...]}` |

211

212Now let's write our library of encoding/decoding functions.

213

214## `/lib/journal.hoon`

215

216```hoon

217/- *journal

218|%

219```

220

221First, we'll import the `/sur/journal.hoon` structures we previously created.

222Next, we'll create two arms in our core, `++dejs-action` and `++enjs-update`, to