icmscript(7)

📦
version 13.07.00 · 7 versions
, in arch rolling

💖 icmscript(7) — The icmake scripting language 💖

okay so bestie, welcome to The icmake scripting language — literally the whole vibe of this page 💅

Icmake(1) is a generic tool that handles program maintenance, and yes, it can be used as an alternative for make(1). It’s “generic” because icmake-scripts are written in a language that closely resembles the C programming language, and those scripts can do tasks that are traditionally the domain of scripting languages. slay ✨

Icmake lets programmers use a programming language — again, closely resembling C — to define the actions required for (complex) program maintenance. For this, icmake offers various special operators plus a set of support functions that have shown their usefulness in program maintenance. iconic behavior, honestly 👑

This man-page covers the icmake scripting language in the following sections:

  • DATA TYPES — int, list, string, and void (for functions);
  • OUTLINE — outline of icmake scripts: what their requirements are, the structure and organization of their main-functions.
  • PREPROCESSOR DIRECTIVES — supported preprocessor directives, like #include and #define;
  • PREDEFINED CONSTANTS — like O_FILE, OFF, and S_IFREG;
  • OPERATORS — like +, younger, and casts
  • FLOW CONTROL — if, for, while, etc. (the switch is not available);
  • PREDEFINED FUNCTIONS — executing programs, changing directories, operations on string and list type variables, etc. Functions are marked as INT FUNCTIONS, LIST FUNCTIONS, STRING FUNCTIONS
  • USER DEFINED FUNCTIONS — at least main, with or without its common parameters argc, argv, and envp.

🌸 DATA TYPES 🌸

Icmake supports the following five data and value types:

  • ASCII character constants — ASCII character constants are ascii-characters surrounded by single or double quotes. Single characters (e.g., ’a’) represent the character itself. Standard escape sequences (e.g., ’\n’) are supported and are converted to their well-known values (e.g., ’\n’ represents ascii value 10 (decimal)). Non-standard escape sequences (e.g., ’\x’) are converted to the ascii character following the escape character (so ’\x’ equals ’x’). Escaped sequences consisting of three octal digits represent the ascii character corresponding to the octal value, modulo 256 (e.g., ’\113’ represents ’K’). Escape sequences consisting of an x followed by two hexadecimal digits represent the ascii character corresponding to the hexadecimal value (e.g., ’\x4b’, also representing ’K’);
  • int — integral values, ranging from -0x8000 through 0x7fff. int constants may be specified as decimal numbers (starting with digits 1 through 9), octal numbers (starting with 0, followed by one or more octal digits), hexadecimal numbers (starting with 0x, followed by one or more hexadecimal digits), or as ASCII character constants;
  • string — text values: text (or string) constants are delimited by double or single quotes. Multiple string constants may be concatenated, but a single string constant may not span multiple lines. Multiple string constants, only separated by white space (i.e., blanks, newlines, comment) are concatenated and are considered one single string constant. To indicate an end-of-line in a string constant use the \n escape sequence;

If arithmetic expressions use at least one int operand then those expressions may also contain single character ASCII constants using double or single quotes. In those cases they represent the ascii-values of their characters.

Conversely, ASCII character constants using single quotes may be used in situations where string operands are expected;

  • list — a list is a data structure containing a series of individually accessible string values. When a list contains elements, its first element has index 0;

Lists may be written to the standard output stream or to file (using printf or fprintf). Lists can also be inserted into string variables using the function strformat. In these cases all (space delimited) elements of the lists are inserted into their destinations;

Lists can also be defined as constants. They consist of an optional series of comma separated string constants surrounded by a pair of square brackets. E.g.,

list words = ["a", "list", "constant"];
  • void — the type void is used when defining functions which do not return values. Alternatively, functions may return int, string or list values (cf. section USER DEFINED FUNCTIONS).

Variables can be defined at the global level and inside functions (not only at the top of compound statements but also between statements and in the initialization section of for- and if-statements). When defined inside functions, the standard C scoping and visibility rules apply. Variables are strongly typed, and cannot have type void.

Variables may be initialized when they are defined. Initializations are expressions which may use predefined or user-defined functions, constant values, and values of variables. Functions or variables that are used for initialization must be visible at the initialization point.

🦋 OUTLINE 🦋

Icmake scripts require a user-defined function main. The function main has three optional parameters, which may be omitted from the last one (envp) to the first one (argc), like in C. Its full prototype is:

void main(int argc, list argv, list envp)

or

int main(int argc, list argv, list envp)

When a void main function ends (using a return; statement or when its execution reaches its body’s closing curly) the value 0 is returned to the operating system. When int main functions end using return statements then those statements must be provided with int-expressions. It’s OK when the execution of an int main function reaches its body’s closing curly, in which case 0 is automatically returned to the operating system.

In main the parameter

  • argc represents the number of elements in argv;
  • argv contains the arguments, with element 0 being equal to the name of the .bim file, that were passed to the .bim file. The OPTIONS section of the icmake(1) manpage covers how these arguments are forwarded to the icmake script using options -e, -s, and -t.
  • envp contains the environment variables. The function listlen can be used to determine the number of its elements. Elements in envp use the format variable=value. Alternatively, the (predefined) function getenv can be used to retrieve a specific environment variable immediately.

Example (the implementations of the user-defined functions usage, modified, and compile are left as an exercise for the reader):

void main(int argc, list argv)
{
    if (argc == 1)
        usage(argv[0]);

    if (list toCompile = modified("*.cc"))
    {
        for (int idx = listlen(toCompile); idx--; )
            compile(toCompile[idx]);
    }
}

When executing an icmake script icmake’s run-time support system first initializes all all global variables in the order of their definitions. Following this the function main is called. The script ends when main returns or when the function exit is called by the script.

✨ PREPROCESSOR DIRECTIVES ✨

okay bestie, before your icmake script even gets actually compiled, it first goes through the icmake pre-processor. That little stage removes comments, includes files specified by include-directives, and processes #define and comparable directives. Basically it’s the backstage crew fixing your fit before the main-character compilation walks out. 💅

The following preprocessor directives are recognized:

  • comment — standard C comment (everything from /* through */) as well as comment-to-end-of-line (starting at //, continuing to the end of the line) is ignored. poof, gone 🫥
  • Shell startup — the first line of the icmake-script may start with #!path, where path defines the (usually absolute) location of the icmake program. By making the script executable, it can be called without explicitly calling icmake.

E.g., if the first line of an (executable) icmake script icm (without extension) contains

#!/usr/bin/icmake -t.

then icm can be issued as a command, interpreting the remaining lines of the script as an icmake source which is compiled and then executed by icmake. The icmake(1) man-page’s section EXECUTING ICMAKE SCRIPTS covers the elements of the first line of icmake scripts. ✨

  • #include "filename" — the file filename is included at the location of the directive. drop it right there 🎀
  • #include <filename> — the file filename is included at the location of the #include directive; filename is searched in the colon-separated directories specified by the IM environment variable. The first occurrence of filename in the directories specified by the IM environment variable is used. first one wins, periodt 👑
  • #define identifier [definition] — the text identifier is replaced by definition. The definition may contain references to already defined identifiers, using the syntax ${identifier}. If the ${identifier} hasn’t been defined (yet), the literal text ${identifier} is used. To prevent infinite recursion at most 100 ${identifier} replacements are accepted. no infinite-loop era 💀

If the last character on a line is a backslash (\) then definitions continue at the next line. (the backslash is not included in the definition). The preprocessor concatenates double-quoted strings. Double quoted strings themselves may not span multiple lines. Multiple blanks (outside of double quoted strings) in definitions are contracted to a single space character.

Following the #define’s identifier a definition may optional be provided. If omitted, the macro is defined, so it can be used in #if(n)def directives (see below), but in those cases these identifiers are simply removed from icmake code statements.

  • #ifdef identifier — if the identifier macro was defined the next block of code (until a matching #else or #endif directive was read) is byte-compiled. Otherwise, the code block is ignored. 🧚
  • #ifndef identifier — if the identifier macro was not defined the next block of code (until a matching #else or #endif directive was detected) is byte-compiled. Otherwise, the code block is ignored. same vibe, opposite check 🦋
  • #else — terminates #ifdef and #ifndef code blocks, reversing the acceptance decision about the following code block. Only one #else directive can be associated with #if(n)def directives. one and done 🌸
  • #endif — terminates the code block starting beyond the matching #ifdef, #ifndef or #else directive. Associated #if(n)def, #else, and #endif directives must be specified in the same file. keep the whole little family in the same file, okay? 🫶
  • #undef identifier — remove identifier from the set of defined symbols. This does not affect the specification of any previously defined symbols using identifier’s definition. If identifier hasn’t been defined a warning is issued. heads up, not drama 🙈

✨ PREDEFINED CONSTANTS ✨

The following predefined int constants are available (the functions listed in the intended for column are described in the upcoming sections covering the predefined functions):

  • O_ALL — value 8, intended for makelist
  • O_DIR — value 2, intended for makelist
  • O_FILE — value 1, intended for makelist
  • O_SUBDIR — value 4, intended for makelist
  • OFF — value 0, intended for echo
  • ON — value 1, intended for echo
  • P_CHECK — value 0, intended for system calls
  • P_NOCHECK — value 1, intended for system calls
  • S_IEXEC — value 32, intended for stat
  • S_IFCHR — value 1, intended for stat
  • S_IFDIR — value 2, intended for stat
  • S_IFREG — value 4, intended for stat
  • S_IREAD — value 8, intended for stat
  • S_IWRITE — value 16, intended for stat

The following constants are architecture dependent — each one is 1 when defined on the platform, otherwise 0:

  • unix — Unix, usually with GNU’s gcc compiler
  • UNIX — may alternatively be available
  • linux — x86 running Linux (usually with gcc)
  • LINUX — may alternatively be available
  • M_SYSV, M_UNIX — x86 running SCO/Unix
  • _POSIX _SOURCE — Unix with Posix compliant compiler
  • __hpux — HP-UX, with the native HP compiler

💅 OPERATORS 💅

Okay so real talk — since icmake version 10.00.00 the << operator can be used like the C++ insertion operator. Like, literally the same vibe. Peep the description of the functions printf and fprintf below for the full tea. 🔥

int-operators

Every single C operator is available (yes, including the ternary operator), except for pointer operators — because icmake does not support pointers, periodt. They all operate exactly like their C-programming-language counterparts. Comparison operators return 1 if the comparison is true, otherwise 0 is returned. Simple as that, bestie. ✨

string-operators

For string variables and/or constants the following operators are available, where lhs and rhs are string variables or constants:

  • lhs + rhs — returns a new string value containing the concatenation of strings lhs and rhs. And ngl, string constants can also be directly concatenated without the + operator, like the following two lines both define the string "hello world":
"hello "   "world"
"hello " + "world"
  • lhs += rhs — lhs must be a string variable, to which the string variable or value rhs is appended. 🫶
  • string comparisons — operators == != <= >= < > != and == return 1 if the comparison is true, otherwise 0. The ordering operators (like < and >=) use the (case sensitive) character ordering defined by the ASCII character set. iykyk 💅
  • !lhs — the boolean ! (not) operator returns 1 if the string lhs is empty, otherwise 0 is returned. Strings merely containing white-space characters are not empty. Sneaky little things.
  • lhs younger rhs, lhs newer rhs — returns 1 if file lhs is more recent than file rhs. E.g., "source.cc" newer "source.o". The files lhs and rhs do not have to exist, which is kind of iconic of them:
    • if both don't exist 0 is returned,
    • if lhs doesn't exist 0 is returned,
    • if rhs doesn't exist, 1 is returned,
    • if they are equally old 0 is returned.

The function exists() (see below, section PREDEFINED FUNCTIONS) can be used to test whether a file exists. 🦋

  • lhs older rhs — returns 1 if file lhs is older than file rhs. E.g., "libprog.a" older "source.o". Same deal, the files lhs and rhs do not have to exist:
    • if both don't exist 0 is returned,
    • if lhs doesn't exist 1 is returned,
    • if rhs doesn't exist, 0 is returned,
    • if they are equally old 0 is returned.
  • [] — the index operator returns a character from a string variable or constant. A string is returned as an rvalue. So the following statement compiles OK:
lhs = rhs[3];

but the following statement won't compile (as lhs[3] is an rvalue):

lhs[3] = "a";

If an invalid (out of bounds) index value is specified an empty string is returned. No crash, no drama, just emptiness. 💀

  • The backtick operator (string cmd) — a string placed between two backticks is executed as a separate command. Different from the exec and system calls, the backtick operator collects the standard output produced by cmd and returns this output as a list. 🎀

The elements of the list contain the subsequent lines of output (including a final newline, if present) produced by cmd. A command that could be executed but that did not produce any output returns a list containing one string element, which is empty.

An empty list indicates that the command could not be executed. 😭

The command's standard error stream output is ignored by the backtick operator. However, standard shell redirection may be used to collect the standard error stream's output. Clever, right?

Example:

printf << `"ls"`;   // prints the elements in
                    // the current directory

Note that the backtick operator requires a string argument: either a string constant or a string variable.

The function eval(string cmd) behaves exactly like the backtick operator: they are synonyms. Two names, one queen. 👑

list-operators

For list variables and/or values the following operators are available:

  • lhs + rhs — returns a new list value containing the concatenation of the values of lists lhs and rhs. Heads up: this is not a set operation — if an element appears both in lhs and in rhs, then both will appear in the resulting list (set-addition is provided by the function listunion). So yes, duplicates, we love that for us. ✨
  • lhs - rhs — returns a new list value containing the elements in lhs that are not present in rhs. This is a set-difference operation. The ordering of the remaining elements in the returned list is equal to the ordering of those elements in lhs. 🧚
  • lhs += rhs — elements in rhs are added to the elements in lhs, which must be a list variable. This is not a set operation.
  • lhs -= rhs — elements in rhs are removed from the elements in lhs. This is a set operation: all elements of lhs that are found in rhs are removed from lhs. The ordering of the remaining elements in lhs is not altered. Ship intact, no notes. 🫶
  • list equality comparisons — operators != and == may be applied to list values or variables. Operator == returns 1 if both lists have element-by-element identical elements, otherwise 0 is returned. Operator != reverses the result of ==.
  • !lhs — the boolean ! operator returns 1 if the list lhs is empty, otherwise 0 is returned.
  • [] — the index operator retrieves an element from a list variable: it returns a string as an rvalue. So the following statement compiles OK:
// assume lst is a list, str is a string
str = lst[3];

but the following statement won't compile (as lst[3] is an rvalue):

lst[3] = str;

If an invalid (out of bounds) index value is specified an empty string is returned. Again: no drama, just vibes and an empty string. 🌸

casting

Type-casts using the standard C-style cast-operator can be used to cast:

  • strings to ints and vice versa ((int)"123", (string)55) — if the content of a string does not represent a (decimal) int value 0 the cast returns 0. Rude but fair. 😭
  • Strings to lists (list lst = (list)"hello") — this returns a list having one element (hello). Note that casting a string to a list as shown is overkill, as list lst = ["hello"] performs the same initialization. Lowkey the longer way around, but it works. 💜

🌈 FLOW CONTROL 🌈

Icmake offers a subset of C's flow control statements. They can be used as in the C programming language. No surprises, no plot twists. ✨

  • expression ; — the plain expression statement.

Insert-expression statements are defined for the functions fprintf and printf. Expression statements may start with printf << or fprintf << filename <<. The values of all subsequent expressions, separated by << operators (which in this context are called insertion operators) are written to the standard output stream (when using printf <<), or to the file whose name is provided in the string filename (when using fprintf << filename <<). Examples:

printf << "hello" << ' ' << "world" << '\n';
fprintf << "out.txt" << "hello" << ' ' << "world" << '\n';
  • The compound statement — variables may be defined and initialized inside compound statements at locations where expression statements can also be used. The visibility of variables starts at their points of definition. Main character energy: they exist from the moment they're introduced. 👑
  • if ([definition;] condition) statement — the [definition;] phrase is optional. If used it defines a type followed by a comma-separated list of variables which may be provided with initialization expressions.

The condition phrase is required, and may define and initialize a variable. E.g,

if (string str = getText())
    process(str);

In this example, process is not called if getText() returns an empty string.

Variables defined in the definition and condition phrases do not exist either before or after the if statement. They said "right place, right time" and dipped. 💅

  • if ([definition;] condition) statement1 else statement2 — acts like the previous statement. If the condition is true statement1 is executed; if the condition is false statement2 is executed.
  • for (init; condition; increment) statement — variables (of a single type) may be initialized (and optionally defined) in the init section. The condition phrase may define and initialize a variable. The init, condition and increment sections may remain empty. An empty condition section is interpreted as always true. So yeah, an empty condition is just infinite confidence. 🔥
  • while (condition) statement — inside the condition a variable may be defined and initialized.

A complementary do ... while() statement is not available. Sad, but we cope.

Note that when a variable is defined and initialized in the condition section the initialization expression is executed at each iteration of the while statement. Thus the following statement never ends, and displays a never ending stream of values 10:

while (int x = 10)
    printf(x--, "\n");

That one's a trap, bestie — it literally never ends. 💀

  • return;, and return expression; — plain return statements can be used in void functions, and return expression statements are used in other type of functions.
  • break — break; statements can only be used in for and while statements, ending those statements. Exit the chat. 🚪
  • continue — continue; statements can only be used in for and while statements, continuing their next iteration. Not leaving, just skipping ahead. 🦋

🎀 PREDEFINED FUNCTIONS 🎀

Icmake provides the following predefined functions, which can be used anywhere in icmake scripts. In the following overview the functions are ordered by categories, and within categories they are ordered alphabetically by function name. Organized, alphabetical, aesthetically flawless. 👑

Five categories are distinguished:

  • Functions operating on ints (see INT FUNCTIONS below) — these functions receive int arguments, processing those arguments;
  • Functions operating on strings (see STRING FUNCTIONS below) — these functions operate on the strings which are passed to these functions as arguments;
  • Functions operating on lists (see LIST FUNCTIONS below) — these functions operate on the lists which are passed to these functions as arguments;
  • Functions manipulating file system entries (see FILESYSTEM FUNCTIONS below) — these functions receive the names of file-system entries (files, directories, etc.) as their string arguments. 🍓

okay so real quick heads-up bestie — these functions are not listed in the STRING FUNCTIONS section, and that's on purpose 💅 they don't actually operate on the string arguments you hand them, they just use those arguments to point at entries in the file system. no cap.

meanwhile stuff like change_base doesn't touch file-system entries at all, which is exactly why that one is an entry in the STRING FUNCTIONS section. the way that logic just... works 🦋

  • system-related functions (peep SYSTEM FUNCTIONS below 👇): these interface to facilities provided by the operating system — like executing programs, or changing the script's environment variables. some of these functions use specialized support functions, and those are hanging out in this section too 🫶

🎀 INT FUNCTIONS 🎀

  • string ascii(int value) — returns value as a string: ascii(65) returns the string "A" ✨
  • echo(int opt) — controls echoing of called programs (and their arguments). specify OFF if echoing is not requested. by default echo(ON) is active 👑

🌸 STRING FUNCTIONS 🌸

  • int ascii(string str) — returns the first character of str as an int: ascii("A") returns 65;
  • string change_base(string file, string base) — returns file whose base name is changed into base: change_base("/path/demo.im", "out") returns "/path/out.im";
  • string change_ext(string file, string ext) — returns file whose extension is changed into ext: change_ext("source.cc", "o") returns "source.o". the extension of the returned string is separated from the file's base name by a single dot (e.g., change_ext("source.", ".cc") returns "source.cc");
  • string change_path(string file, string path) — return file whose path is changed into path: change_path("tmp/binary", "/usr/bin") returns "/usr/bin/binary". to remove the path, specify path as an empty string 🌈
  • string element(int index, string var) — acts identically to the index operator: refer to the index ([]) operator in section OPERATORS;
  • string get_base(string file) — returns the base name of file. the base name is the file without its path prefix and without its extension. the extension is all information starting at the final dot in the filename. if no final dot is found, the file name is the base name. e.g., the base name of a.b equals a, the base name of a.b.c equals a.b, the base name of a/b/c equals c 💖
  • string get_dext(string file) — returns the extension of file, including the separating dot (hence the d in dext). the extension is all information starting at the filename's final dot. if file doesn't have a final dot then an empty string is returned;
  • string get_ext(string file) — returns the extension of file, without the separating dot. the extension is all characters in file starting at file's final dot. if no final dot is found, an empty string is returned;
  • string get_path(string file) — returns file's path-prefix. the path prefix is all information up to (and including) the final directory separator (which is, depending on the operating system, a forward slash or a backslash). if file does not contain a path-element, then an empty string is returned;
  • string resize(string str, int newlength) — returns a copy of string str, resized to newlength characters. if newlength is negative then an empty string is returned; if newlength exceeds str's length then the newly added characters are initialized to blank spaces 🎀
  • int strchr(string str, string chars) — returns the first index in str where any of the characters in chars is found, or -1 if str does not contain any of the characters in chars;
  • int strfind(string haystack, string needle) — returns index in haystack where needle is found, or -1 if needle is not found in haystack;
  • string strformat(string format, argument(s)) — returns a string constructed from the format string containing placeholders %1 .. %2 to refer to arguments following the format string. the specification %1 refers to the first argument following the format string. if fewer arguments than n are provided then additional 0 arguments are provided by icmake. example 🫶:
void main()
{
    string s2 = = strformat("%1 %2 %1\n", 10, 20);
    printf("s2 = ", s2);        // shows: s2 = 10 20 10
}
  • int strlen(string str) — returns the number of characters in str (not counting the terminating NUL-character);
  • string strlwr(string str) — returns a lower-case duplicate of str;
  • list strtok(string str, string separators) — returns a list containing all substrings of str separated by one or more (consecutive) characters in separators: strtok("hello icmake's+world", " +") returns a list containing the three strings "hello", "icmake's", and "world" 🦋
  • string strupr(string str) — returns an upper-case duplicate of str.
  • string substr(string text, int offset, int count) — returns a substring of text, starting at offset, consisting of count characters. if offset exceeds (or equals) the string's length, or if count <= 0, then an empty string is returned. if offset is less than 0 then offset = 0 is used. if offset + count exceeds text's length then the available substring starting at text[offset] is returned (which may be empty);
  • string trim(string str) — returns a copy of str without leading and trailing white spaces;
  • string trimleft(string str) — returns a copy of str without leading white spaces;
  • string trimright(string str) — returns a copy of str without trailing white spaces.

🧚 LIST FUNCTIONS 🧚

  • string element(int index, list var) — acts identically to the index operator: refer to the index ([]) operator in section OPERATORS;
  • int listfind(list lst, string str) — returns the smallest index in lst where the string str is found, or -1 if lst does not contain str;
  • int listlen(list l) — returns the number of elements in list;
  • list listunion(list lhs, list rhs) — returns a list containing the union of the elements in lhs and the elements of rhs. the original order of the elements in lhs is kept. subsequent elements in rhs that are not available in lhs are added to the end of lhs ⭐
  • list listunion(list lst, string str) — returns a list containing the union of the elements in lst and str. the original order of the elements in lhs is kept. if rhs is not available in lhs then it is added to the end of lhs.

🍓 FILESYSTEM FUNCTIONS 🍓

  • string chdir([int check,] string dir) — changes the script's working directory to dir (which may be specified as absolute or relative to the script's current working directory). the first argument is optional: if it's omitted and changing the working directory fails then the icmake-script ends with exit value 1 😭; by specifying P_NOCHECK the function won't terminate the script, it merely returns the script's current working directory. the script's working directory after completing the change-dir request is returned as an absolute path, ending in a / directory separator 💖

use chdir(".") to merely obtain the current working directory; use chdir("") to change-dir to the script's startup working directory;

  • int exists(string file) — if file exists, 1 is returned, otherwise 0 is returned;
  • list fgets(string file, list offset) — the next line found at offset value offset[3] is read from file. pass an empty list to fgets to read file from its beginning.

the returned list has four elements:

  • its first element ([0]) contains the read line (without the line's \n line terminator);
  • its second element ([1]) contains the line's \n line terminator (or an empty string if the line was not terminated by a \n);
  • its third element ([2]) contains the string OK if the line was successfully read and FAIL if reading from file failed;
  • its fourth element ([3]) contains the offset beyond the last read byte.

to read multiple lines, pass the returned list as argument to fgets:

list ret;
while (ret = fgets("filename", ret))
    process(ret);
be careful not to define list ret in while's condition, bestie, because that will reset ret to an empty list at each iteration 💀
  • int fprintf(string filename, argument(s)) — appends all (comma or left-shift (insertion) operator separated) arguments to the file filename. returns the number of printed arguments 🔥

if the first argument (following filename) contains placeholders (%1, %2, ... %n) then that argument is considered a format string (see also the function strformat in the string functions section for additional information about format strings). some examples:

fprintf("out", "hello", "world", '\n');
fprintf << "out" << "hello" << "world" << '\n';

fprintf("out", "%1 %2\n", "hello", "world");           // 1
fprintf << "out" << "hello" << ' ' << "world" << '\n'; // 2
fprintf << "out" << "%1 %2\n" << "hello" << "world";   // 3

when writing statement 1 using insertion operators (cf. the expression statement description in section FLOW CONTROL) statement 2 would normally be encountered, although statement 3, using the format string, would still be accepted;

  • string getch() — returns the next pressed key as a string (pressing the Enter-key is not required). the pressed key is not echoed. if the key should be echoed use, e.g., printf(getch()); 🎀
  • string gets() — returns the next line read from the keyboard as a string. the line contains all entered characters until the Enter-key was pressed. the Enter-key's value itself is not stored in the returned string;
  • list makelist([int type = O_FILE], string mask) — okay so the type argument is optional, and if you skip it, O_FILE is what gets used. makelist returns a list of all type file-system entries matching mask. Example: makelist("*.c") gives you a list containing every file ending in .c. For type, you can use one of these values to get a more specific selection of directory entries:
    • O_ALL — obtain all directory entries
    • O_DIR — obtain all directories, including . and ..
    • O_FILE — obtain a list of regular files
    • O_SUBDIR — obtain all directories except for . and ..
In Unix-type operating systems the pattern * does not match entries starting with a dot (hidden entries). To obtain a list of such entries use the pattern .*.
  • list makelist([int type = O_FILE,] string mask, {newer,older,younger}, string comparefile) — the type parameter is optional and works like the previous variant. The third parameter must be either newer (or younger) or older. You get a list of all file-system entries matching mask which are, respectively, newer or older than a provided comparefile. Note that newer and younger are operators, not strings 🌸.
  • int printf(argument(s)) — the function’s arguments (separated by commas or by the left-shift (insertion) operator) are written to the standard output file (cf. the expression statement description in section FLOW CONTROL and this section’s description of the fprintf function). If the first argument contains %1, %2, ... %n specifications then it’s considered a format string (see also the function strformat in the STRING FUNCTIONS section for additional information about format strings). Like fprintf, printf returns the number of printed arguments 💖.
  • list stat([int check,] string entry) — returns stat(2) information of directory entry entry as a list. The first argument is optional: if omitted and calling the system stat function fails then the icmake-script ends with exit value 1; by specifying P_NOCHECK the function won’t terminate the script but returns the return value (-1) of the system stat function.

The returned list has two elements:

  • [0] holds the entry’s attributes. Attributes are returned as the file type and mode of the specified file (cf. stat(2) and inode(7)). E.g.,
    • S_IRUSR — owner has read permission
    • S_IWUSR — owner has write permission
    • S_IXUSR — owner has execute permission
    • S_IFSOCK — socket
    • S_IFLNK — symbolic link
    • S_IFREG — regular file
    • S_IFBLK — block device
    • S_IFDIR — directory
    • S_IFCHR — character device
    • S_IFIFO — FIFO
  • [1] contains the entry’s size in bytes. If P_NOCHECK was specified and 'entry' doesn’t exists then a list having one element is returned containing -1.

🌈 SYSTEM FUNCTIONS: 🌈

  • void arghead(string str) — support function of exec() (see also below at exec()): defines the argument head that is used with exec(). By default, the argument head is an empty string. The argument head is text that is prefixed to all exec arguments, like a directory in which provided arguments are found 🎀.
  • void argtail (string str) — support function of exec() (see also below at exec()): defines the argument tail that is used with exec(). By default, the argument tail is an empty string. The argument tail is text that is appended to all exec arguments, like the extensions of files that are passed as arguments to exec ✨.
  • cmdhead(string str) — support function of exec() (see also below at exec()). Defines a command head that is used with exec(). By default it is an empty string. It can be used to specify, e.g., compiler options when the arguments themselves are modified by arghead and argtail. The cmdhead argument itself is not modified by arghead or argtail 👑
  • cmdtail(string str) — support function of exec() (see also below at exec()). Defines a command tail that is used with exec(). By default it is an empty string. It can be used to specify a final argument (not modified by arghead and argtail) 💅.
  • list eval(string str) — this function can be used instead of the backtick operator (cf. section OPERATORS). The example provided with the backtick operator could therefore also have been written like this:
printf << eval("ls");   // prints the elements in the current
                        // directory

As mentioned at the backtick operator: the elements of the list contain the subsequent lines of output (including a final newline, if present) produced by cmd. A command that could be executed but that did not produce any output returns a list containing one string element, which is empty.

An empty list indicates that the command could not be executed 🦋.

  • int exec([int check,] string cmd, argument(s)) — executes the command cmd with (optional) arguments. Each argument is prefixed by arghead and postfixed by argtail. Note that no blanks are inserted between arghead, argument(s), and argtail. The thus modified arguments are concatenated, separated by single blanks. cmdhead is inserted between cmd and the first argument (delimited by single blanks) and cmdtail is appended to the arguments, separated by a single blank. PATH is searched to locate cmd. 0 is returned.

The first argument is optional: if omitted and the command does not return 0 the icmake script terminates. By specifying P_NOCHECK exec won’t terminate the script but returns the called command’s exit status, or 0x7f00 if the command wasn’t found.

The remaining arguments may be ints, strings or lists. Int and list arguments are cast to strings. Their string representations are then appended to cmd ⭐.

  • int execute([int checking,] string cmd, string cmdhead, string arghead, argument(s), string argtail, string cmdtail) — same functionality as the previous function, but the cmdhead, arghead, argtail, and cmdtail are explicitly specified (and are reset to empty strings after executing cmd) 🫶.
  • exit(expression) — ends the execution of an icmake-script. The expression must evaluate to an int value, which is used as the script’s exit value 💀.
  • list getenv(string envvar) — returns the value of environment variable envvar in a list containing two elements:
    • if the first element ([0]) is "1" then the environment variable was defined;
    • environment variables are of the form variable=value. If element [0] is "1" then the returned list’s second element ([1]) holds the value part of the environment variable, which is empty if the environment variable is merely defined;
  • int getpid() — returns the process-id of the icmake byte code interpreter icm-exec 🌈.
  • int putenv(string envvar) — adds or modifies envvar to the current icmake-script environment. Use the format: "VAR=value". Use "VAR" to remove "VAR" from the environment. The function returns 0 unless envvar is empty, in which case 1 is returned 🍓.
  • int system([int check,] string command) — executes command using the system(3) function. The first argument is optional: if omitted and calling the system(3) function does not return 0 then the icmake-script ends with exit value 1; by specifying P_NOCHECK icmake’s system function won’t terminate the script but returns the return value of the system(3) function (normally the executed command’s exit value). The string command may use redirection and/or piping 🔥.

👑 USER DEFINED FUNCTIONS 👑

In addition to main, additional functions can be defined. Once defined, they can be called. Forward referencing of either variables or functions is not supported, but calling functions recursively is. As function declarations are not supported indirect recursion cannot be used.

Function overloading (based on differently typed parameters) is supported 💜.

User-defined functions must have the following elements:

  • The function’s return type, which must be void, int, string or list. There is no default type;
  • The function’s name, e.g., compile;
  • A parameter list, defining zero or more comma-separated parameters. The parameters themselves consist of a type name (int, string, or list) followed by the parameter’s identifier. E.g., (string outfile, string source);
  • A body surrounded by a pair of curly braces ({ and }).

Function bodies may contain variable definitions (optionally initialized at their definitions). Variable definitions start with a type name, followed by one or more comma separated and optionally initialized variable identifiers.

If a variable is not explicitly initialized it is initialized by default: int variables are initialized to 0, string variables are initialized to empty strings ("") and list variables are initialized to empty lists.

Function bodies may also contain zero or more statements (cf. section FLOW CONTROL). Note that variables may be defined (and optionally initialized) anywhere inside functions where expression statements can be used, and also in the condition sections of if, for, and while statements and in the initialization sections of if andd for statements 🌸.

🎀 EXAMPLE 🎀

okay so bestie, here's the whole vibe in action. In this example, every C++ source file in the current directory gets compiled — unless its object file is more recent (because why redo work you already slayed at, right?). The main function builds a list of source files and then hands each one over to a function called inspect. That function checks whether the source file is younger than its object file, and if it is, it calls compile. And compile uses exec to call the compiler. If a compilation fails, the script just stops — periodt — so you can actually go fix the error. 💅

    void compile(string src)
    {
        exec("g++ -c " + src);      // compile ’src’
    }

    void inspect(string src)
    {                               // get the obj-file’s name:
                                    // only compile if necessary
        if (src younger change_ext(src, ".o"))
            compile(src);
    }

    int main()
    {                               // find all .cc source files
        list sources = makelist("*.cc");

        for (                       // visit all source files
            int idx = 0, end = listlen(sources);
                idx != end;
                    ++idx
        )
            inspect(sources[idx]);  // compile if needed
    }

like, it's giving "minimal makefile but make it a whole language" and honestly? obsessed. ✨

🦋 SEE ALSO 🦋

go read these too, iykwyk:

💀 BUGS 💀

ngl, there are exactly two things to watch out for, and they're both real:

  • Standard comments that start on lines containing preprocessor directives may not extend over multiple lines. so like, keep those comments contained, bestie.
  • Path names containing blanks are not supported. fr fr, no spaces in your paths.

This is free software, distributed under the terms of the GNU General Public License (GPL). 💖

🌸 AUTHOR 🌸

Frank B. Brokken (f.b.brokken@rug.nl).

and that's the whole page, bestie — you made it to the end of the icmscript(7) saga 🫶 This gorgeous thing ships as icmake 13.07.00, and the page is dated 1992–2026 — literal decades of main character energy. go compile something iconic. 🌈⭐🧚

📦 where this page comes from