@@ -241,7 +241,7 @@ There are dozens of different functions in [`+dejs:format`](/docs/hoon/reference
241241
242242## More `+dejs`
243243
244−We looked at the commonly used `+ot` function in the [first example](#converting-from-json), now let's look at a couple more common `+dejs` object functions.
244+We looked at the commonly used `+ot` function in the [first example](#converting-from-json), now let's look at a couple more common `+dejs` functions.
245245
246246### `+of`
247247
@@ -331,6 +331,64 @@ Let's try it:
331331dojo: hoon expression failed
332332```
333333
334+### `+su`
335+
336+The [`+su`](/docs/hoon/reference/zuse/2d_6#sudejsformat) function parses a string with the given parsing `rule`. Hoon's functional parsing library is very powerful and lets you create arbitrarily complex parsers. JSON will often have data types encoded in strings, so this function can be very useful. The writing of parsers is outside the scope of this guide, but you can see the [Parsing Guide](/docs/hoon/guides/parsing) and sections 4e to 4j of the standard library documentation for details.
337+
338+Here are some simple examples of using `+su` to parse strings:
339+
340+```
341+> `@ux`((su:dejs:format hex) s+'deadbeef1337f00D')
342+0xdead.beef.1337.f00d
343+
344+> `(list @)`((su:dejs:format (most lus dem)) s+'1+2+3+4')
345+~[1 2 3 4]
346+
347+> `@ub`((su:dejs:format ven) s+'+>-<->+<+')
348+0b11.1000.1101
349+```
350+
351+Here's a more complex parser that will parse a GUID like `824e7749-4eac-9c00-db16-4cb816cd6f19` to a `@ux`:
352+
353+#### `su-test.hoon`
354+
355+```hoon
356+|= jon=json
357+^- @ux
358+%. jon
359+%- su:dejs:format
360+%+ cook
361+|= parts=(list [step @])
362+^- @ux
363+(can 3 (flop parts))
364+;~ plug
365+ (stag 4 ;~(sfix (bass 16 (stun 8^8 six:ab)) hep))
366+ (stag 2 ;~(sfix qix:ab hep))
367+ (stag 2 ;~(sfix qix:ab hep))
368+ (stag 2 ;~(sfix qix:ab hep))
369+ (stag 6 (bass 16 (stun 12^12 six:ab)))
370+ (easy ~)
371+==
372+```
373+
374+Save it in the `/gen` directory of the `%base` desk and `|commit` it. We can then try it with:
375+
376+```
377+> +su-test s+'5323a61d-0c26-d8fa-2b73-18cdca805fd8'
378+0x5323.a61d.0c26.d8fa.2b73.18cd.ca80.5fd8
379+```
380+
381+If we delete the last character it'll no longer be a valid GUID and the parsing will fail:
382+
383+```
384+> +su-test s+'5323a61d-0c26-d8fa-2b73-18cdca805fd'
385+/gen/su-test/hoon:<[2 1].[16 3]>
386+/gen/su-test/hoon:<[3 1].[16 3]>
387+{1 36}
388+syntax error
389+dojo: naked generator failure
390+```
391+
334392## `mark` file example
335393
336394Here's a simple `mark` file for the `$user` structure we created in the [first example](#json-encoding-and-decoding-example). It imports the [json-test.hoon](#json-testhoon) library we created and saved in our `%base` desk's `/lib` directory.
@@ -449,3 +507,5 @@ Usually (though not in all cases) these mark conversions will be performed impli
449507[The Iris documentation](/docs/arvo/iris/iris) - Details of the web client vane Iris, which may be used to fetch external JSON data among other things.
450508
451509[Strings Guide](/docs/hoon/guides/strings) - Atom printing functions like `+scot` will often be useful for JSON encoding - see the [Encoding in Text](/docs/hoon/guides/strings#encoding-in-text) section for usage.
510+
511+[Parsing Guide](/docs/hoon/guides/parsing) - Learn how to write functional parsers in hoon which can be used with `+su`.