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.
|
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 CVS conflict error and will return "CVS 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; iDefines 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()
- A macro can have up to 254 arguments.
- It can be wise to put extra parentheses around the arguments expanded since it is a purely textual expansion. I.e. 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.
- A backslash (\) at the end of the line can be used to make the definition span several lines.
- A hash (#) in front of a macro variable "casts" it to a string.
- It is possible to define macros with a variable list of arguments by using the ... syntax.
- Macros are often formulated so that a semicolon after it is apropriate, for improved code readability.
- In Pike code macros and defines are most often written in all caps.
- 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.
- A double hash (##) in front of a macro variable concatenates it with the text before it.
5.4. Preprocessor Directives |
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.
5.4.1. #! |
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.
5.4.2. #<integer> and #line |
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. #1 "/home/pike/program.pike.in". Then this filename will be used instead of the current file for error messages.
5.4.3. #"" |
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. Newlines will be converted to \n characters if the newlines in the file is something else. This preprocessor directive may appear anywhere a string may appear.
5.4.4. #string |
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.
do_something(#string "the_file.wks");
5.4.5. #include |
#include 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. #include "constants.pike" or #include "../debug.h". To include from the include paths, use less than and greater than, e.g. #include <profiling.h>.
5.4.6. #if |
The #if 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 #endif, #else, #elseif or #elif block is encountered on 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. Define returns true if the symbol given as argument is defined. #if defined(MY_DEF) is equal to #ifdef MY_DEF. Efun returns true if its argument is an efun and constant returns true if its argument can be resolved into a constant.
5.4.7. #ifdef |
#ifdef works as #if, but instead of evaluating its arguments it just checks if the first symbol is a defined define or marcro.
5.4.8. #ifndef |
Works as an inverted #ifndef; it only "activated" the following block if the symbol is not defined.
5.4.9. #endif |
Ends a block opened by #if, #ifdef, #ifndef, #else, #elseif or #elif.
#if DEBUG do_debug_stuff(); #endif /* DEBUG */
5.4.10. #else |
This directive is used to divide the current code block into another code block with inverse activation.
#ifdef FAST_ALGORITHM do_fast_algorithm(); #elif defined(EXPERIMENTAL_ALGORITHM) do_experimental_algorithm(); #else do_default_algorithm(); #endif
5.4.11. #elseif and #elif |
#elseif and #elif works as elseif in the #if/#ifdef/#ifndef context.
5.4.12. #undefine and #undef |
#undefine and #undefine undefines the symbol given as argument.
// Strip debug #define werror(X ...) lambda(X){} #include "/home/someone/experimental/stuff.h" #undef werror
5.4.13. #error |
Throws an error during preprocessing.
#ifdef __NT__ #error "This program can not run on MS Windows." #endif
5.4.14. #charset |
Tells the preprocessor which charset the file is encoded with. The Locale.Charset module is called with this string to decode the file.
5.4.15. #pike |
Tells the compiler which version of Pike it should emulate.
#pike 7.2
5.4.16. #pragma all_inline |
5.4.17. #pragma all_nomask |
5.4.18. #pragma strict_types |
5.4.19. #pragma save_parent and #pragma dont_save_parent |
5.4.20. #warning |
Generates a warning during compilation.
#if !constant(Crypto.SHA1.hash) #warning SHA1 hash not available. #endif
5.5. Predefined defines |
Namespace cpp:: |
constant __VERSION__
This define contains the current Pike version as a float. If another Pike version is emulated, this define is updated accordingly.
__REAL_VERSION__
constant __REAL_VERSION__
This define always contains the version of the current Pike, represented as a float.
__VERSION__
constant __MAJOR__
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.
__REAL_MAJOR__
constant __REAL_MAJOR__
This define always contains the major part of the version of the current Pike, represented as an integer.
__MAJOR__
constant __MINOR__
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.
__REAL_MINOR__
constant __REAL_MINOR__
This define always contains the minor part of the version of the current Pike, represented as an integer.
__MINOR__
constant __BUILD__
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.
__REAL_MINOR__
constant __REAL_BUILD__
This define always contains the minor part of the version of the current Pike, represented as an integer.
__BUILD__
constant __LINE__
This define contains the current line number, represented as an integer, in the source file.
constant __FILE__
This define contains the file path and name of the source file.
constant __DATE__
This define contains the current date at the time of compilation, e.g. "Jul 28 2001".
constant __TIME__
This define contains the current time at the time of compilation, e.g. "12:20:51".
constant __PIKE__
This define is always true.
constant __AUTO_BIGNUM__
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.
constant __NT__
This define is defined when the Pike is running on a Microsoft Windows OS, not just Microsoft Windows NT, as the name implies.
constant __amigaos__
This define is defined when the Pike is running on Amiga OS.