home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / spplib_1 / spplib / ReadMe
Encoding:
Text File  |  1997-08-05  |  4.8 KB  |  119 lines
  1.                           USER MANUAL FOR SPPLIB
  2.                           =======================
  3.  
  4.                                          Version 0.1
  5.                                  G.C.Wraith, August 1997
  6.  
  7. SPPLIB is a Simple PreProcessor C Library. Preprocessors work
  8. line by line, which makes it feasible to have an input function,
  9. spp_fgets, which performs the same function as fgets in stdio.h,
  10. but which, in addition, preprocesses the input. This preprocessor
  11. is simpler, and more general, than the usual C preprocessor. Its
  12. directives are described below.
  13.  
  14. SPPLIB consists of this text file, a header file h.spp, and an Acorn
  15. Library Format (ALF) file o.spp, and a simple example of a C program
  16. Example.c.test. This shows how to use the functions spp_init and spp_fgets
  17. to write a minimal preprocessor using SPPLIB.
  18.  
  19. These files are not in the public domain; they belong to me. They are
  20. freeware in the sense that you may distribute and use them freely, and 
  21. need not pay for them. You may not, however, (1) distribute modified
  22. copies, or (2) make money from the programs or documentation in
  23. any way. You may, of course, modify your own copy; but you must
  24. not then distribute it. If you have modifications that you think  are 
  25. improvements, please get in touch with me at the address below and tell 
  26. me more. It is quite likely that there are features and bugs which I have 
  27. not yet discovered. The code is StrongArm compatible.
  28.  
  29. SPPLIB provides three functions:
  30.  
  31. extern void spp_init(char *fname);    /* initialise - use before the others. Do
  32.                                                              not use again until spp_fgets returns
  33.                                                              0 or spp_fclose is called.*/
  34. extern int  spp_fgets(char *buf);        /* read a line of preprocessed
  35.                                                               input into buf - returns 0 when no more */
  36. extern int spp_fclose(void);               /* shut-down - only needed for error
  37.                                                               handling as spp_fgets will have closed all
  38.                                                               the files by the time it returns 0 */
  39.  
  40. SPP
  41. ===
  42. SPP is not aimed specifically at C, which may make some of its behaviour
  43. appear odd to those who are familiar with the C preprocessor. The aim
  44. is for it to be useful for language writers. However, some syntactic choices
  45. have to be made.
  46.  
  47. Comments
  48. --------------
  49. SPP removes comments, which have the same syntax as comments
  50. C++; that is:
  51.  
  52.     1) single line comments, introduced by // and terminated by the end of
  53.         the line or the end of the file.
  54.  
  55.     2) multiline comments, introduced by /* and terminated by */. Multiline
  56.         comments are not nestable. 
  57.  
  58. Strings
  59. ---------
  60. SPP will complain if double-quotes (") do not occur in pairs. However, strings
  61. are not recognised as single tokens, so that double-quotes will not hide comment
  62. initiators and terminators.
  63.  
  64. Directives
  65. -------------
  66. SPP directives must be placed at the beginning of the line, with no preceding
  67. whitespace. If they take an argument they must be separated from it by whitespace.
  68. They are:
  69.  
  70. #include <filename>   
  71.  
  72.              Include the file specified by <filename>. Note that <filename>
  73.              can be any valid file descriptor in Risc OS, e.g
  74.  
  75.                               #include MyVar:mydir.myfile
  76.  
  77.               #includes can be nested up to 8 deep.
  78.  
  79. #define <macroname> <macrobody>    
  80.  
  81.               The syntax for macros follows that of Risc OS. <macroname> must
  82.               not contain whitespace, but <macrobody> can. Formal parameters
  83.               occur in <macrobody> as %0, %1, ... %9 just as in Obey files. %*n 
  84.               stands for all the arguments from the n-th one onwards. Macro
  85.               substitution converts %% to %. When macro substitution takes place
  86.               the argument list is a string of space-separated items following the
  87.               macro's name. Beware of invisible, but significant, whitespace at the
  88.               end of macro bodies.
  89.  
  90.               Example:
  91.  
  92.                           #define abs (%0)?(%0):(-%0)
  93.  
  94.                           y = abs x ;
  95.  
  96.               Note the necessary space between x and ;.
  97.               Macro substitution does not take place within SPP directives.
  98.  
  99. #undef <macroname>
  100.  
  101.               Undefine the macro called <macroname>.
  102.  
  103. #ifdef <macroname>
  104. #ifndef <macroname>
  105. #else
  106. #endif
  107.  
  108.              Conditional inclusion or exclusion of text. 
  109.              The #if(n)def/#endif constructs may be nested up to 8  deep.
  110.  
  111. Errors
  112. --------
  113. SPP will produce error messages indicating the file and line on which the
  114. error occurred.
  115. ----------------------------------------------------------------------------------------------
  116. Gavin Wraith
  117. mailto: gavin@wraith.u-net.com
  118. http://www.wraith.u-net.com/
  119.