@@ -0,0 +1,1551 @@
1++++
2+title = "2d(6): From JSON"
3+weight = 42
4+template = "doc.html"
5++++
6+
7+## `++dejs:format`
8+
9+Container arm for JSON decoding reparsers
10+
11+The `core` inside this arm contains a large collection of functions for converting `json` data to other kinds of nouns. The `json` type is defined in `lull.hoon` as:
12+
13+```hoon
14++$ json :: normal json value
15+ $@ ~ :: null
16+ $% [%a p=(list json)] :: array
17+ [%b p=?] :: boolean
18+ [%o p=(map @t json)] :: object
19+ [%n p=@ta] :: number
20+ [%s p=@t] :: string
21+ == ::
22+```
23+
24+This container arm doesn't do anything by itself. It just contains the core with the rest of the `+dejs` functions which are documented below, plus it defines a couple of things for those functions:
25+
26+```hoon
27+=> |% ++ grub *
28+ ++ fist $-(json grub)
29+ -- ::
30+```
31+
32+A `fist` is a `gate` which takes `json` and produces a `grub`. Apart from a handful of exceptions, all of the functions below are `fist`s. If the functions below aren't adequate for a particular use case, custom `fist`s can easily be written, as long as they conform to the `$-(json grub)` type definition.
33+
34+A `grub` is just defined as `*`, and is the type of the product of a `fist`. In the case of `+dejs`, it can be absolutely any `noun`.
35+
36+Keep in mind that `+grub:dejs:format` and `+fist:dejs:format` defined here (and subsequently referred to as simply `fist` and `grub`) are different to `+grub:dejs-soft:format` and `+fist:dejs-soft:format` for the [+dejs-soft](/docs/hoon/reference/zuse/2d_7) functions, which return `unit`s.
37+
38+---
39+
40+### `++ar:dejs:format`
41+
42+Array as list
43+
44+Convert array `jon` to a list, decoding each item in `jon` with `wit`.
45+
46+The `+ar` function is a wet gate that takes `wit` and produces a new gate which takes `jon`.
47+
48+#### Accepts
49+
50+`wit` is a `fist` and is the sample of the wet gate.
51+
52+`jon` is a `json` array containing the kind of `json` that `wit` handles. `jon` is the sample of the gate produced by the wet gate.
53+
54+#### Produces
55+
56+A `(list [type])` where `[type]` is the type produced by `wit`.
57+
58+#### Source
59+
60+```hoon
61+++ ar
62+ |* wit=fist
63+ |= jon=json ^- (list _(wit *json))
64+ ?> ?=([%a *] jon)
65+ (turn p.jon wit)
66+```
67+
68+#### Examples
69+
70+```
71+> ((ar so):dejs:format a+[s+'foo' s+'bar' s+'baz' ~])
72+<|foo bar baz|>
73+```
74+
75+---
76+
77+### `++as:dejs:format`
78+
79+Array as set
80+
81+Convert array `jon` to a set, decoding each item in `jon` with `a`.
82+
83+The `+as` function is a wet gate that takes `a` and produces a new gate which takes `jon`.
84+
85+#### Accepts
86+
87+`a` is a `fist`, and is the sample of the wet gate.
88+
89+`jon` is a `json` array containing the kind of `json` that `a` takes. `jon` is the sample of the gate produced by the wet gate.
90+
91+#### Produces
92+
93+A `(set [type])` where `[type]` is the type produced by `a`.
94+
95+#### Source
96+
97+```hoon
98+++ as
99+ |* a=fist
100+ (cu ~(gas in *(set _$:a)) (ar a))
101+```
102+
103+#### Examples
104+
105+```
106+> ((as so):dejs:format a+[s+'foo' s+'bar' s+'baz' ~])
107+[n='baz' l={'bar'} r={'foo'}]
108+```
109+
110+---
111+
112+### `++at:dejs:format`
113+
114+Array as tuple
115+
116+Convert array `jon` to a tuple, decoding each item in the array with the corresponding `fist` in list `wil`.
117+
118+The `+at` function is a wet gate that takes `wil` and produces a new gate which takes `jon`.
119+
120+#### Accepts
121+
122+`wil` is a `(pole fist)`, and is the sample of the wet gate. A `pole` is a faceless list.
123+
124+`jon` is a `json` array whose elements are the same kinds of `json` accepted by the `fist`s in `wil` and in the same order. `jon` is the sample of the gate produced by the wet gate.
125+
126+#### Produces
127+
128+A tuple of the same types and in the same order as those produced by the `fist`s in `wil`.
129+
130+#### Source
131+
132+```hoon
133+++ at
134+ |* wil=(pole fist)
135+ |= jon=json
136+ ?> ?=([%a *] jon)
137+ ((at-raw wil) p.jon)
138+```
139+
140+#### Examples
141+
142+```
143+> ((at ~[so ni bo]):dejs:format a+[s+'foo' n+'123' b+& ~])
144+['foo' 123 %.y]
145+```
146+
147+```
148+> ((at ~[so ni bo]):dejs:format a+[b+& s+'foo' n+'123' ~])
149+dojo: hoon expression failed
150+```
151+
152+---
153+
154+### `++at-raw:dejs:format`
155+
156+Array as tuple, raw
157+
158+This function is used internally by `+at` and would not typically be used directly.
159+
160+`+at-raw` converts list `jol` to a tuple, decoding each item in the list with the corresponding function in list `wil`.
161+
162+The `+at-raw` function is a wet gate that takes `wil` and produces a new gate which takes `jol`.
163+
164+#### Accepts
165+
166+`wil` is a `(pole fist)`, and the sample of the wet gate. A `pole` is a faceless list.
167+
168+`jol` is a `(list json)` whose items are the same kinds of `json` accepted by the `fist`s in `wil` and in the same order. `jol` is the sample of the gate produced by the wet gate.
169+
170+#### Produces
171+
172+A tuple of the types and in the same order as those produced by the `fist`s in `wil`.
173+
174+#### Source
175+
176+```hoon
177+++ at-raw
178+ |* wil=(pole fist)
179+ |= jol=(list json)
180+ ?~ jol !!
181+ ?- wil
182+ :: [wit=* t=*]
183+ [* t=*]
184+ => .(wil [wit *]=wil)
185+ ?~ t.wil ?^(t.jol !! (wit.wil i.jol))
186+ [(wit.wil i.jol) ((at-raw t.wil) t.jol)]
187+ ==
188+```
189+
190+#### Examples
191+
192+```
193+> ((at-raw ~[so ni bo]):dejs:format ~[s+'foo' n+'123' b+&])
194+['foo' 123 %.y]
195+```
196+
197+```
198+> ((at-raw ~[so ni bo]):dejs:format ~[n+'123' s+'foo' b+&])
199+dojo: hoon expression failed
200+```
201+
202+---
203+
204+### `++bo:dejs:format`
205+
206+Boolean
207+
208+Convert boolean `jon` to a `?`.
209+
210+#### Accepts
211+
212+`jon` is a `json` boolean.
213+
214+#### Produces
215+
216+A `?`.
217+
218+#### Source
219+
220+```hoon
221+++ bo
222+ |=(jon=json ?>(?=([%b *] jon) p.jon))
223+```
224+
225+#### Examples
226+
227+```
228+> (bo:dejs:format b+|)
229+%.n
230+```
231+
232+---
233+
234+### `++bu:dejs:format`
235+
236+Boolean NOT
237+
238+Convert the logical NOT of boolean `jon` to a `?`.
239+
240+#### Accepts
241+
242+`jon` is a `json` boolean.
243+
244+#### Produces
245+
246+A `?`.
247+
248+#### Source
249+
250+```hoon
251+++ bu
252+ |=(jon=json ?>(?=([%b *] jon) !p.jon))
253+```
254+
255+#### Examples
256+
257+```
258+> (bu:dejs:format [%b %.y])
259+%.n
260+```
261+
262+---
263+
264+### `++ci:dejs:format`
265+
266+Maybe transform
267+
268+Decode `jon` with `wit`, then transform it with gate `poq` which produces a `unit`. Crash if the `unit` is `~` or else unwrap it and produce its data.
269+
270+The `+ci` function is a wet gate that takes a `poq` and `wit` and produces a new gate that takes `jon`.
271+
272+#### Accepts
273+
274+`poq` is a `gate` that produces a `unit`.
275+
276+`wit` is a `fist`.
277+
278+The wet gate takes `[poq=gate wit=fist]`.
279+
280+`jon` is `json` of the kind accepted by `wit`. `jon` is the sample of the gate produced by the wet gate.
281+
282+#### Produces
283+
284+If gate `poq` produces `(unit [type])`, produce `[type]` or else crash.
285+
286+#### Source
287+
288+```hoon
289+++ ci
290+ |* [poq=gate wit=fist]
291+ |= jon=json
292+ (need (poq (wit jon)))
293+```
294+
295+#### Examples
296+
297+```
298+> ((ci |=(a=? ?:(=(a &) `'foo' ~)) bo):dejs:format b+&)
299+'foo'
300+```
301+
302+```
303+> ((ci |=(a=? ?:(=(a &) `'foo' ~)) bo):dejs:format b+|)
304+dojo: hoon expression failed
305+```
306+
307+---
308+
309+### `++cu:dejs:format`
310+
311+Transform
312+
313+Decode `jon` with `wit`, then transform it with gate `poq`.
314+
315+The `+cu` function is a wet gate that takes `poq` and `wit` and produces a new gate that takes `jon`.
316+
317+#### Accepts
318+
319+`poq` is a `gate`.
320+
321+`wit` is a `fist`.
322+
323+The wet gate takes `[poq=gate wit=fist]`.
324+
325+`jon` is `json` of the kind handled by `wit`. `jon` is the sample of the gate produced by the wet gate.
326+
327+#### Produces
328+
329+The type produced by the gate given in `poq`.
330+
331+#### Source
332+
333+```hoon
334+++ cu
335+ |* [poq=gate wit=fist]
336+ |= jon=json
337+ (poq (wit jon))
338+```
339+
340+#### Examples
341+
342+```
343+> ((cu |=(=@t [t t t]) so):dejs:format s+'foo')
344+['foo' 'foo' 'foo']
345+```
346+
347+---
348+
349+### `++di:dejs:format`
350+
351+Millisecond date
352+
353+Convert number `jon` containing milliseconds to a date.
354+
355+#### Accepts
356+
357+`jon` is a `json` number.
358+
359+#### Produces
360+
361+A `@da`.
362+
363+#### Source
364+
365+```hoon
366+++ di
367+ (cu from-unix-ms:chrono:userlib ni)
368+```
369+
370+#### Examples
371+
372+```
373+> =time (time:enjs:format now)
374+> time
375+[%n p=~.1630471202176]
376+> (di:dejs:format time)
377+~2021.9.1..04.40.02..2d0e.5604.1893.74bc
378+```
379+
380+---
381+
382+### `++du:dejs:format`
383+
384+Second date
385+
386+Convert number `jon` containing seconds to a date.
387+
388+#### Accepts
389+
390+`jon` is a `json` number.
391+
392+#### Produces
393+
394+A `@da`.
395+
396+#### Source
397+
398+```hoon
399+++ du
400+ (cu from-unix:chrono:userlib ni)
401+```
402+
403+#### Examples
404+
405+```
406+> =sec (sect:enjs:format now)
407+> sec
408+[%n p=~.1630471524]
409+> (du:dejs:format sec)
410+~2021.9.1..04.45.24
411+```
412+
413+---
414+
415+### `++mu:dejs:format`
416+
417+True unit
418+
419+Decode `jon` with `wit`, then wrap it in a `unit`. Produce `~` if `jon` is `~`.
420+
421+The `+mu` function is a wet gate that takes `wit` and produces a gate which takes `jon`.
422+
423+#### Accepts
424+
425+`wit` is a `fist`.
426+
427+The wet gate takes `wit=fist`.
428+
429+`jon` is `json` of the kind `wit` handles. `jon` is the sample of the gate produced by the wet gate.
430+
431+#### Produces
432+
433+A `(unit [type])`, where `[type]` is the type produced by the `fist` specified in `wit`.
434+
435+#### Source
436+
437+```hoon
438+++ mu
439+ |* wit=fist
440+ |= jon=json
441+ ?~(jon ~ (some (wit jon)))
442+```
443+
444+#### Examples
445+
446+```
447+> ((mu so):dejs:format s+'foo')
448+[~ 'foo']
449+```
450+
451+```
452+> ((mu so):dejs:format ~)
453+~
454+```
455+
456+---
457+
458+### `++ne:dejs:format`
459+
460+Number as real
461+
462+Convert number `jon` to a `@rd`.
463+
464+#### Accepts
465+
466+`jon` is a `json` number.
467+
468+#### Produces
469+
470+A `@rd`.
471+
472+#### Source
473+
474+```hoon
475+++ ne
476+ |= jon=json
477+ ^- @rd
478+ ?> ?=([%n *] jon)
479+ (rash p.jon (cook ryld (cook royl-cell:^so json-rn)))
480+```
481+
482+#### Examples
483+
484+```
485+> (ne:dejs:format n+'123')
486+.~123
487+```
488+
489+```
490+> (ne:dejs:format n+'2.47')
491+.~2.47
492+```
493+
494+---
495+
496+### `++ni:dejs:format`
497+
498+Number as integer
499+
500+Convert number `jon` to a `@ud`. `jon` must be an integer or it will crash.
501+
502+#### Accepts
503+
504+`jon` is a `json` number.
505+
506+#### Produces
507+
508+A `@ud`.
509+
510+#### Source
511+
512+```hoon
513+++ ni
514+ |= jon=json
515+ ?> ?=([%n *] jon)
516+ (rash p.jon dem)
517+```
518+
519+#### Examples
520+
521+```
522+> (ni:dejs:format n+'123')
523+123
524+```
525+
526+```
527+> (ni:dejs:format n+'2.47')
528+{1 2}
529+syntax error
530+```
531+
532+---
533+
534+### `++no:dejs:format`
535+
536+Number as knot
537+
538+Convert number `jon` to a `@ta`.
539+
540+#### Accepts
541+
542+`jon` is a `json` number.
543+
544+#### Produces
545+
546+A `@ta`.
547+
548+#### Source
549+
550+```hoon
551+++ no
552+ |=(jon=json ?>(?=([%n *] jon) p.jon))
553+```
554+
555+#### Examples
556+
557+```
558+> (no:dejs:format n+'2.47')
559+~.2.47
560+```
561+
562+```
563+> (no:dejs:format n+'123')
564+~.123
565+```
566+
567+---
568+
569+### `++nu:dejs:format`
570+
571+Parse string as hex
572+
573+Parse string `jon` as hexadecimal or crash.
574+
575+#### Accepts
576+
577+`jon` is a `json` string.
578+
579+#### Produces
580+
581+A `@`.
582+
583+#### Source
584+
585+```hoon
586+++ nu
587+ |= jon=json
588+ ?> ?=([%s *] jon)
589+ (rash p.jon hex)
590+```
591+
592+#### Examples
593+
594+```
595+> `@ux`(nu:dejs:format s+'DEADBEEF')
596+0xdead.beef
597+```
598+
599+```
600+> `@ux`(nu:dejs:format s+'deadbeef')
601+0xdead.beef
602+```
603+
604+```
605+> `@ux`(nu:dejs:format s+'0xdeadbeef')
606+{1 2}
607+syntax error
608+```
609+
610+---
611+
612+### `++of:dejs:format`
613+
614+Object as frond
615+
616+Convert object `jon`, which contains a single key-value pair, to a key-value tuple using the `fist` in `wer` which matches the key.
617+
618+The `+of` function is a wet gate that takes a list of pairs of keys and `fist`s and produces a new gate that takes `json`.
619+
620+**Note:** While technically the type of an item in the list `wer` is specified as `[cord fist]`, actually using a `cord` may result in incorrect type inferrence. Instead, you'll want to format it as a `@tas` like `%foo`, so the type system correctly interprets it as a tagged union. If the key contains characters that would be invalid in an ordinary `@tas`, you can format it like `%'foo_bar'` - a `%` then single quotes.
621+
622+#### Accepts
623+
624+`wer` is a `(pole [cord fist])`, and is the sample of the wet gate. A `pole` is a faceless `list`.
625+
626+`jon` is a `json` object containing a single key. `jon` is the sample of the gate produced by the wet gate.
627+
628+#### Produces
629+
630+A `[@t [type]]` where `[type]` is the type produced by the matching `fist`.
631+
632+#### Source
633+
634+```hoon
635+++ of
636+ |* wer=(pole [cord fist])
637+ |= jon=json
638+ ?> ?=([%o [@ *] ~ ~] jon)
639+ |-
640+ ?- wer
641+ :: [[key=@t wit=*] t=*]
642+ [[key=@t *] t=*]
643+ => .(wer [[* wit] *]=wer)
644+ ?: =(key.wer p.n.p.jon)
645+ [key.wer ~|(key+key.wer (wit.wer q.n.p.jon))]
646+ ?~ t.wer ~|(bad-key+p.n.p.jon !!)
647+ ((of t.wer) jon)
648+ ==
649+```
650+
651+#### Examples
652+
653+First, let's store some objects containing key-value pairs:
654+
655+```
656+> =obj-1 o+(malt ['foo' s+'hello']~)
657+> (crip (en-json:html obj-1))
658+'{"foo":"hello"}'
659+```
660+
661+```
662+> =obj-2 o+(malt ~[['bar' a+~[n+'123' n+'456']]])
663+> (crip (en-json:html obj-2))
664+'{"bar":[123,456]}'
665+```
666+
667+```
668+> =obj-3 o+(malt ['baz' b+&]~)
669+> (crip (en-json:html obj-3))
670+'{"baz":true}'
671+```
672+
673+Next, let's construct a `+of` function and try it on our objects:
674+
675+```
676+> ((of ~[foo+so bar+(ar ni)]):dejs:format obj-1)
677+[%'foo' 'hello']
678+```
679+
680+```
681+> ((of ~[foo+so bar+(ar ni)]):dejs:format obj-2)
682+[%'bar' ~[123 456]]
683+```
684+
685+```
686+> ((of ~[foo+so bar+(ar ni)]):dejs:format obj-3)
687+[%bad-key 'baz']
688+dojo: hoon expression failed
689+```
690+
691+---
692+
693+### `++ot:dejs:format`
694+
695+Object as tuple.
696+
697+Convert object `jon` to a tuple by decoding each value with the matching `fist` in `wer`. Each key in `wer` must be matched to a key in `jon`. On the other hand, if there are keys in `jon` with no corresponding key in `wer`, they'll simply be ignored.
698+
699+The `+ot` function is a wet gate that takes a list of key-`fist` pairs, and produces a gate which takes `json`.
700+
701+**Note:** While technically the type of an item in the list `wer` is specified as `[cord fist]`, actually using a `cord` may result in incorrect type inferrence. Instead, you'll want to format it as a `@tas` like `%foo`, so the type system correctly interprets it as a tagged union. If the key contains characters that would be invalid in an ordinary `@tas`, you can format it like `%'foo_bar'` - a `%` then single quotes.
702+
703+#### Accepts
704+
705+`wer` is a `(pole [cord fist])`, and is the sample of the wet gate. A `pole` is a faceless list.
706+
707+`jon` is a `json` object, and is the sample of the gate produced by the wet gate.
708+
709+#### Produces
710+
711+A tuple where the type of each item is the product of the corresponding `fist` in `wer`. The order of items in the tuple will match the order of items in `wer`.
712+
713+#### Source
714+
715+```hoon
716+++ ot
717+ |* wer=(pole [cord fist])
718+ |= jon=json
719+ ?> ?=([%o *] jon)
720+ ((ot-raw wer) p.jon)
721+```
722+
723+#### Examples
724+
725+```
726+> %- (ot ~[foo+so bar+ni]):dejs:format
727+ o+(malt (limo ~[['bar' n+'123'] ['foo' s+'hello'] ['baz' b+&]]))
728+['hello' 123]
729+```
730+
731+```
732+> %- (ot ~[foo+so bar+ni]):dejs:format
733+ o+(malt (limo ~[['bar' n+'123'] ['baz' b+&]]))
734+[%key 'foo']
735+dojo: hoon expression failed
736+```
737+
738+---
739+
740+### `++ot-raw:dejs:format`
741+
742+Object as tuple, raw
743+
744+This function is used internally by [+ot](#otdejsformat) and would not typically be used directly.
745+
746+`+ot-raw` converts map `jom` to a tuple by decoding each value with the matching `fist` in `wer`. Each key in `wer` must be matched to a key in the given map. On the other hand, if there are keys in the map with no corresponding key in `wer`, they'll simply be ignored.
747+
748+The `+ot-raw` function is a wet gate that takes a list of key-`fist` pairs, and produces a gate which takes a map of keys to `json`.
749+
750+**Note:** While technically the type of an item in the list `wer` is specified as `[cord fist]`, actually using a `cord` may result in incorrect type inferrence. Instead, you'll want to format it as a `@tas` like `%foo`, so the type system correctly interprets it as a tagged union. If the key contains characters that would be invalid in an ordinary `@tas`, you can format it like `%'foo_bar'` - a `%` then single quotes.
751+
752+#### Accepts
753+
754+`wer` is a `(pole [cord fist])`, and is the sample of the wet gate. A `pole` is a faceless list.
755+
756+`jom` is a `(map @t json)`, and is the sample of the gate produced by the wet gate.
757+
758+#### Produces
759+
760+A tuple where the type of each item is the product of the corresponding `fist` in `wer`. The order of items in the tuple will match the order of items in `wer`.
761+
762+#### Source
763+
764+```hoon
765+++ ot-raw
766+ |* wer=(pole [cord fist])
767+ |= jom=(map @t json)
768+ ?- wer
769+ :: [[key=@t wit=*] t=*]
770+ [[key=@t *] t=*]
771+ => .(wer [[* wit] *]=wer)
772+ =/ ten ~|(key+key.wer (wit.wer (~(got by jom) key.wer)))
773+ ?~(t.wer ten [ten ((ot-raw t.wer) jom)])
774+ ==
775+```
776+
777+#### Examples
778+
779+```
780+> %- (ot-raw ~[foo+so bar+ni]):dejs:format
781+ (malt (limo ~[['bar' n+'123'] ['foo' s+'hello'] ['baz' b+&]]))
782+['hello' 123]
783+```
784+
785+```
786+> %- (ot-raw ~[foo+so bar+ni]):dejs:format
787+ (malt (limo ~[['bar' n+'123'] ['baz' b+&]]))
788+[%key 'foo']
789+dojo: hoon expression failed
790+```
791+
792+---
793+
794+### `++ou:dejs:format`
795+
796+Object of units
797+
798+Convert object `jon` to a tuple by decoding each value with the function in `wer` that matches its key. Keys in `jon` with no matching key in `wer` are ignored. This is the same as [+ot](#otdejsformat) except that:
799+
800+- It wraps each value in `jon` in a `unit` before passing it to the corresponding function in `wer`.
801+- If a key in `wer` has no matching key in `jon`, it passes `~` to that function.
802+
803+Therefore, the functions must take a `(unit json)` rather than just `json`, so they are not `fist`s but rather `$-((unit json) grub)` (despite what the source code says). There are two `+dejs` functions that can be used in `+ou` and take `unit`s: [+uf](#ufdejsformat) and [+un](#undejsformat). Both of them wrap `fist`s like `(uf so)` or `(un so)`. The former, `+uf`, lets you replace a null `unit` with something of your choosing. The latter, `+un`, crashes if the `unit` is null. Using both in a `+ou` allows you to set some values as mandatory and others as optional, replacing any missing optional ones with whatever you want. This is the ultimate purpose of `+ou`.
804+
805+The `+ou` function is a wet gate that takes a list of key-function pairs, and produces a gate which takes `json`.
806+
807+**Note:** While technically the type of an item in the list `wer` is specified as `[cord fist]`, actually using a `cord` may result in incorrect type inferrence. Instead, you'll want to format it as a `@tas` like `%foo`, so the type system correctly interprets it as a tagged union. If the key contains characters that would be invalid in an ordinary `@tas`, you can format it like `%'foo_bar'` - a `%` then single quotes.
808+
809+#### Accepts
810+
811+`wer` is a `(pole [cord $-((unit json) grub)])`, despite saying `(pole [cord fist])` in the source code. `wer` is the sample of the wet gate. A `pole` is a faceless list.
812+
813+`jon` is a `json` object, and is the sample of the gate produced by the wet gate.
814+
815+#### Produces
816+
817+A tuple where the type of each item is the product of the corresponding function in `wer`. The order of items in the tuple will match the order of items in `wer`.
818+
819+#### Source
820+
821+```hoon
822+++ ou
823+ |* wer=(pole [cord fist])
824+ |= jon=json
825+ ?> ?=([%o *] jon)
826+ ((ou-raw wer) p.jon)
827+```
828+
829+#### Examples
830+
831+```
832+> %- (ou ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
833+ o+(malt (limo ~[['foo' s+'hello']]))
834+['hello' %missing]
835+```
836+
837+```
838+> %- (ou ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
839+ o+(malt (limo ~[['bar' n+'123']]))
840+[%key 'foo']
841+dojo: hoon expression failed
842+```
843+
844+```
845+> %- (ou ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
846+ o+(malt (limo ~[['foo' s+'hello'] ['bar' n+'123']]))
847+['hello' 123]
848+```
849+
850+---
851+
852+### `++ou-raw:dejs:format`
853+
854+Object of units, raw
855+
856+This function is used internally by [+ou](#oudejsformat), you would not typically use it directly.
857+
858+Convert map `jom` to a tuple by decoding each value with the function in `wer` that matches its key. Keys in `jom` with no matching key in `wer` are ignored. This is the same as [+ot-raw](#ot-rawdejsformat) except that:
859+
860+- It wraps each value in `jom` in a `unit` before passing it to the corresponding function in `wer`.
861+- If a key in `wer` has no matching key in `jom`, it passes `~` to that function.
862+
863+Therefore, the functions must take a `(unit json)` rather than just `json`, so they are not `fist`s but rather `$-((unit json) grub)` (despite what the source code says). There are two `+dejs` functions that can be used in `+ou-raw` and take `unit`s: [+uf](#ufdejsformat) and [+un](#undejsformat). Both of them wrap `fist`s like `(uf so)` or `(un so)`. The former, `+uf`, lets you replace a null `unit` with something of your choosing. The latter, `+un`, crashes if the `unit` is null. Using both in a `+ou-raw` allows you to set some values as mandatory and others as optional, replacing any missing optional ones with whatever you want.
864+
865+The `+ou-raw` function is a wet gate that takes a list of key-function pairs, and produces a gate which takes a map of `@t` keys to `json`.
866+
867+**Note:** While technically the type of an item in the list `wer` is specified as `[cord fist]`, actually using a `cord` may result in incorrect type inferrence. Instead, you'll want to format it as a `@tas` like `%foo`, so the type system correctly interprets it as a tagged union. If the key contains characters that would be invalid in an ordinary `@tas`, you can format it like `%'foo_bar'` - a `%` then single quotes.
868+
869+#### Accepts
870+
871+`wer` is a `(pole [cord $-((unit json) grub)])`, despite saying `(pole [cord fist])` in the source code. `wer` is the sample of the wet gate. A `pole` is a faceless list.
872+
873+`jon` is a `(map @t json)`, and is the sample of the gate produced by the wet gate.
874+
875+#### Produces
876+
877+A tuple where the type of each item is the product of the corresponding function in `wer`. The order of items in the tuple will match the order of items in `wer`.
878+
879+#### Source
880+
881+```hoon
882+++ ou-raw
883+ |* wer=(pole [cord fist])
884+ |= jom=(map @t json)
885+ ?- wer
886+ :: [[key=@t wit=*] t=*]
887+ [[key=@t *] t=*]
888+ => .(wer [[* wit] *]=wer)
889+ =/ ten ~|(key+key.wer (wit.wer (~(get by jom) key.wer)))
890+ ?~(t.wer ten [ten ((ou-raw t.wer) jom)])
891+ ==
892+```
893+
894+#### Examples
895+
896+```
897+> %- (ou-raw ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
898+ (malt (limo ~[['foo' s+'hello']]))
899+['hello' %missing]
900+```
901+
902+```
903+> %- (ou-raw ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
904+ (malt (limo ~[['bar' n+'123']]))
905+[%key 'foo']
906+dojo: hoon expression failed
907+```
908+
909+```
910+> %- (ou-raw ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
911+ (malt (limo ~[['foo' s+'hello'] ['bar' n+'123']]))
912+['hello' 123]
913+```
914+
915+---
916+
917+### `++oj:dejs:format`
918+
919+Object as jug
920+
921+Convert `jon`, an object of arrays, to a `jug`. Decode each element in each array with `fist`.
922+
923+The `+oj` function is a wet gate that takes `fist` and produces a gate that takes `jon`.
924+
925+#### Accepts
926+
927+`fist` is a `fist`, and is the sample of the wet gate.
928+
929+`jon` is a `json` object of arrays. Each element in each array is of the same `json` kind. `jon` is the sample of the gate produced by the wet gate.
930+
931+#### Produces
932+
933+A `(jug cord [type])`, where `[type]` is the type produced by `fist`.
934+
935+#### Source
936+
937+```hoon
938+++ oj
939+ |* =fist
940+ ^- $-(json (jug cord _(fist *json)))
941+ (om (as fist))
942+```
943+
944+#### Examples
945+
946+```
947+> =jon (need (de-json:html '{"foo":["aaa","bbb","ccc"],"bar":["xxx","yyy","zzz"]}'))
948+> ((oj so):dejs:format jon)
949+{[p='bar' q={'xxx' 'zzz' 'yyy'}] [p='foo' q={'bbb' 'ccc' 'aaa'}]}
950+```
951+
952+---
953+
954+### `++om:dejs:format`
955+
956+Object as map
957+
958+Convert object `jon` to a map, decoding each value with `wit`.
959+
960+The `+om` function is a wet gate that takes `wit` and produces a gate that takes `jon`.
961+
962+#### Accepts
963+
964+`wit` is a `fist`, and is the sample of the wet gate.
965+
966+`jon` is a `json` object whose values are the kind of `json` that `wit` takes. `jon` is the sample of the gate produced by the wet gate.
967+
968+#### Produces
969+
970+A `(map cord [type])`, where `[type]` is the type produced by `wit`.
971+
972+#### Source
973+
974+```hoon
975+++ om
976+ |* wit=fist
977+ |= jon=json
978+ ?> ?=([%o *] jon)
979+ (~(run by p.jon) wit)
980+```
981+
982+#### Examples
983+
984+```
985+> =jon (need (de-json:html '{"foo":"aaa","bar":"bbb"}'))
986+> ((om so):dejs:format jon)
987+{[p='bar' q='bbb'] [p='foo' q='aaa']}
988+```
989+
990+---
991+
992+### `++op:dejs:format`
993+
994+Parse keys of map
995+
996+Convert object `jon` to a map, parsing each key with `fel` and decoding each value with `wit`.
997+
998+The `+op` function is a wet gate that takes `fel` and `wit`, and produces a gate that takes `jon`.
999+
1000+#### Accepts
1001+
1002+The wet gate takes a cell of `[fel wil]`, where `fel` is a parsing `rule` and `wil` is a `fist`.
1003+
1004+`jon` is a `json` object, whose keys are parsable by `fel` and whose values are `json` of the kind `wit` takes. `jon` is the sample of the gate produced by the wet gate.
1005+
1006+#### Produces
1007+
1008+A `(map [a] [b])` where `[a]` is the type produced by `fel` and `[b]` is the type produced by `wit`.
1009+
1010+#### Source
1011+
1012+```hoon
1013+++ op
1014+ |* [fel=rule wit=fist]
1015+ |= jon=json ^- (map _(wonk *fel) _*wit)
1016+ =/ jom ((om wit) jon)
1017+ %- malt
1018+ %+ turn ~(tap by jom)
1019+ |* [a=cord b=*]
1020+ => .(+< [a b]=+<)
1021+ [(rash a fel) b]
1022+```
1023+
1024+#### Examples
1025+
1026+```
1027+> =jon (need (de-json:html '{"123":"aaa","456":"bbb"}'))
1028+> ((op dem so):dejs:format jon)
1029+{[p=456 q='bbb'] [p=123 q='aaa']}
1030+```
1031+
1032+---
1033+
1034+### `++pa:dejs:format`
1035+
1036+String as path
1037+
1038+Convert `jon` and parse to a path.
1039+
1040+#### Accepts
1041+
1042+`jon` is a `json` string encoding a `path`.
1043+
1044+#### Produces
1045+
1046+A `(list @)` which can be cast to a `path`.
1047+
1048+#### Source
1049+
1050+```hoon
1051+++ pa
1052+ (su stap)
1053+```
1054+
1055+#### Examples
1056+
1057+```
1058+> `path`(pa:dejs:format s+'/foo/bar/baz')
1059+/foo/bar/baz
1060+```
1061+
1062+---
1063+
1064+### `++pe:dejs:format`
1065+
1066+Prefix
1067+
1068+Decode `jon` with `wit`, and prefix the result with `pre`.
1069+
1070+The `+pe` function is a wet gate that takes `pre` and `wit`, and produces a gate that takes `jon`.
1071+
1072+#### Accepts
1073+
1074+The wet gate takes a cell of `[pre wit]`, where `pre` is any noun and `wit` is a `fist`.
1075+
1076+`jon` is `json` of the kind accepted by `wit`. `jon` is the sample of the gate produced by the wet gate.
1077+
1078+#### Produces
1079+
1080+A cell of `[[a] [b]]`, where `[a]` is the noun given in `pre` and `[b]` is the type produced by `wit`.
1081+
1082+#### Source
1083+
1084+```hoon
1085+++ pe
1086+ |* [pre=* wit=fist]
1087+ (cu |*(* [pre +<]) wit)
1088+```
1089+
1090+#### Examples
1091+
1092+```
1093+> ((pe %foo so):dejs:format s+'bar')
1094+[%foo 'bar']
1095+```
1096+
1097+---
1098+
1099+### `++sa:dejs:format`
1100+
1101+String as tape
1102+
1103+Convert `jon` to a `tape`.
1104+
1105+#### Accepts
1106+
1107+`jon` is a `json` string.
1108+
1109+#### Produces
1110+
1111+A `tape`.
1112+
1113+#### Source
1114+
1115+```hoon
1116+++ sa
1117+ |=(jon=json ?>(?=([%s *] jon) (trip p.jon)))
1118+```
1119+
1120+#### Examples
1121+
1122+```
1123+> (sa:dejs:format s+'foo')
1124+"foo"
1125+```
1126+
1127+---
1128+
1129+### `++sd:dejs:format`
1130+
1131+String `@ud` as date
1132+
1133+Convert `jon` to a `@da`, parsing it as a date in `@ud` form.
1134+
1135+#### Accepts
1136+
1137+`jon` is a `json` string encoding a date in `@ud` form.
1138+
1139+#### Produces
1140+
1141+A `@da`.
1142+
1143+#### Source
1144+
1145+```hoon
1146+++ sd
1147+ |= jon=json
1148+ ^- @da
1149+ ?> ?=(%s -.jon)
1150+ `@da`(rash p.jon dem:ag)
1151+```
1152+
1153+#### Examples
1154+
1155+```
1156+> (sd:dejs:format s+(scot %ud now))
1157+~2021.9.8..01.02.41..e5db
1158+```
1159+
1160+---
1161+
1162+### `++se:dejs:format`
1163+
1164+String as aura
1165+
1166+Convert and parse `jon` to an atom of the type specified in `aur`.
1167+
1168+The `+se` function is a gate within a gate. The first gate takes `aur` and the second takes `jon`.
1169+
1170+#### Accepts
1171+
1172+`aur` is a `@tas` denoting an aura like `%ud`, `%tas`, `%p`, etc. `aur` is the sample of the first gate
1173+
1174+`jon` is a `json` string encoding an atom of the type specified in `aur`. `jon` is the sample of the second nested gate.
1175+
1176+#### Produces
1177+
1178+A `@` which can then be cast to the type specified in `aur`.
1179+
1180+#### Source
1181+
1182+```hoon
1183+++ se
1184+ |= aur=@tas
1185+ |= jon=json
1186+ ?>(?=([%s *] jon) (slav aur p.jon))
1187+```
1188+
1189+#### Examples
1190+
1191+```
1192+> `@p`((se %p):dejs:format s+(scot %p our))
1193+~zod
1194+```
1195+
1196+```
1197+> `@da`((se %da):dejs:format s+(scot %da now))
1198+~2021.9.8..01.12.28..4f6a
1199+```
1200+
1201+---
1202+
1203+### `++so:dejs:format`
1204+
1205+String as cord
1206+
1207+Convert `jon` to a cord.
1208+
1209+#### Accepts
1210+
1211+`jon` is a `json` string.
1212+
1213+#### Produces
1214+
1215+A `@t`.
1216+
1217+#### Source
1218+
1219+```hoon
1220+++ so
1221+ |=(jon=json ?>(?=([%s *] jon) p.jon))
1222+```
1223+
1224+#### Examples
1225+
1226+```
1227+> (so:dejs:format s+'foo')
1228+'foo'
1229+```
1230+
1231+---
1232+
1233+### `++su:dejs:format`
1234+
1235+Parse string
1236+
1237+Convert and parse `jon` with `sab`.
1238+
1239+The `+su` function is a wet gate that takes `sab`, and produces a gate that takes `jon`.
1240+
1241+#### Accepts
1242+
1243+`sab` is a parsing `rule`, and is the sample of the wet gate.
1244+
1245+`jon` is a `json` string, and is the sample of the gate produced by the wet gate.
1246+
1247+#### Produces
1248+
1249+The type produced by `sab`.
1250+
1251+#### Source
1252+
1253+```hoon
1254+++ su
1255+ |* sab=rule
1256+ |= jon=json ^+ (wonk *sab)
1257+ ?> ?=([%s *] jon)
1258+ (rash p.jon sab)
1259+```
1260+
1261+#### Examples
1262+
1263+```
1264+> ((su dem):dejs:format s+'123456')
1265+123.456
1266+```
1267+
1268+```
1269+> `@ub`((su bin):dejs:format s+'00001011101110001101')
1270+0b1011.1011.1000.1101
1271+```
1272+
1273+---
1274+
1275+### `++uf:dejs:format`
1276+
1277+Unit fall
1278+
1279+Convert the `json` data in unit `jon` with `wit` unless `jon` is `~`, in which case return `def`. Note this deals with `(unit json)` rather than the usual `json`. This would typically be used inside a [+ou](#oudejsformat) function to replace missing values with the given values.
1280+
1281+The `+uf` function is a wet gate that takes `def` and `wit`, and produces a gate that takes `jon`.
1282+
1283+#### Accepts
1284+
1285+The wet gate takes a cell of `[def wit]`, where `def` is any `noun` and `wit` is a `fist`.
1286+
1287+`jon` is a `(unit json)`, and is the sample of the gate produced by the wet gate.
1288+
1289+#### Produces
1290+
1291+Either the type produced by `wit`, or else the `noun` given in `def` if `jon` is null.
1292+
1293+#### Source
1294+
1295+```hoon
1296+++ uf
1297+ |* [def=* wit=fist]
1298+ |= jon=(unit json)
1299+ ?~(jon def (wit u.jon))
1300+```
1301+
1302+#### Examples
1303+
1304+```
1305+> ((uf %missing so):dejs:format `s+'foo')
1306+'foo'
1307+```
1308+
1309+```
1310+> ((uf %missing so):dejs:format ~)
1311+%missing
1312+```
1313+
1314+---
1315+
1316+### `++un:dejs:format`
1317+
1318+Unit need
1319+
1320+Convert the `json` data in unit `jon` with `wit` unless `jon` is `~`, in which case crash. Note this deals with `(unit json)` rather than the usual `json`. This would typically be used inside a [+ou](#oudejsformat) function and in conjunction with [+uf](#ufdejsformat) to specify mandatory values.
1321+
1322+The `+un` function is a wet gate that takes `wit` and produces a gate that takes `jon`.
1323+
1324+#### Accepts
1325+
1326+`wit` is a `fist`, and is the sample of the wet gate.
1327+
1328+`jon` is a `(unit json)`, and is the sample of the gate returned by the wet gate.
1329+
1330+#### Produces
1331+
1332+The type produced by `wit` or crash if `jon` is null.
1333+
1334+#### Source
1335+
1336+```hoon
1337+++ un
1338+ |* wit=fist
1339+ |= jon=(unit json)
1340+ (wit (need jon))
1341+```
1342+
1343+#### Examples
1344+
1345+```
1346+> ((un so):dejs:format `s+'foo')
1347+'foo'
1348+```
1349+
1350+```
1351+> ((un so):dejs:format ~)
1352+dojo: hoon expression failed
1353+```
1354+
1355+---
1356+
1357+### `++ul:dejs:format`
1358+
1359+Null
1360+
1361+Return `~` if `jon` is null or else crash.
1362+
1363+#### Accepts
1364+
1365+`jon` is null `json`.
1366+
1367+#### Produces
1368+
1369+`~` if `jon` is null, otherwise crashes.
1370+
1371+#### Source
1372+
1373+```hoon
1374+++ ul
1375+ |=(jon=json ?~(jon ~ !!))
1376+```
1377+
1378+#### Examples
1379+
1380+```
1381+> (ul:dejs:format ~)
1382+~
1383+```
1384+
1385+```
1386+> (ul:dejs:format b+&)
1387+dojo: hoon expression failed
1388+```
1389+
1390+---
1391+
1392+### `++za:dejs:format`
1393+
1394+Full unit pole
1395+
1396+Check whether all units in list `pod` are non-null. This is used internally by some functions and would not typically be used directly.
1397+
1398+#### Accepts
1399+
1400+`pod` is a `(pole (unit))`. A `pole` is a faceless list.
1401+
1402+#### Produces
1403+
1404+A `?`, which is `%.n` if any of the `unit`s in `pod` are `~`, and `%.y` otherwise.
1405+
1406+#### Source
1407+
1408+```hoon
1409+++ za
1410+ |* pod=(pole (unit))
1411+ ?~ pod &
1412+ ?~ -.pod |
1413+ (za +.pod)
1414+```
1415+
1416+#### Examples
1417+
1418+```
1419+> (za:dejs:format ~[`1 `2 `3 `4])
1420+%.y
1421+```
1422+
1423+```
1424+> (za:dejs:format ~)
1425+%.y
1426+```
1427+
1428+```
1429+> (za:dejs:format ~[`1 `2 ~ `4])
1430+%.n
1431+```
1432+
1433+---
1434+
1435+### `++zl:dejs:format`
1436+
1437+Collapse unit list
1438+
1439+Convert `lut`, a list of units, to a `(unit (list))` by stripping the unit from each item. The resulting unit is null if any of the units in the list are null. This is used internally by some functions, you would not typically use it directly.
1440+
1441+#### Accepts
1442+
1443+A `(list (unit))`.
1444+
1445+#### Produces
1446+
1447+A `(unit (list))` which is null if any of the units in `lut` were null.
1448+
1449+#### Source
1450+
1451+```hoon
1452+++ zl
1453+ |* lut=(list (unit))
1454+ ?. |- ^- ?
1455+ ?~(lut & ?~(i.lut | $(lut t.lut)))
1456+ ~
1457+ %- some
1458+ |-
1459+ ?~ lut ~
1460+ [i=u:+.i.lut t=$(lut t.lut)]
1461+```
1462+
1463+#### Examples
1464+
1465+```
1466+> (zl:dejs:format (limo ~[`1 `2 `3 `4 `5 `6]))
1467+[~ [i=1 t=~[2 3 4 5 6]]]
1468+```
1469+
1470+```
1471+> (zl:dejs:format (limo ~[`1 `2 ~ `4 `5 `6]))
1472+~
1473+```
1474+
1475+---
1476+
1477+### `++zp:dejs:format`
1478+
1479+Unit tuple
1480+
1481+Convert `but`, a list of units, to a tuple by stripping the unit from each item. Crashes if any of the units are null. This is used internally by some functions, you would not typically use it directly.
1482+
1483+#### Accepts
1484+
1485+`but` is a `(pole (unit))`. A `pole` is a faceless list.
1486+
1487+#### Produces
1488+
1489+A tuple containing each unwrapped element from the original list, or crashes if any of the units were null.
1490+
1491+#### Source
1492+
1493+```hoon
1494+++ zp
1495+ |* but=(pole (unit))
1496+ ?~ but !!
1497+ ?~ +.but
1498+ u:->.but
1499+ [u:->.but (zp +.but)]
1500+```
1501+
1502+#### Examples
1503+
1504+```
1505+> (zp:dejs:format ~[`1 `2 `3 `4 `5 `6])
1506+[1 2 3 4 5 6]
1507+```
1508+
1509+```
1510+> (zp:dejs:format ~[`1 `2 ~ `4 `5 `6])
1511+mull-none
1512+dojo: hoon expression failed
1513+```
1514+
1515+---
1516+
1517+### `++zm:dejs-soft:format`
1518+
1519+Collapse unit map
1520+
1521+Strip units from values in `lum`, a map of units. Returns null if any of the units are null. This is used internally by some functions, you would not typically use it directly.
1522+
1523+#### Accepts
1524+
1525+`lum` is a `(map term (unit))`
1526+
1527+#### Produces
1528+
1529+A `(unit (map term [type]))`, where `[type]` is the type the units in `lum` contained. Produces `~` if any of the units were null.
1530+
1531+#### Source
1532+
1533+```hoon
1534+++ zm
1535+ |* lum=(map term (unit))
1536+ ?: (~(rep by lum) |=([[@ a=(unit)] b=_|] |(b ?=(~ a))))
1537+ ~
1538+ (some (~(run by lum) need))
1539+```
1540+
1541+#### Examples
1542+
1543+```
1544+> (zm:dejs-soft:format (malt ~[['foo' `1] ['bar' `2]]))
1545+[~ {[p='bar' q=2] [p='foo' q=1]}]
1546+```
1547+
1548+```
1549+> (zm:dejs-soft:format (malt (limo ~[['foo' `1] ['bar' ~]])))
1550+~
1551+```