EPIC Enhanced Programmable IRC-II Client

Functions

EPIC functions accept arguments and return a value. They can manipulate strings and word lists, perform calculations, inspect client state, or perform operations such as file I/O. A function call can have side effects; it is not necessarily a read-only query.

For a broader introduction, see programming. See expressions and expando substitution for how function results fit into statements.

Calling functions

In expanded text, write $name(arguments). In an expression, write name(arguments) without the dollar sign. Arguments are text expanded before the call, usually separated by spaces rather than commas; each function defines its own argument and quoting rules. Empty parentheses supply an empty argument string.

alias measure { echo Length: $strlen($*) }
@ amount = abs(-12)

After defining the alias, /measure hello displays Length: 5. The expression assigns 12 to amount. Do not assume that a function's argument list is an arithmetic expression: use ${...} explicitly when an argument needs calculation.

Names are case-insensitive. An ordinary call prefers a C built-in when a script alias has the same name. $:name(arguments) selects the script alias; $::name(arguments) selects the built-in. If the selected function does not exist, the dispatcher returns an empty string. Empty results can also be valid data or function-specific failures, so consult the individual page before treating an empty result as a success or error indicator.

Scripts define functions using aliases, optionally with an argument list. return value supplies their result; a function alias starts with an empty return value. The functions script is a collection of helpers, not a prerequisite for calling C built-ins.

Functions by domain

The groups below provide navigation through the current interfaces. Each linked page defines the actual arguments, return values, errors, side effects, and requirements. Similar names do not imply identical behavior. In particular, string positions, Unicode code points, display widths, and word indices are different units.

Extracting substrings from strings

Extract, trim, or locate portions of text.

after, before, chop, left, leftpc, mid, rest, right.

String operations

Transform text, inspect characters, and manage formatting.

ascii, asciiq, center, chr, chrq, count, cparse, deuhc, fix_width, getopt, hex, index, insert, is8bit, isalpha, isdigit, isnumber, isutf8, joinstr, maxlen, msar, nohighlight, numlines, pad, pass, printlen, repeat, reverse, rgb, rindex, rsubstr, sar, shiftbrace, split, splitw, stricmp, strip, stripansi, stripansicodes, stripc, stripcrap, strlen, strtol, substr, tolower, toupper, tr, unicode, unsplit, xform.

Word operations

Extract and manipulate word lists; some functions change a named variable.

afterw, beforew, chngw, common, diff, findw, findws, fromw, indextoword, insertw, leftw, midw, notw, numsort, numwords, pop, prefix, push, qword, remw, remws, restw, revw, rightw, shift, sort, sortby, splice, tow, uniq, unshift, word, wordtoindex.

Math functions

Numeric calculations and conversions; domain and range behavior can depend on the platform math library.

abs, acos, acosh, asin, asinh, atan, atanh, ceil, cos, cosh, exp, floor, jn, log, log10, rand, sin, sinh, srand, tan, tanh, tobase, trunc, yn.

Time info

Timestamps, date formatting and parsing, and elapsed-time formatting.

metric_time, mktime, stime, strftime, strptime, tdiff, tdiff2, time, utime.

Pattern matching

Wildcard selection, filename globbing, and regular-expression handles.

cofilter, copattern, corfilter, corpattern, filter, glob, mask, match, pattern, regcomp, regcomp_cs, regerror, regexec, regfree, regmatches, rfilter, rmatch, rpattern.

Server operations

Inspect or control known server connections. Most information queries read cached client state; a control operation can initiate activity.

cipher, isaway, isconnected, isencrypted, myservers, serverctl, serverwin, servports, ssl, usermode, version.

Channel info

Inspect locally known channel state. Results depend on the selected server and information received from it.

chankey, chanlimit, chanmode, channel, chanusers, chansyncing, chops, ischannel, ischanop, ischanvoice, iscurchan, ishalfop, key, mychannels, nochops, numonchannel, onchannel, userhost.

Display operations

Inspect windows, input, status lines, and retained output.

chanwin, curpos, currchans, geom, getcap, inputctl, isdisplaying, lastlog, levelwindow, line, notifywindows, outputinfo, querywin, status, status_oneoff, winchan, windowctl.

Array operations

Use the separate built-in indexed-array facility; see arrays for item numbers versus sorted indices.

delarray, delitem, delitems, finditem, finditems, getarrays, getitem, getmatches, getrmatches, gettmatch, ifindfirst, ifinditem, ifinditems, igetitem, igetmatches, igetrmatches, indextoitem, itemtoindex, listarray, matchitem, numarrays, numitems, rmatchitem, setitem, usetitem.

File I/O

Open, read, write, seek, and inspect files through client-managed handles; open modes and failure values are function-specific.

close, dbmctl, eof, ferror, frewind, fseek, fsize, fskip, ftell, ftime, ftruncate, isfilevalid, open, randread, read, write, writeb.

Client operations

Inspect and control aliases, keybindings, hooks, timers, settings, output levels, logs, encoding, and CTCP handlers.

aliasctl, bindctl, builtin_expando, cexist, check_code, ctcpctl, curcmd, encodingctl, epic, execctl, fix_arglist, fnexist, functioncall, getcommands, getfunctions, getserial, getset, getsets, hookctl, iconvctl, idle, info, irclib, levelctl, loadinfo, logctl, sequence_point, startupfile, symbolctl, tags, timerctl, xdebug.

Network operations

Address conversion and name resolution; availability and returned addresses depend on the host network environment.

convert, iptolong, iptoname, longtoip, nametoip.

System operations

Filesystem and process operations, process environment, identity, and platform security interfaces.

chmod, exec, fexist, getenv, getgid, getlogin, getpgrp, getuid, killpid, mkdir, pid, pledge, ppid, realpath, rename, rmdir, stat, ttyname, twiddle, umask, uname, unlink, unveil.

Miscellanea

Structured data, cryptographic helpers, identifiers, and list generation.

ecdsatool, hash_32bit, jot, json_error, json_explode, json_implode, jsontest, pbkdf2, scrambox, uuid4.

Script-provided functions

Loading builtins supplies compatibility helpers including b64encode, b64decode, encode, decode, urlencode, urldecode, and sha256, implemented through the C xform interface. They are script aliases even though the package is named builtins. Some helpers overlap names still present in C; ordinary-call dispatch continues to prefer the C function.

Other examples are notify, scan, and pipe. These require their scripts to be loaded, and their effects differ: scan formats channel information, while pipe captures command output. A script helper can itself rely on other scripts or on removed interfaces, so use its current documentation rather than assuming that every installed script is operational.

External scripting languages and availability

python and pydirect are registered when EPIC is built with Python support. Their availability and argument rules are separate from EPIC alias functions. Platform-dependent functions, database support, regular-expression backends, security calls, and individual xform transformations also have their own build or platform requirements.

fnexist(name) tests for a registered C built-in, not a script alias. getfunctions() lists built-in function names; aliasctl and symbolctl provide script-symbol inspection. Registration alone is not a guarantee of useful behavior for every argument or build: consult the function's page and check its result. Server-related operations are also subject to connection state and network policy.

Source references