@@ -241,7 +241,7 @@ There are dozens of different functions in [`+dejs:format`](/docs/hoon/reference
242## More `+dejs`
242## More `+dejs`
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.
@@ -331,6 +331,64 @@ Let's try it:
331dojo: hoon expression failed
331dojo: hoon expression failed
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.
338+Here are some simple examples of using `+su` to parse strings:
341+> `@ux`((su:dejs:format hex) s+'deadbeef1337f00D')
342+0xdead.beef.1337.f00d
344+> `(list @)`((su:dejs:format (most lus dem)) s+'1+2+3+4')
347+> `@ub`((su:dejs:format ven) s+'+>-<->+<+')
351+Here's a more complex parser that will parse a GUID like `824e7749-4eac-9c00-db16-4cb816cd6f19` to a `@ux`:
361+|= parts=(list [step @])
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)))
374+Save it in the `/gen` directory of the `%base` desk and `|commit` it. We can then try it with:
377+> +su-test s+'5323a61d-0c26-d8fa-2b73-18cdca805fd8'
378+0x5323.a61d.0c26.d8fa.2b73.18cd.ca80.5fd8
381+If we delete the last character it'll no longer be a valid GUID and the parsing will fail:
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]>
389+dojo: naked generator failure
334## `mark` file example
392## `mark` file example
336Here'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.
394Here'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
449[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.
507[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.
451[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.
509[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.
511+[Parsing Guide](/docs/hoon/guides/parsing) - Learn how to write functional parsers in hoon which can be used with `+su`.