Go to the first, previous, next, last section, table of contents.


Macro Reference

Flow Control

The macros in this section are special macros in that their arguments are not automatically evaluated before the macro-call but instead are evaluated by the macros themselves. Therefore it is exactly specified when the arguments to these macros are evaluated.

Macro: if (condition,consequence[,alternative])
Evaluates condition and, if its boolean value is TRUE, executed consequence. Otherwise, alternative is executed, if specified.

Macro: ifdef (symbol,consequence[,alternative])
Evaluates symbol. If a symbol with the resulting name exists, consequence is executed. Otherwise, if alternative is specified, it is executed.

Macro: ifdefkey (hash,key,consequence[,alternative])
Evaluates hash and key. If a key with the value of key is contained in the value of hash, consequence is executed. Otherwise, if alternative is specified, it is executed.

Macro: for (counter,start,stop,[increment,]expr)
Evaluates counter, start, stop and, if specified, increment. The values of start, stop and increment must be numbers. If increment is not specified, an increment of @math{1} is used if start is greater than stop, otherwise @math{-1}. The symbol counter is set to start. Then, while the value of counter is before or equal to stop in the counting direction, expr is executed and counter is incremented by increment.

A few examples:

%for(i,1,10,%i%" ")
=> 1 2 3 4 5 6 7 8 9 10
%for(i,10,1,%i%" ")
=> 10 9 8 7 6 5 4 3 2 1
%for(i,1,10,2,%i%" ")
=> 1 3 5 7 9
%for(i,10,1,-2,%i%" ")
=> 10 8 6 4 2
%for(i,1,10,0,%i%" ")
error--> increment in for-loop cannot be zero
%for(i,10,1,1,%i%" ")
=>

Macro: foreach (counter,list,expr)
Evaluates counter and list, which must yield a list. Then iterates over this list, assigning each element to the symbol counter and executing expr.

Macro: foreachkey (counter,hash,expr)
Evaluates counter and hash, which must yield a hash. Then iterates over all keys in the hash, assigning each key to the symbol counter and executing expr.

Macro: while (condition,expr)
Evaluates condition. If this yields a boolean value of TRUE, expr is executed, otherwise the loop is finished. Then repeats the cycle.

Macro: until (condition,expr)
Evaluates condition. If this yields a boolean value of TRUE, the loop is finished, otherwise expr is executed. Then repeats the cycle.

Macro: dowhile (expr,condition)
Executes expr, then evaluates condition. If this yields a boolean value of TRUE, the cycle is repeated.

Macro: dountil (expr,condition)
Executes expr, then evaluates condition. If this yields a boolean value of TRUE, the loop is finished, otherwise the cycle is repeated.

List Operations

Macro: list ([element,...])
Returns a list with all specified elements in that order, beginning with index 0. Note that %list() returns an empty list while %list(%"") returns a list with one element, which is the empty string.

Macro: listlength (list)
Returns the number of elements in the list list.

Macro: split (string,regexp)
Splits the string string into parts separated by the regular expression regexp. Returns a list containing these parts. Example:

%encode(%split(foo::bar:rules,:+))
=> %list(%"foo",%"bar",%"rules")

Macro: join (string,list)
Joins the elements of the list list by inserting between two sequential elements the string string. Example:

%join(:,%list(the,quick,brown,fox))
=> the:quick:brown:fox

Macro: sort (list)
Sorts the elements of the list list, which should be strings, according to the order specified by the strcmp() C function. Returns the resulting list.

Macro: append (list,element)
Returns a list which is formed by appending element to the list list.

Macro: uniq (list)
Returns a list which is formed by removing of all sequential occurences of the same element in list all but one element each. Example:

%encode(%uniq(%list(a,b,b,c,d,e,e,e,f)))
=> %list(%"a",%"b",%"c",%"d",%"e",%"f")

Hash Operations

Macro: hash ([key,value,...])
Returns a hash containing all the specified key/value pairs.

Macro: hashcount (hash)
Returns the number of key/value pairs in the hash hash.

Macro: keys (hash)
Returns a list of all keys in the hash hash in no particular order.

File Operations

Macro: fopen (filename[,mode])
Opens the file named filename and returns a handle to it. If the file could not be opened, for example because it does not exists, for lack of permission or if mode is illegal, returns -1. The file is opened for reading if mode is omitted or is r. The file is opened for writing if mode is w.

Macro: fpipe (executable[,arg...])
Forks off a child process, starts the specified executable with the specified parameters and returns a handle for reading this processes standard output. Returns -1 if something goes wrong. Note that the arguments are not subject to shell expansion, since the process does not start a subshell. If you want shell expansion, you have to start a subshell explicitly. For example, to list all files beginning with an a:

%pipe(/bin/sh,-c,ls a*)

Macro: fclose (file)
Closes the file associated with the handle file.

Macro: fgets (file)
Reads one line from the file associated with the handle file and returns it. The newline character is included.

Macro: fputs (file,string)
Writes string to the file associated with the handle file, which must have been opened for writing.

Macro: feof (file)
Returns boolean TRUE if the end of the file associated with the handle file is reached, FALSE otherwise.

Macro: fstat (filename)
Returns a hash containing information on the file with name filename. Returns an empty hash if the file does not exist. Otherwise, the hash contains values for the following keys:

uid
User ID of owner.
gid
Group ID of owner.
size
Size in bytes.
blksize
Blocksize for filesystem I/O.
blocks
Number of blocks allocated.
atime
Time of last access.
mtime
Time of last modification.
ctime
Time of last change.

All times are given in seconds since January 1, 1970, 00:00:00 GMT. For detailed description of these values see stat(2).

String Operations

Macro: match (regexp,string)
Searches the string string for the first occurrence of the regular expression regexp and returns the index of the first character of this substring. If no match was found, returns -1. Furthermore, sets the variables with numerical names (beginning with @math{1}) to the contents of the corresponding submatches (parts of the regular expression enclosed by parentheses). The variable 0 contains the whole match. For example:

%match(%"\.([^.]*)$",alittlepicture.jpg) %1
=> 14 jpg

Macro: gsub (string,regexp,replacement)
Replaces all occurences of the regular expression regexp in string with the string replacement and returns the resulting string. Example:

%gsub(HEINZI Deinzi,[Ee][Ii],!)
=> H!NZI D!nzi

Macro: removews (string)
Returns a string which results from removing all leading and trailing whitespace from the string string.

Macro: strlength (string)
Returns the length of the string string.

Macro: substring (start,[length,]string)
Returns a substring of the string string. If it is called with two arguments and start is positive, then the substring beginning with index start is returned. If start is negative, the last -start characters are returned. If called with two arguments, start specifies the index of the first character in the substring. If length is positive, it specifies the length of substring. If it is negative, then -length specifies the index of the character following the last character of the substring. Examples:

%substring(3,0123456789)
=> 3456789
%substring(-3,0123456789)
=> 789
%substring(2,3,0123456789)
=> 234
%substring(2,-5,0123456789)
=> 234

Macro: streq (string1,string2)
Returns a boolean value of TRUE if string1 and string2 are equal, otherwise FALSE.

Macro: strcmp (string1,string2)
Returns the result of the strcmp() C function with string1 and string2.

Macro: chr (code)
Returns a string with the character with character code code.

Macro: number (number,base)
Formats the decimal integer number according to the given base base, which must be between 2 and 36 inclusive. Example:

%number(34,2)
=> 100010
%number(-255,16)
=> -ff

Miscellaneous

Macro: void (expr)
Executes expr but discard the result. Example:

%void(%match(%"\.([^.]*)$",alittlepicture.jpg))%1
=> jpg

Macro: outputenable (flag)
If the boolean value of flag is TRUE, enables output, otherwise disables it. If output is disabled, everything is evaluated as usual, but chpp does not output anything.

Macro: depend (dependency[,target])
Adds the filename dependency to the list of dependencies for the file target. If target is not specified, the name of the output file is used.

Macro: warning (message)
Causes chpp to give a warning with the message message.

Macro: error (message)
Causes chpp to signal an error with the message message.

Macro: encode (value)
Returns a string which, upon evaluation, yields a value equal to value.

Macro: random (limit)
Returns a random number in the interval 0 to limit-1. The random number are uniformly distributed.

Symbol Table Manipulation

Macro: define (name,argname[,argname...],body)
Defines a macro with the name name and the specified argument names. The body body is not evaluated.

Macro: locals (symbol[,symbol...],body)
Executed body in a new scope with the specified local variables.


Go to the first, previous, next, last section, table of contents.