docs: document typed paths ($pith, $iota, +pave, +pout, +stip)

content/hoon/stdlib/4m.md

@@ -15,6 +15,76 @@ layout:
 
 # 4m: Formatting Functions
 
+## `+pave` {#pave}
+
+Parse `$path` to [`$pith`](4o.md#pith).
+
+Parses each segment of a `$path` into a typed [`$iota`](4o.md#iota). A segment that does not parse as any recognised aura is kept as `[%ta segment]`.
+
+#### Accepts
+
+`.path` is a `$path`.
+
+#### Produces
+
+A [`$pith`](4o.md#pith).
+
+#### Source
+
+```hoon
+++  pave
+  |=  =path
+  ^-  pith
+  %+  turn  path
+  |=  i=@ta
+  (fall (rush i spot:stip) [%ta i])
+```
+
+#### Examples
+
+```
+> (pave /foo/123/0xdead)
+~[%foo [%ud 123] [%ux 0xdead]]
+```
+
+Note that a cast does not do this — `` `pith`/foo/123 `` produces `~[%foo %123]`, leaving the segments as bare `@tas`.
+
+---
+
+## `+pout` {#pout}
+
+Render [`$pith`](4o.md#pith) to `$path`.
+
+The inverse of [`+pave`](#pave): renders each [`$iota`](4o.md#iota) back to a `@ta` segment with [`+scot`](#scot).
+
+#### Accepts
+
+`.pith` is a [`$pith`](4o.md#pith).
+
+#### Produces
+
+A `$path`.
+
+#### Source
+
+```hoon
+++  pout
+  |=  =pith
+  ^-  path
+  %+  turn  pith
+  |=  i=iota
+  ?@(i i (scot i))
+```
+
+#### Examples
+
+```
+> (pout (pave /foo/123/0xdead))
+/foo/123/0xdead
+```
+
+---
+
 ## `+scot` {#scot}
 
 Render `$dime` as `$cord`.
@@ -527,6 +597,51 @@ A `$path`, or crash.
 
 ---
 
+## `+stip` {#stip}
+
+Typed path parser.
+
+A parser core for [`$pith`](4o.md#pith)s. Used by [`+pave`](#pave).
+
+#### Source
+
+```hoon
+++  stip
+  =<  swot
+  |%
+  ++  swot  |=(n=nail (;~(pfix fas (more fas spot)) n))
+  ::
+  ++  spot
+    %+  sear  (soft iota)
+```
+
+The core reduces to `+swot`, so `+stip` used directly parses a whole path.
+
+### `+spot:stip` {#spotstip}
+
+Parses a single path segment into an [`$iota`](4o.md#iota).
+
+```
+> (rash '123' spot:stip)
+[%ud 123]
+```
+
+```
+> (rash '0xdead' spot:stip)
+[%ux 0xdead]
+```
+
+### `+swot:stip` {#swotstip}
+
+Parses a whole `/`-separated path into a [`$pith`](4o.md#pith).
+
+```
+> (rash '/foo/123' swot:stip)
+[%foo [i=[%ud 123] t=~]]
+```
+
+---
+
 ## `+stap` {#stap}
 
 Path parser.

content/hoon/stdlib/4o.md

@@ -99,6 +99,76 @@ See also: [`$base`](#base), aura reference
 
 ---
 
+## `$iota` {#iota}
+
+Typed path segment.
+
+A single segment of a [`$pith`](#pith). Either a bare `@tas`, or a tagged pair naming the aura of the value it holds.
+
+#### Source
+
+```hoon
++$  iota
+  $+  iota
+  $~  [%n ~]
+  $@  @tas
+  $%  [%ub @ub]  [%uc @uc]  [%ud @ud]  [%ui @ui]
+      [%ux @ux]  [%uv @uv]  [%uw @uw]
+      [%sb @sb]  [%sc @sc]  [%sd @sd]  [%si @si]
+      [%sx @sx]  [%sv @sv]  [%sw @sw]
+      [%da @da]  [%dr @dr]
+      [%f ?]     [%n ~]
+      [%if @if]  [%is @is]
+      [%t @t]    [%ta @ta]
+      [%p @p]    [%q @q]
+      [%rs @rs]  [%rd @rd]  [%rh @rh]  [%rq @rq]
+  ==
+```
+
+#### Examples
+
+```
+> (rash '123' spot:stip)
+[%ud 123]
+```
+
+```
+> (rash '0xdead' spot:stip)
+[%ux 0xdead]
+```
+
+---
+
+## `$pith` {#pith}
+
+Typed Urbit path.
+
+A `$pith` is a `(list iota)` — a path whose segments carry their aura, rather than being flattened to `@ta` as in an ordinary `$path`.
+
+#### Source
+
+```hoon
++$  pith  (list iota)
+```
+
+#### Examples
+
+```
+> (pave /foo/123/0xdead)
+~[%foo [%ud 123] [%ux 0xdead]]
+```
+
+Note that **casting a `$path` to a `$pith` does not parse the segments** — it merely retypes them as bare `@tas`:
+
+```
+> `pith`/foo/123
+~[%foo %123]
+```
+
+Use [`+pave`](4m.md#pave) to actually parse a `$path` into a `$pith`.
+
+---
+
 ## `$base` {#base}
 
 Base type.