[Pkg-jed-commit] r24 - in trunk/packages/jed/debian: . patches
Rafael Laboissiere
rafael@costa.debian.org
Fri, 08 Apr 2005 13:13:29 +0000
Author: rafael
Date: 2005-04-08 13:13:28 +0000 (Fri, 08 Apr 2005)
New Revision: 24
Added:
trunk/packages/jed/debian/patches/50_all.dpatch
trunk/packages/jed/debian/patches/50_emacs-bindings.dpatch
trunk/packages/jed/debian/patches/50_enable-xrenderfont.dpatch
trunk/packages/jed/debian/patches/50_jed-manpage-option-g.dpatch
trunk/packages/jed/debian/patches/50_paste-mode-sl.dpatch
trunk/packages/jed/debian/patches/50_slangfun-txt.dpatch
trunk/packages/jed/debian/patches/50_src-Makefile-in.dpatch
Removed:
trunk/packages/jed/debian/patches/50_debian_0.99.16-4.dpatch
trunk/packages/jed/debian/patches/50_increase-MAX_USER_FLIST.dpatch
Modified:
trunk/packages/jed/debian/changelog
trunk/packages/jed/debian/control
trunk/packages/jed/debian/patches/00list
trunk/packages/jed/debian/rules
Log:
Debian release 0.99.16.pre.0.99.17.84-1
Modified: trunk/packages/jed/debian/changelog
===================================================================
--- trunk/packages/jed/debian/changelog 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/changelog 2005-04-08 13:13:28 UTC (rev 24)
@@ -1,3 +1,29 @@
+jed (0.99.16.pre.0.99.17.84-1) experimental; urgency=low
+
+ +++ Changes by Rafael Laboissiere
+
+ * New upstream release. This is the development branch, a.k.a. the
+ pre-0.99.17 series. I am using a funny version number in order to
+ avoid using epochs when jed 0.99.17 will be released.
+ * This versions makes extensive use of dpatch. The big Debian-specific
+ patch that used to be in 0.99.16-* is now broken down in smaller
+ pieces:
+ - debian/patches/40_freetype-include
+ - debian/patches/50_slangfun-txt.dpatch
+ - debian/patches/50_jed-manpage-option-g
+ - debian/patches/50_enable-xrenderfont
+ - debian/patches/50_emacs-bindings
+ - debian/patches/50_paste-mode-sl
+ - debian/patches/60_gpm-mouse-support
+ * debian/rules:
+ - Do not build/install jgrep, because this program does not even
+ compile against libslang2.
+ - On-the-fly patching of src/Makefile for gpm and xrender support is
+ dropped. Used
+ * debian/control: Build-depends on libslang2-dev (>= 1.99pre2r7-1)
+
+ -- Debian JED Group <pkg-jed-devel@lists.alioth.debian.org> Fri, 8 Apr 2005 15:04:02 +0200
+
jed (0.99.16-5) unstable; urgency=low
+++ Changes by Rafael Laboissiere
Modified: trunk/packages/jed/debian/control
===================================================================
--- trunk/packages/jed/debian/control 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/control 2005-04-08 13:13:28 UTC (rev 24)
@@ -3,7 +3,7 @@
Priority: optional
Maintainer: Debian JED Group <pkg-jed-devel@lists.alioth.debian.org>
Standards-Version: 3.6.1
-Build-Depends: debhelper (>= 4), hevea, libgpmg1-dev (>= 1.17.8-18) [!hurd-i386], perl (>= 5.004.05-1.1), perl-base (>= 5.004.05-1.1), slang1-dev (>= 1.3.11), xlibs-dev (>= 4.0.1-10), libfreetype6-dev (>= 2.0.1-1), libxft-dev, dpatch
+Build-Depends: debhelper (>= 4), hevea, libgpmg1-dev (>= 1.17.8-18) [!hurd-i386], perl (>= 5.004.05-1.1), perl-base (>= 5.004.05-1.1), libslang2-dev (>= 1.99pre2r7-1), xlibs-dev (>= 4.0.1-10), libfreetype6-dev (>= 2.0.1-1), libxft-dev, dpatch
Package: jed
Architecture: any
Modified: trunk/packages/jed/debian/patches/00list
===================================================================
--- trunk/packages/jed/debian/patches/00list 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/00list 2005-04-08 13:13:28 UTC (rev 24)
@@ -1,2 +1,7 @@
-50_debian_0.99.16-4
-50_increase-MAX_USER_FLIST
+40_freetype-include
+50_slangfun-txt.dpatch
+50_jed-manpage-option-g
+50_enable-xrenderfont
+50_emacs-bindings
+50_paste-mode-sl
+60_gpm-mouse-support
Added: trunk/packages/jed/debian/patches/50_all.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_all.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_all.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -0,0 +1,18 @@
+#! /bin/sh /usr/share/dpatch/dpatch-run
+## 50_src-Makefile-include-freetype.dpatch by by Rafael Laboissiere <rafael@debian.org>
+##
+## DP: Add include path for FreeType in CFLAGS
+
+@DPATCH@
+
+--- jed-0.99.16.pre.0.99.17.84.orig/src/Makefile.in
++++ jed-0.99.16.pre.0.99.17.84/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@ @DYNAMIC_LINK_FLAGS@
+
+ #---------------------------------------------------------------------------
Property changes on: trunk/packages/jed/debian/patches/50_all.dpatch
___________________________________________________________________
Name: svn:executable
+ *
Deleted: trunk/packages/jed/debian/patches/50_debian_0.99.16-4.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_debian_0.99.16-4.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_debian_0.99.16-4.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -1,5959 +0,0 @@
-#! /bin/sh /usr/share/dpatch/dpatch-run
-## 50_debian_0.99.16-4.dpatch by Rafael Laboissiere <rafael@debian.org>
-##
-## Legacy patch from package version 0.99.16-4
-
-@DPATCH@
-
---- 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;
Added: trunk/packages/jed/debian/patches/50_emacs-bindings.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_emacs-bindings.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_emacs-bindings.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -0,0 +1,18 @@
+#! /bin/sh /usr/share/dpatch/dpatch-run
+## 50_emacs-bindings.dpatch by Rafael Laboissiere <rafael@debian.org>
+##
+## DP: Start jed in Emacs emulation mode
+
+@DPATCH@
+
+--- jed-0.99.16.pre.0.99.17.84.orig/lib/jed.rc
++++ jed-0.99.16.pre.0.99.17.84/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!!)
Property changes on: trunk/packages/jed/debian/patches/50_emacs-bindings.dpatch
___________________________________________________________________
Name: svn:executable
+ *
Added: trunk/packages/jed/debian/patches/50_enable-xrenderfont.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_enable-xrenderfont.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_enable-xrenderfont.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -0,0 +1,29 @@
+#! /bin/sh /usr/share/dpatch/dpatch-run
+## 50_enable-xrenderfont.dpatch by by Rafael Laboissiere <rafael@debian.org>
+##
+## DP: Use X Render extensions in xjed
+
+@DPATCH@
+
+--- jed-0.99.16.pre.0.99.17.84.orig/src/jed-feat.h
++++ jed-0.99.16.pre.0.99.17.84/src/jed-feat.h
+@@ -88,7 +88,7 @@
+ * extension. You also need to uncomment and possibly modify
+ * XRENDERFONTLIBS in src/Makefile
+ */
+-#define XJED_HAS_XRENDERFONT 0
++#define XJED_HAS_XRENDERFONT 1
+
+ /* Set JED_HAS_IMPORT if you want the ability to import modules into jed via
+ * the slang import statement. This assumes that slang was compiled with
+--- jed-0.99.16.pre.0.99.17.84.orig/src/Makefile.in
++++ jed-0.99.16.pre.0.99.17.84/src/Makefile.in
+@@ -59,7 +59,7 @@
+
+ # 2. XFree86 XRENDERFONT (Anti-aliased font) support for XJED
+ # Also modify "XJED_HAS_XRENDERFONT" in jed-feat.h
+-#XRENDERFONTLIBS = -lXft -lXrender -lfreetype -lXext
++XRENDERFONTLIBS = -lXft -lXrender -lfreetype -lXext
+
+ #---------------------------------------------------------------------------
+ # S-Lang library location
Property changes on: trunk/packages/jed/debian/patches/50_enable-xrenderfont.dpatch
___________________________________________________________________
Name: svn:executable
+ *
Deleted: trunk/packages/jed/debian/patches/50_increase-MAX_USER_FLIST.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_increase-MAX_USER_FLIST.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_increase-MAX_USER_FLIST.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -1,18 +0,0 @@
-#! /bin/sh /usr/share/dpatch/dpatch-run
-## 50_increase-MAX_USER_FLIST.dpatch by Rafael Laboissiere <rafael@debian.org>
-##
-## Increase the maximum number of autoload definitins
-
-@DPATCH@
-
---- jed-0.99.16.orig/src/keymap.c
-+++ jed-0.99.16/src/keymap.c
-@@ -974,7 +974,7 @@
- static SLKeymap_Function_Type *Flist_Context;
- static int Flist_Context_Len;
-
--#define MAX_USER_FLIST 100
-+#define MAX_USER_FLIST 512
- static char *Slang_Functions[MAX_USER_FLIST];
- static char **Slang_Flist_Context;
-
Added: trunk/packages/jed/debian/patches/50_jed-manpage-option-g.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_jed-manpage-option-g.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_jed-manpage-option-g.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -0,0 +1,19 @@
+#! /bin/sh /usr/share/dpatch/dpatch-run
+## 50_jed-manpage-option-g.dpatch by Rafael Laboissiere <rafael@debian.org>
+##
+## DP: Explain better the behavior of option -g
+
+@DPATCH@
+
+--- jed-0.99.16.pre.0.99.17.84.orig/doc/manual/jed.1
++++ jed-0.99.16.pre.0.99.17.84/doc/manual/jed.1
+@@ -45,7 +45,8 @@
+ .RS
+ goto line
+ .I n
+-in buffer
++in buffer (notice that in order to this option to take effect, if must
++appear after the file name in the command line, like 'jed file -g 3')
+ .RE
+ .I -l 'file'
+ .RS
Property changes on: trunk/packages/jed/debian/patches/50_jed-manpage-option-g.dpatch
___________________________________________________________________
Name: svn:executable
+ *
Added: trunk/packages/jed/debian/patches/50_paste-mode-sl.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_paste-mode-sl.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_paste-mode-sl.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -0,0 +1,38 @@
+#! /bin/sh /usr/share/dpatch/dpatch-run
+## 50_paste-mode-sl.dpatch by Rafael Laboissiere <rafael@debian.org>
+##
+## DP: Added paste_mode by John E. Davis
+
+@DPATCH@
+
+--- jed-0.99.16.pre.0.99.17.84.orig/lib/paste_mode.sl
++++ jed-0.99.16.pre.0.99.17.84/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");
Property changes on: trunk/packages/jed/debian/patches/50_paste-mode-sl.dpatch
___________________________________________________________________
Name: svn:executable
+ *
Added: trunk/packages/jed/debian/patches/50_slangfun-txt.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_slangfun-txt.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_slangfun-txt.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -0,0 +1,5614 @@
+#! /bin/sh /usr/share/dpatch/dpatch-run
+## 50_slangfun-txt.dpatch by Rafael Laboissiere <rafael@debian.org>
+##
+## DP: Add lacking file doc/txt/slangfun.txt
+
+@DPATCH@
+
+--- jed-0.99.16.pre.0.99.17.84.orig/doc/txt/slangfun.txt
++++ jed-0.99.16.pre.0.99.17.84/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
++--------------------------------------------------------------
++
Property changes on: trunk/packages/jed/debian/patches/50_slangfun-txt.dpatch
___________________________________________________________________
Name: svn:executable
+ *
Added: trunk/packages/jed/debian/patches/50_src-Makefile-in.dpatch
===================================================================
--- trunk/packages/jed/debian/patches/50_src-Makefile-in.dpatch 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/patches/50_src-Makefile-in.dpatch 2005-04-08 13:13:28 UTC (rev 24)
@@ -0,0 +1,24 @@
+#! /bin/sh /usr/share/dpatch/dpatch-run
+## 50_gpm-mouse-support.dpatch by Rafael Laboissiere <rafael@debian.org>
+##
+## DP: Enable GPM mouse support
+
+@DPATCH@
+
+--- jed-0.99.16.pre.0.99.17.84.orig/src/Makefile.in
++++ jed-0.99.16.pre.0.99.17.84/src/Makefile.in
+@@ -51,10 +51,10 @@
+ #---------------------------------------------------------------------------
+ # 1. Linux GPM Mouse support
+ # Uncomment next FOUR lines for GPM mouse support
+-#MOUSEFLAGS = -DUSE_GPM_MOUSE
+-#MOUSELIB = -lgpm
+-#GPMMOUSEO = gpmmouse.o
+-#OBJGPMMOUSEO = $(OBJDIR)/$(GPMMOUSEO)
++MOUSEFLAGS = -DUSE_GPM_MOUSE
++MOUSELIB = -lgpm
++GPMMOUSEO = gpmmouse.o
++OBJGPMMOUSEO = $(OBJDIR)/$(GPMMOUSEO)
+
+
+ # 2. XFree86 XRENDERFONT (Anti-aliased font) support for XJED
Property changes on: trunk/packages/jed/debian/patches/50_src-Makefile-in.dpatch
___________________________________________________________________
Name: svn:executable
+ *
Modified: trunk/packages/jed/debian/rules
===================================================================
--- trunk/packages/jed/debian/rules 2005-03-19 08:51:42 UTC (rev 23)
+++ trunk/packages/jed/debian/rules 2005-04-08 13:13:28 UTC (rev 24)
@@ -28,24 +28,11 @@
fi
@echo
- @echo "--- activate xrenderfont support patch for Linux ---"
- @echo
- if [ "`uname -s`" = "Linux" ]; then \
- perl -w -i -p \
- -e 's/#XRENDERFONTLIBS/XRENDERFONTLIBS/;' \
- src/Makefile; \
- perl -w -i -p \
- -e 's/#define XJED_HAS_XRENDERFONT[[:space:]]*0/#define XJED_HAS_XRENDERFONT 1/;' \
- src/jed-feat.h; \
- fi
-
-
- @echo
@echo --- MAKE ---
@echo
make JED_ROOT=/usr/share/jed
make xjed JED_ROOT=/usr/share/jed
- make rgrep JED_ROOT=/usr/share/jed
+# make rgrep JED_ROOT=/usr/share/jed
make getmail JED_ROOT=/usr/share/jed
cd doc/manual/ && \
rm -rf jed && \
@@ -64,7 +51,7 @@
rm -f build-stamp install-stamp
find lib/ -name "*.slc" -exec rm {} \;
find lib/ -name "*.dfa" -exec rm {} \;
- rm -f src/config.h
+ rm -f src/config.h config.log config.status
rm -rf doc/manual/jed
dh_clean
-make distclean
@@ -154,8 +141,8 @@
@echo --- JED ---
@echo
install src/$(ARCH)objs/jed $(jed)/usr/bin
- install src/$(ARCH)objs/rgrep $(jed)/usr/bin
- mv $(jed)/usr/bin/rgrep $(jed)/usr/bin/jgrep
+# install src/$(ARCH)objs/rgrep $(jed)/usr/bin
+# mv $(jed)/usr/bin/rgrep $(jed)/usr/bin/jgrep
@echo
@echo --- XJED ---
@@ -170,8 +157,8 @@
gzip -9 $(xjed)/usr/share/man/man1/xjed.1
install -m644 doc/manual/jed.1 $(jed)/usr/share/man/man1/jed.1
gzip -9 $(jed)/usr/share/man/man1/jed.1
- install -m644 doc/manual/rgrep.1 $(jed)/usr/share/man/man1/jgrep.1
- gzip -9 $(jed)/usr/share/man/man1/jgrep.1
+# install -m644 doc/manual/rgrep.1 $(jed)/usr/share/man/man1/jgrep.1
+# gzip -9 $(jed)/usr/share/man/man1/jgrep.1
dh_installdocs -a # just for the /usr/doc link
# only jed-common: dh_installchangelogs -a
dh_installmenu -a