1# Functions Reference
2 
3## Global Functions
4 
5| Function | Signature | Description |
6|----------|-----------|-------------|
7| `date()` | `date(string): date` | Parse string to date. Format: `YYYY-MM-DD HH:mm:ss` |
8| `duration()` | `duration(string): duration` | Parse duration string |
9| `now()` | `now(): date` | Current date and time |
10| `today()` | `today(): date` | Current date (time = 00:00:00) |
11| `if()` | `if(condition, trueResult, falseResult?)` | Conditional |
12| `min()` | `min(n1, n2, ...): number` | Smallest number |
13| `max()` | `max(n1, n2, ...): number` | Largest number |
14| `number()` | `number(any): number` | Convert to number |
15| `link()` | `link(path, display?): Link` | Create a link |
16| `list()` | `list(element): List` | Wrap in list if not already |
17| `file()` | `file(path): file` | Get file object |
18| `image()` | `image(path): image` | Create image for rendering |
19| `icon()` | `icon(name): icon` | Lucide icon by name |
20| `html()` | `html(string): html` | Render as HTML |
21| `escapeHTML()` | `escapeHTML(string): string` | Escape HTML characters |
22 
23## Any Type Functions
24 
25| Function | Signature | Description |
26|----------|-----------|-------------|
27| `isTruthy()` | `any.isTruthy(): boolean` | Coerce to boolean |
28| `isType()` | `any.isType(type): boolean` | Check type |
29| `toString()` | `any.toString(): string` | Convert to string |
30 
31## Date Functions & Fields
32 
33**Fields:** `date.year`, `date.month`, `date.day`, `date.hour`, `date.minute`, `date.second`, `date.millisecond`
34 
35| Function | Signature | Description |
36|----------|-----------|-------------|
37| `date()` | `date.date(): date` | Remove time portion |
38| `format()` | `date.format(string): string` | Format with Moment.js pattern |
39| `time()` | `date.time(): string` | Get time as string |
40| `relative()` | `date.relative(): string` | Human-readable relative time |
41| `isEmpty()` | `date.isEmpty(): boolean` | Always false for dates |
42 
43## Duration Type
44 
45When subtracting two dates, the result is a **Duration** type (not a number). Duration has its own properties and methods.
46 
47**Duration Fields:**
48| Field | Type | Description |
49|-------|------|-------------|
50| `duration.days` | Number | Total days in duration |
51| `duration.hours` | Number | Total hours in duration |
52| `duration.minutes` | Number | Total minutes in duration |
53| `duration.seconds` | Number | Total seconds in duration |
54| `duration.milliseconds` | Number | Total milliseconds in duration |
55 
56**IMPORTANT:** Duration does NOT support `.round()`, `.floor()`, `.ceil()` directly. You must access a numeric field first (like `.days`), then apply number functions.
57 
58```yaml
59# CORRECT: Calculate days between dates
60"(date(due_date) - today()).days"                    # Returns number of days
61"(now() - file.ctime).days"                          # Days since created
62 
63# CORRECT: Round the numeric result if needed
64"(date(due_date) - today()).days.round(0)"           # Rounded days
65"(now() - file.ctime).hours.round(0)"                # Rounded hours
66 
67# WRONG - will cause error:
68# "((date(due) - today()) / 86400000).round(0)"      # Duration doesn't support division then round
69```
70 
71## Date Arithmetic
72 
73```yaml
74# Duration units: y/year/years, M/month/months, d/day/days,
75#                 w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds
76 
77# Add/subtract durations
78"date + \"1M\""           # Add 1 month
79"date - \"2h\""           # Subtract 2 hours
80"now() + \"1 day\""       # Tomorrow
81"today() + \"7d\""        # A week from today
82 
83# Subtract dates returns Duration type
84"now() - file.ctime"                    # Returns Duration
85"(now() - file.ctime).days"             # Get days as number
86"(now() - file.ctime).hours"            # Get hours as number
87 
88# Complex duration arithmetic
89"now() + (duration('1d') * 2)"
90```
91 
92## String Functions
93 
94**Field:** `string.length`
95 
96| Function | Signature | Description |
97|----------|-----------|-------------|
98| `contains()` | `string.contains(value): boolean` | Check substring |
99| `containsAll()` | `string.containsAll(...values): boolean` | All substrings present |
100| `containsAny()` | `string.containsAny(...values): boolean` | Any substring present |
101| `startsWith()` | `string.startsWith(query): boolean` | Starts with query |
102| `endsWith()` | `string.endsWith(query): boolean` | Ends with query |
103| `isEmpty()` | `string.isEmpty(): boolean` | Empty or not present |
104| `lower()` | `string.lower(): string` | To lowercase |
105| `title()` | `string.title(): string` | To Title Case |
106| `trim()` | `string.trim(): string` | Remove whitespace |
107| `replace()` | `string.replace(pattern, replacement): string` | Replace pattern |
108| `repeat()` | `string.repeat(count): string` | Repeat string |
109| `reverse()` | `string.reverse(): string` | Reverse string |
110| `slice()` | `string.slice(start, end?): string` | Substring |
111| `split()` | `string.split(separator, n?): list` | Split to list |
112 
113## Number Functions
114 
115| Function | Signature | Description |
116|----------|-----------|-------------|
117| `abs()` | `number.abs(): number` | Absolute value |
118| `ceil()` | `number.ceil(): number` | Round up |
119| `floor()` | `number.floor(): number` | Round down |
120| `round()` | `number.round(digits?): number` | Round to digits |
121| `toFixed()` | `number.toFixed(precision): string` | Fixed-point notation |
122| `isEmpty()` | `number.isEmpty(): boolean` | Not present |
123 
124## List Functions
125 
126**Field:** `list.length`
127 
128| Function | Signature | Description |
129|----------|-----------|-------------|
130| `contains()` | `list.contains(value): boolean` | Element exists |
131| `containsAll()` | `list.containsAll(...values): boolean` | All elements exist |
132| `containsAny()` | `list.containsAny(...values): boolean` | Any element exists |
133| `filter()` | `list.filter(expression): list` | Filter by condition (uses `value`, `index`) |
134| `map()` | `list.map(expression): list` | Transform elements (uses `value`, `index`) |
135| `reduce()` | `list.reduce(expression, initial): any` | Reduce to single value (uses `value`, `index`, `acc`) |
136| `flat()` | `list.flat(): list` | Flatten nested lists |
137| `join()` | `list.join(separator): string` | Join to string |
138| `reverse()` | `list.reverse(): list` | Reverse order |
139| `slice()` | `list.slice(start, end?): list` | Sublist |
140| `sort()` | `list.sort(): list` | Sort ascending |
141| `unique()` | `list.unique(): list` | Remove duplicates |
142| `isEmpty()` | `list.isEmpty(): boolean` | No elements |
143 
144## File Functions
145 
146| Function | Signature | Description |
147|----------|-----------|-------------|
148| `asLink()` | `file.asLink(display?): Link` | Convert to link |
149| `hasLink()` | `file.hasLink(otherFile): boolean` | Has link to file |
150| `hasTag()` | `file.hasTag(...tags): boolean` | Has any of the tags |
151| `hasProperty()` | `file.hasProperty(name): boolean` | Has property |
152| `inFolder()` | `file.inFolder(folder): boolean` | In folder or subfolder |
153 
154## Link Functions
155 
156| Function | Signature | Description |
157|----------|-----------|-------------|
158| `asFile()` | `link.asFile(): file` | Get file object |
159| `linksTo()` | `link.linksTo(file): boolean` | Links to file |
160 
161## Object Functions
162 
163| Function | Signature | Description |
164|----------|-----------|-------------|
165| `isEmpty()` | `object.isEmpty(): boolean` | No properties |
166| `keys()` | `object.keys(): list` | List of keys |
167| `values()` | `object.values(): list` | List of values |
168 
169## Regular Expression Functions
170 
171| Function | Signature | Description |
172|----------|-----------|-------------|
173| `matches()` | `regexp.matches(string): boolean` | Test if matches |
174