_traceback SYNOPSIS Generate a traceback upon error USAGE Integer_Type _traceback DESCRIPTION `_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 `_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 `_traceback' is zero the traceback will not be generated. Local variables are represented in the form `$n' where `n' is an integer numbered from zero. More explicitly, `$0' represents the first local variable, `$1' represents the second, and so on. Please note that function parameters are local variables and that the first parameter corresponds to `$0'. SEE ALSO _slangtrace, error -------------------------------------------------------------- _slangtrace SYNOPSIS Turn function tracing on or off. USAGE Integer_Type _slangtrace DESCRIPTION The `_slangtrace' variable is a debugging aid that when set to a non-zero value enables tracing when function declared by `_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. SEE ALSO _trace_function, _traceback, _print_stack -------------------------------------------------------------- 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 `-1' and set the variable `errno' to an error code describing the reason for failure. Particular values of `errno' may be specified by the following symbolic constants (read-only variables) and the corresponding `errno_string' value: 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" EXAMPLE The `mkdir' function will attempt to create a directory. If that directory already exists, the function will fail and set `errno' to `EEXIST'. define create_dir (dir) { if (0 == mkdir (dir)) return; if (errno != EEXIST) error ("mkdir %s failied: %s", dir, errno_string); } SEE ALSO errno_string, error, mkdir -------------------------------------------------------------- where SYNOPSIS Get indices where an integer array is non-zero USAGE Array_Type where (Array_Type a) DESCRIPTION The `where' function examines an integer array `a' and returns a 2-d integer array whose rows are the indices of `a' where the corresponding element of `a' is non-zero. EXAMPLE Consider the following: variable X = [0.0:10.0:0.01]; variable A = sin (X); variable I = where (A < 0.0); A[I] = cos (X) [I]; Here the variable `X' has been assigned an array of doubles whose elements range from `0.0' through `10.0' in increments of `0.01'. The second statement assigns `A' to an array whose elements are the `sin' of the elements of `X'. The third statement uses the where function to get the indices of the elements of `A' that are less than `0.0'. Finally, the last statement substitutes into `A' the `cos' of the elements of `X' at the positions of `A' where the corresponding `sin' is less than `0'. The end result is that the elements of `A' are a mixture of sines and cosines. SEE ALSO array_info, sin, cos -------------------------------------------------------------- vmessage SYNOPSIS Print a formatted string onto the message device USAGE vmessage (String_Type fmt, ...) DESCRIPTION The `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 `vmessage' function is not an intrinsic function. Rather it is a predefined S-Lang function using a combination of `Sprintf' and `message'. SEE ALSO message, Sprintf, verror -------------------------------------------------------------- _apropos SYNOPSIS Generate a list of functions and variable USAGE Integer_Type _apropos (String_Type s, Integer_Type flags) DESCRIPTION The `_apropos' function may be used to get a list of all defined objects whose name consists of the substring `s' and whose type matches those specified by `flags'. It returns the number of matches. If the number returned is non-zero, that number of strings which represent the names of the matched objects will also be present on the stack. The second parameter `flags' is a bit mapped value whose bits are defined according to the following table 1 Intrinsic Function 2 User-defined Function 4 Intrinsic Variable 8 User-defined Variable EXAMPLE define apropos (s) { variable n, name; n = _apropos (s, 0xF); if (n) vmessage ("Found %d matches:", n); else message ("No matches."); loop (n) { name = (); message (name); } } prints a list of all matches. NOTES Since the function returns the matches to the stack, it is possible that a stack overfow error could result if there are two many matches. If this happens, the interpreter should be recompiled to use a larger stack size. SEE ALSO is_defined, sprintf -------------------------------------------------------------- _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 `putenv' function: define try_putenv (name, value) { variable status; ERROR_BLOCK { _clear_error (); status = -1; } status = 0; putenv (sprintf ("%s=%s", name, value); return status; } If `putenv' fails, it generates an error condition, which the `try_putenv' function catches and clears. Thus `try_putenv' is a function that returns `-1' upon failure and `0' upon success. SEE ALSO _trace_function, _slangtrace, _traceback -------------------------------------------------------------- _function_name SYNOPSIS Returns the name of the currently executing function USAGE String _function_name (); DESCRIPTION This function returns the name of the currently executing function. If called from top-level, it returns the empty string. SEE ALSO _trace_function, is_defined -------------------------------------------------------------- _pop_n SYNOPSIS Remove objects from the stack USAGE _pop_n (Integer_Type n); DESCRIPTION The `_pop_n' function pops `n' objects from the top of the stack. EXAMPLE define add3 () { variable x, y, z; if (_NARGS != 3) { _pop_n (_NARGS); error ("add3: Expecting 3 arguments"); } (x, y, z) = (); return x + y + z; } SEE ALSO _stkdepth, pop -------------------------------------------------------------- _print_stack SYNOPSIS print the values on the stack. USAGE _print_stack () DESCRIPTION This function dumps out what is currently on the S-Lang. It does not alter the stack and it is usually used for debugging purposes. SEE ALSO _stkdepth, string -------------------------------------------------------------- _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 `s' represents an integer or a floating point number. If it appears to be neither, then a string is assumed. It returns one of three values depending on the format of the string `s': Integer_Type : If it appears to be an integer Double_Type : If it appears to be a double String_Type : Anything else. For example, `_slang_guess_type("1e2")' returns `Double_Type' but `_slang_guess_type("e12")' returns `String_Type'. SEE ALSO integer, string, double -------------------------------------------------------------- _stk_reverse SYNOPSIS Reverse the order of the objects on the stack. USAGE _stk_reverse (Integer_Type n) DESCRIPTION The `_stk_reverse' function reverses the order of the top `n' items on the stack. SEE ALSO _stkdepth, _stk_roll -------------------------------------------------------------- _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 `n' is positive, the top `n' items on the stack are rotated up. If `n' is negative, the top `abs(n)' items on the stack are rotated down. EXAMPLE If the stack looks like: item-0 item-1 item-2 item-3 where `item-0' is at the top of the stack, then `_stk_roll(-3)' will change the stack to: item-2 item-0 item-1 item-3 NOTES This function only has an effect for `abs(n) > 1'. SEE ALSO _stkdepth, _stk_reverse, _pop_n, _print_stack -------------------------------------------------------------- _stkdepth USAGE Get the number of objects currently on the stack. SYNOPSIS Integer_Type _stkdepth () DESCRIPTION The `_stkdepth' function returns number of items on stack prior to the call of `_stkdepth'. SEE ALSO _print_stack, _stk_reverse, _stk_roll -------------------------------------------------------------- _trace_function SYNOPSIS Set the function to trace USAGE _trace_function (String_Type f) DESCRIPTION `_trace_function' declares that the S-Lang function with name `f' is to be traced when it is called. Calling `_trace_function' does not in itself turn tracing on. Tracing is turned on only when the variable `_slangtrace' is non-zero. SEE ALSO _slangtrace, _traceback -------------------------------------------------------------- array_info SYNOPSIS Returns information about an array USAGE (Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a) DESCRIPTION The `array_info' function returns information about the array `a'. It returns three values: an 1-d integer array array specifying the size of each dimension of `a', the number of dimensions of `a', and the data type of `a'. EXAMPLE The `array_info' function may be used to find the number of rows of an array: define num_rows (a) { variable dims, num_dims, data_type; (dims, num_dims, data_type) = array_info (a); return dims [0]; } SEE ALSO typeof, reshape -------------------------------------------------------------- array_sort SYNOPSIS Sort an array USAGE Array_Type array_sort (Array_Type a, String_Type f) DESCRIPTION `array_sort' sorts the array `a' into ascending order according to the function specified by the name `f' and returns an integer array that represents the result of the sort. The sort function represented by `f' must be a S-Lang 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. The integer array returned by this function is simply an index that indicates the order of the sorted array. The input array `a' is not changed. EXAMPLE An array of strings may be sorted using the `strcmp' function since it fits the specification for the sorting function described above: variable A = String_Type [3]; A[0] = "gamma"; A[1] = "alpha"; A[2] = "beta"; variable I = array_sort (A, "strcmp"); After the `array_sort' has executed, the variable `I' will have the values `[2, 0, 1]'. This array can be used to re-shuffle the elements of `A' into the sorted order via the array index expression `A = A[I]'. NOTES The current sorting algorithm is a heap-sort. SEE ALSO strcmp -------------------------------------------------------------- atof SYNOPSIS Convert a string to a double precision number USAGE Double_Type atof (String_Type s) DESCRIPTION This function converts a string `s' to a double precision value and returns the result. It performs no error checking on the format of the string. The function `_slang_guess_type' may be used to check the syntax of the string. EXAMPLE 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 is not a double", s); } SEE ALSO typecast, double, _slang_guess_type -------------------------------------------------------------- autoload SYNOPSIS Load a function from a file USAGE autoload (String_Type funct, String_Type file) DESCRIPTION The `autoload' function is used to declare `funct' to the interpreter and indicate that it should be loaded from `file' when it is actually used. EXAMPLE Suppose `bessel_j0' is a function defined in the file `bessel.sl'. Then the statement autoload ("bessel_j0", "bessel.sl"); will cause `bessel.sl' to be loaded prior to the execution of `bessel_j0' SEE ALSO evalfile -------------------------------------------------------------- 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 `byte_compile_file' function byte-compiles `file' producing a new file with the same name except a `'c'' is added to the output file name. For example, `file' is `"site.sl"', then the function produces a new file named `site.slc'. NOTES The `method' parameter is not used in the current implementation. Its use is reserved for the future. For now, set it to `0'. SEE ALSO evalfile -------------------------------------------------------------- char SYNOPSIS Convert an ascii value into a string USAGE String_Type char (Integer_Type c) DESCRIPTION The `char' function converts an integer ascii value `c' to a string of unit length such that the first character of the string is `c'. For example, `char('a')' returns the string `"a"'. SEE ALSO integer, string, typedef -------------------------------------------------------------- chdir SYNOPSIS Change the current working directory. USAGE Integer_Type chdir (String_Type dir) DESCRIPTION The `chdir' function may be used to changed the current working directory to the directory specified by `dir'. Upon sucess it returns zero; however, upon failure it returns `-1' and sets `errno' accordingly. SEE ALSO mkdir, stat_file -------------------------------------------------------------- chmod SYNOPSIS Change the mode of a file USAGE Integer_Type chmod (String_Type file, Integer_Type mode) DESCRIPTION The `chmod' function changes the permissions of `file' to those specified by `mode'. It returns `0' upon success, or `-1' upon failure setting `errno' accordingly. See the system specific documentation for the C library function `chmod' for a discussion of the `mode' parameter. SEE ALSO chown, stat_file -------------------------------------------------------------- chown SYNOPSIS Change the owner of a file USAGE Integer_Type chown (String_Type file, Integer_Type uid, Integer_Type gid) DESCRIPTION The `chown' function is used to change the user-id and group-id of `file' to `uid' and `gid', respectively. It returns `zero' upon success and `-1' upon failure, with `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. SEE ALSO chmod, stat_file -------------------------------------------------------------- create_delimited_string SYNOPSIS Concatenate strings using a delimiter USAGE String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n) String_Type delim, s_1, ..., s_n Integer_Type n DESCRIPTION `create_delimited_string' performs a concatenation operation on the `n' strings `s_1', ...,`s_n', using the string `delim' as a delimiter. The resulting string is equivalent to one obtained via s_1 + delim + s_2 + delim + ... + s_n EXAMPLE One use for this function is to construct path names, e.g., create_delimited_string ("/", "user", "local", "bin", 3); will produce `"usr/local/bin"'. NOTES The expression `strcat(a,b)' is equivalent to `create_delimited_string("", a, b, 2)'. SEE ALSO is_list_element, extract_element, strchop, strcat -------------------------------------------------------------- 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 `ch_up' is the ascii value of the uppercase character and the second parameter `ch_low' is the ascii value of its lowercase counterpart. SEE ALSO strlow, strup -------------------------------------------------------------- double SYNOPSIS Convert an object to double precision USAGE result = double (x) DESCRIPTION The `double' function typecasts an object `x' to double precision. For example, if `x' is an array of integers, an array of double types will be returned. If an object cannot be converted to `Double_Type', a type-mismatch error will result. NOTES The `double' function is equivalent to the typecast operation typecast (x, Double_Type) To convert a string to a double precision number, use `atoi' function. SEE ALSO typecast, atoi, int -------------------------------------------------------------- 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. SEE ALSO pop, typeof -------------------------------------------------------------- errno_string SYNOPSIS Return a string describing an errno. USAGE String_Type errno_string (Integer_Type err) DESCRIPTION The `errno_string' function returns a string describing the integer error code `err'. The variable `err' usually corresponds to the `errno' intrinsic function. See the description for `errno' for more information. EXAMPLE The `errno_string' function may be used as follows: define sizeof_file (file) { variable st = stat (file); if (st == NULL) verror ("%s: %s", file, errno_string (errno); return st.st_size; } SEE ALSO errno, stat, verror -------------------------------------------------------------- error SYNOPSIS Generate an error condition USAGE error (String_Type msg DESCRIPTION The `error' function generates a S-Lang 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 `ERROR_BLOCK' with the `_clear_error' function. Consult \user-manual for more information. EXAMPLE define add_txt_extension (file) { if (typeof (file) != String_Type) error ("add_extension: parameter must be a string"); file += ".txt"; return file; } SEE ALSO verror, _clear_error, message -------------------------------------------------------------- evalfile SYNOPSIS Interpret a file containing slang code. USAGE Integer_Type evalfile (String_Type file) DESCRIPTION The `evalfile' function loads `file' into the interpreter. If no errors were encountered, `1' will be returned; otherwise, a S-Lang error will be generated and the function will return zero. EXAMPLE define load_file (file) { ERROR_BLOCK { _clear_error (); } () = evalfile (file); } SEE ALSO eval, autoload -------------------------------------------------------------- eval SYNOPSIS Interpret a string as slang code USAGE eval (String_Type expression) DESCRIPTION The `eval' function parses a string as S-Lang code and executes the result. This is a useful function in many contexts such as dynamically generating function definitions where there is no way to generate them otherwise. EXAMPLE if (0 == is_defined ("my_function")) eval ("define my_function () { message (\"my_function\"); }"); SEE ALSO is_defined, autoload, evalfile -------------------------------------------------------------- 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 `extract_element' function may be used to extract the `nth' element of the `delim' delimited list of strings `list'. The function will return the `nth' element of the list, unless `nth' specifies more elements than the list contains, in which case `NULL' will be returned. Elements in the list are numbered from `0'. EXAMPLE The expression extract_element ("element 0, element 1, element 2", 1, ',') returns the string `" element 1"', whereas extract_element ("element 0, element 1, element 2", 1, ' ') returns `"0,"'. The following function may be used to compute the number of elements in the list: define num_elements (list, delim) { variable nth = 0; while (NULL != extract_element (list, nth, delim)) nth++; return nth; } SEE ALSO is_list_element, is_substr, strchop, create_delimited_string -------------------------------------------------------------- fclose SYNOPSIS Close a file USAGE Integer_Type fclose (File_Type fp) DESCRIPTION The `fclose' function may be used to close an open file pointer `fp'. Upon success it returns zero, and upon failure it sets `errno' and returns `-1'. Failure usually indicates a that the file system is full or that `fp' does not refer to an open file. NOTES Many C programmers call `fclose' without checking the return value. The S-Lang language requires the programmer to explicitly handle any value returned by a S-Lang function. The simplest way to handle the return value from `fclose' is to use it as: () = fclose (fp); SEE ALSO fopen, fgets, fflush, errno -------------------------------------------------------------- fflush SYNOPSIS Flush an output stream USAGE Integer_Type fflush (File_Type fp) DESCRIPTION The `fflush' function may be used to update the _output_ stream specified by `fp'. It returns `0' upon success, or `-1' upon failure and sets `errno' accordingly. In particular, this function will fail if `fp' does not represent an output stream, or if `fp' is associated with a disk file and there is insufficient disk space. EXAMPLE This example illustrates how to use the `fflush' function without regard to the return value: () = fputs ("Enter value> ", stdout); () = fflush (stdout); NOTES Many C programmers disregard the return value from the `fflush' function. The above example illustrates how to properly do this in the S-Lang langauge. SEE ALSO fopen, fclose -------------------------------------------------------------- fgets SYNOPSIS Read a line from a file. USAGE Integer_Type fgets (SLang_Ref_Type ref, File_Type fp) DESCRIPTION `fgets' reads a line from the open file specified by `fp' and places the characters in the variable whose reference is specified by `ref'. It returns `-1' if `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: 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; } SEE ALSO fopen, fclose, fputs, error -------------------------------------------------------------- fopen SYNOPSIS Open a file USAGE File_Type fopen (String_Type f, String_Type m) DESCRIPTION The `fopen' function opens a file `f' according to the mode string `m'. Allowed values for `m' are: "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. In addition, the mode string can also include the letter `'b'' as the last character to indicate that the file is to be opened in binary mode. Upon success, `fopen' a `File_Type' object which is meant to be used in other operations that require an open file. Upon failure, the function returns `NULL'. EXAMPLE The following function opens a file in append mode and writes a string to it: 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); } Note that the return values from `fputs' and `fclose' are ignored. NOTES There is no need to explicitly close a file opened with `fopen'. If the returned `File_Type' object goes out of scope, S-Lang will automatically close the file. However, explicitly closing a file after use is recommended. SEE ALSO fclose, fgets, fputs -------------------------------------------------------------- fputs SYNOPSIS Write a string to an open stream USAGE Integer_Type fputs (String_Type s, File_Type fp); DESCRIPTION The `fputs' function writes the string `s' to the open file pointer `fp'. It returns -1 upon failure and sets `errno', otherwise it returns the length of the string. EXAMPLE The following function opens a file in append mode and uses the `fputs' function to write to it. 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); } NOTES One must not disregard the return value from the `fputs' function, as many C programmers do. Doing so may lead to a stack overflow error. SEE ALSO fclose, fopen, fgets -------------------------------------------------------------- getcwd SYNOPSIS Get the current working directory USAGE String_Type getcwd () DESCRIPTION The `getcwd' function returns the absolute pathname of the current working directory. If an error occurs or it cannot determine the working directory, it returns `NULL' and sets `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. SEE ALSO mkdir, chdir, errno -------------------------------------------------------------- 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 `get_doc_string_from_file' opens the documentation file `f' and searches it for topic `t'. It returns the documentation for `t' upon success, otherwise it returns `NULL' upon error. It will fail if `f' could not be opened or does not contain documentation for the topic. SEE ALSO stat_file -------------------------------------------------------------- getenv SYNOPSIS Get the value of an environment variable USAGE String_Type getenv(String_Type var) DESCRIPTION The `getenv' function returns a string that represents the value of an environment variable `var'. It will return `NULL' if there is no environment variable whose name is given by `var'. EXAMPLE if (NULL != getenv ("USE_COLOR")) { set_color ("normal", "white", "blue"); set_color ("status", "black", "gray"); USE_ANSI_COLORS = 1; } SEE ALSO putenv, strlen, is_defined -------------------------------------------------------------- init_char_array SYNOPSIS Initialize an array of characters USAGE init_char_array (Array_Type a, String_Type s) DESCRIPTION The `init_char_array' function may be used to initialize a character array `a' by settting the elements of the array `a' to the corresponding characters of the string `s'. EXAMPLE The statements variable a = Char_Type [10]; init_char_array (a, "HelloWorld"); creates an character array and initializes its elements to the characters in the string `"HelloWorld"'. NOTES The character array must be large enough to hold all the characters of the initialization string. SEE ALSO strlen, strcat -------------------------------------------------------------- integer SYNOPSIS Convert a string to an integer USAGE Integer_Type integer (String_Type s) DESCRIPTION The `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 `integer ("1234")' returns the integer value `1234'. NOTES This function operates only on strings and is not the same as the more general `typecast' operator. SEE ALSO typecast, _slang_guess_type, string, sprintf, char -------------------------------------------------------------- int SYNOPSIS Typecast an object to an integer USAGE int (s) DESCRIPTION This function performs a typecast of `s' from its data type to an object of `Integer_Type'. If `s' is a string, it returns returns the ascii value value of the first character of the string `s'. If `s' is `Double_Type', `int' truncates the number to an integer and returns it. EXAMPLE `int' can be used to convert single character strings to integers. As an example, the intrinsic function `isdigit' may be defined as define isdigit (s) { if ((int (s) >= '0') and (int (s) <= '9')) return 1; return 0; } NOTES This function is equalent to `typecast (s, Integer_Type)'; SEE ALSO typecast, double, integer, char, isdigit -------------------------------------------------------------- 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 `obj' has been defined. If `obj' is not defined, the function returns 0. Otherwise, it returns a non-zero value that defpends on the type of object `obj' represents. Specifically, it returns one of the following values: +1 if an intrinsic function +2 if user defined function -1 if intrinsic variable -2 if user defined variable 0 if undefined EXAMPLE For example, consider the function: define runhooks (hook) { if (2 == is_defined(hook)) eval(hook); } This function could be called from another S-Lang 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. SEE ALSO typeof, eval, autoload -------------------------------------------------------------- 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 `is_list_element' function may be used to determine whether or not a delimited list of strings, `list', contains the element `elem'. If `elem' is not an element of `list', the function will return zero, otherwise, it returns 1 plus the matching element number. EXAMPLE The expression is_list_element ("element 0, element 1, element 2", "0,", ' '); returns `2' since `"0,"' is element number one of the list (numbered from zero). SEE ALSO extract_element, is_substr, create_delimited_string -------------------------------------------------------------- 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 `a' contains the string `b'. If it does not, the function returns 0; otherwise it returns the position of the first occurance of `b' in `a'. NOTES It is important to remember that the first character of a string corresponds to a position value of `1'. SEE ALSO substr, string_match, str_replace -------------------------------------------------------------- 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 `s' is a digit; otherwise, it returns zero. EXAMPLE A simple, user defined implementation of `isdigit' is define isdigit (s) { return ((s[0] <= '9') and (s[0] >= '0')); } However, the intrinsic function `isdigit' executes many times faster than the equivalent representation defined above. NOTES Unlike the C function with the same name, the S-Lang function takes a string argument. SEE ALSO int, integer -------------------------------------------------------------- lstat_file SYNOPSIS Get information about a symbolic link USAGE Struct_Type lstat_file (String_Type file) DESCRIPTION The `lstat_file' function behaves identically to `stat_file' but if `file' is a symbolic link, `lstat_file' returns information about the link itself, and not the file that it references. See the documentation for `stat_file' for more information. NOTES On systems that do not support symbolic links, there is no difference between this function and the `stat_file' function. SEE ALSO stat_file -------------------------------------------------------------- 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 `eval' function. The resulting string is identical to `str' except that it is enclosed in double quotes and the backslash, newline, and double quote characters are expanded. SEE ALSO eval, str_quote_string -------------------------------------------------------------- message SYNOPSIS Print a string onto the message device USAGE message (String_Type s DESCRIPTION The `message' function will print the string specified by `s' onto the message device. EXAMPLE define print_current_time () { message (time ()); } NOTES The message device will depend upon the application. For example, the output message device for the `jed' editor correspond to the line at the bottom of the display window. The default message device is the standard output device. SEE ALSO vmessage, sprintf, error -------------------------------------------------------------- mkdir SYNOPSIS Create a new directory USAGE Integer_Type mkdir (String_Type dir, Integer_Type mode) DESCRIPTION The `mkdir' function creates a directory whose name is specified by the `dir' parameter with permissions specified by `mode'. Upon success `mkdir' returns zero, or it returns `-1' and sets `errno' accordingly. In particular, if the directory already exists, the function will fail and set errno to `EEXIST'. EXAMPLE define my_mkdir (dir) { if (0 == mkdir (dir, 0777)) return; if (errno == EEXIST) return; verror ("mkdir %s failed: %s", dir, errno_string (errno)); } NOTES The `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. SEE ALSO rmdir, getcwd, chdir, fopen, errno -------------------------------------------------------------- polynom SYNOPSIS Evaluate a polynomial USAGE Double_Type polynom(Double_Type a, b, ...c, Integer_Type n, Double_Type x) DESCRIPTION The `polynom' function returns the value of the polynomial expression: ax^n + bx^(n - 1) + ... c NOTES The `polynom' function should be extended to work with complex and array data types. The current implementation is limited to `Double_Type' quantities. SEE ALSO exp -------------------------------------------------------------- putenv SYNOPSIS Add or change an environment variable USAGE putenv (String_Type s) DESCRIPTION This functions adds string `s' to the environment. Typically, `s' should of the form `"name=value"'. The function signals a S-Lang error upon failure. NOTES This function is not available on all systems. SEE ALSO getenv, sprintf -------------------------------------------------------------- reshape SYNOPSIS Reshape an array USAGE reshape (Array_Type A, Array_Type I DESCRIPTION The `reshape' function changes the size of a to have the size specified by the 1-d integer array `I'. The elements of `I' specify the new dimensions of `A' and must be consistent with the number of elements `A'. EXAMPLE If `A' is a `100' element 1-d array, it can be changed to a 2-d `20' by `5' array via reshape (A, [20, 5]); However, `reshape(A, [11,5])' will result in an error because the the `[11,5]' array specifies `55' elements. SEE ALSO array_info -------------------------------------------------------------- set_float_format SYNOPSIS Set the format for printing floating point values. USAGE set_float_format (String_Type fmt) DESCRIPTION The `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 `string' function. The default value is `"%f"' EXAMPLE 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" SEE ALSO string, sprintf, double -------------------------------------------------------------- Sprintf SYNOPSIS Format objects into a string USAGE String_Type Sprintf (String_Type format, ..., Integer_Type n) DESCRIPTION `Sprintf' formats a string from `n' objects according to `format'. Unlike `sprintf', the `Sprintf' function requires the number of items to format. EXAMPLE s = Sprintf("%f is greater than %f but %s is better than %s\n", PI, E, "Cake" "Pie", 4); The final argument to `Sprintf' is the number of items to format; in this case, there are 4 items. SEE ALSO sprintf, string -------------------------------------------------------------- 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 S-Lang function `Sprintf' in that it does not require the number of items to format. See the documentation for `Sprintf' for more information. SEE ALSO Sprintf, string, vmessage -------------------------------------------------------------- stat_file SYNOPSIS Get information about a file USAGE Struct_Type stat_file (String_Type file) DESCRIPTION The `stat_file' function returns information about `file' through the use of the system `stat' call. If the stat call fails, the function returns `NULL' and sets errno accordingly. If it is successful, it returns a stat structure with the following integer fields: st_dev st_ino st_mode st_nlink st_uid st_gid st_rdev st_size st_atime st_mtime st_ctime See the man page for `stat' for a discussion of these fields. EXAMPLE The following example shows how the `stat_file' function may be used to get the size of a file: define file_size (file) { variable st; st = stat_file(file); if (st == NULL) verror ("Unable to stat %s", file); return st.st_size; } SEE ALSO lstat_file, stat_is -------------------------------------------------------------- stat_is SYNOPSIS Parse the var{st_mode USAGE Integer_Type stat_is (String_Type type, Integer_Type st_mode DESCRIPTION The `stat_is' function returns an integer value about the type of file specified by `st_mode'. Specifically, `type' must be one of the strings: "sock" (socket) "fifo" (fifo) "blk" (block device) "chr" (character device) "reg" (regular file) "lnk" (link) "dir" (dir) It returns a non-zero value if `st_mode' corresponds to `type'. EXAMPLE The following example illustrates how to use the `stat_is' function to determine whether or not a file is a directory: define is_directory (file) { variable st; st = stat_file (file); if (st == NULL) return 0; return stat_is ("dir", st.st_mode); } SEE ALSO stat_file, lstat_file -------------------------------------------------------------- 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 `str_quote_string' returns a string identical to `str' except that all characters in the set specified by the string `qlis' are escaped with the `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 node = "Is it [the coat] really worth $100?"; tag = str_quote_string (node, "\\^$[]*.+?", '\\'); will result in `tag' having the value: Is it \[the coat\] really worth \$100\? SEE ALSO str_uncomment_string, make_printable_string -------------------------------------------------------------- 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 `str_replace' function replaces the first occurance of `b' in `a' with `c' and returns an integer that indicates whether a replacement was made or not. If `b' does not occur in `a', zero is returned. However, if `b' occurs in `a', a non-zero integer is returned as well as the new string resulting from the replacement. EXAMPLE define str_replace_all (orig, match, replacement) { while (str_replace (orig, match, replacement)) orig = (); return orig; } is a function that replaces all occurances in a string. SEE ALSO is_substr, strsub, strtrim -------------------------------------------------------------- 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 `s'. The parameters, `beg' and `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 str_uncomment_string ("Hello (testing) 'example' World", "'(", "')") returns the string `"Hello World"'. NOTES This routine does not handle multicharacter comment delimiters and it assumes that comments are not nested. SEE ALSO str_quote_string -------------------------------------------------------------- strcat SYNOPSIS Concatenate two strings USAGE String_Type strcat (String_Type a, String_Type b) DESCRIPTION The `strcat' function takes two string valued quantities, `a' and `b', concatenates them together and returns the result. EXAMPLE strcat ("Hello ", "World"); produces the string `"Hello World"'. NOTES This function is equivalent to the binary operation `a+b'. SEE ALSO sprintf, create_delimited_string -------------------------------------------------------------- strchopr SYNOPSIS Chop or split a string into substrings. USAGE Integer_Type strchopr (String_Type str, String_Type delim, String_Type quote) DESCRIPTION This routine performs exactly the same function as `strchop' except that it returns the substrings in the reverse order. See the documentation for `strchop' for more information. SEE ALSO strchop, extract_element -------------------------------------------------------------- strchop SYNOPSIS Chop or split a string into substrings. USAGE Integer_Type strchop (String_Type str, Integer_Type delim, Integer_Type quote) DESCRIPTION The `strchop' function may be used to split-up a string `str' that consists of substrings delimited by the character specified by `delim'. If the integer `quote' is non-zero, it will be taken as a quote character for the delimiter. The function returns to the stack a variable number of objects. The top stack object represents the number of substrings that are on the stack. For example, strchop ("apples,oranges,pears", ',', 0); will return the integer `3' to the top of the stack followed by the three strings: `"apples"', `"oranges"', and `"pears"'. EXAMPLE define list_to_array (list) { variable n, i, s, a; n = strchop (list, ',', '\\'); a = String_Type [n]; for (i = 0; i < n; i++) a[i] = (); % substring is on stack return a; } This defines a function that converts a comma-separated list of strings to string array containing the substrings. NOTES Since this function returns a variable number of values to the stack, it cannot chop up arbitrarily long strings that consist of many substrings. The function `strchopr' should be used if it is desired to have the string chopped-up in the reverse order. SEE ALSO strchopr, extract_element, create_delimited_string -------------------------------------------------------------- strcmp SYNOPSIS Compare two strings USAGE Interpret strcmp (String_Type a, String_Type b) DESCRIPTION The `strcmp' function may be used to perform a case-sensitive string comparison, in the lexicongraphic sense, on strings `a' and `b'. It returns 0 if the strings are identical, a negative integer if `a' is less than `b', or a positive integer if `a' is greater than `b'. EXAMPLE The `strup' function may be used to perform a case-insensitive string comparison: define case_insensitive_strcmp (a, b) { return strcmp (strup(a), strup(b)); } NOTES One may also use one of the binary comparison operators, e.g., `a > b'. SEE ALSO strup, strncmp -------------------------------------------------------------- strcompress SYNOPSIS Remove excess whitespace characters from a string USAGE String_Type strtrim (String_Type s, String_Type white) DESCRIPTION The `strcompress' function compresses the string `s' by removing all repeated characters specified by by the characters of `white' from the interior of `s'. In addition, it also removes all leading and trailing characters from `s' that are part of `white'. EXAMPLE The expression strcompress (",;apple,,cherry;,banana", ",;"); returns the string @"apple,cherry;banana"@. SEE ALSO strtrim -------------------------------------------------------------- string_match_nth SYNOPSIS Get the result of the last call to var{string_match USAGE (Integer_Type, Integer_Type) string_match_nth(Integer_Type nth) DESCRIPTION The `string_match_nth' function returns two integers describing the result of the last call to `string_match'. It returns both the offset into the string and the length of characters matches by the `nth' submatch. By convention, `nth' equal to zero means the entire match. Otherwise, `nth' must be an integer with a value 1 through 9, and refers to the set of characters matched by the `nth' regular expression enclosed by the pairs `\(, \)'. EXAMPLE Consider: variable matched, pos, len; matched = string_match("hello world", "\\([a-z]+\\) \\([a-z]+\\)", 1); if (matched) (pos, len) = string_match_nth(2); This will set `matched' to 1 since a match will be found at the first position, `pos' to 6 since `w' is offset 6 characters from the beginning of the string, and `len' to 5 since `"world"' is 5 characters long. NOTES The position offset is _not_ affected by the value of the offset parameter to the `string_match' function. For example, if the value of the last parameter to the `string_match' function had been 3, `pos' would still have been set to 6. Note also that `string_match_nth' returns the _offset_ from the beginning of the string and not the position of the match. SEE ALSO string_match -------------------------------------------------------------- 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 `string_match' function returns zero if `str' does not match regular expression specified by `pat'. This function performs the match starting at position `pos' (numbered from 1) in `str'. This function returns the position of the start of the match. To find the exact substring actually matched, use `string_match_nth'. SEE ALSO string_match_nth, strcmp, strncmp -------------------------------------------------------------- string SYNOPSIS Convert an object to a string representation. USAGE Integer_Type string (obj) DESCRIPTION The `string' function may be used to convert an object `obj' of any type to a string representation. For example, `string(12.34)' returns `"12.34"'. EXAMPLE define print_anything (anything) { message (string (anything)); } NOTES This function is _not_ the same as typecasting to a `String_Type' using the `typecast' function. SEE ALSO typecast, sprintf, integer, char -------------------------------------------------------------- strlen SYNOPSIS Compute the length of a string USAGE Integer_Type strlen (String_Type a) DESCRIPTION The `strlen' function may be used to compute the length of a string. EXAMPLE After execution of variable len = strlen ("hello"); `len' will have a value of `5'. SEE ALSO substr -------------------------------------------------------------- strlow SYNOPSIS Convert a string to lowercase USAGE String_Type strlow (String_Type s) DESCRIPTION The `strlow' function takes a string `s' and returns another string identical to `s' except that all upper case characters that comprise `s' will be converted to lower case. EXAMPLE The function define Strcmp (a, b) { return strcmp (strlow (a), strlow (b)); } performs a case-insensitive comparison operation of two strings by converting them to lower case first. SEE ALSO strup, tolower, strcmp, strtrim, define_case -------------------------------------------------------------- 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 `strcmp' except that it compares only the first `n' characters in the strings `a' and `b'. See the documentation for `strcmp' for information about the return value. EXAMPLE The expression strcmp ("apple", "appliance", 3); will return zero since the first three characters match. SEE ALSO strcmp, strlen -------------------------------------------------------------- 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 `strsub' character may be used to substitute the character `ch' for the character at position `pos' of the string `s'. The resulting string is returned. EXAMPLE define replace_spaces_with_comma (s) { variable n; while (n = is_substr (s, " "), n) s = strsub (s, n, ','); return s; } NOTES The first character in the string `s' is specified by `pos' equal to 1. SEE ALSO is_substr, str_replace, strlen -------------------------------------------------------------- strtrim SYNOPSIS Remove whitespace from the ends of a string USAGE String_Type strtrim (String_Type s) DESCRIPTION The `strtrim' function removes all leading and trailing whitespace characters from the string `s' and returns the result. Whitespace is defined to be any combination of spaces, tabs, and newline characters. SEE ALSO int, strlow, strup, strcompress -------------------------------------------------------------- strup SYNOPSIS Convert a string to uppercase USAGE String_Type strup (String_Type s) DESCRIPTION The `strup' function takes a string `s' and returns another string identical to `s' except that all lower case characters that comprise `s' will be converted to upper case. EXAMPLE The function define Strcmp (a, b) { return strcmp (strup (a), strup (b)); } performs a case-insensitive comparison operation of two strings by converting them to upper case first. SEE ALSO strlow, toupper, strcmp, strtrim, define_case -------------------------------------------------------------- substr SYNOPSIS Extract a substring from a string USAGE String_Type substr (String_Type s, Integer_Type n, Integer_Type len) DESCRIPTION The `substr' function returns a substring with length `len' of the string `s' beginning at position `n'. If `len' is `-1', the entire length of the string `s' will be used for `len'. The first character of `s' is given by `n' equal to 1. EXAMPLE substr ("To be or not to be", 7, 5); returns `"or no"' NOTES The expression `substr(s, n, 1)' is equivalent to the array index expression `s[n-1]'. SEE ALSO is_substr, strlen -------------------------------------------------------------- system SYNOPSIS Execute a shell command USAGE Integer_Type system (String_Type cmd) DESCRIPTION The `system' function may be used to execute the string expression `cmd' in an inferior shell. This function is an interface to the C `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 `cmd'. EXAMPLE define dir () { () = system ("DIR"); } displays a directory listing of the current directory under MSDOS or VMS. -------------------------------------------------------------- time SYNOPSIS Return the current data and time as a string USAGE String time (); DESCRIPTION This function returns the current time as a string of the form: Sun Apr 21 13:34:17 1996 SEE ALSO message, substr -------------------------------------------------------------- tolower SYNOPSIS Convert a character to lowercase. USAGE Integer_Type lower (Integer_Type ch) DESCRIPTION This function takes an integer `ch' and returns its lowercase equivalent. SEE ALSO toupper, strup, strlow, int, char, define_case -------------------------------------------------------------- toupper SYNOPSIS Convert a character to uppercase. USAGE Integer_Type toupper (Integer_Type ch) DESCRIPTION This function takes an integer `ch' and returns its uppercase equivalent. SEE ALSO tolower, strup, strlow, int, char, define_case -------------------------------------------------------------- typecast SYNOPSIS Convert an object from one data type to another. USAGE typecast (x, new_type) DESCRIPTION The `typecast' function performs a generic typecast operation on `x' to convert it to `new_type'. If `x' represents an array, the function will attempt to convert all elements of `x' to `new_type'. Not all objects can be converted and a type-mismatch error will result upon failure. EXAMPLE define to_complex (x) { return typecast (x, Complex_Type); } defines a function that converts its argument, `x' to a complex number. SEE ALSO int, double, typeof -------------------------------------------------------------- typeof SYNOPSIS Get the data type of an object. USAGE DataType_Type typeof (x) DESCRIPTION This function returns the data type of `x'. EXAMPLE if (Integer_Type == typeof (x)) print ("x is an integer"); SEE ALSO array_info, _slang_guess_type, typecast -------------------------------------------------------------- unix_ctime SYNOPSIS Convert a calendar time to a string USAGE String_Type unix_ctime(Integer_Type secs) DESCRIPTION This function returns a string representation of the time as given by `secs' seconds since 1970. SEE ALSO time -------------------------------------------------------------- unix_kill SYNOPSIS Send a signal to a process USAGE Integer_Type unix_kill (Integer_Type pid, Integer_Type sig) DESCRIPTION This function may be used to send a signal given by the integer `sig' to the process specified by `pid'. The function returns zero upon sucess and `-1' upon failure setting errno accordingly. EXAMPLE The `unix_kill' function may be used to determine whether or not a specific process exists: define process_exists (pid) { if (-1 == unix_kill (pid, 0)) return 0; % Process does not exist return 1; } NOTES The `unix_kill' function is not available on all systems. SEE ALSO getpid -------------------------------------------------------------- verror SYNOPSIS Generate an error condition USAGE verror (String_Type fmt, ...) DESCRIPTION The `verror' function performs the same role as the `error' function. The only difference is that instead of a single string argument, `verror' takes a sprintf style argument list. EXAMPLE define open_file (file) { variable fp; fp = fopen (file, "r"); if (fp == NULL) verror ("Unable to open %s", file); return fp; } NOTES In the current implementation, strictly speaking, the `verror' function is not an intrinsic function. Rather it is a predefined S-Lang function using a combination of `Sprintf' and `error'. SEE ALSO error, Sprintf, vmessage --------------------------------------------------------------