Skip to content

Commit d7ba9bb

Browse files
mdjastrzebskimdjastrzebski
authored
docs: tweaks (#99)
1 parent 63385ca commit d7ba9bb

12 files changed

+151
-50
lines changed

‎README.md

+23-25
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ This library allows users to create regular expressions in a structured way, mak
2121
const hexColor = /^#?([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$/;
2222

2323
// TS Regex Builder DSL
24-
const hexDigit = charClass(charRange('a', 'f'), charRange('A', 'F'), charRange('0', '9'));
24+
const hexDigit = /[a-fA-F0-9]/; // or: charClass(charRange('a', 'f'), charRange('A', 'F'), charRange('0', '9'));
2525

2626
const hexColor = buildRegExp([
2727
startOfString,
@@ -116,33 +116,15 @@ See [Constructs API doc](https://callstack.github.io/ts-regex-builder/api/constr
116116

117117
| Quantifier | Regex Syntax | Description |
118118
| -------------------------------- | ------------ | ------------------------------------------------- |
119-
| `zeroOrMore(x)` | `x*` | Zero or more occurence of a pattern |
120-
| `oneOrMore(x)` | `x+` | One or more occurence of a pattern |
121-
| `optional(x)` | `x?` | Zero or one occurence of a pattern |
119+
| `zeroOrMore(x)` | `x*` | Zero or more occurrence of a pattern |
120+
| `oneOrMore(x)` | `x+` | One or more occurrence of a pattern |
121+
| `optional(x)` | `x?` | Zero or one occurrence of a pattern |
122122
| `repeat(x, n)` | `x{n}` | Pattern repeats exact number of times |
123123
| `repeat(x, { min: n, })` | `x{n,}` | Pattern repeats at least given number of times |
124124
| `repeat(x, { min: n, max: n2 })` | `x{n1,n2}` | Pattern repeats between n1 and n2 number of times |
125125

126126
See [Quantifiers API doc](https://callstack.github.io/ts-regex-builder/api/quantifiers) for more info.
127127

128-
### Character classes
129-
130-
| Character class | Regex Syntax | Description |
131-
| ---------------------- | ------------ | ------------------------------------------------- |
132-
| `any` | `.` | Any character |
133-
| `word` | `\w` | Word character: letter, digit, underscore |
134-
| `digit` | `\d` | Digit character: 0 to 9 |
135-
| `whitespace` | `\s` | Whitespace character: space, tab, line break, ... |
136-
| `anyOf('abc')` | `[abc]` | Any of provided characters |
137-
| `charRange('a', 'z')` | `[a-z]` | Character in a range |
138-
| `charClass(...)` | `[...]` | Union of multiple character classes |
139-
| `negated(...)` | `[^...]` | Negation of a given character class |
140-
| `char(...)` | `\uXXXX` | Character specified given Unicode code point |
141-
| `unicodeProperty(...)` | `\p{...}` | Characters with given Unicode property |
142-
143-
144-
See [Character Classes API doc](https://callstack.github.io/ts-regex-builder/api/character-classes) and [Unicode API doc](https://callstack.github.io/ts-regex-builder/api/unicode) for more info.
145-
146128
### Assertions
147129

148130
| Assertion | Regex Syntax | Description |
@@ -151,12 +133,30 @@ See [Character Classes API doc](https://callstack.github.io/ts-regex-builder/api
151133
| `endOfString` | `$` | Match the end of the string (or the end of a line in multiline mode) |
152134
| `wordBoundary` | `\b` | Match the start or end of a word without consuming characters |
153135
| `lookahead(...)` | `(?=...)` | Match subsequent text without consuming it |
154-
| `negativeLookhead(...)` | `(?!...)` | Reject subsequent text without consuming it |
136+
| `negativeLookahead(...)` | `(?!...)` | Reject subsequent text without consuming it |
155137
| `lookbehind(...)` | `(?<=...)` | Match preceding text without consuming it |
156138
| `negativeLookbehind(...)` | `(?<!...)` | Reject preceding text without consuming it |
157139

158140
See [Assertions API doc](https://callstack.github.io/ts-regex-builder/api/assertions) for more info.
159141

142+
### Character classes
143+
144+
> [!TIP]
145+
> You may also use inline regexes for specifying character classes, as they offer a concise yet readable syntax. For example, `/[a-z0-9_]/`.
146+
147+
| Character class | Regex Syntax | Description |
148+
| --------------------- | ------------ | ------------------------------------------------- |
149+
| `any` | `.` | Any character |
150+
| `word` | `\w` | Word character: letter, digit, underscore |
151+
| `digit` | `\d` | Digit character: 0 to 9 |
152+
| `whitespace` | `\s` | Whitespace character: space, tab, line break, ... |
153+
| `anyOf('abc')` | `[abc]` | Any of provided characters |
154+
| `charRange('a', 'z')` | `[a-z]` | Character in a range |
155+
| `charClass(...)` | `[...]` | Union of multiple character classes |
156+
| `negated(...)` | `[^...]` | Negation of a given character class |
157+
158+
See [Character Classes API doc](https://callstack.github.io/ts-regex-builder/api/character-classes) and [Unicode API doc](https://callstack.github.io/ts-regex-builder/api/unicode) for more info.
159+
160160
## Examples
161161

162162
See [Examples](https://callstack.github.io/ts-regex-builder/examples).
@@ -185,8 +185,6 @@ TS Regex Builder is inspired by [Swift Regex Builder API](https://developer.appl
185185
- [Swift Evolution 351: Regex Builder DSL](https://github.com/apple/swift-evolution/blob/main/proposals/0351-regex-builder.md)
186186
- [Swift Regex Builder API docs](https://developer.apple.com/documentation/regexbuilder)
187187

188-
189-
190188
---
191189

192190
Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

‎src/constructs/anchors.ts

+12
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,32 @@
11
import type { EncodedRegex } from '../types';
22

3+
/**
4+
* Start of string anchor. Matches the start of of string. In `multiline` mode, also matches immediately following a newline.
5+
*/
36
export const startOfString: EncodedRegex = {
47
precedence: 'atom',
58
pattern: '^',
69
};
710

11+
/**
12+
* End of string anchor. Matches the end of a string. In `multiline` mode, also matches immediately preceding a newline.
13+
*/
814
export const endOfString: EncodedRegex = {
915
precedence: 'atom',
1016
pattern: '$',
1117
};
1218

19+
/**
20+
* Word boundary anchor. Matches the position where one side is a word character (alphanumeric or underscore) and the other side is a non-word character (anything else).
21+
*/
1322
export const wordBoundary: EncodedRegex = {
1423
precedence: 'atom',
1524
pattern: '\\b',
1625
};
1726

27+
/**
28+
* Non-word boundary anchor. Matches the position where both sides are word characters.
29+
*/
1830
export const nonWordBoundary: EncodedRegex = {
1931
precedence: 'atom',
2032
pattern: '\\B',

‎src/constructs/char-class.ts

+25
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
import type { CharacterClass, CharacterEscape, EncodedRegex } from '../types';
22
import { ensureText } from '../utils';
33

4+
/**
5+
* Creates a character class which matches any one of the given characters.
6+
*
7+
* @param elements - Member characters or character ranges.
8+
* @returns Character class.
9+
*/
410
export function charClass(...elements: Array<CharacterClass | CharacterEscape>): CharacterClass {
511
if (!elements.length) {
612
throw new Error('Expected at least one element');
@@ -13,6 +19,13 @@ export function charClass(...elements: Array<CharacterClass | CharacterEscape>):
1319
};
1420
}
1521

22+
/**
23+
* Creates a character class which matches any one of the characters in the range.
24+
*
25+
* @param start - Start of the range (single character).
26+
* @param end - End of the range (single character).
27+
* @returns Character class.
28+
*/
1629
export function charRange(start: string, end: string): CharacterClass {
1730
if (start.length !== 1 || end.length !== 1) {
1831
throw new Error(`Expected single characters, but received "${start}" & "${end}"`);
@@ -29,6 +42,12 @@ export function charRange(start: string, end: string): CharacterClass {
2942
};
3043
}
3144

45+
/**
46+
* Creates a character class which matches any one of the given characters.
47+
*
48+
* @param chars - Characters to match.
49+
* @returns Character class.
50+
*/
3251
export function anyOf(chars: string): CharacterClass {
3352
ensureText(chars);
3453

@@ -38,6 +57,12 @@ export function anyOf(chars: string): CharacterClass {
3857
};
3958
}
4059

60+
/**
61+
* Creates a negated character class which matches any character that is not in the given character class.
62+
*
63+
* @param element - Character class or character escape to negate.
64+
* @returns Negated character class.
65+
*/
4166
export function negated(element: CharacterClass | CharacterEscape): EncodedRegex {
4267
return encodeCharClass.call(element, true);
4368
}

‎src/constructs/char-escape.ts

+18
Original file line numberDiff line numberDiff line change
@@ -9,36 +9,54 @@ export const any: EncodedRegex = {
99
pattern: '.',
1010
};
1111

12+
/**
13+
* Matches any digit (0-9).
14+
*/
1215
export const digit: CharacterEscape = {
1316
precedence: 'atom',
1417
pattern: '\\d',
1518
chars: ['\\d'],
1619
};
1720

21+
/**
22+
* Matches any non-digit (0-9) character.
23+
*/
1824
export const nonDigit: CharacterEscape = {
1925
precedence: 'atom',
2026
pattern: '\\D',
2127
chars: ['\\D'],
2228
};
2329

30+
/**
31+
* Matches any word character (alphanumeric or underscore).
32+
*/
2433
export const word: CharacterEscape = {
2534
precedence: 'atom',
2635
pattern: '\\w',
2736
chars: ['\\w'],
2837
};
2938

39+
/**
40+
* Matches any non-word (alphanumeric or underscore) character.
41+
*/
3042
export const nonWord: CharacterEscape = {
3143
precedence: 'atom',
3244
pattern: '\\W',
3345
chars: ['\\W'],
3446
};
3547

48+
/**
49+
* Matches any whitespace character (space, tab, newline, etc.).
50+
*/
3651
export const whitespace: CharacterEscape = {
3752
precedence: 'atom',
3853
pattern: '\\s',
3954
chars: ['\\s'],
4055
};
4156

57+
/**
58+
* Matches any non-whitespace (space, tab, newline, etc.) character.
59+
*/
4260
export const nonWhitespace: CharacterEscape = {
4361
precedence: 'atom',
4462
pattern: '\\S',

‎src/constructs/choice-of.ts

+6
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
import { encode } from '../encoder';
22
import type { EncodedRegex, RegexSequence } from '../types';
33

4+
/**
5+
* Creates a disjunction (choice of) which matches any of the alternatives.
6+
*
7+
* @param alternatives - Alternatives to choose from.
8+
* @returns Choice of alternatives.
9+
*/
410
export function choiceOf(...alternatives: RegexSequence[]): EncodedRegex {
511
if (alternatives.length === 0) {
612
throw new Error('Expected at least one alternative');

‎src/constructs/quantifiers.ts

+18
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ export interface QuantifierOptions {
66
greedy?: boolean;
77
}
88

9+
/**
10+
* Creates a quantifier which matches zero or more of the given elements.
11+
*
12+
* @param sequence - Elements to match zero or more of.
13+
* @param options - Quantifier options.
14+
*/
915
export function zeroOrMore(sequence: RegexSequence, options?: QuantifierOptions): EncodedRegex {
1016
const elements = ensureElements(sequence);
1117
return {
@@ -14,6 +20,12 @@ export function zeroOrMore(sequence: RegexSequence, options?: QuantifierOptions)
1420
};
1521
}
1622

23+
/**
24+
* Creates a quantifier which matches one or more of the given elements.
25+
*
26+
* @param sequence - Elements to match one or more of.
27+
* @param options - Quantifier options.
28+
*/
1729
export function oneOrMore(sequence: RegexSequence, options?: QuantifierOptions): EncodedRegex {
1830
const elements = ensureElements(sequence);
1931
return {
@@ -22,6 +34,12 @@ export function oneOrMore(sequence: RegexSequence, options?: QuantifierOptions):
2234
};
2335
}
2436

37+
/**
38+
* Creates a quantifier which matches zero or one of the given elements.
39+
*
40+
* @param sequence - Elements to match zero or one of.
41+
* @param options - Quantifier options.
42+
*/
2543
export function optional(sequence: RegexSequence, options?: QuantifierOptions): EncodedRegex {
2644
const elements = ensureElements(sequence);
2745
return {

‎src/constructs/regex.ts

+5
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
import { encode } from '../encoder';
22
import type { EncodedRegex, RegexSequence } from '../types';
33

4+
/**
5+
* Groups the given sequence into a single element.
6+
*
7+
* @param sequence - Sequence to group.
8+
*/
49
export function regex(sequence: RegexSequence): EncodedRegex {
510
return encode(sequence);
611
}

‎src/constructs/repeat.ts

+13
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,21 @@ import { encodeAtomic } from '../encoder';
22
import type { EncodedRegex, RegexSequence } from '../types';
33
import { ensureElements } from '../utils';
44

5+
/**
6+
* Options for the `repeat` function.
7+
*
8+
* @param min - Minimum number of times to match.
9+
* @param max - Maximum number of times to match (default: unlimited).
10+
* @param greedy - Whether to use greedy quantifiers (default: true).
11+
*/
512
export type RepeatOptions = number | { min: number; max?: number; greedy?: boolean };
613

14+
/**
15+
* Creates a quantifier which matches the given sequence a specific number of times.
16+
*
17+
* @param sequence - Sequence to match.
18+
* @param options - Quantifier options.
19+
*/
720
export function repeat(sequence: RegexSequence, options: RepeatOptions): EncodedRegex {
821
const elements = ensureElements(sequence);
922

‎website/docs/api/overview.md

+27-22
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ Most of the regex constructs accept a regex sequence as their argument.
2424
Regex constructs can be composed into a tree structure:
2525

2626
```ts
27-
const currencyCode = repeat(charRange('A', 'Z'), 3);
27+
const currencyCode = repeat(/[A-Z]/, 3); // or repeat(charRange('A', 'Z'), 3);
28+
2829
const currencyAmount = buildRegExp([
2930
choiceOf('$', '€', currencyCode), // currency
3031
capture(
@@ -64,32 +65,15 @@ TS Regex Builder does not have a construct for non-capturing groups. Such groups
6465

6566
| Quantifier | Regex Syntax | Description |
6667
| -------------------------------- | ------------ | ------------------------------------------------- |
67-
| `zeroOrMore(x)` | `x*` | Zero or more occurence of a pattern |
68-
| `oneOrMore(x)` | `x+` | One or more occurence of a pattern |
69-
| `optional(x)` | `x?` | Zero or one occurence of a pattern |
68+
| `zeroOrMore(x)` | `x*` | Zero or more occurrence of a pattern |
69+
| `oneOrMore(x)` | `x+` | One or more occurrence of a pattern |
70+
| `optional(x)` | `x?` | Zero or one occurrence of a pattern |
7071
| `repeat(x, n)` | `x{n}` | Pattern repeats exact number of times |
7172
| `repeat(x, { min: n, })` | `x{n,}` | Pattern repeats at least given number of times |
7273
| `repeat(x, { min: n, max: n2 })` | `x{n1,n2}` | Pattern repeats between n1 and n2 number of times |
7374

7475
See [Quantifiers](./api/quantifiers) for more info.
7576

76-
### Character classes
77-
78-
| Character class | Regex Syntax | Description |
79-
| ---------------------- | ------------ | ------------------------------------------------- |
80-
| `any` | `.` | Any character |
81-
| `word` | `\w` | Word character: letter, digit, underscore |
82-
| `digit` | `\d` | Digit character: 0 to 9 |
83-
| `whitespace` | `\s` | Whitespace character: space, tab, line break, ... |
84-
| `anyOf('abc')` | `[abc]` | Any of provided characters |
85-
| `charRange('a', 'z')` | `[a-z]` | Character in a range |
86-
| `charClass(...)` | `[...]` | Union of multiple character classes |
87-
| `negated(...)` | `[^...]` | Negation of a given character class |
88-
| `char(...)` | `\uXXXX` | Character specified given Unicode code point |
89-
| `unicodeProperty(...)` | `\p{...}` | Characters with given Unicode property |
90-
91-
See [Character Classes](./api/character-classes) and [Unicode](./api/unicode) for more info.
92-
9377
### Assertions
9478

9579
| Assertion | Regex Syntax | Description |
@@ -98,8 +82,29 @@ See [Character Classes](./api/character-classes) and [Unicode](./api/unicode) fo
9882
| `endOfString` | `$` | Match the end of the string (or the end of a line in multiline mode) |
9983
| `wordBoundary` | `\b` | Match the start or end of a word without consuming characters |
10084
| `lookahead(...)` | `(?=...)` | Match subsequent text without consuming it |
101-
| `negativeLookhead(...)` | `(?!...)` | Reject subsequent text without consuming it |
85+
| `negativeLookahead(...)` | `(?!...)` | Reject subsequent text without consuming it |
10286
| `lookbehind(...)` | `(?<=...)` | Match preceding text without consuming it |
10387
| `negativeLookbehind(...)` | `(?<!...)` | Reject preceding text without consuming it |
10488

10589
See [Assertions](./api/assertions) for more info.
90+
91+
### Character classes
92+
93+
::: tip
94+
95+
You may also use inline regexes for specifying character classes, as they offer a concise yet readable syntax. For example, `/[a-z0-9_]/`.
96+
97+
:::
98+
99+
| Character class | Regex Syntax | Description |
100+
| --------------------- | ------------ | ------------------------------------------------- |
101+
| `any` | `.` | Any character |
102+
| `word` | `\w` | Word character: letter, digit, underscore |
103+
| `digit` | `\d` | Digit character: 0 to 9 |
104+
| `whitespace` | `\s` | Whitespace character: space, tab, line break, ... |
105+
| `anyOf('abc')` | `[abc]` | Any of provided characters |
106+
| `charRange('a', 'z')` | `[a-z]` | Character in a range |
107+
| `charClass(...)` | `[...]` | Union of multiple character classes |
108+
| `negated(...)` | `[^...]` | Negation of a given character class |
109+
110+
See [Character Classes](./api/character-classes) and [Unicode](./api/unicode) for more info.

‎website/docs/api/unicode.md

+1
Original file line numberDiff line numberDiff line change
@@ -33,5 +33,6 @@ Unicode character property escape matching a set of characters specified by a Un
3333
Regex syntax: `\p{Property}` or `\p{Property=Value}`
3434

3535
See:
36+
3637
- [MDN: Unicode character class escape](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape)
3738
- [UTS#18: Unicode Regular Expressions](https://www.unicode.org/reports/tr18/)

0 commit comments

Comments
 (0)