Positional parameters are listed before parameters by name.
In the examples below, optional parameters by name are indicated with an assignment operator. If there is no specific default, the value is indicated with a ? mark. Required parameters by name are indicated with the as token, such as by as by.
Parameter expansion is indicated with the triple dot ... operator. If the limits are not 0 to infinity, the triple dot operator will be followed by square brackets, indicating the limits. Parameter expansion only applies to the last positional parameter.
Built-in functions include the following.
| general | is | to | I/O |
| file | number | string | regex |
| general | regex |
| is | to |
| I/O | file |
| number | string |
|
all(over, by=?) over=LIST or HASH if argument by not used, compares based on truthiness returns Boolean indicating whether a validation returns true for all values ...or returns null when given an empty item |
|
any(over, by=?) over=LIST or HASH if argument by not used, compares based on truthiness returns Boolean indicating whether a validation returns true for any values ...or returns null when given an empty item |
|
count(over, by=?) over=LIST or HASH if argument by not used, compares based on truthiness returns count based on validation see also filter(), any(), all() |
|
execT(source) executes a system command source string, using a trusted source (not for use with user-provided data) returns a result or throws an exception see also execTH() |
|
execTH(source) executes a system command source string, using a trusted source (not for use with user-provided data) returns a hash instead of a result or exception see also execT() |
|
exit(code, msg=?) exits a script with an integer code, or with a system-specific generic code if not an integer (does not throw) accepts a bool in place of the code, true meaning success, returning 0, and false meaning failure and returning a system-specific generic code (1 on Linux) accepts an optional msg argument; only if code returned is non-zero, will write msg to standard error, appending a newline |
|
filter(over, by=?) over=LIST or HASH if argument by not used, compares based on truthiness returns list or hash of items based on validation see also count(), any(), all() |
|
fold(...[1..] over, by=?, init=?) over=LISTS/RANGES returns value folded by the FUNCTION from the LIST or RANGE example: accepts integer range in place of a LIST, as implicit series accepts a list of FUNCTIONS in place of FUNCTION, alternating between each for each value FUNCTION parameter count == number of LISTS + 1 for the result (result as first parameter in FUNCTION) see also map(), zip(), mapX() |
|
keys(over) over=HASH, LIST, or STRING returns list of keys from a hash (in no guaranteed order), or the 1-based indices of list or string |
|
len(over) over=HASH, LIST, or STRING returns the length (as integer) of a LIST, HASH, or STRING STRING length in code points |
|
less(over, of=?) over=HASH, LIST, or STRING creates new list, string, or hash, removing the last element, or returns empty item if the length is already 0 ...or leaving out by KEY or list of KEYS, or RANGE does not alter the original LIST, STRING, or HASH may return empty list, string, or hash see also more() |
|
map(...[1..] over, by as by=?) over=LISTS or HASHES returns list (or hash) of values mapped to a FUNCTION from 1 or more LISTS or HASHES accepts integer ranges in place of LISTS, as implicit series accepts a list of FUNCTIONS and no-ops (indicated by underscore) in place of FUNCTION, alternating between each for each value of a list see also fold(), zip(), mapX() |
|
mapX(...[1..] over, by as by=?) over=LISTS returns cross-mapped list of values mapped to a FUNCTION from 1 or more LISTS accepts integer ranges in place of LISTS, as implicit series anything not a list or range becomes an implicit 1-element list see also map(), fold(), zip() |
|
more(with, add=?) with=HASH, LIST, or STRING creates new list, hash, or string, adding 1 or more ITEMS or HASHES does not alter the original LIST, HASH, or STRING for a STRING, may add strings or code points for a HASH, throws on duplicate keys (use concatenation to overwrite keys if desired) see also less() |
|
nn(over, alt=?) returns first element from a list that is not null returns alt value if no suitable value found (an exception if no alt value specified) |
|
reverse(over) over=HASH, LIST, STRING, RANGE, or NUMBER reverses order of LIST or RANGE elements, or digits in a NUMBER reverses STRING by graphemes reverses keys/values of HASH if possible; throws if not possible |
|
rotate(over, distance=?, range=?) over=LIST or INTEGER rotates LIST elements by the DISTANCE given (default 1) positive DISTANCE rotates to the "left" and negative to the "right" for an INTEGER, rotates within RANGE; if outside RANGE, passed through unaltered |
|
series(from, inc=?, asconly=false) generates a list of numbers from a RANGE and INCREMENT (default 1 or -1) may use NUMBER as implicit 1-based range RANGE and INCREMENT not limited to integers |
|
sleep(ms) waits the specified number of milliseconds returns a bool (false if value less than 1) |
|
sort(over, by=?) returns a sorted list or range, comparing each element by a FUNCTION taking two variables and returning a Boolean such as fn{<} alternatively, compares using the less than operator, taking a FUNCTION taking one variable and returing some value, or no function at all |
|
ticks() returns Unix ticks in nanoseconds |
|
zip(...[2..] over, by=?) over=LISTS/RANGES returns new list built by interleaving LISTS alternatively, takes a FUNCTION to determine set of elements to append accepts integer ranges in place of LISTS see also map(), fold(), mapX() |
|
abs(num) returns the absolute value of a NUMBER |
|
atan(num) returns the arctangent of a NUMBER given in radians see also tan(), sine(), cos() |
|
ceiling(num) returns the least integer equal to or greater than a NUMBER see also floor() |
|
cos(num) returns the cosine of a NUMBER given in radians see also sine(), tan(), atan() |
|
floor(num) returns the greatest integer equal to or less than a NUMBER see also ceiling() |
|
gcd(list) returns the greatest common divisor from LIST of numbers see also lcm() |
|
lcm(list) returns the least common multiple from LIST of numbers see also gcd() |
|
max(from) returns the maximum item from a LIST, HASH, RANGE, STRING, or FUNCTION for STRING, returns the maximum code point number for FUNCTION, returns the maximum positional parameter count (-1 for no maximum) see also min(), minmax() |
|
mean(from) returns the mean (average) from a LIST, HASH, or RANGE of values see also mid() |
|
mid(from) returns the mid-point from a LIST, HASH, or RANGE of values see also mean() |
|
min(from) returns the minimum item from a LIST, HASH, RANGE, STRING, or FUNCTION for STRING, returns the minimum code point number for FUNCTION, returns the minimum positional parameter count see also max(), minmax() |
|
minmax(from) returns the minimum to maximum range of items from a LIST, HASH, RANGE, STRING, or FUNCTION for STRING, returns the code point numbers for FUNCTION, returns the positional parameter counts (-1 for no maximum) see also max(), min() |
|
random(from) for an INTEGER, returns 0 if 0, a random number from 1 to the INTEGER if positive, or -1 to the INTEGER if negative for a non-empty LIST, HASH, or STRING, or a RANGE, returns 1 element at random (code point for a STRING) all numbers within limits of a signed 64-bit integer |
|
round(num, places=0, addtrailing=true, mode=?) rounds NUMBER to specified digit PLACES after decimal point (default 0) accepts negative PLACES to indicate to round on the integer portion ADDTRAILING specifies whether to add trailing zeroes to reach scale (default true) Rounding mode defaults to round half away from zero, and a rounding mode can be set. Use the _round hash to specify a mode. see also trunc() |
|
simplify(num) simplifies NUMBER, removing trailing zeros |
|
sine(num) returns the sine of a NUMBER given in radians see also cos(), tan(), atan() |
|
tan(num) returns the tangent of a NUMBER given in radians see also atan(), sine(), cos() |
|
trunc(num, places=0, addtrailing=true) truncates NUMBER to specified digit PLACES after decimal point (default 0) accepts negative PLACES to indicate to truncate on the integer portion ADDTRAILING specifies whether to add trailing zeroes to reach scale (default true) see also round() |
Some functions, such as split() and replace(), are listed under regex functions, though they aren't just for use with regex.
|
b2s(bytes) converts UTF-8 byte or byte list into a string see also s2b(), s2cp(), s2gc(), cp2s(), s2s(), s2n() |
|
cp2s(cp) converts code points (integers), and code point lists, into a string accepts integer RANGE in place of list also accepts embedded lists and ranges of integers (within lists); could have a list of lists of integers representing grapheme clusters see also s2cp(), s2gc(), s2s(), s2b(), b2s(), s2n() |
|
join(list, by=zls) creates a string from LIST, using the specified DELIMITER string between each entry uses see also split(), cp2s() |
|
lcase(from) converts STRING to lowercase accepts an INTEGER representing a code point see also ucase() and tcase() |
|
ltrim(str) removes preceding Unicode spacing see also trim() and rtrim() |
|
nfc(str) converts STRING to normalization form NFC see also nfd(), nfkc(), nfkd() |
|
nfd(str) converts STRING to normalization form NFD see also nfc(), nfkc(), nfkd() |
|
nfkc(str) converts STRING to normalization form NFKC see also nfc(), nfd(), nfkd() |
|
nfkd(str) converts STRING to normalization form NFKD see also nfc(), nfd(), nfkc() |
|
rtrim(str) removes trailing Unicode spacing see also trim() and ltrim() |
|
s2b(str) returns UTF-8 byte list see also b2s(), s2cp(), s2gc(), cp2s(), s2s(), s2n() |
|
s2cp(str, of=?, alt=?) returns code point (integer) or list of code points, or ALTERNATE value for an invalid INDEX see also cp2s(), s2s(), s2b(), b2s(), s2n() |
|
s2gc(str) returns a list of code points and grapheme clusters (lists) from a string see also cp2s(), s2cp(), s2s(), s2b(), b2s(), s2n() |
|
s2n(from) returns list of numbers from a STRING or a single number from an INTEGER (code point), assuming base 36 ... so that the letter A or a is 10 and Z or z is 35. see also s2cp(), s2gc(), cp2s(), s2s(), s2b(), b2s() |
|
s2s(str, of=?, alt=?) returns string built by index, or ALTERNATE value for an invalid INDEX see also s2cp(), s2gc(), cp2s(), s2b(), b2s(), s2n() |
|
tcase(from) converts STRING to titlecase accepts an INTEGER representing a code point see also ucase() and lcase() |
|
trim(str) removes preceding/trailing Unicode spacing see also ltrim() and rtrim() |
|
ucase(from) converts STRING to uppercase accepts an INTEGER representing a code point see also lcase() and tcase() |
The regex functions understand all regex types available in langur.
To generate a regex object for these functions, you use a regex literal (such as re/pattern/) or a compile function (such as reCompile()). You could also assign regex to a variable that may be passed to these functions. The regex is compiled before the functions see it.
For the pattern, some of these functions accept plain strings (not strictly regex functions).
These functions use
|
index(anything, by as by=?, alt=?) returns 1-based code point range for match for no match, returns null or alternate value |
|
indices(anything, by as by=?, max=-1) returns list of ranges (empty list if no matches) |
|
match(anything, by as by=?, alt=?) returns matching string for no match, returns null or ALT_RETURN value |
|
matches(anything, by as by=?, max=-1) returns list of matches (empty list if no matches) |
|
matching(anything, by as by=?) returns Boolean indicating whether there is a match |
|
replace(anything, by as by=?, with=zls, max=-1) returns string with replacements made progressively with replacement STRING or by FUNCTION used with REGEX, the replacement string (with) may contain submatches, using $1, $2, etc. may also use a list of replacement strings, functions, and no-ops, alternating between each in turn (except that using with REGEX doesn't allow multiple string replacements so far) |
|
split(anything, by=zls, max=-1) returns list of strings split by either a REGEX or plain STRING delimiter if passed 1 argument, delimiter defaults to zero-length string (split into code point strings) accepts INTEGER to split by (into code point strings); negative INTEGER splits "from the right" see also join(), s2cp(), s2gc(), s2b(), s2n() |
|
subindex(anything, by as by=?) returns list of submatch ranges (empty list if not a match) |
|
subindices(anything, by as by=?, max=-1) returns list of lists of submatch ranges (empty list if no matches) |
|
submatch(anything, by as by=?) returns list of submatches (empty list if not a match) |
|
submatchH(anything, by as by=?) returns hash of whole match and submatches (empty hash if not a match) includes whole match with key 0 includes named captures twice (once with string key and once with number key) |
|
submatches(anything, by as by=?, max=-1) returns list of lists of submatches (empty list if no matches) |
|
submatchesH(anything, by as by=?, max=-1) returns list of hashes of whole matches and submatches (empty list if no matches) includes whole match with key 0 includes named captures twice (once with string key and once with number key) |
|
reCompile(from) returns re2 regex compiled from a pattern STRING |
|
reEsc(from) converts ANYTHING to a string, escapes re2 regex metacharacters and returns string |
What is often called "global" matching we're calling "progressive." You can limit the results of these functions by passing a maximum count.
| functions | progressive? |
|---|---|
| matching, match, submatch, submatchH, index, subindex | no |
| matches, submatches, submatchesH, indices, subindices, split, replace | yes |
Use the is and is not operators with type names to verify a type. This is covered on the type page.
Use a call on a type name as shown below.
These convert, or attempt to convert a value to another type. Some of them may throw exceptions.
|
datetime(from, fmt=?) generates a date-time value given a STRING without a format, attempts to parse as it does for date-time literals (ISO 8601) given a STRING with a format string, attempts to parse by the Go time package (Note that, having tested the time package with Go 1.14.1 on Linux, it does not parse all time zone abbreviations, such as EST, correctly. It not only fails to parse them, but does so silently.) given a NUMBER, will convert from nanoseconds to date-time value given a HASH, will convert based on hash values given a DATETIME without a time zone (fmt), it is passed through unaltered time zone string (fmt) may be anything recognized by the Go time package, such as "US/Arizona", or may be an empty string (local time zone) or "Z" (UTC), or a string offset, such as "-07:00" |
|
duration(from) generates a duration value given a STRING, attempts to parse as it does for duration literals (ISO 8601) given a NUMBER, will convert from nanoseconds to duration value given a HASH, will convert based on hash values given a DURATION, it is passed through unaltered |
|
hash(...[1..2] from) attempts to create a hash from a single list of keys and values in series, or from parallel lists of keys and values, or from a DATETIME or DURATION value will pass through a HASH value accepts ranges in place of lists |
|
number(from, fmt=?) attempts to convert value to a number given a BOOLEAN, returns 1 for true and 0 for false given a DATETIME, returns Unix nanoseconds since the start of January 1, 1970 UTC given a DURATION, converts to nanoseconds (as well as possible); years and months hard to define in this way accepts a numeric RANGE, returning a prospective count for an integer range (if were to be converted to a list of elements) given a STRING, attempts conversion using base 10, unless a base is specified (fmt) given a NUMBER, it is passed through unaltered see also string(), s2n(), datetime() |
|
string(from, fmt=?) converts to and returns string does not throw if no fmt given given a DATETIME with no format (fmt), returns ISO 8601/RFC 3339 timestamp given a DATETIME with format (fmt), attempts to create string based on format given a DURATION, returns ISO 8601 duration string given an INTEGER with base (fmt), converts using base given an ANYTHING ELSE, converts to a string |
|
bool(from) converts to a Boolean based on the truthiness of a value |
|
read(prompt=zls, validation=?, errmsg=zls, maxattempts=1, alt=?) (optional) validation=REGEX or FUNCTION reads a string from standard in may print a prompt string to standard out for each attempt may use validation via a FUNCTION taking one argument such as fn in: len(in) < 20 or a REGEX such as RE/^\d+$/ prints an errmsg if validation fails (default empty string) tries the maxattempts number of times given (default 1; -1 == infinite) may return an alt value on final failure instead of an exception |
|
write(...from) writes a string of all arguments to standard out |
|
writeErr(...from) writes a string of all arguments to standard error |
|
writeln(...from) writes a string of all arguments to standard out, appending one system newline |
|
writelnErr(...from) writes a string of all arguments to standard error, appending one system newline |
New file permissions, if not passed, default to the file permissions mode, which defaults to 664 (in base 8). In langur, you would write this as 8x664 (NOT 0664 or 664, which would give the wrong number (as base 10)).
|
appendfile(file, contents, perm=?) (optional) perm=code from 0 to 8x777 (if new file) appends content string to given file; creates file if it doesn't exist see also writefile() |
|
cd(path=?) changes working directory of the current script to the path or throws an exception returns the present working directory has no effect on parent processes |
|
prop(path) returns a hash of properties from path file or directory, if it can be determined at time of execution; otherwise returns null |
|
readfile(file) returns string from given file |
|
writefile(file, contents, perm=?) (optional) perm=code from 0 to 8x777 writes STRING to given file see also appendfile() |