slangfun.txt

一个C格式的脚本处理函数库源代码,可让你的C程序具有执行C格式的脚本文件

   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 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 success 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