docs

Author: sinclairzx81

readme.md

@@ -73,8 +73,8 @@ License: MIT
   - [Epsilon](#Epsilon)
 - [Tokens](#Tokens)
   - [Ident](#Ident)
-  - [BigInt](#BigInt)
   - [Integer](#Integer)
+  - [BigInt](#BigInt)
   - [Number](#Number)
   - [String](#String)
 - [Mapping](#Mapping)
@@ -237,11 +237,68 @@ const R2 = Runtime.Parse(T, 'Y Z')                  // const R2 = [[], 'Y Z']
 
 ## Tokens
 
-ParseBox provides combinators for parsing common lexical tokens, such as numbers, identifiers, and strings, enabling static, optimized parsing of typical JavaScript constructs.
+ParseBox includes several specialized combinators used to quickly parse common language tokens.
+
+### Ident
+
+Parses an identifier
+
+```typescript
+const Expression = Runtime.Number()                 //  const Expression = { type: 'Number' }
+
+const Let = Runtime.Tuple([                         //  const Let = {
+  Runtime.Const('let'),                             //    type: 'Tuple',
+  Runtime.Ident(),                                  //    parsers: [
+  Runtime.Const('='),                               //      { type: 'Const', value: 'let' },
+  Expression                                        //      { type: 'Ident' },
+])                                                  //      { type: 'Const', value: '=' },
+                                                    //      { type: 'Number' },
+                                                    //    ]
+                                                    //  }
+
+const R = Runtime.Parse(Let, 'let n = 10')          // const R = [[ 'let', 'n', '=', '10'], '' ]
+
+```
+
+### Integer
+
+Parses a literal integer
+
+```typescript
+const T = Runtime.Integer()
+
+// ...
+
+const R1 = Runtime.Parse(T, '1')                    // const R1 = ['1', '']
+
+const R2 = Runtime.Parse(T, '3.14')                 // const R2 = ['3', '.14']
+
+const R3 = Runtime.Parse(T, '.1')                   // const R3 = []
+
+const E = Runtime.Parse(T, '01')                    // const E = ['0', '1']
+```
+
+### BigInt
+
+Parses a literal bigint number. This combinator will succeed if the number is integer and trailed by a `n`. The `n` is omitted from the result.
+
+```typescript
+const T = Runtime.BigInt()
+
+// ...
+
+const R1 = Runtime.Parse(T, '1n')                    // const R1 = ['1', '']
+
+const R2 = Runtime.Parse(T, '1n2')                   // const R2 = ['1', '2']
+
+const R3 = Runtime.Parse(T, '.1n')                   // const R3 = []
+
+const E = Runtime.Parse(T, '01n')                    // const E = []
+```
 
 ### Number
 
-Parses numeric literals, including integers, decimals, and floating-point numbers. Invalid formats, like leading zeroes, are not matched.
+Parses a number with fractional parts
 
 ```typescript
 const T = Runtime.Number()
@@ -254,7 +311,7 @@ const R2 = Runtime.Parse(T, '3.14')                 // const R2 = ['3.14', '']
 
 const R3 = Runtime.Parse(T, '.1')                   // const R3 = ['.1', '']
 
-const E = Runtime.Parse(T, '01')                    // const E = []
+const E = Runtime.Parse(T, '01')                    // const E = ['0', '1']
 ```
 
 ### String
@@ -269,30 +326,7 @@ const T = Runtime.String(['"'])
 const R = Runtime.Parse(T, '"hello"')              // const R = ['hello', '']
 ```
 
-### Ident
-
-Parses valid JavaScript identifiers, typically used to extract variable or function names. The following example demonstrates parsing a `let` statement.
-
-```bnf
-<let> ::= "let" <ident> "=" <number>
-```
 
-```typescript
-const Expression = Runtime.Number()                 //  const Expression = { type: 'Number' }
-
-const Let = Runtime.Tuple([                         //  const Let = {
-  Runtime.Const('let'),                             //    type: 'Tuple',
-  Runtime.Ident(),                                  //    parsers: [
-  Runtime.Const('='),                               //      { type: 'Const', value: 'let' },
-  Expression                                        //      { type: 'Ident' },
-])                                                  //      { type: 'Const', value: '=' },
-                                                    //      { type: 'Number' },
-                                                    //    ]
-                                                    //  }
-
-const R = Runtime.Parse(Let, 'let n = 10')          // const R = [[ 'let', 'n', '=', '10'], '' ]
-
-```
 
 
 ## Mapping