cref.tm

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

\usage{int SLexecute_function (SLang_Name_Type *nt)}
\description
  The \var{SLexecute_function} allows an application to call the
  \slang function specified by the \var{SLang_Name_Type} pointer
  \var{nt}.  This parameter must be non \var{NULL} and must have been
   previously obtained by a call to \var{SLang_get_function}.
\example
   Consider the \slang function:
#v+
     define my_fun (x)
     {
        return x^2 - 2;
     }
#v-
   Suppose that it is desired to call this function many times with
   different values of x.  There are at least two ways to do this.
   The easiest way is to use \var{SLang_execute_function} by passing
   the string \exmp{"my_fun"}.  A better way that is much faster is to
   use \var{SLexecute_function}:
#v+
      int sum_a_function (char *fname, double *result)
      {
         double sum, x, y;
	 SLang_Name_Type *nt;

	 if (NULL == (nt = SLang_get_function (fname)))
	   return -1;
	 
	 sum = 0;
	 for (x = 0; x < 10.0; x += 0.1)
	   {
	      SLang_start_arg_list ();
	      if (-1 == SLang_push_double (x))
	        return -1;
	      SLang_end_arg_list ();
	      if (-1 == SLexecute_function (nt))
	        return -1;
	      if (-1 == SLang_pop_double (&y, NULL, NULL))
	        return -1;
	      
	      sum += y;
	   }
	 return sum;
      }
#v-
   Although not necessary in this case, \var{SLang_start_arg_list} and
   \var{SLang_end_arg_list} were used to provide the function with
   information about the number of parameters passed to it.
\seealso{SLang_get_function, SLang_start_arg_list, SLang_end_arg_list}
\done


\function{SLang_peek_at_stack}
\synopsis{Find the type of object on the top of the stack}
\usage{int SLang_peek_at_stack (void)}
\description
  The \var{SLang_peek_at_stack} function is useful for determining the
  data type of the object at the top of the stack.  It returns the
  data type, or -1 upon a stack-underflow error.  It does not remove
  anything from the stack.
\seealso{SLang_pop_string, SLang_pop_integer}
\done


\function{SLmake_string}
\synopsis{Duplicate a string}
\usage{char *SLmake_string (char *s)}
\description
  The \var{SLmake_string} function creates a new copy of the string
  \var{s}, via \var{malloc}, and returns it.  Upon failure it returns
  \var{NULL}.  Since the resulting string is malloced, it should be
  freed when nolonger needed via a call to either \var{free} or
  \var{SLfree}.
\notes
  \var{SLmake_string} should not be confused with the function
  \var{SLang_create_slstring}, which performs a similar function.
\seealso{SLmake_nstring, SLfree, SLmalloc, SLang_create_slstring}
\done


\function{SLmake_nstring}
\synopsis{Duplicate a substring}
\usage{char *SLmake_nstring (char *s, unsigned int n)}
\description
  This function is like \var{SLmake_nstring} except that it creates a
  null terminated string formed from the first \var{n} characters of
  \var{s}.  Upon failure, it returns \var{NULL}, otherwise it returns
  the new string.  When nolonger needed, the returned string should be
  freed with either \var{free} or \var{SLfree}.
\seealso{SLmake_nstring, SLfree, SLang_create_nslstring}
\done


\function{SLang_create_nslstring}
\synopsis{Created a hashed substring}
\usage{char *SLang_create_nslstring (char *s, unsigned int n)}
\description
  \var{SLang_create_nslstring} is like \var{SLang_create_slstring}
  except that only the first \var{n} characters of \var{s} are used to
  perform the string.  Upon error, it returns \var{NULL}, otherwise it
  returns the hashed substring.  Such a string must be freed by the
  function \var{SLang_free_slstring}.
\notes
  Do not use \var{free} or \var{SLfree} to free the string returned by
  \var{SLang_create_slstring} or \var{SLang_create_nslstring}.  Also
  it is important that no attempt is made to modify the hashed string
  returned by either of these functions.  If one needs to modify a
  string, the functions \var{SLmake_string} or \var{SLmake_nstring}
  should be used instead.
\seealso{SLang_free_slstring, SLang_create_slstring, SLmake_nstring}
\done

\function{SLang_create_slstring}
\synopsis{Create a hashed string}
\usage{char *SLang_create_slstring (char *s)}
\description
  The \var{SLang_create_slstring} creates a copy of \var{s} and
  returns it as a hashed string.  Upon error, the function returns
  \var{NULL}, otherwise it returns the hashed string.  Such a string
  must only be freed via the \var{SLang_free_slstring} function.
\notes
  Do not use \var{free} or \var{SLfree} to free the string returned by
  \var{SLang_create_slstring} or \var{SLang_create_nslstring}.  Also
  it is important that no attempt is made to modify the hashed string
  returned by either of these functions.  If one needs to modify a
  string, the functions \var{SLmake_string} or \var{SLmake_nstring}
  should be used instead.
\seealso{SLang_free_slstring, SLang_create_nslstring, SLmake_string}
\done


\function{SLang_free_slstring}
\synopsis{Free a hashed string}
\usage{void SLang_free_slstring (char *s)}
\description
  The \var{SLang_free_slstring} function is used to free a hashed
  string such as one returned by \var{SLang_create_slstring},
  \var{SLang_create_nslstring}, or \var{SLang_create_static_slstring}.
  If \var{s} is \var{NULL}, the routine does nothing.
\seealso{SLang_create_slstring, SLang_create_nslstring, SLang_create_static_slstring}
\done


\function{SLang_concat_slstrings}
\synopsis{Concatenate two strings to produce a hashed string}
\usage{char *SLang_concat_slstrings (char *a, char *b)}
\description
  The \var{SLang_concat_slstrings} function concatenates two strings,
  \var{a} and \var{b}, and returns the result as a hashed string.
  Upon failure, \var{NULL} is returned.
\notes
  A hashed string can only be freed using \var{SLang_free_slstring}.
  Never use either \var{free} or \var{SLfree} to free a hashed string,
  otherwise memory corruption will result.
\seealso{SLang_free_slstring, SLang_create_slstring}
\done

\function{SLang_create_static_slstring}
\synopsis{Create a hashed string}
\usage{char *SLang_create_static_slstring (char *s_literal)}
\description
  The \var{SLang_create_static_slstring} creates a hashed string from
  the string literal \var{s_literal} and returns the result.  Upon
  failure it returns \var{NULL}.
\example
#v+
     char *create_hello (void)
     {
        return SLang_create_static_slstring ("hello");
     }
#v-
\notes
  This function should only be used with string literals.
\seealso{SLang_create_slstring, SLang_create_nslstring}
\done


\function{SLmalloc}
\synopsis{Allocate some memory}
\usage{char *SLmalloc (unsigned int nbytes)}
\description
  This function uses \var{malloc} to allocate \var{nbytes} of memory.
  Upon error it returns \var{NULL}; otherwise it returns a pointer to
  the allocated memory.  One should use \var{SLfree} to free the
  memory after used.
\seealso{SLfree, SLrealloc, SLcalloc}
\done


\function{SLcalloc}
\synopsis{Allocate some memory}
\usage{char *SLcalloc (unsigned int num_elem, unsigned int elem_size)}
\description
  This function uses \var{calloc} to allocate memory for
  \var{num_elem} objects with each of size \var{elem_size} and returns
  the result.  In addition, the newly allocated memory is zeroed. 
  Upon error it returns \var{NULL}; otherwise it returns a pointer to
  the allocated memory.  One should use \var{SLfree} to free the
  memory after used.
\seealso{SLmalloc, SLrealloc, SLfree}
\done


\function{SLfree}
\synopsis{Free some allocated memory}
\usage{void SLfree (char *ptr)}
\description
  The \var{SLfree} function uses \var{free} to deallocate the memory
  specified by \var{ptr}, which may be \var{NULL} in which case the
  function does nothing.
\notes
  Never use this function to free a hashed string returned by one of
  the family of \var{slstring} functions, e.g.,
  \var{SLang_pop_slstring}.
\seealso{SLmalloc, SLcalloc, SLrealloc, SLmake_string}
\done


\function{SLrealloc}
\synopsis{Resize a dynamic memory block}
\usage{char *SLrealloc (char *ptr, unsigned int new_size)}
\description
  The \var{SLrealloc} uses the \var{realloc} function to resize the
  memory block specified by \var{ptr} to the new size \var{new_size}.
  If \var{ptr} is \var{NULL}, the function call is equivalent to
  \exmp{SLmalloc(new_size)}.  Similarly, if \var{new_size} is zero,
  the function call is equivalent to \var{SLfree(ptr)}.  

  If the function fails, or if \var{new_size} is zero, \var{NULL} is
  returned.  Otherwise a pointer is returned to the (possibly moved)
  new block of memory.
\seealso{SLfree, SLmalloc, SLcalloc}
\done


\function{SLcurrent_time_string}
\synopsis{Get the current time as a string}
\usage{char *SLcurrent_time_string (void)}
\description
  The \var{SLcurrent_time_string} function uses the C library function
  \var{ctime} to obtain a string representation of the
  current date and time in the form
#v+
     "Wed Dec 10 12:50:28 1997"
#v-
  However, unlike the \var{ctime} function, a newline character is not
  present in the string.  
  
  The returned value points to a statically allocated memory block
  which may get overwritten on subsequent function calls.
\seealso{SLmake_string}
\done



\function{SLatoi}
\synopsis{Convert a text string to an integer}
\usage{int SLatoi(unsigned char *str}
\description
  \var{SLatoi} parses the string \var{str} to interpret it as an
  integer value.  Unlike \var{atoi}, \var{SLatoi} can also parse
  strings containing integers expressed in
  hexidecimal (e.g., \exmp{"0x7F"}) and octal (e.g., \exmp{"012"}.)
  notation.
\seealso{SLang_guess_type}
\done


\function{SLang_pop_fileptr}
\synopsis{Pop a file pointer}
\usage{int SLang_pop_fileptr (SLang_MMT_Type **mmt, FILE **fp)}
\description
  \var{SLang_pop_fileptr} pops a file pointer from the \slang
  run-time stack.  It returns zero upon success, or \-1 upon failure.
  
  A \slang file pointer (SLANG_FILEPTR_TYPE) is actually a memory
  managed object.  For this reason, \var{SLang_pop_fileptr} also
  returns the memory managed object via the argument list.  It is up
  to the calling routine to call \var{SLang_free_mmt} to free the
  object.
\example
  The following example illustrates an application defined intrinsic
  function that writes a user defined double precision number to a
  file.  Note the use of \var{SLang_free_mmt}:
#v+
     int write_double (void)
     {
        double t;
	SLang_MMT_Type *mmt;
	FILE *fp;
	int status;

	if (-1 == SLang_pop_double (&d, NULL, NULL))
	  return -1;
	if (-1 == SLang_pop_fileptr (&mmt, &fp))
	  return -1;
	
	status = fwrite (&d, sizeof (double), 1, fp);
	SLang_free_mmt (mmt);
        return status;
     }
#v-
  This function can be used by a \slang function as follows:
#v+
     define write_some_values ()
     {
        variable fp, d;

	fp = fopen ("myfile.dat", "wb");
	if (fp == NULL)
	  error ("file failed to open");
	for (d = 0; d < 10.0; d += 0.1)
	  {
	     if (-1 == write_double (fp, d))
	       error ("write failed");
	  }
	if (-1 == fclose (fp))
	  error ("fclose failed");
     }
#v-
\seealso{SLang_free_mmt, SLang_pop_double}
\done


\function{SLadd_intrinsic_function}
\synopsis{Add a new intrinsic function to the interpreter}
\usage{int SLadd_intrinsic_function (name, f, type, nargs, ...)}
#v+
    char *name
    FVOID_STAR f
    unsigned char type
    unsigned int nargs
#v-
\description
  The \var{SLadd_intrinsic_function} function may be used to add a new
  intrinsic function.  The \slang name of the function is specified by
  \var{name} and the actual function pointer is given by \var{f}, cast
  to \var{FVOID_STAR}.  The third parameter, \var{type} specifies the
  return type of the function and must be one of the following values:
#v+
    SLANG_VOID_TYPE   (returns nothing)
    SLANG_INT_TYPE    (returns int)
    SLANG_DOUBLE_TYPE (returns double)
    SLANG_STRING_TYPE (returns char *)
#v-
  The \var{nargs} parameter specifies the number of parameters to pass
  to the function.  The variable argument list following \var{nargs}
  must consists of \var{nargs} integers which specify the data type of
  each argument.

  The function returns zero upon success or \-1 upon failure.
\example
  The \jed editor uses this function to change the \var{system}
  intrinsic function to the following:
#v+
     static int jed_system (char *cmd)
     {
        if (Jed_Secure_Mode)
	  {
	    msg_error ("Access denied.");
	    return -1;
	  }	  
	return SLsystem (cmd);
     }
#v-
  After initializing the interpreter with \var{SLang_init_slang},
  \jed calls \var{SLadd_intrinsic_function} to substitute the above
  definition for the default \slang definition:
#v+
     if (-1 ==