home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / preproz / langref.doc < prev    next >
Text File  |  1990-03-27  |  83KB  |  1,729 lines

  1.            James Roskind C Porting Preprocessor (JRCPP)
  2.  
  3.              JRCPP LANGUAGE REFERENCE MANUAL (3/23/90)
  4.  
  5.  
  6.  
  7.     Copyright (C) 1990 James Roskind, All rights reserved. Permission 
  8.     is  granted  to copy and distribute this file as part any machine 
  9.     readable archive containing the entire, unmodified, JRCPP  PUBLIC 
  10.     DISTRIBUTION PACKAGE (henceforth call the "Package").  The set of 
  11.     files that form the Package are described in the README file that 
  12.     is  a  part  of the Package.  Permission is granted to individual 
  13.     users of the Package to copy individual portions of  the  Package 
  14.     (i.e.,  component  files) in any form (e.g.: printed, electronic, 
  15.     electro-optical, etc.) desired  for  the  purpose  of  supporting 
  16.     users   of  the  Package  (i.e.,  providing  online,  or  onshelf 
  17.     documentation access; executing the  binary  JRCPP  code,  etc.).  
  18.     Permission  is  not  granted  to  distribute copies of individual 
  19.     portions of the Package, unless a machine readable version of the 
  20.     complete  Package  is also made available with such distribution. 
  21.     Abstracting with credit is permitted.   There  is  no  charge  or 
  22.     royalty  fee  required  for  copies  made in compliance with this 
  23.     notice.  To otherwise copy  elements  of  this  package  requires 
  24.     prior permission in writing from James Roskind.
  25.  
  26.     James Roskind
  27.     516 Latania Palm Drive
  28.     Indialantic FL 32903
  29.  
  30.     End of copyright notice
  31.  
  32.  
  33. What  the  above  copyright  means  is  that  you are free to use and 
  34. distribute (or even sell) the entire set of files  in  this  Package, 
  35. but  you  can't split them up, and distribute them as separate files.  
  36. The notice also says that you  cannot  modify  the  copies  that  you 
  37. distribute, and this ESPECIALLY includes NOT REMOVING the any part of 
  38. the copyright notice in any file.  JRCPP  currently  implements  a  C 
  39. Preprocessor,  but  the  users  of  this Package do NOT surrender any 
  40. right of ownership or copyright to any source text that is  processed 
  41. by JRCPP, either before or after processing.  Similarly, there are no 
  42. royalty or fee requirements for using the post-preprocessed output of 
  43. JRCPP.  
  44.  
  45. This  Package is expected to be distributed by shareware and freeware 
  46. channels (including BBS sites), but the fees paid for  "distribution" 
  47. costs  are  strictly  exchanged  between  the  distributor,  and  the 
  48. recipient, and James Roskind makes no express or  implied  warranties 
  49. about  the  quality  or integrity of such indirectly acquired copies.  
  50. Distributors  and  users  may  obtain   the   Package   (the   Public 
  51. distribution form) directly from the author by following the ordering 
  52. procedures in the REGISTRATION file.
  53.  
  54.  
  55. DISCLAIMER:
  56.  
  57. JAMES ROSKIND PROVIDES THIS FILE "AS  IS"  WITHOUT  WARRANTY  OF  ANY 
  58. KIND,  EITHER  EXPRESS  OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE 
  59. IMPLIED WARRANTIES OF MERCHANTABILITY OR  FITNESS  FOR  A  PARTICULAR 
  60. PURPOSE.   THE  ENTIRE  RISK AS TO THE QUALITY AND PERFORMANCE OF THE 
  61. PROGRAM AND DOCUMENTATION IS WITH YOU.   Some  states  do  not  allow 
  62. disclaimer  of express or implied warranties in certain transactions, 
  63. therefore, this statement may not apply to you.
  64.  
  65.  
  66. UNIX is a registered trademark of AT&T Bell Laboratories.
  67. ____________________________________________________________________
  68.  
  69.  
  70.  
  71.            James Roskind C Porting Preprocessor (JRCPP)
  72.  
  73.         JRCPP LANGUAGE REFERENCE MANUAL
  74.  
  75. INTRODUCTION
  76.  
  77. This document, in the company of the "ANSI  Programming  Language  C" 
  78. Standard,  is  intended  to act as a language reference manual.  Most 
  79. significantly, this document discusses the performance  of  JRCPP  in 
  80. official    "ANSI    undefined",   "ANSI   unspecified"   and   "ANSI 
  81. implementation defined" domains of the C Language.  In  addition,  it 
  82. lists  performance  limitations  of JRCPP, and directly relates these 
  83. limitations  to  the  standard's  requirements  for   "Implementation 
  84. limits".
  85.  
  86. As an additional matter, this document identifies vaguenesses (and in 
  87. the rare case, errors) in the ANSI  C  Standard,  and  describes  the 
  88. resolution  adopted  by  JRCPP.   Hence  this  document  is  also the 
  89. "Rationale" for JRCPP, in much the same way the the ANSI  C  standard 
  90. has  an accompanying document "Rational For ANSI Programming Language 
  91. C".  This document will generally not discuss aspects of the standard 
  92. that  do  not  involve  preprocessing  activities performed on source 
  93. files.
  94.  
  95. Note that this document was written based on the Draft Proposed  ANSI 
  96. C  Standard,  X3J11/88-158, date December 8, 1988.  After a drawn out 
  97. appeals process, I believe this draft was accepted in January 1990 by 
  98. the  ANSI  Standards Committee.  I am not aware that any changes were 
  99. made during that appeals process, and I apologize in advance for  any 
  100. errors  I  might have made in this regard, or in the description that 
  101. follows.
  102.  
  103. In all cases where this Language Reference Manual deviates  from  the 
  104. ANSI  C Standard, this document should be assumed to be in error, and 
  105. the corresponding bug/misperformance in the JRCPP  program  (if  any) 
  106. should  be  reported.   The  ANSI C Standard a tremendous work, and I 
  107. realize that my abridged commentary in many areas does not do justice 
  108. to  the  meticulous  selection  of  elaborate wording in the official 
  109. Standard.  For many, my description will be enough, but for  language 
  110. lawyers, there is no replacement for the official ANSI document.
  111.  
  112. Section  numbers  in this document have been chosen to match those of 
  113. the ANSI C standard, and hence certain gaps are present.  These  gaps 
  114. represent  areas  where  either  there  is  generally  no  impact  on 
  115. preprocessing activities, or no additional commentary seems necessary.
  116.  
  117. LISTING OF SECTIONS
  118.  
  119. 1.3 References
  120. 1.6 Definition of Terms
  121. 2. ENVIRONMENT
  122. 2.1.1.2 ENVIRONMENT- Translation phases
  123. 2.1.1.3 ENVIRONMENT- Diagnostics
  124. 2.2  ENVIRONMENTAL CONSIDERATION
  125. 2.2.1 ENVIRONMENTAL CONSIDERATION- Character sets
  126. 2.2.1.1 ENVIRONMENTAL CONSIDERATION- Trigraphs Sequences
  127. 2.2.1.3 ENVIRONMENTAL CONSIDERATION- Character sets- Multibyte characters
  128. 2.2.4 ENVIRONMENTAL CONSIDERATION- Translation Limits
  129. 3.1 LANGUAGE- LEXICAL ELEMENTS
  130. 3.1.2 LANGUAGE- LEXICAL ELEMENTS- Identifiers
  131. 3.1.3.3 LANGUAGE- LEXICAL ELEMENTS- Character constants
  132. 3.1.4 LANGUAGE- LEXICAL ELEMENTS- String literals
  133. 3.1.7 LANGUAGE- LEXICAL ELEMENTS- Header names
  134. 3.1.8 LANGUAGE- LEXICAL ELEMENTS- Preprocessing numbers
  135. 3.8 LANGUAGE- PREPROCESSING DIRECTIVES
  136. 3.8.1 LANGUAGE- PREPROCESSING DIRECTIVES- Conditional inclusion
  137. 3.8.2 LANGUAGE- PREPROCESSING DIRECTIVES- Source file inclusion
  138. 3.8.3 LANGUAGE- PREPROCESSING DIRECTIVES- Macro replacement
  139. 3.8.3.2 LANGUAGE- PREPROCESSING DIRECTIVES- The # operator
  140. 3.8.3.3 LANGUAGE- PREPROCESSING DIRECTIVES- The ## operator
  141. 3.8.3.5 LANGUAGE- PREPROCESSING DIRECTIVES- Scope of macro definitions
  142. 3.8.4 LANGUAGE- PREPROCESSING DIRECTIVES- Line control
  143. 3.8.6 LANGUAGE- PREPROCESSING DIRECTIVES- Pragma directive
  144. 3.8.8 LANGUAGE- PREPROCESSING DIRECTIVES- Predefined macro names
  145.  
  146.  
  147. 1.3 References
  148.  
  149. In addition to the 6 references listed  in  the  standard  (the  most 
  150. significant  of  which  is  probably  "The  C  Reference  Manual", by 
  151. Kernighan  and  Ritchie),  an  additional  reference  set  should  be 
  152. considered.   Since  JRCPP is intended to support many dialects of C, 
  153. as well as C++, references for C++ are:
  154.  
  155. "The C++ Programming Language", by Bjarne Stroustrup, Addison-Wessley 
  156. (1986), Copyright Bell Telephone Laboratories Inc.
  157.  
  158. "The  Annotated C++ Reference Manual" by Margaret A. Ellis and Bjarne 
  159. Stroustrup, Addison-Wessley (to be published).
  160.  
  161.  
  162. 1.6 Definition of Terms
  163.  
  164. Among the 17 terms defined in this section (such  as  "bit",  "byte", 
  165. "argument" "parameter"...) which are certainly crucial to a reference 
  166. manual, there are also several terms which identify the focus of this 
  167. manual.  The  definition  are for the phrases "Unspecified behavior", 
  168. "Undefined behavior",  and  "Implementation  defined  behavior".  The 
  169. following are my interpretations of these definitions:
  170.  
  171. "Unspecified  behavior":  Although  the  source  code  is  considered 
  172. correct, the standard has no requirements on any implementation.   An 
  173. example  of  this, is the precedence for the paste (##) and stringize 
  174. operators. Notice that it is not even required that an implementation 
  175. be CONSISTENT in its handling of this issue!
  176.  
  177. "Undefined  behavior"  the  relevant source construct is not portable 
  178. ANSI C.  As a result, the implementation can  accept  or  reject  the 
  179. construct,  at  any point in time from preprocessing and compilation, 
  180. through bound execution.  Fundamentally  such  behavior  is  used  to 
  181. clearly identify non-portable source constructs.
  182.  
  183. "Implementation  defined  behavior":  The  relevant  source  code  is 
  184. considered  correct,  and  each  implementation  is  responsible  for 
  185. defining  the  behavior of that construct.  An example of this is the 
  186. number of significant  characters  in  identifier  names  (above  and 
  187. beyond what are required in a minimally ANSI C implementation).
  188.  
  189. The  above  definitions  will  be  referred  to  regularly during the 
  190. commentary on JRCPP, and its support for the ANSI C standard.
  191.  
  192.  
  193. 2. ENVIRONMENT
  194.  
  195. 2.1.1.2 ENVIRONMENT- Translation phases
  196.  
  197. This section describes the actual phases of translation of  C  source 
  198. code.   The  phases  also  serve  to  delineate  the  points  between 
  199. preprocessing, and compilation.  The  phases  may  be  summarized  as 
  200. follows:
  201.  
  202. Phase  1)  The  characters in the source are translated into those of 
  203. the "source character set".  During this process, JRCPP translates  8 
  204. bit characters into 7 bit characters, by ignoring the high order bit, 
  205. and by translating the source file characters 0 and 128  into  simple 
  206. spaces  (ASCII  32).  This phase also includes identification of line 
  207. delimiters, and the removal of trigraphs.  On  an  DOS/OS2  platform, 
  208. JRCPP     identifies     the     two     source    file    characters 
  209. <carriage-return><line-feed> as the terminator for each  line,  which 
  210. is  henceforth  referred  to  as  <newline>.   The ANSI Standard also 
  211. requires that complete trigraph removal be performed in  this  phase, 
  212. and  JRCPP  fully  supports this. Note that all diagnostics issued by 
  213. JRCPP are based upon line counts generated in this phase,  and  hence 
  214. most  editors  can  be  used  to  move  to  the  line identified in a 
  215. diagnostic.
  216.  
  217. Phase 2) All occurrences of a backslash  followed  immediately  by  a 
  218. <newline>   are   removed.    This  removal  "splices"  together  the 
  219. consecutive lines that were  only  separated  by  this  "escaped  out 
  220. newline".   This  process  may  also  be  seen  as  combining several 
  221. physical lines, as viewed by an editor, into  a  long  logical  line. 
  222. This  activity  is most useful for programmers that wish to have many 
  223. characters on a single source line, in order to,  for  example,  make 
  224. them part of a single preprocessing directive. The ANSI Standard also 
  225. requires that every non-empty source file end in a newline,  that  is 
  226. not escaped by a backslash (JRCPP diagnoses these conditions).
  227.  
  228. Notice  that phase 1 is complete before phase 2 is started. Hence the 
  229. removal of an escaped  newline  CANNOT  create  a  trigraph  that  is 
  230. eligible for translation.
  231.  
  232. Phase  3) This phase of translation is referred to as "tokenization".  
  233. In this phase, sequences of  characters  are  gathered  together  for 
  234. processing as whole units (tokens).  This phase also defines comments 
  235. to be interpreted as equivalent to  a  single  space  character.  The 
  236. standard allows implementations to consider consecutive (non-newline) 
  237. whitespace  (space,  tab,  page  feed,  lone  carriage   return)   as 
  238. equivalent to single spaces.  The ANSI Standard also specifies that a 
  239. source file cannot end in either a partial (unterminated) comment, or 
  240. in  a  partial preprocessing token.  (JRCPP diagnoses an unterminated 
  241. comment at the end of a file).
  242.  
  243. Note that since comments and tokens are  removed  at  the  same  time 
  244. (i.e.:  via  a  single  left  to  right scan for the largest possible 
  245. lexical  group),  there  is  some   contention   between   "otherwise 
  246. overlapping"  string  literals,  character  constants,  and comments.  
  247. This contention is always resolved by accepting the largest  possible 
  248. token (or comment) before allowing a new token to begin. For example, 
  249. the following is a pair of comments surrounding an identifier:
  250.  
  251.    /* ignore " inside comment*/ identifier /* still ignore " in comment*/
  252.  
  253. Hence we see that not only don't comments nest, but  string  literals 
  254. do  not  form  tokens  within  comments  (and hence cannot "hide" the 
  255. comment  terminator).   Similarly,  the  following  is  a   pair   of 
  256. consecutive string literals:
  257.  
  258.     "comments begin /* outside"     " and end with the */ sequence"
  259.  
  260. This  example  shows  that comments are not scanned for within string 
  261. literals (and hence cannot "hide" the terminal close quote). Finally, 
  262. the following is the sum of two character constants,
  263.  
  264.     '"'    +    '"'
  265.  
  266. Which  demonstrates  that  neither  are  character  constants scanned 
  267. internal for any other  extended  sequences  (such  as  comments  are 
  268. literals).
  269.  
  270. The standard does have the confusing phrase: "a source file shall not 
  271. end in a partial preprocessing token", as part of its description  of 
  272. this  phase.  Recall  that  phase  2 ensured that the file ended in a 
  273. carriage return, which  "terminates"  any  preprocessing  token!   It 
  274. appears  impossible to have a "non-terminated preprocessing token" at 
  275. the end of a file. There is a CHANCE that the standard meant  to  say 
  276. "shall not terminate in a partial preprocessing #if directive group", 
  277. but this would not make sense as such items are not identified  until 
  278. later phases.  Finally there is the possibility that this requirement 
  279. was installed in the Standard before the agreement was reached that a 
  280. file  should not end in an escaped newline (re: phase 2 requirement), 
  281. and then (accidentally) never  taken  out.   We  assume  this  latter 
  282. interpretation  is  correct, and we ignore the constraint on "partial 
  283. preprocessing token at end of file".
  284.  
  285. JRCPP  adopts  the  aforementioned  policy  allowing   sequences   of 
  286. non-newline  whitespaces  to  be  equivalent  to  a single space, and 
  287. compacts comments and whitespace into single spaces.  It is  critical 
  288. to  note  that the fact that, "comments are NOT removed prior to this 
  289. phase", means that a program cannot "comment out" trigraph sequences, 
  290. or  any  activity  performed in the earlier phases.  In addition, the 
  291. fact that comments are removed in this phase  means  that  constructs 
  292. that  "look  like  comments"  in  later  phases  (e.g.:  after  macro 
  293. expansion activity) are not regarded as comments.
  294.  
  295. Finally, the fact that comments  are  translated  into  single  space 
  296. characters,  includes  the case where the comment contains a newline! 
  297. This specifically means that preprocessing directives  (discussed  in 
  298. next phase) are not terminated at the end of the line, if the newline 
  299. marking that point is within a  comment.   The  implication  of  this 
  300. should  be  clear  to  programmers  who  had  previously used a macro 
  301. definition of the following form on some non-ANSI compiler:
  302.  
  303.     #define start_comment  /*
  304.         code /* comment_text */ more_code
  305.  
  306.  
  307. The above lines do not define "start_comment" (as understood by later 
  308. phases)  to  be  the sequence "/*".  In the above sample, the "/* and 
  309. all characters up until the comment terminator  "*/",  are  compacted 
  310. into a single space.  Since the next comment terminator occurs on the 
  311. next line of the example, the above code is equivalent to:
  312.  
  313.     #define  start_comment more_code
  314.  
  315. On the brighter side, JRCPP would have issued  a  warning  about  the 
  316. above sequence as having a "/*" within a comment.
  317.  
  318.  
  319. Phase 4) In phase 4, the tokens are parsed (grouped together) to form 
  320. preprocessing directives and source  code.   This  activity  includes 
  321. establishing  and  maintaining  a database of macros (re: #define and 
  322. #undef), conditionally including sections of source  code  (re:  #if, 
  323. #ifdef,  #ifndef,  #elif,  #else, #endif), inserting additional files 
  324. (re: #include), providing user supplied error messages (#error),  and 
  325. servicing  implementation  defined  directives  (#pragma).  Note that 
  326. when a #include directive  is  processed,  the  phases  1-4  are  all 
  327. applied to the source file as it is inserted.
  328.  
  329. Phase  5-8 of the ANSI Standard relate to phases of processing that I 
  330. would refer to as compilation and linking.  It  is  conceivable  that 
  331. the  concatenation  of  adjacent  string literals (phase 6) should be 
  332. considered as part of the preprocessing effort,  but  they  have  NOT 
  333. been included in JRCPP for two reasons:
  334.  
  335. Reason  1)  If  a  series of large string literals were concatenated, 
  336. then there is a good chance that the result would be  too  large  for 
  337. many  lexical  analysers (re: the first scanning phase of a compiler) 
  338. to handle.  I would prefer to produce code that is  acceptable  to  a 
  339. larger range of compilers.
  340.  
  341. Reason  2)  Hexadecimal  escape  sequences  have no termination mark.  
  342. Hence the concatenation of two  string  literals  may  be  MUCH  more 
  343. complex   than  concatenating  the  "sections  between  the  quotes".  
  344. (Example: "\x1" "b" is NOT the same as "\x1b".  Specifically, in most 
  345. in  DOS  environment,  "\x1"  "b"  is  the  same  as "\001" "\097" or 
  346. equivalently "\001\097", whereas "\x1b" is the same as "\033".) Since 
  347. hex  escape sequences have no terminator, an example such as what was 
  348. just given MUST be translated into a series of octal escape sequences 
  349. (at  least  the  trailing  hex  sequence  in the first literal must).  
  350. Unfortunately, the translation of  long  hex  escape  sequences  with 
  351. "equivalent"  octal  escape  sequences,  would  introduce  an area of 
  352. platform dependency that is  probably  best  avoided  in  a  portable 
  353. preprocessor.
  354.  
  355.  
  356. 2.1.1.3 ENVIRONMENT- Diagnostics
  357.  
  358. The standard requires that at least one diagnostic message be emitted 
  359. for every "violation  of  any  syntax  rule  or  constraint".   JRCPP 
  360. attempts to support this, with the two caveats that a) parsing of the 
  361. C language output is NOT performed, and associated error checking  is 
  362. not  provided.   As  an interesting example of this support, the user 
  363. should   note   that   special   JRCPP    features    (re:    #pragma 
  364. diagnostic_adjust)   allow   arbitrary   diagnostic  messages  to  be 
  365. "silenced".  In order to support the above ANSI  C  requirement,  the 
  366. first  such  adjustment  of  a  diagnostic  severity  level  CAUSES a 
  367. diagnostic to be issues. Hence at least that diagnostic  notification 
  368. is  present  no  matter  what  user  customizations  are  applied  to 
  369. diagnostics.
  370.  
  371.  
  372. 2.  ENVIRONMENTAL CONSIDERATION
  373.  
  374. 2.2.1 ENVIRONMENTAL CONSIDERATION- Character sets
  375.  
  376. The character set supported by  JRCPP  includes  the  full  range  of 
  377. characters that are required by the standard.  In addition, the ASCII 
  378. characters in the range 129 to 255 are interpreted  as  though  their 
  379. high  bit  of  an  eight  bit  byte was 0 (i.e., mapped into values 1 
  380. though 127), and the ASCII values 0 and 128  are  treated  as  spaces 
  381. (ASCII 32).
  382.  
  383. 2.2.1.1 ENVIRONMENTAL CONSIDERATION- Trigraphs Sequences
  384.  
  385. All the standard trigraph sequences are supported.  These include:
  386.  
  387. Trigraph      Equivalent Character
  388.  
  389.   ??=           #
  390.   ??(           [
  391.   ??/           \
  392.   ??)           ]
  393.   ??'           ^
  394.   ??<           {
  395.   ??!           |
  396.   ??>           }
  397.   ??-           ~
  398.  
  399. Here  again  it  is significant to recall that trigraph sequences are 
  400. replaced in the very first phase of translation.  Hence the following 
  401. is not a comment:
  402.  
  403.     ??/* test*/
  404.  
  405. as it is equivalent to:
  406.  
  407.     \* test*/
  408.  
  409. In a similar vein, the following obscure code has surprising meaning:
  410.  
  411.     "/control??/"        /* continue till "/* real comment */
  412.  
  413. as it is equivalent to:
  414.  
  415.     "/control\"        /* continue till "/* real comment */
  416.  
  417. Which is later tokenized as the long single string literal:
  418.  
  419.     "/control\"        /* continue till "
  420.  
  421.  
  422.  
  423.  
  424. 2.2.1.3   ENVIRONMENTAL   CONSIDERATION-  Character  sets-  Multibyte 
  425. characters
  426.  
  427. Other than support for the single byte  characters  required  in  the 
  428. standard,  multibyte  characters  are  not  specified or supported in 
  429. JRCPP. If multibyte characters are encountered, they are passed along 
  430. blindly, but they cannot be evaluated in any meaningful as a #if/elif 
  431. expression (a diagnostic is produced if such  an  attempt  is  made). 
  432. This stance is in keeping with the requirements of the standard.
  433.  
  434. 2.2.4 ENVIRONMENTAL CONSIDERATION- Translation Limits
  435.  
  436. This section of the standard requires that at least one program exist 
  437. that satisfies  all  of  the  limits,  and  can  be  translated.  The 
  438. following  are  the  limits  that  relate  to a preprocessor, and the 
  439. details of how to construct a program exercising those  limits.  Note 
  440. that  the  limits  are  very  easy  for  JRCPP to handle, and no true 
  441. "cunning" is required to generate a required test program.
  442.  
  443.  
  444. 8 nesting levels of conditional inclusion
  445.  
  446.     Currently about 38+ (see Appendix B of USERS MANUAL)  levels  are 
  447.     supported,  but  this  static  limit  may  be  removed  in future 
  448.     releases.
  449.  
  450. 32  nesting  levels  of  parenthesized  expressions  within  a   full 
  451. expression
  452.  
  453.     The parsing stack for evaluation of preprocessor is currently set 
  454.     at 150 (see Appendix B of USERS MANUAL) levels.  At a minimum, it 
  455.     would require 150 non-white  tokens  (not  just  characters,  but 
  456.     whole tokens) on a preprocessing #if line to cause a parser stack 
  457.     overflow.  Lines less than 150 tokens cannot cause  an  overflow, 
  458.     but  the  absolute  limit on parenthesis nesting depends upon the 
  459.     number of additional operators, along with their  precedence  and 
  460.     placement.   Any  demonstration program that that has expressions 
  461.     that      "tower      to      the      left",      such       as: 
  462.     "((((((...(((5+4)*3-3)+.../7)|6-8)+1",  and  has  less than about 
  463.     130 nested parenthesis, should also be acceptable to JRCPP.
  464.  
  465. 31 significant initial characters in an identifier name
  466.  
  467.     All  identifiers  are  considered  significant   in   all   their 
  468.     characters,  which  may  extend  well  beyond 31 characters.  See 
  469.     Appendix B  of  USERS  MANUAL  for  actual  restrictions  an  the 
  470.     absolute length of identifiers.
  471.  
  472. 511 External identifier names in one translation unit
  473.  
  474.     JRCPP  has  no static limit on the number of distinct identifiers 
  475.     of any type.
  476.  
  477. 1024 Macro identifier simultaneously defined in one translation unit
  478.  
  479.     JRCPP has no static limit on the number of macros defined.
  480.  
  481. 31 Parameters in one macro definition
  482.  
  483.     JRCPP has no static limit on  the  number  of  parameters  for  a 
  484.     function like macro.
  485.  
  486. 31 Arguments in one macro invocation
  487.  
  488.     JRCPP  has no static limit on the number of arguments supplied to 
  489.     a macro invocation.
  490.  
  491. 509 Characters in a logical source line
  492.  
  493.     JRCPP has no static limit on the number of characters in a source 
  494.     line.   There  is a limit on the number of characters in a single 
  495.     token, but there is no limit on the number of tokens on  a  line. 
  496.     (see Appendix B of USERS MANUAL).
  497.  
  498. 509 Characters in a string literal (after concatenation)
  499.  
  500.     Since JRCPP does not currently perform string concatenation, this 
  501.     limit does not generally apply.  The limit on  the  length  of  a 
  502.     single  token applies to individual string literals (see Appendix 
  503.     B of USERS MANUAL).
  504.  
  505. 8 levels of nested #include
  506.  
  507.     JRCPP has no static limit on the number of nested include  files. 
  508.     To  support  this  (no  limit) stance, JRCPP does require that at 
  509.     least 2 file handles be made available to it, in addition to  the 
  510.     standard  set of stdin, stdout, stderr. See your operating system 
  511.     manual for details.  Note that there is a limit on the  depth  of 
  512.     nested  file  inclusion when the original source file is actually 
  513.     stdin. This limit is based on the operating system restriction on 
  514.     the  number  of  files  that  may  be open at one time.  This odd 
  515.     limitation may be removed in future  versions,  but  typical  DOS 
  516.     configurations  would  only  limit  nested  inclusion at about 16 
  517.     levels.
  518.  
  519.  
  520. 3.1 LANGUAGE- LEXICAL ELEMENTS
  521.  
  522. This section defines exactly how to interpret a series of  characters 
  523. as  tokens.  The  one  point  of  undefined  behavior in this section 
  524. concerns the presence of unmatched single (') or  double  (")  quotes 
  525. appearing  on  a  logical line.  JRCPP makes an effort to not abandon 
  526. compilation when it encounters errors, and its behavior in this  area 
  527. is typical of such resolutions.
  528.  
  529. In  the case of an unmatched single quote ('), JRCPP assumes that the 
  530. programmer forgot the quote, but assumes that only a single character 
  531. "character  constant"  was intended.  Hence for the purposes of error 
  532. recovery, the single quote and at most one  following  c-char  (which 
  533. includes single characters, and a select set of escape sequences, but 
  534. excludes  newlines)  is  accepted  as  a  character  constant.   This 
  535. construction  of  an  erroneous  is  performed  despite the fact that 
  536. without the terminal quote, the spelling of the token is invalid.
  537.  
  538. In the case of an unmatched double quote ("), JRCPP also assumes that 
  539. the  programmer forgot the quote.  In the case of string literals, it 
  540. is assumed that that most literals are fairly long.  For the purposes 
  541. of  error recovery, JRCPP assumes that the original quote, along with 
  542. the longest possible sequence of s-chars (a class of characters  that 
  543. includes single characters, and a select set of escape sequences, but 
  544. excludes newlines) formed the string literal.
  545.  
  546. Note that in both cases  diagnostics  are  generated  that  will,  by 
  547. default,  prevent  any preprocessed output from being generated.  The 
  548. default settings of these diagnostics can however be  overridden  for 
  549. the purposes of generating some output.
  550.  
  551.  
  552. 3.1.2 LANGUAGE- LEXICAL ELEMENTS- Identifiers
  553.  
  554. JRCPP  supports the standard definition of identifiers, consisting of 
  555. a leading alphabetic character (or  an  underscore),  and  continuing 
  556. with an arbitrary sequence of alphanumeric characters and underscores.
  557.  
  558. As  an  extension,  JRCPP also supports the presence of the character 
  559. '$' at any position (including first character) of an identifier, but 
  560. it  flags  such  usage  as an error.  Here again JRCPP can be seen to 
  561. comply    with    the    ANSI     requirements     for     diagnosing 
  562. nonportable/nonstandard constructs, while still allowing the user the 
  563. opportunity to ignore the error, and facilitate a  porting  operation 
  564. (note  that  the  default  diagnostic  level  of  such  an  error  is 
  565. sufficient to preclude output, but this level may be modified via the 
  566. #pragma adjust_diagnostic ... directive).  This extension does not in 
  567. any way conflict with the ANSI standard, as a '$' character,  outside 
  568. of  a  string literal or character constant token, is usually illegal 
  569. anyway. Hence incorporating it into an identifier does  not  preclude 
  570. any valid constructs.
  571.  
  572. In certain obscure cases, an ANSI conformant program might have a '$' 
  573. character  provided  outside  of  a  string  literal,  or   character 
  574. constant.   This  placement  is  only potentially legal if the '$' is 
  575. formed into part of a valid token by the  end  of  the  preprocessing 
  576. phases.  If  this  obscure  case  is  actually significant to a user, 
  577. modification of diagnostic levels can permit this construct.  If I am 
  578. pressed  by  registered  users,  I  may modify the performance of the 
  579. preprocessor to more naturally support such obscure ANSI C conformant 
  580. cases.
  581.  
  582. This  section  of  the  Standard  also  discusses the significance of 
  583. characters in an identifier name.  Specifically, it requires that all 
  584. of  the  first  31  characters  in  a  macro  name be considered when 
  585. comparing names  and  invocations.  In  order  to  support  the  many 
  586. existing implementations, the standard leaves as "undefined behavior" 
  587. whether identifiers that  differ  ONLY  beyond  the  31st  character.  
  588. JRCPP  resolves  this  simply  by  treating  all  characters  in  any 
  589. identifier name as significant.  This may  identify  as  errors  some 
  590. typos  that other compilers overlook, but this only tends to make the 
  591. code more robust in terms of portability.
  592.  
  593.  
  594.  
  595. 3.1.3.3 LANGUAGE- LEXICAL ELEMENTS- Character constants
  596.  
  597. In the discussion of character constants by the ANSI Standard, it  is 
  598. mentioned  that  when undefined escape sequences are encountered in a 
  599. character constant, the results are undefined.
  600.  
  601. Note that the defined  escape  sequences  for  use  within  character 
  602. constants include:
  603.  
  604.     '\\' (backslash),
  605.     '\'' (single quote),
  606.     '\"' (double quote),
  607.     '\?' (question mark),
  608.     '\a' (alarm or bell),
  609.     '\b' (backspace),
  610.     '\f' (form feed),
  611.     '\n' (newline), '
  612.     '\r' (carriage return),
  613.     '\t' (tab),
  614.     '\v' (vertical tab),
  615.     octal escape sequences with 1-3 octal digits, and
  616.     hexadecimal escape sequences with arbitrarily many hex digits.
  617.  
  618. Examples of the latter two types are: '\27', and '\xab10cd'.
  619.  
  620. When  JRCPP  finds  an  invalid  escape  sequence  within a character 
  621. constant (and there is a trailing quote found later on that line),  a 
  622. diagnostic  is  produced, but the character sequence is accepted as a 
  623. character  constant.   The  severity  level  of  the  diagnostic   is 
  624. sufficient to prevent the preprocessor from producing output, but the 
  625. level may be varied by the user if acceptance of  such  sequences  is 
  626. considered reasonable for the user's target compiler.
  627.  
  628.  
  629. 3.1.4 LANGUAGE- LEXICAL ELEMENTS- String literals
  630.  
  631. The  undefined  behavior  in  string literals is also centered on the 
  632. presence of illegal escape  sequences  within  the  literal.   In  an 
  633. analogous  fashion  to  the  handling  of  character  constants,  the 
  634. presence of illegal escape  sequences  generates  a  diagnostic,  but 
  635. (error  recovery)  accepts  the  sequence.   The default severity the 
  636. diagnostic is high enough that on output will not be produced by  the 
  637. preprocessor unless the level is adjusted downward.
  638.  
  639. 3.1.7 LANGUAGE- LEXICAL ELEMENTS- Header names
  640.  
  641. This section of the Standard discusses the lexical form of file names 
  642. that are used in #include directives.  The undefined behavior in this 
  643. area  involves  the  presence of the characters ', \, ", or /* within 
  644. the <....> form of an include directive, and the presence of ', \, or 
  645. /*  within  the  "...."  form  of  the directive.  Since the original 
  646. platform for JRCPP was DOS/OS2, the  defining  of  behavior  of  such 
  647. sequences  is  quite important (DOS and OS2 file systems use '\' as a 
  648. separator in path names, in the same way as UNIX systems use '/' as a 
  649. separator).   In  order  to  support the use of standard DOS/OS2 path 
  650. names, a header name is considered a special and distinct token.
  651.  
  652. JRCPP defines a "...." style header  name  to  begin  with  a  double 
  653. quote,  and  continue  until  a matching double quote is encountered, 
  654. without passing the newline.  Note  that  escape  sequences  are  NOT 
  655. honored  during  the  scanning  of  this  token,  and hence backslash 
  656. characters represent themselves directly (and the final quote  CANNOT 
  657. be  escaped  using a backslash).  In addition, since this is a single 
  658. token, the presence of /* within it is of no  consequence.  The  only 
  659. context  in  which  a  "...." style header name is permitted by JRCPP 
  660. (and hence scanned  for),  is  as  the  first  non-whitespace  token, 
  661. following  the keyword "include", on a #include directive line.  Note 
  662. that comments are considered whitespace, and may precede  the  "...." 
  663. style  header  name.   The  following  are examples of entirely legal 
  664. include directives:
  665.  
  666.     #include /* comment */ "sys\header.h"
  667.     #include "weird/*b.h"
  668.     #include "any char is legal !@' wow \"
  669.  
  670. Note however that the operating  system  will  more  than  likely  be 
  671. unable to find such files!.  The mapping from include directives into 
  672. actual file names involves replacing each occurrence of a '\' or  '/' 
  673. with the appropriate path name separator, and requesting that file be 
  674. opened.  Consider for example the following:
  675.  
  676.     #define stringize(x) #x
  677.     #include stringize( \sys\header )
  678.  
  679. Since the macro will expand its argument to "\\sys\\header"  (details 
  680. of  stringization  are  defined in section 3.8.3.2), the file will be 
  681. searched for using four backslashes!  This mapping into a  file  name 
  682. is  independent  of  whether the file name was provided in the "...." 
  683. style, or it was a string literal  generated  by  some  preprocessing 
  684. replacement.
  685.  
  686. In  an  identical  fashion,  a <....> style header name is defined by 
  687. JRCPP to begin with a '<' character, and to not terminate  until  the 
  688. first  '>'  character is reached, without extending past the newline. 
  689. The context for scanning for this token is identical to that  of  the 
  690. "...."  style  header  name.   As with the "...." style header names, 
  691. there are NO special characters (i.e.: escape sequences)  interpreted 
  692. during  the  scanning  for  such  a  token.   The following are legal 
  693. #include directives, and demonstrate this:
  694.  
  695.     #include <system.h\header.h/*this_too>
  696.     #include /*comment*/ /*comment*/ <any char ' or " or even \>
  697.     #/*comment*/ include /*comment
  698.             comment continues*/ < spaces even count  >
  699.  
  700. The last example also demonstrates that comments  are  reduced  to  a 
  701. single  space,  and  hence  do not disrupt the context of the scan as 
  702. defined.
  703.  
  704. Note that all characters between the delimiters < and >, (or  between 
  705. the  double quotes in the "...." style) are interpreted as being part 
  706. of the file name.
  707.  
  708. In the interest of portability, it is suggested that the user refrain 
  709. from using the standard '\' path delimiter in an DOS/OS2 environment, 
  710. and instead make use of the equivalent character '/'.
  711.  
  712.  
  713. 3.1.8 LANGUAGE- LEXICAL ELEMENTS- Preprocessing numbers
  714.  
  715. The lexical token "preprocessing number" appears to have been  placed 
  716. into  the standard to allow for arbitrary substrings of valid numbers 
  717. to be manipulated conveniently.  The need for such a token is perhaps 
  718. motivated  by  the requirement (given elsewhere in the standard) that 
  719. if the result of some preprocessing operation (such as token  pasting 
  720. via  ##)  is  not  a  valid  preprocessing  token, then the resulting 
  721. behavior is undefined.  With that requirement "on the books", it then 
  722. follows  that  substrings of numbers should be considered valid.  For 
  723. example, the substring `3.14' could be pasted onto  `0e4',  to  yield 
  724. the  result `3.140e4'.  In order to make life as easy as possible for 
  725. the implementers, the standard is VERY broad in its allowance of what 
  726. is   a   valid  preprocessing  number.   For  example,  the  sequence 
  727. `1.2aZ4E-_6.7.2_3' is a  valid  preprocessing  number.   As  per  the 
  728. standard,  this token is supported, in the full generality that it is 
  729. specified.
  730.  
  731. The user should also be warned  of  the  fact  that  a  preprocessing 
  732. number is a SINGLE TOKEN, and hence is not scanned internally for the 
  733. presence of  macro  names.   For  example,  when  the  above  example 
  734. `1.2aZ4E-_6.7.2_3'  is  present  in a file, the preprocessor will NOT 
  735. consider the macro aZ4E for expansion, even if it  is  defined!   The 
  736. point  being  made  here  is  that when number are placed adjacent to 
  737. letters in the source file, they will typically be  blended  together 
  738. into  a  single token, and the letters will not be eligible for macro 
  739. substitution.   Similarly,  even  though  the  `.'  operator  may  be 
  740. overloaded  in  C++,  if it is placed to the right of and adjacent to 
  741. ANY number sequence, it will be absorbed as part of that token!
  742.  
  743.  
  744. 3.8 LANGUAGE- PREPROCESSING DIRECTIVES
  745.  
  746. The  descriptions  given  in  this  section  cover  all  aspects   of 
  747. preprocessor  directives.   I  will in general paraphrase some of the 
  748. significant areas  that  I  consider  non-intuitive.   An  interested 
  749. reader  should  certainly  consider examining the actual standard for 
  750. any additional details.
  751.  
  752. One notable item in  the  overview  section  is  that  tokens  within 
  753. directives  are  generally  NOT  subject  to  macro expansion, unless 
  754. otherwise noted. Hence logical  lines  of  text  are  categorized  as 
  755. directive or non-directive lines BEFORE macro expansion of such lines 
  756. take place.  In addition, as pointed out in a later section, if macro 
  757. expansion produces something that "resembles" a directive line, it is 
  758. NOT processed as a  preprocessing  directive.   The  following  is  a 
  759. summary  of  the  actions  of  various  directives  with  regards  to 
  760. expansion of the tokens that follow the "# directive_name":
  761.  
  762. Directives for which tokens, on the line with them, are expanded:
  763.  
  764.     #if
  765.     #elif
  766.     #include
  767.     #line
  768.  
  769. Directive for which tokens on the line with them, are not expanded:
  770.  
  771.     #ifdef
  772.     #ifndef
  773.     #define
  774.     #undef
  775.     #error
  776.     #pragma
  777.  
  778. Directives which cannot legally have other tokens on  the  line  with 
  779. them:
  780.  
  781.     #else
  782.     #endif
  783.     #
  784.  
  785. Note  that the #if and #elif have some additional translation that is 
  786. performed on their tokens both BEFORE and AFTER macro expansion.  The 
  787. #include  and  #line directive are only expanded when a standard form 
  788. of arguments is not present.  In the case  of  a  #include  directive 
  789. that  does require expansion of the tokens, the post-expansion tokens 
  790. are processed (concatenated) after  expansion  and  rescanned  for  a 
  791. standard  format.  The  fact  that  additional tokens are not allowed 
  792. following the null directive (the lone #), is significant in that any 
  793. other lines that begin with # are strictly illegal.
  794.  
  795.  
  796. 3.8.1 LANGUAGE- PREPROCESSING DIRECTIVES- Conditional inclusion
  797.  
  798. Conditional inclusion refers to the use of #if directives (along with 
  799. its various forms and grouping directives) to cause a section of code 
  800. to  be  optionally included or excluded from the preprocessed result. 
  801. Fundamentally, there are three ways to start an  if  directive  group 
  802. (#if,  #ifndef, #ifdef), two ways to continue a group (#elif, #else), 
  803. and one directive to mark the end of the group (#endif).  Since  such 
  804. if  groups  can nest (i.e., contain inner groups), we will start with 
  805. the description of an outermost conditional group, and  then  discuss 
  806. the  ramifications on inner groups.  We will also defer discussion of 
  807. #ifdef and #ifndef, as their definition follows directly from the the 
  808. definition of #if.
  809.  
  810.  
  811. Subsection A) Evaluation Of #if Expressions
  812.  
  813. The first point to address is how the tokens on a line with a #if are 
  814. evaluated, and what their resulting "value" signifies.  To  make  the 
  815. discussion clearer, we will assume the following example
  816.  
  817.     #define hi 5
  818.     #if (1u == defined(hello)) || (3 < hi + low + int)
  819.     ...
  820.  
  821. The  process  of  evaluating  the  tokens  on a line with a directive 
  822. consist of 6 phases:
  823.     
  824.     1) remove all occurrences of "defined identifier" and  "define  ( 
  825.             identifier )", and replace them with either 0 or 1 (1 iff 
  826.             the identifier is currently defined as a macro)
  827.  
  828.     2) macro expand the  line  that  resulted  from  phase  1  (using 
  829.             standard rules described in section 3.8.3)
  830.  
  831.     3)  replace all identifiers and keywords in the result of phase 2 
  832.             with the number 0 (this result is a list of constants and 
  833.             operators)
  834.  
  835.     4)  convert all constants of type "int" to identical constants of 
  836.             type "long", and constants  of  type  "unsigned  int"  to 
  837.             "unsigned long".
  838.  
  839.     5)  evaluate  the  expression  produced  by  phase 4 according to 
  840.             standard C expressions methods,  but  always  use  "long" 
  841.             types  for  subexpressions that evaluate to an "int", and 
  842.             "unsigned long"  for  expressions  that  evaluate  to  an 
  843.             "unsigned  int" (the final result is an integral constant 
  844.             of type "long" or "unsigned long")
  845.  
  846.     6) if the final result of  phase  5  is  equal  to  0,  then  the 
  847.             expression was false, otherwise it is true.
  848.  
  849.  
  850. The  process  can  be  demonstrated  on  the  example given, with the 
  851. following evaluations.  After phase 1 removal of "defined":
  852.  
  853.     #define hi 5
  854.     #if (1u == 0) || (3 < hi + low + int)
  855.     ...
  856.  
  857. After phase 2 macro expansion
  858.  
  859.     #define hi 5
  860.     #if (1u == 0)) || (3 < 5 + low + int)
  861.     ...
  862.  
  863. After phase 3 replacement of identifiers and keywords with 0:
  864.  
  865.     #define hi 5
  866.     #if (1u == 1) || (3 < 5 + 0 + 0)
  867.     ...
  868.  
  869. After phase 4 conversion of "int"s to "long"s:
  870.  
  871.     #if (1uL == 1L) || (3L < 5L + 0L + 0L)
  872.     ...
  873.  
  874. The phase 5 evaluation might proceed something like:
  875.  
  876.     (1uL == 1uL) || (3L < 5L)
  877.     (    1     ) || (   1   )
  878.     (    1L    ) || (   1L  )
  879.              1
  880.              1L
  881.  
  882. Finally in phase 5, the above constant can be seen  to  be  non-zero, 
  883. and hence the result of the evaluation is true.
  884.  
  885. The  above  rules  work  for  the  most part, as expected by "almost" 
  886. everyone, but the following details and anomalies are worth noting.
  887.  
  888. Note that in phase 1 an attempt is made to remove all occurrences  of 
  889. the  operator  "defined".   If  this  operator  is  not applied to an 
  890. identifier, the Standard indicates that the  results  are  undefined.  
  891. JRCPP  considers  this  scenario  to  be  a  syntax error, and aborts 
  892. evaluation of the expression.  As a means of  error  recovery,  JRCPP 
  893. assumes an evaluated result of FALSE, and a diagnostic is generated.
  894.  
  895. A  second  point  of  ANSI  C undefined behavior takes place when the 
  896. result of macro  expansion  produces  the  operator  "defined".   For 
  897. simplicity  and portability of code, JRCPP disregards the presence of 
  898. such an operator as  the  result  of  macro  expansion,  and  follows 
  899. exactly  the  multiphase algorithm supplied above.  Hence occurrences 
  900. of the keyword "defined" that are produced  by  macro  expansion  are 
  901. replaced in phase 3 with a value of 0.
  902.  
  903. During  the  expansion  of  phase  4,  some ANSI C undefined behavior 
  904. exists with regard to evaluating character constants.  The two points 
  905. here  that  must  be  resolved  are  how  to  evaluate multicharacter 
  906. character constants (which contain  more  than  one  item,  which  is 
  907. either  an  escape  sequence  or  a  simple  character),  and whether 
  908. character constants may assume  negative  values.   As  mentioned  in 
  909. earlier  sections,  multicharacter  character  constants  represent a 
  910. major area of non-portability, and hence  they  are  not  effectively 
  911. supported   in   #if   expression  evaluation.   Specifically,  if  a 
  912. multicharacter character  constant  (such  as  'zq')  appears  in  an 
  913. expression,  it  is truncated to a single character constant, keeping 
  914. only the leftmost character (or escape  sequence)  and  of  course  a 
  915. diagnostic is generated.  Character constants under JRCPP evaluate as 
  916. "signed int", which in a DOS 8088-80x86 environment is taken to be  a 
  917. 16  bit  signed integer.  Single character character constants always 
  918. evaluate as positive numbers.   Octal  character  constants  are  all 
  919. considered  positive  (i.e.,  '\000' through '\777'), but hexadecimal 
  920. character constants may evaluate to a negative number.  Specifically, 
  921. if  the  high  order  bit  of  a hexadecimal character constant (when 
  922. viewed as a "signed int") is set (i.e., '\x8000' through '\xffff') on 
  923. a 16 bit signed int architecture), then the number is negative, using 
  924. a two's complement representation.  Additionally,  if  a  hexadecimal 
  925. escape  sequence exceeds the representational precision or range of a 
  926. character constant (e.g., "signed int" under JRCPP, which corresponds 
  927. to  16  bits  under  a DOS environment), then the high order bits are 
  928. discarded.
  929.  
  930. There are several subtleties involving preprocessor "#if"  expression 
  931. evaluation.  The first item to observe is that the expression must be 
  932. formed using only integral constant subexpression (i.e., no  floating 
  933. point; no pointers); casts may not be used; and the 'sizeof' operator 
  934. is not evaluated (in fact, 'sizeof' is replaced in  phase  3  by  the 
  935. value  0).   As  per allowance by the standard, there is no guarantee 
  936. that  character  constants  will  be  evaluated  identically  in  the 
  937. preprocessor as they are in the compiler (since JRCPP is external and 
  938. unknown to your compiler, this is all the more important to be  aware 
  939. of).
  940.  
  941. One  slightly  quirky  aspect of the evaluation of #if centers around 
  942. the consistent use of "long"  types  to  replace  "int"  types.   The 
  943. following  demonstrates  this "quirk", and is commonly a thorn (bug?) 
  944. in the side of many "would be ANSI compatible" preprocessors:
  945.  
  946.     #if 1 > (0 ? 1u : -1)
  947.  
  948. The tricky aspect of evaluation of this example involves the value of 
  949. the  ternary  "?:" subexpression AFTER the transition to "long" types 
  950. is made. The subexpression looks like "(0L ?  1uL : -1L)".  Note  the 
  951. the  type  associated  with  this ternary must be the "larger" of the 
  952. types "unsigned long" (from 1uL) and "signed long" (from -1L). Hence, 
  953. according  to  ANSI,  the  result  of the ternary expression must the 
  954. "unsigned long" representation of "-1", which is actually the largest 
  955. possible  "unsigned  long".   So we can see that the above expression 
  956. ends up evaluating to FALSE! The moral of the story  for  programmers 
  957. is  to  exercise  care  when  working  with  negative  numbers in the 
  958. preprocessor #if statements.
  959.  
  960.  
  961. Subsection B: Other conditional inclusion directives
  962.  
  963. As mentioned in the standard the lines:
  964.  
  965.     #ifdef any_identifier
  966. and
  967.     #ifndef any_identifier
  968.  
  969. are equivalent, respectively, to:
  970.  
  971.     #if defined any_identifier
  972. and
  973.     #if ! defined any_identifier
  974.  
  975. Each basic conditional inclusion section of source code consists of a 
  976. "if  group",  followed  by  any  number  of  "elif  groups", followed 
  977. optionally by an "else group", and terminated by a line with a #endif 
  978. directive.    An   "if   group"  consists  of  a  #if  directive  (or 
  979. equivalent), followed optionally by lines of code.  An  "elif  group" 
  980. consists  of a #elif directive (which has an expression to evaluate), 
  981. followed optionally by lines of code.  An "else group", consists of a 
  982. #else directive, followed optionally by lines of code.  Note that for 
  983. each #if directive, there MUST be a matching  #endif  directive  that 
  984. follows  it,  and  that  these conditional inclusion sections do nest 
  985. within a single "group" of code (i.e., within a single "if group", or 
  986. within a single "elif group", or within a single "else group").
  987.  
  988.  
  989.  
  990. The  semantics  (meaning) of these directives is most simply given by 
  991. an example:
  992.  
  993.     #if expression_1
  994.       block 1
  995.     #elif expression_2
  996.       block 2
  997.     #elif expression_3
  998.       block 3
  999.     #else
  1000.       block 4
  1001.     #endif
  1002.  
  1003. Fundamentally, only one of the blocks 1,2,3, and 4 can EVER be passed 
  1004. to  the  output  of  the  preprocessor  (if we were missing the "else 
  1005. group", then it  is  possible  that  none  of  the  blocks  would  be 
  1006. processed).  If  expression_1 evaluates to TRUE, then ONLY block 1 is 
  1007. processed, and block 2, 3, and 4 are discarded, and expression 2  and 
  1008. 3  need not even be evaluated.  On the other hand, if expression 1 is 
  1009. FALSE, then block 1 is discarded, and expression 2  is  evaluated  as 
  1010. though  it  were the start of a conditional inclusion section.  Hence 
  1011. the first #if or #elif directive that evaluates to  true  causes  its 
  1012. associated  section of code to be included, and all other sections in 
  1013. the other groups to  be  discarded.   IF  none  of  these  expression 
  1014. evaluate to TRUE, then the code in the "else group", if it exists and 
  1015. has code, is processed.
  1016.  
  1017.  
  1018. One very common  use  of  conditional  inclusion  is  to  effectively 
  1019. comment  out  a  large  section  of  code,  that more than likely has 
  1020. /*...*/ based comments.  Since standard /*...*/ based comments do not 
  1021. nest,  large  blocks  of code CANNOT be safely removed using standard 
  1022. /*...*/  delimiters.  In  contrast,   since   conditional   inclusion 
  1023. directives  do nest, placing "#if 0" at the start of the section, and 
  1024. "#endif" at the end of the section effectively comments out  (safely) 
  1025. an  arbitrary  block  of code.  Also, from a stylistic point of view, 
  1026. the fact that  these  directives  DO  NOT  have  to  appear  directly 
  1027. adjacent  to  the  left  margin  (as  was  the  case  in some early C 
  1028. preprocessors)  allows  such  commenting  to  be  done  in   a   very 
  1029. aesthetically pleasing format.
  1030.  
  1031.  
  1032.  
  1033. 3.8.2 LANGUAGE- PREPROCESSING DIRECTIVES- Source file inclusion
  1034.  
  1035. Source  file  inclusion  is performed using the "#include" directive. 
  1036. For our discussion, we will refer to directives like:
  1037.  
  1038.     #include <stdio.h>
  1039.  
  1040. as <...> style includes, and
  1041.  
  1042.     #include "header.h"
  1043.  
  1044. as "..." style includes.
  1045.  
  1046. Subsection A) Interpretation of expanded tokens following #include
  1047.  
  1048. One notable change to many compilers to support the ANSI standard, is 
  1049. the acceptance of include directives of the form:
  1050.  
  1051.     #include token1 token2 ..... tokeni
  1052.  
  1053. wherein the token sequence cannot be interpreted as either a <...> or 
  1054. "..." style include.  We will refer to this include  directive  as  a 
  1055. "macro  derived" directive, in honor of the fact that the tokens must 
  1056. be macro expanded before the include directive  can  be  acted  upon. 
  1057. Note  that  to  not  be a "..." style include, the first character of 
  1058. token1 must be other than `"', or at least there must be no other `"' 
  1059. character  later  on the include line.  Similarly, to avoid the <...> 
  1060. style, the first character of token1 must be other than `<', or there 
  1061. must  be  no  terminating `>' later on the line. Recall also from the 
  1062. discussion of tokenization, that  backslashes  cannot  escape  out  a 
  1063. closing  quote,  and that a the sequence /* is NOT honored within the 
  1064. file name in either the "..." or  <...>  style  include  (this  is  a 
  1065. special context).
  1066.  
  1067. The  first  element  of  undefined  behavior  for #include directives 
  1068. concerns the method by which  the  results  of  macro  expanding  the 
  1069. tokens  in  a  macro  derived  directive  are  interpreted.  The most 
  1070. obvious (and simple) case is when the expansion of the  entire  token 
  1071. sequence  is a simple string literal.  The more complex case involves 
  1072. an expansion that is still a token  sequence,  such  that  the  first 
  1073. token  begins  with  a  `<', and the last token ends with a `>'.  The 
  1074. following are examples of such include directives:
  1075.  
  1076.     #define myfile "header.h"
  1077.     #define yourfile  /* this macro has a null definition */
  1078.     #define less_than <
  1079.     #define greater_than >
  1080.     #define big_system_header os2.h
  1081.  
  1082.     #include yourfile myfile
  1083.     #include less_than big_system_header greater_than
  1084.  
  1085. Although  the  above  macro  defined  directives  expand  to   tokens 
  1086. sequences  that "look like" more common include directives, there are 
  1087. some  special  differences.   Specifically,  using  the  above  macro 
  1088. definition the resulting token sequences look like:
  1089.  
  1090.     #include "header.h"
  1091.     #include < os2.h >
  1092.  
  1093. Note  that  the  above  casual  macro  definitions  left  leading and 
  1094. trailing spaces in the file name for  the  latter  example.  Although 
  1095. this could have been avoided by using function like macros, which can 
  1096. be placed sequentially with no white space between them, the presence 
  1097. of  whitespace  in the result is believed to be common among users of 
  1098. this  feature.   With  the  above  examples  understood,  the   JRCPP 
  1099. resolution   is  simply  to  concatenate  all  the  tokens,  ignoring 
  1100. inter-token whitespace, and THEN reinterpret the resulting  character 
  1101. sequence  in  the context appropriate to <...> or "..." style include 
  1102. directives (i.e., no special meaning for backslashes, etc.).
  1103.  
  1104.  
  1105. Subsection B) Search algorithm for included files
  1106.  
  1107. A second point of undefined behavior in the ANSI C standard  involves 
  1108. where  exactly  included  files are searched for.  There are actually 
  1109. several very distinct conventions for  this  search  mechanism,  even 
  1110. within  file  systems  which are hierarchically based (such as UNIX).  
  1111. JRCPP  has  adopted  a  default  strategy  that  is  consistent  with 
  1112. Microsoft  C  5.1, and several other more recent compilers.  There is 
  1113. also support (selected via  #pragma  include_search)  for  algorithms 
  1114. compatible   with   Microsoft  C  4.0,  and  support  for  approaches 
  1115. compatible with older UNIX system cpp implementations.
  1116.  
  1117. If an application is placing all the source and  header  files  in  a 
  1118. single  directory, which is also the current working directory during 
  1119. the compilation,  and  the  system  include  directory  is  a  single 
  1120. absolute  directory, then the search algorithm then almost any search 
  1121. algorithm will suffice.  On the other hand, if header  files  in  one 
  1122. directory  includes  header  files  in a second directory, which then 
  1123. include header files in yet a third directory, while the user  has  a 
  1124. current  working  directory  yet  elsewhere,  and  some of the system 
  1125. include or application include directories use relative  path  names, 
  1126. the meaning of:
  1127.  
  1128.     #include "header.h"
  1129.  
  1130. is  far  from  obvious.   Historically, projects developed under UNIX 
  1131. placed all source and header files in a  single  directory,  and  the 
  1132. discussion  of  search  algorithms  was irrelevant.  With the growing 
  1133. complexity of code, and the presence of a multitude of programmers on 
  1134. a  project,  the need has arisen to hierarchically segregate sections 
  1135. of large project into file hierarchies.  In order to support function 
  1136. calls  between these sections, header file inclusion well outside the 
  1137. current directory  has  become  commonplace.   Various  vendors  have 
  1138. adopted   algorithms   that  support  the  "trivial"  case  described 
  1139. originally, but there  has  often  been  disagreement  about  how  to 
  1140. process the more complex cases.
  1141.  
  1142. The  philosophy  that  drove  the development of the slightly complex 
  1143. include strategy of JRCPP motivated by the following requirements:
  1144.  
  1145.     1) It should be possible to write  include  files,  that  include 
  1146.     other  files,  without  concern  about what source file was being 
  1147.     compiled, where that file was, and what directory the user was in 
  1148.     when  the compilation was requested.  This allows complex systems 
  1149.     of header files to be written INDEPENDENT of the application that 
  1150.     uses them.
  1151.  
  1152.     2)  To allow for even more complex sets of include files, if file 
  1153.     A included file B, and file A was able to include  file  C,  then 
  1154.     file B should be able to include file C with equal ease.  In some 
  1155.     sense, this concept is similar to inheritance in object  oriented 
  1156.     programming.
  1157.  
  1158.     3)   It   should  be  possible  for  a  user  to  change  current 
  1159.     directories, and in doing so change what files are accessible via 
  1160.     include  searches  (assuming  the programmer has orchestrated the 
  1161.     placement of header files to support this strategy).  This allows 
  1162.     different  versions  of an application to be compiled easily into 
  1163.     different directory areas.
  1164.  
  1165.     4) It should be possible to define the location of include  files 
  1166.     via  a relative path.  This facility would allow the construction 
  1167.     of source file hierarchies that are  easily  ported  to  distinct 
  1168.     absolute positions in file system hierarchies.
  1169.  
  1170. We  will start with some definitions of terms.  We define the "system 
  1171. include path" to be a list of directories where system  header  files 
  1172. are  provided.   Typically  all  the  ANSI C specified library header 
  1173. files are in directories listed in the system include path, and files 
  1174. in such directories can be expected to never change (hence it is rare 
  1175. to provide "make" dependencies  on  such  files).   The  "application 
  1176. include  path"  is  a  list  of directories that contain header files 
  1177. significant to a specific application or project.   Typically,  files 
  1178. in  the  application include path tend to change often during program 
  1179. development.   Next  there  is  the  "current  directory",  with  its 
  1180. standard  meaning  in  a  UNIX  or  DOS  like  file hierarchy.  Three 
  1181. additional directory lists need to be defined, the  "original  source 
  1182. directory", the "current source directory", and the "ancestral source 
  1183. directories".  The "original source directory" is  the  directory  in 
  1184. which  the  source  file specified on the compilation or preprocessor 
  1185. command line was  found.   The  "current  source  directory"  is  the 
  1186. directory which contains the include directive file that is currently 
  1187. being parsed, and has the include directive that  we  are  trying  to 
  1188. process.    The   "ancestral   source  directories"  are  a  list  of 
  1189. directories that begin  with  the  "current  source  directory",  and 
  1190. proceed  back  through each level of nested inclusion (specifying the 
  1191. directory in which that source file was found), all the  way  to  the 
  1192. "original source directory".
  1193.  
  1194. The algorithm for searching for header.h consists of the bottom level 
  1195. ancestral search, and a top level search.  The  algorithm  terminates 
  1196. the  first time a file can be accessed. In pigeon code, the algorithm 
  1197. would look like:
  1198.  
  1199. ancestral_search(file_name)
  1200.     {
  1201.     if (file_name has relative prefix)
  1202.         {
  1203.         for (every prefix p, in the ancestral include list)
  1204.         do try to open (p/file_name)
  1205.         }
  1206.  
  1207.     /* but as a last resort ... */
  1208.     try to open (file_name)          /* with no prefix */
  1209.     }
  1210.  
  1211. Driving the code that we just listed is the higher level search, that 
  1212. is directed by the use of user specified include paths:
  1213.  
  1214. standard_search(file_name)
  1215.     {
  1216.     try ancestral_search(file_name)     /* with no prefix */
  1217.  
  1218.     if (file_name has relative path)
  1219.         {
  1220.         for every prefix p in the application include path
  1221.         do ancestral_search(p/file_name)
  1222.  
  1223.         for every prefix p in the system include path
  1224.         do ancestral_search(p/file_name)
  1225.         }
  1226.     }
  1227.  
  1228. The  above pigeon code corresponds to the algorithm for finding "..." 
  1229. style includes.  When <...> style includes are searched for, the file 
  1230. is not searched for directly (with no prefix) unless an absolute path 
  1231. specifier, and the "application include path" is never made  use  of.  
  1232. The  following  pigeon  code  describes  the  search  for <...> style 
  1233. include files:
  1234.  
  1235. system_search(file_name)
  1236.     {
  1237.     if (file_name has relative path)
  1238.         {
  1239.         for every prefix p in the system include path
  1240.         do ancestral_search(p/file_name)
  1241.         }
  1242.     else  /* file has an absolute path specification */
  1243.         try to open (file_name)
  1244.     }
  1245.  
  1246.  
  1247. It should also be pointed out that when the ancestral_search function 
  1248. is  used,  that  the  path prefix for the ancestral include files are 
  1249. tried sequentially,  starting  with  the  current  source  file,  and 
  1250. proceeding back to the original source file.
  1251.  
  1252.  
  1253. Next,  we  will  present an example of the above definitions, and the 
  1254. resulting search path. We will assume:
  1255.  
  1256. The current working directory  is  /current_path.   The  source  file 
  1257. original_path/original.c   included  the  file  header1path/header1.h 
  1258. (hence original_path  is  the  "original  source  directory").   File 
  1259. header1.h   included   header2path/header2.h  (hence  the  "ancestral 
  1260. directory list" is: header2path,  header1path,  original_path).   The 
  1261. system include path contains the directory sysdir1, and sysdir2.  The 
  1262. application  include  path  contains  the  directories  appdir1,  and 
  1263. appdir2.  For  our  example  of searching, we will examine the search 
  1264. pattern when header file header2.h contains the include directive:
  1265.  
  1266.     #include "header3.h"
  1267.  
  1268. If the file specified as header3.h does have an absolute path prefix, 
  1269. then  only  that  absolute path/filename is used in searching for the 
  1270. file (an example with an absolute path is "/usr/lex/lexdefs.h").   If 
  1271. header3.h  does  not have an absolute path prefix, then the following 
  1272. search pattern is followed. With the caveat  to  be  mentioned  in  a 
  1273. moment,  the  search  for  a  file  consists  of  trying  to open the 
  1274. following:
  1275.  
  1276.     header3.h
  1277.     appdir1/header3.h
  1278.     appdir2/header3.h
  1279.     sysdir1/header3.h
  1280.     sysdir2/header3.h
  1281.  
  1282. There is, as mentioned, one caveat to the above search sequence.  The 
  1283. caveat  is that whenever a file in the above list has a relative path 
  1284. prefix, then the prefixes provided by the ancestral  directories  are 
  1285. tried sequentially, followed by the unadorned filename, before moving 
  1286. on down the list.  Since we assumed that header3.h did  not  have  an 
  1287. absolute  path  prefix, the following files would actually be subject 
  1288. to fopen() calls:
  1289.  
  1290.     header2path/header3.h
  1291.     header1path/header3.h
  1292.     original_path/header3.h
  1293.     current_path/header3.h  (same as simply `header3.h')
  1294.  
  1295. The above list corresponds to a search using path prefixes taken from 
  1296. the ancestral include list, and then using the current directory.
  1297.  
  1298. Note that if one of the application include path directories had only 
  1299. a relative path prefix, then it too would make use of  the  ancestral 
  1300. include  directories  for  prefixes.   For  example, if app2dir was a 
  1301. relative path, then header3.h would (if it were not found earlier  in 
  1302. our list) be searched for in:
  1303.  
  1304.     header2path/app2dir/header3.h
  1305.     header1path/app2dir/header3.h
  1306.     original_path/app2dir/header3.h
  1307.     currentpath/app2dir/header3.h  (same as `app2dir/header3.h')
  1308.  
  1309. Subsection B: Include strategy compatibility
  1310.  
  1311. The  include  strategy described above is compatible with Microsoft C 
  1312. 5.1, and several other  major  compilers.   Since  this  strategy  is 
  1313. rather  general,  it  tends  to  provide  coverage  of  search  areas 
  1314. sufficient for most any project.  If however, absolute  compatibility 
  1315. is  desired with other compilers, the search strategy may be modified 
  1316. by use of the appropriate pragma options.  The adjustments  permitted 
  1317. all  represent restrictions to search in only a subset of the default 
  1318. areas.
  1319.  
  1320. For example, the SUN UNIX cpp searches for "..." style includes first 
  1321. in  the parent directory, and then in the application's include path. 
  1322. To achieve complete compatibility with SUN, it is  necessary  to  use 
  1323. the pragma:
  1324.  
  1325.     #pragma include_search youngest_ancestor_only
  1326.  
  1327. As  a  second example, Lattice C 3.0 searched for "..." include files 
  1328. in the current working  directory,  and  then  in  the  application's 
  1329. include  path.   To be compatible with such a strategy, the following 
  1330. pragmas should be entered:
  1331.  
  1332.     #pragma include_search current_directory
  1333.  
  1334. Note that the  options  for  the  different  ancestral  search  modes 
  1335. include:    `youngest_ancestor_only',   `eldest_ancestor_only',   and 
  1336. `all_ancestors'. These options correspond respectively to  the  using 
  1337. the directory of the current_path, original_path, and the full search 
  1338. algorithm.  The default provided by  JRCPP  is  `all_ancestors',  but 
  1339. omitting  an ancestral selection (as in the last example) implies the 
  1340. use of no ancestral directories.
  1341.  
  1342. Note that if searching in the  current_directory,  and  searching  in 
  1343. directories  associated  with  all  ancestral modes are disabled (via 
  1344. omission in such a pragma), then it  is  impossible  to  include  any 
  1345. files  without  using an absolute prefix supplied in a system include 
  1346. path, or an applications include path.
  1347.  
  1348. 3.8.3 LANGUAGE- PREPROCESSING DIRECTIVES- Macro replacement
  1349.  
  1350. This section has only two mentions of undefined behavior, but it  has 
  1351. several  topics  worthy  of  commentary.   We  will  start  with  the 
  1352. comments, and then proceed to resolve the cases of undefined behavior.
  1353.  
  1354. It should be mentioned here that JRCPP has a rather novel pragma that 
  1355. explains  in  detail  the steps taken during a macro expansion.  This 
  1356. information may be used as a tutorial assistant (for the novice),  as 
  1357. a  debugging  assistant  (for  the  professional programmer), or as a 
  1358. method of proof of a bug  (for  a  registered  user  to  file  a  bug 
  1359. report).   The explanation given includes a step by step breakdown of 
  1360. the macro expansion process, along with reference listings of current 
  1361. macro  definitions  as  they  are  applied,  and reasons for ignoring 
  1362. current definitions (such as the fact that an identifier is already a 
  1363. part  of  a  recursive  expansion  of  itself).  For more details see 
  1364. "#pragma describe_macro_expansions", and note that this  feature  can 
  1365. be  turned  on  and  off to localize its impact.  It is expected that 
  1366. this pragma can easily augment  this  Language  Reference  Manual  by 
  1367. provided annotated examples.
  1368.  
  1369. ANSI C differs from many prior C preprocessor implementations in that 
  1370. an identifier may not be redefined  "differently"  from  its  current 
  1371. macro  definition,  without first undefining the existing definition.  
  1372. Some non-ANSI implementations allowed redefinitions to mask  existing 
  1373. definitions,  and  future  #undef directives to "pop" into visibility 
  1374. older definitions. Other implementations  simply  allowed  new  macro 
  1375. definitions  to  overwrite  existing definitions. JRCPP only supports 
  1376. the ANSI C approach, with the agreement with  the  ANSI  C  Rationale 
  1377. that  other  formats are error prone, and generally an actual errors.  
  1378. Note that redefinitions that are identical to the original  (such  as 
  1379. occurs  when  a  header  file is include twice) are fully legal.  The 
  1380. Standard is quite specific in defining what a benign redefinition is, 
  1381. but  it  can be summarized by saying that the only difference allowed 
  1382. in a redefinition is the length of white space interludes.  (There is 
  1383. actually  a  subtle  error in the Standard.  The restriction that the 
  1384. "order of the parameters" be unchanged in  a  redefinition,  was  not 
  1385. listed.   JRCPP  assumes this was a typo, and requires that the order 
  1386. of parameters be unchanged in a macro redefinition).   If  I  receive 
  1387. sufficient  input  from users that my decision here is a hindrance, I 
  1388. will support the other standards involving  non-benign  redefinitions 
  1389. (with appropriate diagnostics), controlled via pragma directives.
  1390.  
  1391. A  second  item  worthy of noting is that whitespace at the start and 
  1392. end of a replacement list is not considered part of  the  replacement 
  1393. list.   Hence  it  is  impossible  to  define a macro that expands to 
  1394. whitespace.
  1395.  
  1396. The two aspects of undefined behavior involve odd occurrences  during 
  1397. the  gathering of arguments for a function like macro invocation. The 
  1398. first problem that needs to be addressed is what the behavior is when 
  1399. a  token  sequence  that  could  be  interpreted  as  a  directive is 
  1400. encountered while gathering a list of arguments.  The second point of 
  1401. undefined  behavior  is  present  when  an  argument  consists of "no 
  1402. preprocessing tokens".
  1403.  
  1404. Fundamentally, the problem with allowing preprocessor  directives  to 
  1405. occur  during  the gathering of parameter list for a macro, is that a 
  1406. #define or #undef  directive  might  be  encountered.   Consider  the 
  1407. following code:
  1408.  
  1409.     #define f(x)   x+1
  1410.     f(2)            /* that was easy */
  1411.     f(              /* look for the argument ... */
  1412.     #undef f
  1413.     2 )             /* found the arg, but should we use it? */
  1414.  
  1415. JRCPP resolves such ambiguities very easily by not generally allowing 
  1416. directives to be present within macro argument lists.   Specifically, 
  1417. JRCPP  would  generate  a  diagnostic  indicating  that  there was no 
  1418. closing parenthesis for the macro invocation (JRCPP  stopped  looking 
  1419. when  it  reached the directive).  Although this is a VERY reasonable 
  1420. result when #define and #undef directives are reached, it is  not  so 
  1421. obviously  necessary  when  certain  other directives are reached. To 
  1422. assist the programmer that is using existing code such as:
  1423.  
  1424.     #define f(x) x+1
  1425.     f(
  1426.     #if foo
  1427.       2
  1428.     #else
  1429.       3
  1430.     #endif
  1431.     )
  1432.  
  1433. a pragma (#pragma delayed_expansion [on|off]) is provided that causes 
  1434. such  "ANSI  C undefined behavior" to be acceptable.  The restriction 
  1435. on this pragma based extension is  that  no  directives  are  allowed 
  1436. within the argument list that can even possibly cause a change in the 
  1437. macro database (i.e., the relevance of the change is not  considered; 
  1438. the significance of the change, such as a benign redefinition, is not 
  1439. considered).  Simply  put,  if  a  #define,  #undef,  or  #pragma  is 
  1440. encountered  during  a  scan  for  arguments  to a macro, the scan is 
  1441. terminated with a "missing  close  paren"  diagnostic,  even  if  the 
  1442. delayed_expansion pragma is active.
  1443.  
  1444. As  mentioned,  the second area of ANSI C undefined behavior involves 
  1445. the "presence of  an  argument  consisting  of  no  tokens...  before 
  1446. argument  substitution...". This phrase unfortunately contradicts the 
  1447. definition of argument: "... sequence of preprocessing tokens ...  in 
  1448. a  macro  invocation".   Note also that "substitution" is the time at 
  1449. which expansion of the argument is  considered,  and  hence  the  odd 
  1450. phrase  cannot  possibly  refer to the situation where an argument is 
  1451. expanded, but the result is nil (or whitespace).  Rather than harp on 
  1452. this  inconsistency,  we  will  discuss what perhaps is a related (or 
  1453. even intended) problem: What  is  the  interpretation  of  a  missing 
  1454. argument (or at least white space where an argument should be)?
  1455.  
  1456. It  is  clearly  stated  that  the  number  of  arguments  in a macro 
  1457. invocation must agree exactly with the number  of  arguments  in  the 
  1458. corresponding   macro   definition,   and  hence  JRCPP  generates  a 
  1459. diagnostic if this is not the case.  In addition,  JRCPP  enlists  an 
  1460. error  recovery  strategy  that  consists  of substituting whitespace 
  1461. (which is clearly not a  valid  ANSI  C  argument)  for  any  missing 
  1462. arguments.   This  strategy  is  intended  to be compatible with some 
  1463. prior non-ANSI implementations.  Note that this action  can  cause  a 
  1464. secondary  error  if  the macro attempts use this argument in certain 
  1465. ways.  The following example demonstrate these secondary errors:
  1466.  
  1467.     #define paste_left(x)   something ## x
  1468.     #define paste_right(x)  x  ## something
  1469.     #define stringize(x)    # x
  1470.     paste_left(/*white*/)
  1471.     paste_right(/*white*/)
  1472.     stringize(/*white*/)
  1473.  
  1474. Fortunately, since most code that  exploits  this  non-ANSI  behavior 
  1475. (missing  argument  is  actually  whitespace)  does not use the paste 
  1476. operator (##) or the stringize operator  (#),  hence  this  secondary 
  1477. error  will  have  tend  not to occur.  Applications that are porting 
  1478. non-ANSI code through JRCPP may then choose  to  lower  the  severity 
  1479. level  of  the  diagnostic  that reports the whitespace argument, and 
  1480. accept the error recovery procedure as reasonable.  (User feedback on 
  1481. my  error  recovery  scheme  may  improve  compatibility  with  other 
  1482. implementations).
  1483.  
  1484.  
  1485.  
  1486. 3.8.3.2 LANGUAGE- PREPROCESSING DIRECTIVES- The # operator
  1487.  
  1488. The # operator provides the stringizing functionality to ANSI C, that 
  1489. was often provided via expansion of parameters within string literals 
  1490. in older (and NON-ANSI) implementations.  One key point  that  should 
  1491. be  stressed  is  that  when  this  functionality  is  used, then the 
  1492. argument is NOT macro expanded before being stringized (i.e.,  placed 
  1493. into quotes).  For example:
  1494.  
  1495.     #define stringize(x) #x
  1496.     #define A 2
  1497.     stringize(2)     /* becomes "2" */
  1498.     stringize(A)     /* becomes "A" */
  1499.  
  1500. If  a user wants the argument to be expanded and THEN stringized, the 
  1501. following construction should be used:
  1502.  
  1503.     #define stringize(x) # x
  1504.     #define expand_then_stringize(x)   stringize(x)
  1505.     #define A 2
  1506.     expand_then_stringize(2)  /* becomes "2" */
  1507.     expand_then_stringize(A)  /* becomes stringize(2), which 
  1508.                                         becomes "2"*/
  1509.  
  1510. The  Standard indicates that the order of evaluation of the operators 
  1511. # and ## is unspecified.   Since  the  token  to  the  right  of  the 
  1512. stringize  operator (#) must be a parameter, it would appear that the 
  1513. following are the only two cases to consider:
  1514.  
  1515.     #define F(x)  word ## # x
  1516.     #define G(x)  # x ## other
  1517.  
  1518. JRCPP follows the C tradition  of  providing  higher  precedence  for 
  1519. unary   operators  than  for  binary  operators.   JRCPP  parses  the 
  1520. definition of F to attempt to paste a stringized version of parameter 
  1521. x  onto  the right side of the identifier `word'.  This decision is a 
  1522. bit immaterial, as the result  of  pasting  any  valid  preprocessing 
  1523. token to the left side of a string literal (the stringized version of 
  1524. x) is almost always an invalid preprocessing  token.  Similarly,  the 
  1525. definition of G provides a request to paste the word `other' onto the 
  1526. right side of the stringized version of parameter  x.   Defining  the 
  1527. precedence in any other way appears to be of equally little use.
  1528.  
  1529.  
  1530. 3.8.3.3 LANGUAGE- PREPROCESSING DIRECTIVES- The ## operator
  1531.  
  1532. The pasting operator ## supplies the functionality in ANSI C that was 
  1533. supplied in various compilers in the past, by means of various hacks.  
  1534. Most  hacks  were based on methods of getting adjacent identifiers to 
  1535. "flow together".  The two methods that I am aware of are:
  1536.  
  1537.     #define f() start
  1538.     f()end       /* for SOME non-ANSI cpp, becomes: `startend' */
  1539.  
  1540. and
  1541.  
  1542.     #define g start
  1543.     g/*comments go away*/end  /* some non-ANSI cpp: `startend' */
  1544.  
  1545. Neither of these constructs are supported under ANSI C, and  in  both 
  1546. cases  JRCPP  defaults  to produces the two tokens `start' and `end', 
  1547. separated by a space.  The first of the two approaches  is  supported 
  1548. via a pragma under JRCPP (see #pragma space_between_tokens).
  1549.  
  1550. It  should  be  emphasized that, just as with the stringize operator, 
  1551. arguments are NOT expanded, prior to insertion in  replacement  list, 
  1552. at  points  where they are about to be subjects of a ## operator. For 
  1553. example:
  1554.  
  1555.     #define A 2
  1556.     #define append(x) x ## right   left ## x    x
  1557.     append(A)  /* becomes: Aright leftA 2 */
  1558.  
  1559. If the user desires an expansion  prior  to  pasting,  the  construct 
  1560. described earlier with regard to stringization must be used.
  1561.  
  1562.  
  1563. 3.8.3.5 LANGUAGE- PREPROCESSING DIRECTIVES- Scope of macro definitions
  1564.  
  1565. This  section  of  the  standard  has  some very nice examples of the 
  1566. process of macro expansion.  These  include  the  use  of  the  paste 
  1567. operator  (##),  the  stringize  operator  (#), and the prevention of 
  1568. infinite recursion of macros.  If the user tries these torture  tests 
  1569. on  JRCPP,  rather  than reveal an error in JRCPP, they will reveal a 
  1570. typo in the ANSI C Standard.  The  specific  error  in  the  standard 
  1571. involves:
  1572.  
  1573.     #define str(x) #x
  1574.     str(: @\n)
  1575.  
  1576. which  the  standard  incorrectly  expands to ": \n", but should have 
  1577. expanded to ": @\\n".  The goal of  the  stringize  operation  is  to 
  1578. produce  text  that  can  print  exactly  as  the  argument  that was 
  1579. supplied. The standard is clear on this point, and other items in the 
  1580. expansion  demonstrate this.  Unfortunately, I am sure that this typo 
  1581. in the Standard will also be the source of many bug reports.
  1582.  
  1583. The user that is trying these tests should also  run  them  with  the 
  1584. pragma space_between_tokens set to off, if they would like the format 
  1585. to be closer to that of the listing in the Standard.  In either  case 
  1586. the  results  should  be  correct.   The  user may also note a slight 
  1587. discrepancy in the format of the output, due to the fact  that  JRCPP 
  1588. maintains  line  position  information much more accurately than most 
  1589. other preprocessors.  In this regard, consider the example:
  1590.  
  1591.     #define swap(x,y)  y x
  1592.     swap (
  1593.     +i
  1594.     +j,
  1595.     +k
  1596.     +l)
  1597.  
  1598. Most preprocessors produce the output:
  1599.  
  1600.     #line 2
  1601.     +k +l +i +j
  1602.  
  1603. Whereas JRCPP produces:
  1604.  
  1605.     #line 5
  1606.     +k
  1607.     +l
  1608.     #line 3
  1609.     +i
  1610.     +j
  1611.  
  1612. The big advantage of the method provided by  JRCPP  is  exposed  when 
  1613. compiler diagnostics wish to refer to a token in such a stream.  When 
  1614. JRCPP is used, a diagnostic for "syntax error on token  `+'"  can  be 
  1615. very  specific  about  the  line number with the offending character. 
  1616. With other preprocessors, the user is just told the error was on line 
  1617. 2.   (As  a historical note, many pre-ANSI preprocessor required that 
  1618. the macro name and all the arguments be  placed  on  a  single  line.  
  1619. Many  users have, as a result, built large logical lines when a macro 
  1620. was being invoked.  ANSI C established a standard whereby this was no 
  1621. longer necessary, but many compiler manufacturers are slow to service 
  1622. the users that have moved to this more readable notation.)
  1623.  
  1624.  
  1625. 3.8.4 LANGUAGE- PREPROCESSING DIRECTIVES- Line control
  1626.  
  1627. The #line directive is fully supported by JRCPP.  There  are  several 
  1628. points  to note about its performance.  The first item worthy of note 
  1629. is that the standard provides for macro expansion of  the  tokens  on 
  1630. the  logical  line  with the #line directive.  Unfortunately, it does 
  1631. not provide for arithmetic reductions.  The result of macro expansion 
  1632. must  be  either  a digit sequence (representing a line number), or a 
  1633. digit sequence with a string literal (file name).
  1634.  
  1635. Note that the line directive requires a string literal,  and  has  no 
  1636. consideration of the sort of context that was provided for evaluation 
  1637. of a file name in an include directive.  This distinction means  that 
  1638. when  a  backslash  is  used in a file name that is specified using a 
  1639. #line directive, then it must be "escaped" using another backslash.
  1640.  
  1641. 3.8.6 LANGUAGE- PREPROCESSING DIRECTIVES- Pragma directive
  1642.  
  1643. JRCPP makes extensive use of pragmas in order to direct customization 
  1644. of  the  performance  of the preprocessor.  Users should refer to the 
  1645. JRCPP Users Guide for a complete list of valid  pragmas,  along  with 
  1646. their meaning.  As per the Standard, unrecognized pragmas are ignored 
  1647. by JRCPP.  In order to facilitate the use  of  pragma  directives  to 
  1648. control  the  compiler,  unrecognized  pragmas  are  passed unchanged 
  1649. (except for comment removal and whitespace compaction) through to the 
  1650. post-preprocessed output file.
  1651.  
  1652. Note  that  because some pragmas do modify the macro database, pragma 
  1653. directives are not permitted within macro invocation argument  lists.  
  1654. If  there  is  some  need  to  pass  forward a pragma to the compiler 
  1655. without having it acted upon by the preprocessor (for  example,  when 
  1656. JRCPP  would  misunderstand  it), then the following sort of approach 
  1657. can be taken:
  1658.  
  1659.     #define HIDE_PRAGMA
  1660.     HIDE_PRAGMA # pragma any tokens
  1661.  
  1662. Due to  the  fact  that  the  results  of  expansion  will  NEVER  be 
  1663. considered  by  JRCPP to be a directive, the pragma presented in this 
  1664. cloak will not be processed by JRCPP.  Unfortunately, when a user  is 
  1665. forced  to  this  extreme, the protection against macro expanding the 
  1666. list of tokens for an unknown pragma is lost.  JRCPP  has  endeavored 
  1667. to  use  novel names that should not clash with the specifications of 
  1668. many other implementations.
  1669.  
  1670.  
  1671.  
  1672. 3.8.8 LANGUAGE- PREPROCESSING DIRECTIVES- Predefined macro names
  1673.  
  1674. All five of the ANSI C predefined macros are supported by JRCPP.  The 
  1675. macros are:
  1676.  
  1677. __LINE__  Current  presumed line number in the source file. The value 
  1678.          of __LINE__ will be in the range permissible  for  a  signed 
  1679.          long integer.
  1680.  
  1681. __FILE__  Current  presumed  file name, provided as a string literal. 
  1682.          Note  that  because  __FILE__  is  a  string  literal,   any 
  1683.          occurrences  of the backslash character in the actual source 
  1684.          name have been replaced by `\\' (an escaped backslash).
  1685.  
  1686.  
  1687.  
  1688. __DATE__ The date on which JRCPP began  to  preprocess  the  original 
  1689.          source  file,  expressed  as a character string.  The format 
  1690.          will always be "Mon dd yyyy", where Mon in the  abbreviation 
  1691.          for  the month, dd is 1 or 2 digit representation of the day 
  1692.          of the month, and yyyy is the 4 digit calendar year.
  1693.  
  1694. __TIME__ The time at which JRCPP began  to  preprocess  the  original 
  1695.          source file, expressed as a character string.  The format is 
  1696.          "hh:mm:ss", where hh is the number of  hours  past  midnight 
  1697.          local  time,  mm is the number of minutes past the hour, and 
  1698.          ss is the number of seconds past the whole minute.
  1699.  
  1700. __STDC__ The integer constant 1.  This constant is meant to  indicate 
  1701.          that  the  compiler/preprocessor  is  as  conforming  ANSI C 
  1702.          implementation.
  1703.  
  1704. The Standard restricts the preprocessor from redefining any of  these 
  1705. macro  names,  as  well  as  attempting  to  undefine  any  of  them.  
  1706. Similarly, the standard precludes the use of #define or #undef on the 
  1707. identifier  `defined'  (which  has  special  meaning  in evaluating a 
  1708. #if/elif directive).
  1709.  
  1710. JRCPP supports the full ANSI  C  Standard  as  indicated  above,  but 
  1711. maintains  customization  features  that  allow  it  to  be  modified 
  1712. slightly to be non-conforming.
  1713.  
  1714. One major point is that most of the time, the compiler that JRCPP  is 
  1715. preprocessing  for  is  not  ANSI conformant.  With this situation in 
  1716. mind, there must be some mechanism for undefining __STDC__.   Special 
  1717. pragmas have been provided in JRCPP to accomplish most of these tasks 
  1718. (see #pragma undefine_macros).
  1719.  
  1720. As a special note, the pragma that switches to C++ mode (see  #pragma 
  1721. cplusplus_mode)  has  the  following  effect:  The  macro __STDC__ is 
  1722. undefined, and the macro __cplusplus is defined.  Moreover, this  new 
  1723. macro  __cplusplus  has  the  same  reserved  status (i.e.: cannot be 
  1724. #define'd or #undef'ed) as __STDC__  has  under  default  JRCPP.   In 
  1725. addition,  the  one  line // style comments are also supported in c++ 
  1726. mode.
  1727.  
  1728.  
  1729.