# 2d(7): From JSON (unit)

## `+dejs-soft:format` <a href="#dejs-softformat" id="dejs-softformat"></a>

Container arm for unitized JSON decoding reparsers

The `+core` inside this arm contains a large collection of functions for converting `$json` data to `+unit`s of various kinds. 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-soft` functions which are documented below, plus it defines a couple of things for those functions:

```hoon
=>  |%  ++  grub  (unit *)
        ++  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 `(unit *)`, and is the type of the product of a `+fist`. In the case of `+dejs-soft`, it can be any noun in a `+unit`.

Keep in mind that `+grub:dejs-soft:format` and `+fist:dejs-soft:format` defined here (and subsequently referred to as simply `+fist` and `+grub`) are different to `+grub:dejs:format` and `+fist:dejs:format` for the [+dejs](https://docs.urbit.org/hoon/zuse/2d_6) functions, which simply return `$noun`s rather than `+unit`s.

***

### `+ar:dejs-soft:format` <a href="#ardejs-softformat" id="ardejs-softformat"></a>

Array as list (in unit)

Convert array `jon` to a list, decoding each item in `jon` with `wit`. The result is wrapped in a unit which is null if the decoding failed.

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 `(unit (list [type]))` where `[type]` is the type produced by `wit`. The `+unit` is null if decoding fails.

#### Source

```hoon
++  ar
  |*  wit=fist
  |=  jon=json
  ?.  ?=([%a *] jon)  ~
  %-  zl
  |-
  ?~  p.jon  ~
  [i=(wit i.p.jon) t=$(p.jon t.p.jon)]
```

#### Examples

```
> ((ar so):dejs-soft:format a+~[s+'foo' s+'bar' s+'baz'])
[~ [i='foo' t=<|bar baz|>]]
```

```
> ((ar so):dejs-soft:format a+~[n+'123' s+'bar' s+'baz'])
~
```

***

### `+at:dejs-soft:format` <a href="#atdejs-softformat" id="atdejs-softformat"></a>

Array as tuple (in unit)

Convert array `jon` to a tuple, decoding each item in the array with the corresponding `+fist` in list `wil`. The result is wrapped in a unit which is null if the decoding failed.

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 `(unit [n])` where `[n]` is a tuple containing items of the same type and in the same order as those produced by the `+fist`s in `wil`. The `+unit` is null if decoding failed.

#### Source

```hoon
++  at
  |*  wil=(pole fist)
  |=  jon=json
  ?.  ?=([%a *] jon)  ~
  ?.  =((lent wil) (lent p.jon))  ~
  =+  raw=((at-raw wil) p.jon)
  ?.((za raw) ~ (some (zp raw)))
```

#### Examples

```
> ((at ~[so ni bo]):dejs-soft:format a+~[s+'foo' n+'123' b+&])
[~ ['foo' 123 %.y]]
```

```
> ((at ~[so ni bo]):dejs-soft:format a+~[n+'123' s+'foo' b+&])
~
```

***

### `+at-raw:dejs-soft:format` <a href="#at-rawdejs-softformat" id="at-rawdejs-softformat"></a>

Array as tuple, raw (unitized)

This function is used internally by [+at](#atdejs-softformat) and would not typically be used directly.

`+at-raw` converts list `jol` to a new list, decoding each item in the list with the corresponding function in list `wil`. Each item in the list gets wrapped in a unit, and any item whose decoding fails is null.

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 list of the types and in the same order as those produced by the `+fist`s in `wil`. Each item is wrapped in a unit and any item whose decoding fails is null.

#### Source

```hoon
++  at-raw
  |*  wil=(pole fist)
  |=  jol=(list json)
  ?~  wil  ~
  :-  ?~(jol ~ (-.wil i.jol))
  ((at-raw +.wil) ?~(jol ~ t.jol))
```

#### Examples

```
> ((at-raw ~[so ni bo]):dejs-soft:format ~[s+'foo' n+'123' b+&])
[[~ 'foo'] [~ 123] [~ %.y] ~]
```

```
> ((at-raw ~[so ni bo]):dejs-soft:format ~[s+'foo' b+| b+&])
[[~ 'foo'] ~ [~ %.y] ~]
```

***

### `+bo:dejs-soft:format` <a href="#bodejs-softformat" id="bodejs-softformat"></a>

Boolean (in unit)

Convert boolean `jon` to a `?` and wrap the result in a unit. If decoding fails the unit is null.

#### Accepts

`jon` is a `$json` boolean.

#### Produces

A `?` wrapped in a `+unit`. The unit is null if the decoding failed.

#### Source

```hoon
++  bo
  |=(jon=json ?.(?=([%b *] jon) ~ [~ u=p.jon]))
```

#### Examples

```
> (bo:dejs-soft:format b+|)
[~ %.n]
```

```
> (bo:dejs-soft:format n+'123')
~
```

***

### `+bu:dejs-soft:format` <a href="#budejs-softformat" id="budejs-softformat"></a>

Boolean NOT (in unit)

Convert the logical NOT of boolean `jon` to a `?`. The result is wrapped in a unit, if the decoding fails the unit is null.

#### Accepts

`jon` is a `$json` boolean.

#### Produces

A `(unit ?)`. The `+unit` is `~` if the decoding failed.

#### Source

```hoon
++  bu
  |=(jon=json ?.(?=([%b *] jon) ~ [~ u=!p.jon]))
```

#### Examples

```
> (bu:dejs-soft:format b+&)
[~ %.n]
```

```
> (bu:dejs-soft:format n+'123')
~
```

***

### `+ci:dejs-soft:format` <a href="#cidejs-softformat" id="cidejs-softformat"></a>

Maybe transform (in unit)

Decode `jon` with `wit`, then transform it with gate `poq` which produces a unit. If the unit is null or the decoding fails it produces `~`, otherwise it produces the unit.

The `+ci` function is a wet gate that takes a `poq` and `wit` and produces a new gate that takes `jon`.

#### Accepts

The wet gate takes `[poq wit]`, where `poq` is a `$gate` that produces a `+unit` 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

Produces `(unit [type])`, where `[type]` is the type of the data in the `+unit` produced by `poq`. The `+unit` is `~` if the decoding failed or if the `+unit` produced by `poq` is `~`.

#### Source

```hoon
++  ci
  |*  [poq=gate wit=fist]
  |=  jon=json
  (biff (wit jon) poq)
```

#### Examples

```
> ((ci |=(a=? ?:(=(a &) `'foo' ~)) bo):dejs-soft:format b+&)
[~ 'foo']
```

```
> ((ci |=(a=? ?:(=(a &) `'foo' ~)) bo):dejs-soft:format b+|)
~
```

```
> ((ci |=(a=? ?:(=(a &) `'foo' ~)) bo):dejs-soft:format n+'123')
~
```

***

### `+cu:dejs-soft:format` <a href="#cudejs-softformat" id="cudejs-softformat"></a>

Transform (in unit)

Decode `jon` with `wit`, then transform it with gate `poq`. The result is wrapped in a unit, which is null if the decoding failed.

The `+cu` function is a wet gate that takes `poq` and `wit` and produces a new gate that takes `jon`.

#### Accepts

The wet gate takes `[poq wit]`, where `poq` is a `$gate` and `wit` is a `+fist`.

`jon` is `$json` of the kind handled by `wit`. `jon` is the sample of the gate produced by the wet gate.

#### Produces

`(unit [type])`, where `[type]` is the type produced by the gate given in `poq`. The `+unit` is `~` if the decoding failed.

#### Source

```hoon
++  cu
  |*  [poq=gate wit=fist]
  |=  jon=json
  (bind (wit jon) poq)
```

#### Examples

```
> ((cu |=(a=? ?:(=(a &) 'foo' ~)) bo):dejs-soft:format b+&)
[~ 'foo']
```

```
> ((cu |=(a=? ?:(=(a &) 'foo' ~)) bo):dejs-soft:format b+|)
[~ ~]
```

```
> ((cu |=(a=? ?:(=(a &) 'foo' ~)) bo):dejs-soft:format n+'123')
~
```

***

### `+da:dejs-soft:format` <a href="#dadejs-softformat" id="dadejs-softformat"></a>

UTC date (in unit)

Convert string `jon` to a `@da`, parsing it as a UTC date & time string, e.g.`'Thu, 09 Sep 2021 05:58:52'`. Note the inclusion of a timezone offset like `+1200` will pass the parser but will be ignored. The result is wrapped in a unit, which is null if decoding or parsing failed.

#### Accepts

`jon` is a `$json` string encoding a UTC date & time string.

#### Produces

A `@da`.

#### Examples

```
> (da:dejs-soft:format s+'Thu, 09 Sep 2021 05:58:52')
[~ ~2021.9.9..05.58.52]
```

```
> (da:dejs-soft:format s+'09 Sep 2021 05:58:52')
[~ ~2021.9.9..05.58.52]
```

```
> (da:dejs-soft:format s+'Thu, 09 Sep 2021 05:58:52 +1200')
[~ ~2021.9.9..05.58.52]
```

```
> (da:dejs-soft:format s+'gkjeagkja')
~
```

```
> (da:dejs-soft:format b+&)
~
```

***

### `+dank:dejs-soft:format` <a href="#dankdejs-softformat" id="dankdejs-softformat"></a>

Tank (in unit)

Convert `jon`, a `$json`-encoded `$tank`, to a `$tank`. The result is wrapped in a unit and is null if decoding failed.

#### Accepts

`jon` is `$json`.

#### Produces

A `(unit tank)`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  dank
  ^-  $-(json (unit tank))
  %+  re  *tank  |.  ~+
  %-  of  :~
    leaf+sa
    palm+(ot style+(ot mid+sa cap+sa open+sa close+sa ~) lines+(ar dank) ~)
    rose+(ot style+(ot mid+sa open+sa close+sa ~) lines+(ar dank) ~)
  ==
```

#### Examples

```
> =js-txt '{"rose":{"lines":[{"leaf":"foo"},{"leaf":"bar"},{"leaf":"baz"}],"style":{"mid":" ","close":"]","open":"["}}}'
> (dank:dejs-soft:format (need (de:json:html js-txt)))
[~ [%rose p=[p=" " q="[" r="]"] q=~[[%leaf p="foo"] [%leaf p="bar"] [%leaf p="baz"]]]]
> ~(ram re (need (dank:dejs-soft:format (need (de:json:html js-txt)))))
"[foo bar baz]"
```

```
> (dank:dejs-soft:format (need (de:json:html '{"leaf":"foo"}')))
[~ [%leaf p="foo"]]
> ~(ram re (need (dank:dejs-soft:format (need (de:json:html '{"leaf":"foo"}')))))
"foo"
```

```
> (dank:dejs-soft:format n+'123')
~
```

***

### `+di:dejs-soft:format` <a href="#didejs-softformat" id="didejs-softformat"></a>

Millisecond date (in unit)

Convert number `jon` containing milliseconds to a date. The result is wrapped in a unit which is null if decoding failed.

#### Accepts

`jon` is a `$json` number.

#### Produces

A `(unit @da)`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  di
  (cu from-unix-ms:chrono:userlib ni)
```

#### Examples

```
> =time (time:enjs:format now)
> time
[%n p=~.1631177855330]
> (di:dejs-soft:format time)
[~ ~2021.9.9..08.57.35..547a.e147.ae14.7ae1]
```

```
> (di:dejs-soft:format b+&)
~
```

***

### `+mu:dejs-soft:format` <a href="#mudejs-softformat" id="mudejs-softformat"></a>

True unit (in unit)

Decode `jon` with `wit`, then wrap it in two units. The inner unit is null if `jon` was null, the outer unit is null if decoding failed.

The `+mu` function is a wet gate that takes `wit` and produces a gate which takes `jon`.

#### Accepts

`wit` is a `+fist`, and is the sample of the wet gate.

`jon` is `$json` of the kind `wit` handles. `jon` is the sample of the gate produced by the wet gate.

#### Produces

A `(unit (unit [type]))`, where `[type]` is the type produced by `wit`. The inner `+unit` is `~` if `jon` was null, the outer `+unit` is `~` if decoding failed.

#### Source

```hoon
++  mu
  |*  wit=fist
  |=  jon=json
  ?~(jon (some ~) (bind (wit jon) some))
```

#### Examples

```
> ((mu so):dejs-soft:format s+'foo')
[~ [~ u='foo']]
```

```
> ((mu so):dejs-soft:format ~)
[~ u=~]
```

```
> ((mu so):dejs-soft:format b+&)
~
```

***

### `+ne:dejs-soft:format` <a href="#nedejs-softformat" id="nedejs-softformat"></a>

Number as real (in unit)

Convert number `jon` to a `@rd` and wrap the result in a unit. The unit is null if decoding failed.

#### Accepts

`jon` is a `$json` number.

#### Produces

A `(unit @rd)`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  ne
  |=  jon=json
  ^-  (unit @rd)
  ?.  ?=([%n *] jon)  ~
  (rush p.jon (cook ryld (cook royl-cell:^so json-rn)))
```

#### Examples

```
> (ne:dejs-soft:format n+'123')
[~ .~123]
```

```
> (ne:dejs-soft:format n+'2.47')
[~ .~2.47]
```

```
> (ne:dejs-soft:format b+&)
~
```

***

### `+ni:dejs-soft:format` <a href="#nidejs-softformat" id="nidejs-softformat"></a>

Number as integer (in unit)

Convert number `jon` to a `@ud` and wrap it in a unit. If `jon` is not an integer or if decoding otherwise failed, the unit is null.

#### Accepts

`jon` is a `$json` number.

#### Produces

A `(unit @ud)`. The `+unit` is `~` if `jon` was not an integer or if decoding otherwise failed.

#### Source

```hoon
++  ni
  |=  jon=json
  ?.  ?=([%n *] jon)  ~
  (rush p.jon dem)
```

#### Examples

```
> (ni:dejs-soft:format n+'123')
[~ 123]
```

```
> (ni:dejs-soft:format n+'2.47')
~
```

```
> (ni:dejs-soft:format b+&)
~
```

***

### `+no:dejs-soft:format` <a href="#nodejs-softformat" id="nodejs-softformat"></a>

Number as knot (in unit)

Convert number `jon` to a `@ta` and wrap it in a unit. The result is null if decoding failed.

#### Accepts

`jon` is a `$json` number.

#### Produces

A `(unit @ta)`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  no
  |=  jon=json
  ?.  ?=([%n *] jon)  ~
  (some p.jon)
```

#### Examples

```
> (no:dejs-soft:format n+'2.47')
[~ ~.2.47]
```

```
> (no:dejs-soft:format n+'123')
[~ ~.123]
```

```
> (no:dejs-soft:format b+&)
~
```

***

### `+of:dejs-soft:format` <a href="#ofdejs-softformat" id="ofdejs-softformat"></a>

Object as frond (in unit)

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 result is wrapped in a unit which is null if the key couldn't be found in `wer` or if the decoding failed.

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 `(unit [@t [type]])` where `[type]` is the type produced by the matching `+fist`. The `+unit` is `~` if decoding failed or the key could not be found.

#### Source

```hoon
++  of
  |*  wer=(pole [cord fist])
  |=  jon=json
  ?.  ?=([%o [@ *] ~ ~] jon)  ~
  |-
  ?~  wer  ~
  ?:  =(-.-.wer p.n.p.jon)
    ((pe -.-.wer +.-.wer) q.n.p.jon)
  ((of +.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-soft:format obj-1)
[~ [%foo 'hello']]
```

```
> ((of ~[foo+so bar+(ar ni)]):dejs-soft:format obj-2)
[~ [%bar [i=123 t=~[456]]]]
```

```
> ((of ~[foo+so bar+(ar ni)]):dejs-soft:format obj-3)
~
```

```
> ((of ~[foo+so bar+(ar ni)]):dejs-soft:format b+&)
~
```

***

### `+ot:dejs-soft:format` <a href="#otdejs-softformat" id="otdejs-softformat"></a>

Object as tuple (in unit)

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 result is wrapped in a unit which is null if decoding failed.

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 `(unit [tuple])` where the type of each item in `[tuple]` is the product of the corresponding `+fist` in `wer`. The order of items in the tuple will match the order of items in `wer`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  ot
  |*  wer=(pole [cord fist])
  |=  jon=json
  ?.  ?=([%o *] jon)  ~
  =+  raw=((ot-raw wer) p.jon)
  ?.((za raw) ~ (some (zp raw)))
```

#### Examples

```
> %-  (ot ~[foo+so bar+ni]):dejs-soft:format
  o+(malt (limo ~[['bar' n+'123'] ['foo' s+'hello'] ['baz' b+&]]))
[~ ['hello' 123]]
```

```
> %-  (ot ~[foo+so bar+ni]):dejs-soft:format
  o+(malt (limo ~[['bar' n+'123'] ['baz' b+&]]))
~
```

***

### `+ot-raw:dejs-soft:format` <a href="#ot-rawdejs-softformat" id="ot-rawdejs-softformat"></a>

Object as list of units, raw

This function is used internally by [+ot](#otdejs-softformat) and would not typically be used directly.

`+ot-raw` converts map `jom` to a list of units by decoding each value with the matching `+fist` in `wer`, then wrapping them in a unit. Any key in `wer` which cannot be matched to a key in `jon` is null in the resulting list. If there are keys in `jom` 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 `(list (unit))`, where the type of the data in each `+unit` is the product of the corresponding `+fist` in `wer`. The order of items in the list will match the order of items in `wer`. Any keys in `wer` which couldn't be matched will be `~` in the resulting list.

#### Source

```hoon
++  ot-raw
  |*  wer=(pole [cord fist])
  |=  jom=(map @t json)
  ?~  wer  ~
  =+  ten=(~(get by jom) -.-.wer)
  [?~(ten ~ (+.-.wer u.ten)) ((ot-raw +.wer) jom)]
```

#### Examples

```
> %-  (ot-raw ~[foo+so bar+ni]):dejs-soft:format
  (malt (limo ~[['bar' n+'123'] ['foo' s+'hello'] ['baz' b+&]]))
[[~ 'hello'] [~ 123] ~]
```

```
> %-  (ot-raw ~[foo+so bar+ni]):dejs-soft:format
  (malt (limo ~[['bar' n+'123'] ['baz' b+&]]))
[~ [~ 123] ~]
```

***

### `+om:dejs-soft:format` <a href="#omdejs-softformat" id="omdejs-softformat"></a>

Object as map (in unit)

Convert object `jon` to a map, decoding each value with `wit`. The result is wrapped in a unit which is null if decoding failed.

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 `(unit (map @t [type]))`, where `[type]` is the type produced by `wit`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  om
  |*  wit=fist
  |=  jon=json
  ?.  ?=([%o *] jon)  ~
  (zm (~(run by p.jon) wit))
```

#### Examples

```
> =jon (need (de:json:html '{"foo":"aaa","bar":"bbb"}'))
> ((om so):dejs-soft:format jon)
[~ {[p='bar' q='bbb'] [p='foo' q='aaa']}]
```

```
> ((om so):dejs-soft:format b+&)
~
```

***

### `+op:dejs-soft:format` <a href="#opdejs-softformat" id="opdejs-softformat"></a>

Parse keys of map (in unit)

Convert object `jon` to a map, parsing each key with `fel` and decoding each value with `wit`. The result is wrapped in a unit which is null if decoding or parsing failed.

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 `(unit (map [a] [b]))` where `[a]` is the type produced by `fel` and `[b]` is the type produced by `wit`. The `+unit` is `~` if decoding or parsing failed.

#### 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-soft:format jon)
[~ u={[p=456 q='bbb'] [p=123 q='aaa']}]
```

***

### `+pe:dejs-soft:format` <a href="#pedejs-softformat" id="pedejs-softformat"></a>

Prefix (in unit)

Decode `jon` with `wit`, prefix it with `pre`, then wrap the result in a unit which is null if decoding failed.

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 `(unit [[a] [b]])`, where `[a]` is the noun given in `pre` and `[b]` is the type produced by `wit`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  pe
  |*  [pre=* wit=fist]
  (cu |*(* [pre +<]) wit)
```

#### Examples

```
> ((pe %foo so):dejs-soft:format s+'abc')
[~ [%foo 'abc']]
```

```
> ((pe %foo so):dejs-soft:format b+&)
~
```

***

### `+re:dejs-soft:format` <a href="#redejs-softformat" id="redejs-softformat"></a>

Recursive reparser

This function facilitates recursion in other `+fist`s. It is used internally by some functions and would not typically be used directly. `jon` is decoded by the `+fist` in the trap `sef` and cast to the type of the noun given in `gar`. The result is wrapped in a unit which is null if decoding failed.

`+re` is a wet gate that takes a cell of `gar` and `sef`, and produces a gate which takes `jon`.

#### Accepts

`gar` is any `$noun`, its type determines the return type.

`sef` is a `|.(fist)`.

The wet gate takes `[gar sef]`.

`jon` is `$json` of the kind handled by the `+fist` in `sef`, and is the sample of the gate produced by the wet gate.

#### Produces

A `(unit [type])` where `[type]` is the type of `gar`.

#### Source

```hoon
++  re
  |*  [gar=* sef=_|.(fist)]
  |=  jon=json
  ^-  (unit _gar)
  ((sef) jon)
```

#### Examples

The basic format looks like so:

```
> ((re *@t |.(so)):dejs-soft:format s+'abc')
[~ 'abc']
```

```
> ((re *@t |.(so)):dejs-soft:format b+&)
~
```

For a recursive example, see its usage in the source of [+dank](#dankdejs-softformat).

***

### `+sa:dejs-soft:format` <a href="#sadejs-softformat" id="sadejs-softformat"></a>

String as tape (in unit)

Convert `jon` to a `$tape` and wrap the result in a unit, which is null if the decoding failed.

#### Accepts

`jon` is a `$json` string.

#### Produces

A `(unit tape)`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  sa
  |=  jon=json
  ?.(?=([%s *] jon) ~ (some (trip p.jon)))
```

#### Examples

```
> (sa:dejs-soft:format s+'foo')
[~ "foo"]
```

```
> (sa:dejs-soft:format b+&)
~
```

***

### `+so:dejs-soft:format` <a href="#sodejs-softformat" id="sodejs-softformat"></a>

String as cord (in unit)

Convert `jon` to a cord and wrap it in a unit. The unit is null if decoding failed.

#### Accepts

`jon` is a `$json` string.

#### Produces

A `(unit @t)`. The `+unit` is `~` if decoding failed.

#### Source

```hoon
++  so
  |=  jon=json
  ?.(?=([%s *] jon) ~ (some p.jon))
```

#### Examples

```
> (so:dejs-soft:format s+'foo')
[~ 'foo']
```

```
> (so:dejs-soft:format b+&)
~
```

***

### `+su:dejs-soft:format` <a href="#sudejs-softformat" id="sudejs-softformat"></a>

Parse string (in unit)

Convert and parse `jon` with `sab`, then wrap the result in a unit. The unit is null if parsing or decoding failed.

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

A `(unit [type])`, where `[type]` is the type produced by `sab`.

#### Source

```hoon
++  su
  |*  sab=rule
  |=  jon=json
  ?.  ?=([%s *] jon)  ~
  (rush p.jon sab)
```

#### Examples

```
> ((su dem):dejs-soft:format s+'123456')
[~ 123.456]
```

```
> `(unit @ub)`((su bin):dejs-soft:format s+'00001011101110001101')
[~ 0b1011.1011.1000.1101]
```

```
> ((su dem):dejs-soft:format s+'abc')
~
```

```
> ((su dem):dejs-soft:format b+&)
~
```

***

### `+ul:dejs-soft:format` <a href="#uldejs-softformat" id="uldejs-softformat"></a>

Null (in unit)

Return `[~ ~]` if `jon` is null or else return `~`.

#### Accepts

`jon` is null `$json`.

#### Produces

A `(unit ~)`. The `+unit` is `~` if `jon` is not `~`.

#### Source

```hoon
++  ul  |=(jon=json ?~(jon (some ~) ~))
```

#### Examples

```
> (ul:dejs-soft:format ~)
[~ ~]
```

```
> (ul:dejs-soft:format b+&)
~
```

### `+za:dejs-soft:format` <a href="#zadejs-softformat" id="zadejs-softformat"></a>

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-soft:format ~[`1 `2 `3 `4])
%.y
```

```
> (za:dejs-soft:format ~)
%.y
```

```
> (za:dejs-soft:format ~[`1 `2 ~ `4])
%.n
```

***

### `+zl:dejs-soft:format` <a href="#zldejs-softformat" id="zldejs-softformat"></a>

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-soft:format (limo ~[`1 `2 `3 `4 `5 `6]))
[~ [i=1 t=~[2 3 4 5 6]]]
```

```
> (zl:dejs-soft:format (limo ~[`1 `2 ~ `4 `5 `6]))
~
```

***

### `+zp:dejs-soft:format` <a href="#zpdejs-softformat" id="zpdejs-softformat"></a>

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-soft:format ~[`1 `2 `3 `4 `5 `6])
[1 2 3 4 5 6]
```

```
> (zp:dejs-soft:format ~[`1 `2 ~ `4 `5 `6])
mull-none
dojo: hoon expression failed
```

***

### `+zm:dejs-soft:format` <a href="#zmdejs-softformat" id="zmdejs-softformat"></a>

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-soft:format (malt ~[['foo' `1] ['bar' `2]]))
[~ {[p='bar' q=2] [p='foo' q=1]}]
```

```
> (zm:dejs-soft:format (malt (limo ~[['foo' `1] ['bar' ~]])))
~
```