0
# Static Utilities
1

2
Utility functions for encoding/decoding, finding URIs in text, joining paths, configuration, and advanced URI operations.
3

4
## Capabilities
5

6
### Text Processing Utilities
7

8
Methods for finding and processing URIs within text strings.
9

10
```javascript { .api }
11
/**
12
 * Find URIs in text and process them with a callback
13
 * @param string - Text string to search for URIs
14
 * @param callback - Function to process each found URI
15
 * @param options - Options for URI detection and processing
16
 * @returns Modified string with processed URIs
17
 */
18
URI.withinString(string: string, callback: function, options?: object): string;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
// Find and modify URIs in text
25
const text = 'Visit http://example.com and https://api.example.com/users for more info.';
26

27
const result = URI.withinString(text, function(url) {
28
  const uri = new URI(url);
29
  // Convert to HTTPS
30
  if (uri.protocol() === 'http') {
31
    uri.protocol('https');
32
  }
33
  return uri.toString();
34
});
35

36
console.log(result);
37
// 'Visit https://example.com and https://api.example.com/users for more info.'
38

39
// Add tracking parameters
40
const withTracking = URI.withinString(text, function(url) {
41
  return new URI(url).addQuery('utm_source', 'email').toString();
42
});
43

44
console.log(withTracking);
45
// 'Visit http://example.com?utm_source=email and https://api.example.com/users?utm_source=email for more info.'
46

47
// Extract all URIs
48
const urls = [];
49
URI.withinString(text, function(url) {
50
  urls.push(url);
51
  return url; // Return unchanged
52
});
53
console.log(urls); // ['http://example.com', 'https://api.example.com/users']
54
```
55

56
### DOM Integration Utilities
57

58
Methods for working with DOM elements and URI attributes.
59

60
```javascript { .api }
61
/**
62
 * Get the appropriate URI attribute for a DOM element
63
 * @param node - DOM element to examine
64
 * @returns Attribute name that should contain the URI
65
 */
66
URI.getDomAttribute(node: Element): string;
67
```
68

69
**Usage Examples:**
70

71
```javascript
72
// Get URI attribute for different elements
73
const linkElement = document.createElement('a');
74
console.log(URI.getDomAttribute(linkElement)); // 'href'
75

76
const imgElement = document.createElement('img');
77
console.log(URI.getDomAttribute(imgElement)); // 'src'
78

79
const formElement = document.createElement('form');
80
console.log(URI.getDomAttribute(formElement)); // 'action'
81

82
const scriptElement = document.createElement('script');
83
console.log(URI.getDomAttribute(scriptElement)); // 'src'
84

85
// Use with actual DOM manipulation
86
const links = document.querySelectorAll('a');
87
links.forEach(link => {
88
  const attr = URI.getDomAttribute(link);
89
  const currentUri = new URI(link.getAttribute(attr));
90
  // Modify URI as needed
91
  currentUri.addQuery('processed', 'true');
92
  link.setAttribute(attr, currentUri.toString());
93
});
94
```
95

96
### Global Configuration
97

98
Methods for managing global URI.js configuration and preventing conflicts.
99

100
```javascript { .api }
101
/**
102
 * Restore previous URI variable and optionally remove extensions
103
 * @param removeAll - Whether to remove all URI.js extensions
104
 * @returns Previous URI variable value
105
 */
106
URI.noConflict(removeAll?: boolean): any;
107
```
108

109
**Usage Examples:**
110

111
```javascript
112
// Store original URI variable
113
const originalURI = window.URI;
114

115
// Load URI.js (overrides window.URI)
116
// <script src="URI.js"></script>
117

118
// Use URI.js
119
const uri = new URI('http://example.com');
120

121
// Restore original and get URI.js reference
122
const URIjs = URI.noConflict();
123
console.log(window.URI === originalURI); // true
124

125
// Continue using URI.js with new reference
126
const newUri = new URIjs('http://other.com');
127

128
// Remove all extensions too
129
const URIjsClean = URI.noConflict(true);
130
// This removes jQuery plugins, fragment extensions, etc.
131
```
132

133
### Internal Utilities
134

135
Internal utility methods exposed for advanced usage.
136

137
```javascript { .api }
138
/**
139
 * Create new URI parts object with default values
140
 * @returns Object with default URI component values
141
 */
142
URI._parts(): object;
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
// Create empty parts object
149
const parts = URI._parts();
150
console.log(parts);
151
// {
152
//   protocol: null,
153
//   username: null,
154
//   password: null,
155
//   hostname: null,
156
//   port: null,
157
//   pathname: null,
158
//   query: null,
159
//   fragment: null
160
// }
161

162
// Use for custom parsing
163
const customParts = URI._parts();
164
customParts.protocol = 'https';
165
customParts.hostname = 'example.com';
166
customParts.pathname = '/api/users';
167

168
const customUri = URI.build(customParts);
169
console.log(customUri); // 'https://example.com/api/users'
170
```
171

172
### Configuration Objects
173

174
Access to internal configuration and data structures.
175

176
```javascript { .api }
177
// DOM element to URI attribute mapping
178
URI.domAttributes: {
179
  a: 'href',
180
  blockquote: 'cite',
181
  link: 'href',
182
  base: 'href',
183
  script: 'src',
184
  form: 'action',
185
  img: 'src',
186
  area: 'href',
187
  iframe: 'src',
188
  embed: 'src',
189
  source: 'src',
190
  track: 'src',
191
  input: 'src',
192
  audio: 'src',
193
  video: 'src'
194
};
195

196
// Protocols that require hostnames
197
URI.hostProtocols: ['http', 'https'];
198

199
// Character encoding/decoding maps
200
URI.characters: {
201
  pathname: {
202
    encode: object,
203
    decode: object
204
  },
205
  reserved: {
206
    encode: object,
207
    decode: object
208
  },
209
  urnpath: {
210
    encode: object,
211
    decode: object
212
  }
213
};
214

215
// URI finding patterns
216
URI.findUri: {
217
  start: RegExp,
218
  end: RegExp,
219
  trim: RegExp,
220
  parens: RegExp
221
};
222
```
223

224
**Usage Examples:**
225

226
```javascript
227
// Check if protocol requires hostname
228
const requiresHost = URI.hostProtocols.includes('http');
229
console.log(requiresHost); // true
230

231
// Add custom DOM attribute mapping
232
URI.domAttributes['my-custom-element'] = 'data-uri';
233

234
// Access encoding characters
235
const pathChars = URI.characters.pathname;
236
console.log(pathChars.encode); // Object with character mappings
237

238
// Use find patterns for custom URI detection
239
const customText = 'Check out http://example.com!';
240
const match = customText.match(URI.findUri.start);
241
if (match) {
242
  console.log('Found URI starting at:', match.index);
243
}
244
```
245

246
### Regular Expression Patterns
247

248
Access to internal regular expressions for validation and parsing.
249

250
```javascript { .api }
251
// Available regex patterns
252
URI.protocol_expression: RegExp; // Protocol validation
253
URI.idn_expression: RegExp;      // Internationalized domain names
254
URI.punycode_expression: RegExp; // Punycode detection
255
URI.ip4_expression: RegExp;      // IPv4 address validation  
256
URI.ip6_expression: RegExp;      // IPv6 address validation
257
URI.find_uri_expression: RegExp; // URI detection in text
258
URI.leading_whitespace_expression: RegExp; // Leading whitespace
259
URI.ascii_tab_whitespace: RegExp; // ASCII control characters
260
URI.invalid_hostname_characters: RegExp; // Invalid hostname chars
261
```
262

263
**Usage Examples:**
264

265
```javascript
266
// Validate protocols
267
const validProtocol = URI.protocol_expression.test('http');
268
console.log(validProtocol); // true
269

270
const invalidProtocol = URI.protocol_expression.test('ht-tp');
271
console.log(invalidProtocol); // false
272

273
// Check for IPv4 addresses
274
const isIPv4 = URI.ip4_expression.test('192.168.1.1');
275
console.log(isIPv4); // true
276

277
// Check for IPv6 addresses
278
const isIPv6 = URI.ip6_expression.test('2001:db8::1');
279
console.log(isIPv6); // true
280

281
// Detect punycode
282
const hasPunycode = URI.punycode_expression.test('xn--e1afmkfd.xn--p1ai');
283
console.log(hasPunycode); // true
284

285
// Find URIs in text
286
const textWithURI = 'Visit http://example.com today!';
287
const foundURI = textWithURI.match(URI.find_uri_expression);
288
console.log(foundURI[0]); // 'http://example.com'
289

290
// Check for invalid hostname characters
291
const hasInvalidChars = URI.invalid_hostname_characters.test('invalid..hostname');
292
console.log(hasInvalidChars); // true
293
```