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


Macros

List Operations

Macro: list ([element,...])
Returns a list containing all specified elements in the specified 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: llength (list)
Returns the number of elements in the list list.

Macro: linsert (list,index,element)
Inserts the element element into the list list at index index. If index is greater or equal the length of list, the list is enlarged by appending empty strings. Examples:

%<lst=%list(a,b,c)>

%linsert(%&lst,1,x)%encode(%lst)
=> %list(%'a',%'x',%'b',%'c')
%linsert(%&lst,5,y)%encode(%lst)
=> %list(%'a',%'x',%'b',%'c',%",%'y')

Macro: ldelete (list,index)
Deletes from the list list the element at index index. Example:

%<lst=%list(a,b,c)>%ldelete(%&lst,1)%encode(%lst)
=> %list(%'a',%'c')

Macro: lsort (list[,comparator])
Sorts the elements of the list list, which should be strings, according to the order specified by comparator, which must be a closure taking two arguments and returning an integer. A return value of 0 denotes that the two arguments are equal, less than 0 means that the first argument should come before the second, greater than 0 means that the first argument should come after the second. If comparator is omitted, the macro scmp is used. Returns the resulting list. Examples:

%encode(%lsort(%list(b,c,a)))
=> %list(%'a',%'b',%'c')
%encode(%lsort(%list(b,c,a),%lambda(a,b,%scmp(%b,%a))))
=> %list(%'c',%'b',%'a')

Macro: lappend (list,value[,value...])
Appends all values to the list list. Returns nothing, i.e. is called for its side effects, which means that the first parameter should be a list to be modified, not a copy of a list.

Macro: luniq (list[,comparator])
Removes all but the first occurrences of all sequential occurrences of the same element in list, where the sameness is determined by the closure comparator, which must accept two arguments and return a boolean value of TRUE if they are equal, FALSE otherwise. If comparator is omitted, seq is used. Returns the modified list.

%encode(%luniq(%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: hcount (hash)
Returns the number of key/value pairs in the hash hash.

Macro: hcontains (hash,key)
Returns 1, if the key key is contained in the hash hash. Otherwise, returns 0.

Macro: hkeys (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: smatch (regexp,string[,registers])
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. If registers is specified, which must be a list, clears it and sets its elements (beginning with @math{1}) to the contents of the corresponding submatches (parts of the regular expression enclosed by parentheses). The element 0 is set to the whole match. For example:

%<regs=%list()>\
%smatch(%'\.([^.]*)$',alittlepicture.jpg,%&regs) %regs[1]
=> 14 jpg

Macro: ssplit (regexp,string[,connector])
Splits the string string into parts separated by the regular expression regexp. Returns a list containing these parts. If connector is specified, the parts that are inserted into the list are generated by invocations of connector. connector is always called with three parameters, the first being the registers of regexp for the match right before the string and the third being the registers of the match right after the string. The second parameter is the string itself. For the very first string, the first parameter is an empty list, whereas for the last string, the third parameter is an empty list. Thus

%ssplit(%regex,%string)

is equivalent to

%ssplit(%regex,%string,%lambda(a,b,c,%b))

Example:

%encode(%ssplit(:+,foo::bar:rules))
=> %list(%'foo',%'bar',%'rules')

Macro: stokenize (regexp,string[,tokener])
Returns a list containing all substrings of string matching regexp. If tokener is specified, not the whole matches are inserted into the result list, but the results of calling tokener with the respective lists of registers of the matches. This means, that these two calls have the same result:

%stokenize(%regexp,%string)
%stokenize(%regexp,%string,%lambda(r,%r[0]))

Examples:

%encode(%stokenize([a-zA-Z0-9]+,%' a bc d04 d   fsfd, rwe'))
=> %list(%'a',%'bc',%'d04',%'d',%'fsfd',%'rwe')
%encode(%stokenize(%'-([0-9]+)-',%'  -32- -- 543 -12--43--',
                   %lambda(r,%r[1])))
=> %list(%'32',%'12',%'43')

Macro: sgsub (regexp,string,replacement[,options])
Replaces all occurrences of the regular expression regexp in string. If replacement is a string, the occurrences are replaced with this string. Otherwise, replacement must be a closure taking one argument and returning a string. In this case, the occurrences are replaced by the result of the closure when called with a list containing the regular expression registers in elements beginning with 1 and the whole match in element 0. options, if specified, should be a string composed of one or more of the following characters:

i
Match case insensitively. The default is case-sensitive matching.

Examples:

%sgsub(ei,HEINZI Deinzi,!,i)
=> H!NZI D!nzi
%sgsub(a+,abaacaaadaaaa,%lambda(r,%slength(%r[0])))
=> 1b2c3d4

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

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

Macro: ssub (string,start[,length])
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(0123456789,3)
=> 3456789
%substring(0123456789,-3)
=> 789
%substring(0123456789,2,3)
=> 234
%substring(0123456789,2,-5)
=> 234

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

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

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

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

Miscellaneous

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

%<regs=%list()>\
%void(%smatch(%'\.([^.]*)$',alittlepicture.jpg,%&regs))%regs[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.

Macro: same (val1,val2)
Returns 1 if val1 and val2 refer to the same value, otherwise 0. Two values are the same if a change in one entails the same change in the other, i.e. if they occupy the same memory location. Examples:

%<val=abc>%same(%val,%val)
=> 0
%<val=abc>%same(%&val,%&val)
=> 1
%<val=abc>%<val2=%&val>%same(%&val,%&val2)
=> 1

Macro: equal (val1,val2)
Returns 1 if val1 is equal to val2, otherwise 0. Two scalars are equal if the strings they contain are equal. Two lists are equal if they have the same length and contain equal elements. Two hashes are equal if they have the same count and the same keys map to equal values.

%equal(%list(a,b,c),%list(a,b,c))
=> 1
%equal(%hash(a,1,b,2,c,3),%hash(c,3,b,2,a,1))
=> 1
%equal(%list(a,b,c),%list(1,2,3))
=> 0

Macro: typeof (value)
Returns the type of value. The result can be one of scalar, list, hash, lambda, built-in.

%typeof(abc)
=> scalar
%typeof(%list(a,b,c))
=> list
%typeof(%hash(a,1,b,2,c,3))
=> hash
%typeof(%lambda(a,%a%a))
=> lambda
%typeof(%typeof)
=> built-in

Macro: bound (name)
Returns 1 if the name name is bound in the current environment. If not, returns 0.

Macro: apply (lambda,arglist)
Calls lambda with the elements of arglist as arguments.

%apply(%lambda(a,b,c,my args are %a %b %c),%list(1,2,3))
=> my args are 1 2 3

Macro: not (expr)
Returns the negation of the boolean value of expr, i.e. returns 1 if expr is FALSE and 0 if expr is TRUE.

Macro: shexencode (string)
Translates the bytes of string to a sequence of hexadecimal digits.

%shexencode(hello world!)
=> 68656C6C6F20776F726C6421

Macro: shexdecode (string)
Translates a sequence of hexadecimal digits as produced by shexencode to a string.

%shexdecode(68656C6C6F20776F726C6421)
=> hello world!


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