0
# Built-in Functions
1

2
Over 60 built-in functions organized into categories: color manipulation (rgba, hsl, lighten), mathematical operations (abs, ceil, min), string processing (substr, split, unquote), list operations (push, pop, keys), and utility functions (json, lookup, image-size).
3

4
## Capabilities
5

6
### Color Functions
7

8
Functions for creating, manipulating, and analyzing colors.
9

10
```javascript { .api }
11
/**
12
 * Get red component of color (0-255)
13
 * @param {Color} color - Color value
14
 * @returns {Unit} Red component
15
 */
16
function red(color);
17

18
/**
19
 * Get green component of color (0-255)
20
 * @param {Color} color - Color value
21
 * @returns {Unit} Green component
22
 */
23
function green(color);
24

25
/**
26
 * Get blue component of color (0-255)
27
 * @param {Color} color - Color value
28
 * @returns {Unit} Blue component
29
 */
30
function blue(color);
31

32
/**
33
 * Get alpha component of color (0-1)
34
 * @param {Color} color - Color value
35
 * @returns {Unit} Alpha component
36
 */
37
function alpha(color);
38

39
/**
40
 * Get hue component of color (0-360 degrees)
41
 * @param {Color} color - Color value
42
 * @returns {Unit} Hue in degrees
43
 */
44
function hue(color);
45

46
/**
47
 * Get saturation component of color (0-100%)
48
 * @param {Color} color - Color value
49
 * @returns {Unit} Saturation percentage
50
 */
51
function saturation(color);
52

53
/**
54
 * Get lightness component of color (0-100%)
55
 * @param {Color} color - Color value
56
 * @returns {Unit} Lightness percentage
57
 */
58
function lightness(color);
59

60
/**
61
 * Create RGBA color
62
 * @param {Unit} r - Red component (0-255)
63
 * @param {Unit} g - Green component (0-255)
64
 * @param {Unit} b - Blue component (0-255)
65
 * @param {Unit} a - Alpha component (0-1)
66
 * @returns {RGBA} RGBA color
67
 */
68
function rgba(r, g, b, a);
69

70
/**
71
 * Create HSLA color
72
 * @param {Unit} h - Hue (0-360 degrees)
73
 * @param {Unit} s - Saturation (0-100%)
74
 * @param {Unit} l - Lightness (0-100%)
75
 * @param {Unit} a - Alpha (0-1)
76
 * @returns {RGBA} RGBA color
77
 */
78
function hsla(h, s, l, a);
79

80
/**
81
 * Lighten color by percentage
82
 * @param {Color} color - Base color
83
 * @param {Unit} amount - Percentage to lighten (0-100%)
84
 * @returns {RGBA} Lightened color
85
 */
86
function lighten(color, amount);
87

88
/**
89
 * Darken color by percentage
90
 * @param {Color} color - Base color
91
 * @param {Unit} amount - Percentage to darken (0-100%)
92
 * @returns {RGBA} Darkened color
93
 */
94
function darken(color, amount);
95

96
/**
97
 * Saturate color by percentage
98
 * @param {Color} color - Base color
99
 * @param {Unit} amount - Percentage to saturate (0-100%)
100
 * @returns {RGBA} Saturated color
101
 */
102
function saturate(color, amount);
103

104
/**
105
 * Desaturate color by percentage
106
 * @param {Color} color - Base color
107
 * @param {Unit} amount - Percentage to desaturate (0-100%)
108
 * @returns {RGBA} Desaturated color
109
 */
110
function desaturate(color, amount);
111

112
/**
113
 * Invert color
114
 * @param {Color} color - Color to invert
115
 * @returns {RGBA} Inverted color
116
 */
117
function invert(color);
118

119
/**
120
 * Get complement color (rotate hue by 180 degrees)
121
 * @param {Color} color - Base color
122
 * @returns {RGBA} Complement color
123
 */
124
function complement(color);
125

126
/**
127
 * Rotate color hue by degrees
128
 * @param {Color} color - Base color
129
 * @param {Unit} degrees - Degrees to rotate (-360 to 360)
130
 * @returns {RGBA} Color with rotated hue
131
 */
132
function spin(color, degrees);
133
```
134

135
### Mathematical Functions
136

137
Functions for numerical calculations and operations.
138

139
```javascript { .api }
140
/**
141
 * Absolute value
142
 * @param {Unit} n - Number
143
 * @returns {Unit} Absolute value
144
 */
145
function abs(n);
146

147
/**
148
 * Ceiling (round up)
149
 * @param {Unit} n - Number to round up
150
 * @returns {Unit} Rounded up value
151
 */
152
function ceil(n);
153

154
/**
155
 * Floor (round down)
156
 * @param {Unit} n - Number to round down
157
 * @returns {Unit} Rounded down value
158
 */
159
function floor(n);
160

161
/**
162
 * Round to nearest integer
163
 * @param {Unit} n - Number to round
164
 * @returns {Unit} Rounded value
165
 */
166
function round(n);
167

168
/**
169
 * Minimum of two values
170
 * @param {Unit} a - First value
171
 * @param {Unit} b - Second value
172
 * @returns {Unit} Minimum value
173
 */
174
function min(a, b);
175

176
/**
177
 * Maximum of two values
178
 * @param {Unit} a - First value
179
 * @param {Unit} b - Second value
180
 * @returns {Unit} Maximum value
181
 */
182
function max(a, b);
183

184
/**
185
 * Sum of list of numbers
186
 * @param {Expression} nums - List of numbers
187
 * @returns {Unit} Sum of all numbers
188
 */
189
function sum(nums);
190

191
/**
192
 * Average of list of numbers
193
 * @param {Expression} nums - List of numbers
194
 * @returns {Unit} Average of all numbers
195
 */
196
function avg(nums);
197

198
/**
199
 * Sine of angle
200
 * @param {Unit} angle - Angle in radians or degrees
201
 * @returns {Unit} Sine value
202
 */
203
function sin(angle);
204

205
/**
206
 * Cosine of angle
207
 * @param {Unit} angle - Angle in radians or degrees
208
 * @returns {Unit} Cosine value
209
 */
210
function cos(angle);
211

212
/**
213
 * Tangent of angle
214
 * @param {Unit} angle - Angle in radians or degrees
215
 * @returns {Unit} Tangent value
216
 */
217
function tan(angle);
218

219
/**
220
 * Arc tangent
221
 * @param {Unit} n - Number
222
 * @returns {Unit} Arc tangent in radians
223
 */
224
function atan(n);
225

226
/**
227
 * Pi constant
228
 * @returns {Unit} Pi value (3.14159...)
229
 */
230
function pi();
231

232
/**
233
 * Square root
234
 * @param {Unit} n - Number
235
 * @returns {Unit} Square root
236
 */
237
function sqrt(n);
238

239
/**
240
 * Power function
241
 * @param {Unit} base - Base number
242
 * @param {Unit} exp - Exponent
243
 * @returns {Unit} Base raised to exponent
244
 */
245
function pow(base, exp);
246
```
247

248
### String Functions
249

250
Functions for string manipulation and processing.
251

252
```javascript { .api }
253
/**
254
 * Get length of string or list
255
 * @param {String|Expression} expr - String or list
256
 * @returns {Unit} Length
257
 */
258
function length(expr);
259

260
/**
261
 * Extract substring
262
 * @param {String} string - Source string
263
 * @param {Unit} start - Start index (0-based)
264
 * @param {Unit} length - Length to extract
265
 * @returns {String} Substring
266
 */
267
function substr(string, start, length);
268

269
/**
270
 * Slice string or list
271
 * @param {String|Expression} val - Value to slice
272
 * @param {Unit} start - Start index
273
 * @param {Unit} end - End index
274
 * @returns {String|Expression} Sliced value
275
 */
276
function slice(val, start, end);
277

278
/**
279
 * Split string by delimiter
280
 * @param {String} delimiter - Delimiter string
281
 * @param {String} val - String to split
282
 * @returns {Expression} List of strings
283
 */
284
function split(delimiter, val);
285

286
/**
287
 * Join values with delimiter
288
 * @param {String} delimiter - Delimiter string
289
 * @param {Expression} vals - Values to join
290
 * @returns {String} Joined string
291
 */
292
function join(delimiter, vals);
293

294
/**
295
 * Replace pattern in string
296
 * @param {String} pattern - Pattern to find
297
 * @param {String} replacement - Replacement string
298
 * @param {String} val - Source string
299
 * @returns {String} String with replacements
300
 */
301
function replace(pattern, replacement, val);
302

303
/**
304
 * Remove quotes from string
305
 * @param {String} str - Quoted string
306
 * @returns {Literal} Unquoted string
307
 */
308
function unquote(str);
309

310
/**
311
 * Add quotes to string
312
 * @param {String} str - String to quote
313
 * @returns {String} Quoted string
314
 */
315
function quote(str);
316

317
/**
318
 * Convert to uppercase
319
 * @param {String} str - String to convert
320
 * @returns {String} Uppercase string
321
 */
322
function uppercase(str);
323

324
/**
325
 * Convert to lowercase
326
 * @param {String} str - String to convert
327
 * @returns {String} Lowercase string
328
 */
329
function lowercase(str);
330
```
331

332
### List Functions
333

334
Functions for manipulating lists and arrays.
335

336
```javascript { .api }
337
/**
338
 * Add values to end of list
339
 * @param {Expression} expr - Base list
340
 * @param {Node} vals - Values to add
341
 * @returns {Expression} Extended list
342
 */
343
function push(expr, vals);
344

345
/**
346
 * Remove last value from list
347
 * @param {Expression} expr - List to modify
348
 * @returns {Node} Removed value
349
 */
350
function pop(expr);
351

352
/**
353
 * Remove first value from list
354
 * @param {Expression} expr - List to modify
355
 * @returns {Node} Removed value
356
 */
357
function shift(expr);
358

359
/**
360
 * Add values to start of list
361
 * @param {Expression} expr - Base list
362
 * @param {Node} vals - Values to add
363
 * @returns {Expression} Extended list
364
 */
365
function unshift(expr, vals);
366

367
/**
368
 * Get keys from object/pairs list
369
 * @param {Expression} pairs - Object or pairs list
370
 * @returns {Expression} List of keys
371
 */
372
function keys(pairs);
373

374
/**
375
 * Get values from object/pairs list
376
 * @param {Expression} pairs - Object or pairs list
377
 * @returns {Expression} List of values
378
 */
379
function values(pairs);
380

381
/**
382
 * Convert object to pairs list
383
 * @param {Object} obj - Object to convert
384
 * @returns {Expression} List of key-value pairs
385
 */
386
function pairs(obj);
387

388
/**
389
 * Get list separator type
390
 * @param {Expression} list - List to check
391
 * @returns {String} Separator type (',' or ' ')
392
 */
393
function listSeparator(list);
394

395
/**
396
 * Reverse list order
397
 * @param {Expression} list - List to reverse
398
 * @returns {Expression} Reversed list
399
 */
400
function reverse(list);
401

402
/**
403
 * Sort list values
404
 * @param {Expression} list - List to sort
405
 * @returns {Expression} Sorted list
406
 */
407
function sort(list);
408
```
409

410
### Type Functions
411

412
Functions for type checking and conversion.
413

414
```javascript { .api }
415
/**
416
 * Get type name of value
417
 * @param {Node} expr - Value to check
418
 * @returns {String} Type name
419
 */
420
function typeOf(expr);
421

422
/**
423
 * Convert unit type
424
 * @param {Unit} unit - Number with unit
425
 * @param {String} type - Target unit type
426
 * @returns {Unit} Converted unit
427
 */
428
function unit(unit, type);
429

430
/**
431
 * Pattern matching
432
 * @param {String} pattern - Regular expression pattern
433
 * @param {String} str - String to match
434
 * @returns {Expression|Null} Match results or null
435
 */
436
function match(pattern, str);
437

438
/**
439
 * Type checking
440
 * @param {Node} val - Value to check
441
 * @param {String} type - Expected type name
442
 * @returns {Boolean} True if value is of type
443
 */
444
function isA(val, type);
445
```
446

447
### Utility Functions
448

449
General utility functions for various operations.
450

451
```javascript { .api }
452
/**
453
 * Parse JSON file
454
 * @param {String} path - Path to JSON file
455
 * @param {Boolean} local - Whether to use local lookup
456
 * @returns {Object} Parsed JSON data
457
 */
458
function json(path, local);
459

460
/**
461
 * Use plugin
462
 * @param {String} plugin - Plugin name
463
 * @param {Object} options - Plugin options
464
 * @returns {Null} No return value
465
 */
466
function use(plugin, options);
467

468
/**
469
 * Get current selector
470
 * @returns {String} Current selector string
471
 */
472
function selector();
473

474
/**
475
 * Get current selectors
476
 * @returns {Expression} List of current selectors
477
 */
478
function selectors();
479

480
/**
481
 * Get current property name
482
 * @returns {String} Current property name
483
 */
484
function currentProperty();
485

486
/**
487
 * Prefix class names
488
 * @param {String} prefix - Prefix to add
489
 * @returns {Null} No return value
490
 */
491
function prefixClasses(prefix);
492

493
/**
494
 * Property lookup in current scope
495
 * @param {String} prop - Property name to lookup
496
 * @returns {Node} Property value or null
497
 */
498
function lookup(prop);
499

500
/**
501
 * Get call location information
502
 * @returns {String} Call location details
503
 */
504
function calledFrom();
505

506
/**
507
 * Throw error with message
508
 * @param {String} msg - Error message
509
 * @throws {Error} Always throws error
510
 */
511
function error(msg);
512

513
/**
514
 * Output warning message
515
 * @param {String} msg - Warning message
516
 * @returns {Null} No return value
517
 */
518
function warn(msg);
519

520
/**
521
 * Get image dimensions
522
 * @param {String} path - Path to image file
523
 * @returns {Expression} List containing [width, height]
524
 */
525
function imageSize(path);
526

527
/**
528
 * Add CSS property dynamically
529
 * @param {String} name - Property name
530
 * @param {Node} expr - Property value
531
 * @returns {Null} No return value
532
 */
533
function addProperty(name, expr);
534
```
535

536
### URL Functions
537

538
Functions for URL processing and embedding.
539

540
```javascript { .api }
541
/**
542
 * Embed URL as data URI
543
 * @param {String} url - URL to embed
544
 * @param {String} enc - Encoding (base64, utf8)
545
 * @returns {Literal} Data URI string
546
 */
547
function embedurl(url, enc);
548

549
/**
550
 * Process URL with optional lookup
551
 * @param {String} path - URL path
552
 * @param {Boolean} lookup - Whether to perform file lookup
553
 * @returns {Literal} Processed URL
554
 */
555
function url(path, lookup);
556
```
557

558
## Usage Examples
559

560
```stylus
561
// Color functions
562
$primary = #3498db
563
$light-primary = lighten($primary, 20%)
564
$dark-primary = darken($primary, 15%)
565
$complement = complement($primary)
566

567
// Math functions
568
$golden-ratio = 1.618
569
$container-width = round(960px / $golden-ratio)
570
$max-width = max(320px, $container-width)
571

572
// String functions
573
$font-stack = 'Helvetica Neue', sans-serif
574
$font-name = unquote(substr($font-stack, 0, 8))
575
$class-list = split(',', 'header,nav,main,footer')
576

577
// List functions
578
$breakpoints = 480px 768px 1024px
579
$mobile-first = unshift($breakpoints, 320px)
580
$breakpoint-count = length($mobile-first)
581

582
// Utility functions
583
$config = json('config.json')
584
$current-sel = selector()
585
$image-dims = image-size('logo.png')
586
```