<chapter title="Preprocessor">

<p>Before the Pike code is sent to the compiler it is fed through the
preprocessor. The preprocessor converts the source code from its
character encoding into the Pike internal representation, performs
some simple normalizations and consistency checks and executes the
"preprocessor directives" that the programmer may have put into the
file. The preprocessor directives are like a very simple programming
language that allows for simple code generation and manipulation.
The code preprocessor can be called from within Pike with the
<ref>cpp</ref> call.</p>

<section title="Charset Heuristics">

<p>Pike code is Unicode enabled, so the first thing the preprocessor
has to do is to try to determine the character encoding of the file.
It will first look at the two first bytes of the file and interpret
them according to this chart.</p>

<matrix>
<r><c><b>Byte 0</b></c><c><b>Byte 1</b></c><c><b>Interpretation</b></c></r>
<r><c>0</c><c>0</c><c>32bit wide string.</c></r>
<r><c>0</c><c>&gt;0</c><c>16bit Unicode string.</c></r>
<r><c>&gt;0</c><c>0</c><c>16bit Unicode string in reverse byte order.</c></r>
<r><c>0xfe</c><c>0xff</c><c>16bit Unicode string.</c></r>
<r><c>0xff</c><c>0xfe</c><c>16bit Unicode string in reverse byte order.</c></r>
<r><c>0x7b</c><c>0x83</c><c>EBCDIC-US ("#c").</c></r>
<r><c>0x7b</c><c>0x40</c><c>EBCDIC-US ("# ").</c></r>
<r><c>0x7b</c><c>0x09</c><c>EBCDIC-US ("#\t").</c></r>
</matrix>

<ul>
<li>With any other combination of bytes the preprocessor will assume
iso-8859-1 encoding until a #charset directive has been found.</li>
<li>The file must be an multiple of 4 or 2 bytes in order to be correctly
decoded as 32bit or 16bit wide string.</li>
<li>It's an error for a program written in EBCDIC not to start with a
#charset directive.</li>
<li>For obfuscation it is possible to encode the #charset directive in
a different charset than the charset stated in the #charset directive.</li>
</ul>

</section>

<section title="Code Normalization">

<p>The preprocessor collapses all consecutive white space characters
outside of strings, except for newlines, to single space characters.
All // and /**/ comments are removed, as are #! lines. Pike considers
ANSI/DEC escape sequences as white space. Supported formats are
&lt;ESC&gt;[\040-\077]+[\100-\177] and
&lt;CSI&gt;[\040-\077]*[\100-\177]. Note that this means that it is
possible to do color markup in the actual source file.</p>

<p>The preprocessor will treat seven consecutive &lt; characters
outside of a string as an CVS conflict error and will return "CVS
conflict detected."</p>

</section>

<section title="Defines and Macros">

<p>Defining macros or constants is one of the most used preprocessor
features. It enables you to make abstractions on a code generation
level as well as altering constants cross-application. The simplest
use of the #define directive however is to declare a "define" as
present.</p>

<example>
#define DO_OVERSAMPLING
</example>

<p>The existence of this definition can now be used by e.g. #ifdef and
#ifndef to activate or deactivate blocks of program code.</p>

<example>
#ifdef DO_OVERSAMPLING
  // This code is not always run.
  img->render(size*4)->shrink(4);
#endif
</example>

<p>Note that defines can be given to pike at execution time. In order
to set DO_OVERSAMPLING from a command line, the option
-DDO_OVERSAMPLING is added before the name of the pike program. E.g.
<tt>pike -DDO_OVERSAMPLING my_program.pike</tt>.</p>

<p>A define can also be given a specific value, which will be inserted
everywhere the define is placed in the source code.</p>

<example>
#define CYCLES 20

void do_stuff() {
  for(int i; i&lt;CYCLES; i++) do_other_stuff();
}
</example>

<p>Defines can be given specific values on the command line too, just
be sure to quote them as required by your shell.</p>

<example>
~% pike '-DTEXT="Hello world!"' -e 'write("%s\n", TEXT);'
Hello world!
</example>

<p>Finally #define can also be used to define macros. Macros are just
text expansion with arguments, but it is often very useful to make a
cleaner looking code and to write less.</p>

<example>
#define VAR(X) id-&gt;misc-&gt;variable[X]
#define ROL(X,Y) (((X)&lt;&lt;(Y))&amp;7+((X)&gt;&gt;(8-(Y))))
#define PLACEHOLDER(X) void X(mixed ... args) { \
  error("Method " #X " is not implemented yet.\n"); }
#define ERROR(X,Y ...) werror("MyClass" X "\n", Y)
#define NEW_CONSTANTS(X) do{ int i=sizeof(all_constants()); \
    X \
    werror("Constant diff is %d\n", sizeof(all_constants())-i); \
  }while(0)
#define MY_FUNC(X,Y) void my##X##Y()
</example>

<ul>
<li>A macro can have up to 254 arguments.</li>
<li>It can be wise to put extra parentheses around the arguments
expanded since it is a purely textual expansion. E.g. if the macro
DOUBLE(X) is defined as X*2, then DOUBLE(2+3) will produce 2+3*2,
probably producing a hard to track down bug.</li>
<li>Since the preprocessor works with textual expansion, it will not
evaluate its arguments. Using one argument several time in the macro
will thus cause it to evaluated several times during execution. E.g.
#define MSG(X) werror("The value "+(X)+" can differ from "+(X)+"\n")
when called with MSG(random(1000));.</li>
<li>A backslash (\) at the end of the line can be used to make the
definition span several lines.</li>
<li>A hash (#) in front of a macro variable "casts" it to a string.</li>
<li>It is possible to define macros with a variable list of arguments
by using the ... syntax.</li>
<li>Macros are often formulated so that a semicolon after it is
apropriate, for improved code readability.</li>
<li>In Pike code macros and defines are most often written in all caps.</li>
<li>If a macro expands into several statements, you are well advised to
group them together in containment block, such as do { BODY } while(0).
If you do not, your macro could produce other hard to track down bugs,
if put as a loop or if body without surrounding curly braces.</li>
<li>A double hash (##) in front of a macro variable concatenates it with
the text before it.</li>
</ul>

</section>

<section title="Preprocessor Directives">

<p>All the preprocessor directives should be at the beginning of the
line. Although indentation is allowed currently, it is possible that
it will generate warnings or errors in the future. It is however
allowed to put spaces after the hash character to create indentation
in code.</p>

<subsection title="#!">
<p>All lines beginning with <tt>#!</tt> will be regarded as comments,
to enable shell integration. It is recommended that Pike applications
begin with the line <tt>"#! /usr/bin/env pike"</tt> for maximum cross
platform compatibility.</p>
</subsection>

<subsection title="#&lt;integer&gt; and #line">
<p>A hash character followed by a number or by the string
<tt>"line"</tt> and a number will make the preprocessor line counter
set this number as the line number for the next line and adjust the
following lines accordingly. All error messages from Pike will use
these line numbers. Optionally the number may be followed by a file
name, e.g. <tt>#1 "/home/pike/program.pike.in"</tt>. Then this
filename will be used instead of the current file for error
messages.</p>
</subsection>

<subsection title='#""'>
<p>If a string literal is opened with <tt>#"</tt> newlines in the
string will end up in the string literal, instead of triggering a
<tt>"newline in string"</tt> error. Newlines will be converted to
<tt>\n</tt> characters if the newlines in the file is something else.
This preprocessor directive may appear anywhere a string may
appear.</p>
</subsection>

<subsection title="#string">
<p>The preprocessor directive #string will load the file in the
string that follows and insert its contents as a string. This
preprocessor directive may appear anywhere a string may appear.</p>
<example>
do_something(#string "the_file.wks");
</example>
</subsection>

<subsection title="#include">
<p><tt>#include</tt> may be used to insert the contents of another
file into the processed file at the place of the include directive.
Files can be referenced either by absolute or relative path from the
source file by using double quotes, or searched for in the include
paths. To include a file with absolute or relative path, use double
quotes, e.g. <tt>#include "constants.pike"</tt> or <tt>#include
"../debug.h"</tt>. To include from the include paths, use less than
and greater than, e.g. <tt>#include &lt;profiling.h&gt;</tt>. It is
also possible to include a file whose path is defined in a
preprocessor define, e.g. <tt>#include USER_SETTINGS</tt>.</p>
</subsection>

<subsection title="#if">
<p>The <tt>#if</tt> directive can evaluate simple expressions and, if
the expression is evaluated to true, "activate" the code block that
follows. The code block ends when an <tt>#endif</tt>, <tt>#else</tt>,
<tt>#elseif</tt> or <tt>#elif</tt> block is encountered on the same
nesting depth.</p>

<p>The <tt>#if</tt> expressions may include defines, integer, string
and float constants, ?:, || and &amp;&amp; operations, ~, ^, !, | and
&amp; operations, &lt;, &gt;, &lt;=, &gt;=, == and != operations, +,
-, *, /, &lt;&lt; and &gt;&gt; operations and paranthesis. Strings may
also be indexed with the [] index operator. Finally there are three
special "functions" available in <tt>#if</tt> expressions; defined,
efun and constant. Define returns true if the symbol given as argument
is defined. <tt>#if defined(MY_DEF)</tt> is equal to <tt>#ifdef
MY_DEF</tt>. Efun returns true if its argument is an efun and constant
returns true if its argument can be resolved into a constant.</p>
</subsection>

<subsection title="#ifdef">
<p><tt>#ifdef</tt> works as <tt>#if</tt>, but instead of evaluating
its arguments it just checks if the first symbol is a defined define
or marcro.</p>
</subsection>

<subsection title="#ifndef">
<p>Works as an inverted <tt>#ifndef</tt>; it only "activates" the
following block if the symbol is not defined.</p>
</subsection>

<subsection title="#endif">
<p>Ends a block opened by <tt>#if</tt>, <tt>#ifdef</tt>, <tt>#ifndef</tt>,
<tt>#else</tt>, <tt>#elseif</tt> or <tt>#elif</tt>.</p>
<example>
#if DEBUG
do_debug_stuff();
#endif /* DEBUG */
</example>
</subsection>

<subsection title="#else">
<p>This directive is used to divide the current code block into another
code block with inverse activation.</p>
<example>
#ifdef FAST_ALGORITHM
do_fast_algorithm();
#elif defined(EXPERIMENTAL_ALGORITHM)
do_experimental_algorithm();
#else
do_default_algorithm();
#endif
</example>
</subsection>

<subsection title="#elseif and #elif">
<p><tt>#elseif</tt> and <tt>#elif</tt> works as <tt>elseif</tt> in the
<tt>#if</tt>/<tt>#ifdef</tt>/<tt>#ifndef</tt> context.</p>
</subsection>

<subsection title="#undefine and #undef">
<p><tt>#undefine</tt> and <tt>#undefine</tt> undefines the symbol
given as argument.</p>
<example>
// Strip debug
#define werror(X ...) lambda(X){}
#include "/home/someone/experimental/stuff.h"
#undef werror
</example>
</subsection>

<subsection title="#error">
<p>Throws an error during preprocessing.</p>
<example>
#ifdef __NT__
#error "This program can not run on MS Windows."
#endif
</example>
</subsection>

<subsection title="#charset">
<p>Tells the preprocessor which charset the file is encoded with. The
Locale.Charset module is called with this string to decode the
file.</p>
</subsection>

<subsection title="#pike">
<p>Tells the compiler which version of Pike it should emulate.</p>
<example>
#pike 7.2
</example>
</subsection>

<subsection title="#pragma all_inline">
</subsection>

<subsection title="#pragma all_final">
<p>Instructs the compiler to mark all symbols as final.</p>
</subsection>

<subsection title="#pragma all_nomask">
<p>Deprecated version of #pragma all_final</p>
</subsection>

<subsection title="#pragma strict_types">
</subsection>

<subsection title="#pragma save_parent and #pragma dont_save_parent">
</subsection>

<subsection title="#warning">
<p>Generates a warning during compilation.</p>
<example>
#if !constant(Crypto.SHA1.hash)
#warning SHA1 hash not available.
#endif
</example>
</subsection>

</section>

<section title="Predefined defines">
  <insert-move entity="cpp::"/>
</section>

</chapter>