[Pkg-jed-commit] r18 - trunk/packages/jed/debian
Rafael Laboissiere
rafael@costa.debian.org
Wed, 16 Mar 2005 13:54:31 +0100
Author: rafael
Date: 2005-03-16 13:54:31 +0100 (Wed, 16 Mar 2005)
New Revision: 18
Removed:
trunk/packages/jed/debian/jed_0.99.16-4.diff
Log:
Removed obsolete file
Deleted: trunk/packages/jed/debian/jed_0.99.16-4.diff
===================================================================
--- trunk/packages/jed/debian/jed_0.99.16-4.diff 2005-03-16 12:54:00 UTC (rev 17)
+++ trunk/packages/jed/debian/jed_0.99.16-4.diff 2005-03-16 12:54:31 UTC (rev 18)
@@ -1,5952 +0,0 @@
---- jed-0.99.16.orig/doc/manual/jed.1
-+++ jed-0.99.16/doc/manual/jed.1
-@@ -30,44 +30,44 @@
- provides brief tutorial.
- .SH OPTIONS
- .LP
--.I -batch
-+.I \-batch
- .RS
- run Jed in batch mode.
- This is a non-interactive mode.
- .RE
--.I -n
-+.I \-n
- .RS
- do not load
- .I .jedrc
- file.
- .RE
--.I -g 'n'
-+.I \-g 'n'
- .RS
- goto line
- .I n
- in buffer
- .RE
--.I -l 'file'
-+.I \-l 'file'
- .RS
- load
- .I file
- as S-Lang code.
- .RE
--.I -f 'function'
-+.I \-f 'function'
- .RS
- execute S-Lang function named
- .I function
- .RE
--.I -s 'string'
-+.I \-s 'string'
- .RS
- search forward for
- .I string
- .RE
--.I -2
-+.I \-2
- .RS
- split window
- .RE
--.I -i 'file'
-+.I \-i 'file'
- .RS
- insert
- .I file
---- jed-0.99.16.orig/doc/manual/rgrep.1
-+++ jed-0.99.16/doc/manual/rgrep.1
-@@ -29,65 +29,65 @@
- this results in very poor performance.
- .SH COMMAND LINE OPTIONS
- .LP
--.I -?
-+.I \-?
- .RS
--additional help (use '-?' to avoid shell expansion on some systems)
-+additional help (use '\-?' to avoid shell expansion on some systems)
- .RE
--.I -c
-+.I \-c
- .RS
- count matches
- .RE
--.I -h
-+.I \-h
- .RS
- highlight match (ANSI compatable terminal assumed)
- .RE
--.I -H
-+.I \-H
- .RS
- Output match instead of entire line containing match
- .RE
--.I -i
-+.I \-i
- .RS
- ignore case
- .RE
--.I -l
-+.I \-l
- .RS
- list filename only
- .RE
--.I -n
-+.I \-n
- .RS
- print line number of match
- .RE
--.I -F
-+.I \-F
- .RS
- follow links
- .RE
--.I -r
-+.I \-r
- .RS
- recursively scan through directory tree
- .RE
--.I -N
-+.I \-N
- .RS
- Do NOT perform a recursive search
- .RE
--.I -R 'pat'
-+.I \-R 'pat'
- .RS
--like '-r' except that only those files matching 'pat' are checked
-+like '\-r' except that only those files matching 'pat' are checked
- .RE
--.I -v
-+.I \-v
- .RS
- print only lines that do NOT match the specified pattern
- .RE
--.I -x 'ext'
-+.I \-x 'ext'
- .RS
- checks only files with extension given by 'ext'.
- .RE
--.I -D
-+.I \-D
- .RS
- Print all directories that would be searched. This option is for
- debugging purposes only. No file is grepped with this
- option.
- .RE
--.I -W 'len'
-+.I \-W 'len'
- .RS
- lines are 'len' characters long (not newline terminated).
- .RE
-@@ -130,14 +130,14 @@
- .RS
- matches any single character between brackets.
- For example,
--.I [-02468]
-+.I [\-02468]
- matches
--.I '-'
-+.I '\-'
- or any even digit.
- and
--.I [-0-9a-z]
-+.I [\-0\-9a\-z]
- matches
--.I '-'
-+.I '\-'
- and any digit between
- .I 0
- and
-@@ -159,7 +159,7 @@
- .I '\\\\( ... \\\\)'
- expression.
- For example,
--.I '\\\\([\ \\\\t][a-zA-Z]+\\\\)\\\\1[\ \\\\t]'
-+.I '\\\\([\ \\\\t][a\-zA\-Z]+\\\\)\\\\1[\ \\\\t]'
- matches any
- word repeated consecutively.
- .RE
-@@ -172,16 +172,16 @@
- printing the line containing the match with its line number: (two
- methods)
- .LP
--.I rgrep -n -R '*.c' '^int ' .
-+.I rgrep \-n \-R '*.c' '^int ' .
- .LP
--.I rgrep -n -x c '^int ' .
-+.I rgrep \-n \-x c '^int ' .
- .LP
- Highlight all matches of repeated words in file 'paper.tex':
- .LP
--.I rgrep -h
--.I '[\ \\\\t]\\\\([a-zA-Z]+\\\\)[\ \\\\t]+\\\\1[\ \\\\t\\\\n]' paper.tex
-+.I rgrep \-h
-+.I '[\ \\\\t]\\\\([a\-zA\-Z]+\\\\)[\ \\\\t]+\\\\1[\ \\\\t\\\\n]' paper.tex
- .LP
--.I rgrep -h '^\\\\([a-zA-Z]+\\\\)[\ \\\\t]+\\\\1[\ \\\\t\\\\n]' paper.tex
-+.I rgrep \-h '^\\\\([a\-zA\-Z]+\\\\)[\ \\\\t]+\\\\1[\ \\\\t\\\\n]' paper.tex
- .LP
- (Note that this version of rgrep requires two
- passes for this example)
-@@ -190,14 +190,14 @@
- looking
- for the string 'mouse' without regard to case:
- .LP
--.I rgrep -i -R '*.[^ao]' mouse /usr/src/linux
-+.I rgrep \-i \-R '*.[^ao]' mouse /usr/src/linux
- .LP
- Search a fixed record length FITS file for the keyword EXTNAME:
- .LP
--.I rgrep -W80 ^EXTNAME file.fits
-+.I rgrep \-W80 ^EXTNAME file.fits
- .LP
- (Note that the regular expression
--.I '^[A-Z]+'
-+.I '^[A\-Z]+'
- will dump all fits headers.)
- .SH AUTHOR
- .LP
---- jed-0.99.16.orig/doc/txt/slangfun.txt
-+++ jed-0.99.16/doc/txt/slangfun.txt
-@@ -0,0 +1,5604 @@
-+_reshape
-+
-+ SYNOPSIS
-+ Copy an array to a new shape
-+
-+ USAGE
-+ Array_Type _reshape (Array_Type A, Array_Type I)
-+
-+ DESCRIPTION
-+ The `_reshape' function creates a copy of an array `A',
-+ reshapes it to the form specified by `I' and returns the result.
-+ The elements of `I' specify the new dimensions of the copy of
-+ `A' and must be consistent with the number of elements `A'.
-+
-+ EXAMPLE
-+ If `A' is a `100' element 1-d array, a new array 2-d array of
-+ size `20' by `5' may be created from the elements of `A'
-+ by
-+
-+ A = _reshape (A, [20, 5]);
-+
-+ In this example, the original array was no longer needed. Hence, it
-+ is preferable to make use of the `__tmp' operator to avoid the
-+ creation of a new array, i.e.,
-+
-+ A = _reshape (__tmp(A), [20,5]);
-+
-+
-+ NOTES
-+ The `reshape' function performs a similar function to
-+ `_reshape'. In fact, the `_reshape' function could have been
-+ implemented via:
-+
-+ define _reshape (a, i)
-+ {
-+ a = @a; % Make a new copy
-+ reshape (a, i);
-+ return a;
-+ }
-+
-+
-+ SEE ALSO
-+ reshape, array_info
-+--------------------------------------------------------------
-+
-+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];
-+ }
-+
-+ For 1-d arrays, this information is more easily obtained from the
-+ `length' function.
-+
-+ SEE ALSO
-+ typeof, reshape, length, _reshape
-+--------------------------------------------------------------
-+
-+array_map
-+
-+ SYNOPSIS
-+ Apply a function to each element of an array
-+
-+ USAGE
-+ Array_Type array_map (type, func, arg0, ...)
-+
-+ DataType_Type type;
-+ Ref_Type func;
-+
-+
-+ DESCRIPTION
-+ The `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 `type' parameter indicates what kind of
-+ array should be returned and generally corresponds to the return
-+ type of the function. The `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 `strlen' function
-+ to an array of strings:
-+
-+ S = ["", "Train", "Subway", "Car"];
-+ L = array_map (Integer_Type, &strlen, S);
-+
-+ This is equivalent to:
-+
-+ S = ["", "Train", "Subway", "Car"];
-+ L = Integer_Type [length (S)];
-+ for (i = 0; i < length (S); i++) L[i] = strlen (S[i]);
-+
-+
-+ Now consider an example involving the `strcat' function:
-+
-+ 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"];
-+
-+
-+ NOTES
-+ Many mathemetical functions already work transparantly on arrays.
-+ For example, the following two statements produce identical results:
-+
-+ B = sin (A);
-+ B = array_map (Double_Type, &sin, A);
-+
-+
-+ SEE ALSO
-+ array_info, strlen, strcat, sin
-+--------------------------------------------------------------
-+
-+array_sort
-+
-+ SYNOPSIS
-+ Sort an array
-+
-+ USAGE
-+ Array_Type array_sort (Array_Type a [, String_Type or Ref_Type f])
-+
-+ DESCRIPTION
-+ `array_sort' sorts the array `a' into ascending order and
-+ returns an integer array that represents the result of the sort. If
-+ the optional second parameter `f' is present, the function
-+ specified by `f' will be used to compare elements of `a';
-+ otherwise, a built-in sorting function will be used.
-+
-+ If `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 `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.
-+
-+ If the comparision function is not specified, then a built-in comparison
-+ function appropriate for the data type will be used. For example,
-+ if `a' is an array of character strings, then the sort will be
-+ preformed using `strcmp'.
-+
-+ 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);
-+
-+ Alternatively, one may use
-+
-+ variable I = array_sort (A);
-+
-+ to use the built-in comparison function.
-+
-+ 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]'.
-+
-+ SEE ALSO
-+ strcmp
-+--------------------------------------------------------------
-+
-+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 setting 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
-+ bstring_to_array, strlen, strcat
-+--------------------------------------------------------------
-+
-+length
-+
-+ SYNOPSIS
-+ Get the length of an object
-+
-+ USAGE
-+ Integer_Type length (obj)
-+
-+ DESCRIPTION
-+ The `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 `obj' is a string, `length' returns 1 because a
-+ `String_Type' object is considered to be a scalar. To get the
-+ number of characters in a string, use the `strlen' function.
-+
-+ SEE ALSO
-+ array_info, typeof, strlen
-+--------------------------------------------------------------
-+
-+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.
-+
-+ NOTES
-+ Since `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
-+ `_reshape' function instead.
-+
-+ SEE ALSO
-+ _reshape, array_info
-+--------------------------------------------------------------
-+
-+transpose
-+
-+ SYNOPSIS
-+ Transpose a 2d array
-+
-+ USAGE
-+ Array_Type transpose (Array_Type a)
-+
-+ DESCRIPTION
-+ The `transpose' function returns the transpose of a specified
-+ array. By definition, the transpose of an array, say one with
-+ elements `a[i,j,...k]' is an array whose elements are
-+ `a[k,...,j,i]'.
-+
-+ SEE ALSO
-+ _reshape, reshape, array_info
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+assoc_delete_key
-+
-+ SYNOPSIS
-+ Delete a key from an Associative Array
-+
-+ USAGE
-+ assoc_delete_key (Assoc_Type a, String_Type k)
-+
-+ DESCRIPTION
-+ The `assoc_delete_key' function deletes a key given by `k'
-+ from the associative array `a'. If the specified key does not
-+ exist in `a', then this function has no effect.
-+
-+ SEE ALSO
-+ assoc_key_exists, assoc_get_keys
-+--------------------------------------------------------------
-+
-+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
-+ `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:
-+
-+ define get_num_elements (a)
-+ {
-+ return length (assoc_get_keys (a));
-+ }
-+
-+
-+ SEE ALSO
-+ assoc_get_values, assoc_key_exists, assoc_delete_key, length
-+--------------------------------------------------------------
-+
-+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
-+ `a' as an array of proper type. If the associative array
-+ contains no keys, an empty array will be returned.
-+
-+ EXAMPLE
-+ Suppose that `a' is an associative array of type
-+ `Integer_Type', i.e., it was created via
-+
-+ variable a = Assoc_Type[Integer_Type];
-+
-+ The the following may be used to print the values of the array in
-+ ascending order:
-+
-+ 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);
-+ }
-+ }
-+
-+
-+ SEE ALSO
-+ assoc_get_values, assoc_key_exists, assoc_delete_key, array_sort
-+--------------------------------------------------------------
-+
-+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 `assoc_key_exists' function may be used to determine whether
-+ or not a specified key `k' exists in an associative array `a'.
-+ It returns 1 if the key exists, or 0 if it does not.
-+
-+ SEE ALSO
-+ assoc_get_keys, assoc_get_values, assoc_delete_key
-+--------------------------------------------------------------
-+
-+array_to_bstring
-+
-+ SYNOPSIS
-+ Convert an array to a binary string
-+
-+ USAGE
-+ BString_Type array_to_bstring (Array_Type a)
-+
-+ DESCRIPTION
-+ The `array_to_bstring' function returns the elements of an
-+ array `a' as a binary string.
-+
-+ SEE ALSO
-+ bstring_to_array, init_char_array
-+--------------------------------------------------------------
-+
-+bstring_to_array
-+
-+ SYNOPSIS
-+ Convert a binary string to an array of characters
-+
-+ USAGE
-+ UChar_Type[] bstring_to_array (BString_Type b)
-+
-+ DESCRIPTION
-+ The `bstring_to_array' function returns an array of unsigned
-+ characters whose elements correspond to the characters in the
-+ binary string.
-+
-+ SEE ALSO
-+ array_to_bstring, init_char_array
-+--------------------------------------------------------------
-+
-+bstrlen
-+
-+ SYNOPSIS
-+ Get the length of a binary string
-+
-+ USAGE
-+ UInt_Type bstrlen (BString_Type s)
-+
-+ DESCRIPTION
-+ The `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
-+
-+ variable s = "hello\0";
-+ len = bstrlen (s); % ==> len = 6
-+ len = strlen (s); % ==> len = 5
-+
-+
-+ SEE ALSO
-+ strlen, length
-+--------------------------------------------------------------
-+
-+pack
-+
-+ SYNOPSIS
-+ Pack objects into a binary string
-+
-+ USAGE
-+ BString_Type pack (String_Type fmt, ...)
-+
-+ DESCRIPTION
-+ The `pack' function combines zero or more the objects (represented
-+ by the ellipses above) into a binary string acording to the format
-+ string `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:
-+
-+ 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
-+
-+ A decimal length specifier may follow the data-type specifier. With
-+ the exception of the `s' and `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 `s' or
-+ `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 `c', `C', `s', `S', and
-+ `x', each of these may be prefixed by a character that indicates
-+ the byte-order of the object:
-+
-+ > big-endian order (network order)
-+ < little-endian order
-+ = native byte-order
-+
-+ The default is to use native byte order.
-+
-+ When unpacking via the `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 `S' specifier.
-+
-+ EXAMPLE
-+
-+ 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"
-+
-+
-+ SEE ALSO
-+ unpack, sizeof_pack, pad_pack_format, sprintf
-+--------------------------------------------------------------
-+
-+pad_pack_format
-+
-+ SYNOPSIS
-+ Add padding to a pack format
-+
-+ USAGE
-+ BString_Type pad_pack_format (String_Type fmt)
-+
-+ DESCRIPTION
-+ The `pad_pack_format' function may be used to add the
-+ appropriate padding to the format `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.
-+
-+ SEE ALSO
-+ pack, unpack, sizeof_pack
-+--------------------------------------------------------------
-+
-+sizeof_pack
-+
-+ SYNOPSIS
-+ Compute the size implied by a pack format string
-+
-+ USAGE
-+ UInt_Type sizeof_pack (String_Type fmt)
-+
-+ DESCRIPTION
-+ The `sizeof_pack' function returns the size of the binary string
-+ represented by the format string `fmt'. This information may be
-+ needed when reading a structure from a file.
-+
-+ NOTES
-+
-+ SEE ALSO
-+ pack, unpack, pad_pack_format
-+--------------------------------------------------------------
-+
-+unpack
-+
-+ SYNOPSIS
-+ Unpack Objects from a Binary String
-+
-+ USAGE
-+ (...) = unpack (String_Type fmt, BString_Type s)
-+
-+ DESCRIPTION
-+ The `unpack' function unpacks objects from a binary string
-+ `s' according to the format `fmt' and returns the objects to
-+ the stack in the order in which they were unpacked. See the
-+ documentation of the `pack' function for details about the
-+ format string.
-+
-+ EXAMPLE
-+
-+ (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"
-+
-+
-+ SEE ALSO
-+ pack, sizeof_pack, pad_pack_format
-+--------------------------------------------------------------
-+
-+_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
-+--------------------------------------------------------------
-+
-+_debug_info
-+
-+ SYNOPSIS
-+ Configure debugging information
-+
-+ USAGE
-+ Integer_Type _debug_info
-+
-+ DESCRIPTION
-+ The `_debug_info' variable controls whether or not extra code
-+ should be generated for additional debugging and traceback
-+ information. Currently, if `_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 is local to each compilation unit and
-+ setting its value in one unit has no effect upon its value in other
-+ units.
-+
-+ EXAMPLE
-+
-+ _debug_info = 1; % Enable debugging information
-+
-+
-+ NOTES
-+ Setting this variable to a non-zero value may slow down the
-+ interpreter somewhat.
-+
-+ SEE ALSO
-+ _traceback, _slangtrace
-+--------------------------------------------------------------
-+
-+_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
-+--------------------------------------------------------------
-+
-+_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
-+--------------------------------------------------------------
-+
-+_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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+listdir
-+
-+ SYNOPSIS
-+ Get a list of the files in a directory
-+
-+ USAGE
-+ String_Type[] listdir (String_Type dir)
-+
-+ DESCRIPTION
-+ The `listdir' function returns the directory listing of all the
-+ files in the specified directory `dir' as an array of strings.
-+ It does not return the special files `".."' and `"."' as
-+ part of the list.
-+
-+ SEE ALSO
-+ stat_file, stat_is, length
-+--------------------------------------------------------------
-+
-+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, readlink
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+readlink
-+
-+ SYNOPSIS
-+ String_Type readlink (String_Type path)
-+
-+ USAGE
-+ Get the value of a symbolic link
-+
-+ DESCRIPTION
-+ The `readlink' function returns the value of a symbolic link and
-+ returns it as a string. Upon failure, NULL is returned and
-+ `errno' set accordingly.
-+
-+ NOTES
-+ Not all systems support this function.
-+
-+ SEE ALSO
-+ lstat_file, stat_file, stat_is
-+--------------------------------------------------------------
-+
-+remove
-+
-+ SYNOPSIS
-+ Delete a file
-+
-+ USAGE
-+ Integer_Type remove (String_Type file)
-+
-+ DESCRIPTION
-+ The `remove' function deletes a file. It returns 0 upon
-+ success, or -1 upon error and sets `errno' accordingly.
-+
-+ SEE ALSO
-+ rename, rmdir
-+--------------------------------------------------------------
-+
-+rename
-+
-+ SYNOPSIS
-+ Rename a file
-+
-+ USAGE
-+ Integer_Type rename (String_Type old, String_Type new)
-+
-+ DESCRIPTION
-+ The `rename' function renames a file from `old' to `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 `errno' accordingly.
-+
-+ SEE ALSO
-+ remove, errno
-+--------------------------------------------------------------
-+
-+rmdir
-+
-+ SYNOPSIS
-+ Remove a directory
-+
-+ USAGE
-+ Integer_Type rmdir (String_Type dir)
-+
-+ DESCRIPTION
-+ The `rmdir' function deletes a specified directory. It returns
-+ 0 upon success or -1 upon error and sets `errno' accordingly.
-+
-+ NOTES
-+ The directory must be empty before it can be removed.
-+
-+ SEE ALSO
-+ rename, remove, mkdir
-+--------------------------------------------------------------
-+
-+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
-+ Char_Type stat_is (String_Type type, Integer_Type st_mode)
-+
-+ DESCRIPTION
-+ The `stat_is' function returns a signed character 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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+get_import_module_path
-+
-+ SYNOPSIS
-+ Get the search path for dynamically loadable objects
-+
-+ USAGE
-+ String_Type get_import_module_path ()
-+
-+ DESCRIPTION
-+ The `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 `import' function.
-+
-+ SEE ALSO
-+ import, set_import_module_path
-+--------------------------------------------------------------
-+
-+import
-+
-+ SYNOPSIS
-+ Dynamically link to a specified module
-+
-+ USAGE
-+ import (String_Type module [, String_Type namespace])
-+
-+ DESCRIPTION
-+ The `import' function causes the run-time linker to dynamically
-+ link to the shared object specified by the `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
-+ `set_import_module_path' function. If not found, a search is
-+ performed along the paths given by the `SLANG_MODULE_PATH'
-+ environment variable. Finally, a system dependent search is
-+ performed (e.g., using the `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 `import' function is not available on all systems.
-+
-+ SEE ALSO
-+ set_import_module_path, use_namespace, current_namespace, getenv, evalfile
-+--------------------------------------------------------------
-+
-+set_import_module_path
-+
-+ SYNOPSIS
-+ Set the search path for dynamically loadable objects
-+
-+ USAGE
-+ set_import_module_path (String_Type path_list)
-+
-+ DESCRIPTION
-+ The `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 `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 `path_list'. For win32
-+ systems a semi-colon is used.
-+
-+ SEE ALSO
-+ import, get_import_module_path
-+--------------------------------------------------------------
-+
-+_NARGS
-+
-+ SYNOPSIS
-+ The number of parameters passed to a function
-+
-+ USAGE
-+ Integer_Type _NARGS
-+
-+ EXAMPLE
-+ This example uses the `_NARGS' variable to print the list of
-+ values passed to the function:
-+
-+ 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);
-+ }
-+ }
-+
-+
-+ SEE ALSO
-+ __pop_args, __push_args, typeof
-+--------------------------------------------------------------
-+
-+__get_defined_symbols
-+
-+ SYNOPSIS
-+ Get the symbols defined by the preprocessor
-+
-+ USAGE
-+ Integer_Type __get_defined_symbols ()
-+
-+ DESCRIPTION
-+ The `__get_defined_symbols' functions is used to get the list of
-+ all the symbols defined by the S-Lang preprocessor. It pushes each
-+ of the symbols on the stack followed by the number of items pushed.
-+
-+ SEE ALSO
-+ is_defined, _apropos
-+--------------------------------------------------------------
-+
-+__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 `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:
-+
-+ define zero ()
-+ {
-+ variable f;
-+ return __is_initialized (&f);
-+ }
-+
-+ will always return zero, but
-+
-+ define one ()
-+ {
-+ variable f = 0;
-+ return __is_initialized (&f);
-+ }
-+
-+ will return one.
-+
-+ NOTES
-+ It is easy to see why a reference to the variable must be passed to
-+ `__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.
-+
-+ SEE ALSO
-+ __get_reference, __uninitialize, is_defined, typeof, eval
-+--------------------------------------------------------------
-+
-+_apropos
-+
-+ SYNOPSIS
-+ Generate a list of functions and variables
-+
-+ USAGE
-+ Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags)
-+
-+ DESCRIPTION
-+ The `_apropos' function may be used to get a list of all defined
-+ objects in the namespace `ns' whose name matches the regular
-+ expression `s' and whose type matches those specified by
-+ `flags'. It returns an array of strings representing the
-+ matches.
-+
-+ 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, a;
-+ a = _apropos ("Global", s, 0xF);
-+
-+ vmessage ("Found %d matches:", length (a));
-+ foreach (a)
-+ {
-+ name = ();
-+ message (name);
-+ }
-+ }
-+
-+ prints a list of all matches.
-+
-+ NOTES
-+ If the namespace specifier `ns' is the empty string `""',
-+ then the namespace will default to the static namespace of the
-+ current compilation unit.
-+
-+ SEE ALSO
-+ is_defined, sprintf
-+--------------------------------------------------------------
-+
-+_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.
-+
-+ SEE ALSO
-+ _trace_function, is_defined
-+--------------------------------------------------------------
-+
-+_slang_doc_dir
-+
-+ SYNOPSIS
-+ Installed documentation directory
-+
-+ USAGE
-+ String_Type _slang_doc_dir;
-+
-+ DESCRIPTION
-+ The `_slang_doc_dir' variable is a read-only whose value
-+ specifies the installation location of the S-Lang documentation.
-+
-+ SEE ALSO
-+ get_doc_string_from_file
-+--------------------------------------------------------------
-+
-+_slang_version
-+
-+ SYNOPSIS
-+ The S-Lang library version number
-+
-+ USAGE
-+ Integer_Type _slang_version
-+
-+ DESCRIPTION
-+ The `_slang_version' variable is read-only and and whose
-+ value represents the number of the S-Lang library.
-+
-+ SEE ALSO
-+ _slang_version_string
-+--------------------------------------------------------------
-+
-+_slang_version_string
-+
-+ SYNOPSIS
-+ The S-Lang library version number as a string
-+
-+ USAGE
-+ String_Type _slang_version_string
-+
-+ DESCRIPTION
-+ The `_slang_version_string' variable is read-only and whose
-+ value represents the version number of the S-Lang library.
-+
-+ SEE ALSO
-+ _slang_version
-+--------------------------------------------------------------
-+
-+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
-+
-+ SEE ALSO
-+ _slang_doc_dir
-+--------------------------------------------------------------
-+
-+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, __get_reference, __is_initialized
-+--------------------------------------------------------------
-+
-+Conj
-+
-+ SYNOPSIS
-+ Compute the complex conjugate of a number
-+
-+ USAGE
-+ z1 = Conj (z)
-+
-+ DESCRIPTION
-+ The `Conj' function returns the complex conjugate of a number.
-+ If its argument is an array, the `Conj' function will be applied to each
-+ element and the result returned as an array.
-+
-+ SEE ALSO
-+ Real, Imag, abs
-+--------------------------------------------------------------
-+
-+Imag
-+
-+ SYNOPSIS
-+ Compute the imaginary part of a number
-+
-+ USAGE
-+ i = Imag (z)
-+
-+ DESCRIPTION
-+ The `Imag' function returns the imaginary part of a number.
-+ If its argument is an array, the `Imag' function will be applied to each
-+ element and the result returned as an array.
-+
-+ SEE ALSO
-+ Real, Conj, abs
-+--------------------------------------------------------------
-+
-+Real
-+
-+ SYNOPSIS
-+ Compute the real part of a number
-+
-+ USAGE
-+ r = Real (z)
-+
-+ DESCRIPTION
-+ The `Real' function returns the real part of a number. If its
-+ argument is an array, the `Real' function will be applied to
-+ each element and the result returned as an array.
-+
-+ SEE ALSO
-+ Imag, Conj, abs
-+--------------------------------------------------------------
-+
-+abs
-+
-+ SYNOPSIS
-+ Compute the absolute value of a number
-+
-+ USAGE
-+ y = abs(x)
-+
-+ DESCRIPTION
-+ The `abs' function returns the absolute value of an arithmetic
-+ type. If its argument is a complex number (`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 `abs' function.
-+
-+ SEE ALSO
-+ sign, sqr
-+--------------------------------------------------------------
-+
-+acos
-+
-+ SYNOPSIS
-+ Compute the arc-cosine of an number
-+
-+ USAGE
-+ y = acos (x)
-+
-+ DESCRIPTION
-+ The `acos' function computes the arc-cosine of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `acos' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+acosh
-+
-+ SYNOPSIS
-+ Compute the inverse cosh of an number
-+
-+ USAGE
-+ y = acosh (x)
-+
-+ DESCRIPTION
-+ The `acosh' function computes the inverse cosh of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `acosh' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+asin
-+
-+ SYNOPSIS
-+ Compute the arc-sine of an number
-+
-+ USAGE
-+ y = asin (x)
-+
-+ DESCRIPTION
-+ The `asin' function computes the arc-sine of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `asin' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+asinh
-+
-+ SYNOPSIS
-+ Compute the inverse-sinh of an number
-+
-+ USAGE
-+ y = asinh (x)
-+
-+ DESCRIPTION
-+ The `asinh' function computes the inverse-sinh of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `asinh' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+atan
-+
-+ SYNOPSIS
-+ Compute the arc-tangent of an number
-+
-+ USAGE
-+ y = atan (x)
-+
-+ DESCRIPTION
-+ The `atan' function computes the arc-tangent of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `atan' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+atanh
-+
-+ SYNOPSIS
-+ Compute the inverse-tanh of an number
-+
-+ USAGE
-+ y = atanh (x)
-+
-+ DESCRIPTION
-+ The `atanh' function computes the inverse-tanh of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `atanh' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+cos
-+
-+ SYNOPSIS
-+ Compute the cosine of an number
-+
-+ USAGE
-+ y = cos (x)
-+
-+ DESCRIPTION
-+ The `cos' function computes the cosine of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `cos' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+cosh
-+
-+ SYNOPSIS
-+ Compute the hyperbolic cosine of an number
-+
-+ USAGE
-+ y = cosh (x)
-+
-+ DESCRIPTION
-+ The `cosh' function computes the hyperbolic cosine of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `cosh' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+exp
-+
-+ SYNOPSIS
-+ Compute the exponential of an number
-+
-+ USAGE
-+ y = exp (x)
-+
-+ DESCRIPTION
-+ The `exp' function computes the exponential of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `exp' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+log
-+
-+ SYNOPSIS
-+ Compute the logarithm of an number
-+
-+ USAGE
-+ y = log (x)
-+
-+ DESCRIPTION
-+ The `log' function computes the logarithm of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `log' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+log10
-+
-+ SYNOPSIS
-+ Compute the base-10 logarithm of an number
-+
-+ USAGE
-+ y = log10 (x)
-+
-+ DESCRIPTION
-+ The `log10' function computes the base-10 logarithm of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `log10' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+mul2
-+
-+ SYNOPSIS
-+ Multiply a number by 2
-+
-+ USAGE
-+ y = mul2(x)
-+
-+ DESCRIPTION
-+ The `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 `mul2' function.
-+
-+ SEE ALSO
-+ sqr, abs
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+sign
-+
-+ SYNOPSIS
-+ Compute the sign of a number
-+
-+ USAGE
-+ y = sign(x)
-+
-+ DESCRIPTION
-+ The `sign' function returns the sign of an arithmetic type. If
-+ its argument is a complex number (`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 `sign' function.
-+
-+ When applied to a real number or an integer, the `sign' function
-+ returns -1, 0, or `+1' according to whether the number is
-+ less than zero, equal to zero, or greater than zero, respectively.
-+
-+ SEE ALSO
-+ abs
-+--------------------------------------------------------------
-+
-+sin
-+
-+ SYNOPSIS
-+ Compute the sine of an number
-+
-+ USAGE
-+ y = sin (x)
-+
-+ DESCRIPTION
-+ The `sin' function computes the sine of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `sin' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+sinh
-+
-+ SYNOPSIS
-+ Compute the hyperbolic sine of an number
-+
-+ USAGE
-+ y = sinh (x)
-+
-+ DESCRIPTION
-+ The `sinh' function computes the hyperbolic sine of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `sinh' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+sqr
-+
-+ SYNOPSIS
-+ Compute the square of a number
-+
-+ USAGE
-+ y = sqr(x)
-+
-+ DESCRIPTION
-+ The `sqr' function returns the square of an arithmetic type. If its
-+ argument is a complex number (`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 `sqr' function.
-+
-+ SEE ALSO
-+ abs, mul2
-+--------------------------------------------------------------
-+
-+sqrt
-+
-+ SYNOPSIS
-+ Compute the square root of an number
-+
-+ USAGE
-+ y = sqrt (x)
-+
-+ DESCRIPTION
-+ The `sqrt' function computes the square root of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `sqrt' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ sqr, cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+tan
-+
-+ SYNOPSIS
-+ Compute the tangent of an number
-+
-+ USAGE
-+ y = tan (x)
-+
-+ DESCRIPTION
-+ The `tan' function computes the tangent of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `tan' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+tanh
-+
-+ SYNOPSIS
-+ Compute the hyperbolic tangent of an number
-+
-+ USAGE
-+ y = tanh (x)
-+
-+ DESCRIPTION
-+ The `tanh' function computes the hyperbolic tangent of a number and
-+ returns the result as an array. If its argument is an array, the
-+ `tanh' function will be applied to each element and the result returned
-+ as an array.
-+
-+ SEE ALSO
-+ cos, atan, acosh, cosh
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+usage
-+
-+ SYNOPSIS
-+ Generate a usage error
-+
-+ USAGE
-+ usage (String_Type msg)
-+
-+ DESCRIPTION
-+ The `usage' function generates a usage exception and displays
-+ `msg' to the message device.
-+
-+ EXAMPLE
-+ Suppose that some function `plot' plots an array of `x' and
-+ `y' values. The such a function could be written to issue a
-+ usage message if the wrong number of arguments were passed:
-+
-+ define plot ()
-+ {
-+ variable x, y;
-+
-+ if (_NARGS != 2)
-+ usage ("plot (x, y)");
-+
-+ (x, y) = ();
-+ % Now do the hard part
-+ .
-+ .
-+ }
-+
-+
-+ SEE ALSO
-+ error, message
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+__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 `nm'. If no such object exists, it
-+ returns `NULL', otherwise it returns a reference.
-+
-+ EXAMPLE
-+ For example, consider the function:
-+
-+ define runhooks (hook)
-+ {
-+ variable f;
-+ f = __get_reference (hook);
-+ if (f != NULL)
-+ @f ();
-+ }
-+
-+ 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
-+ is_defined, typeof, eval, autoload, __is_initialized, __uninitialize
-+--------------------------------------------------------------
-+
-+__uninitialize
-+
-+ SYNOPSIS
-+ Uninitialize a variable
-+
-+ USAGE
-+ __uninitialize (Ref_Type x)
-+
-+ DESCRIPTION
-+ The `__uninitialize' function may be used to uninitialize the
-+ variable referenced by the parameter `x'.
-+
-+ EXAMPLE
-+ The following two lines are equivalent:
-+
-+ () = __tmp(z);
-+ __uninitialize (&z);
-+
-+
-+ SEE ALSO
-+ __tmp, __is_initialized
-+--------------------------------------------------------------
-+
-+_auto_declare
-+
-+ SYNOPSIS
-+ Set automatic variable declaration mode
-+
-+ USAGE
-+ Integer_Type _auto_declare
-+
-+ DESCRIPTION
-+ The `_auto_declare' may be used to have all undefined variables
-+ implicitely declared as `static'. If set to zero, any variable
-+ must be declared witha `variable' declaration before it can be
-+ used. If set to one, then any undeclared variabled will be declared
-+ as a `static' global variable.
-+
-+ The `_auto_declare' variable is 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 `X' not been
-+ declared:
-+
-+ X = 1;
-+
-+ However,
-+
-+ _auto_declare = 1; % declare variables as static.
-+ X = 1;
-+
-+ is equivalent to
-+
-+ static variable X = 1;
-+
-+
-+ NOTES
-+ This variable should be used sparingly and is intended primarily for
-+ interactive applications where one types S-Lang commands at a prompt.
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+implements
-+
-+ SYNOPSIS
-+ Name a private namespace
-+
-+ USAGE
-+ implements (String_Type name);
-+
-+ DESCRIPTION
-+ The `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 `Global'.
-+
-+ EXAMPLE
-+ Suppose that some file `t.sl' contains:
-+
-+ implements ("Ts_Private");
-+ static define message (x)
-+ {
-+ Global->vmessage ("Ts_Private message: %s", x);
-+ }
-+ message ("hello");
-+
-+ will produce `"Ts_Private message: hello"'. This `message'
-+ function may be accessed from outside via:
-+
-+ Ts_Private->message ("hi");
-+
-+
-+ NOTES
-+ Since `message' is an intrinsic function, it is global and may
-+ not be redefined in the global namespace.
-+
-+ SEE ALSO
-+ use_namespace, current_namespace, import
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+use_namespace
-+
-+ SYNOPSIS
-+ Change to another namespace
-+
-+ USAGE
-+ use_namespace (String_Type name)
-+
-+ DESCRIPTION
-+ The `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.
-+
-+ SEE ALSO
-+ implements, current_namespace, import
-+--------------------------------------------------------------
-+
-+current_namespace
-+
-+ SYNOPSIS
-+ Get the name of the current namespace
-+
-+ USAGE
-+ String_Type current_namespace ()
-+
-+ DESCRIPTION
-+ The `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 `implements' function, the
-+ empty string `""' will be returned.
-+
-+ SEE ALSO
-+ implements, use_namespace, import
-+--------------------------------------------------------------
-+
-+path_basename
-+
-+ SYNOPSIS
-+ Get the basename part of a pathname
-+
-+ USAGE
-+ String_Type path_basename (String_Type path)
-+
-+ DESCRIPTION
-+ The `path_basename' function returns the basename associated
-+ with the `path' parameter. The basename is the non-directory
-+ part of the filename, e.g., on unix `c' is the basename of
-+ `/a/b/c'.
-+
-+ SEE ALSO
-+ path_dirname, path_extname, path_concat, path_is_absolute
-+--------------------------------------------------------------
-+
-+path_concat
-+
-+ SYNOPSIS
-+ Combine elements of a pathname
-+
-+ USAGE
-+ String_Type path_concat (String_Type dir, String_Type basename)
-+
-+ DESCRIPTION
-+ The `path_concat' function combines the arguments `dir' and
-+ `basename' to produce a pathname. For example, on unix is
-+ `dir' is `x/y' and `basename' is `z', then the
-+ function will return `x/y/z'.
-+
-+ SEE ALSO
-+ path_dirname, path_basename, path_extname, path_is_absolute
-+--------------------------------------------------------------
-+
-+path_dirname
-+
-+ SYNOPSIS
-+ Get the directory name part of a pathname
-+
-+ USAGE
-+ String_Type path_dirname (String_Type path)
-+
-+ DESCRIPTION
-+ The `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.
-+
-+ SEE ALSO
-+ path_basename, path_extname, path_concat, path_is_absolute
-+--------------------------------------------------------------
-+
-+path_extname
-+
-+ SYNOPSIS
-+ Return the extension part of a pathname
-+
-+ USAGE
-+ String_Type path_extname (String_Type path)
-+
-+ DESCRIPTION
-+ The `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 `path'
-+ is `file.c', then this function returns `".c"'. If no
-+ extension is present, the function returns an empty string `""'.
-+
-+ NOTES
-+ Under VMS, the file version number is not returned as part of the
-+ extension.
-+
-+ SEE ALSO
-+ path_sans_extname, path_dirname, path_basename, path_concat, path_is_absolute
-+--------------------------------------------------------------
-+
-+path_is_absolute
-+
-+ SYNOPSIS
-+ Determine whether or not a pathname is absolute
-+
-+ USAGE
-+ Int_Type path_is_absolute (String_Type path)
-+
-+ DESCRIPTION
-+ The `path_is_absolute' function will return non-zero is
-+ `path' refers to an absolute pathname, otherwise it returns zero.
-+
-+ SEE ALSO
-+ path_dirname, path_basename, path_extname, path_concat
-+--------------------------------------------------------------
-+
-+path_sans_extname
-+
-+ SYNOPSIS
-+ Strip the extension from a pathname
-+
-+ USAGE
-+ String_Type path_sans_extname (String_Type path)
-+
-+ DESCRIPTION
-+ The `path_sans_extname' function removes the file name extension
-+ (including the dot) from the path and returns the result.
-+
-+ SEE ALSO
-+ path_extname, path_basename, path_dirname, path_concat
-+--------------------------------------------------------------
-+
-+close
-+
-+ SYNOPSIS
-+ Close an open file descriptor
-+
-+ USAGE
-+ Int_Type close (FD_Type fd)
-+
-+ DESCRIPTION
-+ The `close' function is used to open file descriptor of type
-+ `FD_Type'. Upon success 0 is returned, otherwise the function
-+ returns -1 and sets `errno' accordingly.
-+
-+ SEE ALSO
-+ open, fclose, read, write
-+--------------------------------------------------------------
-+
-+dup_fd
-+
-+ SYNOPSIS
-+ Duplicate a file descriptor
-+
-+ USAGE
-+ FD_Type dup_fd (FD_Type fd)
-+
-+ DESCRIPTION
-+ The `dup_fd' function duplicates and file descriptor and returns
-+ its duplicate. If the function fails, NULL will be returned and
-+ `errno' set accordingly.
-+
-+ NOTES
-+ This function is essentually a wrapper around the POSIX `dup'
-+ function.
-+
-+ SEE ALSO
-+ open, close
-+--------------------------------------------------------------
-+
-+fileno
-+
-+ SYNOPSIS
-+ Convert a stdio File_Type object to a FD_Type descriptor
-+
-+ USAGE
-+ FD_Type fileno (File_Type fp)
-+
-+ DESCRIPTION
-+ The `fileno' function returns the `FD_Type' descriptor
-+ associated with the `File_Type' file pointer. Upon failure,
-+ NULL is returned.
-+
-+ SEE ALSO
-+ fopen, open, fclose, close, dup_fd
-+--------------------------------------------------------------
-+
-+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 `fd' refers to a
-+ terminal; otherwise it returns 0. The object `fd' may either
-+ be a `File_Type' stdio descriptor or an `FD_Type' object.
-+
-+ SEE ALSO
-+ fopen, fclose, fileno
-+--------------------------------------------------------------
-+
-+lseek
-+
-+ SYNOPSIS
-+ Reposition a file descriptor's file pointer
-+
-+ USAGE
-+ Long_Type lseek (FD_Type fd, Long_Type ofs, int mode)
-+
-+ SEEK_SET Set the offset to ofs
-+ SEEK_CUR Add ofs to the current offset
-+ SEEK_END Add ofs to the current file size
-+
-+
-+ NOTES
-+ Not all file descriptors are capable of supporting the seek
-+ operation, e.g., a descriptor associated with a pipe.
-+
-+ By using `SEEK_END' with a positive value of the `ofs'
-+ parameter, it is possible to position the file pointer beyond the
-+ current size of the file.
-+
-+ SEE ALSO
-+ fseek, ftell, open, close
-+--------------------------------------------------------------
-+
-+open
-+
-+ SYNOPSIS
-+ Open a file
-+
-+ USAGE
-+ FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode])
-+
-+ DESCRIPTION
-+ The `open' function attempts to open a file specified by the
-+ `filename' parameter according to the `flags' parameter,
-+ which must be one of the following values:
-+
-+ O_RDONLY (read-only)
-+ O_WRONLY (write-only)
-+ O_RDWR (read/write)
-+
-+ In addition, `flags' may also be bitwise-or'd with any of the
-+ following:
-+
-+ O_BINARY (open the file in binary mode)
-+ O_TEXT (open the file in text mode)
-+ O_CREAT (create file if it does not exists)
-+ 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)
-+
-+ If `O_CREAT' is used for the `flags' parameterm then the
-+ `mode' parameter must be present. `mode' specifies the
-+ permissions to use if a new file is created. The actual file
-+ permissions will be affected by the process's `umask' via
-+ `mode&~umask'. The `mode' parameter's value is
-+ constructed via bitwise-or of the following values:
-+
-+ 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)
-+
-+ Upon success `open' returns a file descriptor object
-+ (`FD_Type'), otherwise `NULL' is returned and `errno'
-+ is set.
-+
-+ NOTES
-+ If you are not familiar with the `open' system call, then it
-+ is recommended that you use `fopen' instead.
-+
-+ SEE ALSO
-+ fopen, close, read, write, stat_file
-+--------------------------------------------------------------
-+
-+read
-+
-+ SYNOPSIS
-+ Read from an open file descriptor
-+
-+ USAGE
-+ UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num)
-+
-+ DESCRIPTION
-+ The `read' function attempts to read at most `num' bytes
-+ into the variable indicated by `buf' from the open file
-+ descriptor `fd'. It returns the number of bytes read, or -1
-+ and sets `errno' upon failure. The number of bytes read may be
-+ less than `num', and will be zero if an attempt is made to read
-+ past the end of the file.
-+
-+ NOTES
-+ `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 `errno' to `EAGAIN'.
-+
-+ SEE ALSO
-+ fread, open, close, write
-+--------------------------------------------------------------
-+
-+write
-+
-+ SYNOPSIS
-+ Write to an open file descriptor
-+
-+ USAGE
-+ UInt_Type write (FD_Type fd, BString_Type buf)
-+
-+ DESCRIPTION
-+ The `write' function attempts to write the bytes specified by
-+ the `buf' parameter to the open file descriptor `fd'. It
-+ returns the number of bytes successfully written, or -1 and sets
-+ `errno' upon failure. The number of bytes written may be less
-+ than `length(buf)'.
-+
-+ SEE ALSO
-+ read, fwrite, open, close
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+getegid
-+
-+ SYNOPSIS
-+ Get the effective group id
-+
-+ USAGE
-+ Int_Type getegid ()
-+
-+ DESCRIPTION
-+ The `getegid' function returns the effective group ID of the
-+ current process.
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ getgid, geteuid, setgid
-+--------------------------------------------------------------
-+
-+geteuid
-+
-+ SYNOPSIS
-+ Get the effective user-id of the current process
-+
-+ USAGE
-+ Int_Type geteuid ()
-+
-+ DESCRIPTION
-+ The `geteuid' function returns the effective user-id of the
-+ current process.
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ getuid, setuid, setgid
-+--------------------------------------------------------------
-+
-+getgid
-+
-+ SYNOPSIS
-+ Get the group id
-+
-+ USAGE
-+ Integer_Type getgid ()
-+
-+ DESCRIPTION
-+ The `getgid' function returns the real group id of the current
-+ process.
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ getpid, getppid
-+--------------------------------------------------------------
-+
-+getpid
-+
-+ SYNOPSIS
-+ Get the current process id
-+
-+ USAGE
-+ Integer_Type getpid ()
-+
-+ DESCRIPTION
-+ The `getpid' function returns the current process identification
-+ number.
-+
-+ SEE ALSO
-+ getppid, getgid
-+--------------------------------------------------------------
-+
-+getppid
-+
-+ SYNOPSIS
-+ Get the parent process id
-+
-+ USAGE
-+ Integer_Type getppid ()
-+
-+ DESCRIPTION
-+ The `getpid' function returns the process identification
-+ number of the parent process.
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ getpid, getgid
-+--------------------------------------------------------------
-+
-+getuid
-+
-+ SYNOPSIS
-+ Get the user-id of the current process
-+
-+ USAGE
-+ Int_Type getuid ()
-+
-+ DESCRIPTION
-+ The `getuid' function returns the user-id of the current
-+ process.
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ getuid, getegid
-+--------------------------------------------------------------
-+
-+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 `sig'
-+ to the process specified by `pid'. The function returns zero upon
-+ sucess and `-1' upon failure setting errno accordingly.
-+
-+ EXAMPLE
-+ The `kill' function may be used to determine whether or not
-+ a specific process exists:
-+
-+ define process_exists (pid)
-+ {
-+ if (-1 == kill (pid, 0))
-+ return 0; % Process does not exist
-+ return 1;
-+ }
-+
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ getpid
-+--------------------------------------------------------------
-+
-+mkfifo
-+
-+ SYNOPSIS
-+ Create a named pipe
-+
-+ USAGE
-+ Int_Type mkfifo (String_Type name, Int_Type mode)
-+
-+ DESCRIPTION
-+ The `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 `errno' upon failure.
-+
-+ NOTES
-+ Not all systems support the `mkfifo' function and even on
-+ systems that do implement the `mkfifo' system call, the
-+ underlying file system may not support the concept of a named pipe,
-+ e.g, an NFS filesystem.
-+
-+ SEE ALSO
-+ stat_file
-+--------------------------------------------------------------
-+
-+setgid
-+
-+ SYNOPSIS
-+ Set the group-id of the current process
-+
-+ USAGE
-+ Int_Type setgid (Int_Type gid)
-+
-+ DESCRIPTION
-+ The `setgid' function sets the effective group-id of the current
-+ process. It returns zero upon success, or -1 upon error and sets
-+ `errno' appropriately.
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ getgid, setuid
-+--------------------------------------------------------------
-+
-+setpgid
-+
-+ SYNOPSIS
-+ Set the process group-id
-+
-+ USAGE
-+ Int_Type setpgid (Int_Type pid, Int_Type gid)
-+
-+ DESCRIPTION
-+ The `setpgid' function sets the group-id `gid' of the
-+ process whose process-id is `pid'. If `pid' is 0, then the
-+ current process-id will be used. If `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 `errno' accordingly.
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ setgid, setuid
-+--------------------------------------------------------------
-+
-+setuid
-+
-+ SYNOPSIS
-+ Set the user-id of the current process
-+
-+ USAGE
-+ Int_Type setuid (Int_Type id)
-+
-+ DESCRIPTION
-+ The `setuid' function sets the effective user-id of the current
-+ process. It returns zero upon success, or -1 upon error and sets
-+ `errno' appropriately.
-+
-+ NOTES
-+ This function is not supported by all systems.
-+
-+ SEE ALSO
-+ setgid, setpgid, getuid, geteuid
-+--------------------------------------------------------------
-+
-+sleep
-+
-+ SYNOPSIS
-+ Pause for a specified number of seconds
-+
-+ USAGE
-+ sleep (Double_Type n)
-+
-+ DESCRIPTION
-+ The `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.
-+--------------------------------------------------------------
-+
-+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.
-+
-+ SEE ALSO
-+ popen, listdir
-+--------------------------------------------------------------
-+
-+umask
-+
-+ SYNOPSIS
-+ Set the file creation mask
-+
-+ USAGE
-+ Int_Type umask (Int_Type m)
-+
-+ DESCRIPTION
-+ The `umask' function sets the file creation mask to `m' and
-+ returns the previous mask.
-+
-+ SEE ALSO
-+ stat_file
-+--------------------------------------------------------------
-+
-+uname
-+
-+ SYNOPSIS
-+ Get the system name
-+
-+ USAGE
-+ Struct_Tye uname ()
-+
-+ DESCRIPTION
-+ The `uname' function returns a structure containing information
-+ about the operating system. The structure contains the following
-+ fields:
-+
-+ 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)
-+
-+
-+ NOTES
-+ Not all systems support this function.
-+
-+ SEE ALSO
-+ getenv, pack, unpack
-+--------------------------------------------------------------
-+
-+__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 `__push_args'
-+ is useful for passing the arguments of a function to another function.
-+ `__pop_args' returns an array of `n' structures with a
-+ single structure field called `value', which represents the value
-+ of the argument.
-+
-+ EXAMPLE
-+ Consider the following `print' function. It prints all its
-+ arguments to `stdout' separated by spaces:
-+
-+ 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);
-+ }
-+
-+ Now consider the problem of defining a function called `ones'
-+ that returns a multi-dimensional array with all the elements set to
-+ 1. For example, `ones(10)' should return a 1-d array of ones,
-+ whereas `ones(10,20)' should return a 10x20 array.
-+
-+ define ones ()
-+ {
-+ !if (_NARGS) return 1;
-+ variable a;
-+
-+ a = __pop_args (_NARGS);
-+ return @Array_Type (Integer_Type, [__push_args (a)]) + 1;
-+ }
-+
-+ Here, `__push_args' was used to push on the arguments passed to
-+ the `ones' function onto the stack to be used when dereferencing
-+ `Array_Type'.
-+
-+ SEE ALSO
-+ __push_args, typeof, _pop_n
-+--------------------------------------------------------------
-+
-+__push_args
-+
-+ SYNOPSIS
-+ Remove n function arguments onto the stack
-+
-+ USAGE
-+ __push_args (Struct_Type args);
-+
-+ DESCRIPTION
-+ This function together with the companion function `__pop_args'
-+ is useful for passing the arguments of one function to another.
-+ See the desription of `__pop_args' for more information.
-+
-+ SEE ALSO
-+ __pop_args, typeof, _pop_n
-+--------------------------------------------------------------
-+
-+_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
-+--------------------------------------------------------------
-+
-+_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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+exch
-+
-+ SYNOPSIS
-+ Exchange two items on the stack
-+
-+ USAGE
-+ exch ()
-+
-+ DESCRIPTION
-+ The `exch' swaps the two top items on the stack.
-+
-+ SEE ALSO
-+ pop, _stk_reverse, _stk_roll
-+--------------------------------------------------------------
-+
-+pop
-+
-+ SYNOPSIS
-+ Discard an item from the stack
-+
-+ USAGE
-+ pop ()
-+
-+ DESCRIPTION
-+ The `pop' function removes the top item from the stack.
-+
-+ SEE ALSO
-+ _pop_n
-+--------------------------------------------------------------
-+
-+clearerr
-+
-+ SYNOPSIS
-+ Clear the error of a file stream
-+
-+ USAGE
-+ clearerr (File_Type fp
-+
-+ DESCRIPTION
-+ The `clearerr' function clears the error and end-of-file flags
-+ associated with the open file stream `fp'.
-+
-+ SEE ALSO
-+ ferror, feof, fopen
-+--------------------------------------------------------------
-+
-+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, pclose, errno
-+--------------------------------------------------------------
-+
-+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 `fdopen' function creates and returns a stdio
-+ `File_Type' object from the open `FD_Type'
-+ descriptor `fd'. The `mode' parameter corresponds to the
-+ `mode' parameter of the `fopen' function and must be
-+ consistent with the mode of the descriptor `fd'. The function
-+ returns NULL upon failure and sets `errno'.
-+
-+ NOTES
-+ The `fclose' function does not close the `File_Type' object
-+ returned from this function. The underlying file object must be
-+ closed by the `close' function.
-+
-+ SEE ALSO
-+ fileno, fopen, open, close, fclose
-+--------------------------------------------------------------
-+
-+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 `fp'. It returns `0'
-+ if the indicator is not set, or non-zero if it is. The end-of-file
-+ indicator may be cleared by the `clearerr' function.
-+
-+ SEE ALSO
-+ ferror, clearerr, fopen
-+--------------------------------------------------------------
-+
-+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 `fp'. It returns `0'
-+ if the indicator is not set, or non-zero if it is. The error
-+ indicator may be cleared by the `clearerr' function.
-+
-+ SEE ALSO
-+ feof, clearerr, fopen
-+--------------------------------------------------------------
-+
-+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, fread, error
-+--------------------------------------------------------------
-+
-+fgetslines
-+
-+ SYNOPSIS
-+ Read all the lines from an open file
-+
-+ USAGE
-+ String_Type[] fgetslines (File_Type fp)
-+
-+ DESCRIPTION
-+ The `fgetslines' function returns all the remaining lines as an
-+ array of strings in the file specified by the open file pointer
-+ `fp'. If the file is empty, an empty string array will be
-+ returned. The function returns `NULL' upon error.
-+
-+ EXAMPLE
-+ The following function returns the number of lines in a file:
-+
-+ 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);
-+ }
-+
-+ 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.
-+
-+ SEE ALSO
-+ fgets, fread, fopen
-+--------------------------------------------------------------
-+
-+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, popen
-+--------------------------------------------------------------
-+
-+fprintf
-+
-+ SYNOPSIS
-+ Create and write a formatted string to a file
-+
-+ USAGE
-+ Int_Type fprintf (File_Type fp, String_Type fmt, ...)
-+
-+ DESCRIPTION
-+ `fprintf' formats the objects specified by the variable argument
-+ list according to the format `fmt' and write the result to the
-+ open file pointer `fp'.
-+
-+ The format string obeys the same syntax and semantics as the
-+ `sprintf' format string. See the description of the
-+ `sprintf' function for more information.
-+
-+ `fprintf' returns the number of characters written to the file,
-+ or -1 upon error.
-+
-+ SEE ALSO
-+ fputs, printf, fwrite, message
-+--------------------------------------------------------------
-+
-+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.
-+
-+ To write an object that contains embedded null characters, use the
-+ `fwrite' function.
-+
-+ SEE ALSO
-+ fclose, fopen, fgets, fwrite
-+--------------------------------------------------------------
-+
-+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 `fread' function may be used to read `n' objects of type
-+ `t' from an open file pointer `fp'. Upon success, it
-+ returns the number of objects read from the file and places the
-+ objects in the variable specified by `b'. Upon error or end of
-+ file, it returns `-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 `Char_Type' or
-+ `UChar_Type' objects from a file, in which case the data will be
-+ returned as a BString_Type binary string.
-+
-+ EXAMPLE
-+ The following example illustrates how to read 50 bytes from a file:
-+
-+ 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;
-+ }
-+
-+
-+ NOTES
-+ Use the `pack' and `unpack' functions to read data with a
-+ specific byte-ordering.
-+
-+ SEE ALSO
-+ fwrite, fgets, fopen, pack, unpack
-+--------------------------------------------------------------
-+
-+fseek
-+
-+ SYNOPSIS
-+ Reposition a stream
-+
-+ USAGE
-+ Integer_Type fseek (File_Type fp, Integer_Type ofs, Integer_Type whence
-+
-+ DESCRIPTION
-+ The `fseek' function may be used to reposition the file position
-+ pointer associated with the open file stream `fp'. Specifically,
-+ it moves the pointer `ofs' bytes relative to the position
-+ indicated by `whence'. If whence is set to one of the symbolic
-+ constants `SEEK_SET', `SEEK_CUR', or `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
-+ `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.
-+
-+ SEE ALSO
-+ ftell, fopen
-+--------------------------------------------------------------
-+
-+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 `fp'. It returns
-+ the position of the pointer measured in bytes from the beginning of
-+ the file. Upon error, it returns `-1' and sets `errno'.
-+
-+ SEE ALSO
-+ fseek, fopen
-+--------------------------------------------------------------
-+
-+fwrite
-+
-+ SYNOPSIS
-+ Write binary data to a file
-+
-+ USAGE
-+ UInt_Type fwrite (b, File_Type fp)
-+
-+ DESCRIPTION
-+ The `fwrite' may be used to write the object represented by
-+ `b' to an open file. If `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 `errno'
-+ accordingly.
-+
-+ EXAMPLE
-+ The following example illustrates how to write an integer array to a
-+ file. In this example, `fp' is an open file descriptor:
-+
-+ variable a = [1:50]; % 50 element integer array
-+ if (50 != fwrite (a, fp))
-+ error ("fwrite failed");
-+
-+ Here is how to write the array one element at a time:
-+
-+ variable a = [1:50];
-+ foreach (a)
-+ {
-+ variable ai = ();
-+ if (1 != fwrite(ai, fp))
-+ error ("fwrite failed");
-+ }
-+
-+
-+ NOTES
-+ Not all data types may support the `fwrite' operation. However,
-+ it is supported by all vector, scalar, and string objects.
-+
-+ SEE ALSO
-+ fread, fputs, fopen, pack, unpack
-+--------------------------------------------------------------
-+
-+pclose
-+
-+ SYNOPSIS
-+ Close an object opened with popen
-+
-+ USAGE
-+ Integer_Type pclose (File_Type fp)
-+
-+ DESCRIPTION
-+ The `pclose' function waits for the process associated with
-+ `fp' to exit and the returns the exit status of the command.
-+
-+ SEE ALSO
-+ pclose, fclose
-+--------------------------------------------------------------
-+
-+popen
-+
-+ SYNOPSIS
-+ Open a process
-+
-+ USAGE
-+ File_Type popen (String_Type cmd, String_Type mode)
-+
-+ DESCRIPTION
-+ The `popen' function executes a process specified by `cmd'
-+ and opens a unidirectional pipe to the newly created process. The
-+ `mode' indicates whether or not the the pipe is open for reading
-+ or writing. Specifically, if `mode' is `"r"', then the
-+ pipe is opened for reading, or if `mode' is `"w"', then the
-+ pipe will be open for writing.
-+
-+ Upon success, a `File_Type' pointer will be returned, otherwise
-+ the function failed and `NULL' will be returned.
-+
-+ NOTES
-+ This function is not available on all systems.
-+
-+ SEE ALSO
-+ pclose, fopen
-+--------------------------------------------------------------
-+
-+printf
-+
-+ SYNOPSIS
-+ Create and write a formatted string to stdout
-+
-+ USAGE
-+ Int_Type printf (String_Type fmt, ...)
-+
-+ DESCRIPTION
-+ `fprintf' formats the objects specified by the variable argument
-+ list according to the format `fmt' and write the result to
-+ `stdout'. This function is equivalent to `fprintf' used
-+ with the `stdout' file pointer. See `fprintf' for more
-+ information.
-+
-+ `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
-+ `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:
-+
-+ () = printf ("%s laid %d eggs\n", chicken_name, num_egg);
-+
-+
-+ SEE ALSO
-+ fputs, printf, fwrite, message
-+--------------------------------------------------------------
-+
-+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.
-+
-+ The format string is a C library `sprintf' style format
-+ descriptor. Briefly, the format string may consist of ordinary
-+ characters (not including the `%' character), which are copied
-+ into the output string as-is, and a conversion specification
-+ introduced by the `%' character. The `%' character must be
-+ followed by at least one other character to specify the conversion:
-+
-+ 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
-+
-+ Note that `%S' is a S-Lang extension which will cause the value
-+ to be formatted as string. In fact, `sprintf("%S",x)' is
-+ equivalent to `sprintf("%s",string(x))'.
-+
-+ 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, sscanf
-+--------------------------------------------------------------
-+
-+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
-+ strjoin, is_list_element, extract_element, strchop, strcat
-+--------------------------------------------------------------
-+
-+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;
-+ }
-+
-+
-+ Alternatively, the `strchop' function may be more useful. In
-+ fact, `extract_element' may be expressed in terms of the
-+ function `strchop' as
-+
-+ define extract_element (list, nth, delim)
-+ {
-+ list = strchop(list, delim, 0);
-+ if (nth >= length (list))
-+ return NULL;
-+ else
-+ return list[nth];
-+ }
-+
-+ and the `num_elements' function used above may be recoded more
-+ simply as:
-+
-+ define num_elements (list, delim)
-+ {
-+ return length (strchop (length, delim, 0));
-+ }
-+
-+
-+ SEE ALSO
-+ is_list_element, is_substr, strtok, strchop, create_delimited_string
-+--------------------------------------------------------------
-+
-+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, strreplace
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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, sscanf, vmessage
-+--------------------------------------------------------------
-+
-+sscanf
-+
-+ SYNOPSIS
-+ Parse a formatted string
-+
-+ USAGE
-+ Int_Type sscanf (s, fmt, r1, ... rN)
-+
-+ String_Type s, fmt;
-+ Ref_Type r1, ..., rN
-+
-+
-+ DESCRIPTION
-+ The `sscanf' function parses the string `s' according to the
-+ format `fmt' and sets the variables whose references are given by
-+ `r1', ..., `rN'. The function returns the number of
-+ references assigned, or `-1' upon error.
-+
-+ The format string `fmt' consists of ordinary characters and
-+ conversion specifiers. A conversion specifier begins with the
-+ special character `%' 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 `%' is used to denote a conversion specifier whose general
-+ form is given by `%[*][width][type]format' where the brackets
-+ indicate optional items. If `*' is present, then the conversion
-+ will be performed by no assignment to a reference will be made. The
-+ `width' specifier specifies the maximum field width to use for
-+ the conversion. The `type' modifier is used to indicate size of
-+ the object, e.g., a short integer, as follows.
-+
-+ If _type_ is given as the character `h', then if the format
-+ conversion is for an integer (`dioux'), the object assigned will
-+ be a short integer. If _type_ is `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:
-+
-+ % 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.
-+
-+
-+ EXAMPLE
-+ Suppose that `s' is `"Coffee: (3,4,12.4)"'. Then
-+
-+ n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z);
-+
-+ will set `n' to 4, `item' to `"Coffee"', `x' to 3,
-+ `y' to 4, and `z' to the double precision number
-+ `12.4'. However,
-+
-+ n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z);
-+
-+ will set `n' to 1, `item' to `"Coffee:"' and the
-+ remaining variables will not be assigned.
-+
-+ SEE ALSO
-+ sprintf, unpack, string, atof, int, integer, string_match
-+--------------------------------------------------------------
-+
-+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 `del_set' from the string `str'. The result is returned.
-+
-+ EXAMPLE
-+
-+ str = str_delete_chars (str, "^A-Za-z");
-+
-+ will remove all characters except `A-Z' and `a-z' from
-+ `str'.
-+--------------------------------------------------------------
-+
-+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.
-+
-+ NOTES
-+ This function has been superceded by `strreplace'.
-+
-+ SEE ALSO
-+ strreplace
-+--------------------------------------------------------------
-+
-+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 strings
-+
-+ USAGE
-+ String_Type strcat (String_Type a_1, ..., String_Type a_N)
-+
-+ DESCRIPTION
-+ The `strcat' function concatenates its N `String_Type'
-+ arguments `a_1', ... `a_N' together and returns the result.
-+
-+ EXAMPLE
-+
-+ strcat ("Hello", " ", "World");
-+
-+ produces the string `"Hello World"'.
-+
-+ NOTES
-+ This function is equivalent to the binary operation `a_1+...+a_N'.
-+ However, `strcat' is much faster making it the preferred method
-+ to concatenate string.
-+
-+ SEE ALSO
-+ sprintf, create_delimited_string
-+--------------------------------------------------------------
-+
-+strchop
-+
-+ SYNOPSIS
-+ Chop or split a string into substrings.
-+
-+ USAGE
-+ String_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 the substrings as an array.
-+
-+ EXAMPLE
-+ The following function illustrates how to sort a comma separated
-+ list of strings:
-+
-+ 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, ",");
-+ }
-+
-+
-+ NOTES
-+ The semantics of this `strchop' and `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 `strchopr' should be used if it is desired to have
-+ the string chopped-up in the reverse order.
-+
-+ SEE ALSO
-+ strchopr, extract_element, strjoin, strtok
-+--------------------------------------------------------------
-+
-+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 `strchop' except
-+ that it returns the substrings in the reverse order. See the
-+ documentation for `strchop' for more information.
-+
-+ SEE ALSO
-+ strchop, extract_element, strtok, strjoin
-+--------------------------------------------------------------
-+
-+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 strcompress (String_Type s, String_Type white)
-+
-+ DESCRIPTION
-+ The `strcompress' function compresses the string `s' by
-+ replacing a sequence of one or more characters from the set
-+ `white' by the first character of `white'. 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, strtrans
-+--------------------------------------------------------------
-+
-+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_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 `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
-+--------------------------------------------------------------
-+
-+strjoin
-+
-+ SYNOPSIS
-+ Concatenate elements of a string array
-+
-+ USAGE
-+ String_Type strjoin (Array_Type a, String_Type delim)
-+
-+ DESCRIPTION
-+ The `strjoin' function operates on an array of strings by joining
-+ successive elements together separated with a delimiter `delim'.
-+ If `delim' is the empty string `""', then the result will
-+ simply be the concatenation of the elements.
-+
-+ EXAMPLE
-+ Suppose that
-+
-+ days = ["Sun","Mon","Tue","Wed","Thu","Fri","Sat","Sun"];
-+
-+ Then `strjoin (days,"+")' will produce
-+ `"Sun+Mon+Tue+Wed+Thu+Fri+Sat+Sun"'. Similarly,
-+ `strjoin (["","",""], "X")' will produce `"XX"'.
-+
-+ SEE ALSO
-+ create_delimited_string, strchop, strcat
-+--------------------------------------------------------------
-+
-+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
-+ bstrlen, length, 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
-+--------------------------------------------------------------
-+
-+strreplace
-+
-+ SYNOPSIS
-+ Replace one or more substrings
-+
-+ USAGE
-+ (new, n) = strreplace (a, b, c, max_n)
-+
-+ String_Type a, b, c, rep;
-+ Int_Type n, max_n;
-+
-+
-+ DESCRIPTION
-+ The `strreplace' function may be used to replace one or more
-+ occurances of `b' in `a' with `c'. If the integer
-+ `max_n' is positive, then the first `max_n' occurances of
-+ `b' in `a' will be replaced. Otherwise, if `max_n' is
-+ negative, then the last `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 `strreplace' may be used
-+ to remove all occurances of a specified substring
-+
-+ define delete_substrings (a, b)
-+ {
-+ (a, ) = strreplace (a, b, "", strlen (a));
-+ return a;
-+ }
-+
-+
-+ SEE ALSO
-+ is_substr, strsub, strtrim, strtrans, str_delete_chars
-+--------------------------------------------------------------
-+
-+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;
-+ }
-+
-+ For uses such as this, the `strtrans' function is a better choice.
-+
-+ NOTES
-+ The first character in the string `s' is specified by `pos'
-+ equal to 1.
-+
-+ SEE ALSO
-+ is_substr, strreplace, strlen
-+--------------------------------------------------------------
-+
-+strtok
-+
-+ SYNOPSIS
-+ Extract tokens from a string
-+
-+ USAGE
-+ String_Type[] strtok (String_Type str [,String_Type white])
-+
-+ DESCRIPTION
-+ `strtok' breaks the string `str' into a series of tokens and
-+ returns them as an array of strings. If the second parameter
-+ `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 `white' is `'^'', then the
-+ whitespace characters consist of all characters except those in
-+ `white'. For example, if `white' is `" \t\n,;."',
-+ then those characters specifiy the whitespace characters. However,
-+ if `white' is given by `"^a-zA-Z0-9_"', then any character
-+ is a whitespace character except those in the ranges `a-z',
-+ `A-Z', `0-9', and the underscore character.
-+
-+ If the second parameter is not present, then it defaults to
-+ `" \t\r\n\f"'.
-+
-+ EXAMPLE
-+ The following example may be used to count the words in a text file:
-+
-+ 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;
-+ }
-+
-+
-+ SEE ALSO
-+ strchop, strcompress, extract_element, strjoin
-+--------------------------------------------------------------
-+
-+strtrans
-+
-+ SYNOPSIS
-+ Replace characters in a string
-+
-+ USAGE
-+ String_Type strtrans (str, old_set, new_set)
-+
-+ String_Type str, old_set, new_set;
-+
-+
-+ DESCRIPTION
-+ The `strtrans' function may be used to replace all the characters
-+ from the set `old_set' with the corresponding characters from
-+ `new_set' in the string `str'. If `new_set' is empty,
-+ then the characters in `new_set' will be removed from `str'.
-+ This function returns the result.
-+
-+ EXAMPLE
-+
-+ str = strtrans (str, "A-Z", "a-z"); % lower-case str
-+ str = strtrans (str, "^0-9", " "); % Replace anything but 0-9 by space
-+
-+
-+ SEE ALSO
-+ strreplace, strtrim, strup, strlow
-+--------------------------------------------------------------
-+
-+strtrim
-+
-+ SYNOPSIS
-+ Remove whitespace from the ends of a string
-+
-+ USAGE
-+ String_Type strtrim (String_Type s [,String_Type w])
-+
-+ DESCRIPTION
-+ The `strtrim' function removes all leading and trailing whitespace
-+ characters from the string `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 `" \t\r\n"'.
-+
-+ SEE ALSO
-+ strtrim_beg, strtrim_end, strcompress
-+--------------------------------------------------------------
-+
-+strtrim_beg
-+
-+ SYNOPSIS
-+ Remove leading whitespace from a string
-+
-+ USAGE
-+ String_Type strtrim_beg (String_Type s [,String_Type w])
-+
-+ DESCRIPTION
-+ The `strtrim_beg' function removes all leading whitespace
-+ characters from the string `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 `" \t\r\n"'.
-+
-+ SEE ALSO
-+ strtrim, strtrim_end, strcompress
-+--------------------------------------------------------------
-+
-+strtrim_end
-+
-+ SYNOPSIS
-+ Remove trailing whitespace from a string
-+
-+ USAGE
-+ String_Type strtrim_end (String_Type s [,String_Type w])
-+
-+ DESCRIPTION
-+ The `strtrim_end' function removes all trailing whitespace
-+ characters from the string `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 `" \t\r\n"'.
-+
-+ SEE ALSO
-+ strtrim, strtrim_beg, 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, strtrans
-+--------------------------------------------------------------
-+
-+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
-+ In many cases it is more convenient to use array indexing rather
-+ than the `substr' function. In fact, `substr(s,i+1,strlen(s))' is
-+ equivalent to `s[[i:]]'.
-+
-+ SEE ALSO
-+ is_substr, strlen
-+--------------------------------------------------------------
-+
-+_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 `_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.
-+
-+ SEE ALSO
-+ get_struct_field_names, get_struct_field
-+--------------------------------------------------------------
-+
-+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 `get_struct_field' function gets the value of the field
-+ whose name is specified by `field_name' of the structure `s'.
-+
-+ EXAMPLE
-+ The following example illustrates how this function may be used to
-+ to print the value of a structure.
-+
-+ 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));
-+ }
-+ }
-+
-+
-+ SEE ALSO
-+ set_struct_field, get_struct_field_names, array_info
-+--------------------------------------------------------------
-+
-+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 `get_struct_field_names' function returns an array of
-+ strings whose elements specify the names of the fields of the
-+ struct `s'.
-+
-+ EXAMPLE
-+ The following example illustrates how the
-+ `get_struct_field_names' function may be used to print the
-+ value of a structure.
-+
-+ 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));
-+ }
-+ }
-+
-+
-+ SEE ALSO
-+ _push_struct_field_values, get_struct_field
-+--------------------------------------------------------------
-+
-+is_struct_type
-+
-+ SYNOPSIS
-+ Determine whether or not an object is a structure
-+
-+ USAGE
-+ Integer_Type is_struct_type (X)
-+
-+ DESCRIPTION
-+ The `is_struct_type' function returns 1 if the the parameter
-+ refers to a structure or a user-defined type. If the object is
-+ neither, 0 will be returned.
-+
-+ SEE ALSO
-+ typeof, _typeof
-+--------------------------------------------------------------
-+
-+set_struct_field
-+
-+ SYNOPSIS
-+ Set the value associated with a structure field
-+
-+ USAGE
-+ set_struct_field (s, field_name, field_value)
-+
-+ Struct_Type s;
-+ String_Type field_name;
-+ Generic_Type field_value;
-+
-+
-+ DESCRIPTION
-+ The `set_struct_field' function sets the value of the field
-+ whose name is specified by `field_name' of the structure
-+ `s' to `field_value'.
-+
-+ SEE ALSO
-+ get_struct_field, get_struct_field_names, set_struct_fields, array_info
-+--------------------------------------------------------------
-+
-+set_struct_fields
-+
-+ SYNOPSIS
-+ Set the fields of a structure
-+
-+ USAGE
-+ set_struct_fields (Struct_Type s, ...)
-+
-+ DESCRIPTION
-+ The `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
-+
-+ variable s = struct { "name", "age", "height" };
-+ set_struct_fields (s, "Bill", 13, 64);
-+
-+
-+ SEE ALSO
-+ set_struct_field, get_struct_field_names
-+--------------------------------------------------------------
-+
-+_time
-+
-+ SYNOPSIS
-+ Get the current time in seconds
-+
-+ USAGE
-+ ULong_Type _time ()
-+
-+ DESCRIPTION
-+ The `_time' function returns the number of elapsed seconds since
-+ 00:00:00 GMT, January 1, 1970. The `ctime' function may be used
-+ to convert this into a string representation.
-+
-+ SEE ALSO
-+ ctime, time, localtime, gmtime
-+--------------------------------------------------------------
-+
-+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 `secs' seconds since 1970.
-+
-+ SEE ALSO
-+ time, _time, localtime, gmtime
-+--------------------------------------------------------------
-+
-+gmtime
-+
-+ SYNOPSIS
-+ Break down a time in seconds to GMT timezone
-+
-+ USAGE
-+ Struct_Type gmtime (Long_Type secs)
-+
-+ DESCRIPTION
-+ The `gmtime' function is exactly like `localtime' except
-+ that the values in the structure it returns are with respect to GMT
-+ instead of the local timezone. See the documentation for
-+ `localtime' for more information.
-+
-+ NOTES
-+ On systems that do not support the `gmtime' C library function,
-+ this function is the same as `localtime'.
-+
-+ SEE ALSO
-+ localtime, _time
-+--------------------------------------------------------------
-+
-+localtime
-+
-+ SYNOPSIS
-+ Break down a time in seconds to local timezone
-+
-+ USAGE
-+ Struct_Type localtime (Long_Type secs)
-+
-+ DESCRIPTION
-+ The `localtime' function takes a parameter `secs'
-+ representing the number of seconds since 00:00:00, January 1 1970
-+ UTC and returns a structure containing information about `secs'
-+ in the local timezone. The structure contains the following
-+ `Int_Type' fields:
-+
-+ `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.
-+
-+ `tm_min' The number of minutes after the hour, in the
-+ range 0 to 59.
-+
-+ `tm_hour' The number of hours past midnight, in the range
-+ 0 to 23.
-+
-+ `tm_mday' The day of the month, in the range 1 to 31.
-+
-+ `tm_mon' The number of months since January, in the range
-+ 0 to 11.
-+
-+ `tm_year' The number of years since 1900.
-+
-+ `tm_wday' The number of days since Sunday, in the range 0
-+ to 6.
-+
-+ `tm_yday' The number of days since January 1, in the
-+ range 0 to 365.
-+
-+ `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.
-+
-+ SEE ALSO
-+ gmtime, _time, ctime
-+--------------------------------------------------------------
-+
-+tic
-+
-+ SYNOPSIS
-+ Start timing
-+
-+ USAGE
-+ void tic ()
-+
-+ DESCRIPTION
-+ The `tic' function restarts the internal clock used for timing
-+ the execution of commands. To get the elapsed time of the clock,
-+ use the `toc' function.
-+
-+ SEE ALSO
-+ toc, times
-+--------------------------------------------------------------
-+
-+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:
-+
-+ Sun Apr 21 13:34:17 1996
-+
-+
-+ SEE ALSO
-+ ctime, message, substr
-+--------------------------------------------------------------
-+
-+times
-+
-+ SYNOPSIS
-+ Get process times
-+
-+ USAGE
-+ Struct_Type times ()
-+
-+ DESCRIPTION
-+ The `times' function returns a structure containing the
-+ following fields:
-+
-+ tms_utime (user time)
-+ tms_stime (system time)
-+ tms_cutime (user time of child processes)
-+ tms_cstime (system time of child processes)
-+
-+
-+ NOTES
-+ Not all systems support this function.
-+
-+ SEE ALSO
-+ tic, toc, _times
-+--------------------------------------------------------------
-+
-+toc
-+
-+ SYNOPSIS
-+ Get elapsed CPU time
-+
-+ USAGE
-+ Double_Type toc ()
-+
-+ DESCRIPTION
-+ The `toc' function returns the elapsed CPU time in seconds since
-+ the last call to `tic'. The CPU time is the amount of time the
-+ CPU spent running the code of the current process.
-+
-+ EXAMPLE
-+ The `tic' and `toc' functions are ideal for timing the
-+ execution of the interpreter:
-+
-+ 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);
-+
-+
-+ NOTES
-+ This function may not be available on all systems.
-+
-+ The implementation of this function is based upon the `times'
-+ system call. The precision of the clock is system dependent.
-+
-+ SEE ALSO
-+ tic, times, _time
-+--------------------------------------------------------------
-+
-+_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
-+--------------------------------------------------------------
-+
-+_typeof
-+
-+ SYNOPSIS
-+ Get the data type of an object
-+
-+ USAGE
-+ DataType_Type _typeof (x)
-+
-+ DESCRIPTION
-+ This function is similar to the `typeof' function except in the
-+ case of arrays. If the object `x' is an array, then the data
-+ type of the array will be returned. otherwise `_typeof' returns
-+ the data type of `x'.
-+
-+ EXAMPLE
-+
-+ if (Integer_Type == _typeof (x))
-+ message ("x is an integer or an integer array");
-+
-+
-+ SEE ALSO
-+ typeof, array_info, _slang_guess_type, typecast
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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
-+--------------------------------------------------------------
-+
-+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)) message ("x is an integer");
-+
-+
-+ SEE ALSO
-+ _typeof, is_struct_type, array_info, _slang_guess_type, typecast
-+--------------------------------------------------------------
-+
---- jed-0.99.16.orig/lib/jed.rc
-+++ jed-0.99.16/lib/jed.rc
-@@ -28,7 +28,7 @@
- % uncomment Wordstar line. A similar statement applies for BRIEF,
- % and for Borland IDE-like bindings.
- %
--% () = evalfile("emacs"); % Emacs-like bindings
-+ () = evalfile("emacs"); % Emacs-like bindings
- % () = evalfile("edt"); % EDT emulation
- % () = evalfile ("ide"); % Borland IDE (see also doc/ide-mode.txt)
- % () = evalfile ("brief"); % Brief Keybindings (MSDOS only!!)
---- jed-0.99.16.orig/lib/paste_mode.sl
-+++ jed-0.99.16/lib/paste_mode.sl
-@@ -0,0 +1,28 @@
-+% made by JED and pasted to the mailing list
-+% use as follows:
-+% M-x push_mode
-+% Push to mode: paste
-+% <paste with mouse>
-+% M-x pop_mode
-+
-+$1 = "Paste";
-+!if (keymap_p ($1)) make_keymap ($1);
-+_for (32, 255, 1)
-+{
-+ $2 = char ();
-+ undefinekey ($2, $1);
-+ definekey ("self_insert_cmd", $2, $1);
-+}
-+definekey ("newline", "\n", $1);
-+definekey ("newline", "\r", $1);
-+definekey ("self_insert_cmd", "\t", $1);
-+
-+define paste_mode ()
-+{
-+ variable kmap = "Paste";
-+ set_mode (kmap, 2);
-+ use_keymap (kmap);
-+ runhooks ("paste_mode_hook");
-+}
-+
-+provide("paste_mode");
---- jed-0.99.16.orig/src/Makefile.in
-+++ jed-0.99.16/src/Makefile.in
-@@ -2,7 +2,7 @@
-
- # C compiler and C flags
- CC = @CC@
--CFLAGS = @CFLAGS@ @CPPFLAGS@ @X_CFLAGS@
-+CFLAGS = @CFLAGS@ @CPPFLAGS@ @X_CFLAGS@ -I/usr/include/freetype2
- LDFLAGS = @LDFLAGS@
-
- #---------------------------------------------------------------------------
---- jed-0.99.16.orig/src/win32.c
-+++ jed-0.99.16/src/win32.c
-@@ -233,7 +233,7 @@
-
-
- /* returns 0 if file does not exist, 1 if it is not a dir, 2 if it is */
--int sys_chmod(char *file, int what, int *mode, short *uid, short *gid)
-+int sys_chmod(char *file, int what, int *mode, int *uid, int *gid)
- {
- #ifdef _MSC_VER
- struct _stat buf;
---- jed-0.99.16.orig/src/file.c
-+++ jed-0.99.16/src/file.c
-@@ -969,7 +969,7 @@
- int jed_copy_file (char *from, char *to) /*{{{*/
- {
- int mode;
-- short uid, gid;
-+ int uid, gid;
- FILE *fp0, *fp1;
- char buf[0x7FFF];
- unsigned int readlen;
-@@ -1104,7 +1104,7 @@
- char autosave_file[JED_MAX_PATH_LEN];
- int n;
- int mode, do_mode;
-- short uid, gid;
-+ int uid, gid;
- #ifndef VMS
- char *old = NULL;
- int backup_went_ok;
-@@ -1532,7 +1532,7 @@
- */
- {
- int mode = 0;
-- short uid, gid;
-+ int uid, gid;
- return sys_chmod(file, 0, &mode, &uid, &gid);
- }
-
---- jed-0.99.16.orig/src/os2.c
-+++ jed-0.99.16/src/os2.c
-@@ -356,7 +356,7 @@
- #endif
-
- #if defined(_MSC_VER) || defined (__EMX__) || defined(__WATCOMC__)
--int sys_chmod(char *file, int what, int *mode, short *uid, short *gid)
-+int sys_chmod(char *file, int what, int *mode, int *uid, int *gid)
- {
- struct stat buf;
- int m;
---- jed-0.99.16.orig/src/sysdep.h
-+++ jed-0.99.16/src/sysdep.h
-@@ -33,7 +33,7 @@
- extern void ungetkey(int *);
- extern void sys_resume(void);
- extern int sys_delete_file(char *);
--extern int sys_chmod(char *, int, int *, short *, short *);
-+extern int sys_chmod(char *, int, int *, int *, int *);
- extern unsigned long sys_file_mod_time(char *);
-
- /* expand the file in a canonical way and return a pointer to a
---- jed-0.99.16.orig/src/unix.c
-+++ jed-0.99.16/src/unix.c
-@@ -680,7 +680,7 @@
- /*}}}*/
-
- /* returns 0 if file does not exist, 1 if it is not a dir, 2 if it is */
--int sys_chmod(char *file, int what, int *mode, short *uid, short *gid) /*{{{*/
-+int sys_chmod(char *file, int what, int *mode, int *uid, int *gid) /*{{{*/
- {
- struct stat buf;
- int m;
---- jed-0.99.16.orig/src/vms.c
-+++ jed-0.99.16/src/vms.c
-@@ -982,7 +982,7 @@
- #include <stat.h>
-
- /* returns 0 if file does not exist, 1 if it is not a dir, 2 if it is */
--int sys_chmod(char *file, int what, int *mode, short *uid, short *gid) /*{{{*/
-+int sys_chmod(char *file, int what, int *mode, int *uid, int *gid) /*{{{*/
- {
- struct stat buf;
- int m;