5. Preprocessor

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 cpp call.

5.1. Charset Heuristics

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.

Byte 0Byte 1Interpretation
0032bit wide string.
0>016bit Unicode string.
>0016bit Unicode string in reverse byte order.
0xfe0xff16bit Unicode string.
0xff0xfe16bit Unicode string in reverse byte order.
0x7b0x83EBCDIC-US ("#c").
0x7b0x40EBCDIC-US ("# ").
0x7b0x09EBCDIC-US ("#\t").

5.2. Code Normalization

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 <ESC>[\040-\077]+[\100-\177] and <CSI>[\040-\077]*[\100-\177]. Note that this means that it is possible to do color markup in the actual source file.

The preprocessor will treat seven consecutive < characters outside of a string as an version control conflict error and will return "Merge conflict detected."

5.3. Defines and Macros

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.

#define DO_OVERSAMPLING

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

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

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. pike -DDO_OVERSAMPLING my_program.pike.

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

#define CYCLES 20

void do_stuff() {
  for(int i; i<CYCLES; i++) do_other_stuff();
}

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

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

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.

#define VAR(X) id->misc->variable[X]
#define ROL(X,Y) (((X)<<(Y))&7+((X)>>(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()

5.4. Preprocessor Directives

All of the preprocessor directives except the string-related (#string and #"") should have the hash character (#) as the first character of the line. Even though it is currently allowed to be indented, it is likely that this will generate warnings or errors in the future. Note that it is however allowed to put white-space between the hash character and the rest of the directive to create indentation in code.


Directive #!

#!

Description

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


Directive #line
Directive #<integer>

#line
#<integer>

Description

A hash character followed by a number or by the string "line" 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. #line 1 "/home/pike/program.pike.in". Then this filename will be used instead of the current file for error messages.


Directive #""

#""

Description

If a string literal is opened with #" newlines in the string will end up in the string literal, instead of triggering a "newline in string" error.

Note

Newlines will be converted to \n characters in the string even if the newlines in the file are something else.

This preprocessor directive may appear anywhere a string may appear.

See also

#string


Directive #(#)
Directive #[#]
Directive #{#}

#(#)
#[#]
#{#}

Description

If a string literal is opened with #( all subsequent characters until the closing #) will be treated as literals, including newlines, \, " and '.

There are three different pairs of start/end tokens for this type of literals, #( and #), #[ and #], and #{ and #}.

Example

#["\n\'##] is equivalent to "\"\\n\\'#".


Directive #string

#string

Description

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.

Example
do_something(#string "the_file.wks"
);
See also

#include


Directive #include

#include

Description

#include is 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, or searched for in the include paths.

To include a file with absolute or relative path, use double quotes, e.g. #include "constants.pike" or #include "../debug.h".

To include from the include paths, use less than and greater than, e.g. #include <profiling.h>.

It is also possible to include a file whose path is defined in a preprocessor macro, e.g. #include USER_SETTINGS.


Directive #if

#if

Description

The #if directive can evaluate simple expressions and, if the expression is evaluates to true, "activate" the code block that follows. The code block ends when an #endif, #else, #elseif or #elif block is encountered at the same nesting depth.

The #if expressions may include defines, integer, string and float constants, ?:, || and && operations, ~, ^, !, | and & operations, <, >, <=, >=, == and != operations, +, -, *, /, << and >> operations and paranthesis.

Strings may also be indexed with the [] index operator. Finally there are three special "functions" available in #if expressions; defined(), efun() and constant().

See also

#ifdef, #ifndef, #elif, #else, #endif, defined(), constant(), efun()


Directive #ifdef

#ifdef

Description

Check whether an identifier is a macro.

The directive

#ifdef <identifier>

is equivalent to

#if defined(<identifier>)

See also

#if, #ifndef, defined


Directive #ifndef

#ifndef

Description

Check whether an identifier is not a macro.

This is the inverse of #ifdef.

The directive

#ifndef <identifier>

is equivalent to

#if !defined(<identifier>)

See also

#if, #ifdef, defined


Directive #endif

#endif

Description

End a block opened with #if, #ifdef, #ifndef, #else, #elseif or #elif.

Example
#ifdef DEBUG
    do_debug_stuff();
  #endif // DEBUG

Directive #else

#else

Description

This directive is used to divide the current code block into another code block with inverse activation.

Example
#ifdef FAST_ALGORITHM
    do_fast_algorithm();
  #elif defined(EXPERIMENTAL_ALGORITHM)
    do_experimental_algorithm();
  #else
    do_default_algorithm();
  #endif

Directive #elif
Directive #elseif

#elif
#elseif

Description

These work as a combined #else and #if without adding an extra level of nesting.

Example

The following two are equivalent:

#ifdef A
    // Code for A.
  #else
  #ifdef B
    // Code for B.
  #else
  #ifdef C
    // Code for C.
  #else
    // Code for D.
  #endif
  #endif
  #endif

And

#ifdef A
    // Code for A.
  #elif defined(B)
    // Code for B.
  #elseif defined(C)
    // Code for C.
  #else
    // Code for D.
  #endif
See also

#if, #ifdef, #else, defined(), constant()


Directive #elifdef
Directive #elseifdef

#elifdef
#elseifdef

Description

These work as a combined #else and #ifdef without adding an extra level of nesting.

Example

The following two are equivalent:

#ifdef A
    // Code for A.
  #else
  #ifdef B
    // Code for B.
  #else
  #ifdef C
    // Code for C.
  #else
    // Code for D.
  #endif
  #endif
  #endif

And

#ifdef A
    // Code for A.
  #elifdef B
    // Code for B.
  #elseifdef C
    // Code for C.
  #else
    // Code for D.
  #endif
See also

#if, #ifdef, #else, defined(), constant()


Directive #elifndef
Directive #elseifndef

#elifndef
#elseifndef

Description

These work as a combined #else and #ifndef without adding an extra level of nesting.

Example

The following two are equivalent:

#ifndef A
    // Code for not A.
  #else
  #ifndef B
    // Code for not B.
  #else
  #ifdef C
    // Code for not C.
  #else
    // Code for ABC.
  #endif
  #endif
  #endif

And

#ifndef A
    // Code for not A.
  #elifndef B
    // Code for not B.
  #elseifndef C
    // Code for not C.
  #else
    // Code for ABC.
  #endif
See also

#if, #ifdef, #else, defined(), constant()


Directive #define

#define

Description

This directive is used to define or redefine a cpp macro.

The simplest way to use define is to write

#define <identifier> <replacement string>

which will cause all subsequent occurances of <identifier to be replaced with the <replacement string>.

Define also has the capability to use arguments, thus a line like

#define <identifier>(arg1, arg2) <replacement string>

would cause <identifer> to be a macro. All occurances of '<identifier>(something1,something2d)' would be replaced with the <replacement string>. And in the <replacement string>, arg1 and arg2 will be replaced with something1 and something2.


Directive #undef
Directive #undefine

#undef
#undefine

Description

This removes the effect of a #define, all subsequent occurances of the undefined identifier will not be replaced by anything.

Note

Note that when undefining a macro, you just give the identifer, not the arguments.

Example

// Strip debug #define werror(X ...) 0 #include "/home/someone/experimental/stuff.h" #undef werror

See also

#define, defined()


Directive #charset

#charset

Description

Inform the preprocessor about which charset the file is encoded with. The Charset module is called with this string to decode the remainder of the file.


Directive #pike

#pike

Description

Set the Pike compiler backward compatibility level.

This tells the compiler which version of Pike it should attempt to emulate from this point on in the current compilation unit.

This is typically used to "quick-fix" old code to work with more recent versions of Pike.

Example
// This code was written for Pike 7.2, and depends on
  // the old behaviour for 7.2::dirname().
  #pike 7.2

  // ... Code that uses dirname() ...

This directive is also needed for Pike modules that have been installed globally, and might be used by a Pike that has been started with the -V flag.

Example
// Pike modules that are bundled with Pike are
  // typically written for the same version of Pike.
  #pike __REAL_VERSION__

Directive #pragma

#pragma

Description

This is a generic directive for flags to the compiler.

These are some of the flags that are available:

"all_inline"

This is the same as adding the modifier inline to all functions that follow.

"all_final"

Instructs the compiler to mark all symbols as final.

"deprecation_warnings"

Enable warnings for use of deprecated or experimental symbols (default). Note that this does not enable warnings for experimental symbols if those warnings have been disabled explicitly via "no_experimental_warnings".

"no_deprecation_warnings"

Disable warnings for use of deprecated or experimental symbols. This is typically used in code that implements the deprecated symbols.

"experimental_warnings"

Enable warnings for use of experimental symbols (default). Note that this does not enable warnings for experimental symbols when warnings for deprecated symbols are disabled.

"no_experimental_warnings"

Disable warnings for use of experimental symbols. This is typically used in code that implements or tests the experimental symbols.

"save_parent"

Cause nested classes to save a reference to their surrounding class even if not strictly needed.

"dont_save_parent"

Inverse of "save_parent". This is needed to override if the global symbol predef::__pragma_save_parent__ has been set.

"strict_types"

Enable warnings for all cases where the compiler isn't certain that the types are correct.

"disassemble"

Enable disassembly output for the code being compiled. Note that this option essentially has a function-level scope, so enabling it for just a few lines is usually a noop. This is similar to Debug.assembler_debug() level 3.

"no_disassemble"

Disable disassembly output (default).


Directive #require

#require

Description

If the directive evaluates to false, the source file will be considered to have failed dependencies, and will not be found by the resolver. In practical terms the cpp() call will return zero.

See also

#if


Directive #warning

#warning

Description

Generate a warning during preprocessing.

This directive causes a cpp warning, it can be used to notify the user that certain functions are missing and similar things.

Example
#if !constant(Yp)
  #warning Support for NIS not available. Some features may not work.
  #endif
See also

#error


Directive #error

#error

Description

Throw an error during preprocessing.

This directive causes a cpp error. It can be used to notify the user that certain functions are missing and similar things.

Note

Note that this directive will cause cpp() to throw an error at the end of preprocessing, which will cause any compilation to fail.

Example
#if !constant(Yp)
  #error Support for NIS not available.
  #endif
See also

#warning

5.5. Predefined defines


Constant __VERSION__

constant __VERSION__

Description

This define contains the current Pike version as a float. If another Pike version is emulated, this define is updated accordingly.

See also

__REAL_VERSION__


Constant __MAJOR__

constant __MAJOR__

Description

This define contains the major part of the current Pike version, represented as an integer. If another Pike version is emulated, this define is updated accordingly.

See also

__REAL_MAJOR__


Constant __MINOR__

constant __MINOR__

Description

This define contains the minor part of the current Pike version, represented as an integer. If another Pike version is emulated, this define is updated accordingly.

See also

__REAL_MINOR__


Constant __BUILD__

constant __BUILD__

Description

This constant contains the build number of the current Pike version, represented as an integer. If another Pike version is emulated, this constant remains unaltered.

See also

__REAL_MINOR__


Constant __REAL_VERSION__

constant __REAL_VERSION__

Description

This define always contains the version of the current Pike, represented as a float.

See also

__VERSION__


Constant __REAL_MAJOR__

constant __REAL_MAJOR__

Description

This define always contains the major part of the version of the current Pike, represented as an integer.

See also

__MAJOR__


Constant __REAL_MINOR__

constant __REAL_MINOR__

Description

This define always contains the minor part of the version of the current Pike, represented as an integer.

See also

__MINOR__


Constant __REAL_BUILD__

constant __REAL_BUILD__

Description

This define always contains the minor part of the version of the current Pike, represented as an integer.

See also

__BUILD__


Constant __DATE__

constant __DATE__

Description

This define contains the current date at the time of compilation, e.g. "Jul 28 2001".


Constant __TIME__

constant __TIME__

Description

This define contains the current time at the time of compilation, e.g. "12:20:51".


Constant __FILE__

constant __FILE__

Description

This define contains the file path and name of the source file.


Constant __DIR__

constant __DIR__

Description

This define contains the directory path of the source file.


Constant __LINE__

constant __LINE__

Description

This define contains the current line number, represented as an integer, in the source file.


Variable __COUNTER__

int(1..) __COUNTER__

Description

This define contains a unique counter (unless it has been expanded Int.NATIVE_MAX times) represented as an integer.


Constant __AUTO_BIGNUM__

constant __AUTO_BIGNUM__

Description

This define is defined when automatic bignum conversion is enabled. When enabled all integers will automatically be converted to bignums when they get bigger than what can be represented by an integer, hampering performance slightly instead of crashing the program. This define is always set since Pike 8.0.


Constant __NT__

constant __NT__

Description

This define is defined when the Pike is running on a Microsoft Windows OS, not just Microsoft Windows NT, as the name implies.


Constant __PIKE__

constant __PIKE__

Description

This define is always true.


Constant __amigaos__

constant __amigaos__

Description

This define is defined when the Pike is running on Amiga OS.


Constant __APPLE__

constant __APPLE__

Description

This define is defined when the Pike is running on MacOS X.


Constant __HAIKU__

constant __HAIKU__

Description

This define is defined when the Pike is running on Haiku.


Method _Pragma

void _Pragma(string directive)

Description

This macro inserts the corresponding #pragma directive in the source.

e.g. _Pragma("strict_types") is the same as #pragma strict_types .

See also

#pragma


Constant static_assert

constant static_assert

Description

This define expands to the symbol _Static_assert.

It is the preferred way to perform static (ie compile-time) assertions.

Note

The macro can also be used to check for whether static assertions are supported.

See also

predef::_Static_assert()

5.6. Test functions

These functions are used in #if et al expressions to test for presence of symbols.


Method constant
Method efun

bool constant(mixed identifier)
__deprecated__ bool efun(mixed identifier)

Description

Check whether the argument resolves to a constant or not.

See also

#if, defined()


Method defined

bool defined(mixed identifier)

Description

Check whether an identifier is a cpp macro or not.

Returns

defined returns true if the symbol given as argument is defined.

Note

#if defined(MY_DEF) is equivalent to #ifdef MY_DEF.

See also

#if, #ifdef, constant()