This file has been translated from LaTeX by HeVeA.  Node: Subsection 8-2-7, Next: Subsection 8-2-8, Prev: Subsection 8-2-6, Up: Section 8-2 8.2.7 try =========== << try try-body catch class1(v1) catch-body when expr when-body ... finally finally-body >> The `try' form is used for exception handling. First, the expressions in the `try-body' are evaluated. If evaluation results in a value `v' without raising an exception, then the expressions in the `finally-body' are evaluated and the value `v' is returned as the result. If evaluation of the `try-body' results in a exception object `obj', the `catch' clauses are examined in order. When examining `catch' clause `catch class(v)', if the exception object `obj' is an instance of the class name `class', the variable `v' is bound to the exception object, and the expressions in the `catch-body' are evaluated. If a `when' clause is encountered while a `catch' body is being evaluated, the predicate `expr' is evaluated. If the result is true, evaluation continues with the expressions in the `when-body'. Otherwise, the next `catch' clause is considered for evaluation. If evaluation of a `catch-body' or `when-body' completes successfully, returning a value `v', without encountering another `when' clause, then the expressions in the `finally-body' are evaluated and the value `v' is returned as the result. There can be any number of `catch' clauses; the `finally' clause is optional.  Node: Subsection 8-2-8, Next: Subsection 8-2-9, Prev: Subsection 8-2-7, Up: Section 8-2 8.2.8 raise ============= << raise exn exn : Exception >> The `raise' function raises an exception. The `exn' object can be any object. However, the normal convention is to raise an 'Exception' object. If the exception is never caught, the whole object will be verbosely printed in the error message. However, if the object is an `Exception' one and contains a `message' field, only that field will be included in the error message.  Node: Subsection 8-2-9, Next: Subsection 8-2-10, Prev: Subsection 8-2-8, Up: Section 8-2 8.2.9 exit ============ << exit(code) code : Int >> The `exit' function terminates omake abnormally. `$(exit )' The `exit' function takes one integer argument, which is exit code. Non-zero values indicate abnormal termination.  Node: Subsection 8-2-10, Next: Subsection 8-2-11, Prev: Subsection 8-2-9, Up: Section 8-2 8.2.10 defined ================ << $(defined sequence) : String sequence : Sequence >> The `defined' function test whether all the variables in the sequence are currently defined. For example, the following code defines the `X' variable if it is not already defined. << if $(not $(defined X)) X = a b c export >>  Node: Subsection 8-2-11, Next: Subsection 8-2-12, Prev: Subsection 8-2-10, Up: Section 8-2 8.2.11 defined-env ==================== << $(defined-env sequence) : String sequence : String >> The `defined-env' function tests whether a variable is defined as part of the process environment. For example, the following code adds the `-g' compile option if the environment variable `DEBUG' is defined. <>  Node: Subsection 8-2-12, Next: Subsection 8-2-13, Prev: Subsection 8-2-11, Up: Section 8-2 8.2.12 getenv =============== << $(getenv name) : String $(getenv name, default) : String >> The `getenv' function gets the value of a variable from the process environment. The function takes one or two arguments. In the single argument form, an exception is raised if the variable variable is not defined in the environment. In the two-argument form, the second argument is returned as the result if the value is not defined. For example, the following code defines the variable `X' to be a space-separated list of elements of the `PATH' environment variable if it is defined, and to `/bin /usr/bin' otherwise. << X = $(split $(PATHSEP), $(getenv PATH, /bin:/usr/bin)) >> You may also use the alternate form. << getenv(NAME) default >>  Node: Subsection 8-2-13, Next: Subsection 8-2-14, Prev: Subsection 8-2-12, Up: Section 8-2 8.2.13 setenv =============== << setenv(name, value) name : String value : String >> The `setenv' function sets the value of a variable in the process environment. Environment variables are scoped like normal variables.  Node: Subsection 8-2-14, Next: Subsection 8-2-15, Prev: Subsection 8-2-13, Up: Section 8-2 8.2.14 unsetenv ================= << unsetenv(names) names : String Array >> The `unsetenv' function removes some variable definitions from the process environment. Environment variables are scoped like normal variables.  Node: Subsection 8-2-15, Next: Subsection 8-2-16, Prev: Subsection 8-2-14, Up: Section 8-2 8.2.15 get-registry ===================== << get-registry(hkey, key, field) : String get-registry(hkey, key, field, default) : String hkey : String key : String field : String >> The `get-registry' function retrieves a string value from the system registry on Win32. On other architectures, there is no registry. The `hive' (I think that is the right word), indicates which part of the registry to use. It should be one of the following values. - `HKEY_CLASSES_ROOT' - `HKEY_CURRENT_CONFIG' - `HKEY_CURRENT_USER' - `HKEY_LOCAL_MACHINE' - `HKEY_USERS' Refer to the Microsoft documentation if you want to know what these mean. The `key' is the field you want to get from the registry. It should have a form like `A\B\C' (if you use forward slashes, they will be converted to backslashes). The field is the sub-field of the key. In the 4-argument form, the `default' is returned on failure. You may also use the alternate form. << get-registry(hkey, key, field) default >>  Node: Subsection 8-2-16, Next: Subsection 8-2-17, Prev: Subsection 8-2-15, Up: Section 8-2 8.2.16 getvar =============== << $(getvar name) : String >> The `getvar' function gets the value of a variable. An exception is raised if the variable variable is not defined. For example, the following code defines X to be the string abc. << NAME = foo foo_1 = abc X = $(getvar $(NAME)_1) >>  Node: Subsection 8-2-17, Next: Section 8-3, Prev: Subsection 8-2-16, Up: Section 8-2 8.2.17 setvar =============== << setvar(name, value) name : String value : String >> The `setvar' function defines a new variable. For example, the following code defines the variable `X' to be the string `abc'. << NAME = X setvar($(NAME), abc) >>  Node: Section 8-3, Next: Subsection 8-3-1, Prev: Section 8-2, Up: Chapter 8 8.3 Arrays and sequences *=*=*=*=*=*=*=*=*=*=*=*=*= * Menu: * Subsection 8-3-1:: array * Subsection 8-3-2:: split * Subsection 8-3-3:: concat * Subsection 8-3-4:: length * Subsection 8-3-5:: nth * Subsection 8-3-6:: nth-hd * Subsection 8-3-7:: nth-tl * Subsection 8-3-8:: subrange * Subsection 8-3-9:: rev * Subsection 8-3-10:: join * Subsection 8-3-11:: string * Subsection 8-3-12:: string-escaped, ocaml-escaped, html-escaped, html-pre-escaped, c-escaped, id-escaped * Subsection 8-3-13:: decode-uri, encode-uri * Subsection 8-3-14:: quote * Subsection 8-3-15:: quote-argv * Subsection 8-3-16:: html-string * Subsection 8-3-17:: addsuffix * Subsection 8-3-18:: mapsuffix * Subsection 8-3-19:: addsuffixes * Subsection 8-3-20:: removeprefix * Subsection 8-3-21:: removesuffix * Subsection 8-3-22:: replacesuffixes * Subsection 8-3-23:: addprefix * Subsection 8-3-24:: mapprefix * Subsection 8-3-25:: add-wrapper * Subsection 8-3-26:: set * Subsection 8-3-27:: mem * Subsection 8-3-28:: intersection * Subsection 8-3-29:: intersects * Subsection 8-3-30:: set-diff * Subsection 8-3-31:: filter * Subsection 8-3-32:: filter-out * Subsection 8-3-33:: capitalize * Subsection 8-3-34:: uncapitalize * Subsection 8-3-35:: uppercase * Subsection 8-3-36:: lowercase * Subsection 8-3-37:: system * Subsection 8-3-38:: shell * Subsection 8-3-39:: export * Subsection 8-3-40:: while * Subsection 8-3-41:: break * Subsection 8-3-42:: random, random-init  Node: Subsection 8-3-1, Next: Subsection 8-3-2, Prev: Section 8-3, Up: Section 8-3 8.3.1 array ============= << $(array elements) : Array elements : Sequence >> The `array' function creates an array from a sequence. If the `' is a string, the elements of the array are the whitespace-separated elements of the string, respecting quotes. In addition, array variables can be declared as follows. << A[] = ... >> In this case, the elements of the array are exactly `', ..., `', and whitespace is preserved literally.  Node: Subsection 8-3-2, Next: Subsection 8-3-3, Prev: Subsection 8-3-1, Up: Section 8-3 8.3.2 split ============= << $(split sep, elements) : Array sep : String elements : Sequence >> The `split' function takes two arguments, a string of separators, and a string argument. The result is an array of elements determined by splitting the elements by all occurrence of the separator in the `elements' sequence. For example, in the following code, the `X' variable is defined to be the array `/bin /usr/bin /usr/local/bin'. << PATH = /bin:/usr/bin:/usr/local/bin X = $(split :, $(PATH)) >> The `sep' argument may be omitted. In this case `split' breaks its arguments along the white space. Quotations are not split.  Node: Subsection 8-3-3, Next: Subsection 8-3-4, Prev: Subsection 8-3-2, Up: Section 8-3 8.3.3 concat ============== << $(concat sep, elements) : String sep : String elements : Sequence >> The `concat' function takes two arguments, a separator string, and a sequence of elements. The result is a string formed by concatenating the elements, placing the separator between adjacent elements. For example, in the following code, the `X' variable is defined to be the string `foo_x_bar_x_baz'. << X = foo bar baz Y = $(concat _x_, $(X)) >>  Node: Subsection 8-3-4, Next: Subsection 8-3-5, Prev: Subsection 8-3-3, Up: Section 8-3 8.3.4 length ============== << $(length sequence) : Int sequence : Sequence >> The `length' function returns the number of elements in its argument. For example, the expression `$(length a b "c d")' evaluates to 3.  Node: Subsection 8-3-5, Next: Subsection 8-3-6, Prev: Subsection 8-3-4, Up: Section 8-3 8.3.5 nth =========== << $(nth i, sequence) : value i : Int sequence : Sequence raises RuntimeException >> The `nth' function returns the nth element of its argument, treated as a list. Counting starts at 0. An exception is raised if the index is not in bounds. For example, the expression `$(nth 1, a "b c" d)' evaluates to `"b c"'.  Node: Subsection 8-3-6, Next: Subsection 8-3-7, Prev: Subsection 8-3-5, Up: Section 8-3 8.3.6 nth-hd ============== << $(nth-hd i, sequence) : value i : Int sequence : Sequence raises RuntimeException >> The `nth-hd' function returns the first `i' elements of the sequence. An exception is raised if the sequence is not at least `i' elements long. For example, the expression `$(nth-hd 2, a "b c" d)' evaluates to `a "b c"'.  Node: Subsection 8-3-7, Next: Subsection 8-3-8, Prev: Subsection 8-3-6, Up: Section 8-3 8.3.7 nth-tl ============== << $(nth-tl i, sequence) : value i : Int sequence : Sequence raises RuntimeException >> The `nth-tl' function skips `i' elements of the sequence and returns the rest. An exception is raised if the sequence is not at least `i' elements long. For example, the expression `$(nth-tl 1, a "b c" d)' evaluates to `"b c" d'.  Node: Subsection 8-3-8, Next: Subsection 8-3-9, Prev: Subsection 8-3-7, Up: Section 8-3 8.3.8 subrange ================ << $(subrange off, len, sequent) : value off : Int len : Int sequence : Sequence raises RuntimeException >> The `subrange' function returns a subrange of the sequence. Counting starts at 0. An exception is raised if the specified range is not in bounds. For example, the expression `$(subrange 1, 2, a "b c" d e)' evaluates to `"b c" d'.  Node: Subsection 8-3-9, Next: Subsection 8-3-10, Prev: Subsection 8-3-8, Up: Section 8-3 8.3.9 rev =========== << $(rev sequence) : Sequence sequence : Sequence >> The `rev' function returns the elements of a sequence in reverse order. For example, the expression `$(rev a "b c" d)' evaluates to `d "b c" a'.  Node: Subsection 8-3-10, Next: Subsection 8-3-11, Prev: Subsection 8-3-9, Up: Section 8-3 8.3.10 join ============= << $(join sequence1, sequence2) : Sequence sequence1 : Sequence sequence2 : Sequence >> The `join' function joins together the elements of the two sequences. For example, `$(join a b c, .c .cpp .h)' evaluates to `a.c b.cpp c.h'. If the two input sequences have different lengths, the remainder of the longer sequence is copied at the end of the output unmodified.  Node: Subsection 8-3-11, Next: Subsection 8-3-12, Prev: Subsection 8-3-10, Up: Section 8-3 8.3.11 string =============== << $(string sequence) : String sequence : Sequence >> The `string' function flattens a sequence into a single string. This is similar to the `concat' function, but the elements are separated by whitespace. The result is treated as a unit; whitespace is significant.  Node: Subsection 8-3-12, Next: Subsection 8-3-13, Prev: Subsection 8-3-11, Up: Section 8-3 8.3.12 string-escaped, ocaml-escaped, html-escaped, html-pre-escaped, ======================================================================= c-escaped, id-escaped ===================== \@name {@default108} << $(string-escaped sequence) : String Array $(ocaml-escaped sequence) : String Array $(html-escaped sequence) : String Array $(html-pre-escaped sequence) : String Array $(c-escaped sequence) : String Array $(hex-escaped sequence) : StringArray sequence : Array >> The `string-escaped' function converts each element of its argument to a string, escaping it, if it contains symbols that are special to OMake. The special characters include `:()\,$'"#' and whitespace. This function can be used in scanner rules to escape file names before printing then to `stdout'. The `ocaml-escaped' function converts each element of its argument to a string, escaping characters that are special to OCaml. The `c-escaped' function converts a string to a form that can be used as a string constant in C. The `id-escaped' function turns a string into an identifier that may be used in OMake. The `html-escaped' function turns a literal string into a form acceptable as HTML. The `html-pre-escaped' function is similar, but it does not translate newlines into `
'. << println($(string $(string-escaped $"a b" $"y:z"))) a\ b y\:z >>  Node: Subsection 8-3-13, Next: Subsection 8-3-14, Prev: Subsection 8-3-12, Up: Section 8-3 8.3.13 decode-uri, encode-uri =============================== << $(decode-uri sequence) : sequence sequence : Sequence >> These two functions perform URI encoding, where special characters are represented by hexadecimal characters. << osh> s = $(encode-uri $'a b~c') "a+b%7ec" osh> decode-uri($s) "a b~c" >>  Node: Subsection 8-3-14, Next: Subsection 8-3-15, Prev: Subsection 8-3-13, Up: Section 8-3 8.3.14 quote ============== << $(quote sequence) : String sequence : Sequence >> The `quote' function flattens a sequence into a single string and adds quotes around the string. Inner quotation symbols are escaped. For example, the expression `$(quote a "b c" d)' evaluates to `"a \"b c\" d"', and `$(quote abc)' evaluates to `"abc"'.  Node: Subsection 8-3-15, Next: Subsection 8-3-16, Prev: Subsection 8-3-14, Up: Section 8-3 8.3.15 quote-argv =================== << $(quote-argv sequence) : String sequence : Sequence >> The `quote-argv' function flattens a sequence into a single string, and adds quotes around the string. The quotation is formed so that a command-line parse can separate the string back into its components.  Node: Subsection 8-3-16, Next: Subsection 8-3-17, Prev: Subsection 8-3-15, Up: Section 8-3 8.3.16 html-string ==================== << $(html-string sequence) : String sequence : Sequence >> The `html-string' function flattens a sequence into a single string, and escaped special HTML characters. This is similar to the `concat' function, but the elements are separated by whitespace. The result is treated as a unit; whitespace is significant.  Node: Subsection 8-3-17, Next: Subsection 8-3-18, Prev: Subsection 8-3-16, Up: Section 8-3 8.3.17 addsuffix ================== << $(addsuffix suffix, sequence) : Array suffix : String sequence : Sequence >> The `addsuffix' function adds a suffix to each component of sequence. The number of elements in the array is exactly the same as the number of elements in the sequence. For example, `$(addsuffix .c, a b "c d")' evaluates to `a.c b.c "c d".c'.  Node: Subsection 8-3-18, Next: Subsection 8-3-19, Prev: Subsection 8-3-17, Up: Section 8-3 8.3.18 mapsuffix ================== << $(mapsuffix suffix, sequence) : Array suffix : value sequence : Sequence >> The `mapsuffix' function adds a suffix to each component of sequence. It is similar to `addsuffix', but uses array concatenation instead of string concatenation. The number of elements in the array is twice the number of elements in the sequence. For example, `$(mapsuffix .c, a b "c d")' evaluates to `a .c b .c "c d" .c'.  Node: Subsection 8-3-19, Next: Subsection 8-3-20, Prev: Subsection 8-3-18, Up: Section 8-3 8.3.19 addsuffixes ==================== << $(addsuffixes suffixes, sequence) : Array suffixes : Sequence sequence : Sequence >> The `addsuffixes' function adds all suffixes in its first argument to each component of a sequence. If `suffixes' has `n' elements, and `sequence' has `m' elements, the the result has `n * m' elements. For example, the `$(addsuffixes .c .o, a b c)' expressions evaluates to `a.c a.o b.c b.o c.o c.a'.  Node: Subsection 8-3-20, Next: Subsection 8-3-21, Prev: Subsection 8-3-19, Up: Section 8-3 8.3.20 removeprefix ===================== << $(removeprefix prefix, sequence) : Array prefix : String sequence : Array >> The `removeprefix' function removes a prefix from each component of a sequence.  Node: Subsection 8-3-21, Next: Subsection 8-3-22, Prev: Subsection 8-3-20, Up: Section 8-3 8.3.21 removesuffix ===================== << $(removesuffix sequence) : Array sequence : String >> The `removesuffix' function removes the suffixes from each component of a sequence. For example, `$(removesuffix a.c b.foo "c d")' expands to `a b "c d"'.  Node: Subsection 8-3-22, Next: Subsection 8-3-23, Prev: Subsection 8-3-21, Up: Section 8-3 8.3.22 replacesuffixes ======================== << $(replacesuffixes old-suffixes, new-suffixes, sequence) : Array old-suffixes : Sequence new-suffixes : Sequence sequence : Sequence >> The `replacesuffixes' function modifies the suffix of each component in sequence. The `old-suffixes' and `new-suffixes' sequences should have the same length. For example, `$(replacesuffixes .h .c, .o .o, a.c b.h c.z)' expands to `a.o b.o c.z'.  Node: Subsection 8-3-23, Next: Subsection 8-3-24, Prev: Subsection 8-3-22, Up: Section 8-3 8.3.23 addprefix ================== << $(addprefix prefix, sequence) : Array prefix : String sequence : Sequence >> The `addprefix' function adds a prefix to each component of a sequence. The number of element in the result array is exactly the same as the number of elements in the argument sequence. For example, `$(addprefix foo/, a b "c d")' evaluates to `foo/a foo/b foo/"c d"'.  Node: Subsection 8-3-24, Next: Subsection 8-3-25, Prev: Subsection 8-3-23, Up: Section 8-3 8.3.24 mapprefix ================== << $(mapprefix prefix, sequence) : Array prefix : String sequence : Sequence >> The `mapprefix' function adds a prefix to each component of a sequence. It is similar to `addprefix', but array concatenation is used instead of string concatenation. The result array contains twice as many elements as the argument sequence. For example, `$(mapprefix foo, a b "c d")' expands to `foo a foo b foo "c d"'.  Node: Subsection 8-3-25, Next: Subsection 8-3-26, Prev: Subsection 8-3-24, Up: Section 8-3 8.3.25 add-wrapper ==================== << $(add-wrapper prefix, suffix, sequence) : Array prefix : String suffix : String sequence : Sequence >> The `add-wrapper' functions adds both a prefix and a suffix to each component of a sequence. For example, the expression `$(add-wrapper dir/, .c, a b)' evaluates to `dir/a.c dir/b.c'. String concatenation is used. The array result has the same number of elements as the argument sequence.  Node: Subsection 8-3-26, Next: Subsection 8-3-27, Prev: Subsection 8-3-25, Up: Section 8-3 8.3.26 set ============ << $(set sequence) : Array sequence : Sequence >> The `set' function sorts a set of string components, eliminating duplicates. For example, `$(set z y z "m n" w a)' expands to `"m n" a w y z'.  Node: Subsection 8-3-27, Next: Subsection 8-3-28, Prev: Subsection 8-3-26, Up: Section 8-3 8.3.27 mem ============ << $(mem elem, sequence) : Boolean elem : String sequence : Sequence >> The `mem' function tests for membership in a sequence. For example, `$(mem "m n", y z "m n" w a)' evaluates to `true', while `$(mem m n, y z "m n" w a)' evaluates to `false'.  Node: Subsection 8-3-28, Next: Subsection 8-3-29, Prev: Subsection 8-3-27, Up: Section 8-3 8.3.28 intersection ===================== << $(intersection sequence1, sequence2) : Array sequence1 : Sequence sequence2 : Sequence >> The `intersection' function takes two arguments, treats them as sets of strings, and computes their intersection. The order of the result is undefined, and it may contain duplicates. Use the `set' function to sort the result and eliminate duplicates in the result if desired. For example, the expression `$(intersection c a b a, b a)' evaluates to `a b a'.  Node: Subsection 8-3-29, Next: Subsection 8-3-30, Prev: Subsection 8-3-28, Up: Section 8-3 8.3.29 intersects =================== << $(intersects sequence1, sequence2) : Boolean sequence1 : Sequence sequence2 : Sequence >> The `intersects' function tests whether two sets have a non-empty intersection. This is slightly more efficient than computing the intersection and testing whether it is empty. For example, the expression `$(intersects a b c, d c e)' evaluates to `true', and `$(intersects a b c a, d e f)' evaluates to `false'.  Node: Subsection 8-3-30, Next: Subsection 8-3-31, Prev: Subsection 8-3-29, Up: Section 8-3 8.3.30 set-diff ================= << $(set-diff sequence1, sequence2) : Array sequence1 : Sequence sequence2 : Sequence >> The `set-diff' function takes two arguments, treats them as sets of strings, and computes their difference (all the elements of the first set that are not present in the second one). The order of the result is undefined and it may contain duplicates. Use the `set' function to sort the result and eliminate duplicates in the result if desired. For example, the expression `$(set-diff c a b a e, b a)' evaluates to `c e'.  Node: Subsection 8-3-31, Next: Subsection 8-3-32, Prev: Subsection 8-3-30, Up: Section 8-3 8.3.31 filter =============== << $(filter patterns, sequence) : Array patterns : Sequence sequence : Sequence >> The `filter' function picks elements from a sequence. The patterns is a non-empty sequence of patterns, each may contain one occurrence of the wildcard `%' character. For example `$(filter %.h %.o, a.c x.o b.h y.o "hello world".c)' evaluates to `x.o b.h y.o'.  Node: Subsection 8-3-32, Next: Subsection 8-3-33, Prev: Subsection 8-3-31, Up: Section 8-3 8.3.32 filter-out =================== << $(filter-out patterns, sequence) : Array patterns : Sequence sequence : Sequence >> The `filter-out' function removes elements from a sequence. The patterns is a non-empty sequence of patterns, each may contain one occurrence of the wildcard `%' character. For example `$(filter-out %.c %.h, a.c x.o b.h y.o "hello world".c)' evaluates to `x.o y.o'.  Node: Subsection 8-3-33, Next: Subsection 8-3-34, Prev: Subsection 8-3-32, Up: Section 8-3 8.3.33 capitalize =================== << $(capitalize sequence) : Array sequence : Sequence >> The `capitalize' function capitalizes each word in a sequence. For example, `$(capitalize through the looking Glass)' evaluates to `Through The Looking Glass'.  Node: Subsection 8-3-34, Next: Subsection 8-3-35, Prev: Subsection 8-3-33, Up: Section 8-3 8.3.34 uncapitalize ===================== << $(uncapitalize sequence) : Array sequence : Sequence >> The `uncapitalize' function uncapitalizes each word in its argument. For example, `$(uncapitalize through the looking Glass)' evaluates to `through the looking glass'.  Node: Subsection 8-3-35, Next: Subsection 8-3-36, Prev: Subsection 8-3-34, Up: Section 8-3 8.3.35 uppercase ================== << $(uppercase sequence) : Array sequence : Sequence >> The `uppercase' function converts each word in a sequence to uppercase. For example, `$(uppercase through the looking Glass)' evaluates to `THROUGH THE LOOKING GLASS'.  Node: Subsection 8-3-36, Next: Subsection 8-3-37, Prev: Subsection 8-3-35, Up: Section 8-3 8.3.36 lowercase ================== << $(lowercase sequence) : Array sequence : Sequence >> The `lowercase' function reduces each word in its argument to lowercase. For example, `$(lowercase through tHe looking Glass)' evaluates to `through the looking glass'.  Node: Subsection 8-3-37, Next: Subsection 8-3-38, Prev: Subsection 8-3-36, Up: Section 8-3 8.3.37 system =============== << system(s) s : Sequence >> The `system' function is used to evaluate a shell expression. This function is used internally by omake to evaluate shell commands. For example, the following program is equivalent to the expression `system(ls foo)'. << ls foo >>  Node: Subsection 8-3-38, Next: Subsection 8-3-39, Prev: Subsection 8-3-37, Up: Section 8-3 8.3.38 shell ============== << $(shell command) : Array $(shella command) : Array $(shell-code command) : Int command : Sequence >> The `shell' function evaluates a command using the command shell, and returns the whitespace-separated words of the standard output as the result. The `shella' function acts similarly, but it returns the lines as separate items in the array. The `shell-code' function returns the exit code. The output is not diverted. For example, if the current directory contains the files `OMakeroot', `OMakefile', and `hello.c', then `$(shell ls)' evaluates to `hello.c OMakefile OMakeroot' (on a Unix system).  Node: Subsection 8-3-39, Next: Subsection 8-3-40, Prev: Subsection 8-3-38, Up: Section 8-3 8.3.39 export =============== The `export' function allows one to capture the current environment in a variable. For example, the following code: <> will print `1 1 2'. The arguments to this function are interpreted the exact same way as the arguments to the `export' special form (see Section 5.3*Note Section 5-3::).  Node: Subsection 8-3-40, Next: Subsection 8-3-41, Prev: Subsection 8-3-39, Up: Section 8-3 8.3.40 while ============== << while >> --or-- << while case ... case default >> The loop is executed while the test is true. In the first form, the `' is executed on every loop iteration. In the second form, the body `' is selected, as the first case where the test `' is true. If none apply, the optional default case is evaluated. If no cases are true, the loop exits. The environment is automatically exported. Examples. Iterate for `i' from `0' to `9'. << i = 0 while $(lt $i, 10) echo $i i = $(add $i, 1) >> The following example is equivalent. << i = 0 while true case $(lt $i, 10) echo $i i = $(add $i, 1) >> The following example is similar, but some special cases are printed. value is printed. << i = 0 while $(lt $i, 10) case $(equal $i, 0) echo zero case $(equal $i, 1) echo one default echo $i >> The 'break' function can be used to break out of the `while' loop early.  Node: Subsection 8-3-41, Next: Subsection 8-3-42, Prev: Subsection 8-3-40, Up: Section 8-3 8.3.41 break ============== << break >> Terminate execution of the innermost loop, returning the current state.  Node: Subsection 8-3-42, Next: Section 8-4, Prev: Subsection 8-3-41, Up: Section 8-3 8.3.42 random, random-init ============================ << random-init(i) i : Int random() : Int >> Produce a random number. The numbers are pseudo-random, and are not cryptographically secure. The generator is initialized form semi-random system data. Subsequent runs should produce different results. The `rando-init' function can be used to return the generator to a known state.  Node: Section 8-4, Next: Subsection 8-4-1, Prev: Section 8-3, Up: Chapter 8 8.4 Arithmetic *=*=*=*=*=*=*=*= * Menu: * Subsection 8-4-1:: int * Subsection 8-4-2:: float * Subsection 8-4-3:: Basic arithmetic * Subsection 8-4-4:: Comparisons  Node: Subsection 8-4-1, Next: Subsection 8-4-2, Prev: Section 8-4, Up: Section 8-4 8.4.1 int =========== The `int' function can be used to create integers. It returns an `Int' object. `$(int 17)'.  Node: Subsection 8-4-2, Next: Subsection 8-4-3, Prev: Subsection 8-4-1, Up: Section 8-4 8.4.2 float ============= The `float' function can be used to create floating-point numbers. It returns a `Float' object. `$(float 3.1415926)'.  Node: Subsection 8-4-3, Next: Subsection 8-4-4, Prev: Subsection 8-4-2, Up: Section 8-4 8.4.3 Basic arithmetic ======================== The following functions can be used to perform basic arithmetic. - `$(neg )': arithmetic inverse - `$(add )': addition. - `$(sub )': subtraction. - `$(mul )': multiplication. - `$(div )': division. - `$(mod )': remainder. - `$(lnot )': bitwise inverse. - `$(land )': bitwise and. - `$(lor )': bitwise or. - `$(lxor )': bitwise exclusive-or. - `$(lsl )': logical shift left. - `$(lsr )': logical shift right. - `$(asr )': arithmetic shift right. - `$(min )': smallest element. - `$(max )': largest element.  Node: Subsection 8-4-4, Next: Section 8-5, Prev: Subsection 8-4-3, Up: Section 8-4 8.4.4 Comparisons =================== The following functions can be used to perform numerical comparisons. - `$(lt )': less then. - `$(le )': no more than. - `$(eq )': equal. - `$(ge )': no less than. - `$(gt )': greater than. - `$(ult )': unsigned less than. - `$(ule )': unsigned greater than. - `$(uge )': unsigned greater than or equal. - `$(ugt )': unsigned greater than.  Node: Section 8-5, Next: Subsection 8-5-1, Prev: Section 8-4, Up: Chapter 8 8.5 First-class functions *=*=*=*=*=*=*=*=*=*=*=*=*=* * Menu: * Subsection 8-5-1:: fun * Subsection 8-5-2:: apply * Subsection 8-5-3:: applya * Subsection 8-5-4:: create-map, create-lazy-map  Node: Subsection 8-5-1, Next: Subsection 8-5-2, Prev: Section 8-5, Up: Section 8-5 8.5.1 fun =========== The `fun' form introduces anonymous functions. `$(fun , ..., , )' The last argument is the body of the function. The other arguments are the parameter names. The three following definitions are equivalent. << F(X, Y) = return($(addsuffix $(Y), $(X))) F = $(fun X, Y, $(addsuffix $(Y), $(X))) F = fun(X, Y) value $(addsuffix $(Y), $(X)) >>  Node: Subsection 8-5-2, Next: Subsection 8-5-3, Prev: Subsection 8-5-1, Up: Section 8-5 8.5.2 apply ============= The `apply' operator is used to apply a function. `$(apply , )' Suppose we have the following function definition. << F(X, Y) = return($(addsuffix $(Y), $(X))) >> The the two expressions below are equivalent. << X = F(a b c, .c) X = $(apply $(F), a b c, .c) >>  Node: Subsection 8-5-3, Next: Subsection 8-5-4, Prev: Subsection 8-5-2, Up: Section 8-5 8.5.3 applya ============== The `applya' operator is used to apply a function to an array of arguments. `$(applya , )' For example, in the following program, the value of `Z' is `file.c'. << F(X, Y) = return($(addsuffix $(Y), $(X))) args[] = file .c Z = $(applya $(F), $(args)) >>  Node: Subsection 8-5-4, Next: Section 8-6, Prev: Subsection 8-5-3, Up: Section 8-5 8.5.4 create-map, create-lazy-map =================================== The `create-map' is a simplified form for creating `Map' objects. The `create-map' function takes an even number of arguments that specify key/value pairs. For example, the following values are equivalent. << X = $(create-map name1, xxx, name2, yyy) X. = extends $(Map) $|name1| = xxx $|name2| = yyy >> The `create-lazy-map' function is similar, but the values are computed lazily. The following two definitions are equivalent. << Y = $(create-lazy-map name1, $(xxx), name2, $(yyy)) Y. = extends $(Map) $|name1| = $`(xxx) $|name2| = $`(yyy) >> The 'create-lazy-map' function is used in rule construction.  Node: Section 8-6, Next: Subsection 8-6-1, Prev: Section 8-5, Up: Chapter 8 8.6 Iteration and mapping *=*=*=*=*=*=*=*=*=*=*=*=*=* * Menu: * Subsection 8-6-1:: foreach  Node: Subsection 8-6-1, Next: Chapter 9, Prev: Section 8-6, Up: Section 8-6 8.6.1 foreach =============== The `foreach' function maps a function over a sequence. << $(foreach , ) foreach(, ) >> For example, the following program defines the variable `X' as an array `a.c b.c c.c'. << X = foreach(x, a b c) value $(x).c # Equivalent expression X = $(foreach $(fun x, $(x).c), abc) >> There is also an abbreviated syntax. The `export' form can also be used in a `foreach' body. The final value of `X' is `a.c b.c c.c'. << X = foreach(x, a b c) X += $(x).c export >> The 'break' function can be used to break out of the loop early.  Node: Chapter 9, Next: Section 9-1, Prev: Section 8-6, Up: Top Chapter 9 File, I/O and system operations ********************************************* * Menu: * Section 9-1:: File names * Section 9-2:: Path search * Section 9-3:: File stats * Section 9-4:: Globbing and file listings * Section 9-5:: Filesystem operations * Section 9-6:: vmount * Section 9-7:: File predicates * Section 9-8:: IO functions * Section 9-9:: Printing functions * Section 9-10:: Value printing functions * Section 9-11:: Higher-level IO functions  Node: Section 9-1, Next: Subsection 9-1-1, Prev: Chapter 9, Up: Chapter 9 9.1 File names *=*=*=*=*=*=*=*= * Menu: * Subsection 9-1-1:: file, dir * Subsection 9-1-2:: tmpfile * Subsection 9-1-3:: in * Subsection 9-1-4:: basename * Subsection 9-1-5:: dirname * Subsection 9-1-6:: rootname * Subsection 9-1-7:: dirof * Subsection 9-1-8:: fullname * Subsection 9-1-9:: absname * Subsection 9-1-10:: homename * Subsection 9-1-11:: suffix  Node: Subsection 9-1-1, Next: Subsection 9-1-2, Prev: Section 9-1, Up: Section 9-1 9.1.1 file, dir ================= << $(file sequence) : File Sequence sequence : Sequence $(dir sequence) : Dir Sequence sequence : Sequence >> The `file' and `dir' functions define location-independent references to files and directories. In omake, the commands to build a target are executed in the target's directory. Since there may be many directories in an omake project, the build system provides a way to construct a reference to a file in one directory, and use it in another without explicitly modifying the file name. The functions have the following syntax, where the name should refer to a file or directory. For example, we can construct a reference to a file `foo' in the current directory. << FOO = $(file foo) .SUBDIRS: bar >> If the `FOO' variable is expanded in the `bar' subdirectory, it will expand to `../foo'. These commands are often used in the top-level OMakefile to provide location-independent references to top-level directories, so that build commands may refer to these directories as if they were absolute. << ROOT = $(dir .) LIB = $(dir lib) BIN = $(dir bin) >> Once these variables are defined, they can be used in build commands in subdirectories as follows, where `$(BIN)' will expand to the location of the `bin' directory relative to the command being executed. << install: hello cp hello $(BIN) >>  Node: Subsection 9-1-2, Next: Subsection 9-1-3, Prev: Subsection 9-1-1, Up: Section 9-1 9.1.2 tmpfile =============== << $(tmpfile prefix) : File $(tmpfile prefix, suffix) : File prefix : String suffix : String >> The `tmpfile' function returns the name of a fresh temporary file in the temporary directory.  Node: Subsection 9-1-3, Next: Subsection 9-1-4, Prev: Subsection 9-1-2, Up: Section 9-1 9.1.3 in ========== << $(in dir, exp) : String Array dir : Dir exp : expression >> The `in' function is closely related to the `dir' and `file' functions. It takes a directory and an expression, and evaluates the expression in that effective directory. For example, one common way to install a file is to define a symbol link, where the value of the link is relative to the directory where the link is created. The following commands create links in the `$(LIB)' directory. << FOO = $(file foo) install: ln -s $(in $(LIB), $(FOO)) $(LIB)/foo >> Note that the `in' function only affects the expansion of `Node' (`File' and `Dir') values.  Node: Subsection 9-1-4, Next: Subsection 9-1-5, Prev: Subsection 9-1-3, Up: Section 9-1 9.1.4 basename ================ << $(basename files) : String Sequence files : String Sequence >> The `basename' function returns the base names for a list of files. The basename is the filename with any leading directory components removed. For example, the expression `$(basename dir1/dir2/a.out /etc/modules.conf /foo.ml)' evaluates to `a.out modules.conf foo.ml'.  Node: Subsection 9-1-5, Next: Subsection 9-1-6, Prev: Subsection 9-1-4, Up: Section 9-1 9.1.5 dirname =============== << $(dirname files) : String Sequence files : String Sequence >> The `dirname' function returns the directory name for a list of files. The directory name is the filename with the basename removed. If a name does not have a directory part, the directory is "." For example, the expression `$(dirname dir1\dir2\a.out /etc/modules.conf /foo.ml bar.ml)' evaluates to `dir1/dir2 /etc / .'. Note: this function is different from the `dirof' function. The function `dirname' is simple a function over strings, while `dirof' is a function on filenames.  Node: Subsection 9-1-6, Next: Subsection 9-1-7, Prev: Subsection 9-1-5, Up: Section 9-1 9.1.6 rootname ================ << $(rootname files) : String Sequence files : String Sequence >> The `rootname' function returns the root name for a list of files. The rootname is the filename with the final suffix removed. For example, the expression `$(rootname dir1/dir2/a.out /etc/a.b.c /foo.ml)' evaluates to `dir1/dir2/a /etc/a.b /foo'.  Node: Subsection 9-1-7, Next: Subsection 9-1-8, Prev: Subsection 9-1-6, Up: Section 9-1 9.1.7 dirof ============= << $(dirof files) : Dir Sequence files : File Sequence >> The `dirof' function returns the directory for each of the listed files. For example, the expression `$(dirof dir/dir2/a.out /etc/modules.conf /foo.ml)' evaluates to the directories `dir1/dir2 /etc /'.  Node: Subsection 9-1-8, Next: Subsection 9-1-9, Prev: Subsection 9-1-7, Up: Section 9-1 9.1.8 fullname ================ << $(fullname files) : String Sequence files : File Sequence >> The `fullname' function returns the pathname relative to the project root for each of the files or directories.  Node: Subsection 9-1-9, Next: Subsection 9-1-10, Prev: Subsection 9-1-8, Up: Section 9-1 9.1.9 absname =============== << $(absname files) : String Sequence files : File Sequence >> The `absname' function returns the absolute pathname for each of the files or directories.  Node: Subsection 9-1-10, Next: Subsection 9-1-11, Prev: Subsection 9-1-9, Up: Section 9-1 9.1.10 homename ================= << $(homename files) : String Sequence files : File Sequence >> The `homename' function returns the name of a file in tilde form, if possible. The unexpanded forms are computed lazily: the `homename' function will usually evaluate to an absolute pathname until the first tilde-expansion for the same directory.  Node: Subsection 9-1-11, Next: Section 9-2, Prev: Subsection 9-1-10, Up: Section 9-1 9.1.11 suffix =============== << $(suffix files) : String Sequence files : StringSequence >> The `suffix' function returns the suffixes for a list of files. If a file has no suffix, the function returns the empty string. For example, the expression `$(suffix dir1/dir2/a.out /etc/a /foo.ml)' evaluates to `.out .ml'.  Node: Section 9-2, Next: Subsection 9-2-1, Prev: Section 9-1, Up: Chapter 9 9.2 Path search *=*=*=*=*=*=*=*=* * Menu: * Subsection 9-2-1:: which * Subsection 9-2-2:: where * Subsection 9-2-3:: rehash * Subsection 9-2-4:: exists-in-path * Subsection 9-2-5:: digest * Subsection 9-2-6:: find-in-path * Subsection 9-2-7:: digest-path  Node: Subsection 9-2-1, Next: Subsection 9-2-2, Prev: Section 9-2, Up: Section 9-2 9.2.1 which ============= << $(which files) : File Sequence files : String Sequence >> The `which' function searches for executables in the current command search path, and returns `file' values for each of the commands. It is an error if a command is not found.  Node: Subsection 9-2-2, Next: Subsection 9-2-3, Prev: Subsection 9-2-1, Up: Section 9-2 9.2.2 where ============= The `where' function is similar to which, except it returns the list of all the locations of the given executable (in the order in which the corresponding directories appear in `$PATH'). In case a command is handled internally by the `Shell' object, the first string in the output will describe the command as a built-in function. << % where echo echo is a Shell object method (a built-in function) /bin/echo >>  Node: Subsection 9-2-3, Next: Subsection 9-2-4, Prev: Subsection 9-2-2, Up: Section 9-2 9.2.3 rehash ============== << rehash() >> The `rehash' function resets all search paths.  Node: Subsection 9-2-4, Next: Subsection 9-2-5, Prev: Subsection 9-2-3, Up: Section 9-2 9.2.4 exists-in-path ====================== << $(exists-in-path files) : String files : String Sequence >> The `exists-in-path' function tests whether all executables are present in the current search path.  Node: Subsection 9-2-5, Next: Subsection 9-2-6, Prev: Subsection 9-2-4, Up: Section 9-2 9.2.5 digest ============== << $(digest files) : String Array file : File Array raises RuntimeException $(digest-optional files) : String Array file : File Array >> The `digest' and `digest-optional' functions compute MD5 digests of files. The `digest' function raises an exception if a file does no exist. The `digest-optional' returns `false' if a file does no exist. MD5 digests are cached.  Node: Subsection 9-2-6, Next: Subsection 9-2-7, Prev: Subsection 9-2-5, Up: Section 9-2 9.2.6 find-in-path ==================== << $(find-in-path path, files) : File Array path : Dir Array files : String Array raises RuntimeException $(find-in-path-optional path, files) : File Array >> The `find-in-path' function searches for the files in a search path. Only the tail of the filename is significant. The `find-in-path' function raises an exception if the file can't be found. The `find-in-path-optional' function silently removes files that can't be found.  Node: Subsection 9-2-7, Next: Section 9-3, Prev: Subsection 9-2-6, Up: Section 9-2 9.2.7 digest-path =================== << $(digest-in-path path, files) : String/File Array path : Dir Array files : String Array raises RuntimeException $(digest-in-path-optional path, files) : String/File Array >> The `digest-in-path' function searches for the files in a search path and returns the file and digest for each file. Only the tail of the filename is significant. The `digest-in-path' function raises an exception if the file can't be found. The `digest-in-path-optional' function silently removes elements that can't be found.  Node: Section 9-3, Next: Subsection 9-3-1, Prev: Section 9-2, Up: Chapter 9 9.3 File stats *=*=*=*=*=*=*=*= * Menu: * Subsection 9-3-1:: file-exists, target-exists, target-is-proper * Subsection 9-3-2:: stat-reset * Subsection 9-3-3:: filter-exists, filter-targets, filter-proper-targets * Subsection 9-3-4:: find-targets-in-path, find-targets-in-path-optional * Subsection 9-3-5:: file-sort * Subsection 9-3-6:: file-check-sort  Node: Subsection 9-3-1, Next: Subsection 9-3-2, Prev: Section 9-3, Up: Section 9-3 9.3.1 file-exists, target-exists, target-is-proper ==================================================== \@na me{@default197} << $(file-exists files) : String $(target-exists files) : String $(target-is-proper files) : String files : File Sequence >> The `file-exists' function checks whether the files listed exist. The `target-exists' function is similar to the `file-exists' function. However, it returns true if the file exists or if it can be built by the current project. The `target-is-proper' returns true only if the file can be generated in the current project.  Node: Subsection 9-3-2, Next: Subsection 9-3-3, Prev: Subsection 9-3-1, Up: Section 9-3 9.3.2 stat-reset ================== << $(stat-reset files) : String files : File Sequence >> OMake uses a stat-cache. The `stat-reset' function reset the `stat' information for the given files, forcing the `stat' information to be recomputed the next time it is requested.  Node: Subsection 9-3-3, Next: Subsection 9-3-4, Prev: Subsection 9-3-2, Up: Section 9-3 9.3.3 filter-exists, filter-targets, filter-proper-targets ============================================================ \@na me{@default201} << $(filter-exists files) : File Sequence $(filter-targets files) : File Sequence $(filter-proper-targets) : File Sequence files : File Sequence >> The `filter-exists', `filter-targets', and `filter-proper-targets' functions remove files from a list of files. - `filter-exists': the result is the list of files that exist. - `filter-targets': the result is the list of files either exist, or can be built by the current project. - `filter-proper-targets': the result is the list of files that can be built in the current project. One way to create a simple "clean" rule that removes generated files from the project is by removing all files that can be built in the current project. CAUTION: you should be careful before you do this. The rule removes any file that can potentially be reconstructed. There is no check to make sure that the commands to rebuild the file would actually succeed. Also, note that no file outside the current project will be deleted. << .PHONY: clean clean: rm $(filter-proper-targets $(ls R, .)) >> See the `dependencies-proper' function to see an alternate method for removing intermediate files. If you use CVS, you may wish to use the `cvs_realclean' program that is distributed with `omake'.  Node: Subsection 9-3-4, Next: Subsection 9-3-5, Prev: Subsection 9-3-3, Up: Section 9-3 9.3.4 find-targets-in-path, find-targets-in-path-optional =========================================================== << $(find-targets-in-path path files) : File Array $(find-targets-in-path-optional path, files) : File Array path : Dir Array files : File Sequence >> The `find-target-in-path' function searches for targets in the search path. For each file `file' in the file list, the path is searched sequentially for a directory `dir' such that the target `dir/file' exists. If so, the file `dir/file' is returned. For example, suppose you are building a C project, and project contains a subdirectory `src/' containing only the files `fee.c' and `foo.c'. The following expression evaluates to the files `src/fee.o' `src/foo.o' even if the files have not already been built. << $(find-targets-in-path lib src, fee.o foo.o) # Evaluates to src/fee.o src/foo.o >> The `find-targets-in-path' function raises an exception if the file can't be found. The `find-targets-in-path-optional' function silently removes targets that can't be found. << $(find-targets-in-path-optional lib src, fee.o foo.o fum.o) # Evaluates to src/fee.o src/foo.o >>