SecuritySNACCRuntime/doc/coding.tex

   1 % file: .../doc/coding.tex
   2
   3 % $Header: /cvs/Darwin/Security/SecuritySNACCRuntime/doc/coding.tex,v 1.1.1.1 2001/05/18 23:14:10 mb Exp $
   4 % $Log: coding.tex,v $
   5 % Revision 1.1.1.1  2001/05/18 23:14:10  mb
   6 % Move from private repository to open source repository
   7 %
   8 % Revision 1.1.1.1  1999/03/16 18:05:52  aram
   9 % Originals from SMIME Free Library.
  10 %
  11 % Revision 1.1  1997/01/01 22:47:48  rj
  12 % first check-in
  13 %
  14
  15 \chapter{\label{coding-tricks}Coding Tricks For Readability}
  16
  17 \index{ANSI C}
  18 \index{K&R C}
  19 \index{PROTO}
  20 \index{PARAM}
  21 \index{COMMA}
  22
  23 One of our project partners needed some additional function arguments and so they duplicated the function declarator and put a preprocessor switch around it.
  24 The metacode and the Tcl interface added some additional compilation conditions.
  25 Since the Tcl interface is only useful on top of the metacode, there are six different combinations instead of eight.
  26 Even these six combinations would have made the code very ugly.
  27 Please decide for yourself, here is an example with an example function with only up to four arguments, {\C PrintCxxCode()} has up to 17 arguments.
  28
  29 \begin{Ccode}
  30 static void\\
  31 \#if A\\
  32 FunctionName PARAMS ((a, b),\\
  33   \>TypeA a \_AND\_\\
  34   \>TypeB b)\\
  35 \#if B\\
  36 FunctionName PARAMS ((a, b, c),\\
  37   \>TypeA a \_AND\_\\
  38   \>TypeB b \_AND\_\\
  39   \>TypeC c)\\
  40 \#if C\\
  41 FunctionName PARAMS ((a, b, c, d),\\
  42   \>TypeA a \_AND\_\\
  43   \>TypeB b \_AND\_\\
  44   \>TypeC c \_AND\_\\
  45   \>TypeD d)\\
  46 \#endif\\
  47 \#endif\\
  48 \#else\\
  49 FunctionName PARAMS ((b),\\
  50   \>TypeB b)\\
  51 \#if B\\
  52 FunctionName PARAMS ((b, c),\\
  53   \>TypeB b \_AND\_\\
  54   \>TypeC c)\\
  55 \#if C\\
  56 FunctionName PARAMS ((b, c, d),\\
  57   \>TypeB b \_AND\_\\
  58   \>TypeC c \_AND\_\\
  59   \>TypeD d)\\
  60 \#endif\\
  61 \#endif\\
  62 \#endif
  63 \end{Ccode}
  64
  65 Here is the code after introduction of my shorthand:
  66
  67 \begin{Ccode}
  68 static void\\
  69 FunctionName PARAMS ((if\_A (a COMMA) b if\_C (COMMA c) if\_D (COMMA d)),\\
  70   \>if\_A (TypeA a \_AND\_)\\
  71   \>TypeB b\\
  72   \>if\_C (\_AND\_ TypeC c)\\
  73   \>if\_D (\_AND\_ TypeD d))
  74 \end{Ccode}
  75
  76 The tricks are very simple.
  77 One is the {\C if\_\dots} macro
  78
  79 \begin{Ccode}
  80 \#if A\\
  81 \#define if\_A( code)                   \>\>\>code\\
  82 \#else\\
  83 \#define if\_A( code)
  84 \#endif
  85 \end{Ccode}
  86
  87 that lets us get rid of at least four lines of code for every invocation, and the other trick is the {\C COMMA} macro
  88
  89 \begin{Ccode}
  90 \#define COMMA \>\>\>,
  91 \end{Ccode}
  92
  93 that makes the arguments to the {\C if\_\dots{}} macros look like a single argument.
  94 Without this trick,
  95
  96 The other trick, of course is the {\C if\_\dots{}} macro itself.
  97 The {\C if\_\dots{}} macros have to expand into code without brackets, for example {\C if\_A (a COMMA b)} exands into {\C a, b}.
  98 The {\C COMMA} is not my invention, snacc's {\C \_AND\_} macro is exactly the same.
  99 Both {\C \_AND\_} and {\C COMMA} serve the purpose of being a comma (``,'') as the final result (well, only for ANSI C, for K\&R C, the {\C \_AND\_} becomes a semicolon), but without being an argument separator to the C preprocessor.
 100 The {\C PROTO} macro that was already present in snacc 1.1 gets a single argument as well, but by means of additional parenthesis, inside which commas can savely be used.
 101 It expands into code with brackets around it: {\C PROTO ((int a, char~*b))} expands into {\C (int a, char~*b)}.
 102 The first argument to the {\C PARAM} macro is bracketed list as well, and for the arguments purpose, to be a function argument list, this is fine.
 103
 104 To have both an ANSI C and a K\&R C version, without {\C PROTO}, {\C PARAMS} and supporting macros, twelve conditional code compilations would have to be written out instead of one!
 105 And what a tedious job to maintain all twelve versions!