cslang.tm

来自「一个C格式的脚本处理函数库源代码,可让你的C程序具有执行C格式的脚本文件」· TM 代码 · 共 1,759 行 · 第 1/5 页

#c -*- mode: tm; mode: fold -*-

#c text-macro definitions #%{{{
#i linuxdoc.tm

#d slang \bf{S-Lang}
#d slrn \bf{slrn}
#d jed \bf{jed}
#d key#1 <tt>$1</tt>
#d footnote#1 <footnote>$1</footnote>
#d grp#1 <tt>$1</tt>
#d file#1 <tt>$1</tt>
#d -1 <tt>-1</tt>
#d 0 <tt>0</tt>
#d 1 <tt>1</tt>

#d kw#1 \tt{$1}
#d exmp#1 \tt{$1}
#d var#1 \tt{$1}

#d cfun#1 \tt{$1}
#d ivar#1 \tt{$1}
#d ifun#1 \tt{$1}
#d exfile#1 \tt{$1}
#d exns#1 \tt{$1}
#d exstr#1 \tt{"$1"}

#d ldots ...
#d times *
#d sc#1 \tt{$1}
#d verb#1 \tt{$1}
#d sldxe \bf{sldxe}
#d url#1 <htmlurl url="$1" name="$1">
#d slang-library-reference \bf{The \slang Library Reference}
#d chapter#1 <chapt>$1<p>
#d tag#1 <tag>$1</tag>
#d appendix <appendix>

#d kbd#1 <tt>$1</tt>

#d documentstyle book

#%}}}

\linuxdoc

\begin{\documentstyle}

\title S-Lang Library C Programmer's Guide, V1.4.9
\author John E. Davis, \tt{[e-mail]}
\date \__today__

\toc

#i preface.tm

\chapter{Introduction} #%{{{

  \slang is a C programmer's library that includes routines for the rapid
  development of sophisticated, user friendly, multi-platform applications.
  The \slang library includes the following:

\begin{itemize} 
\item  Low level tty input routines for reading single characters at a time.
\item  Keymap routines for defining keys and manipulating multiple keymaps.
\item  A high-level keyprocessing interface (\verb{SLkp}) for
       handling function and arrow keys.
\item  High level screen management routines for manipulating both
       monochrome and color terminals.  These routines are \em{very}
       efficient. (\tt{SLsmg})
\item  Low level terminal-independent routines for manipulating the display
       of a terminal. (\tt{SLtt})
\item  Routines for reading single line input with line editing and recall
       capabilities. (\tt{SLrline})
\item  Searching functions: both ordinary searches and regular expression
       searches. (\tt{SLsearch})
\item  An embedded stack-based language interpreter with a C-like syntax.
\end{itemize} 

  The library is currently available for OS/2, MSDOS, Unix, and VMS
  systems.  For the most part, the interface to library routines has
  been implemented in such a way that it appears to be platform
  independent from the point of view of the application.  In addition,
  care has been taken to ensure that the routines are ``independent''
  of one another as much as possible.  For example, although the
  keymap routines require keyboard input, they are not tied to
  \slang's keyboard input routines--- one can use a different keyboard
  \verb{getkey} routine if one desires.  This also means that linking
  to only part of the \slang library does not pull the whole library
  into the application.  Thus, \slang applications tend to be
  relatively small in comparison to programs that use libraries with
  similar capabilities.

#%}}}

\chapter{Interpreter Interface} #%{{{

  The \slang library provides an interpreter that when embedded into
  an application, makes the application extensible.  Examples of
  programs that embed the interpreter include the \jed editor and the
  \slrn newsreader.

  Embedding the interpreter is easy.  The hard part is to decide what
  application specific built-in or intrinsic functions should be
  provided by the application.  The \slang library provides some
  pre-defined intrinsic functions, such as string processing
  functions, and simple file input-output routines.  However, the
  basic philosophy behind the interpreter is that it is not a
  standalone program and it derives much of its power from the
  application that embeds it.
  
\sect{Embedding the Interpreter} #%{{{

  Only one function needs to be called to embed the \slang interpreter
  into an application: \cfun{SLang_init_slang}.  This function
  initializes the interpreter's data structures and adds some intrinsic
  functions:
#v+
      if (-1 == SLang_init_slang ())
        exit (EXIT_FAILURE);
#v-
  This function does not provide file input output intrinsic nor does
  it provide mathematical functions.  To make these as well as some
  posix system calls available use
#v+
     if ((-1 == SLang_init_slang ())    /* basic interpreter functions */
         || (-1 == SLang_init_slmath ()) /* sin, cos, etc... */
         || (-1 == SLang_init_stdio ()) /* stdio file I/O */
         || (-1 == SLang_init_posix_dir ()) /* mkdir, stat, etc. */
         || (-1 == SLang_init_posix_process ()) /* getpid, umask, etc. */
        )
       exit (EXIT_FAILURE);
#v-
  If you intend to enable all intrinsic functions, then it is simpler
  to initialize the interpreter via
#v+
     if (-1 == SLang_init_all ())
       exit (EXIT_FAILURE);
#v-
  See the \slang-run-time-library for more information about the
  intrinsic functions.


#%}}}

\sect{Calling the Interpreter} #%{{{

  There are several ways of calling the interpreter.  The two most common
  method is to load a file containing \slang code, or to load a
  string.

\sect1{Loading Files}
  The \cfun{SLang_load_file} and \cfun{SLns_load_file} functions may
  be used to interpret a file.  Both these functions return zero if
  successful, or \-1 upon failure.  If either of these functions fail,
  the interpreter will accept no more code unless the error state is
  cleared.  This is done by calling \cfun{SLang_restart} function to
  set the interpreter to its default state, \em{and} setting
  \ivar{SLang_Error} to 0, e.g.,
#v+
     if (-1 == SLang_load_file ("site.sl"))
       {
          /* Clear the error and rest the interpreter */
          SLang_restart (1);
          SLang_Error = 0;
       }
#v-

  When a file is loaded via \cfun{SLang_load_file}, any non-public
  variables and functions defined in the file will be placed into a
  namespace that is local to the file itself.  The
  \cfun{SLns_load_file} function may be used to load a file using a
  specified namespace, e.g.,
#v+
     if (-1 == SLns_load_file ("site.sl", "NS"))
       {
         SLang_restart (1);
         SLang_Error = 0;
       }
#v-
  will load \exfile{site.sl} into a namespace called \exns{NS}.  If such a
  namespace does not exist, then it will be created.
  
  Both the \cfun{SLang_load_file} and \cfun{SLns_load_file} functions
  search for files along an application-specified search path.  This
  path may be set using the \cfun{SLpath_set_load_path} function, as
  well as from interpeted code via the \ifun{set_slang_load_path}
  function.  By default, no search path is defined.
  
  Files are searched as follows: If the name begins with the
  equivalent of \exstr{./} or \exstr{../}, then it is searched for
  with respect to the current directory, and not along the load-path.
  If no such file exists, then an error will be generated. Otherwise,
  the file is searched for in each of the directories of the load-path
  by concatenating the path element with the specified file name.  The
  first such file found to exist by this process will be loaded.  If a
  matching file still has not been found, and the file name lacks an
  extension, then the path is searched with \exstr{.sl} and
  \exstr{.slc} appended to the filename.  If two such files are found
  (one ending with \exstr{.sl} and the other with \exstr{.slc}), then
  the more recent of the two will be used.  If no matching file has
  been found by this process, then the search will cease and an error
  generated.

  The search path is a delimiter separated list of directories that
  specify where the interpreter looks for files.  By default, the
  value of the delimiter is OS-dependent following the convention of
  the underlying OS.  For example, on Unix the delimiter is
  represented by a colon, on DOS/Windows it is a semi-colon, and on
  VMS it is a space.  The \cfun{SLpath_set_delimiter} and
  \cfun{SLpath_get_delimiter} may be used to set and query the
  delimiter's value, respectively.

\sect1{Loading Strings}
  There are several other mechanisms for interacting with the
  interpreter.  For example, the \cfun{SLang_load_string} function
  loads a string into the interpreter and interprets it:
#v+
    if (-1 == SLang_load_string ("message (\"hello\");"))
      {
        SLang_restart (1);
        SLang_Error = 0;
      }
#v-
  Similarly, the \cfun{SLns_load_string} function may be used to load
  a string into a specified namespace.

  Typically, an interactive application will load a file via
  \cfun{SLang_load_file} and then go into a loop that consists of
  reading lines of input and sending them to the interpreter, e.g.,
#v+
      while (EOF != fgets (buf, sizeof (buf), stdin))
        {
           if (-1 == SLang_load_string (buf))
             SLang_restart (1);
           SLang_Error = 0;
        }
#v-

  Finally, some applications such as \jed and \slrn use another method of
  interacting with the interpreter.  They read key sequences from the
  keyboard and map those key sequences to interpreter functions via
  the \slang keymap interface.

#%}}}

\sect{Intrinsic Functions} #%{{{

  An intrinsic function is simply a function that is written in C and
  is made available to the interpreter as a built-in function.  For
  this reason, the words `intrinsic' and `built-in' are often used
  interchangeably.

  Applications are expected to add application specific functions to
  the interpreter.  For example, \jed adds nearly 300 editor-specific
  intrinsic functions.  The application designer should think
  carefully about what intrinsic functions to add to the interpreter.

\sect1{Restrictions on Intrinsic Functions} #%{{{

  When implementing intrinsic functions, it is necessary to follow a
  few rules to cooperate with the interpreter.

  The C version of an intrinsic function takes only pointer arguments.
  This is because when the interpreter calls an intrinsic function, it
  passes values to the function by reference and \em{not} by value. For
  example, intrinsic with the declarations:
#v+
     int intrinsic_0 (void);
     int intrinsic_1 (char *s);
     void intrinsic_2 (char *s, int *i);
     void intrinsic_3 (int *i, double *d, double *e);
#v-
  are all valid.  However, 
#v+
     int invalid_1 (char *s, int len);
#v-
  is not valid since the \var{len} parameter is not a pointer.
  
  The return value of an intrinsic function must be one of the
  following types: \var{void}, \var{char}, \var{short}, \var{int},
  \var{long}, \var{double}, \var{char *}, as well as unsigned versions
  of the integer types.  A function such as 
#v+
    int *invalid (void);
#v-
  is not permitted since \var{int*} is not a valid return-type for an
  intrinsic function.  Any other type of value can be passed back to
  the interpreter by explicitly pushing the object onto the
  interpreter's stack via the appropriate "push" function.

  The current implementation limits the number of arguments of an
  intrinsic function to \exmp{7}.  The "pop" functions can be used to
  allow the function to take an arbitrary number as seen from an
  interpreter script.

  Another restriction is that the intrinsic function should regard all its
  parameters as pointers to constant objects and make no attempt to
  modify the value to which they point.  For example,
#v+
      void truncate (char *s)
      {
         s[0] = 0;
      }
#v-
  is illegal since the function modifies the string \var{s}.


#%}}}

\sect1{Adding a New Intrinsic} #%{{{

  There are two basic mechanisms for adding an intrinsic function to the
  interpreter: \cfun{SLadd_intrinsic_function} and
  \cfun{SLadd_intrin_fun_table}.  Functions may be added to a specified
  namespace via \cfun{SLns_add_intrinsic_function} and
  \cfun{SLns_add_intrin_fun_table} functions.

  As an specific example, consider a function that will cause the
  program to exit via the \var{exit} C library function.  It is not
  possible to make this function an intrinsic because it does not meet
  the specifications for an intrinsic function that were described
  earlier.  However, one can call \var{exit} from a function that is
  suitable, e.g.,
#v+
     void intrin_exit (int *code)
     {
        exit (*code);
     }
#v-
  This function may be made available to the interpreter as an
  intrinsic via the \cfun{SLadd_intrinsic_function} routine:
#v+
     if (-1 == SLadd_intrinsic_function ("exit", (FVOID_STAR) intrin_exit,
                                         SLANG_VOID_TYPE, 1,
                                         SLANG_INT_TYPE))
       exit (EXIT_FAILURE);
#v-
  This statement basically tells the interpreter that
  \var{intrin_exit} is a function that returns nothing and takes a
  single argument: a pointer to an integer (\var{SLANG_INT_TYPE}).
  A user can call this function from within the interpreter
  via
#v+
     message ("Calling the exit function");
     exit (0);
#v-
  After printing a message, this will cause the \var{intrin_exit}
  function to execute, which in turn calls \var{exit}.
  
  The most convenient mechanism for adding new intrinsic functions is
  to create a table of \cfun{SLang_Intrin_Fun_Type} objects and add the