# 4i: Parsing (Useful Idioms)

## `+alf` <a href="#alf" id="alf"></a>

Alphabetic characters.

Parse alphabetic characters, both upper and lowercase.

#### Source

```hoon
++  alf  ;~(pose low hig)
```

#### Examples

```
> (scan "a" alf)
'a'
```

```
> (scan "A" alf)
'A'
```

```
> `tape`(scan "AaBbCc" (star alf))
"AaBbCc"
```

***

## `+aln` <a href="#aln" id="aln"></a>

Alphanumeric characters.

Parse alphanumeric characters - both alphabetic characters and numbers.

#### Source

```hoon
++  aln  ;~(pose low hig nud)
```

#### Examples

```
> (scan "0" aln)
'0'
```

```
> `tape`(scan "alf42" (star aln))
"alf42"
```

***

## `+alp` <a href="#alp" id="alp"></a>

Alphanumeric and `-`.

Parse alphanumeric strings and hep, `-`.

#### Source

```hoon
++  alp  ;~(pose low hig nud hep)
```

#### Examples

```
> (scan "7" alp)
'7'
```

```
> (scan "s" alp)
's'
```

```
> `tape`(scan "123abc-" (star alp))
"123abc-"
```

***

## `+bet` <a href="#bet" id="bet"></a>

Axis syntax `-`, `+`.

Parse the hep and lus axis syntax.

#### Source

```hoon
++  bet  ;~(pose (cold 2 hep) (cold 3 lus))
```

#### Examples

```
> (scan "-" bet)
2
```

```
> (scan "+" bet)
3
```

***

## `+bin` <a href="#bin" id="bin"></a>

Binary to `$atom`.

Parse a tape of binary (`0`s and `1`s) and produce its atomic representation.

#### Source

```hoon
++  bin  (bass 2 (most gon but))
```

#### Examples

```
> (scan "0000" bin)
0
```

```
> (scan "0001" bin)
1
```

```
> (scan "0010" bin)
2
```

```
> (scan "100000001111" bin)
2.063
```

***

## `+but` <a href="#but" id="but"></a>

Binary digit.

Parse a single binary digit.

#### Source

```hoon
++  but  (cook |=(a=@ (sub a '0')) (shim '0' '1'))
```

#### Examples

```
> (scan "0" but)
0
```

```
> (scan "1" but)
1
```

```
> (scan "01" but)
! {1 2}
! 'syntax-error'
! exit
```

```
> (scan "01" (star but))
~[0 1]
```

***

## `+cit` <a href="#cit" id="cit"></a>

Octal digit.

Parse a single octal digit.

#### Source

```hoon
++  cit  (cook |=(a=@ (sub a '0')) (shim '0' '7'))
```

#### Examples

```
> (scan "1" cit)
1
```

```
> (scan "7" cit)
7
```

```
> (scan "8" cit)
! {1 1}
! 'syntax-error'
! exit
```

```
> (scan "60" (star cit))
~[6 0]
```

***

## `+dem` <a href="#dem" id="dem"></a>

Decimal to `$atom`.

Parse a decimal number to an `$atom`.

#### Source

```hoon
++  dem  (bass 10 (most gon dit))
```

#### Examples

```
> (scan "7" dem)
7
```

```
> (scan "42" dem)
42
```

```
> (scan "150000000" dem)
150.000.000
```

```
> (scan "12456" dem)
12.456
```

***

## `+dit` <a href="#dit" id="dit"></a>

Decimal digit.

Parse a single decimal digit.

#### Source

```hoon
++  dit  (cook |=(a=@ (sub a '0')) (shim '0' '9'))
```

#### Examples

```
> (scan "7" dit)
7
```

```
> (scan "42" (star dit))
~[4 2]
```

```
> (scan "26000" (star dit))
~[2 6 0 0 0]
```

***

## `+dog` <a href="#dog" id="dog"></a>

`.` optional gap.

Dot followed by an optional gap, used with numbers.

#### Source

```hoon
++  dog  ;~(plug dot gay)
```

#### Examples

```
> (scan "." dog)
['.' ~]
```

```
> (scan "a.        " ;~(pfix alf dog))
['.' ~]
```

***

## `+dof` <a href="#dof" id="dof"></a>

`-` optional gap.

Hep followed by an optional gap, used with `@p` & `@q` syntax.

#### Source

```hoon
++  dof  ;~(plug hep gay)
```

#### Examples

```
> (scan "-" dof)
['-' ~]
```

```
> (scan "-     " dof)
['-' ~]
```

***

## `+doh` <a href="#doh" id="doh"></a>

`@p` separator.

Phonetic base phrase separator

#### Source

```hoon
++  doh  ;~(plug ;~(plug hep hep) gay)
```

#### Examples

```
> (scan "--" doh)
[['-' '-'] ~]
```

```
> (scan "--     " doh)
[['-' '-'] ~]
```

***

## `+dun` <a href="#dun" id="dun"></a>

`--` to `~`.

Parse phep, `--`, to null, `~`.

#### Source

```hoon
++  dun  (cold ~ ;~(plug hep hep))
```

#### Examples

```
> (scan "--" dun)
~
```

***

## `+duz` <a href="#duz" id="duz"></a>

`==` to `~`.

Parse stet, `==`, to null `~`.

#### Source

```hoon
++  duz  (cold ~ ;~(plug tis tis))
```

#### Examples

```
> (scan "==" duz)
~
```

***

## `+gah` <a href="#gah" id="gah"></a>

Newline or ' '.

Whitespace component, either newline or space.

#### Source

```hoon
++  gah  (mask [`@`10 ' ' ~])
```

#### Examples

```
> `tape`(scan " \0a \0a" (star gah))
" \0a \0a"
```

***

## `+gap` <a href="#gap" id="gap"></a>

Plural whitespace.

Separates tall runes.

#### Source

```hoon
++  gap  (cold ~ ;~(plug gaq (star ;~(pose vul gah))))
```

#### Examples

```
> `tape`(scan " \0a \0a" gap)
""
```

```
> (scan "\0a   \0a XYZ" ;~(pfix gap (jest 'XYZ')))
'XYZ'
```

***

## `+gaq` <a href="#gaq" id="gaq"></a>

End of line.

Two spaces, a newline, or comment.

#### Source

```hoon
++  gaq  ;~  pose
             (just `@`10)
             ;~(plug gah ;~(pose gah vul))
             vul
         ==
```

#### Examples

```
> (scan "123\0a" ;~(sfix dem gaq))
123
```

```
> (scan "123 :: foo\0a" ;~(sfix dem gaq))
123
```

***

## `+gaw` <a href="#gaw" id="gaw"></a>

Normal whitespace.

#### Source

```hoon
++  gaw  (cold ~ (star ;~(pose vul gah)))
```

#### Examples

```
> (scan "  \0a  :: foo  \0a" gaw)
~
```

```
> (scan "  " gaw)
~
```

```
> (scan "\0a" gaw)
~
```

***

## `+gay` <a href="#gay" id="gay"></a>

Optional gap.

#### Source

```hoon
++  gay  ;~(pose gap (easy ~))
```

#### Examples

```
> (scan "  " gay)
~
```

```
> (scan "     " gay)
~
```

```
> (scan "\0a" gay)
~
```

```
> (scan "" gay)
~
```

***

## `+gon` <a href="#gon" id="gon"></a>

Long numbers.

Parse long numbers - Numbers which wrap around the shell with the line

#### Source

```hoon
++  gon  ;~(pose ;~(plug bas gay fas) (easy ~))
```

#### Examples

```
> 'abc\
  /def'
'abcdef'
```

```
> (scan "\\\0a/" gon)
['\\' ~ '/']
```

***

## `+gul` <a href="#gul" id="gul"></a>

Axis syntax `<` or `>`.

Parse the axis gal and gar axis syntax.

#### Source

```hoon
++  gul  ;~(pose (cold 2 gal) (cold 3 gar))
```

#### Examples

```
> (scan "<" gul)
2
```

```
> (scan ">" gul)
3
```

***

## `+hex` <a href="#hex" id="hex"></a>

Hex to `$atom`.

Parse any hexadecimal number to an `$atom`.

#### Source

```hoon
++  hex  (bass 16 (most gon hit))
```

#### Examples

```
> (scan "a" hex)
10
```

```
> (scan "A" hex)
10
```

```
> (scan "2A" hex)
42
```

```
> (scan "1ee7" hex)
7.911
```

```
> (scan "1EE7" hex)
7.911
```

```
> (scan "1EE7F7" hex)
2.025.463
```

```
> `@ux`(scan "1EE7F7" hex)
0x1e.e7f7
```

***

## `+hig` <a href="#hig" id="hig"></a>

Uppercase.

Parse a single uppercase letter.

#### Source

```hoon
++  hig  (shim 'A' 'Z')
```

#### Examples

```
> (scan "G" hig)
'G'
```

```
> (scan "ABCDEFGHIJKLMNOPQRSTUVWXYZ" (star hig))
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
```

***

## `+hit` <a href="#hit" id="hit"></a>

Hex digits.

Parse a single hexadecimal digit.

#### Source

```hoon
++  hit  ;~  pose
           dit
           (cook |=(a=char (sub a 87)) (shim 'a' 'f'))
           (cook |=(a=char (sub a 55)) (shim 'A' 'F'))
         ==
```

#### Examples

```
> (scan "a" hit)
10
```

```
> (scan "A" hit)
10
```

```
> (scan "2A" (star hit))
~[2 10]
```

***

## `+iny` <a href="#iny" id="iny"></a>

Indentation block.

Apply `$rule` to indented block starting at current column number, omitting the leading whitespace.

#### Accepts

`sef` is a `$rule`

#### Produces

A `$rule`.

#### Source

```hoon
++  iny
  |*  sef=rule
  |=  nail  ^+  (sef)
  =+  [har tap]=[p q]:+<
  =+  lev=(fil 3 (dec q.har) ' ')
  =+  eol=(just `@t`10)
  =+  =-  roq=((star ;~(pose prn ;~(sfix eol (jest lev)) -)) har tap)
      ;~(simu ;~(plug eol eol) eol)
  ?~  q.roq  roq
  =+  vex=(sef har(q 1) p.u.q.roq)
  =+  fur=p.vex(q (add (dec q.har) q.p.vex))
  ?~  q.vex  vex(p fur)
  =-  vex(p fur, u.q -)
  :+  &3.vex
    &4.vex(q.p (add (dec q.har) q.p.&4.vex))
  =+  res=|4.vex
  |-  ?~  res  |4.roq
  ?.  =(10 -.res)  [-.res $(res +.res)]
  (welp [`@t`10 (trip lev)] $(res +.res))
```

#### Examples

```
> `tape`(scan "   foo\0a   bar" ;~(pfix ace ace ace (iny (star ;~(pose prn (just '\0a'))))))
"foo\0abar"
```

#### Discussion

Note the amount of indentation whitespace to be stripped from the beginning of each line is determined by the value of `.q` (the column) in the `$hair` when `+iny` is first called. This means something like the `+pfix` expression in the example above is necessary to set the level of indentation. Additionally, the `$rule` given to `+iny` must consume the whole line including the line ending.

***

## `+low` <a href="#low" id="low"></a>

Lowercase.

Parse a single lowercase letter.

#### Source

```hoon
++  low  (shim 'a' 'z')
```

#### Examples

```
> (scan "g" low)
'g'
```

***

## `+mes` <a href="#mes" id="mes"></a>

Hexbyte.

Parse a hexbyte.

#### Source

```hoon
++  mes  %+  cook
           |=({a/@ b/@} (add (mul 16 a) b))
         ;~(plug hit hit)
```

#### Examples

```
> (scan "2A" mes)
42
```

```
> (scan "42" mes)
66
```

***

## `+nix` <a href="#nix" id="nix"></a>

Letters and underscore.

Parse Letters and `_`.

#### Source

```hoon
++  nix  (boss 256 (star ;~(pose aln cab)))
```

#### Examples

```
> `@t`(scan "as_me" nix)
'as_me'
```

***

## `+nud` <a href="#nud" id="nud"></a>

Numeric.

Parse a numeric character - A number.

#### Source

```hoon
++  nud  (shim '0' '9')
```

#### Examples

```
> (scan "0" nud)
'0'
```

```
> (scan "7" nud)
'7'
```

***

## `+prn` <a href="#prn" id="prn"></a>

Printable character.

Parse any printable character.

#### Source

```hoon
++  prn  ;~(less (just `@`127) (shim 32 256))
```

#### Examples

```
> (scan "h" prn)
'h'
```

```
> (scan "!" prn)
'!'
```

```
> (scan "\01" prn)
! {1 1}
! exit
```

***

## `+qat` <a href="#qat" id="qat"></a>

Chars in blockcord.

Parse a single character contained in a multi-line cord block.

#### Source

```hoon
++  qat  ;~  pose
             prn
             ;~(less ;~(plug (just `@`10) soz) (just `@`10))
         ==
```

#### Examples

```
> ^-  tape
  %+  scan
    "'''\0aabc\0adef\0aghi\0a'''"
  %+  ifix
    :-  ;~(plug soz (just `@`10))
    ;~(plug (just `@`10) soz)
  (star qat)
"abc\0adef\0aghi"
```

***

## `+qit` <a href="#qit" id="qit"></a>

Chars in cord.

Parse an individual character to its cord `$atom` representation. Escaped characters are converted to the value they represent.

#### Source

```hoon
++  qit  ;~  pose                                       ::  chars in a cord
             ;~(less bas soq prn)
             ;~(pfix bas ;~(pose bas soq mes))          ::  escape chars
         ==
```

#### Examples

```
> (scan "%" qit)
'%'
```

```
> `tape`(scan "cord" (star qit))
"cord"
```

```
> `tape`(scan "\\0a" (star qit))
"\0a"
```

***

## `+qut` <a href="#qut" id="qut"></a>

Cord.

Parse single-soq cord with `\{gap}/` anywhere in the middle, or triple-single quote (aka triple-soq) cord, between which must be in an indented block.

#### Source

```hoon
++  qut  ;~  simu  soq
           ;~  pose
             ;~  less  soz
               (ifix [soq soq] (boss 256 (more gon qit)))
             ==
             =+  hed=;~(pose ;~(plug (plus ace) vul) (just '\0a'))
             %-  iny  %+  ifix
               :-  ;~(plug soz hed)
               ;~(plug (just '\0a') soz)
             (boss 256 (star qat))
           ==
         ==
```

#### Examples

```
> `@t`(scan "'cord'" qut)
'cord'
```

```
> `@t`(scan "'''\0aabc\0adef\0a'''" qut)
'abc\0adef'
```

***

## `+soz` <a href="#soz" id="soz"></a>

Delimiting `'''`.

Parse a triple-single quote, used for multiline strings.

#### Source

```hoon
++  soz  ;~(plug soq soq soq)
```

#### Examples

```
> (scan "'''" soz)
['\'' '\'' '\'']
```

***

## `+sym` <a href="#sym" id="sym"></a>

Term.

A term: a lowercase letter, followed by letters, numbers, or `-`.

#### Source

```hoon
++  sym
  %+  cook
    |=(a=tape (rap 3 ^-((list @) a)))
  ;~(plug low (star ;~(pose nud low hep)))
```

#### Examples

```
> `term`(scan "sam-2" sym)
%sam-2
```

***

## `+mixed-case-symbol` <a href="#mixed-case-symbol" id="mixed-case-symbol"></a>

Mixed-case term.

The same as [`+sym`](#sym) but allowing uppercase letters.

#### Source

```hoon
++  mixed-case-symbol
  %+  cook
    |=(a=tape (rap 3 ^-((list @) a)))
  ;~(plug alf (star alp))
```

#### Examples

```
> `term`(scan "sAm-2" mixed-case-symbol)
%sAm-2
```

***

## `+ven` <a href="#ven" id="ven"></a>

`+>-` axis syntax.

Axis syntax parser

#### Source

```hoon
++  ven  ;~  (comp |=([a=@ b=@] (peg a b)))
           bet
           =+  hom=`?`|
           |=  tub=nail
           ^-  (like @)
           =+  vex=?:(hom (bet tub) (gul tub))
           ?~  q.vex
             [p.tub [~ 1 tub]]
           =+  wag=$(p.tub p.vex, hom !hom, tub q.u.q.vex)
           ?>  ?=(^ q.wag)
           [p.wag [~ (peg p.u.q.vex p.u.q.wag) q.u.q.wag]]
         ==
```

#### Examples

```
> (scan "->+" ven)
11
```

```
> (scan "->+<-" ven)
44
```

***

## `+vit` <a href="#vit" id="vit"></a>

Base64 digit.

Parse a standard base64 digit.

#### Source

```hoon
++  vit
  ;~  pose
    (cook |=(a=@ (sub a 65)) (shim 'A' 'Z'))
    (cook |=(a=@ (sub a 71)) (shim 'a' 'z'))
    (cook |=(a=@ (add a 4)) (shim '0' '9'))
    (cold 62 (just '-'))
    (cold 63 (just '+'))
  ==
```

#### Examples

```
> (scan "C" vit)
2
```

```
> (scan "c" vit)
28
```

```
> (scan "2" vit)
54
```

```
> (scan "-" vit)
62
```

***

## `+vul` <a href="#vul" id="vul"></a>

Comments to null.

Parse comments and produce a null. Note that a comment must be ended with a newline character.

#### Source

```hoon
++  vul  %+  cold   ~
         ;~  plug  col  col
           (star prn)
           (just `@`10)
         ==
```

#### Examples

```
> (scan "::this is a comment \0a" vul)
~
```

```
> (scan "::this is a comment " vul)
! {1 21}
! exit
```

***