built-in functions

Built-in functions include the following. These function names are not case sensitive. (Other elements of langur are case sensitive.)

general is to I/O
file number string regex
general regex
is to
I/O file
number string

general functions

  • benchmark(FUNCTION)
  • benchmark(FUNCTION, COUNT)

returns string representing time required to execute the FUNCTION, the number of times given by the COUNT (default 1)

The FUNCTION must be one that takes no parameters. COUNT must be a positive integer.

  • bestTag(PREF_TAGS, AVAIL_TAGS)

takes 2 arrays of language tag strings (IETF BCP 47); picks closest available and returns hash with results (including fields such as "tag", "index", and "confidence")

  • execT(STRING)

executes a system command STRING, using a trusted source (not for use with user-provided data)

  • exit()
  • exit(CODE)

exits a script with an integer CODE (default 0), or with 1 if not an integer (does not throw)

  • first(ARRAY)
  • first(STRING)
  • first(RANGE)

returns first element of the ARRAY, STRING, or RANGE

see also last()

  • fold(FUNCTION, ARRAY)

returns value folded by the FUNCTION from the ARRAY

  • foldfrom(FUNCTION, INIT, ARRAYS...)

returns value folded by a FUNCTION from 1 or more ARRAYS, starting with an INIT value

FUNCTION parameter count == number of ARRAYS + 1 for the result (result as first parameter in FUNCTION)

  • good(FUNCTION, ARRAY)
  • good(REGEX, ARRAY)
  • good(FUNCTION, ARRAY, ALT_VALUE)
  • good(REGEX, ARRAY, ALT_VALUE)

returns first element from an ARRAY that a validation FUNCTION or REGEX returns true for

returns ALT_VALUE if no suitable value found (an exception if no ALT_VALUE specified)

see also nn() and ns()

  • group(FUNCTION, ARRAY)
  • group(MAX, ARRAY)

groups ARRAY elements into an array of arrays, based on the return value of a FUNCTION or a MAX count (per grouping)

  • keyExists(HASH, KEY)

checks if KEY exists in HASH (returns Boolean)

  • keys(HASH)

returns array of keys from a HASH (in no guaranteed order)

  • last(ARRAY)
  • last(STRING)
  • last(RANGE)

returns last element of the ARRAY, STRING, or RANGE

see also first()

  • len(ARRAY)
  • len(STRING)
  • len(HASH)

returns the length (as integer) of an ARRAY, HASH, or STRING

STRING length in code points

  • map(FUNCTION, ARRAYS...)
  • map(FUNCTION, HASHES...)

returns array (or hash) of values mapped to a FUNCTION from 1 or more ARRAYS or HASHES

  • nn(ARRAY)
  • nn(ARRAY, ALT_VALUE)

returns first element from an ARRAY that is not null

returns ALT_VALUE if no suitable value found (an exception if no ALT_VALUE specified)

see also ns() and good()

  • ns(ARRAY)
  • ns(ARRAY, ALT_VALUE)

returns first element from an ARRAY that is not special (null, NaN, or Infinity)

returns ALT_VALUE if no suitable value found (an exception if no ALT_VALUE specified)

see also nn() and good()

  • pop(ARRAY)
  • pop(STRING)
  • pop(HASH, KEY)
  • pop(HASH, KEYS)

removes the last element of an ARRAY or STRING or does nothing if the length is 0

...or removes KEY or array of KEYS from HASH (with their values)

may return empty array, string, or hash

does not alter the original ARRAY, STRING, or HASH

see also push() and rest()

  • push(ARRAY, ITEMS...)
  • push(STRING, ITEMS...)

adds 1 or more ITEMS to end of an ARRAY or STRING

for a STRING, may add strings or code points

does not alter the original ARRAY or STRING

see also pop()

  • rest(ARRAY)
  • rest(STRING)

removes the first element of an ARRAY or STRING or does nothing if the length is 0

may return empty array or string

does not alter the original ARRAY or STRING

see also push() and pop()

  • reverse(ARRAY)
  • reverse(RANGE)

returns the reversed ARRAY or RANGE

future development: to reverse a string by Unicode rules
(To reverse a string by code points, use a descending range with an index, such as .s[len(.s)..1; ""] where .s is a string variable.)

  • series(RANGE)
  • series(RANGE, INCREMENT)

generates an array of numbers from a RANGE and INCREMENT (default 1 or -1)

RANGE and INCREMENT not limited to integers

  • sort(FUNCTION, ARRAY)

returns a sorted array, comparing each element by a FUNCTION taking two variables and returning a Boolean such as f .a < .b

  • where(FUNCTION, ARRAY)
  • where(REGEX, ARRAY)
  • where(FUNCTION, HASH)
  • where(REGEX, HASH)

returns array or hash of values that the FUNCTION or REGEX returns true for

may return empty array or hash

number functions

  • abs(NUMBER)

returns the absolute value of a NUMBER

  • ceiling(NUMBER)

returns the least integer equal to or greater than a NUMBER

see also floor()

  • floor(NUMBER)

returns the greatest integer equal to or less than a NUMBER

see also ceiling()

  • round(NUMBER)
  • round(NUMBER, COUNT)

rounds NUMBER to specified digit COUNT after decimal point (default 0)

COUNT < 0 means to simplify (remove trailing zeros)

Rounding is always done with the round-half-even method. A future version might allow for other rounding methods.

see also truncate()

  • simplify(NUMBER)

simplifies NUMBER, removing trailing zeros

  • truncate(NUMBER)
  • truncate(NUMBER, COUNT)

truncates NUMBER to specified digit COUNT after decimal point (default 0)

COUNT < 0 means to simplify (remove trailing zeros)

see also round()

string functions

Some functions, such as split() and replace(), are listed under regex functions, though they aren't just for use with regex.

  • cpToString(INTEGER)
  • cpToString(ARRAY_OF_INTS)

converts code points (integers) into a string

see also stringToCp()

  • join(DELIMITER, ARRAY_OF_STR)

creates a string from ARRAY_OF_STR, using the specified DELIMITER string between each entry

see also split()

  • lcase(STRING)

converts STRING to lowercase

see also ucase() and tcase()

  • lTrim(STRING)

removes preceding Unicode spacing

see also trim() and rTrim()

  • nfc(STRING)

converts STRING to normalization form NFC

see also nfd(), nfkc(), nfkd()

  • nfd(STRING)

converts STRING to normalization form NFD

see also nfc(), nfkc(), nfkd()

  • nfkc(STRING)

converts STRING to normalization form NFKC

see also nfc(), nfd(), nfkd()

  • nfkd(STRING)

converts STRING to normalization form NFKD

see also nfc(), nfd(), nfkc()

  • rTrim(STRING)

removes trailing Unicode spacing

see also trim() and lTrim()

  • stringToCp(STRING)
  • stringToCp(STRING, INDEX)
  • stringToCp(STRING, INDEX, ALTERNATE)

returns code point (integer) or array of code points, or ALTERNATE value for an invalid INDEX

see also cpToString()

  • tcase(STRING)

converts STRING to titlecase

see also ucase() and lcase()

  • trim(STRING)

removes preceding/trailing Unicode spacing

see also lTrim() and rTrim()

  • ucase(STRING)

converts STRING to uppercase

see also lcase() and tcase()

regex

The regex functions understand all regex types available in langur.

To generate a regex object for these functions, you use a regex literal or a compile function (such as reCompile() for re2). You could also assign regex to a variable that may be passed to these functions. The regex is compiled before the functions see it.

In place of a string to test, these functions accept anything and convert it to a string if necessary.

Some of these functions also accept plain strings (not strictly regex functions).

  • index(REGEX, ANYTHING)
  • index(STRING, ANYTHING)
  • index(REGEX, ANYTHING, ALT_RETURN)
  • index(STRING, ANYTHING, ALT_RETURN)

returns 1-based code point range for match

for no match, returns null or ALT_RETURN value

  • indices(REGEX, ANYTHING)
  • indices(STRING, ANYTHING)
  • indices(REGEX, ANYTHING, MAX)
  • indices(STRING, ANYTHING, MAX)

returns array of ranges (empty array if no matches)

  • match(REGEX, ANYTHING)
  • match(REGEX, ANYTHING, ALT_RETURN)

returns matching string

for no match, returns null or ALT_RETURN value

  • matches(REGEX, ANYTHING)
  • matches(REGEX, ANYTHING, MAX)

returns array of matches (empty array if no matches)

  • matching(REGEX, ANYTHING)
  • matching(STRING, ANYTHING)

returns Boolean indicating whether there is a match

  • replace(ANY_SOURCE, REGEX, REPLACEMENT_STR)
  • replace(ANY_SOURCE, STRING, REPLACEMENT_STR)
  • replace(ANY_SOURCE, REGEX, REPLACEMENT_STR, MAX)
  • replace(ANY_SOURCE, STRING, REPLACEMENT_STR, MAX)

returns string with replacements made progressively

  • split(REGEX, ANYTHING)
  • split(STRING, ANYTHING)
  • split(REGEX, ANYTHING, MAX)
  • split(STRING, ANYTHING, MAX)

returns array of strings split by either a REGEX or plain STRING delimiter

  • subindex(REGEX, ANYTHING)

returns array of submatch ranges (empty array if not a match)

  • subindices(REGEX, ANYTHING)
  • subindices(REGEX, ANYTHING, MAX)

returns array of arrays of submatch ranges (empty array if no matches)

  • submatch(REGEX, ANYTHING)

returns array of submatches (empty array if not a match)

  • submatches(REGEX, ANYTHING)
  • submatches(REGEX, ANYTHING, MAX)

returns array of arrays of submatches (empty array if no matches)

  • reCompile(STRING)

returns re2 regex compiled from a STRING

  • reEsc(ANYTHING)

converts ANYTHING to a string, escapes re2 regex metacharacters and returns string

progressive matching

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, index, subindex no
matches, submatches, indices, subindices, split, replace yes

is functions

These functions return a Boolean. They do not throw.

  • isArray
  • isBool
  • isBoolOrNull
  • isBuiltIn

checks for built-in function

  • isCallable

checks for built-in or user-defined function

  • isHash
  • isInfinity
  • isInteger

note: may have zeros after a decimal point and still be an integer

  • isNaN
  • isNull
  • isNumber

excludes NaN and Infinity
also does not check for numeric strings

  • isNumType

includes NaN and Infinity
does not check for numeric strings

  • isPosNumType

checks for a positive number type
includes positive Infinity
does not check for numeric strings

  • isRange
  • isRe
checks for an re2 regex
  • isRegex

checks for any type of regex available in langur

  • isSpecial

checks for a special value (null, NaN, or Infinity)

  • isString

to functions

These functions convert, or attempt to convert a value to another type. Some of them may throw exceptions.

  • toBool(ANYTHING)

The effect of toBool() is different than the "truthiness" used in logical operations.

  • true, "true": true
  • false, "false": false
  • null, "null", NaN, "NaN": false
  • 0, "0": false
  • non-zero number or trimmed non-zero number string: true
  • empty regex: false
  • empty array: false
  • empty hash: false
  • trimmed number string: converted to number and tested
  • unknown string: false
  • other: true

does not throw

  • toBoolOrNull(ANYTHING)
  • true, "true": true
  • false, "false": false
  • null, "null", NaN, "NaN": null
  • 0, "0": false
  • non-zero number or trimmed non-zero number string: true
  • empty regex: false
  • empty array: false
  • empty hash: false
  • trimmed number string: converted to number and tested
  • unknown string: null
  • other: true

does not throw

  • toHash(KEY_VALUE_ARRAY)
  • toHash(KEYS_ARRAY, VALUES_ARRAY)

attempts to create a hash from a single array of keys and values in series, or from parallel arrays of keys and values

see also keys()

  • toNumber(NUMBER)
  • toNumber(BOOLEAN)
  • toNumber(STRING)
  • toNumber(STRING, BASE)

attempts to convert value to a number

excludes NaN and Infinity

see also toNumType() and toString()

  • toNumType(NUMBER)
  • toNumType(BOOLEAN)
  • toNumType(STRING)
  • toNumType(STRING, BASE)

attempts to convert value to a number type

includes NaN and Infinity

see also toNumber() and toString()

  • toString(ANYTHING)
  • toString(INTEGER, BASE)

converts to and returns string

does not throw if no BASE given

see also toNumber() and toNumType()

I/O functions

  • read()
  • read(PROMPT)
  • read(PROMPT, REGEX)
  • read(PROMPT, FUNCTION)
  • read(PROMPT, REGEX, ERR_STRING)
  • read(PROMPT, FUNCTION, ERR_STRING)
  • read(PROMPT, REGEX, ERR_STRING, MAX)
  • read(PROMPT, FUNCTION, ERR_STRING, MAX)
  • read(PROMPT, REGEX, ERR_STRING, MAX, ALT_VALUE)
  • read(PROMPT, FUNCTION, ERR_STRING, MAX, ALT_VALUE)

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 f len(.input) < 20 or a REGEX such as RE/^\d+$/

prints an ERR_STRING if validation fails (default empty string)

tries the MAX number of times given (default 1; -1 == infinite)

may return an ALT_VALUE on final failure instead of an exception

  • write(ARGS...)

writes a string of all arguments to standard out

  • writeErr(ARGS...)

writes a string of all arguments to standard error

  • writeln(ARGS...)

writes a string of all arguments to standard out, appending one system newline

  • writelnErr(ARGS...)

writes a string of all arguments to standard error, appending one system newline

file functions

New file permissions, if not passed, default to 664. In langur, you would write this as 8x664 (NOT 0664 or 664, which would give the wrong number).
  • appendfile(FILENAME, STRING)
  • appendfile(FILENAME, STRING, PERMISSIONS)

appends STRING to given file; creates file if it doesn't exist

see also writefile()

  • readfile(FILENAME)

returns string from given file

  • writefile(FILENAME, STRING)
  • writefile(FILENAME, STRING, PERMISSIONS)

writes STRING to given file

see also appendfile()