0
# RegExp Module
1

2
Regular expression utilities for escaping strings and manipulating regex flags.
3

4
## Core Imports
5

6
```javascript
7
// Import Sugar namespace
8
import Sugar from "sugar";
9
// Methods available as Sugar.RegExp.methodName()
10
```
11

12
CommonJS:
13
```javascript
14
const Sugar = require("sugar");
15
// Methods available as Sugar.RegExp.methodName()
16
Sugar.RegExp.escape('text');
17
```
18

19
## Capabilities
20

21
### RegExp Utility
22

23
Utility functions for working with regular expressions.
24

25
#### Escape
26

27
Escapes special regex characters in a string to create a literal match pattern.
28

29
```javascript { .api }
30
/**
31
 * Escapes special regex characters in string for literal matching
32
 * @param str - String to escape for regex use
33
 * @returns Escaped string safe for regex patterns
34
 */
35
function escape(str?: string): string;
36
```
37

38
**Usage Example:**
39
```javascript
40
import Sugar from "sugar";
41

42
const userInput = "What is $100 + $200?";
43
const escaped = Sugar.RegExp.escape(userInput);
44
console.log(escaped); // "What is \\$100 \\+ \\$200\\?"
45

46
// Use in regex for literal matching
47
const regex = new RegExp(escaped);
48
const text = "The question was: What is $100 + $200?";
49
console.log(regex.test(text)); // true
50

51
// Without escaping (would fail)
52
const badRegex = new RegExp(userInput);
53
// This would create invalid regex due to special characters
54
```
55

56
### RegExp Manipulation
57

58
Methods for getting and setting regular expression flags.
59

60
#### Get Flags
61

62
Gets the flags from a regular expression as a string.
63

64
```javascript { .api }
65
/**
66
 * Gets flags from regular expression
67
 * @param instance - RegExp to get flags from
68
 * @returns String containing all flags (e.g., "gim")
69
 */
70
function getFlags(instance: RegExp): string;
71
```
72

73
**Usage Example:**
74
```javascript
75
import Sugar from "sugar";
76

77
const regex1 = /pattern/gi;
78
console.log(Sugar.RegExp.getFlags(regex1)); // "gi"
79

80
const regex2 = /test/m;
81
console.log(Sugar.RegExp.getFlags(regex2)); // "m"
82

83
const regex3 = /simple/;
84
console.log(Sugar.RegExp.getFlags(regex3)); // ""
85
```
86

87
#### Set Flags
88

89
Creates a new regular expression with the specified flags, replacing existing flags.
90

91
```javascript { .api }
92
/**
93
 * Creates new regex with specified flags (replaces existing)
94
 * @param instance - RegExp to modify
95
 * @param flags - New flags to set (e.g., "gi")
96
 * @returns New RegExp with specified flags
97
 */
98
function setFlags(instance: RegExp, flags: string): RegExp;
99
```
100

101
**Usage Example:**
102
```javascript
103
import Sugar from "sugar";
104

105
const original = /pattern/i;
106
const modified = Sugar.RegExp.setFlags(original, "gm");
107

108
console.log(original.flags); // "i"
109
console.log(modified.flags); // "gm"
110
console.log(original.source); // "pattern"
111
console.log(modified.source); // "pattern"
112

113
// Completely replace flags
114
const regex = /test/gim;
115
const newRegex = Sugar.RegExp.setFlags(regex, "s");
116
console.log(newRegex.flags); // "s" (all previous flags removed)
117
```
118

119
#### Add Flags
120

121
Creates a new regular expression by adding flags to existing ones.
122

123
```javascript { .api }
124
/**
125
 * Creates new regex by adding flags to existing ones
126
 * @param instance - RegExp to modify
127
 * @param flags - Flags to add (e.g., "g")
128
 * @returns New RegExp with additional flags
129
 */
130
function addFlags(instance: RegExp, flags: string): RegExp;
131
```
132

133
**Usage Example:**
134
```javascript
135
import Sugar from "sugar";
136

137
const original = /pattern/i;
138
const withGlobal = Sugar.RegExp.addFlags(original, "g");
139

140
console.log(original.flags); // "i"
141
console.log(withGlobal.flags); // "gi"
142

143
// Add multiple flags
144
const regex = /test/;
145
const enhanced = Sugar.RegExp.addFlags(regex, "gim");
146
console.log(enhanced.flags); // "gim"
147

148
// Adding existing flags is safe (no duplicates)
149
const alreadyGlobal = /word/g;
150
const stillGlobal = Sugar.RegExp.addFlags(alreadyGlobal, "g");
151
console.log(stillGlobal.flags); // "g" (not "gg")
152
```
153

154
#### Remove Flags
155

156
Creates a new regular expression by removing specified flags.
157

158
```javascript { .api }
159
/**
160
 * Creates new regex by removing specified flags
161
 * @param instance - RegExp to modify
162
 * @param flags - Flags to remove (e.g., "g")
163
 * @returns New RegExp with specified flags removed
164
 */
165
function removeFlags(instance: RegExp, flags: string): RegExp;
166
```
167

168
**Usage Example:**
169
```javascript
170
import Sugar from "sugar";
171

172
const original = /pattern/gim;
173
const noGlobal = Sugar.RegExp.removeFlags(original, "g");
174

175
console.log(original.flags); // "gim"
176
console.log(noGlobal.flags); // "im"
177

178
// Remove multiple flags
179
const regex = /test/gims;
180
const simplified = Sugar.RegExp.removeFlags(regex, "gs");
181
console.log(simplified.flags); // "im"
182

183
// Removing non-existent flags is safe
184
const simple = /word/i;
185
const stillSimple = Sugar.RegExp.removeFlags(simple, "g");
186
console.log(stillSimple.flags); // "i" (no change)
187

188
// Remove all flags
189
const complex = /pattern/gimsy;
190
const bare = Sugar.RegExp.removeFlags(complex, "gimsy");
191
console.log(bare.flags); // ""
192
```
193

194
## Common Usage Patterns
195

196
### Safe String Matching
197

198
```javascript
199
import Sugar from "sugar";
200

201
function createLiteralMatcher(searchTerm) {
202
  return new RegExp(Sugar.RegExp.escape(searchTerm), "gi");
203
}
204

205
// Safe search in user content
206
const userQuery = "$100 (special offer)";
207
const matcher = createLiteralMatcher(userQuery);
208
const content = "Today only: $100 (special offer) available!";
209
console.log(matcher.test(content)); // true
210
```
211

212
### Dynamic Flag Management
213

214
```javascript
215
import Sugar from "sugar";
216

217
function toggleCaseSensitive(regex) {
218
  const flags = Sugar.RegExp.getFlags(regex);
219
  return flags.includes('i') 
220
    ? Sugar.RegExp.removeFlags(regex, 'i')
221
    : Sugar.RegExp.addFlags(regex, 'i');
222
}
223

224
let pattern = /hello/g;
225
console.log(Sugar.RegExp.getFlags(pattern)); // "g"
226

227
pattern = toggleCaseSensitive(pattern);
228
console.log(Sugar.RegExp.getFlags(pattern)); // "gi"
229

230
pattern = toggleCaseSensitive(pattern);
231
console.log(Sugar.RegExp.getFlags(pattern)); // "g"
232
```
233

234
### RegExp Builder
235

236
```javascript
237
import Sugar from "sugar";
238

239
class RegExpBuilder {
240
  constructor(pattern) {
241
    this.regex = new RegExp(pattern);
242
  }
243
  
244
  global() {
245
    this.regex = Sugar.RegExp.addFlags(this.regex, 'g');
246
    return this;
247
  }
248
  
249
  ignoreCase() {
250
    this.regex = Sugar.RegExp.addFlags(this.regex, 'i');
251
    return this;
252
  }
253
  
254
  multiline() {
255
    this.regex = Sugar.RegExp.addFlags(this.regex, 'm');
256
    return this;
257
  }
258
  
259
  build() {
260
    return this.regex;
261
  }
262
}
263

264
const emailRegex = new RegExpBuilder('[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}')
265
  .global()
266
  .ignoreCase()
267
  .build();
268

269
console.log(emailRegex.flags); // "gi"
270
```