docs: improve (#68)

callstack · Mar 4, 2024 · f59e6bf · f59e6bf
1 parent a666086
commit f59e6bf
Show file tree

Hide file tree

Showing 10 changed files with 139 additions and 108 deletions.
diff --git a/README.md b/README.md
@@ -102,14 +102,10 @@ See [Builder API doc](https://callstack.github.io/ts-regex-builder/api/builder)
 
 ### Regex Constructs
 
-| Construct                 | Regex Syntax | Notes                                       |
-| ------------------------- | ------------ | ------------------------------------------- |
-| `choiceOf(x, y, z)`       | `x\|y\|z`    | Match one of provided sequences             |
-| `capture(...)`            | `(...)`      | Create a capture group                      |
-| `lookahead(...)`          | `(?=...)`    | Match subsequent text without consuming it  |
-| `negativeLookhead(...)`   | `(?!...)`    | Reject subsequent text without consuming it |
-| `lookbehind(...)`         | `(?<=...)`   | Match preceding text without consuming it   |
-| `negativeLookbehind(...)` | `(?<!...)`   | Reject preceding text without consuming it  |
+| Construct           | Regex Syntax | Notes                           |
+| ------------------- | ------------ | ------------------------------- |
+| `choiceOf(x, y, z)` | `x\|y\|z`    | Match one of provided sequences |
+| `capture(...)`      | `(...)`      | Create a capture group          |
 
 See [Constructs API doc](https://callstack.github.io/ts-regex-builder/api/constructs) for more info.
 
@@ -144,15 +140,20 @@ See [Quantifiers API doc](https://callstack.github.io/ts-regex-builder/api/quant
 
 See [Character Classes API doc](https://callstack.github.io/ts-regex-builder/api/character-classes) for more info.
 
-### Anchors
+### Assertions
 
-| Anchor          | Regex Syntax | Description                                                              |
-| --------------- | ------------ | ------------------------------------------------------------------------ |
-| `startOfString` | `^`          | Match the start of the string (or the start of a line in multiline mode) |
-| `endOfString`   | `$`          | Match the end of the string (or the end of a line in multiline mode)     |
-| `wordBoundary`  | `\b`         | Match the start or end of a word without consuming characters            |
+| Assertion                 | Regex Syntax | Description                                                              |
+| ------------------------- | ------------ | ------------------------------------------------------------------------ |
+| `startOfString`           | `^`          | Match the start of the string (or the start of a line in multiline mode) |
+| `endOfString`             | `$`          | Match the end of the string (or the end of a line in multiline mode)     |
+| `wordBoundary`            | `\b`         | Match the start or end of a word without consuming characters            |
+| `lookahead(...)`          | `(?=...)`    | Match subsequent text without consuming it                               |
+| `negativeLookhead(...)`   | `(?!...)`    | Reject subsequent text without consuming it                              |
+| `lookbehind(...)`         | `(?<=...)`   | Match preceding text without consuming it                                |
+| `negativeLookbehind(...)` | `(?<!...)`   | Reject preceding text without consuming it                               |
 
-See [Anchors API doc](https://callstack.github.io/ts-regex-builder/api/anchors) for more info.
+
+See [Assertions API doc](https://callstack.github.io/ts-regex-builder/api/assertions) for more info.
 
 ## Examples
 

diff --git a/website/docs/api/anchors.md b/website/docs/api/anchors.md
diff --git a/website/docs/api/assertions.md b/website/docs/api/assertions.md
@@ -0,0 +1,84 @@
+---
+id: assertions
+title: Assertions
+---
+
+## Anchors
+
+Anchors are special characters or sequences that specify positions in the input string rather than matching specific characters.
+
+### Start and end of string
+
+```ts
+const startOfString: Anchor;
+const endOfString: Anchor;
+```
+
+- `startOfString` anchor matches the start of a string (or line, if multiline mode is enabled). Regex syntax: `^`.
+- `endOfString` anchor matches the end of a string (or line, if multiline mode is enabled). Regex syntax: `$`.
+
+### Word boundary
+
+_This API was added in version 1.3.0._
+
+```ts
+const wordBoundary: Anchor;
+const notWordBoundary: Anchor;
+```
+
+- `wordBoundary` matches the positions where a word character is not followed or preceded by another word character, effectively indicating the start or end of a word. Regex syntax: `\b`.
+- `notWordBoundary` matches the positions where a word character is followed or preceded by another word character, indicating that it is not at the start or end of a word. Regex syntax: `\B`.
+
+Note: word characters are letters, digits, and underscore (`_`). Other special characters like `#`, `$`, etc are not considered word characters.
+
+## Lookarounds
+
+Lookarounds in regex are used for asserting that some pattern is or isn't followed or preceded by another pattern, without including the latter in the match.
+
+### `lookahead()`
+
+_This API was added in version 1.3.0._
+
+```ts
+function lookahead(sequence: RegexSequence): Lookahead;
+```
+
+Regex syntax: `(?=...)`.
+
+Allows for conditional matching by checking for subsequent patterns in regexes without consuming them.
+
+### `negativeLookahead()`
+
+_This API was added in version 1.3.0._
+
+```ts
+function negativeLookahead(sequence: RegexSequence): NegativeLookahead;
+```
+
+Regex syntax: `(?!...)`.
+
+Allows for matches to be rejected if a specified subsequent pattern is present, without consuming any characters.
+
+### `lookbehind()`
+
+_This API was added in version 1.3.0._
+
+```ts
+function lookbehind(sequence: RegexSequence): Lookahead;
+```
+
+Regex syntax: `(?<=...)`.
+
+Allows for conditional matching by checking for preceeding patterns in regexes without consuming them.
+
+### `negativeLookbehind()`
+
+_This API was added in version 1.3.0._
+
+```ts
+function negativeLookahead(sequence: RegexSequence): NegativeLookahead;
+```
+
+Regex syntax: `(?<!...)`.
+
+Allows for matches to be rejected if a specified preceeding pattern is present, without consuming any characters.
diff --git a/website/docs/api/builder.md b/website/docs/api/builder.md
@@ -1,7 +1,6 @@
 ---
 id: builder
 title: Builder
-sidebar_position: 2
 ---
 
 ### `buildRegExp()`

diff --git a/website/docs/api/character-classes.md b/website/docs/api/character-classes.md
@@ -1,7 +1,6 @@
 ---
 id: character-classes
 title: Character Classes
-sidebar_position: 5
 ---
 
 Character classes are a set of characters that match any one of the characters in the set.

diff --git a/website/docs/api/constructs.md b/website/docs/api/constructs.md
@@ -1,7 +1,6 @@
 ---
 id: constructs
 title: Constructs
-sidebar_position: 3
 ---
 
 These functions and objects represent available regex constructs.
@@ -30,45 +29,9 @@ Regex syntax: `(...)`.
 
 Captures, also known as capturing groups, extract and store parts of the matched string for later use.
 
-> [!NOTE]
-> TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required. E.g., `zeroOrMore(["abc"])` is encoded as `(?:abc)+`.
+:::note
 
-### `lookahead()`
+TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required. E.g., `zeroOrMore("abc")` is encoded as `(?:abc)+`.
 
-```ts
-function lookahead(sequence: RegexSequence): Lookahead;
-```
-
-Regex syntax: `(?=...)`.
-
-Allows for conditional matching by checking for subsequent patterns in regexes without consuming them.
-
-### `negativeLookahead()`
-
-```ts
-function negativeLookahead(sequence: RegexSequence): NegativeLookahead;
-```
-
-Regex syntax: `(?!...)`.
-
-Allows for matches to be rejected if a specified subsequent pattern is present, without consuming any characters.
-
-### `lookbehind()`
-
-```ts
-function lookbehind(sequence: RegexSequence): Lookahead;
-```
-
-Regex syntax: `(?<=...)`.
-
-Allows for conditional matching by checking for preceeding patterns in regexes without consuming them.
-
-### `negativeLookbehind()`
-
-```ts
-function negativeLookahead(sequence: RegexSequence): NegativeLookahead;
-```
-
-Regex syntax: `(?<!...)`.
+:::
 
-Allows for matches to be rejected if a specified preceeding pattern is present, without consuming any characters.
diff --git a/website/docs/api/overview.md b/website/docs/api/overview.md
@@ -47,19 +47,18 @@ See [Builder](./api/builder) for more info.
 
 ### Regex Constructs
 
-| Construct                 | Regex Syntax | Notes                                       |
-| ------------------------- | ------------ | ------------------------------------------- |
-| `choiceOf(x, y, z)`       | `x\|y\|z`    | Match one of provided sequences             |
-| `capture(...)`            | `(...)`      | Create a capture group                      |
-| `lookahead(...)`          | `(?=...)`    | Match subsequent text without consuming it  |
-| `negativeLookhead(...)`   | `(?!...)`    | Reject subsequent text without consuming it |
-| `lookbehind(...)`         | `(?<=...)`   | Match preceding text without consuming it   |
-| `negativeLookbehind(...)` | `(?<!...)`   | Reject preceding text without consuming it  |
+| Construct           | Regex Syntax | Notes                           |
+| ------------------- | ------------ | ------------------------------- |
+| `choiceOf(x, y, z)` | `x\|y\|z`    | Match one of provided sequences |
+| `capture(...)`      | `(...)`      | Create a capture group          |
 
 See [Constructs](./api/constructs) for more info.
 
-> [!NOTE]
-> TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required.
+:::note
+
+TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required.
+
+:::
 
 ### Quantifiers
 
@@ -89,12 +88,17 @@ See [Quantifiers](./api/quantifiers) for more info.
 
 See [Character Classes](./api/character-classes) for more info.
 
-### Anchors
+### Assertions
+
+| Assertion                 | Regex Syntax | Description                                                              |
+| ------------------------- | ------------ | ------------------------------------------------------------------------ |
+| `startOfString`           | `^`          | Match the start of the string (or the start of a line in multiline mode) |
+| `endOfString`             | `$`          | Match the end of the string (or the end of a line in multiline mode)     |
+| `wordBoundary`            | `\b`         | Match the start or end of a word without consuming characters            |
+| `lookahead(...)`          | `(?=...)`    | Match subsequent text without consuming it                               |
+| `negativeLookhead(...)`   | `(?!...)`    | Reject subsequent text without consuming it                              |
+| `lookbehind(...)`         | `(?<=...)`   | Match preceding text without consuming it                                |
+| `negativeLookbehind(...)` | `(?<!...)`   | Reject preceding text without consuming it                               |
 
-| Anchor          | Regex Syntax | Description                                                              |
-| --------------- | ------------ | ------------------------------------------------------------------------ |
-| `startOfString` | `^`          | Match the start of the string (or the start of a line in multiline mode) |
-| `endOfString`   | `$`          | Match the end of the string (or the end of a line in multiline mode)     |
-| `wordBoundary`  | `\b`         | Match the start or end of a word without consuming characters            |
 
-See [Anchors](./api/anchors) for more info.
+See [Assertions](./api/assertions) for more info.
diff --git a/website/docs/api/quantifiers.md b/website/docs/api/quantifiers.md
@@ -1,7 +1,6 @@
 ---
 id: quantifiers
 title: Quantifiers
-sidebar_position: 4
 ---
 
 Quantifiers in regex define the number of occurrences to match for a pattern.

diff --git a/website/docs/api/types.md b/website/docs/api/types.md
@@ -1,16 +1,28 @@
 ---
 id: types
 title: Types
-sidebar_position: 1
 ---
 
 ### `RegexSequence`
 
+```ts
+type RegexSequence = 
+    | RegexElement[]
+    | RegexElement;
+```
+
 The sequence of regex elements forming a regular expression. For developer convenience, it also accepts a single element instead of an array.
 
 ### `RegexElement`
 
-Fundamental building blocks of a regular expression, defined as either a regex construct, a string, or a `RegExp` literal (`/.../`).
+```ts
+type RegexElement = 
+    | RegexConstruct
+    | RegExp
+    | string;
+```
+
+Regex elements are fundamental building blocks of a regular expression. These can be either further regex constructs, regular strings to be matched literally or `RegExp` literals (`/.../`) for including simple regexes as part of a larger structure.
 
 ### `RegexConstruct`
 

diff --git a/website/sidebars.js b/website/sidebars.js
@@ -31,7 +31,7 @@ export default {
         'api/constructs',
         'api/quantifiers',
         'api/character-classes',
-        'api/anchors',
+        'api/assertions',
       ],
     },
     {
@@ -41,4 +41,3 @@ export default {
     },
   ],
 };
-