esc/es4-doc/conditional-compilation.txt

   1 NAME:       "Conditional compilation"
   2 CATEGORY:   Lexical conventions (E262-3 ch 7)
   3 SOURCES:    (none)
   4 AUTHOR:     Lars
   5 STATUS:     ?
   6 REVIEWS:    ?
   7 RI STATUS:  ?
   8 ESC STATUS: ?
   9 TEST CASE:  ?
  10
  11
  12            **** VERY PRELIMINARY ****
  13            **** UNAPPROVED PROPOSAL ****
  14
  15 Notes:
  16
  17   - This needs to be compatible somehow with the MSIE approach
  18
  19   - The condition should really be restricted to "version=n" which
  20     tests whether the browser can handle language version n or higher.
  21     IOW, this is equivalent to the mime-type test.
  22
  23   - It's an interesting fact that code that loads scripts dynamically
  24     into a browser that does not support this facility directly
  25     can perform the preprocessing fairly easily using existing facilities.
  26     That would be a good way to define its semantics.
  27
  28
  29 DESCRIPTION
  30
  31 A block comment that is preceded on the same line only by horizontal
  32 whitespace and that starts with the four-character sequence /**@ is
  33 part of a conditional compilation directive.
  34
  35 A condition must follow the @ without intervening spaces.
  36
  37 If the block comment does not end on the same line then:
  38
  39   If the condition is true, then the text in the block comment
  40   starting from the line following the end of the condition through
  41   the end of the comment is inserted into the source stream.
  42   Otherwise the contents of the block comment are removed, just as
  43   if the comment were an ordinary comment.
  44
  45 Otherwise, if the block comment does end on the same line then:
  46
  47   If the condition is false, then all the source text following the
  48   comment up until the next block comment that begins with the text
  49   /**@end (no leading whitespace etc) is removed from the source
  50   stream.  Otherwise it is left in place .
  51
  52   - if the block comment does end on the same line, then the text following
  53
  54 Directives may nest (useful to test for version=5 inside version=4 code).
  55
  56 No gunk after the condition, or after @else or @end -- only
  57 whitespace (arbitrary linefeeds OK) and the end-comment thing.
  58
  59 /**@version=4
  60 testing
  61    @else */     // preceded by whitespace, followed by end-of-comment
  62
  63 /**@endif */
  64
  65
  66 EXAMPLE 1
  67
  68 /**@version=4
  69
  70 class Point {
  71   function Point(x, y) : x=x, y=y {}
  72   function scale(n) {
  73     x *= 2
  74     y *= 2
  75   }
  76   var x, y
  77 }
  78
  79   @else */
  80
  81 function Point(x, y) {
  82   this.x = x
  83   this.y = y
  84 }
  85
  86 Point.prototype = {
  87   scale:
  88     function (n) {
  89       x *= 2;
  90       y *= 2;
  91     }
  92 }
  93 /**@end */
  94
  95
  96 EXAMPLE 2
  97
  98 /**@version=3 */
  99 clclclc
 100 /**@end */