diff options
Diffstat (limited to 'libslang/doc/tm/rtl')
| -rw-r--r-- | libslang/doc/tm/rtl/array.tm | 378 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/assoc.tm | 76 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/bstr.tm | 151 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/debug.tm | 98 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/dir.tm | 223 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/eval.tm | 119 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/import.tm | 51 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/info.tm | 202 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/math.tm | 291 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/message.tm | 111 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/misc.tm | 201 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/ospath.tm | 77 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/posio.tm | 154 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/posix.tm | 285 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/stack.tm | 165 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/stdio.tm | 421 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/strops.tm | 736 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/struct.tm | 104 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/time.tm | 137 | ||||
| -rwxr-xr-x | libslang/doc/tm/rtl/tm-sort.sl | 153 | ||||
| -rw-r--r-- | libslang/doc/tm/rtl/type.tm | 245 | ||||
| -rwxr-xr-x | libslang/doc/tm/rtl/whatelse.sl | 116 |
22 files changed, 4494 insertions, 0 deletions
diff --git a/libslang/doc/tm/rtl/array.tm b/libslang/doc/tm/rtl/array.tm new file mode 100644 index 0000000..7f55ba3 --- /dev/null +++ b/libslang/doc/tm/rtl/array.tm @@ -0,0 +1,378 @@ +\function{_isnull} +\synopsis{Check array for NULL elements} +\usage{Char_Type[] = _isnull (a[])} +\description + This function may be used to test for the presence of NULL elements + of an array. Specifically, it returns a \var{Char_Type} array of + with the same number of elements and dimensionality of the input + array. If an element of the input array is \NULL, then the + corresponding element of the output array will be set to \1, + otherwise it will be set to \0. +\example + Set all \NULL elements of a string array \exmp{A} to the empty + string \exmp{""}: +#v+ + A[where(_isnull(A))] = ""; +#v- +\notes + It is important to understand the difference between \exmp{A==NULL} + and \exmp{_isnull(A)}. The latter tests all elements of \exmp{A} + against \NULL, whereas the former only tests \exmp{A} itself. +\seealso{where, array_map} +\done + +\function{_reshape} +\synopsis{Copy an array to a new shape} +\usage{Array_Type _reshape (Array_Type A, Array_Type I)} +\description + The \var{_reshape} function creates a copy of an array \var{A}, + reshapes it to the form specified by \var{I} and returns the result. + The elements of \var{I} specify the new dimensions of the copy of + \var{A} and must be consistent with the number of elements \var{A}. +\example + If \var{A} is a \var{100} element 1-d array, a new array 2-d array of + size \var{20} by \var{5} may be created from the elements of \var{A} + by +#v+ + A = _reshape (A, [20, 5]); +#v- + In this example, the original array was no longer needed. Hence, it + is preferable to make use of the \var{__tmp} operator to avoid the + creation of a new array, i.e., +#v+ + A = _reshape (__tmp(A), [20,5]); +#v- +\notes + The \var{reshape} function performs a similar function to + \var{_reshape}. In fact, the \var{_reshape} function could have been + implemented via: +#v+ + define _reshape (a, i) + { + a = @a; % Make a new copy + reshape (a, i); + return a; + } +#v- +\seealso{reshape, array_info} +\done + +\function{array_info} +\synopsis{Returns information about an array} +\usage{(Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a)} +\description + The \var{array_info} function returns information about the array \var{a}. + It returns three values: an 1-d integer array specifying the + size of each dimension of \var{a}, the number of dimensions of + \var{a}, and the data type of \var{a}. +\example + The \var{array_info} function may be used to find the number of rows + of an array: +#v+ + define num_rows (a) + { + variable dims, num_dims, data_type; + + (dims, num_dims, data_type) = array_info (a); + return dims [0]; + } +#v- + For 1-d arrays, this information is more easily obtained from the + \var{length} function. +\seealso{typeof, reshape, length, _reshape} +\done + +\function{array_map} +\synopsis{Apply a function to each element of an array} +\usage{Array_Type array_map (type, func, arg0, ...)} +#v+ + DataType_Type type; + Ref_Type func; +#v- +\description + The \var{array_map} function may be used to apply a function to each + element of an array and returns the result as an array of a + specified type. The \var{type} parameter indicates what kind of + array should be returned and generally corresponds to the return + type of the function. The \var{arg0} parameter should be an array + and is used to determine the dimensions of the resulting array. If + any subsequent arguments correspond to an array of the same size, + then those array elements will be passed in parallel with the first + arrays arguments. +\example + The first example illustrates how to apply the \var{strlen} function + to an array of strings: +#v+ + S = ["", "Train", "Subway", "Car"]; + L = array_map (Integer_Type, &strlen, S); +#v- + This is equivalent to: +#v+ + S = ["", "Train", "Subway", "Car"]; + L = Integer_Type [length (S)]; + for (i = 0; i < length (S); i++) L[i] = strlen (S[i]); +#v- + + Now consider an example involving the \var{strcat} function: +#v+ + files = ["slang", "slstring", "slarray"]; + + exts = ".c"; + cfiles = array_map (String_Type, &strcat, files, exts); + % ==> cfiles = ["slang.c slstring.c slarray.c"]; + + exts = [".a",".b",".c"]; + xfiles = array_map (String_Type, &strcat, files, exts); + % ==> xfiles = ["slang.a", "slstring.b", "slarray.c"]; +#v- +\notes + Many mathemetical functions already work transparantly on arrays. + For example, the following two statements produce identical results: +#v+ + B = sin (A); + B = array_map (Double_Type, &sin, A); +#v- +\seealso{array_info, strlen, strcat, sin} +\done + +\function{array_sort} +\synopsis{Sort an array} +\usage{Array_Type array_sort (Array_Type a [, String_Type or Ref_Type f])} +\description + \var{array_sort} sorts the array \var{a} into ascending order and + returns an integer array that represents the result of the sort. If + the optional second parameter \var{f} is present, the function + specified by \var{f} will be used to compare elements of \var{a}; + otherwise, a built-in sorting function will be used. + + If \var{f} is present, then it must be either a string representing + the name of the comparison function, or a reference to the function. + The sort function represented by \var{f} must be a \slang + user-defined function that takes two arguments. The function must + return an integer that is less than zero if the first parameter is + considered to be less than the second, zero if they are equal, and a + value greater than zero if the first is greater than the second. + + If the comparision function is not specified, then a built-in comparison + function appropriate for the data type will be used. For example, + if \var{a} is an array of character strings, then the sort will be + preformed using \var{strcmp}. + + The integer array returned by this function is simply an index that + indicates the order of the sorted array. The input array \var{a} is + not changed. +\example + An array of strings may be sorted using the \var{strcmp} function + since it fits the specification for the sorting function described + above: +#v+ + variable A = String_Type [3]; + A[0] = "gamma"; A[1] = "alpha"; A[2] = "beta"; + + variable I = array_sort (A, &strcmp); +#v- + Alternatively, one may use +#v+ + variable I = array_sort (A); +#v- + to use the built-in comparison function. + + After the \var{array_sort} has executed, the variable \var{I} will + have the values \exmp{[2, 0, 1]}. This array can be used to + re-shuffle the elements of \var{A} into the sorted order via the + array index expression \exmp{A = A[I]}. +\seealso{strcmp} +\done + +\function{cumsum} +\synopsis{Compute the cumulative sum of an array} +\usage{result = cumsum (Array_Type a [, Int_Type dim])} +\description + The \var{cumsum} function performs a cumulative sum over the + elements of a numeric array and returns the resulting. If a second + argument is given, then it specifies the dimension of the array to + be summed over. For example, the cumulative sum of + \exmp{[1,2,3,4]}, is the array \exmp{[1,1+2,1+2+3,1+2+3+4]}, i.e., + \exmp{[1,3,6,10]}. +\seealso{sum} +\done + +\function{init_char_array} +\synopsis{Initialize an array of characters} +\usage{init_char_array (Array_Type a, String_Type s)} +\description + The \var{init_char_array} function may be used to initialize a + character array \var{a} by setting the elements of the array + \var{a} to the corresponding characters of the string \var{s}. +\example + The statements +#v+ + variable a = Char_Type [10]; + init_char_array (a, "HelloWorld"); +#v- + creates an character array and initializes its elements to the + characters in the string \exmp{"HelloWorld"}. +\notes + The character array must be large enough to hold all the characters + of the initialization string. +\seealso{bstring_to_array, strlen, strcat} +\done + +\function{length} +\synopsis{Get the length of an object} +\usage{Integer_Type length (obj)} +\description + The \var{length} function may be used to get information about the + length of an object. For simple scalar data-types, it returns \1. + For arrays, it returns the total number of elements of the array. +\notes + If \var{obj} is a string, \var{length} returns \1 because a + \var{String_Type} object is considered to be a scalar. To get the + number of characters in a string, use the \var{strlen} function. +\seealso{array_info, typeof, strlen} +\done + +\function{max} +\synopsis{Get the maximum value of an array} +\usage{result = max (Array_Type a [,Int_Type dim])} +\description + The \var{max} function examines the elements of a numeric array and + returns the value of the largest element. If a second argument is + given, then it specifies the dimension of the array to be searched. + In this case, an array of dimension one less than that of the input array + will be returned with the corresponding elements in the specified + dimension replaced by the minimum value in that dimension. +\example + Consider the 2-d array +#v+ + 1 2 3 4 5 + 6 7 8 9 10 +#v- + generated by +#v+ + a = _reshape ([1:10], [2, 5]); +#v- + Then \exmp{max(a)} will return \exmp{10}, and \exmp{max(a,0)} will return + a 1-d array with elements +#v+ + 6 7 8 9 10 +#v- +\seealso{max, sum, reshape} +\done + +\function{min} +\synopsis{Get the minimum value of an array} +\usage{result = min (Array_Type a [,Int_Type dim])} +\description + The \var{min} function examines the elements of a numeric array and + returns the value of the smallest element. If a second argument is + given, then it specifies the dimension of the array to be searched. + In this case, an array of dimension one less than that of the input array + will be returned with the corresponding elements in the specified + dimension replaced by the minimum value in that dimension. +\example + Consider the 2-d array +#v+ + 1 2 3 4 5 + 6 7 8 9 10 +#v- + generated by +#v+ + a = _reshape ([1:10], [2, 5]); +#v- + Then \exmp{min(a)} will return \exmp{1}, and \exmp{min(a,0)} will return + a 1-d array with elements +#v+ + 1 2 3 4 5 +#v- +\seealso{max, sum, reshape} +\done + +\function{reshape} +\synopsis{Reshape an array} +\usage{reshape (Array_Type A, Array_Type I)} +\description + The \var{reshape} function changes the size of \var{A} to have the size + specified by the 1-d integer array \var{I}. The elements of \var{I} + specify the new dimensions of \var{A} and must be consistent with + the number of elements \var{A}. +\example + If \var{A} is a \var{100} element 1-d array, it can be changed to a + 2-d \var{20} by \var{5} array via +#v+ + reshape (A, [20, 5]); +#v- + However, \exmp{reshape(A, [11,5])} will result in an error because + the \exmp{[11,5]} array specifies \exmp{55} elements. +\notes + Since \var{reshape} modifies the shape of an array, and arrays are + treated as references, then all references to the array will + reference the new shape. If this effect is unwanted, then use the + \var{_reshape} function instead. +\seealso{_reshape, array_info} +\done + +\function{sum} +\synopsis{Sum over the elements of an array} +\usage{result = sum (Array_Type a [, Int_Type dim])} +\description + The \var{sum} function sums over the elements of a numeric array and + returns its result. If a second argument is given, then it + specifies the dimension of the array to be summed over. In this + case, an array of dimension one less than that of the input array + will be returned. + + If the input array is an integer type, then the resulting value will + be a \var{Double_Type}. If the input array is a \var{Float_Type}, + then the result will be a \var{Float_Type}. +\example + The mean of an array \exmp{a} of numbers is +#v+ + sum(a)/length(a) +#v- +\seealso{cumsum, transpose, reshape} +\done + +\function{transpose} +\synopsis{Transpose an array} +\usage{Array_Type transpose (Array_Type a)} +\description + The \var{transpose} function returns the transpose of a specified + array. By definition, the transpose of an array, say one with + elements \exmp{a[i,j,...k]} is an array whose elements are + \exmp{a[k,...,j,i]}. +\seealso{_reshape, reshape, sum, array_info} +\done + +\function{where} +\synopsis{Get indices where an integer array is non-zero} +\usage{Array_Type where (Array_Type a)} +\description + The \var{where} function examines an numeric array \var{a} and + returns an integer array giving the indices of \var{a} + where the corresponding element of \var{a} is non-zero. + + Although this function may appear to be simple or even trivial, it + is arguably one of the most important and powerful functions for + manipulating arrays. +\example + Consider the following: +#v+ + variable X = [0.0:10.0:0.01]; + variable A = sin (X); + variable I = where (A < 0.0); + A[I] = cos (X) [I]; +#v- + Here the variable \var{X} has been assigned an array of doubles + whose elements range from \exmp{0.0} through \exmp{10.0} in + increments of \var{0.01}. The second statement assigns \var{A} to + an array whose elements are the \var{sin} of the elements of \var{X}. + The third statement uses the where function to get the indices of + the elements of \var{A} that are less than \var{0.0}. Finally, the + last statement substitutes into \var{A} the \var{cos} of the + elements of \var{X} at the positions of \var{A} where the + corresponding \var{sin} is less than \var{0}. The end result is + that the elements of \var{A} are a mixture of sines and cosines. +\seealso{array_info, sin, cos} +\done + diff --git a/libslang/doc/tm/rtl/assoc.tm b/libslang/doc/tm/rtl/assoc.tm new file mode 100644 index 0000000..e5f0dc6 --- /dev/null +++ b/libslang/doc/tm/rtl/assoc.tm @@ -0,0 +1,76 @@ +\function{assoc_delete_key} +\synopsis{Delete a key from an Associative Array} +\usage{assoc_delete_key (Assoc_Type a, String_Type k)} +\description + The \var{assoc_delete_key} function deletes a key given by \var{k} + from the associative array \var{a}. If the specified key does not + exist in \var{a}, then this function has no effect. +\seealso{assoc_key_exists, assoc_get_keys} +\done + +\function{assoc_get_keys} +\synopsis{Return all the key names of an Associative Array} +\usage{String_Type[] assoc_get_keys (Assoc_Type a)} +\description + This function returns all the key names of an associative array + \var{a} as an ordinary one dimensional array of strings. If the + associative array contains no keys, an empty array will be returned. +\example + The following function computes the number of keys in an associative + array: +#v+ + define get_num_elements (a) + { + return length (assoc_get_keys (a)); + } +#v- +\seealso{assoc_get_values, assoc_key_exists, assoc_delete_key, length} +\done + +\function{assoc_get_values} +\synopsis{Return all the values of an Associative Array} +\usage{Array_Type assoc_get_keys (Assoc_Type a)} +\description + This function returns all the values in the associative array + \var{a} as an array of proper type. If the associative array + contains no keys, an empty array will be returned. +\example + Suppose that \var{a} is an associative array of type + \var{Integer_Type}, i.e., it was created via +#v+ + variable a = Assoc_Type[Integer_Type]; +#v- + The the following may be used to print the values of the array in + ascending order: +#v+ + static define int_sort_fun (x, y) + { + return sign (x - y); + } + define sort_and_print_values (a) + { + variable i, v; + + v = assoc_get_values (a); + i = array_sort (v, &int_sort_fun); + v = v[i]; + foreach (v) + { + variable vi = (); + () = fprintf (stdout, "%d\n", vi); + } + } +#v- +\seealso{assoc_get_values, assoc_key_exists, assoc_delete_key, array_sort} +\done + +\function{assoc_key_exists} +\synopsis{Check to see whether a key exists in an Associative Array} +\usage{Integer_Type assoc_key_exists (Assoc_Type a, String_Type k)} +\description + The \var{assoc_key_exists} function may be used to determine whether + or not a specified key \var{k} exists in an associative array \var{a}. + It returns \1 if the key exists, or \0 if it does not. +\seealso{assoc_get_keys, assoc_get_values, assoc_delete_key} +\done + diff --git a/libslang/doc/tm/rtl/bstr.tm b/libslang/doc/tm/rtl/bstr.tm new file mode 100644 index 0000000..ffe2825 --- /dev/null +++ b/libslang/doc/tm/rtl/bstr.tm @@ -0,0 +1,151 @@ +\function{array_to_bstring} +\synopsis{Convert an array to a binary string} +\usage{BString_Type array_to_bstring (Array_Type a)} +\description + The \var{array_to_bstring} function returns the elements of an + array \var{a} as a binary string. +\seealso{bstring_to_array, init_char_array} +\done + +\function{bstring_to_array} +\synopsis{Convert a binary string to an array of characters} +\usage{UChar_Type[] bstring_to_array (BString_Type b)} +\description + The \var{bstring_to_array} function returns an array of unsigned + characters whose elements correspond to the characters in the + binary string. +\seealso{array_to_bstring, init_char_array} +\done + +\function{bstrlen} +\synopsis{Get the length of a binary string} +\usage{UInt_Type bstrlen (BString_Type s)} +\description + The \var{bstrlen} function may be used to obtain the length of a + binary string. A binary string differs from an ordinary string (a C + string) in that a binary string may include null chracters. +\example +#v+ + variable s = "hello\0"; + len = bstrlen (s); % ==> len = 6 + len = strlen (s); % ==> len = 5 +#v- +\seealso{strlen, length} +\done + +\function{pack} +\synopsis{Pack objects into a binary string} +\usage{BString_Type pack (String_Type fmt, ...)} +\description + The \var{pack} function combines zero or more the objects (represented + by the ellipses above) into a binary string acording to the format + string \var{fmt}. + + The format string consists of one or more data-type specification + characters, and each may be followed by an optional decimal length + specifier. Specifically, the data-types are specified according to + the following table: +#v+ + c char + C unsigned char + h short + H unsigned short + i int + I unsigned int + l long + L unsigned long + j 16 bit int + J 16 unsigned int + k 32 bit int + K 32 bit unsigned int + f float + d double + F 32 bit float + D 64 bit float + s character string, null padded + S character string, space padded + x a null pad character +#v- + A decimal length specifier may follow the data-type specifier. With + the exception of the \var{s} and \var{S} specifiers, the length + specifier indicates how many objects of that data type are to be + packed or unpacked from the string. When used with the \var{s} or + \var{S} specifiers, it indicates the field width to be used. If the + length specifier is not present, the length defaults to one. + + With the exception of \var{c}, \var{C}, \var{s}, \var{S}, and + \var{x}, each of these may be prefixed by a character that indicates + the byte-order of the object: +#v+ + > big-endian order (network order) + < little-endian order + = native byte-order +#v- + The default is to use native byte order. + + When unpacking via the \var{unpack} function, if the length + specifier is greater than one, then an array of that length will be + returned. In addition, trailing whitespace and null character are + stripped when unpacking an object given by the \var{S} specifier. +\example +#v+ + a = pack ("cc", 'A', 'B'); % ==> a = "AB"; + a = pack ("c2", 'A', 'B'); % ==> a = "AB"; + a = pack ("xxcxxc", 'A', 'B'); % ==> a = "\0\0A\0\0B"; + a = pack ("h2", 'A', 'B'); % ==> a = "\0A\0B" or "\0B\0A" + a = pack (">h2", 'A', 'B'); % ==> a = "\0\xA\0\xB" + a = pack ("<h2", 'A', 'B'); % ==> a = "\0B\0A" + a = pack ("s4", "AB", "CD"); % ==> a = "AB\0\0" + a = pack ("s4s2", "AB", "CD"); % ==> a = "AB\0\0CD" + a = pack ("S4", "AB", "CD"); % ==> a = "AB " + a = pack ("S4S2", "AB", "CD"); % ==> a = "AB CD" +#v- +\seealso{unpack, sizeof_pack, pad_pack_format, sprintf} +\done + +\function{pad_pack_format} +\synopsis{Add padding to a pack format} +\usage{BString_Type pad_pack_format (String_Type fmt)} +\description + The \var{pad_pack_format} function may be used to add the + appropriate padding to the format \var{fmt} such that the data types + specified by the format will be properly aligned for the system. + This is especially important when reading or writing files that + assume the native alignment. + + See the S-Lang User's Guide for more information about the use of + this function. +\seealso{pack, unpack, sizeof_pack} +\done + +\function{sizeof_pack} +\synopsis{Compute the size implied by a pack format string} +\usage{UInt_Type sizeof_pack (String_Type fmt)} +\description + The \var{sizeof_pack} function returns the size of the binary string + represented by the format string \var{fmt}. This information may be + needed when reading a structure from a file. +\notes +\seealso{pack, unpack, pad_pack_format} +\done + +\function{unpack} +\synopsis{Unpack Objects from a Binary String} +\usage{(...) = unpack (String_Type fmt, BString_Type s)} +\description + The \var{unpack} function unpacks objects from a binary string + \var{s} according to the format \var{fmt} and returns the objects to + the stack in the order in which they were unpacked. See the + documentation of the \var{pack} function for details about the + format string. +\example +#v+ + (x,y) = unpack ("cc", "AB"); % ==> x = 'A', y = 'B' + x = unpack ("c2", "AB"); % ==> x = ['A', 'B'] + x = unpack ("x<H", "\0\xAB\xCD"); % ==> x = 0xCDABuh + x = unpack ("xxs4", "a b c\0d e f"); % ==> x = "b c\0" + x = unpack ("xxS4", "a b c\0d e f"); % ==> x = "b c" +#v- +\seealso{pack, sizeof_pack, pad_pack_format} +\done + diff --git a/libslang/doc/tm/rtl/debug.tm b/libslang/doc/tm/rtl/debug.tm new file mode 100644 index 0000000..682c4b8 --- /dev/null +++ b/libslang/doc/tm/rtl/debug.tm @@ -0,0 +1,98 @@ +\function{_clear_error} +\synopsis{Clear an error condition} +\usage{_clear_error ()} +\description + This function may be used in error-blocks to clear the error that + triggered execution of the error block. Execution resumes following + the statement, in the scope of the error-block, that triggered the + error. +\example + Consider the following wrapper around the \var{putenv} function: +#v+ + define try_putenv (name, value) + { + variable status; + ERROR_BLOCK + { + _clear_error (); + status = -1; + } + status = 0; + putenv (sprintf ("%s=%s", name, value); + return status; + } +#v- + If \var{putenv} fails, it generates an error condition, which the + \var{try_putenv} function catches and clears. Thus \var{try_putenv} + is a function that returns \exmp{-1} upon failure and \var{0} upon + success. +\seealso{_trace_function, _slangtrace, _traceback} +\done + +\variable{_debug_info} +\synopsis{Configure debugging information} +\usage{Integer_Type _debug_info} +\description + The \var{_debug_info} variable controls whether or not extra code + should be generated for additional debugging and traceback + information. Currently, if \var{_debug_info} is zero, no extra code + will be generated; otherwise extra code will be inserted into the + compiled bytecode for additional debugging data. + + The value of this variable is local to each compilation unit and + setting its value in one unit has no effect upon its value in other + units. +\example +#v+ + _debug_info = 1; % Enable debugging information +#v- +\notes + Setting this variable to a non-zero value may slow down the + interpreter somewhat. +\seealso{_traceback, _slangtrace} +\done + +\variable{_slangtrace} +\synopsis{Turn function tracing on or off.} +\usage{Integer_Type _slangtrace} +\description + The \var{_slangtrace} variable is a debugging aid that when set to a + non-zero value enables tracing when function declared by + \var{_trace_function} is entered. If the value is greater than + zero, both intrinsic and user defined functions will get traced. + However, if set to a value less than zero, intrinsic functions will + not get traced. +\seealso{_trace_function, _traceback, _print_stack} +\done + +\function{_trace_function} +\synopsis{Set the function to trace} +\usage{_trace_function (String_Type f)} +\description + \var{_trace_function} declares that the \slang function with name + \var{f} is to be traced when it is called. Calling + \var{_trace_function} does not in itself turn tracing on. Tracing + is turned on only when the variable \var{_slangtrace} is non-zero. +\seealso{_slangtrace, _traceback} +\done + +\variable{_traceback} +\synopsis{Generate a traceback upon error} +\usage{Integer_Type _traceback} +\description + \var{_traceback} is an intrinsic integer variable whose value + controls whether or not a traceback of the call stack is to be + generated upon error. If \var{_traceback} is greater than zero, a + full traceback will be generated, which includes the values of local + variables. If the value is less than zero, a traceback will be + generated without local variable information, and if + \var{_traceback} is zero the traceback will not be generated. + + Local variables are represented in the form \var{$n} where \var{n} is an + integer numbered from zero. More explicitly, \var{$0} represents the + first local variable, \var{$1} represents the second, and so on. + Please note that function parameters are local variables and that the + first parameter corresponds to \var{$0}. +\seealso{_slangtrace, error} +\done + diff --git a/libslang/doc/tm/rtl/dir.tm b/libslang/doc/tm/rtl/dir.tm new file mode 100644 index 0000000..a25fc86 --- /dev/null +++ b/libslang/doc/tm/rtl/dir.tm @@ -0,0 +1,223 @@ +\function{chdir} +\synopsis{Change the current working directory.} +\usage{Integer_Type chdir (String_Type dir)} +\description + The \var{chdir} function may be used to changed the current working + directory to the directory specified by \var{dir}. Upon success it + returns zero; however, upon failure it returns \exmp{-1} and sets + \var{errno} accordingly. +\seealso{mkdir, stat_file} +\done + +\function{chmod} +\synopsis{Change the mode of a file} +\usage{Integer_Type chmod (String_Type file, Integer_Type mode)} +\description + The \var{chmod} function changes the permissions of \var{file} to those + specified by \var{mode}. It returns \exmp{0} upon success, or + \exmp{-1} upon failure setting \var{errno} accordingly. + + See the system specific documentation for the C library + function \var{chmod} for a discussion of the \var{mode} parameter. +\seealso{chown, stat_file} +\done + +\function{chown} +\synopsis{Change the owner of a file} +\usage{Integer_Type chown (String_Type file, Integer_Type uid, Integer_Type gid)} +\description + The \var{chown} function is used to change the user-id and group-id of + \var{file} to \var{uid} and \var{gid}, respectively. It returns + \var{zero} upon success and \exmp{-1} upon failure, with \var{errno} + set accordingly. +\notes + On most systems, only the super user can change the ownership of a + file. + + Some systems do not support this function. +\seealso{chmod, stat_file} +\done + +\function{getcwd} +\synopsis{Get the current working directory} +\usage{String_Type getcwd ()} +\description + The \var{getcwd} function returns the absolute pathname of the + current working directory. If an error occurs or it cannot + determine the working directory, it returns \var{NULL} and sets + \var{errno} accordingly. +\notes + Under Unix, OS/2, and MSDOS, the pathname returned by this function + includes the trailing slash character. Some versions also include + the drive specifier. +\seealso{mkdir, chdir, errno} +\done + +\function{listdir} +\synopsis{Get a list of the files in a directory} +\usage{String_Type[] listdir (String_Type dir)} +\description + The \var{listdir} function returns the directory listing of all the + files in the specified directory \var{dir} as an array of strings. + It does not return the special files \exmp{".."} and \exmp{"."} as + part of the list. +\seealso{stat_file, stat_is, length} +\done + +\function{lstat_file} +\synopsis{Get information about a symbolic link} +\usage{Struct_Type lstat_file (String_Type file)} +\description + The \var{lstat_file} function behaves identically to \var{stat_file} + but if \var{file} is a symbolic link, \var{lstat_file} returns + information about the link itself, and not the file that it + references. + + See the documentation for \var{stat_file} for more information. +\notes + On systems that do not support symbolic links, there is no + difference between this function and the \var{stat_file} function. +\seealso{stat_file, readlink} +\done + +\function{mkdir} +\synopsis{Create a new directory} +\usage{Integer_Type mkdir (String_Type dir, Integer_Type mode)} +\description + The \var{mkdir} function creates a directory whose name is specified + by the \var{dir} parameter with permissions specified by \var{mode}. + Upon success \var{mkdir} returns zero, or it returns \exmp{-1} and + sets \var{errno} accordingly. In particular, if the directory + already exists, the function will fail and set errno to + \var{EEXIST}. +\example +#v+ + define my_mkdir (dir) + { + if (0 == mkdir (dir, 0777)) return; + if (errno == EEXIST) return; + verror ("mkdir %s failed: %s", dir, errno_string (errno)); + } +#v- +\notes + The \var{mode} parameter may not be meaningful on all systems. On + systems where it is meaningful, the actual permissions on the newly + created directory are modified by the process's umask. +\seealso{rmdir, getcwd, chdir, fopen, errno} +\done + +\function{readlink} +\synopsis{String_Type readlink (String_Type path)} +\usage{Get the value of a symbolic link} +\description + The \var{readlink} function returns the value of a symbolic link and + returns it as a string. Upon failure, \NULL is returned and + \var{errno} set accordingly. +\notes + Not all systems support this function. +\seealso{lstat_file, stat_file, stat_is} +\done + +\function{remove} +\synopsis{Delete a file} +\usage{Integer_Type remove (String_Type file)} +\description + The \var{remove} function deletes a file. It returns \0 upon + success, or \-1 upon error and sets \var{errno} accordingly. +\seealso{rename, rmdir} +\done + +\function{rename} +\synopsis{Rename a file} +\usage{Integer_Type rename (String_Type old, String_Type new)} +\description + The \var{rename} function renames a file from \var{old} to \var{new} + moving it between directories if necessary. This function may fail + if the directories do not refer to the same file system. It returns + \0 upon success, or \-1 upon error and sets \var{errno} accordingly. +\seealso{remove, errno} +\done + +\function{rmdir} +\synopsis{Remove a directory} +\usage{Integer_Type rmdir (String_Type dir)} +\description + The \var{rmdir} function deletes a specified directory. It returns + \0 upon success or \-1 upon error and sets \var{errno} accordingly. +\notes + The directory must be empty before it can be removed. +\seealso{rename, remove, mkdir} +\done + +\function{stat_file} +\synopsis{Get information about a file} +\usage{Struct_Type stat_file (String_Type file)} +\description + The \var{stat_file} function returns information about \var{file} + through the use of the system \var{stat} call. If the stat call + fails, the function returns \var{NULL} and sets errno accordingly. + If it is successful, it returns a stat structure with the following + integer fields: +#v+ + st_dev + st_ino + st_mode + st_nlink + st_uid + st_gid + st_rdev + st_size + st_atime + st_mtime + st_ctime +#v- + See the man page for \var{stat} for a discussion of these fields. +\example + The following example shows how the \var{stat_file} function may be + used to get the size of a file: +#v+ + define file_size (file) + { + variable st; + st = stat_file(file); + if (st == NULL) verror ("Unable to stat %s", file); + return st.st_size; + } +#v- +\seealso{lstat_file, stat_is} +\done + +\function{stat_is} +\synopsis{Parse the \var{st_mode} field of a stat structure} +\usage{Char_Type stat_is (String_Type type, Integer_Type st_mode)} +\description + The \var{stat_is} function returns a signed character value about + the type of file specified by \var{st_mode}. Specifically, + \var{type} must be one of the strings: +#v+ + "sock" (socket) + "fifo" (fifo) + "blk" (block device) + "chr" (character device) + "reg" (regular file) + "lnk" (link) + "dir" (dir) +#v- + It returns a non-zero value if \var{st_mode} corresponds to + \var{type}. +\example + The following example illustrates how to use the \var{stat_is} + function to determine whether or not a file is a directory: +#v+ + define is_directory (file) + { + variable st; + + st = stat_file (file); + if (st == NULL) return 0; + return stat_is ("dir", st.st_mode); + } +#v- +\seealso{stat_file, lstat_file} +\done + diff --git a/libslang/doc/tm/rtl/eval.tm b/libslang/doc/tm/rtl/eval.tm new file mode 100644 index 0000000..3c1e66c --- /dev/null +++ b/libslang/doc/tm/rtl/eval.tm @@ -0,0 +1,119 @@ +\function{autoload} +\synopsis{Load a function from a file} +\usage{autoload (String_Type funct, String_Type file)} +\description + The \var{autoload} function is used to declare \var{funct} to the + interpreter and indicate that it should be loaded from \var{file} when + it is actually used. +\example + Suppose \var{bessel_j0} is a function defined in the file + \var{bessel.sl}. Then the statement +#v+ + autoload ("bessel_j0", "bessel.sl"); +#v- + will cause \var{bessel.sl} to be loaded prior to the execution of + \var{bessel_j0} +\seealso{evalfile} +\done + +\function{byte_compile_file} +\synopsis{Compile a file to byte-code for faster loading.} +\usage{byte_compile_file (String_Type file, Integer_Type method)} +\description + The \var{byte_compile_file} function byte-compiles \var{file} + producing a new file with the same name except a \var{'c'} is added + to the output file name. For example, \var{file} is + \exmp{"site.sl"}, then the function produces a new file named + \exmp{site.slc}. +\notes + The \var{method} parameter is not used in the current + implementation. Its use is reserved for the future. For now, set + it to \exmp{0}. +\seealso{evalfile} +\done + +\function{eval} +\synopsis{Interpret a string as \slang code} +\usage{eval (String_Type expression, [,String_Type namespace])} +\description + The \var{eval} function parses a string as S-Lang code and executes the + result. If called with the optional namespace argument, then the + string will be evaluated in the specified namespace. + + This is a useful function in many contexts such as dynamically + generating function definitions where there is no way to generate + them otherwise. +\example +#v+ + if (0 == is_defined ("my_function")) + eval ("define my_function () { message (\"my_function\"); }"); +#v- +\seealso{is_defined, autoload, evalfile} +\done + +\function{evalfile} +\synopsis{Interpret a file containing \slang code.} +\usage{Integer_Type evalfile (String_Type file, [,String_Type namespace])} +\description + The \var{evalfile} function loads \var{file} into the interpreter + and executes it. If called with the optional namespace argument, + the file will be loaded into the specified namespace, which will be + created if necessary. If no errors were encountered, \exmp{1} will + be returned; otherwise, a \slang error will be generated and the + function will return zero. +\example +#v+ + define load_file (file) + { + ERROR_BLOCK { _clear_error (); } + () = evalfile (file); + } +#v- +\notes + For historical reasons, the return value of this function is not + really useful. + + The file is searched along an application-defined load-path. The + \ifun{get_slang_load_path} and \ifun{set_slang_load_path} functions + may be used to set and query the path. +\seealso{eval, autoload, set_slang_load_path, get_slang_load_path} +\done + +\function{get_slang_load_path} +\synopsis{Get the value of the interpreter's load-path} +\usage{String_Type get_slang_load_path ()} +\description + This function retrieves the value of the delimiter-separated search + path used for loading files. +\notes + Some applications may not support the built-in load-path searching + facility provided by the underlying library. +\seealso{} +\done + +\function{set_slang_load_path} +\synopsis{Set the value of the interpreter's load-path} +\usage{set_slang_load_path (String_Type path)} +\description + This function may be used to set the value of the + delimiter-separated search path used by the \ifun{evalfile} and + \ifun{autoload} functions for locating files. +\example +#v+ + public define prepend_to_slang_load_path (p) + { + variable s = stat_file (p); + if (s == NULL) return; + if (0 == stat_is ("dir", s.st_mode)) + return; + + variable d = path_get_delimiter (); + set_slang_load_path (strcat (p, d, get_slang_load_path ())); + } +#v- +\notes + Some applications may not support the built-in load-path searching + facility provided by the underlying library. +\seealso{get_slang_load_path, path_get_delimiter, evalfile, autoload} +\done + diff --git a/libslang/doc/tm/rtl/import.tm b/libslang/doc/tm/rtl/import.tm new file mode 100644 index 0000000..54dd5b6 --- /dev/null +++ b/libslang/doc/tm/rtl/import.tm @@ -0,0 +1,51 @@ +\function{get_import_module_path} +\synopsis{Get the search path for dynamically loadable objects} +\usage{String_Type get_import_module_path ()} +\description + The \var{get_import_module_path} may be used to get the search path + for dynamically shared objects. Such objects may be made accessable + to the application via the \var{import} function. +\seealso{import, set_import_module_path} +\done + +\function{import} +\synopsis{Dynamically link to a specified module} +\usage{import (String_Type module [, String_Type namespace])} +\description + The \var{import} function causes the run-time linker to dynamically + link to the shared object specified by the \var{module} parameter. + It seaches for the shared object as follows: First a search is + performed along all module paths specified by the application. Then + a search is made along the paths defined via the + \var{set_import_module_path} function. If not found, a search is + performed along the paths given by the \var{SLANG_MODULE_PATH} + environment variable. Finally, a system dependent search is + performed (e.g., using the \var{LD_LIBRARY_PATH} environment + variable). + + The optional second parameter may be used to specify a namespace + for the intrinsic functions and variables of the module. If this + parameter is not present, the intrinsic objects will be placed into + the global namespace. + + This function signals an error if the specified module is not found. +\notes + The \var{import} function is not available on all systems. +\seealso{set_import_module_path, use_namespace, current_namespace, getenv, evalfile} +\done + +\function{set_import_module_path} +\synopsis{Set the search path for dynamically loadable objects} +\usage{set_import_module_path (String_Type path_list)} +\description + The \var{set_import_module_path} may be used to set the search path + for dynamically shared objects. Such objects may be made accessable + to the application via the \var{import} function. + + The actual syntax for the specification of the set of paths will + vary according to the operating system. Under Unix, a colon + character is used to separate paths in \var{path_list}. For win32 + systems a semi-colon is used. +\seealso{import, get_import_module_path} +\done + diff --git a/libslang/doc/tm/rtl/info.tm b/libslang/doc/tm/rtl/info.tm new file mode 100644 index 0000000..b476689 --- /dev/null +++ b/libslang/doc/tm/rtl/info.tm @@ -0,0 +1,202 @@ +\variable{_NARGS} +\synopsis{The number of parameters passed to a function} +\usage{Integer_Type _NARGS} + The value of the \var{_NARGS} variable represents the number of + arguments passed to the function. This variable is local to each + function. +\example + This example uses the \var{_NARGS} variable to print the list of + values passed to the function: +#v+ + define print_values () + { + variable arg; + + if (_NARGS == 0) + { + message ("Nothing to print"); + return; + } + foreach (__pop_args (_NARGS)) + { + arg = (); + vmessage ("Argument value is: %S", arg.value); + } + } +#v- +\seealso{__pop_args, __push_args, typeof} +\done + +\function{__get_defined_symbols} +\synopsis{Get the symbols defined by the preprocessor} +\usage{Integer_Type __get_defined_symbols ()} +\description + The \var{__get_defined_symbols} functions is used to get the list of + all the symbols defined by the \slang preprocessor. It pushes each + of the symbols on the stack followed by the number of items pushed. +\seealso{is_defined, _apropos, _get_namespaces} +\done + +\function{__is_initialized} +\synopsis{Determine whether or not a variable has a value} +\usage{Integer_Type __is_initialized (Ref_Type r)} +\description + This function returns non-zero of the object referenced by \var{r} + is initialized, i.e., whether it has a value. It returns \0 if the + referenced object has not been initialized. +\example + For example, the function: +#v+ + define zero () + { + variable f; + return __is_initialized (&f); + } +#v- + will always return zero, but +#v+ + define one () + { + variable f = 0; + return __is_initialized (&f); + } +#v- + will return one. +\notes + It is easy to see why a reference to the variable must be passed to + \var{__is_initialized} and not the variable itself; otherwise, the + value of the variable would be passed and the variable may have no + value if it was not initialized. +\seealso{__get_reference, __uninitialize, is_defined, typeof, eval} +\done + +\function{_apropos} +\synopsis{Generate a list of functions and variables} +\usage{Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags)} +\description + The \var{_apropos} function may be used to get a list of all defined + objects in the namespace \var{ns} whose name matches the regular + expression \var{s} and whose type matches those specified by + \var{flags}. It returns an array of strings representing the + matches. + + The second parameter \var{flags} is a bit mapped value whose bits + are defined according to the following table +#v+ + 1 Intrinsic Function + 2 User-defined Function + 4 Intrinsic Variable + 8 User-defined Variable +#v- +\example +#v+ + define apropos (s) + { + variable n, name, a; + a = _apropos ("Global", s, 0xF); + + vmessage ("Found %d matches:", length (a)); + foreach (a) + { + name = (); + message (name); + } + } +#v- + prints a list of all matches. +\notes + If the namespace specifier \var{ns} is the empty string \exmp{""}, + then the namespace will default to the static namespace of the + current compilation unit. +\seealso{is_defined, sprintf, _get_namespaces} +\done + +\function{_function_name} +\synopsis{Returns the name of the currently executing function} +\usage{String_Type _function_name ()} +\description + This function returns the name of the currently executing function. + If called from top-level, it returns the empty string. +\seealso{_trace_function, is_defined} +\done + +\function{_get_namespaces} +\synopsis{Returns a list of namespace names} +\usage{String_Type[] _get_namespaces ()} +\description + This function returns a string array containing the names of the + currently defined namespaces. +\seealso{_apropos, use_namespace, implements, __get_defined_symbols} +\done + +\variable{_slang_doc_dir} +\synopsis{Installed documentation directory} +\usage{String_Type _slang_doc_dir;} +\description + The \var{_slang_doc_dir} variable is a read-only whose value + specifies the installation location of the \slang documentation. +\seealso{get_doc_string_from_file} +\done + +\variable{_slang_version} +\synopsis{The S-Lang library version number} +\usage{Integer_Type _slang_version} +\description + The \var{_slang_version} variable is read-only and whose + value represents the number of the \slang library. +\seealso{_slang_version_string} +\done + +\variable{_slang_version_string} +\synopsis{The S-Lang library version number as a string} +\usage{String_Type _slang_version_string} +\description + The \var{_slang_version_string} variable is read-only and whose + value represents the version number of the \slang library. +\seealso{_slang_version} +\done + +\function{get_doc_string_from_file} +\synopsis{Read documentation from a file} +\usage{String_Type get_doc_string_from_file (String_Type f, String_Type t)} +\description + \var{get_doc_string_from_file} opens the documentation file \var{f} + and searches it for topic \var{t}. It returns the documentation for + \var{t} upon success, otherwise it returns \var{NULL} upon error. + It will fail if \var{f} could not be opened or does not contain + documentation for the topic. +\seealso{stat_file} +\seealso{_slang_doc_dir} +\done + +\function{is_defined} +\synopsis{Indicate whether a variable or function defined.} +\usage{Integer_Type is_defined (String_Type obj)} +\description + This function is used to determine whether or not a function or + variable whose name is \var{obj} has been defined. If \var{obj} is not + defined, the function returns 0. Otherwise, it returns a non-zero + value that defpends on the type of object \var{obj} represents. + Specifically, it returns one of the following values: +#v+ + +1 if an intrinsic function + +2 if user defined function + -1 if intrinsic variable + -2 if user defined variable + 0 if undefined +#v- +\example + For example, consider the function: +#v+ + define runhooks (hook) + { + if (2 == is_defined(hook)) eval(hook); + } +#v- + This function could be called from another \slang function to + allow customization of that function, e.g., if the function + represents a mode, the hook could be called to setup keybindings + for the mode. +\seealso{typeof, eval, autoload, __get_reference, __is_initialized} +\done + diff --git a/libslang/doc/tm/rtl/math.tm b/libslang/doc/tm/rtl/math.tm new file mode 100644 index 0000000..104589f --- /dev/null +++ b/libslang/doc/tm/rtl/math.tm @@ -0,0 +1,291 @@ +\function{Conj} +\synopsis{Compute the complex conjugate of a number} +\usage{z1 = Conj (z)} +\description + The \var{Conj} function returns the complex conjugate of a number. + If its argument is an array, the \var{Conj} function will be applied to each + element and the result returned as an array. +\seealso{Real, Imag, abs} +\done + +\function{Imag} +\synopsis{Compute the imaginary part of a number} +\usage{i = Imag (z)} +\description + The \var{Imag} function returns the imaginary part of a number. + If its argument is an array, the \var{Imag} function will be applied to each + element and the result returned as an array. +\seealso{Real, Conj, abs} +\done + +\function{Real} +\synopsis{Compute the real part of a number} +\usage{r = Real (z)} +\description + The \var{Real} function returns the real part of a number. If its + argument is an array, the \var{Real} function will be applied to + each element and the result returned as an array. +\seealso{Imag, Conj, abs} +\done + +\function{abs} +\synopsis{Compute the absolute value of a number} +\usage{y = abs(x)} +\description + The \var{abs} function returns the absolute value of an arithmetic + type. If its argument is a complex number (\var{Complex_Type}), + then it returns the modulus. If the argument is an array, a new + array will be created whose elements are obtained from the original + array by using the \var{abs} function. +\seealso{sign, sqr} +\done + +\function{acos} +\synopsis{Compute the arc-cosine of an number} +\usage{y = acos (x)} +\description + The \var{acos} function computes the arc-cosine of a number and + returns the result as an array. If its argument is an array, the + \var{acos} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{acosh} +\synopsis{Compute the inverse cosh of an number} +\usage{y = acosh (x)} +\description + The \var{acosh} function computes the inverse cosh of a number and + returns the result as an array. If its argument is an array, the + \var{acosh} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{asin} +\synopsis{Compute the arc-sine of an number} +\usage{y = asin (x)} +\description + The \var{asin} function computes the arc-sine of a number and + returns the result as an array. If its argument is an array, the + \var{asin} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{asinh} +\synopsis{Compute the inverse-sinh of an number} +\usage{y = asinh (x)} +\description + The \var{asinh} function computes the inverse-sinh of a number and + returns the result as an array. If its argument is an array, the + \var{asinh} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{atan} +\synopsis{Compute the arc-tangent of an number} +\usage{y = atan (x)} +\description + The \var{atan} function computes the arc-tangent of a number and + returns the result as an array. If its argument is an array, the + \var{atan} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{atanh} +\synopsis{Compute the inverse-tanh of an number} +\usage{y = atanh (x)} +\description + The \var{atanh} function computes the inverse-tanh of a number and + returns the result as an array. If its argument is an array, the + \var{atanh} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{cos} +\synopsis{Compute the cosine of an number} +\usage{y = cos (x)} +\description + The \var{cos} function computes the cosine of a number and + returns the result as an array. If its argument is an array, the + \var{cos} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{cosh} +\synopsis{Compute the hyperbolic cosine of an number} +\usage{y = cosh (x)} +\description + The \var{cosh} function computes the hyperbolic cosine of a number and + returns the result as an array. If its argument is an array, the + \var{cosh} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{exp} +\synopsis{Compute the exponential of an number} +\usage{y = exp (x)} +\description + The \var{exp} function computes the exponential of a number and + returns the result as an array. If its argument is an array, the + \var{exp} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{log} +\synopsis{Compute the logarithm of an number} +\usage{y = log (x)} +\description + The \var{log} function computes the logarithm of a number and + returns the result as an array. If its argument is an array, the + \var{log} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{log10} +\synopsis{Compute the base-10 logarithm of an number} +\usage{y = log10 (x)} +\description + The \var{log10} function computes the base-10 logarithm of a number and + returns the result as an array. If its argument is an array, the + \var{log10} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{mul2} +\synopsis{Multiply a number by 2} +\usage{y = mul2(x)} +\description + The \var{mul2} function multiplies an arithmetic type by two and + returns the result. If its argument is an array, a new array will + be created whose elements are obtained from the original array by + using the \var{mul2} function. +\seealso{sqr, abs} +\done + +\function{polynom} +\synopsis{Evaluate a polynomial} +\usage{Double_Type polynom(Double_Type a, b, ...c, Integer_Type n, Double_Type x)} +\description + The \var{polynom} function returns the value of the polynomial expression: +#v+ + ax^n + bx^(n - 1) + ... c +#v- +\notes + The \var{polynom} function should be extended to work with complex + and array data types. The current implementation is limited to + \var{Double_Type} quantities. +\seealso{exp} +\done + +\function{set_float_format} +\synopsis{Set the format for printing floating point values.} +\usage{set_float_format (String_Type fmt)} +\description + The \var{set_float_format} function is used to set the floating + point format to be used when floating point numbers are printed. + The routines that use this are the traceback routines and the + \var{string} function. The default value is \exmp{"%f"} +\example +#v+ + s = string (PI); % --> s = "3.14159" + set_float_format ("%16.10f"); + s = string (PI); % --> s = "3.1415926536" + set_float_format ("%10.6e"); + s = string (PI); % --> s = "3.141593e+00" +#v- +\seealso{string, sprintf, double} +\done + +\function{sign} +\synopsis{Compute the sign of a number} +\usage{y = sign(x)} +\description + The \var{sign} function returns the sign of an arithmetic type. If + its argument is a complex number (\var{Complex_Type}), it returns + the sign of the imaginary part of the number. If the argument is an + array, a new array will be created whose elements are obtained from + the original array by using the \var{sign} function. + + When applied to a real number or an integer, the \var{sign} function + returns \-1, \0, or \exmp{+1} according to whether the number is + less than zero, equal to zero, or greater than zero, respectively. +\seealso{abs} +\done + +\function{sin} +\synopsis{Compute the sine of an number} +\usage{y = sin (x)} +\description + The \var{sin} function computes the sine of a number and + returns the result as an array. If its argument is an array, the + \var{sin} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{sinh} +\synopsis{Compute the hyperbolic sine of an number} +\usage{y = sinh (x)} +\description + The \var{sinh} function computes the hyperbolic sine of a number and + returns the result as an array. If its argument is an array, the + \var{sinh} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{sqr} +\synopsis{Compute the square of a number} +\usage{y = sqr(x)} +\description + The \var{sqr} function returns the square of an arithmetic type. If its + argument is a complex number (\var{Complex_Type}), then it returns + the square of the modulus. If the argument is an array, a new array + will be created whose elements are obtained from the original array + by using the \var{sqr} function. +\seealso{abs, mul2} +\done + +\function{sqrt} +\synopsis{Compute the square root of an number} +\usage{y = sqrt (x)} +\description + The \var{sqrt} function computes the square root of a number and + returns the result as an array. If its argument is an array, the + \var{sqrt} function will be applied to each element and the result returned + as an array. +\seealso{sqr, cos, atan, acosh, cosh} +\done + +\function{tan} +\synopsis{Compute the tangent of an number} +\usage{y = tan (x)} +\description + The \var{tan} function computes the tangent of a number and + returns the result as an array. If its argument is an array, the + \var{tan} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + +\function{tanh} +\synopsis{Compute the hyperbolic tangent of an number} +\usage{y = tanh (x)} +\description + The \var{tanh} function computes the hyperbolic tangent of a number and + returns the result as an array. If its argument is an array, the + \var{tanh} function will be applied to each element and the result returned + as an array. +\seealso{cos, atan, acosh, cosh} +\done + diff --git a/libslang/doc/tm/rtl/message.tm b/libslang/doc/tm/rtl/message.tm new file mode 100644 index 0000000..e97f7cf --- /dev/null +++ b/libslang/doc/tm/rtl/message.tm @@ -0,0 +1,111 @@ +\function{error} +\synopsis{Generate an error condition} +\usage{error (String_Type msg} +\description + The \var{error} function generates a \slang error condition causing + the interpreter to start unwinding to top-level. It takes a single + string parameter which is displayed on the stderr output device. + The error condition may be cleared via an \var{ERROR_BLOCK} with the + \var{_clear_error} function. Consult \user-manual for more + information. +\example +#v+ + define add_txt_extension (file) + { + if (typeof (file) != String_Type) + error ("add_extension: parameter must be a string"); + file += ".txt"; + return file; + } +#v- +\seealso{verror, _clear_error, message} +\done + +\function{message} +\synopsis{Print a string onto the message device} +\usage{message (String_Type s} +\description + The \var{message} function will print the string specified by + \var{s} onto the message device. +\example +#v+ + define print_current_time () + { + message (time ()); + } +#v- +\notes + The message device will depend upon the application. For example, + the output message device for the \var{jed} editor correspond to the + line at the bottom of the display window. The default message + device is the standard output device. +\seealso{vmessage, sprintf, error} +\done + +\function{usage} +\synopsis{Generate a usage error} +\usage{usage (String_Type msg)} +\description + The \var{usage} function generates a usage exception and displays + \var{msg} to the message device. +\example + Suppose that some function \var{plot} plots an array of \var{x} and + \var{y} values. The such a function could be written to issue a + usage message if the wrong number of arguments were passed: +#v+ + define plot () + { + variable x, y; + + if (_NARGS != 2) + usage ("plot (x, y)"); + + (x, y) = (); + % Now do the hard part + . + . + } +#v- +\seealso{error, message} +\done + +\function{verror} +\synopsis{Generate an error condition} +\usage{verror (String_Type fmt, ...)} +\description + The \var{verror} function performs the same role as the \var{error} + function. The only difference is that instead of a single string + argument, \var{verror} takes a sprintf style argument list. +\example +#v+ + define open_file (file) + { + variable fp; + + fp = fopen (file, "r"); + if (fp == NULL) verror ("Unable to open %s", file); + return fp; + } +#v- +\notes + In the current implementation, strictly speaking, the \var{verror} + function is not an intrinsic function. Rather it is a predefined + \slang function using a combination of \var{Sprintf} and + \var{error}. +\seealso{error, Sprintf, vmessage} +\done + +\function{vmessage} +\synopsis{Print a formatted string onto the message device} +\usage{vmessage (String_Type fmt, ...)} +\description + The \var{vmessage} function formats a sprintf style argument list + and displays the resulting string onto the message device. +\notes + In the current implementation, strictly speaking, the \var{vmessage} + function is not an intrinsic function. Rather it is a predefined + \slang function using a combination of \var{Sprintf} and + \var{message}. +\seealso{message, Sprintf, verror} +\done + diff --git a/libslang/doc/tm/rtl/misc.tm b/libslang/doc/tm/rtl/misc.tm new file mode 100644 index 0000000..39cd62f --- /dev/null +++ b/libslang/doc/tm/rtl/misc.tm @@ -0,0 +1,201 @@ +\function{__class_id} +\synopsis{Return the class-id of a specified type} +\usage{Int_Type __class_id (DataType_Type type))} +\description + This function returns the internal class-id of a specified data type. +\seealso{typeof, _typeof, __class_type} +\done + +\function{__class_type} +\synopsis{Return the class-type of a specified type} +\usage{Int_Type __class_type (DataType_Type type))} +\description + Internally \slang objects are classified according to four types: + scalar, vector, pointer, and memory managed types. For example, an + integer is implemented as a scalar, a complex number as a vector, + and a string is represented as a pointer. The \var{__class_type} + function returns an integer representing the class-type associated + with the specified data type. Specifically, it returns: +#v+ + 0 memory-managed + 1 scalar + 2 vector + 3 pointer +#v- +\seealso{typeof, _typeof, __class_id} +\done + +\function{__eqs} +\synopsis{Test for equality between two objects} +\usage{Int_Type __eqs (a, b)} +\description + This function tests its two arguments for equalit and returns \1 + if they are equal, and \0 otherwise. To be equal, the data type of + the arguments must match and the values of the objects must + reference the same underlying object. +\example + __eqs (1, 1) ===> 1 + __eqs (1, 1.0) ===> 0 + __eqs ("a", 1) ===> 0 + __eqs ([1,2], [1,2]) ===> 0 +\seealso{typeof, __get_reference} +\notes + This function should be thought of as a test for "sameness". +\done + +\function{__get_reference} +\synopsis{Get a reference to a global object} +\usage{Ref_Type __get_reference (String_Type nm)} +\description + This function returns a reference to a global variable or function + whose name is specified by \var{nm}. If no such object exists, it + returns \var{NULL}, otherwise it returns a reference. +\example + For example, consider the function: +#v+ + define runhooks (hook) + { + variable f; + f = __get_reference (hook); + if (f != NULL) + @f (); + } +#v- + This function could be called from another \slang function to + allow customization of that function, e.g., if the function + represents a mode, the hook could be called to setup keybindings + for the mode. +\seealso{is_defined, typeof, eval, autoload, __is_initialized, __uninitialize} +\done + +\function{__uninitialize} +\synopsis{Uninitialize a variable} +\usage{__uninitialize (Ref_Type x)} +\description + The \var{__uninitialize} function may be used to uninitialize the + variable referenced by the parameter \var{x}. +\example + The following two lines are equivalent: +#v+ + () = __tmp(z); + __uninitialize (&z); +#v- +\seealso{__tmp, __is_initialized} +\done + +\variable{_auto_declare} +\synopsis{Set automatic variable declaration mode} +\usage{Integer_Type _auto_declare} +\description + The \var{_auto_declare} may be used to have all undefined variables + implicitely declared as \var{static}. If set to zero, any variable + must be declared witha \var{variable} declaration before it can be + used. If set to one, then any undeclared variabled will be declared + as a \var{static} global variable. + + The \var{_auto_declare} variable is local to each compilation unit and + setting its value in one unit has no effect upon its value in other + units. The value of this variable has no effect upon the variables + in a function. +\example + The following code will not compile if \var{X} not been + declared: +#v+ + X = 1; +#v- + However, +#v+ + _auto_declare = 1; % declare variables as static. + X = 1; +#v- + is equivalent to +#v+ + static variable X = 1; +#v- +\notes + This variable should be used sparingly and is intended primarily for + interactive applications where one types \slang commands at a prompt. +\done + +\function{current_namespace} +\synopsis{Get the name of the current namespace} +\usage{String_Type current_namespace ()} +\description + The \var{current_namespace} function returns the name of the + current namespace. If the current namespace is anonymous, that is, + has not been given a name via the \var{implements} function, the + empty string \exmp{""} will be returned. +\seealso{implements, use_namespace, import} +\done + +\function{getenv} +\synopsis{Get the value of an environment variable} +\usage{String_Type getenv(String_Type var)} +\description + The \var{getenv} function returns a string that represents the + value of an environment variable \var{var}. It will return + \var{NULL} if there is no environment variable whose name is given + by \var{var}. +\example +#v+ + if (NULL != getenv ("USE_COLOR")) + { + set_color ("normal", "white", "blue"); + set_color ("status", "black", "gray"); + USE_ANSI_COLORS = 1; + } +#v- +\seealso{putenv, strlen, is_defined} +\done + +\function{implements} +\synopsis{Name a private namespace} +\usage{implements (String_Type name);} +\description + The \var{implements} function may be used to name the private + namespace associated with the current compilation unit. Doing so + will enable access to the members of the namespace from outside the + unit. The name of the global namespace is \exmp{Global}. +\example + Suppose that some file \exmp{t.sl} contains: +#v+ + implements ("Ts_Private"); + static define message (x) + { + Global->vmessage ("Ts_Private message: %s", x); + } + message ("hello"); +#v- + will produce \exmp{"Ts_Private message: hello"}. This \var{message} + function may be accessed from outside via: +#v+ + Ts_Private->message ("hi"); +#v- +\notes + Since \var{message} is an intrinsic function, it is global and may + not be redefined in the global namespace. +\seealso{use_namespace, current_namespace, import} +\done + +\function{putenv} +\synopsis{Add or change an environment variable} +\usage{putenv (String_Type s)} +\description + This functions adds string \var{s} to the environment. Typically, + \var{s} should of the form \var{"name=value"}. The function + signals a \slang error upon failure. +\notes + This function is not available on all systems. +\seealso{getenv, sprintf} +\done + +\function{use_namespace} +\synopsis{Change to another namespace} +\usage{use_namespace (String_Type name)} +\description + The \var{use_namespace} function changes the current namespace to + the one specified by the parameter. If the specified namespace + does not exist, an error will be generated. +\seealso{implements, current_namespace, import} +\done + diff --git a/libslang/doc/tm/rtl/ospath.tm b/libslang/doc/tm/rtl/ospath.tm new file mode 100644 index 0000000..5604b8f --- /dev/null +++ b/libslang/doc/tm/rtl/ospath.tm @@ -0,0 +1,77 @@ +\function{path_basename} +\synopsis{Get the basename part of a pathname} +\usage{String_Type path_basename (String_Type path)} +\description + The \var{path_basename} function returns the basename associated + with the \var{path} parameter. The basename is the non-directory + part of the filename, e.g., on unix \exmp{c} is the basename of + \exmp{/a/b/c}. +\seealso{path_dirname, path_extname, path_concat, path_is_absolute} +\done + +\function{path_concat} +\synopsis{Combine elements of a pathname} +\usage{String_Type path_concat (String_Type dir, String_Type basename)} +\description + The \var{path_concat} function combines the arguments \var{dir} and + \var{basename} to produce a pathname. For example, on unix is + \var{dir} is \exmp{x/y} and \var{basename} is \exmp{z}, then the + function will return \exmp{x/y/z}. +\seealso{path_dirname, path_basename, path_extname, path_is_absolute} +\done + +\function{path_dirname} +\synopsis{Get the directory name part of a pathname} +\usage{String_Type path_dirname (String_Type path)} +\description + The \var{path_dirname} function returns the directory name + associated with a specified pathname. +\notes + On systems that include a drive specifier as part of the pathname, + the value returned by this function will include the driver + specifier. +\seealso{path_basename, path_extname, path_concat, path_is_absolute} +\done + +\function{path_extname} +\synopsis{Return the extension part of a pathname} +\usage{String_Type path_extname (String_Type path)} +\description + The \var{path_extname} function returns the extension portion of a + specified pathname. If an extension is present, this function will + also include the dot as part of the extension, i.e., if \var{path} + is \exmp{file.c}, then this function returns \exmp{".c"}. If no + extension is present, the function returns an empty string \exmp{""}. +\notes + Under VMS, the file version number is not returned as part of the + extension. +\seealso{path_sans_extname, path_dirname, path_basename, path_concat, path_is_absolute} +\done + +\function{path_get_delimiter} +\synopsis{Get the value of a search-path delimiter} +\usage{Char_Type path_get_delimiter ()} +\description + This function returns the value of the character used to delimit + fields of a search-path. +\seealso{set_slang_load_path, get_slang_load_path} +\done + +\function{path_is_absolute} +\synopsis{Determine whether or not a pathname is absolute} +\usage{Int_Type path_is_absolute (String_Type path)} +\description + The \var{path_is_absolute} function will return non-zero is + \var{path} refers to an absolute pathname, otherwise it returns zero. +\seealso{path_dirname, path_basename, path_extname, path_concat} +\done + +\function{path_sans_extname} +\synopsis{Strip the extension from a pathname} +\usage{String_Type path_sans_extname (String_Type path)} +\description + The \var{path_sans_extname} function removes the file name extension + (including the dot) from the path and returns the result. +\seealso{path_extname, path_basename, path_dirname, path_concat} +\done + diff --git a/libslang/doc/tm/rtl/posio.tm b/libslang/doc/tm/rtl/posio.tm new file mode 100644 index 0000000..cb7bc40 --- /dev/null +++ b/libslang/doc/tm/rtl/posio.tm @@ -0,0 +1,154 @@ +\function{close} +\synopsis{Close an open file descriptor} +\usage{Int_Type close (FD_Type fd)} +\description + The \var{close} function is used to open file descriptor of type + \var{FD_Type}. Upon success \0 is returned, otherwise the function + returns \-1 and sets \var{errno} accordingly. +\seealso{open, fclose, read, write} +\done + +\function{dup_fd} +\synopsis{Duplicate a file descriptor} +\usage{FD_Type dup_fd (FD_Type fd)} +\description + The \var{dup_fd} function duplicates and file descriptor and returns + its duplicate. If the function fails, \NULL will be returned and + \var{errno} set accordingly. +\notes + This function is essentually a wrapper around the POSIX \var{dup} + function. +\seealso{open, close} +\done + +\function{fileno} +\synopsis{Convert a stdio File_Type object to a FD_Type descriptor} +\usage{FD_Type fileno (File_Type fp)} +\description + The \var{fileno} function returns the \var{FD_Type} descriptor + associated with the \var{File_Type} file pointer. Upon failure, + \NULL is returned. +\seealso{fopen, open, fclose, close, dup_fd} +\done + +\function{isatty} +\synopsis{Determine if an open file descriptor refers to a terminal} +\usage{Int_Type isatty (FD_Type or File_Type fd)} +\description + This function returns \1 if the file descriptor \var{fd} refers to a + terminal; otherwise it returns \0. The object \var{fd} may either + be a \var{File_Type} stdio descriptor or an \var{FD_Type} object. +\seealso{fopen, fclose, fileno} +\done + +\function{lseek} +\synopsis{Reposition a file descriptor's file pointer} +\usage{Long_Type lseek (FD_Type fd, Long_Type ofs, int mode)} + The \var{lseek} function repositions the file pointer associated + with the open file descriptor \var{fp} to offset \var{ofs} + according to the mode parameter. Specifically, \var{mode} must be + one of the values: +#v+ + SEEK_SET Set the offset to ofs + SEEK_CUR Add ofs to the current offset + SEEK_END Add ofs to the current file size +#v- + Upon error, \var{lseek} returns \-1 and sets \var{errno}. If + successful, it returns the new filepointer offset. +\notes + Not all file descriptors are capable of supporting the seek + operation, e.g., a descriptor associated with a pipe. + + By using \var{SEEK_END} with a positive value of the \var{ofs} + parameter, it is possible to position the file pointer beyond the + current size of the file. +\seealso{fseek, ftell, open, close} +\done + +\function{open} +\synopsis{Open a file} +\usage{FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode])} +\description + The \var{open} function attempts to open a file specified by the + \var{filename} parameter according to the \var{flags} parameter, + which must be one of the following values: +#v+ + O_RDONLY (read-only) + O_WRONLY (write-only) + O_RDWR (read/write) +#v- + In addition, \var{flags} may also be bitwise-or'd with any of the + following: +#v+ + O_BINARY (open the file in binary mode) + O_TEXT (open the file in text mode) + O_CREAT (create file if it does not exist) + O_EXCL (fail if the file already exists) + O_NOCTTY (do not make the device the controlling terminal) + O_TRUNC (truncate the file if it exists) + O_APPEND (open the file in append mode) + O_NONBLOCK (open the file in non-blocking mode) +#v- + Some of these flags only make sense when combined with other flags. + For example, if O_EXCL is used, then O_CREAT must also be + specified, otherwise unpredictable behavior may result. + + If \var{O_CREAT} is used for the \var{flags} parameter then the + \var{mode} parameter must be present. \var{mode} specifies the + permissions to use if a new file is created. The actual file + permissions will be affected by the process's \var{umask} via + \exmp{mode&~umask}. The \var{mode} parameter's value is + constructed via bitwise-or of the following values: +#v+ + S_IRWXU (Owner has read/write/execute permission) + S_IRUSR (Owner has read permission) + S_IWUSR (Owner has write permission) + S_IXUSR (Owner has execute permission) + S_IRWXG (Group has read/write/execute permission) + S_IRGRP (Group has read permission) + S_IWGRP (Group has write permission) + S_IXGRP (Group has execute permission) + S_IRWXO (Others have read/write/execute permission) + S_IROTH (Others have read permission) + S_IWOTH (Others have write permission) + S_IXOTH (Others have execute permission) +#v- + Upon success \var{open} returns a file descriptor object + (\var{FD_Type}), otherwise \var{NULL} is returned and \var{errno} + is set. +\notes + If you are not familiar with the \var{open} system call, then it + is recommended that you use \var{fopen} instead. +\seealso{fopen, close, read, write, stat_file} +\done + +\function{read} +\synopsis{Read from an open file descriptor} +\usage{UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num)} +\description + The \var{read} function attempts to read at most \var{num} bytes + into the variable indicated by \var{buf} from the open file + descriptor \var{fd}. It returns the number of bytes read, or \-1 + and sets \var{errno} upon failure. The number of bytes read may be + less than \var{num}, and will be zero if an attempt is made to read + past the end of the file. +\notes + \var{read} is a low-level function and may return \-1 for a variety + of reasons. For example, if non-blocking I/O has been specified for + the open file descriptor and no data is available for reading then + the function will return \-1 and set \var{errno} to \var{EAGAIN}. +\seealso{fread, open, close, write} +\done + +\function{write} +\synopsis{Write to an open file descriptor} +\usage{UInt_Type write (FD_Type fd, BString_Type buf)} +\description + The \var{write} function attempts to write the bytes specified by + the \var{buf} parameter to the open file descriptor \var{fd}. It + returns the number of bytes successfully written, or \-1 and sets + \var{errno} upon failure. The number of bytes written may be less + than \exmp{length(buf)}. +\seealso{read, fwrite, open, close} +\done + diff --git a/libslang/doc/tm/rtl/posix.tm b/libslang/doc/tm/rtl/posix.tm new file mode 100644 index 0000000..d16b6eb --- /dev/null +++ b/libslang/doc/tm/rtl/posix.tm @@ -0,0 +1,285 @@ +\variable{errno} +\synopsis{Error code set by system functions.} +\usage{Integer_Type errno} +\description + A system function can fail for a variety of reasons. For example, a + file operation may fail because lack of disk space, or the process + does not have permission to perform the operation. Such functions + will return \var{-1} and set the variable \var{errno} to an error + code describing the reason for failure. + + Particular values of \var{errno} may be specified by the following + symbolic constants (read-only variables) and the corresponding + \var{errno_string} value: +#v+ + EPERM "Not owner" + ENOENT "No such file or directory" + ESRCH "No such process" + ENXIO "No such device or address" + ENOEXEC "Exec format error" + EBADF "Bad file number" + ECHILD "No children" + ENOMEM "Not enough core" + EACCES "Permission denied" + EFAULT "Bad address" + ENOTBLK "Block device required" + EBUSY "Mount device busy" + EEXIST "File exists" + EXDEV "Cross-device link" + ENODEV "No such device" + ENOTDIR "Not a directory" + EISDIR "Is a directory" + EINVAL "Invalid argument" + ENFILE "File table overflow" + EMFILE "Too many open files" + ENOTTY "Not a typewriter" + ETXTBSY "Text file busy" + EFBIG "File too large" + ENOSPC "No space left on device" + ESPIPE "Illegal seek" + EROFS "Read-only file system" + EMLINK "Too many links" + EPIPE "Broken pipe" + ELOOP "Too many levels of symbolic links" + ENAMETOOLONG "File name too long" +#v- +\example + The \var{mkdir} function will attempt to create a directory. If + that directory already exists, the function will fail and set + \var{errno} to \var{EEXIST}. +#v+ + define create_dir (dir) + { + if (0 == mkdir (dir)) return; + if (errno != EEXIST) + error ("mkdir %s failied: %s", dir, errno_string); + } +#v- +\seealso{errno_string, error, mkdir} +\done + +\function{errno_string} +\synopsis{Return a string describing an errno.} +\usage{String_Type errno_string (Integer_Type err)} +\description + The \var{errno_string} function returns a string describing the + integer error code \var{err}. The variable \var{err} usually + corresponds to the \var{errno} intrinsic function. See the + description for \var{errno} for more information. +\example + The \var{errno_string} function may be used as follows: +#v+ + define sizeof_file (file) + { + variable st = stat (file); + if (st == NULL) + verror ("%s: %s", file, errno_string (errno); + return st.st_size; + } +#v- +\seealso{errno, stat, verror} +\done + +\function{getegid} +\synopsis{Get the effective group id} +\usage{Int_Type getegid ()} +\description + The \var{getegid} function returns the effective group ID of the + current process. +\notes + This function is not supported by all systems. +\seealso{getgid, geteuid, setgid} +\done + +\function{geteuid} +\synopsis{Get the effective user-id of the current process} +\usage{Int_Type geteuid ()} +\description + The \var{geteuid} function returns the effective user-id of the + current process. +\notes + This function is not supported by all systems. +\seealso{getuid, setuid, setgid} +\done + +\function{getgid} +\synopsis{Get the group id} +\usage{Integer_Type getgid ()} +\description + The \var{getgid} function returns the real group id of the current + process. +\notes + This function is not supported by all systems. +\seealso{getpid, getppid} +\done + +\function{getpid} +\synopsis{Get the current process id} +\usage{Integer_Type getpid ()} +\description + The \var{getpid} function returns the current process identification + number. +\seealso{getppid, getgid} +\done + +\function{getppid} +\synopsis{Get the parent process id} +\usage{Integer_Type getppid ()} +\description + The \var{getpid} function returns the process identification + number of the parent process. +\notes + This function is not supported by all systems. +\seealso{getpid, getgid} +\done + +\function{getuid} +\synopsis{Get the user-id of the current process} +\usage{Int_Type getuid ()} +\description + The \var{getuid} function returns the user-id of the current + process. +\notes + This function is not supported by all systems. +\seealso{getuid, getegid} +\done + +\function{kill} +\synopsis{Send a signal to a process} +\usage{Integer_Type kill (Integer_Type pid, Integer_Type sig)} +\description + This function may be used to send a signal given by the integer \var{sig} + to the process specified by \var{pid}. The function returns zero upon + success and \exmp{-1} upon failure setting errno accordingly. +\example + The \var{kill} function may be used to determine whether or not + a specific process exists: +#v+ + define process_exists (pid) + { + if (-1 == kill (pid, 0)) + return 0; % Process does not exist + return 1; + } +#v- +\notes + This function is not supported by all systems. +\seealso{getpid} +\done + +\function{mkfifo} +\synopsis{Create a named pipe} +\usage{Int_Type mkfifo (String_Type name, Int_Type mode)} +\description + The \var{mkfifo} attempts to create a named pipe with the specified + name and mode (modified by the process's umask). The function + returns \0 upon success, or \-1 and sets \var{errno} upon failure. +\notes + Not all systems support the \var{mkfifo} function and even on + systems that do implement the \var{mkfifo} system call, the + underlying file system may not support the concept of a named pipe, + e.g, an NFS filesystem. +\seealso{stat_file} +\done + +\function{setgid} +\synopsis{Set the group-id of the current process} +\usage{Int_Type setgid (Int_Type gid)} +\description + The \var{setgid} function sets the effective group-id of the current + process. It returns zero upon success, or \-1 upon error and sets + \var{errno} appropriately. +\notes + This function is not supported by all systems. +\seealso{getgid, setuid} +\done + +\function{setpgid} +\synopsis{Set the process group-id} +\usage{Int_Type setpgid (Int_Type pid, Int_Type gid)} +\description + The \var{setpgid} function sets the group-id \var{gid} of the + process whose process-id is \var{pid}. If \var{pid} is \0, then the + current process-id will be used. If \var{pgid} is \0, then the pid + of the affected process will be used. + + If successful zero will be returned, otherwise the function will + return \-1 and set \var{errno} accordingly. +\notes + This function is not supported by all systems. +\seealso{setgid, setuid} +\done + +\function{setuid} +\synopsis{Set the user-id of the current process} +\usage{Int_Type setuid (Int_Type id)} +\description + The \var{setuid} function sets the effective user-id of the current + process. It returns zero upon success, or \-1 upon error and sets + \var{errno} appropriately. +\notes + This function is not supported by all systems. +\seealso{setgid, setpgid, getuid, geteuid} +\done + +\function{sleep} +\synopsis{Pause for a specified number of seconds} +\usage{sleep (Double_Type n)} +\description + The \var{sleep} function delays the current process for the + specified number of seconds. If it is interrupted by a signal, it + will return prematurely. +\notes + Not all system support sleeping for a fractional part of a second. +\done + +\function{system} +\synopsis{Execute a shell command} +\usage{Integer_Type system (String_Type cmd)} +\description + The \var{system} function may be used to execute the string + expression \var{cmd} in an inferior shell. This function is an + interface to the C \var{system} function which returns an + implementation-defined result. On Linux, it returns 127 if the + inferior shell could not be invoked, -1 if there was some other + error, otherwise it returns the return code for \var{cmd}. +\example +#v+ + define dir () + { + () = system ("DIR"); + } +#v- + displays a directory listing of the current directory under MSDOS or + VMS. +\seealso{popen, listdir} +\done + +\function{umask} +\synopsis{Set the file creation mask} +\usage{Int_Type umask (Int_Type m)} +\description + The \var{umask} function sets the file creation mask to \var{m} and + returns the previous mask. +\seealso{stat_file} +\done + +\function{uname} +\synopsis{Get the system name} +\usage{Struct_Tye uname ()} +\description + The \var{uname} function returns a structure containing information + about the operating system. The structure contains the following + fields: +#v+ + sysname (Name of the operating system) + nodename (Name of the node within the network) + release (Release level of the OS) + version (Current version of the release) + machine (Name of the hardware) +#v- +\notes + Not all systems support this function. +\seealso{getenv, pack, unpack} +\done + diff --git a/libslang/doc/tm/rtl/stack.tm b/libslang/doc/tm/rtl/stack.tm new file mode 100644 index 0000000..ad00a71 --- /dev/null +++ b/libslang/doc/tm/rtl/stack.tm @@ -0,0 +1,165 @@ +\function{__pop_args} +\synopsis{Remove n function arguments from the stack} +\usage{variable args = __pop_args(Integer_Type n);} +\description + This function together with the companion function \var{__push_args} + is useful for passing the arguments of a function to another function. + \var{__pop_args} returns an array of \var{n} structures with a + single structure field called \var{value}, which represents the value + of the argument. +\example + Consider the following \var{print} function. It prints all its + arguments to \var{stdout} separated by spaces: +#v+ + define print () + { + variable i; + variable args = __pop_args (_NARGS); + + for (i = 0; i < _NARGS; i++) + { + () = fputs (string (args[i].value), stdout); + () = fputs (" ", stdout); + } + () = fputs ("\n", stdout); + () = fflush (stdout); + } +#v- + Now consider the problem of defining a function called \var{ones} + that returns a multi-dimensional array with all the elements set to + 1. For example, \exmp{ones(10)} should return a 1-d array of ones, + whereas \exmp{ones(10,20)} should return a 10x20 array. +#v+ + define ones () + { + !if (_NARGS) return 1; + variable a; + + a = __pop_args (_NARGS); + return @Array_Type (Integer_Type, [__push_args (a)]) + 1; + } +#v- + Here, \var{__push_args} was used to push on the arguments passed to + the \var{ones} function onto the stack to be used when dereferencing + \var{Array_Type}. +\seealso{__push_args, typeof, _pop_n} +\done + +\function{__push_args} +\synopsis{Remove n function arguments onto the stack} +\usage{__push_args (Struct_Type args);} +\description + This function together with the companion function \var{__pop_args} + is useful for passing the arguments of one function to another. + See the desription of \var{__pop_args} for more information. +\seealso{__pop_args, typeof, _pop_n} +\done + +\function{_pop_n} +\synopsis{Remove objects from the stack} +\usage{_pop_n (Integer_Type n);} +\description + The \var{_pop_n} function pops \var{n} objects from the top of the + stack. +\example +#v+ + define add3 () + { + variable x, y, z; + if (_NARGS != 3) + { + _pop_n (_NARGS); + error ("add3: Expecting 3 arguments"); + } + (x, y, z) = (); + return x + y + z; + } +#v- +\seealso{_stkdepth, pop} +\done + +\function{_print_stack} +\synopsis{print the values on the stack.} +\usage{_print_stack ()} +\description + This function dumps out what is currently on the \slang. It does not + alter the stack and it is usually used for debugging purposes. +\seealso{_stkdepth, string} +\done + +\function{_stk_reverse} +\synopsis{Reverse the order of the objects on the stack.} +\usage{_stk_reverse (Integer_Type n)} +\description + The \var{_stk_reverse} function reverses the order of the top + \var{n} items on the stack. +\seealso{_stkdepth, _stk_roll} +\done + +\function{_stk_roll} +\synopsis{Roll items on the stack} +\usage{_stk_roll (Integer_Type n);} +\description + This function may be used to alter the arrangement of objects on the + stack. Specifically, if the integer \var{n} is positive, the top + \var{n} items on the stack are rotated up. If + \var{n} is negative, the top \var{abs(n)} items on the stack are + rotated down. +\example + If the stack looks like: +#v+ + item-0 + item-1 + item-2 + item-3 +#v- + where \exmp{item-0} is at the top of the stack, then + \exmp{_stk_roll(-3)} will change the stack to: +#v+ + item-2 + item-0 + item-1 + item-3 +#v- +\notes + This function only has an effect for \exmp{abs(n) > 1}. +\seealso{_stkdepth, _stk_reverse, _pop_n, _print_stack} +\done + +\function{_stkdepth} +\usage{Get the number of objects currently on the stack.} +\synopsis{Integer_Type _stkdepth ()} +\description + The \var{_stkdepth} function returns number of items on stack prior + to the call of \var{_stkdepth}. +\seealso{_print_stack, _stk_reverse, _stk_roll} +\done + +\function{dup} +\synopsis{Duplicate the value at the top of the stack} +\usage{dup ()} +\description + This function returns an exact duplicate of the object on top of the + stack. For some objects such as arrays or structures, it creates a + new reference to the array. However, for simple scalar S-Lang types such + as strings, integers, and doubles, it creates a new copy of the + object. +\seealso{pop, typeof} +\done + +\function{exch} +\synopsis{Exchange two items on the stack} +\usage{exch ()} +\description + The \var{exch} swaps the two top items on the stack. +\seealso{pop, _stk_reverse, _stk_roll} +\done + +\function{pop} +\synopsis{Discard an item from the stack} +\usage{pop ()} +\description + The \var{pop} function removes the top item from the stack. +\seealso{_pop_n} +\done + diff --git a/libslang/doc/tm/rtl/stdio.tm b/libslang/doc/tm/rtl/stdio.tm new file mode 100644 index 0000000..abb5ea8 --- /dev/null +++ b/libslang/doc/tm/rtl/stdio.tm @@ -0,0 +1,421 @@ +\function{clearerr} +\synopsis{Clear the error of a file stream} +\usage{clearerr (File_Type fp} +\description + The \var{clearerr} function clears the error and end-of-file flags + associated with the open file stream \var{fp}. +\seealso{ferror, feof, fopen} +\done + +\function{fclose} +\synopsis{Close a file} +\usage{Integer_Type fclose (File_Type fp)} +\description + The \var{fclose} function may be used to close an open file pointer + \var{fp}. Upon success it returns zero, and upon failure it sets + \var{errno} and returns \exmp{-1}. Failure usually indicates a that + the file system is full or that \var{fp} does not refer to an open file. +\notes + Many C programmers call \var{fclose} without checking the return + value. The \slang language requires the programmer to explicitly + handle any value returned by a \slang function. The simplest way to + handle the return value from \var{fclose} is to use it as: +#v+ + () = fclose (fp); +#v- +\seealso{fopen, fgets, fflush, pclose, errno} +\done + +\function{fdopen} +\synopsis{Convert a FD_Type file descriptor to a stdio File_Type object} +\usage{File_Type fdopen (FD_Type, String_Type mode)} +\description + The \var{fdopen} function creates and returns a stdio + \var{File_Type} object from the open \var{FD_Type} + descriptor \var{fd}. The \var{mode} parameter corresponds to the + \var{mode} parameter of the \var{fopen} function and must be + consistent with the mode of the descriptor \var{fd}. The function + returns \NULL upon failure and sets \var{errno}. +\notes + The \var{fclose} function does not close the \var{File_Type} object + returned from this function. The underlying file object must be + closed by the \var{close} function. +\seealso{fileno, fopen, open, close, fclose} +\done + +\function{feof} +\synopsis{Get the end-of-file status} +\usage{Integer_Type feof (File_Type fp)} +\description + This function may be used to determine the state of the end-of-file + indicator of the open file descriptor \var{fp}. It returns \var{0} + if the indicator is not set, or non-zero if it is. The end-of-file + indicator may be cleared by the \var{clearerr} function. +\seealso{ferror, clearerr, fopen} +\done + +\function{ferror} +\synopsis{Determine the error status of an open file descriptor} +\usage{Integer_Type ferror (File_Type fp)} +\description + This function may be used to determine the state of the error + indicator of the open file descriptor \var{fp}. It returns \var{0} + if the indicator is not set, or non-zero if it is. The error + indicator may be cleared by the \var{clearerr} function. +\seealso{feof, clearerr, fopen} +\done + +\function{fflush} +\synopsis{Flush an output stream} +\usage{Integer_Type fflush (File_Type fp)} +\description + The \var{fflush} function may be used to update the \em{output} + stream specified by \var{fp}. It returns \var{0} upon success, or + \var{-1} upon failure and sets \var{errno} accordingly. In + particular, this function will fail if \var{fp} does not represent + an output stream, or if \var{fp} is associated with a disk file and + there is insufficient disk space. +\example + This example illustrates how to use the \var{fflush} function + without regard to the return value: +#v+ + () = fputs ("Enter value> ", stdout); + () = fflush (stdout); +#v- +\notes + Many C programmers disregard the return value from the \var{fflush} + function. The above example illustrates how to properly do this in + the \slang langauge. +\seealso{fopen, fclose} +\done + +\function{fgets} +\synopsis{Read a line from a file.} +\usage{Integer_Type fgets (SLang_Ref_Type ref, File_Type fp)} +\description + \var{fgets} reads a line from the open file specified by \var{fp} + and places the characters in the variable whose reference is + specified by \var{ref}. + It returns \exmp{-1} if \var{fp} is not associated with an open file + or an attempt was made to read at the end the file; otherwise, it + returns the number of characters read. +\example + The following example returns the lines of a file via a linked list: +#v+ + define read_file (file) + { + variable buf, fp, root, tail; + variable list_type = struct { text, next }; + + root = NULL; + + fp = fopen(file, "r"); + if (fp == NULL) + error("fopen %s failed." file); + while (-1 != fgets (&buf, fp)) + { + if (root == NULL) + { + root = @list_type; + tail = root; + } + else + { + tail.next = @list_type; + tail = tail.next; + } + tail.text = buf; + tail.next = NULL; + } + () = fclose (fp); + return root; + } +#v- +\seealso{fopen, fclose, fputs, fread, error} +\done + +\function{fgetslines} +\synopsis{Read all the lines from an open file} +\usage{String_Type[] fgetslines (File_Type fp)} +\description + The \var{fgetslines} function returns all the remaining lines as an + array of strings in the file specified by the open file pointer + \var{fp}. If the file is empty, an empty string array will be + returned. The function returns \var{NULL} upon error. +\example + The following function returns the number of lines in a file: +#v+ + define count_lines_in_file (file) + { + variable fp, lines; + + fp = fopen (file, "r"); + if (fp == NULL) + return -1; + + lines = fgetslines (fp); + if (lines == NULL) + return -1; + + return length (lines); + } +#v- + Note that the file was implicitly closed by the function. +\notes + This function should not be used if the file contains many lines + since that would require that all the lines be read into memory. +\seealso{fgets, fread, fopen} +\done + +\function{fopen} +\synopsis{Open a file} +\usage{File_Type fopen (String_Type f, String_Type m)} +\description + The \var{fopen} function opens a file \var{f} according to the mode + string \var{m}. Allowed values for \var{m} are: +#v+ + "r" Read only + "w" Write only + "a" Append + "r+" Reading and writing at the beginning of the file. + "w+" Reading and writing. The file is created if it does not + exist; otherwise, it is truncated. + "a+" Reading and writing at the end of the file. The file is created + if it does not already exist. +#v- + In addition, the mode string can also include the letter \var{'b'} + as the last character to indicate that the file is to be opened in + binary mode. + + Upon success, \var{fopen} a \var{File_Type} object which is meant to + be used in other operations that require an open file. Upon + failure, the function returns \var{NULL}. +\example + The following function opens a file in append mode and writes a + string to it: +#v+ + define append_string_to_file (file, str) + { + variable fp = fopen (file, "a"); + if (fp == NULL) verror ("%s could not be opened", file); + () = fputs (string, fp); + () = fclose (fp); + } +#v- + Note that the return values from \var{fputs} and \var{fclose} are + ignored. +\notes + There is no need to explicitly close a file opened with \var{fopen}. + If the returned \var{File_Type} object goes out of scope, \slang + will automatically close the file. However, explicitly closing a + file after use is recommended. +\seealso{fclose, fgets, fputs, popen} +\done + +\function{fprintf} +\synopsis{Create and write a formatted string to a file} +\usage{Int_Type fprintf (File_Type fp, String_Type fmt, ...)} +\description + \var{fprintf} formats the objects specified by the variable argument + list according to the format \var{fmt} and write the result to the + open file pointer \var{fp}. + + The format string obeys the same syntax and semantics as the + \var{sprintf} format string. See the description of the + \var{sprintf} function for more information. + + \var{fprintf} returns the number of characters written to the file, + or \-1 upon error. +\seealso{fputs, printf, fwrite, message} +\done + +\function{fputs} +\synopsis{Write a string to an open stream} +\usage{Integer_Type fputs (String_Type s, File_Type fp);} +\description + The \var{fputs} function writes the string \var{s} to the open file + pointer \var{fp}. It returns -1 upon failure and sets \var{errno}, + otherwise it returns the length of the string. +\example + The following function opens a file in append mode and uses the + \var{fputs} function to write to it. +#v+ + define append_string_to_file (str, file) + { + variable fp; + fp = fopen (file, "a"); + if (fp == NULL) verror ("Unable to open %s", file); + if ((-1 == fputs (s, fp)) + or (-1 == fclose (fp))) + verror ("Error writing to %s", file); + } +#v- +\notes + One must not disregard the return value from the \var{fputs} + function, as many C programmers do. Doing so may lead to a stack + overflow error. + + To write an object that contains embedded null characters, use the + \var{fwrite} function. +\seealso{fclose, fopen, fgets, fwrite} +\done + +\function{fread} +\synopsis{Read binary data from a file} +\usage{UInt_Type fread (Ref_Type b, DataType_Type t, UInt_Type n, File_Type fp)} +\description + The \var{fread} function may be used to read \var{n} objects of type + \var{t} from an open file pointer \var{fp}. Upon success, it + returns the number of objects read from the file and places the + objects in the variable specified by \var{b}. Upon error or end of + file, it returns \var{-1}. If more than one object is read from the + file, those objects will be placed in an array of the appropriate + size. The exception to this is when reading \var{Char_Type} or + \var{UChar_Type} objects from a file, in which case the data will be + returned as an \var{n} character BString_Type binary string, but + only if \var{n}>1. +\example + The following example illustrates how to read 50 bytes from a file: +#v+ + define read_50_bytes_from_file (file) + { + variable fp, n, buf; + + fp = fopen (file, "rb"); + if (fp == NULL) error ("Open failed"); + n = fread (&buf, Char_Type, 50, fp); + if (n == -1) + error ("fread failed"); + () = fclose (fp); + return buf; + } +#v- +\notes + Use the \var{pack} and \var{unpack} functions to read data with a + specific byte-ordering. +\seealso{fwrite, fgets, fopen, pack, unpack} +\done + +\function{fseek} +\synopsis{Reposition a stream} +\usage{Integer_Type fseek (File_Type fp, Integer_Type ofs, Integer_Type whence} +\description + The \var{fseek} function may be used to reposition the file position + pointer associated with the open file stream \var{fp}. Specifically, + it moves the pointer \var{ofs} bytes relative to the position + indicated by \var{whence}. If whence is set to one of the symbolic + constants \exmp{SEEK_SET}, \exmp{SEEK_CUR}, or \exmp{SEEK_END}, the + offset is relative to the start of the file, the current position + indicator, or end-of-file, respectively. + + The function return zero upon success, or \-1 upon failure and sets + \var{errno} accordingly. +\example + define rewind (fp) + { + if (0 == fseek (fp, 0, SEEK_SET)) return; + vmessage ("rewind failed, reason: %s", errno_string (errno)); + } +\notes + The current implementation uses an integer to specify the offset. + One some systems, a long integer may be required making this + function fail for very large files, i.e., files that are longer than + the maximum value of an integer. +\seealso{ftell, fopen} +\done + +\function{ftell} +\synopsis{Obtain the current position in an open stream} +\usage{Integer_Type ftell (File_Type fp)} +\description + The ftell function may be used to obtain the current position in the + stream associated with the open file pointer \var{fp}. It returns + the position of the pointer measured in bytes from the beginning of + the file. Upon error, it returns \exmp{-1} and sets \var{errno}. +\seealso{fseek, fopen} +\done + +\function{fwrite} +\synopsis{Write binary data to a file} +\usage{UInt_Type fwrite (b, File_Type fp)} +\description + The \var{fwrite} may be used to write the object represented by + \var{b} to an open file. If \var{b} is a string or an array, the + function will attempt to write all elements of the object to the + file. It returns the number of objects successfully written, + otherwise it returns \-1 upon error and sets \var{errno} + accordingly. +\example + The following example illustrates how to write an integer array to a + file. In this example, \var{fp} is an open file descriptor: +#v+ + variable a = [1:50]; % 50 element integer array + if (50 != fwrite (a, fp)) + error ("fwrite failed"); +#v- + Here is how to write the array one element at a time: +#v+ + variable a = [1:50]; + foreach (a) + { + variable ai = (); + if (1 != fwrite(ai, fp)) + error ("fwrite failed"); + } +#v- +\notes + Not all data types may support the \var{fwrite} operation. However, + it is supported by all vector, scalar, and string objects. +\seealso{fread, fputs, fopen, pack, unpack} +\done + +\function{pclose} +\synopsis{Close an object opened with popen} +\usage{Integer_Type pclose (File_Type fp)} +\description + The \var{pclose} function waits for the process associated with + \var{fp} to exit and the returns the exit status of the command. +\seealso{pclose, fclose} +\done + +\function{popen} +\synopsis{Open a process} +\usage{File_Type popen (String_Type cmd, String_Type mode)} +\description + The \var{popen} function executes a process specified by \var{cmd} + and opens a unidirectional pipe to the newly created process. The + \var{mode} indicates whether or not the pipe is open for reading + or writing. Specifically, if \var{mode} is \exmp{"r"}, then the + pipe is opened for reading, or if \var{mode} is \exmp{"w"}, then the + pipe will be open for writing. + + Upon success, a \var{File_Type} pointer will be returned, otherwise + the function failed and \var{NULL} will be returned. +\notes + This function is not available on all systems. +\seealso{pclose, fopen} +\done + +\function{printf} +\synopsis{Create and write a formatted string to stdout} +\usage{Int_Type printf (String_Type fmt, ...)} +\description + \var{fprintf} formats the objects specified by the variable argument + list according to the format \var{fmt} and write the result to + \var{stdout}. This function is equivalent to \var{fprintf} used + with the \var{stdout} file pointer. See \var{fprintf} for more + information. + + \var{printf} returns the number of characters written to the file, + or \-1 upon error. +\notes + Many C programmers do not check the return status of the + \var{printf} C library function. Make sure that if you do not care + about whether or not the function succeeds, then code it as in the + following example: +#v+ + () = printf ("%s laid %d eggs\n", chicken_name, num_egg); +#v- +\seealso{fputs, printf, fwrite, message} +\done + diff --git a/libslang/doc/tm/rtl/strops.tm b/libslang/doc/tm/rtl/strops.tm new file mode 100644 index 0000000..5b1d8b4 --- /dev/null +++ b/libslang/doc/tm/rtl/strops.tm @@ -0,0 +1,736 @@ +\function{Sprintf} +\synopsis{Format objects into a string} +\usage{String_Type Sprintf (String_Type format, ..., Integer_Type n)} +\description + \var{Sprintf} formats a string from \var{n} objects according to + \var{format}. Unlike \var{sprintf}, the \var{Sprintf} function + requires the number of items to format. + + The format string is a C library \var{sprintf} style format + descriptor. Briefly, the format string may consist of ordinary + characters (not including the \exmp{%} character), which are copied + into the output string as-is, and a conversion specification + introduced by the \exmp{%} character. The \var{%} character must be + followed by at least one other character to specify the conversion: +#v+ + s value is a string + f value is a floating point number + e print float in exponential form, e.g., 2.345e08 + g print float as e or g, depending upon its value + c value is an ascii character + % print the percent character + d print a signed decimal integer + u print an unsigned decimal integer + o print an integer as octal + X print an integer as hexadecimal + S convert value to a string and format as string +#v- + Note that \var{%S} is a \slang extension which will cause the value + to be formatted as string. In fact, \exmp{sprintf("%S",x)} is + equivalent to \exmp{sprintf("%s",string(x))}. +#v+ + s = Sprintf("%f is greater than %f but %s is better than %s\n", + PI, E, "Cake" "Pie", 4); +#v- + The final argument to \var{Sprintf} is the number of items to format; in + this case, there are 4 items. +\seealso{sprintf, string, sscanf} +\done + +\function{create_delimited_string} +\synopsis{Concatenate strings using a delimiter} +\usage{String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n)} +#v+ + String_Type delim, s_1, ..., s_n + Integer_Type n +#v- +\description + \var{create_delimited_string} performs a concatenation operation on + the \var{n} strings \var{s_1}, ...,\var{s_n}, using the string + \var{delim} as a delimiter. The resulting string is equivalent to + one obtained via +#v+ + s_1 + delim + s_2 + delim + ... + s_n +#v- +\example + One use for this function is to construct path names, e.g., +#v+ + create_delimited_string ("/", "user", "local", "bin", 3); +#v- + will produce \exmp{"usr/local/bin"}. +\notes + The expression \exmp{strcat(a,b)} is equivalent to + \exmp{create_delimited_string("", a, b, 2)}. +\seealso{strjoin, is_list_element, extract_element, strchop, strcat} +\done + +\function{extract_element} +\synopsis{Extract the nth element of a string with delimiters} +\usage{String_Type extract_element (String_Type list, Integer_Type nth, Integer_Type delim);} +\description + The \var{extract_element} function may be used to extract the + \var{nth} element of the \var{delim} delimited list of strings + \var{list}. The function will return the \var{nth} element of the + list, unless \var{nth} specifies more elements than the list + contains, in which case \var{NULL} will be returned. + Elements in the list are numbered from \var{0}. +\example + The expression +#v+ + extract_element ("element 0, element 1, element 2", 1, ',') +#v- + returns the string \exmp{" element 1"}, whereas +#v+ + extract_element ("element 0, element 1, element 2", 1, ' ') +#v- + returns \exmp{"0,"}. + + The following function may be used to compute the number of elements + in the list: +#v+ + define num_elements (list, delim) + { + variable nth = 0; + while (NULL != extract_element (list, nth, delim)) + nth++; + return nth; + } +#v- + + Alternatively, the \var{strchop} function may be more useful. In + fact, \var{extract_element} may be expressed in terms of the + function \var{strchop} as +#v+ + define extract_element (list, nth, delim) + { + list = strchop(list, delim, 0); + if (nth >= length (list)) + return NULL; + else + return list[nth]; + } +#v- + and the \var{num_elements} function used above may be recoded more + simply as: +#v+ + define num_elements (list, delim) + { + return length (strchop (length, delim, 0)); + } +#v- +\seealso{is_list_element, is_substr, strtok, strchop, create_delimited_string} +\done + +\function{is_list_element} +\synopsis{Test whether a delimited string contains a specific element} +\usage{Integer_Type is_list_element (String_Type list, String_Type elem, Integer_Type delim)} +\description + The \var{is_list_element} function may be used to determine whether + or not a delimited list of strings, \var{list}, contains the element + \var{elem}. If \var{elem} is not an element of \var{list}, the function + will return zero, otherwise, it returns 1 plus the matching element + number. +\example + The expression +#v+ + is_list_element ("element 0, element 1, element 2", "0,", ' '); +#v- + returns \exmp{2} since \exmp{"0,"} is element number one of the list + (numbered from zero). +\seealso{extract_element, is_substr, create_delimited_string} +\done + +\function{is_substr} +\synopsis{Test for a specified substring within a string.} +\usage{Integer_Type is_substr (String_Type a, String_Type b)} +\description + This function may be used to determine if \var{a} contains the + string \var{b}. If it does not, the function returns 0; otherwise it + returns the position of the first occurance of \var{b} in \var{a}. +\notes + It is important to remember that the first character of a string + corresponds to a position value of \exmp{1}. +\seealso{substr, string_match, strreplace} +\done + +\function{make_printable_string} +\synopsis{Format a string suitable for parsing} +\usage{String_Type make_printable_string(String_Type str)} +\description + This function formats a string in such a way that it may be used as + an argument to the \var{eval} function. The resulting string is + identical to \var{str} except that it is enclosed in double quotes and the + backslash, newline, and double quote characters are expanded. +\seealso{eval, str_quote_string} +\done + +\function{sprintf} +\synopsis{Format objects into a string} +\usage{String sprintf (String format, ...);} +\description + This function performs a similar task as the C function with the same + name. It differs from the \slang function \var{Sprintf} in that it + does not require the number of items to format. + See the documentation for \var{Sprintf} for more information. +\seealso{Sprintf, string, sscanf, vmessage} +\done + +\function{sscanf} +\synopsis{Parse a formatted string} +\usage{Int_Type sscanf (s, fmt, r1, ... rN)} +#v+ + String_Type s, fmt; + Ref_Type r1, ..., rN +#v- +\description + The \var{sscanf} function parses the string \var{s} according to the + format \var{fmt} and sets the variables whose references are given by + \var{r1}, ..., \var{rN}. The function returns the number of + references assigned, or \var{-1} upon error. + + The format string \var{fmt} consists of ordinary characters and + conversion specifiers. A conversion specifier begins with the + special character \var{%} and is described more fully below. A white + space character in the format string matches any amount of whitespace + in the input string. Parsing of the format string stops whenever a + match fails. + + The \var{%} is used to denote a conversion specifier whose general + form is given by \exmp{%[*][width][type]format} where the brackets + indicate optional items. If \var{*} is present, then the conversion + will be performed by no assignment to a reference will be made. The + \var{width} specifier specifies the maximum field width to use for + the conversion. The \var{type} modifier is used to indicate size of + the object, e.g., a short integer, as follows. + + If \em{type} is given as the character \var{h}, then if the format + conversion is for an integer (\var{dioux}), the object assigned will + be a short integer. If \em{type} is \var{l}, then the conversion + will be to a long integer for integer conversions, or to a double + precession floating point number for floating point conversions. + + The format specifier is a character that specifies the conversion: +#v+ + % Matches a literal percent character. No assigment is + performed. + d Matches a signed decimal integer. + D Matches a long decimal integer (equiv to `ld') + u Matches an unsigned decimal integer + U Matches an unsigned long decimal integer (equiv to `lu') + i Matches either a hexidecimal integer, decimal integer, or + octal integer. + I Equivalent to `li'. + x Matches a hexidecimal integer. + X Matches a long hexidecimal integer (same as `lx'). + e,f,g Matches a decimal floating point number (Float_Type). + E,F,G Matches a double precision floating point number, same as `lf'. + s Matches a string of non-whitespace characters (String_Type). + c Matches one character. If width is given, width + characters are matched. + n Assigns the number of characters scanned so far. + [...] Matches zero or more characters from the set of characters + enclosed by the square brackets. If '^' is given as the + first character, then the complement set is matched. +#v- +\example + Suppose that \var{s} is \exmp{"Coffee: (3,4,12.4)"}. Then +#v+ + n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z); +#v- + will set \var{n} to \4, \var{item} to \exmp{"Coffee"}, \var{x} to \3, + \var{y} to \4, and \var{z} to the double precision number + \exmp{12.4}. However, +#v+ + n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z); +#v- + will set \var{n} to \1, \var{item} to \exmp{"Coffee:"} and the + remaining variables will not be assigned. +\seealso{sprintf, unpack, string, atof, int, integer, string_match} +\done + +\function{str_delete_chars} +\synopsis{Delete characters from a string} +\usage{String_Type str_delete_chars (String_Type str, String_Type del_set} +\description + This function may be used to delete the set of characters specified + by \var{del_set} from the string \var{str}. The result is returned. +\example +#v+ + str = str_delete_chars (str, "^A-Za-z"); +#v- + will remove all characters except \exmp{A-Z} and \exmp{a-z} from + \var{str}. +\done + +\function{str_quote_string} +\synopsis{Escape characters in a string.} +\usage{String_Type str_quote_string(String_Type str, String_Type qlis, Integer_Type quote)} +\description + The \var{str_quote_string} returns a string identical to \var{str} + except that all characters in the set specified by the string + \var{qlis} are escaped with the \var{quote} character, including the + quote character itself. This function is useful for making a + string that can be used in a regular expression. +\example + Execution of the statements +#v+ + node = "Is it [the coat] really worth $100?"; + tag = str_quote_string (node, "\\^$[]*.+?", '\\'); +#v- + will result in \var{tag} having the value: +#v+ + Is it \[the coat\] really worth \$100\? +#v- +\seealso{str_uncomment_string, make_printable_string} +\done + +\function{str_replace} +\synopsis{Replace a substring of a string} +\usage{Integer_Type str_replace (String_Type a, String_Type b, String_Type c)} +\description + The \var{str_replace} function replaces the first occurance of \var{b} in + \var{a} with \var{c} and returns an integer that indicates whether a + replacement was made or not. If \var{b} does not occur in \var{a}, zero is + returned. However, if \var{b} occurs in \var{a}, a non-zero integer is + returned as well as the new string resulting from the replacement. +\notes + This function has been superceded by \var{strreplace}. +\seealso{strreplace} +\done + +\function{str_uncomment_string} +\synopsis{Remove comments from a string} +\usage{String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end)} +\description + This function may be used to remove comments from a string \var{s}. + The parameters, \var{beg} and \var{end}, are strings of equal length + whose corresponding characters specify the begin and end comment + characters, respectively. It returns the uncommented string. +\example + The expression +#v+ + str_uncomment_string ("Hello (testing) 'example' World", "'(", "')") +#v- + returns the string \exmp{"Hello World"}. +\notes + This routine does not handle multicharacter comment delimiters and it + assumes that comments are not nested. +\seealso{str_quote_string} +\done + +\function{strcat} +\synopsis{Concatenate strings} +\usage{String_Type strcat (String_Type a_1, ..., String_Type a_N)} +\description + The \var{strcat} function concatenates its N \var{String_Type} + arguments \var{a_1}, ... \var{a_N} together and returns the result. +\example +#v+ + strcat ("Hello", " ", "World"); +#v- + produces the string \exmp{"Hello World"}. +\notes + This function is equivalent to the binary operation \exmp{a_1+...+a_N}. + However, \var{strcat} is much faster making it the preferred method + to concatenate string. +\seealso{sprintf, create_delimited_string} +\done + +\function{strchop} +\synopsis{Chop or split a string into substrings.} +\usage{String_Type[] strchop (String_Type str, Integer_Type delim, Integer_Type quote)} +\description + The \var{strchop} function may be used to split-up a string + \var{str} that consists of substrings delimited by the character + specified by \var{delim}. If the integer \var{quote} is non-zero, + it will be taken as a quote character for the delimiter. The + function returns the substrings as an array. +\example + The following function illustrates how to sort a comma separated + list of strings: +#v+ + define sort_string_list (a) + { + variable i, b, c; + b = strchop (a, ',', 0); + + i = array_sort (b, &strcmp); + b = b[i]; % rearrange + + % Convert array back into comma separated form + return strjoin (b, ","); + } +#v- +\notes + The semantics of this \var{strchop} and \var{strchopr} have been + changed since version 1.2.x of the interpreter. Old versions of + these functions returned the values on the stack, which meant that + one could not chop up arbitrarily long strings that consist of + many substrings. + + The function \var{strchopr} should be used if it is desired to have + the string chopped-up in the reverse order. +\seealso{strchopr, extract_element, strjoin, strtok} +\done + +\function{strchopr} +\synopsis{Chop or split a string into substrings.} +\usage{String_Type[] strchopr (String_Type str, String_Type delim, String_Type quote)} +\description + This routine performs exactly the same function as \var{strchop} except + that it returns the substrings in the reverse order. See the + documentation for \var{strchop} for more information. +\seealso{strchop, extract_element, strtok, strjoin} +\done + +\function{strcmp} +\synopsis{Compare two strings} +\usage{Interpret strcmp (String_Type a, String_Type b)} +\description + The \var{strcmp} function may be used to perform a case-sensitive + string comparison, in the lexicongraphic sense, on strings \var{a} and + \var{b}. It returns 0 if the strings are identical, a negative integer + if \var{a} is less than \var{b}, or a positive integer if \var{a} is greater + than \var{b}. +\example + The \var{strup} function may be used to perform a case-insensitive + string comparison: +#v+ + define case_insensitive_strcmp (a, b) + { + return strcmp (strup(a), strup(b)); + } +#v- +\notes + One may also use one of the binary comparison operators, e.g., + \exmp{a > b}. +\seealso{strup, strncmp} +\done + +\function{strcompress} +\synopsis{Remove excess whitespace characters from a string} +\usage{String_Type strcompress (String_Type s, String_Type white)} +\description + The \var{strcompress} function compresses the string \var{s} by + replacing a sequence of one or more characters from the set + \var{white} by the first character of \var{white}. In addition, it + also removes all leading and trailing characters from \var{s} that + are part of \var{white}. +\example + The expression +#v+ + strcompress (",;apple,,cherry;,banana", ",;"); +#v- + returns the string \exmp{"apple,cherry,banana"}. +\seealso{strtrim, strtrans} +\done + +\function{string_match} +\synopsis{Match a string against a regular expression} +\usage{Integer_Type string_match(String_Type str, String_Type pat, Integer_Type pos)} +\description + The \var{string_match} function returns zero if \var{str} does not + match regular expression specified by \var{pat}. This function + performs the match starting at position \var{pos} (numbered from 1) in + \var{str}. This function returns the position of the start of the + match. To find the exact substring actually matched, use + \var{string_match_nth}. +\seealso{string_match_nth, strcmp, strncmp} +\done + +\function{string_match_nth} +\synopsis{Get the result of the last call to string_match} +\usage{(Integer_Type, Integer_Type) = string_match_nth(Integer_Type nth)} +\description + The \var{string_match_nth} function returns two integers describing + the result of the last call to \var{string_match}. It returns both + the offset into the string and the length of characters matches by + the \var{nth} submatch. + + By convention, \var{nth} equal to zero means the entire match. + Otherwise, \var{nth} must be an integer with a value 1 through 9, + and refers to the set of characters matched by the \var{nth} regular + expression enclosed by the pairs \exmp{\\(, \\)}. +\example + Consider: +#v+ + variable matched, pos, len; + matched = string_match("hello world", "\\([a-z]+\\) \\([a-z]+\\)", 1); + if (matched) (pos, len) = string_match_nth(2); +#v- + This will set \var{matched} to 1 since a match will be found at the + first position, \var{pos} to 6 since \var{w} is offset 6 characters + from the beginning of the string, and \var{len} to 5 since + \exmp{"world"} is 5 characters long. +\notes + The position offset is \em{not} affected by the value of the offset + parameter to the \var{string_match} function. For example, if the + value of the last parameter to the \var{string_match} function had + been 3, \var{pos} would still have been set to 6. + + Note also that \var{string_match_nth} returns the \em{offset} from + the beginning of the string and not the position of the match. +\seealso{string_match} +\done + +\function{strjoin} +\synopsis{Concatenate elements of a string array} +\usage{String_Type strjoin (Array_Type a, String_Type delim)} +\description + The \var{strjoin} function operates on an array of strings by joining + successive elements together separated with a delimiter \var{delim}. + If \var{delim} is the empty string \exmp{""}, then the result will + simply be the concatenation of the elements. +\example + Suppose that +#v+ + days = ["Sun","Mon","Tue","Wed","Thu","Fri","Sat","Sun"]; +#v- + Then \exmp{strjoin (days,"+")} will produce + \exmp{"Sun+Mon+Tue+Wed+Thu+Fri+Sat+Sun"}. Similarly, + \exmp{strjoin (["","",""], "X")} will produce \exmp{"XX"}. +\seealso{create_delimited_string, strchop, strcat} +\done + +\function{strlen} +\synopsis{Compute the length of a string} +\usage{Integer_Type strlen (String_Type a)} +\description + The \var{strlen} function may be used to compute the length of a string. +\example + After execution of +#v+ + variable len = strlen ("hello"); +#v- + \var{len} will have a value of \exmp{5}. +\seealso{bstrlen, length, substr} +\done + +\function{strlow} +\synopsis{Convert a string to lowercase} +\usage{String_Type strlow (String_Type s)} +\description + The \var{strlow} function takes a string \var{s} and returns another + string identical to \var{s} except that all upper case characters + that comprise \var{s} will be converted to lower case. +\example + The function +#v+ + define Strcmp (a, b) + { + return strcmp (strlow (a), strlow (b)); + } +#v- + performs a case-insensitive comparison operation of two strings by + converting them to lower case first. +\seealso{strup, tolower, strcmp, strtrim, define_case} +\done + +\function{strncmp} +\synopsis{Compare the first few characters of two strings} +\usage{Integer_Type strncmp (String_Type a, String_Type b, Integer_Type n)} +\description + This function behaves like \var{strcmp} except that it compares only the + first \var{n} characters in the strings \var{a} and \var{b}. See + the documentation for \var{strcmp} for information about the return + value. +\example + The expression +#v+ + strcmp ("apple", "appliance", 3); +#v- + will return zero since the first three characters match. +\seealso{strcmp, strlen} +\done + +\function{strreplace} +\synopsis{Replace one or more substrings} +\usage{(new, n) = strreplace (a, b, c, max_n)} +#v+ + String_Type a, b, c, rep; + Int_Type n, max_n; +#v- +\description + The \var{strreplace} function may be used to replace one or more + occurances of \var{b} in \var{a} with \var{c}. If the integer + \var{max_n} is positive, then the first \var{max_n} occurances of + \var{b} in \var{a} will be replaced. Otherwise, if \var{max_n} is + negative, then the last \exmp{abs(max_n)} occurances will be replaced. + + The function returns the resulting string and an integer indicating + how many replacements were made. +\example + The following function illustrates how \var{strreplace} may be used + to remove all occurances of a specified substring +#v+ + define delete_substrings (a, b) + { + (a, ) = strreplace (a, b, "", strlen (a)); + return a; + } +#v- +\seealso{is_substr, strsub, strtrim, strtrans, str_delete_chars} +\done + +\function{strsub} +\synopsis{Replace a character with another in a string.} +\usage{String_Type strsub (String_Type s, Integer_Type pos, Integer_Type ch)} +\description + The \var{strsub} character may be used to substitute the character + \var{ch} for the character at position \var{pos} of the string + \var{s}. The resulting string is returned. +\example +#v+ + define replace_spaces_with_comma (s) + { + variable n; + while (n = is_substr (s, " "), n) s = strsub (s, n, ','); + return s; + } +#v- + For uses such as this, the \var{strtrans} function is a better choice. +\notes + The first character in the string \var{s} is specified by \var{pos} + equal to 1. +\seealso{is_substr, strreplace, strlen} +\done + +\function{strtok} +\synopsis{Extract tokens from a string} +\usage{String_Type[] strtok (String_Type str [,String_Type white])} +\description + \var{strtok} breaks the string \var{str} into a series of tokens and + returns them as an array of strings. If the second parameter + \var{white} is present, then it specifies the set of characters that + are to be regarded as whitespace when extracting the tokens, and may + consist of the whitespace characters or a range of such characters. + If the first character of \var{white} is \exmp{'^'}, then the + whitespace characters consist of all characters except those in + \var{white}. For example, if \var{white} is \exmp{" \\t\\n,;."}, + then those characters specifiy the whitespace characters. However, + if \var{white} is given by \exmp{"^a-zA-Z0-9_"}, then any character + is a whitespace character except those in the ranges \exmp{a-z}, + \exmp{A-Z}, \exmp{0-9}, and the underscore character. + + If the second parameter is not present, then it defaults to + \exmp{" \\t\\r\\n\\f"}. +\example + The following example may be used to count the words in a text file: +#v+ + define count_words (file) + { + variable fp, line, count; + + fp = fopen (file, "r"); + if (fp == NULL) return -1; + + count = 0; + while (-1 != fgets (&line, fp)) + { + line = strtok (line, "^a-zA-Z"); + count += length (line); + } + () = fclose (fp); + return count; + } +#v- +\seealso{strchop, strcompress, extract_element, strjoin} +\done + +\function{strtrans} +\synopsis{Replace characters in a string} +\usage{String_Type strtrans (str, old_set, new_set)} +#v+ + String_Type str, old_set, new_set; +#v- +\description + The \var{strtrans} function may be used to replace all the characters + from the set \var{old_set} with the corresponding characters from + \var{new_set} in the string \var{str}. If \var{new_set} is empty, + then the characters in \var{old_set} will be removed from \var{str}. + This function returns the result. +\example +#v+ + str = strtrans (str, "A-Z", "a-z"); % lower-case str + str = strtrans (str, "^0-9", " "); % Replace anything but 0-9 by space +#v- +\seealso{strreplace, strtrim, strup, strlow} +\done + +\function{strtrim} +\synopsis{Remove whitespace from the ends of a string} +\usage{String_Type strtrim (String_Type s [,String_Type w])} +\description + The \var{strtrim} function removes all leading and trailing whitespace + characters from the string \var{s} and returns the result. The + optional second parameter specifies the set of whitespace + characters. If the argument is not present, then the set defaults + to \exmp{" \\t\\r\\n"}. +\seealso{strtrim_beg, strtrim_end, strcompress} +\done + +\function{strtrim_beg} +\synopsis{Remove leading whitespace from a string} +\usage{String_Type strtrim_beg (String_Type s [,String_Type w])} +\description + The \var{strtrim_beg} function removes all leading whitespace + characters from the string \var{s} and returns the result. The + optional second parameter specifies the set of whitespace + characters. If the argument is not present, then the set defaults + to \exmp{" \\t\\r\\n"}. +\seealso{strtrim, strtrim_end, strcompress} +\done + +\function{strtrim_end} +\synopsis{Remove trailing whitespace from a string} +\usage{String_Type strtrim_end (String_Type s [,String_Type w])} +\description + The \var{strtrim_end} function removes all trailing whitespace + characters from the string \var{s} and returns the result. The + optional second parameter specifies the set of whitespace + characters. If the argument is not present, then the set defaults + to \exmp{" \\t\\r\\n"}. +\seealso{strtrim, strtrim_beg, strcompress} +\done + +\function{strup} +\synopsis{Convert a string to uppercase} +\usage{String_Type strup (String_Type s)} +\description + The \var{strup} function takes a string \var{s} and returns another + string identical to \var{s} except that all lower case characters + that comprise \var{s} will be converted to upper case. +\example + The function +#v+ + define Strcmp (a, b) + { + return strcmp (strup (a), strup (b)); + } +#v- + performs a case-insensitive comparison operation of two strings by + converting them to upper case first. +\seealso{strlow, toupper, strcmp, strtrim, define_case, strtrans} +\done + +\function{substr} +\synopsis{Extract a substring from a string} +\usage{String_Type substr (String_Type s, Integer_Type n, Integer_Type len)} +\description + The \var{substr} function returns a substring with length \var{len} + of the string \var{s} beginning at position \var{n}. If \var{len} is + \exmp{-1}, the entire length of the string \var{s} will be used for + \var{len}. The first character of \var{s} is given by \var{n} equal + to 1. +\example +#v+ + substr ("To be or not to be", 7, 5); +#v- + returns \exmp{"or no"} +\notes + In many cases it is more convenient to use array indexing rather + than the \var{substr} function. In fact, \exmp{substr(s,i+1,strlen(s))} is + equivalent to \exmp{s[[i:]]}. +\seealso{is_substr, strlen} +\done + diff --git a/libslang/doc/tm/rtl/struct.tm b/libslang/doc/tm/rtl/struct.tm new file mode 100644 index 0000000..9d23263 --- /dev/null +++ b/libslang/doc/tm/rtl/struct.tm @@ -0,0 +1,104 @@ +\function{_push_struct_field_values} +\synopsis{Push the values of a structure's fields onto the stack} +\usage{Integer_Type num = _push_struct_field_values (Struct_Type s)} +\description + The \var{_push_struct_field_values} function pushes the values of + all the fields of a structure onto the stack, returning the + number of items pushed. The fields are pushed such that the last + field of the structure is pushed first. +\seealso{get_struct_field_names, get_struct_field} +\done + +\function{get_struct_field} +\synopsis{Get the value associated with a structure field} +\usage{x = get_struct_field (Struct_Type s, String field_name)} +\description + The \var{get_struct_field} function gets the value of the field + whose name is specified by \var{field_name} of the structure \var{s}. +\example + The following example illustrates how this function may be used to + to print the value of a structure. +#v+ + define print_struct (s) + { + variable name; + + foreach (get_struct_field_names (s)) + { + name = (); + value = get_struct_field (s, name); + vmessage ("s.%s = %s\n", name, string(value)); + } + } +#v- +\seealso{set_struct_field, get_struct_field_names, array_info} + +\done + +\function{get_struct_field_names} +\synopsis{Retrieve the field names associated with a structure} +\usage{String_Type[] = get_struct_field_names (Struct_Type s)} +\description + The \var{get_struct_field_names} function returns an array of + strings whose elements specify the names of the fields of the + struct \var{s}. +\example + The following example illustrates how the + \var{get_struct_field_names} function may be used to print the + value of a structure. +#v+ + define print_struct (s) + { + variable name, value; + + foreach (get_struct_field_names (s)) + { + name = (); + value = get_struct_field (s, name); + vmessage ("s.%s = %s\n", name, string (value)); + } + } +#v- +\seealso{_push_struct_field_values, get_struct_field} +\done + +\function{is_struct_type} +\synopsis{Determine whether or not an object is a structure} +\usage{Integer_Type is_struct_type (X)} +\description + The \var{is_struct_type} function returns \1 if the parameter + refers to a structure or a user-defined type. If the object is + neither, \0 will be returned. +\seealso{typeof, _typeof} +\done + +\function{set_struct_field} +\synopsis{Set the value associated with a structure field} +\usage{set_struct_field (s, field_name, field_value)} +#v+ + Struct_Type s; + String_Type field_name; + Generic_Type field_value; +#v- +\description + The \var{set_struct_field} function sets the value of the field + whose name is specified by \var{field_name} of the structure + \var{s} to \var{field_value}. +\seealso{get_struct_field, get_struct_field_names, set_struct_fields, array_info} +\done + +\function{set_struct_fields} +\synopsis{Set the fields of a structure} +\usage{set_struct_fields (Struct_Type s, ...)} +\description + The \var{set_struct_fields} function may be used to set zero or more + fields of a structure. The fields are set in the order in which + they were created when the structure was defined. +\example +#v+ + variable s = struct { name, age, height }; + set_struct_fields (s, "Bill", 13, 64); +#v- +\seealso{set_struct_field, get_struct_field_names} +\done + diff --git a/libslang/doc/tm/rtl/time.tm b/libslang/doc/tm/rtl/time.tm new file mode 100644 index 0000000..bc11de4 --- /dev/null +++ b/libslang/doc/tm/rtl/time.tm @@ -0,0 +1,137 @@ +\function{_time} +\synopsis{Get the current time in seconds} +\usage{ULong_Type _time ()} +\description + The \var{_time} function returns the number of elapsed seconds since + 00:00:00 GMT, January 1, 1970. The \var{ctime} function may be used + to convert this into a string representation. +\seealso{ctime, time, localtime, gmtime} +\done + +\function{ctime} +\synopsis{Convert a calendar time to a string} +\usage{String_Type ctime(ULong_Type secs)} +\description + This function returns a string representation of the time as given + by \var{secs} seconds since 1970. +\seealso{time, _time, localtime, gmtime} +\done + +\function{gmtime} +\synopsis{Break down a time in seconds to GMT timezone} +\usage{Struct_Type gmtime (Long_Type secs)} +\description + The \var{gmtime} function is exactly like \var{localtime} except + that the values in the structure it returns are with respect to GMT + instead of the local timezone. See the documentation for + \var{localtime} for more information. +\notes + On systems that do not support the \var{gmtime} C library function, + this function is the same as \var{localtime}. +\seealso{localtime, _time} +\done + +\function{localtime} +\synopsis{Break down a time in seconds to local timezone} +\usage{Struct_Type localtime (Long_Type secs)} +\description + The \var{localtime} function takes a parameter \var{secs} + representing the number of seconds since 00:00:00, January 1 1970 + UTC and returns a structure containing information about \var{secs} + in the local timezone. The structure contains the following + \var{Int_Type} fields: + + \var{tm_sec} The number of seconds after the minute, normally + in the range 0 to 59, but can be up to 61 to allow for + leap seconds. + + \var{tm_min} The number of minutes after the hour, in the + range 0 to 59. + + \var{tm_hour} The number of hours past midnight, in the range + 0 to 23. + + \var{tm_mday} The day of the month, in the range 1 to 31. + + \var{tm_mon} The number of months since January, in the range + 0 to 11. + + \var{tm_year} The number of years since 1900. + + \var{tm_wday} The number of days since Sunday, in the range 0 + to 6. + + \var{tm_yday} The number of days since January 1, in the + range 0 to 365. + + \var{tm_isdst} A flag that indicates whether daylight saving + time is in effect at the time described. The value is + positive if daylight saving time is in effect, zero if it + is not, and negative if the information is not available. +\seealso{gmtime, _time, ctime} +\done + +\function{tic} +\synopsis{Start timing} +\usage{void tic ()} +\description + The \var{tic} function restarts the internal clock used for timing + the execution of commands. To get the elapsed time of the clock, + use the \var{toc} function. +\seealso{toc, times} +\done + +\function{time} +\synopsis{Return the current data and time as a string} +\usage{String_Type time ()} +\description + This function returns the current time as a string of the form: +#v+ + Sun Apr 21 13:34:17 1996 +#v- +\seealso{ctime, message, substr} +\done + +\function{times} +\synopsis{Get process times} +\usage{Struct_Type times ()} +\description + The \var{times} function returns a structure containing the + following fields: +#v+ + tms_utime (user time) + tms_stime (system time) + tms_cutime (user time of child processes) + tms_cstime (system time of child processes) +#v- +\notes + Not all systems support this function. +\seealso{tic, toc, _times} +\done + +\function{toc} +\synopsis{Get elapsed CPU time} +\usage{Double_Type toc ()} +\description + The \var{toc} function returns the elapsed CPU time in seconds since + the last call to \var{tic}. The CPU time is the amount of time the + CPU spent running the code of the current process. +\example + The \var{tic} and \var{toc} functions are ideal for timing the + execution of the interpreter: +#v+ + variable a = "hello", b = "world", c, n = 100000, t; + + tic (); loop (n) c = a + b; t = toc (); + vmessage ("a+b took %f seconds\n", t); + tic (); loop (n) c = strcat(a,b); t = toc (); + vmessage ("strcat took %f seconds\n", t); +#v- +\notes + This function may not be available on all systems. + + The implementation of this function is based upon the \var{times} + system call. The precision of the clock is system dependent. +\seealso{tic, times, _time} +\done + diff --git a/libslang/doc/tm/rtl/tm-sort.sl b/libslang/doc/tm/rtl/tm-sort.sl new file mode 100755 index 0000000..ca73827 --- /dev/null +++ b/libslang/doc/tm/rtl/tm-sort.sl @@ -0,0 +1,153 @@ +#! /usr/bin/env slsh +_debug_info = 1; + +if (__argc < 2) +{ + () = fprintf (stderr, "Usage: %s files....\n", __argv[0]); + exit (1); +} + +static variable Data; + +static define init () +{ + Data = Assoc_Type[String_Type]; +} + +static define warning () +{ + variable args = __pop_args (_NARGS); + () = fprintf (stderr, "***WARNING: %s\n", sprintf (__push_args ())); +} + + +static define process_function (line, fp) +{ + variable fname; + variable lines; + + fname = strtrim (strtok (line, "{}")[1]); + + lines = line; +#iftrue + foreach (fp) + { + line = (); + lines = strcat (lines, line); + if (0 == strncmp ("\\done", line, 5)) + break; + } +#else + while (-1 != fgets (&line, fp)) + { + lines += line; + if (0 == strncmp ("\\done", line, 5)) + break; + } +#endif + if (assoc_key_exists (Data, fname)) + { + warning ("Key %s already exists", fname); + return -1; + } + + Data[fname] = lines; + return 0; +} + +static define process_variable (line, fp) +{ + % warning ("process_variable not implemented"); + process_function (line, fp); +} + +static define read_file_contents (file) +{ + variable fp = fopen (file, "r"); + variable n = 0; + variable line; + + if (fp == NULL) + { + () = fprintf (stderr, "Unable to open %s\n", file); + return -1; + } + + + %while (-1 != fgets (&line, fp)) + foreach (fp) + { + line = (); + if (0 == strncmp (line, "\\function{", 10)) + { + if (-1 == process_function (line, fp)) + return -1; + + continue; + } + + if (0 == strncmp (line, "\\variable{", 10)) + { + if (-1 == process_variable (line, fp)) + return -1; + + continue; + } + } + + () = fclose (fp); + return 0; +} + +static define sort_and_write_file_elements (file) +{ + variable fp; + variable i, keys; + variable backup_file; + + backup_file = file + ".BAK"; + () = remove (backup_file); + () = rename (file, backup_file); + + fp = fopen (file, "w"); + if (fp == NULL) + return -1; + + keys = assoc_get_keys (Data); + i = array_sort (keys, &strcmp); + + foreach (keys[i]) + { + variable k = (); + + () = fputs (Data[k], fp); + () = fputs ("\n", fp); + } + + () = fclose (fp); + + return 0; +} + + +static define process_file (file) +{ + init (); + + () = fprintf (stdout, "Processing %s ...", file); + () = fflush (stdout); + + if (-1 == read_file_contents (file)) + return -1; + + if (-1 == sort_and_write_file_elements (file)) + return -1; + + () = fputs ("done.\n", stdout); + return 0; +} + +foreach (__argv[[1:]]) + process_file (); + +exit (0); diff --git a/libslang/doc/tm/rtl/type.tm b/libslang/doc/tm/rtl/type.tm new file mode 100644 index 0000000..342f012 --- /dev/null +++ b/libslang/doc/tm/rtl/type.tm @@ -0,0 +1,245 @@ +\function{_slang_guess_type} +\synopsis{Guess the data type that a string represents.} +\usage{DataType_Type _slang_guess_type (String_Type s)} +\description + This function tries to determine whether its argument \var{s} + represents an integer (short, int, long), floating point (float, + double), or a complex number. If it appears to be none of these, + then a string is assumed. It returns one of the following values + depending on the format of the string \var{s}: +#v+ + Short_Type : short integer (e.g., "2h") + UShort_Type : unsigned short integer (e.g., "2hu") + Integer_Type : integer (e.g., "2") + UInteger_Type : unsigned integer (e.g., "2") + Long_Type : long integer (e.g., "2l") + ULong_Type : unsigned long integer (e.g., "2l") + Float_Type : float (e.g., "2.0f") + Double_Type : double (e.g., "2.0") + Complex_Type : imaginary (e.g., "2i") + String_Type : Anything else. (e.g., "2foo") +#v- + For example, \exmp{_slang_guess_type("1e2")} returns + \var{Double_Type} but \exmp{_slang_guess_type("e12")} returns + \var{String_Type}. +\seealso{integer, string, double, atof} +\done + +\function{_typeof} +\synopsis{Get the data type of an object} +\usage{DataType_Type _typeof (x)} +\description + This function is similar to the \var{typeof} function except in the + case of arrays. If the object \exmp{x} is an array, then the data + type of the array will be returned. otherwise \var{_typeof} returns + the data type of \var{x}. +\example +#v+ + if (Integer_Type == _typeof (x)) + message ("x is an integer or an integer array"); +#v- +\seealso{typeof, array_info, _slang_guess_type, typecast} +\done + +\function{atof} +\synopsis{Convert a string to a double precision number} +\usage{Double_Type atof (String_Type s)} +\description + This function converts a string \var{s} to a double precision value + and returns the result. It performs no error checking on the format + of the string. The function \var{_slang_guess_type} may be used to + check the syntax of the string. +\example +#v+ + define error_checked_atof (s) + { + switch (_slang_guess_type (s)) + { + case Double_Type: + return atof (s); + } + { + case Integer_Type: + return double (integer (s)); + } + + verror ("%s is not a double", s); + } +#v- +\seealso{typecast, double, _slang_guess_type} +\done + +\function{char} +\synopsis{Convert an ascii value into a string} +\usage{String_Type char (Integer_Type c)} +\description + The \var{char} function converts an integer ascii value \var{c} to a string + of unit length such that the first character of the string is \var{c}. + For example, \exmp{char('a')} returns the string \exmp{"a"}. +\seealso{integer, string, typedef} +\done + +\function{define_case} +\synopsis{Define upper-lower case conversion.} +\usage{define_case (Integer_Type ch_up, Integer_Type ch_low);} +\description + This function defines an upper and lowercase relationship between two + characters specified by the arguments. This relationship is used by + routines which perform uppercase and lowercase conversions. + The first integer \var{ch_up} is the ascii value of the uppercase character + and the second parameter \var{ch_low} is the ascii value of its + lowercase counterpart. +\seealso{strlow, strup} +\done + +\function{double} +\synopsis{Convert an object to double precision} +\usage{result = double (x)} +\description + The \var{double} function typecasts an object \var{x} to double + precision. For example, if \var{x} is an array of integers, an + array of double types will be returned. If an object cannot be + converted to \var{Double_Type}, a type-mismatch error will result. +\notes + The \var{double} function is equivalent to the typecast operation +#v+ + typecast (x, Double_Type) +#v- + To convert a string to a double precision number, use the \var{atof} + function. +\seealso{typecast, atof, int} +\done + +\function{int} +\synopsis{Typecast an object to an integer} +\usage{int (s)} +\description + This function performs a typecast of \var{s} from its data type to + an object of \var{Integer_Type}. If \var{s} is a string, it returns + returns the ascii value of the first character of the string + \var{s}. If \var{s} is \var{Double_Type}, \var{int} truncates the + number to an integer and returns it. +\example + \var{int} can be used to convert single character strings to + integers. As an example, the intrinsic function \var{isdigit} may + be defined as +#v+ + define isdigit (s) + { + if ((int (s) >= '0') and (int (s) <= '9')) return 1; + return 0; + } +#v- +\notes + This function is equalent to \exmp{typecast (s, Integer_Type)}; +\seealso{typecast, double, integer, char, isdigit} +\done + +\function{integer} +\synopsis{Convert a string to an integer} +\usage{Integer_Type integer (String_Type s)} +\description + The \var{integer} function converts a string representation of an + integer back to an integer. If the string does not form a valid + integer, a type-mismatch error will be generated. +\example + \exmp{integer ("1234")} returns the integer value \exmp{1234}. +\notes + This function operates only on strings and is not the same as the + more general \var{typecast} operator. +\seealso{typecast, _slang_guess_type, string, sprintf, char} +\done + +\function{isdigit} +\synopsis{Tests for a decimal digit character} +\usage{Integer_Type isdigit (String_Type s)} +\description + This function returns a non-zero value if the first character in the + string \var{s} is a digit; otherwise, it returns zero. +\example + A simple, user defined implementation of \var{isdigit} is +#v+ + define isdigit (s) + { + return ((s[0] <= '9') and (s[0] >= '0')); + } +#v- + However, the intrinsic function \var{isdigit} executes many times faster + than the equivalent representation defined above. +\notes + Unlike the C function with the same name, the \slang function takes + a string argument. +\seealso{int, integer} +\done + +\function{string} +\synopsis{Convert an object to a string representation.} +\usage{Integer_Type string (obj)} +\description + The \var{string} function may be used to convert an object + \var{obj} of any type to a string representation. + For example, \exmp{string(12.34)} returns \exmp{"12.34"}. +\example +#v+ + define print_anything (anything) + { + message (string (anything)); + } +#v- +\notes + This function is \em{not} the same as typecasting to a \var{String_Type} + using the \var{typecast} function. +\seealso{typecast, sprintf, integer, char} +\done + +\function{tolower} +\synopsis{Convert a character to lowercase.} +\usage{Integer_Type lower (Integer_Type ch)} +\description + This function takes an integer \var{ch} and returns its lowercase + equivalent. +\seealso{toupper, strup, strlow, int, char, define_case} +\done + +\function{toupper} +\synopsis{Convert a character to uppercase.} +\usage{Integer_Type toupper (Integer_Type ch)} +\description + This function takes an integer \var{ch} and returns its uppercase + equivalent. +\seealso{tolower, strup, strlow, int, char, define_case} +\done + +\function{typecast} +\synopsis{Convert an object from one data type to another.} +\usage{typecast (x, new_type)} +\description + The \var{typecast} function performs a generic typecast operation on + \var{x} to convert it to \var{new_type}. If \var{x} represents an + array, the function will attempt to convert all elements of \var{x} + to \var{new_type}. Not all objects can be converted and a + type-mismatch error will result upon failure. +\example +#v+ + define to_complex (x) + { + return typecast (x, Complex_Type); + } +#v- + defines a function that converts its argument, \var{x} to a complex + number. +\seealso{int, double, typeof} +\done + +\function{typeof} +\synopsis{Get the data type of an object.} +\usage{DataType_Type typeof (x)} +\description + This function returns the data type of \var{x}. +\example +#v+ + if (Integer_Type == typeof (x)) message ("x is an integer"); +#v- +\seealso{_typeof, is_struct_type, array_info, _slang_guess_type, typecast} +\done + diff --git a/libslang/doc/tm/rtl/whatelse.sl b/libslang/doc/tm/rtl/whatelse.sl new file mode 100755 index 0000000..fec4f0d --- /dev/null +++ b/libslang/doc/tm/rtl/whatelse.sl @@ -0,0 +1,116 @@ +#! /usr/bin/env slsh +% -*- slang -*- + +% This file is used to determine what functions still need documenting. +% I think that it provides a good example of the use of associative arrays. + +_debug_info = 1; + +variable Src_Files = "../../../src/*.c"; +variable TM_Files = "*.tm"; +variable Unwanted_Files = "../../../src/calc.c"; + +define grep (pat, files) +{ + if (strlen (files) == 0) + return String_Type[0]; + + variable fp = popen (sprintf ("rgrep '%s' %s", pat, files), "r"); + variable matches; + + matches = fgetslines (fp); + () = pclose (fp); + + return matches; +} + + +static define prune_array (a, b) +{ + foreach (b) using ("keys") + { + variable k = (); + assoc_delete_key (a, k); + } +} + +define get_with_pattern (a, pat, white) +{ + variable f; + + foreach (grep (pat, Src_Files)) + { + f = (); + + f = strtok (f, white)[1]; + a [f] = 1; + } + + if (Unwanted_Files != NULL) foreach (grep (pat, Unwanted_Files)) + { + f = (); + f = strtok (f, white)[1]; + assoc_delete_key (a, f); + } +} + +define get_src_intrinsics () +{ + variable f; + variable src = Assoc_Type[Int_Type]; + + get_with_pattern (src, "^[ \t]+MAKE_INTRINSIC.*(\".*\"", "\""); + get_with_pattern (src, "^[ \t]+MAKE_MATH_UNARY.*(\".*\"", "\""); + get_with_pattern (src, "^[ \t]+MAKE_VARIABLE.*(\".*\"", "\""); + get_with_pattern (src, "^[ \t]+MAKE_DCONSTANT.*(\".*\"", "\""); + get_with_pattern (src, "^[ \t]+MAKE_ICONSTANT.*(\".*\"", "\""); + + return src; +} + +define get_doc_intrinsics () +{ + variable funs; + variable doc = Assoc_Type[Int_Type]; + + funs = grep ("^\\\\function{", TM_Files); + foreach (funs) + { + variable f; + f = (); + f = strtok (f, "{}")[1]; + doc [f] = 1; + } + funs = grep ("^\\\\variable{", TM_Files); + foreach (funs) + { + f = (); + f = strtok (f, "{}")[1]; + doc [f] = 1; + } + return doc; +} + + +define main () +{ + variable k; + variable src, doc; + + doc = get_doc_intrinsics (); + src = get_src_intrinsics (); + + prune_array (src, doc); + + k = assoc_get_keys (src); + k = k[array_sort(k)]; + + foreach (k) + { + message (); + } +} + +main (); + + |