Libfawk builtins

Libfawk provides only the bare minimum and leaves everything else (including file handing, string handling and even math functions) for the host application to implement. Those functions are documented at the specific host applications.

This document describes the few builtins all libmawk implementations must have.


Convert val into an integer value. If val is a floating point number, truncate it toward 0 (5.9 will become 5, -5.9 will become -5). If val is a string, it is converted to an integer as a decimal number (up to the first character that can not be interpreted as part of the number, where the conversion stops and the rest of the string is ignored). Values larger than 2^31-1 are not guaranteed to work. If any other type is encountered, 0 is returned.

The return type is always a number.


If var is a string, return the length of the string (number of characters). If var is an array, return the number of (direct) members of the array. These lengths are returned with type number, value is always 0 or larger. For any other input, return NIL.


Delete an array or array member. For array members use the & prefix for getting a reference. Always returns NIL.


Returns 1 if var is an array, 0 else. Return type is a number.

fawk_print(p...), fawk_print_cell(p...)

Print every parameter passed, then a newline, to stdout. If there are more than one parameters, separate them by space. The fawk_print_cell() variant always prints extra information about the cell passed (type, reference counter, length, etc.).

These functions always return NIL.

Note: these calls are provided for debugging & diagnostics and for the example scripts for the documentation. Host applications shall provide a better function for printing messages to whatever channel they see fit. Production scripts should never use the fawk_print*() calls but the calls provided by the host application. Some host applications may even disable fawk_print*(): in that case the functions still exist but do not have any effect.

substr(str, from [,len])

Return a substring of str. The substring starts from the fromth character (counting from 1). If from is less than 1, it is rounded up to 1; if it is beyond the end of the string, empty string is returned.

The optional len parameter determines how many characters are returned. It is an upper bound: if the string has less character from from, less is returned. If len is not specified, the rest if the string from from is returned.


A global string variable that is used as separator for creating the final scalar string index by concatenating multidimensional indices of a multidimensional array reference. In practice: ARR[1,2] is really ARR[1 @ SUBSEP @ 2].


A global numeric variable that is used to indicate the version of the fawk API. This number is increased any time either the C API or the API shown to the scripts have significant change, including feature extension. (It is not increased for bugfixes that do not affect the API).

Since libfawk single source version can use integers for the numeric type, FAWK_API_VER is always an integer value.

This number refers to core libfawk features only. Any host application API may change independently thus needs to be versioned independently using a different method.