# 2d(6): From JSON
## `+dejs:format`
Container arm for JSON decoding reparsers
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 `/sys/lull.hoon` as:
```hoon
+$ json :: normal json value
$@ ~ :: null
$% [%a p=(list json)] :: array
[%b p=?] :: boolean
[%o p=(map @t json)] :: object
[%n p=@ta] :: number
[%s p=@t] :: string
== ::
```
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:
```hoon
=> |% ++ grub *
++ fist $-(json grub)
-- ::
```
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.
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`.
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](https://docs.urbit.org/hoon/zuse/2d_7) functions, which return `+unit`s.
***
### `+ar:dejs:format`
Array as list
Convert array `jon` to a list, decoding each item in `jon` with `wit`.
The `+ar` function is a wet gate that takes `wit` and produces a new gate which takes `jon`.
#### Accepts
`wit` is a `+fist` and is the sample of the wet gate.
`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.
#### Produces
A `(list [type])` where `[type]` is the type produced by `wit`.
#### Source
```hoon
++ ar
|* wit=fist
|= jon=json ^- (list _(wit *json))
?> ?=([%a *] jon)
(turn p.jon wit)
```
#### Examples
```
> ((ar so):dejs:format a+[s+'foo' s+'bar' s+'baz' ~])
<|foo bar baz|>
```
***
### `+as:dejs:format`
Array as set
Convert array `jon` to a set, decoding each item in `jon` with `.a`.
The `+as` function is a wet gate that takes `.a` and produces a new gate which takes `jon`.
#### Accepts
`.a` is a `+fist`, and is the sample of the wet gate.
`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.
#### Produces
A `(set [type])` where `[type]` is the type produced by `.a`.
#### Source
```hoon
++ as
|* a=fist
(cu ~(gas in *(set _$:a)) (ar a))
```
#### Examples
```
> ((as so):dejs:format a+[s+'foo' s+'bar' s+'baz' ~])
[n='baz' l={'bar'} r={'foo'}]
```
***
### `+at:dejs:format`
Array as tuple
Convert array `jon` to a tuple, decoding each item in the array with the corresponding `+fist` in list `wil`.
The `+at` function is a wet gate that takes `wil` and produces a new gate which takes `jon`.
#### Accepts
`wil` is a `(pole fist)`, and is the sample of the wet gate. A `+pole` is a faceless list.
`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.
#### Produces
A tuple of the same types and in the same order as those produced by the `+fist`s in `wil`.
#### Source
```hoon
++ at
|* wil=(pole fist)
|= jon=json
?> ?=([%a *] jon)
((at-raw wil) p.jon)
```
#### Examples
```
> ((at ~[so ni bo]):dejs:format a+[s+'foo' n+'123' b+& ~])
['foo' 123 %.y]
```
```
> ((at ~[so ni bo]):dejs:format a+[b+& s+'foo' n+'123' ~])
dojo: hoon expression failed
```
***
### `+at-raw:dejs:format`
Array as tuple, raw
This function is used internally by `+at` and would not typically be used directly.
`+at-raw` converts list `jol` to a tuple, decoding each item in the list with the corresponding function in list `wil`.
The `+at-raw` function is a wet gate that takes `wil` and produces a new gate which takes `jol`.
#### Accepts
`wil` is a `(pole fist)`, and the sample of the wet gate. A `+pole` is a faceless list.
`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.
#### Produces
A tuple of the types and in the same order as those produced by the `+fist`s in `wil`.
#### Source
```hoon
++ at-raw
|* wil=(pole fist)
|= jol=(list json)
?~ jol !!
?- wil
:: [wit=* t=*]
[* t=*]
=> .(wil [wit *]=wil)
?~ t.wil ?^(t.jol !! (wit.wil i.jol))
[(wit.wil i.jol) ((at-raw t.wil) t.jol)]
==
```
#### Examples
```
> ((at-raw ~[so ni bo]):dejs:format ~[s+'foo' n+'123' b+&])
['foo' 123 %.y]
```
```
> ((at-raw ~[so ni bo]):dejs:format ~[n+'123' s+'foo' b+&])
dojo: hoon expression failed
```
***
### `+bo:dejs:format`
Boolean
Convert boolean `jon` to a `?`.
#### Accepts
`jon` is a `$json` boolean.
#### Produces
A `?`.
#### Source
```hoon
++ bo
|=(jon=json ?>(?=([%b *] jon) p.jon))
```
#### Examples
```
> (bo:dejs:format b+|)
%.n
```
***
### `+bu:dejs:format`
Boolean NOT
Convert the logical NOT of boolean `jon` to a `?`.
#### Accepts
`jon` is a `$json` boolean.
#### Produces
A `?`.
#### Source
```hoon
++ bu
|=(jon=json ?>(?=([%b *] jon) !p.jon))
```
#### Examples
```
> (bu:dejs:format [%b %.y])
%.n
```
***
### `+ci:dejs:format`
Maybe transform
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.
The `+ci` function is a wet gate that takes a `poq` and `wit` and produces a new gate that takes `jon`.
#### Accepts
`poq` is a `$gate` that produces a `+unit`.
`wit` is a `+fist`.
The wet gate takes `[poq=gate wit=fist]`.
`jon` is `$json` of the kind accepted by `wit`. `jon` is the sample of the gate produced by the wet gate.
#### Produces
If gate `poq` produces `(unit [type])`, produce `[type]` or else crash.
#### Source
```hoon
++ ci
|* [poq=gate wit=fist]
|= jon=json
(need (poq (wit jon)))
```
#### Examples
```
> ((ci |=(a=? ?:(=(a &) `'foo' ~)) bo):dejs:format b+&)
'foo'
```
```
> ((ci |=(a=? ?:(=(a &) `'foo' ~)) bo):dejs:format b+|)
dojo: hoon expression failed
```
***
### `+cu:dejs:format`
Transform
Decode `jon` with `wit`, then transform it with gate `poq`.
The `+cu` function is a wet gate that takes `poq` and `wit` and produces a new gate that takes `jon`.
#### Accepts
`poq` is a `$gate`.
`wit` is a `+fist`.
The wet gate takes `[poq=gate wit=fist]`.
`jon` is `$json` of the kind handled by `wit`. `jon` is the sample of the gate produced by the wet gate.
#### Produces
The type produced by the gate given in `poq`.
#### Source
```hoon
++ cu
|* [poq=gate wit=fist]
|= jon=json
(poq (wit jon))
```
#### Examples
```
> ((cu |=(=@t [t t t]) so):dejs:format s+'foo')
['foo' 'foo' 'foo']
```
***
### `+di:dejs:format`
Millisecond date
Convert number `jon`, containing a Unix milliseconds timestamp, to a date.
#### Accepts
`jon` is a `$json` number.
#### Produces
A `@da`.
#### Source
```hoon
++ di
(cu from-unix-ms:chrono:userlib ni)
```
#### Examples
```
> =time (time:enjs:format now)
> time
[%n p=~.1630471202176]
> (di:dejs:format time)
~2021.9.1..04.40.02..2d0e.5604.1893.74bc
```
***
### `+du:dejs:format`
Second date
Convert number `jon`, containing a Unix seconds timestamp, to a date.
#### Accepts
`jon` is a `$json` number.
#### Produces
A `@da`.
#### Source
```hoon
++ du
(cu from-unix:chrono:userlib ni)
```
#### Examples
```
> =sec (sect:enjs:format now)
> sec
[%n p=~.1630471524]
> (du:dejs:format sec)
~2021.9.1..04.45.24
```
***
### `+mu:dejs:format`
True unit
Decode `jon` with `wit`, then wrap it in a `+unit`. Produce `~` if `jon` is `~`.
The `+mu` function is a wet gate that takes `wit` and produces a gate which takes `jon`.
#### Accepts
`wit` is a `+fist`.
The wet gate takes `wit=fist`.
`jon` is `$json` of the kind `wit` handles. `jon` is the sample of the gate produced by the wet gate.
#### Produces
A `(unit [type])`, where `[type]` is the type produced by the `+fist` specified in `wit`.
#### Source
```hoon
++ mu
|* wit=fist
|= jon=json
?~(jon ~ (some (wit jon)))
```
#### Examples
```
> ((mu so):dejs:format s+'foo')
[~ 'foo']
```
```
> ((mu so):dejs:format ~)
~
```
***
### `+ne:dejs:format`
Number as real
Convert number `jon` to a `@rd`.
#### Accepts
`jon` is a `$json` number.
#### Produces
A `@rd`.
#### Source
```hoon
++ ne
|= jon=json
^- @rd
?> ?=([%n *] jon)
(rash p.jon (cook ryld (cook royl-cell:^so json-rn)))
```
#### Examples
```
> (ne:dejs:format n+'123')
.~123
```
```
> (ne:dejs:format n+'2.47')
.~2.47
```
***
### `+ni:dejs:format`
Number as integer
Convert number `jon` to a `@ud`. `jon` must be an integer or it will crash.
#### Accepts
`jon` is a `$json` number.
#### Produces
A `@ud`.
#### Source
```hoon
++ ni
|= jon=json
?> ?=([%n *] jon)
(rash p.jon dem)
```
#### Examples
```
> (ni:dejs:format n+'123')
123
```
```
> (ni:dejs:format n+'2.47')
{1 2}
syntax error
```
***
### `+no:dejs:format`
Number as knot
Convert number `jon` to a `@ta`.
#### Accepts
`jon` is a `$json` number.
#### Produces
A `@ta`.
#### Source
```hoon
++ no
|=(jon=json ?>(?=([%n *] jon) p.jon))
```
#### Examples
```
> (no:dejs:format n+'2.47')
~.2.47
```
```
> (no:dejs:format n+'123')
~.123
```
***
### `+nu:dejs:format`
Parse string as hex
Parse string `jon` as hexadecimal or crash.
#### Accepts
`jon` is a `$json` string.
#### Produces
A `@`.
#### Source
```hoon
++ nu
|= jon=json
?> ?=([%s *] jon)
(rash p.jon hex)
```
#### Examples
```
> `@ux`(nu:dejs:format s+'DEADBEEF')
0xdead.beef
```
```
> `@ux`(nu:dejs:format s+'deadbeef')
0xdead.beef
```
```
> `@ux`(nu:dejs:format s+'0xdeadbeef')
{1 2}
syntax error
```
***
### `+of:dejs:format`
Object as frond
Convert object `jon`, which contains a single key-value pair, to a key-value tuple using the `+fist` in `wer` which matches the key.
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`.
**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.
#### Accepts
`wer` is a `(pole [cord fist])`, and is the sample of the wet gate. A `+pole` is a faceless `+list`.
`jon` is a `$json` object containing a single key. `jon` is the sample of the gate produced by the wet gate.
#### Produces
A `[@t [type]]` where `[type]` is the type produced by the matching `+fist`.
#### Source
```hoon
++ of
|* wer=(pole [cord fist])
|= jon=json
?> ?=([%o [@ *] ~ ~] jon)
|-
?- wer
:: [[key=@t wit=*] t=*]
[[key=@t *] t=*]
=> .(wer [[* wit] *]=wer)
?: =(key.wer p.n.p.jon)
[key.wer ~|(key+key.wer (wit.wer q.n.p.jon))]
?~ t.wer ~|(bad-key+p.n.p.jon !!)
((of t.wer) jon)
==
```
#### Examples
First, let's store some objects containing key-value pairs:
```
> =obj-1 o+(malt ['foo' s+'hello']~)
> (en:json:html obj-1)
'{"foo":"hello"}'
```
```
> =obj-2 o+(malt ~[['bar' a+~[n+'123' n+'456']]])
> (en:json:html obj-2)
'{"bar":[123,456]}'
```
```
> =obj-3 o+(malt ['baz' b+&]~)
> (en:json:html obj-3)
'{"baz":true}'
```
Next, let's construct a `+of` function and try it on our objects:
```
> ((of ~[foo+so bar+(ar ni)]):dejs:format obj-1)
[%'foo' 'hello']
```
```
> ((of ~[foo+so bar+(ar ni)]):dejs:format obj-2)
[%'bar' ~[123 456]]
```
```
> ((of ~[foo+so bar+(ar ni)]):dejs:format obj-3)
[%bad-key 'baz']
dojo: hoon expression failed
```
***
### `+ot:dejs:format`
Object as tuple.
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.
The `+ot` function is a wet gate that takes a list of key-`+fist` pairs, and produces a gate which takes `$json`.
**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.
#### Accepts
`wer` is a `(pole [cord fist])`, and is the sample of the wet gate. A `+pole` is a faceless list.
`jon` is a `$json` object, and is the sample of the gate produced by the wet gate.
#### Produces
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`.
#### Source
```hoon
++ ot
|* wer=(pole [cord fist])
|= jon=json
?> ?=([%o *] jon)
((ot-raw wer) p.jon)
```
#### Examples
```
> %- (ot ~[foo+so bar+ni]):dejs:format
o+(malt (limo ~[['bar' n+'123'] ['foo' s+'hello'] ['baz' b+&]]))
['hello' 123]
```
```
> %- (ot ~[foo+so bar+ni]):dejs:format
o+(malt (limo ~[['bar' n+'123'] ['baz' b+&]]))
[%key 'foo']
dojo: hoon expression failed
```
***
### `+ot-raw:dejs:format`
Object as tuple, raw
This function is used internally by [+ot](#otdejsformat) and would not typically be used directly.
`+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.
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`.
**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.
#### Accepts
`wer` is a `(pole [cord fist])`, and is the sample of the wet gate. A `+pole` is a faceless list.
`jom` is a `(map @t json)`, and is the sample of the gate produced by the wet gate.
#### Produces
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`.
#### Source
```hoon
++ ot-raw
|* wer=(pole [cord fist])
|= jom=(map @t json)
?- wer
:: [[key=@t wit=*] t=*]
[[key=@t *] t=*]
=> .(wer [[* wit] *]=wer)
=/ ten ~|(key+key.wer (wit.wer (~(got by jom) key.wer)))
?~(t.wer ten [ten ((ot-raw t.wer) jom)])
==
```
#### Examples
```
> %- (ot-raw ~[foo+so bar+ni]):dejs:format
(malt (limo ~[['bar' n+'123'] ['foo' s+'hello'] ['baz' b+&]]))
['hello' 123]
```
```
> %- (ot-raw ~[foo+so bar+ni]):dejs:format
(malt (limo ~[['bar' n+'123'] ['baz' b+&]]))
[%key 'foo']
dojo: hoon expression failed
```
***
### `+ou:dejs:format`
Object of units
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:
* It wraps each value in `jon` in a `+unit` before passing it to the corresponding function in `wer`.
* If a key in `wer` has no matching key in `jon`, it passes `~` to that function.
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`.
The `+ou` function is a wet gate that takes a list of key-function pairs, and produces a gate which takes `$json`.
**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.
#### Accepts
`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.
`jon` is a `$json` object, and is the sample of the gate produced by the wet gate.
#### Produces
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`.
#### Source
```hoon
++ ou
|* wer=(pole [cord fist])
|= jon=json
?> ?=([%o *] jon)
((ou-raw wer) p.jon)
```
#### Examples
```
> %- (ou ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
o+(malt (limo ~[['foo' s+'hello']]))
['hello' %missing]
```
```
> %- (ou ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
o+(malt (limo ~[['bar' n+'123']]))
[%key 'foo']
dojo: hoon expression failed
```
```
> %- (ou ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
o+(malt (limo ~[['foo' s+'hello'] ['bar' n+'123']]))
['hello' 123]
```
***
### `+ou-raw:dejs:format`
Object of units, raw
This function is used internally by [+ou](#oudejsformat), you would not typically use it directly.
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:
* It wraps each value in `jom` in a `+unit` before passing it to the corresponding function in `wer`.
* If a key in `wer` has no matching key in `jom`, it passes `~` to that function.
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.
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`.
**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.
#### Accepts
`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.
`jon` is a `(map @t json)`, and is the sample of the gate produced by the wet gate.
#### Produces
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`.
#### Source
```hoon
++ ou-raw
|* wer=(pole [cord fist])
|= jom=(map @t json)
?- wer
:: [[key=@t wit=*] t=*]
[[key=@t *] t=*]
=> .(wer [[* wit] *]=wer)
=/ ten ~|(key+key.wer (wit.wer (~(get by jom) key.wer)))
?~(t.wer ten [ten ((ou-raw t.wer) jom)])
==
```
#### Examples
```
> %- (ou-raw ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
(malt (limo ~[['foo' s+'hello']]))
['hello' %missing]
```
```
> %- (ou-raw ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
(malt (limo ~[['bar' n+'123']]))
[%key 'foo']
dojo: hoon expression failed
```
```
> %- (ou-raw ~[foo+(un so) bar+(uf missing+ni)]):dejs:format
(malt (limo ~[['foo' s+'hello'] ['bar' n+'123']]))
['hello' 123]
```
***
### `+oj:dejs:format`
Object as jug
Convert `jon`, an object of arrays, to a `+jug`. Decode each element in each array with `+fist`.
The `+oj` function is a wet gate that takes `+fist` and produces a gate that takes `jon`.
#### Accepts
`+fist` is a `+fist`, and is the sample of the wet gate.
`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.
#### Produces
A `(jug cord [type])`, where `[type]` is the type produced by `+fist`.
#### Source
```hoon
++ oj
|* =fist
^- $-(json (jug cord _(fist *json)))
(om (as fist))
```
#### Examples
```
> =jon (need (de:json:html '{"foo":["aaa","bbb","ccc"],"bar":["xxx","yyy","zzz"]}'))
> ((oj so):dejs:format jon)
{[p='bar' q={'xxx' 'zzz' 'yyy'}] [p='foo' q={'bbb' 'ccc' 'aaa'}]}
```
***
### `+om:dejs:format`
Object as map
Convert object `jon` to a map, decoding each value with `wit`.
The `+om` function is a wet gate that takes `wit` and produces a gate that takes `jon`.
#### Accepts
`wit` is a `+fist`, and is the sample of the wet gate.
`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.
#### Produces
A `(map cord [type])`, where `[type]` is the type produced by `wit`.
#### Source
```hoon
++ om
|* wit=fist
|= jon=json
?> ?=([%o *] jon)
(~(run by p.jon) wit)
```
#### Examples
```
> =jon (need (de:json:html '{"foo":"aaa","bar":"bbb"}'))
> ((om so):dejs:format jon)
{[p='bar' q='bbb'] [p='foo' q='aaa']}
```
***
### `+op:dejs:format`
Parse keys of map
Convert object `jon` to a map, parsing each key with `fel` and decoding each value with `wit`.
The `+op` function is a wet gate that takes `fel` and `wit`, and produces a gate that takes `jon`.
#### Accepts
The wet gate takes a cell of `[fel wil]`, where `fel` is a parsing `$rule` and `wil` is a `+fist`.
`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.
#### Produces
A `(map [a] [b])` where `[a]` is the type produced by `fel` and `[b]` is the type produced by `wit`.
#### Source
```hoon
++ op
|* [fel=rule wit=fist]
|= jon=json ^- (map _(wonk *fel) _*wit)
=/ jom ((om wit) jon)
%- malt
%+ turn ~(tap by jom)
|* [a=cord b=*]
=> .(+< [a b]=+<)
[(rash a fel) b]
```
#### Examples
```
> =jon (need (de:json:html '{"123":"aaa","456":"bbb"}'))
> ((op dem so):dejs:format jon)
{[p=456 q='bbb'] [p=123 q='aaa']}
```
***
### `+pa:dejs:format`
String as path
Convert `jon` and parse to a path.
#### Accepts
`jon` is a `$json` string encoding a `$path`.
#### Produces
A `(list @)` which can be cast to a `$path`.
#### Source
```hoon
++ pa
(su stap)
```
#### Examples
```
> `path`(pa:dejs:format s+'/foo/bar/baz')
/foo/bar/baz
```
***
### `+pe:dejs:format`
Prefix
Decode `jon` with `wit`, and prefix the result with `pre`.
The `+pe` function is a wet gate that takes `pre` and `wit`, and produces a gate that takes `jon`.
#### Accepts
The wet gate takes a cell of `[pre wit]`, where `pre` is any noun and `wit` is a `+fist`.
`jon` is `$json` of the kind accepted by `wit`. `jon` is the sample of the gate produced by the wet gate.
#### Produces
A cell of `[[a] [b]]`, where `[a]` is the noun given in `pre` and `[b]` is the type produced by `wit`.
#### Source
```hoon
++ pe
|* [pre=* wit=fist]
(cu |*(* [pre +<]) wit)
```
#### Examples
```
> ((pe %foo so):dejs:format s+'bar')
[%foo 'bar']
```
***
### `+sa:dejs:format`
String as tape
Convert `jon` to a `$tape`.
#### Accepts
`jon` is a `$json` string.
#### Produces
A `$tape`.
#### Source
```hoon
++ sa
|=(jon=json ?>(?=([%s *] jon) (trip p.jon)))
```
#### Examples
```
> (sa:dejs:format s+'foo')
"foo"
```
***
### `+sd:dejs:format`
String `@ud` as date
Convert `jon` to a `@da`, parsing it as a date in `@ud` form.
#### Accepts
`jon` is a `$json` string encoding a date in `@ud` form.
#### Produces
A `@da`.
#### Source
```hoon
++ sd
|= jon=json
^- @da
?> ?=(%s -.jon)
`@da`(rash p.jon dem:ag)
```
#### Examples
```
> (sd:dejs:format s+(scot %ud now))
~2021.9.8..01.02.41..e5db
```
***
### `+se:dejs:format`
String as aura
Convert and parse `jon` to an atom of the type specified in `aur`.
The `+se` function is a gate within a gate. The first gate takes `aur` and the second takes `jon`.
#### Accepts
`aur` is a `@tas` denoting an aura like `%ud`, `%tas`, `%p`, etc. `aur` is the sample of the first gate
`jon` is a `$json` string encoding an atom of the type specified in `aur`. `jon` is the sample of the second nested gate.
#### Produces
A `@` which can then be cast to the type specified in `aur`.
#### Source
```hoon
++ se
|= aur=@tas
|= jon=json
?>(?=([%s *] jon) (slav aur p.jon))
```
#### Examples
```
> `@p`((se %p):dejs:format s+(scot %p our))
~zod
```
```
> `@da`((se %da):dejs:format s+(scot %da now))
~2021.9.8..01.12.28..4f6a
```
***
### `+so:dejs:format`
String as cord
Convert `jon` to a cord.
#### Accepts
`jon` is a `$json` string.
#### Produces
A `@t`.
#### Source
```hoon
++ so
|=(jon=json ?>(?=([%s *] jon) p.jon))
```
#### Examples
```
> (so:dejs:format s+'foo')
'foo'
```
***
### `+su:dejs:format`
Parse string
Convert and parse `jon` with `sab`.
The `+su` function is a wet gate that takes `sab`, and produces a gate that takes `jon`.
#### Accepts
`sab` is a parsing `$rule`, and is the sample of the wet gate.
`jon` is a `$json` string, and is the sample of the gate produced by the wet gate.
#### Produces
The type produced by `sab`.
#### Source
```hoon
++ su
|* sab=rule
|= jon=json ^+ (wonk *sab)
?> ?=([%s *] jon)
(rash p.jon sab)
```
#### Examples
```
> ((su dem):dejs:format s+'123456')
123.456
```
```
> `@ub`((su bin):dejs:format s+'00001011101110001101')
0b1011.1011.1000.1101
```
***
### `+uf:dejs:format`
Unit fall
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.
The `+uf` function is a wet gate that takes `def` and `wit`, and produces a gate that takes `jon`.
#### Accepts
The wet gate takes a cell of `[def wit]`, where `def` is any `$noun` and `wit` is a `+fist`.
`jon` is a `(unit json)`, and is the sample of the gate produced by the wet gate.
#### Produces
Either the type produced by `wit`, or else the `$noun` given in `def` if `jon` is null.
#### Source
```hoon
++ uf
|* [def=* wit=fist]
|= jon=(unit json)
?~(jon def (wit u.jon))
```
#### Examples
```
> ((uf %missing so):dejs:format `s+'foo')
'foo'
```
```
> ((uf %missing so):dejs:format ~)
%missing
```
***
### `+un:dejs:format`
Unit need
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.
The `+un` function is a wet gate that takes `wit` and produces a gate that takes `jon`.
#### Accepts
`wit` is a `+fist`, and is the sample of the wet gate.
`jon` is a `(unit json)`, and is the sample of the gate returned by the wet gate.
#### Produces
The type produced by `wit` or crash if `jon` is null.
#### Source
```hoon
++ un
|* wit=fist
|= jon=(unit json)
(wit (need jon))
```
#### Examples
```
> ((un so):dejs:format `s+'foo')
'foo'
```
```
> ((un so):dejs:format ~)
dojo: hoon expression failed
```
***
### `+ul:dejs:format`
Null
Return `~` if `jon` is null or else crash.
#### Accepts
`jon` is null `$json`.
#### Produces
`~` if `jon` is null, otherwise crashes.
#### Source
```hoon
++ ul
|=(jon=json ?~(jon ~ !!))
```
#### Examples
```
> (ul:dejs:format ~)
~
```
```
> (ul:dejs:format b+&)
dojo: hoon expression failed
```
***
### `+za:dejs:format`
Full unit pole
Check whether all units in list `pod` are non-null. This is used internally by some functions and would not typically be used directly.
#### Accepts
`pod` is a `(pole (unit))`. A `+pole` is a faceless list.
#### Produces
A `?`, which is `%.n` if any of the `+unit`s in `pod` are `~`, and `%.y` otherwise.
#### Source
```hoon
++ za
|* pod=(pole (unit))
?~ pod &
?~ -.pod |
(za +.pod)
```
#### Examples
```
> (za:dejs:format ~[`1 `2 `3 `4])
%.y
```
```
> (za:dejs:format ~)
%.y
```
```
> (za:dejs:format ~[`1 `2 ~ `4])
%.n
```
***
### `+zl:dejs:format`
Collapse unit list
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.
#### Accepts
A `(list (unit))`.
#### Produces
A `(unit (list))` which is null if any of the units in `lut` were null.
#### Source
```hoon
++ zl
|* lut=(list (unit))
?. |- ^- ?
?~(lut & ?~(i.lut | $(lut t.lut)))
~
%- some
|-
?~ lut ~
[i=u:+.i.lut t=$(lut t.lut)]
```
#### Examples
```
> (zl:dejs:format (limo ~[`1 `2 `3 `4 `5 `6]))
[~ [i=1 t=~[2 3 4 5 6]]]
```
```
> (zl:dejs:format (limo ~[`1 `2 ~ `4 `5 `6]))
~
```
***
### `+zp:dejs:format`
Unit tuple
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.
#### Accepts
`but` is a `(pole (unit))`. A `+pole` is a faceless list.
#### Produces
A tuple containing each unwrapped element from the original list, or crashes if any of the units were null.
#### Source
```hoon
++ zp
|* but=(pole (unit))
?~ but !!
?~ +.but
u:->.but
[u:->.but (zp +.but)]
```
#### Examples
```
> (zp:dejs:format ~[`1 `2 `3 `4 `5 `6])
[1 2 3 4 5 6]
```
```
> (zp:dejs:format ~[`1 `2 ~ `4 `5 `6])
mull-none
dojo: hoon expression failed
```
***
### `+zm:dejs:format`
Collapse unit map
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.
#### Accepts
`lum` is a `(map term (unit))`
#### Produces
A `(unit (map term [type]))`, where `[type]` is the type the units in `lum` contained. Produces `~` if any of the units were null.
#### Source
```hoon
++ zm
|* lum=(map term (unit))
?: (~(rep by lum) |=([[@ a=(unit)] b=_|] |(b ?=(~ a))))
~
(some (~(run by lum) need))
```
#### Examples
```
> (zm:dejs:format (malt ~[['foo' `1] ['bar' `2]]))
[~ {[p='bar' q=2] [p='foo' q=1]}]
```
```
> (zm:dejs:format (malt (limo ~[['foo' `1] ['bar' ~]])))
~
```