cslang.txt

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

  S-Lang Library C Programmer's Guide, V1.4.9
  John E. Davis, [e-mail]
  Mar 23, 2003
  ____________________________________________________________

  Table of Contents

   Preface

  1. A Brief History of S-Lang
  2. Acknowledgements
  2. Introduction
  2. Interpreter Interface
  3. Embedding the Interpreter
  4. Calling the Interpreter
     4.1 Loading Files
     4.2 Loading Strings

  5. Intrinsic Functions
     5.1 Restrictions on Intrinsic Functions
     5.2 Adding a New Intrinsic
     5.3 More Complicated Intrinsics

  6. Intrinsic Variables
  7. Aggregate Data Objects
     7.1 Arrays
     7.2 Structures
        7.2.1 Interpreter Structures
        7.2.2 Intrinsic Structures
        7.2.2 Keyboard Interface

  8. Initializing the Keyboard Interface
  9. Resetting the Keyboard Interface
  10. Initializing the SLkp Routines
  11. Setting the Interrupt Handler
  12. Reading Keyboard Input with SLang_getkey
  13. Reading Keyboard Input with SLkp_getkey
  14. Buffering Input
  15. Global Variables
  15. Screen Management
  16. Initialization
  17. Resetting SLsmg
  18. Handling Screen Resize Events
  19. SLsmg Functions
     19.1 Positioning the cursor
     19.2 Writing to the Display
     19.3 Erasing the Display
     19.4 Setting Character Attributes
     19.5 Lines and Alternate Character Sets
     19.6 Miscellaneous Functions

  20. Variables
  21. Hints for using SLsmg
  21. Signal Functions
  21. Searching Functions
  22. Regular Expressions
  23. Simple Searches
  24. Initialization
  25. SLsearch
  25. Copyright
  A. The GNU Public License
  B. The Artistic License


  ______________________________________________________________________

  1.  Preface



  S-Lang is an interpreted language that was designed from the start to
  be easily embedded into a program to provide it with a powerful
  extension language.  Examples of programs that use S-Lang as an
  extension language include the jed text editor, the slrn newsreader,
  and sldxe (unreleased), a numerical computation program.  For this
  reason, S-Lang does not exist as a separate application and many of
  the examples in this document are presented in the context of one of
  the above applications.

  S-Lang is also a programmer's library that permits a programmer to
  develop sophisticated platform-independent software.  In addition to
  providing the S-Lang extension language, the library provides
  facilities for screen management, keymaps, low-level terminal I/O,
  etc.  However, this document is concerned only with the extension
  language and does not address these other features of the S-Lang
  library.  For information about the other components of the library,
  the reader is referred to the The S-Lang Library Reference.


  1.1.  A Brief History of S-Lang



  I first began working on S-Lang sometime during the fall of 1992.  At
  that time I was writing a text editor (jed), which I wanted to endow
  with a macro language.  It occured to me that an application-
  independent language that could be embedded into the editor would
  prove more useful because I could envision embedding it into other
  programs.  As a result, S-Lang was born.

  S-Lang was originally a stack language that supported a postscript-
  like syntax.  For that reason, I named it S-Lang, where the S was
  supposed to emphasize its stack-based nature.  About a year later, I
  began to work on a preparser that would allow one to write using a
  more traditional infix syntax making it easier to use for those
  unfamiliar with stack based languages.  Currently, the syntax of the
  language resembles C, nevertheless some postscript-like features still
  remain, e.g., the `%' character is still used as a comment delimiter.



  1.2.  Acknowledgements



  Since I first released S-Lang, I have received a lot feedback about
  the library and the language from many people.  This has given me the
  opportunity and pleasure to interact with several people to make the
  library portable and easy to use.  In particular, I would like to
  thank the following individuals:

  Luchesar Ionkov <[e-mail]> for his comments and criticisms of
  the syntax of the language.  He was the person who made me realize
  that the low-level byte-code engine should be totally type-
  independent.  He also improved the tokenizer and preparser and
  impressed upon me that the language needed a grammar.

  Mark Olesen <[e-mail]> for his many patches to
  various aspects of the library and his support on AIX. He also
  contributed a lot to the pre-processing (SLprep) routines.

  John Burnell <[e-mail]> for the OS/2 port of the video and
  keyboard routines.  He also made value suggestions regarding the
  interpreter interface.

  Darrel Hankerson <[e-mail]> for cleaning up and
  unifying some of the code and the makefiles.

  Dominik Wujastyk <[e-mail]> who was always willing to test
  new releases of the library.

  Michael Elkins <[e-mail]> for his work on the curses
  emulation.

  Ulli Horlacher <[e-mail]> and Oezguer Kesim <[e-mail]-
  berlin.de> for the S-Lang newsgroup and mailing list.

  Hunter Goatley, Andy Harper <[e-mail]>, and Martin P.J.
  Zinser <[e-mail]> for their VMS support.

  Dave Sims <[e-mail]> and Chin Huang <[e-mail]> for
  Windows 95 and Windows NT support.

  Lloyd Zusman <[e-mail]> and Rich Roth <[e-mail]> for
  creating and maintaining www.s-lang.org.

  I am also grateful to many other people who send in bug-reports and
  bug-fixes, for without such community involvement, S-Lang would not be
  as well-tested and stable as it is.  Finally, I would like to thank my
  wife for her support and understanding while I spent long weekend
  hours developing the library.



  2.  Introduction



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


  o  Low level tty input routines for reading single characters at a
     time.

  o  Keymap routines for defining keys and manipulating multiple
     keymaps.

  o  A high-level keyprocessing interface (SLkp) for handling function
     and arrow keys.

  o  High level screen management routines for manipulating both
     monochrome and color terminals.  These routines are very efficient.
     (SLsmg)

  o  Low level terminal-independent routines for manipulating the
     display of a terminal. (SLtt)

  o  Routines for reading single line input with line editing and recall
     capabilities. (SLrline)

  o  Searching functions: both ordinary searches and regular expression
     searches. (SLsearch)

  o  An embedded stack-based language interpreter with a C-like syntax.


  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 S-Lang's
  keyboard input routines--- one can use a different keyboard getkey
  routine if one desires.  This also means that linking to only part of
  the S-Lang library does not pull the whole library into the
  application.  Thus, S-Lang applications tend to be relatively small in
  comparison to programs that use libraries with similar capabilities.



  3.  Interpreter Interface



  The S-Lang 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 S-Lang 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.


  3.1.  Embedding the Interpreter



  Only one function needs to be called to embed the S-Lang interpreter
  into an application: SLang_init_slang.  This function initializes the
  interpreter's data structures and adds some intrinsic functions:


             if (-1 == SLang_init_slang ())
               exit (EXIT_FAILURE);



  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


            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);



  If you intend to enable all intrinsic functions, then it is simpler to
  initialize the interpreter via


            if (-1 == SLang_init_all ())
              exit (EXIT_FAILURE);



  See the \slang-run-time-library for more information about the intrin-
  sic functions.



  3.2.  Calling the Interpreter



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


  3.2.1.  Loading Files

  The SLang_load_file and 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 SLang_restart function to set the interpreter to its
  default state, and setting SLang_Error to 0, e.g.,


            if (-1 == SLang_load_file ("site.sl"))
              {
                 /* Clear the error and rest the interpreter */
                 SLang_restart (1);
                 SLang_Error = 0;
              }



  When a file is loaded via 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 SLns_load_file function may be used
  to load a file using a specified namespace, e.g.,


            if (-1 == SLns_load_file ("site.sl", "NS"))
              {
                SLang_restart (1);
                SLang_Error = 0;
              }



  will load site.sl into a namespace called NS.  If such a namespace
  does not exist, then it will be created.

  Both the SLang_load_file and SLns_load_file functions search for files
  along an application-specified search path.  This path may be set
  using the SLpath_set_load_path function, as well as from interpeted
  code via the 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 "./" or "../", 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 ".sl" and ".slc" appended to the filename.  If two such
  files are found (one ending with ".sl" and the other with ".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 SLpath_set_delimiter and SLpath_get_delimiter may be used to set
  and query the delimiter's value, respectively.


  3.2.2.  Loading Strings

  There are several other mechanisms for interacting with the
  interpreter.  For example, the SLang_load_string function loads a
  string into the interpreter and interprets it:


           if (-1 == SLang_load_string ("message (\"hello\");"))
             {
               SLang_restart (1);
               SLang_Error = 0;
             }



  Similarly, the SLns_load_string function may be used to load a string
  into a specified namespace.

  Typically, an interactive application will load a file via
  SLang_load_file and then go into a loop that consists of reading lines
  of input and sending them to the interpreter, e.g.,


             while (EOF != fgets (buf, sizeof (buf), stdin))
               {
                  if (-1 == SLang_load_string (buf))
                    SLang_restart (1);
                  SLang_Error = 0;
               }



  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
  S-Lang keymap interface.



  3.3.  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.


  3.3.1.  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.