Difference between revisions of "PreProcessor Commands"

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Reverted edits by Ilias48rus (talk) to last revision by killzone_kid)
m (Arguments: fixed typo)
 
(21 intermediate revisions by 8 users not shown)
Line 1: Line 1:
[[Category:Scripting Topics]]
+
{{SideTOC|0.9}}
The parser allows you to use macros in configs. Macros are a bit similar to functions in programming and allow you to use a single definition many times in the config, without having to duplicate the whole definition again and again. It also gives you a centralized place to correct errors in this definition. This page mainly refer to OFP, some example don't work on ARMA and ARMA 2.<br>
+
The parser allows you to use macros in configs. Macros are a bit similar to functions in programming and allow you to use a single definition many times in the config, without having to duplicate the whole definition again and again. It also gives you a centralized place to correct errors in this definition. This page mainly refers to '''{{ofp}}''', some examples won't work for {{arma}} and {{arma2}}.<br>
(In ArmA 3) preprocessor commands are <b>case-sensitive!</b>
+
If you really want to dig into the depths of the preprocessor you'll need to confront it with a bunch of edge cases and see how it behaves. If you are interested in this kind of thing, you might want to have a look at the collection of test-cases linked at the end of this page.<br>
 +
{{Feature arma3 | In {{arma3}}, preprocessor commands are <b>case-sensitive!</b>}}
 +
 
  
 
== Parsing ==
 
== Parsing ==
 +
 
* '''[[Config.cpp]]''' - parsed when PBO is binarized.
 
* '''[[Config.cpp]]''' - parsed when PBO is binarized.
 
** [[localize]] cannot be used in macros, as it would hardcode string of current language instead of creating reference.
 
** [[localize]] cannot be used in macros, as it would hardcode string of current language instead of creating reference.
Line 13: Line 16:
  
 
=== Comments ===
 
=== Comments ===
A comment is a line in your code that is not actually processed by the game engine. They are used to make your code more readable. The preprocessor removes all comments from the file, before it is processed. Therefore, any comments written in your code, will never actually be "seen" by the engine. They are for humans only.
 
  
There are two types of comments: single line comments and multi line comments.
+
A comment is a line within code that is not actually processed by the game engine. They are used to make code more readable or to add notes for future reference. The preprocessor removes all comments from the file before it is processed. Therefore, comments are never actually "seen" by the game engine.
 +
 
 +
Comments may span multiple lines, or only part of a line if needed.
  
  {{codecomment|//this is a single line comment}}
+
  {{cc|this is a single-line comment}}
  mycode = something; {{codecomment|//only this part of the line is commented out}}
+
   
  {{codecomment|/* this
+
  {{codecomment|/* this is a
  is a multi line
+
  multi-line
 
  comment */}}
 
  comment */}}
 +
 +
mycode = something; {{cc|only this part of the line is commented out}}
 +
 +
myArray = ["apple"{{codecomment|/*,"banana*/}},"pear"]; {{cc|// a portion in the middle of this line is commented out}}
 +
 +
=== #define ===
  
 +
Using the ''#define'' instruction, you can define a keyword and assign a definition to it. The keyword may contain any letter, digit or underscore in arbitrary order, as long as it doesn't start with a digit (RegEx: <tt>[a-zA-Z_][0-9a-zA-Z_]*</tt>). As an example:
 +
<syntaxhighlight lang="cpp">
 +
#define true 1
 +
</syntaxhighlight>
  
=== #define ===
+
The above means that whenever ''true'' is used in a config, the parser will replace this with the value ''1''.
Using the ''#define'' instruction you can define a keyword and assign a definition to it. An example:
+
 
 +
The define-statement does swallow all spaces in between the macro-keyword and any non-space-character in the body (Note that tabs aren't spaces! They don't get removed)
 +
<syntaxhighlight lang="cpp">
 +
#define MACRO                    test
 +
MACRO // preprocesses to test (without any spaces)
  
  #define true 1
+
#define MACRO test // There's a tab between MACRO and test
 +
MACRO // preprocesses to " test" (without quotes - they are only used to show that the tab character didn't get removed)
 +
</syntaxhighlight>
  
The above means that whenever you use ''true'' in your config, the parser will replace this with the value ''1''.
+
The space between the macro-keyword and the body is also fully optional (though very useful to tell the preprocessor where the macro name ends and where the body begins):
 +
<syntaxhighlight lang="cpp">
 +
#define MACRO#test
 +
MACRO // preprocesses to "test"
 +
</syntaxhighlight>
  
 
==== Arguments ====
 
==== Arguments ====
You can add arguments to your more complex macros, by including them between brackets after the keyword:
+
You can add arguments to more complex macros, by including them between brackets after the keyword. For the name of the arguments the same rule as for the macro-keyword (see above) apply.
 +
<syntaxhighlight lang="cpp">
 +
#define CAR(NAME) displayName = NAME;
 +
</syntaxhighlight>
  
  #define CAR(NAME) displayName = NAME;
+
If you now use ''CAR("Mini")'', this will be replaced with ''displayName = "Mini";''. Multiple arguments can also be used:
 +
<syntaxhighlight lang="cpp">
 +
#define BLASTOFF(UNIT,RATE) UNIT setVelocity [0,0,RATE];
 +
</syntaxhighlight>
  
If you now use ''CAR("Mini")'', this will be replaced with ''displayName = "Mini";''. Multiple arguments can also be used:
+
Macro arguments may be composed of any characters, as long as they do not contain a comma (because commas are used as argument-delimiters). If quotes are being used, they have to be balanced. The same applies to single-quotes This is because String detection is working in macro arguments - Therefore you can even pass in commas as macro argument as long as they are part of a String (This only works with Strings wrapped in double-quotes though). Note however that although the macro gets resolved properly, the comma gets removed from the String (probably a bug).
 +
<syntaxhighlight lang="cpp">
 +
#define MACRO(arg) arg
 +
MACRO("Some, content") // preprocesses to "Some content" (note the missing comma)
 +
</syntaxhighlight>
  
  #define BLASTOFF(UNIT,RATE) UNIT setVelocity [0,0,RATE];
+
Quote escaping is also not supported in this context (neither with double- nor with single-quotes)
 +
<syntaxhighlight lang="cpp">
 +
#define MACRO(arg) arg
 +
MACRO("Some ""content""") // preprocesses to "Some ""content"""
 +
</syntaxhighlight>
  
 
Passing arrays with more than one element <tt>[el1,el2,...]</tt> as arguments into macros as well as any argument containing comas <tt>"some, sentence"</tt>, will need a small workaround:
 
Passing arrays with more than one element <tt>[el1,el2,...]</tt> as arguments into macros as well as any argument containing comas <tt>"some, sentence"</tt>, will need a small workaround:
 
+
<syntaxhighlight lang="cpp">
  #define HINTARG(ARG) hint ("Passed argument: " + str ARG)
+
#define HINTARG(ARG) hint ("Passed argument: " + str ARG)
 +
</syntaxhighlight>
  
 
Incorrect usage:
 
Incorrect usage:
 
+
<syntaxhighlight lang="cpp">
  HINTARG([1,2,3,4,5,6,7,8,9,0]); //ERROR, wouldn't even compile
+
HINTARG([1,2,3,4,5,6,7,8,9,0]); // ERROR, won't even compile
 +
</syntaxhighlight>
  
 
Correct usage:
 
Correct usage:
 +
<syntaxhighlight lang="cpp">
 +
#define array1 [1,2,3,4,5,6,7,8,9,0]
 +
HINTARG(array1); // SUCCESS
 +
</syntaxhighlight>
  
  #define array1 [1,2,3,4,5,6,7,8,9,0]
+
The argument replacement is performed before expansion of the macro body. That means one doesn't have to worry about name-conflicts between argument-names of the current macro and already defined macros:
  HINTARG(array1); //SUCCESS
+
<syntaxhighlight lang="cpp">
 +
#define ONE foo
 +
#define TWO(ONE) ONE
 +
TWO(bar) // will preprocess to bar
 +
</syntaxhighlight>
  
 
==== Replacing parts of words ====
 
==== Replacing parts of words ====
 
By default you can only replace whole words by arguments. If you need to replace only part of a word, you can use the ''##'' instruction. This is necessary when either the start or the end of the argument connects to another character that is not a ''';''' (semi-colon) or &nbsp; (space).
 
By default you can only replace whole words by arguments. If you need to replace only part of a word, you can use the ''##'' instruction. This is necessary when either the start or the end of the argument connects to another character that is not a ''';''' (semi-colon) or &nbsp; (space).
 
+
<syntaxhighlight lang="cpp">
  class NAME##_Button_Slider: RscText \
+
class NAME##_Button_Slider: RscText \
  { \
+
{ \
      model = \OFP2\Structures\Various\##FOLDER##\##FOLDER; \
+
model = \OFP2\Structures\Various\##FOLDER##\##FOLDER; \
 +
</syntaxhighlight>
  
 
You can also use the single ''#'' to convert an argument to a string.
 
You can also use the single ''#'' to convert an argument to a string.
 
+
<syntaxhighlight lang="cpp">
  statement = (this animate [#SEL, 0]); \
+
statement = (this animate [#SEL, 0]); \
 +
</syntaxhighlight>
  
 
==== Multi-line ====
 
==== Multi-line ====
For longer definitions, you can stretch the macro across multiple lines. Each line, save the last one, ends with a ''\'' character:
+
For longer definitions, you can stretch the macro across multiple lines. To create a multi-line definition, each line except the last one should end with a ''\'' character:
 +
<syntaxhighlight lang="cpp">
 +
#define DRAWBUTTON(NAME)\
 +
__EXEC(idcNav = idcNav + 4) \
 +
...
 +
</syntaxhighlight>
  
  #define DRAWBUTTON(NAME)\
+
{{Informative | The backslash must be the last character in a line when defining a multi-line macro. Any character (including spaces) after the backslash will cause issues.}}
      __EXEC(idcNav = idcNav + 4) \
 
  ...
 
  
'''NOTE''': The backslash is the last character in the line, there cannot be a space after it, for example.
+
=== #undef ===
  
=== #undef ===
 
 
Undefine (delete) a macro previously set by the use of #define.
 
Undefine (delete) a macro previously set by the use of #define.
#undef NAME
+
<syntaxhighlight lang="cpp">
 +
#undef NAME
 +
</syntaxhighlight>
  
 +
=== #ifdef ===
  
=== #ifdef ===
+
You can use a simple if-then construction to check whether a certain set of definitions has already been made:
You can use a simple if-then construction to for example check whether a certain set of definitions has already been made:
+
<syntaxhighlight lang="cpp">
#ifdef NAME
+
#ifdef NAME
  ...text that will be used if NAME is defined...
+
...text that will be used if NAME is defined...
#endif
+
#endif
IFDEFs ''cannot'' be nested, as the preprocessor will generate an error if the outer definition doesn't exist.
+
</syntaxhighlight>
  
 +
IFDEFs ''cannot'' be nested. The preprocessor will generate errors for all inner definitions if the outer definition doesn't exist.
  
 
=== #ifndef ===
 
=== #ifndef ===
Same as #ifdef, but checks for absence of definiton instead.
 
#ifndef NAME
 
  ...text that will be used if NAME ''isn't'' defined...
 
#endif
 
  
 +
Same as #ifdef, but checks for absence of definition instead.
 +
<syntaxhighlight lang="cpp">
 +
#ifndef NAME
 +
...text that will be used if NAME ''isn't'' defined...
 +
#endif
 +
</syntaxhighlight>
  
 
=== #else ===
 
=== #else ===
#ifndef NAME
+
<syntaxhighlight lang="cpp">
  ...text that will be used if NAME ''isn't'' defined...
+
#ifndef NAME
#else
+
...text that will be used if NAME is -not- defined...
  ...text that will be used if NAME ''is'' defined...
+
#else
#endif
+
...text that will be used if NAME -is- defined...
 +
#endif
 +
</syntaxhighlight>
  
 
=== #endif ===
 
=== #endif ===
 +
 
This ends a conditional block as shown in the descriptions of #ifdef and #ifndef above.
 
This ends a conditional block as shown in the descriptions of #ifdef and #ifndef above.
  
 +
=== #include ===
  
=== #include ===
 
 
Copies the code from a target file and pastes it where #include directive is.
 
Copies the code from a target file and pastes it where #include directive is.
#include "codestrip.hpp"
+
<syntaxhighlight lang="cpp">
#include <codestrip.txt>
+
#include "file.hpp"
 +
#include <file.txt> // Brackets are equivalent to quotation marks and may be used in their place.
 +
</syntaxhighlight>
  
Brackets are equal to quotation marks. 
+
Source directory is:
 +
* For any file without starting the include path with \ - the file's current directory
 +
* When starting with \ - the internal filesystem root (see [[CMA:DevelopmentSetup#Addon_development|Addon_development]]) or the Game's working directory (only with [[Arma_3_Startup_Parameters#Developer_Options -filePatching]] enabled)
  
Source directory is:
 
* for description.ext, addon configs – game root folder (where exe file is)
 
* for global config and resource – their source folder
 
  
Alternatively you may write a path starting from drive:
+
You can define a path beginning with:
#include "d:\temp\codestrip.txt"
+
* drive (only with [[Arma_3_Startup_Parameters#Developer_Options -filePatching]] enabled):<!--
 +
--><syntaxhighlight lang="cpp">#include "D:\file.txt"</syntaxhighlight><!--
 +
-->
 +
* PBO with [[PBOPREFIX]]:<!--
 +
--><syntaxhighlight lang="cpp"> #include "\myMod\myAddon\file.txt"</syntaxhighlight>
 +
* PBO (keep in mind that in this case, if the PBO's file name will be changed, all '#include' referencing it will need to be updated):<!--
 +
--><syntaxhighlight lang="cpp">#include"\myMod\myAddon\file.txt" // Arma 3\@myMod\addons\myAddon.pbo\file.txt;</syntaxhighlight>
 +
 
  
 
To move to parent directory use '..' (two dots) (Supported in Arma 3 since v1.49.131707):
 
To move to parent directory use '..' (two dots) (Supported in Arma 3 since v1.49.131707):
#include "..\codestrip.txt"
+
<syntaxhighlight lang="cpp">
 +
#include "..\file.sqf"
 +
</syntaxhighlight>
  
You can also include files from the installation dir:
+
Preprocessor does not support the use of macros for pre-defined file names.
#include "\myDirectory\codestrip.txt" // ArmA 2\myDirectory\codestrip.txt
+
<syntaxhighlight lang="cpp">
 +
#define path "codestrip.txt"
 +
#include path // this will cause an error
 +
</syntaxhighlight>
  
Addon locations are saved to memory. To include a file from one of them write:
+
=== # ===
#include "<addon folder name>\<file>"
 
  
Preprocessor does not support computed includes (macro for file name).
+
'#' (single hash) operator wraps the text with quotation marks.
#define path "codestrip.txt"
+
<syntaxhighlight lang="cpp">
#include path
+
#define STRINGIFY(s) #s;
This code will cause an error. Macros will be explained later.
+
#define FOO 123
 +
test1 = STRINGIFY(123); //test1 = "123";
 +
test2 = STRINGIFY(FOO); //test2 = "123";
 +
</syntaxhighlight>
  
=== # ===
+
This operator does only work on keywords following the rules for macro-names (see <tt>#define</tt>-section). If one wants to stringify anything else (like e.g. a number), one has to use a stringify-macro that takes an argment and stringifies that (as in the example above).
'#' (single hash) operator wraps the text with quotation marks.
+
<syntaxhighlight lang="cpp">
#define STRINGIFY(s) #s;
+
#define MACRO Test #123
#define FOO 123
+
MACRO // preprocesses to Test 123 - note that there aren't any quotes inserted
test1 = STRINGIFY(123); //test1 = "123";
+
</syntaxhighlight>
test2 = STRINGIFY(FOO); //test2 = "123";
 
  
 
=== ## ===
 
=== ## ===
 +
 
'##' (double hash) operator concatenates what's before the ## with what's after it.
 
'##' (double hash) operator concatenates what's before the ## with what's after it.
#define GLUE(g1,g2) g1##g2
+
<syntaxhighlight lang="cpp">
#define FOO 123
+
#define GLUE(g1,g2) g1##g2
#define BAR 456
+
#define FOO 123
test1 = GLUE(123,456); //test1 = 123456;
+
#define BAR 456
test2 = GLUE(FOO,BAR); //test2 = 123456;
+
test1 = GLUE(123,456); //test1 = 123456;
 +
test2 = GLUE(FOO,BAR); //test2 = 123456;
 +
</syntaxhighlight>
  
 
=== __EXEC ===
 
=== __EXEC ===
This '''config parser''' macro allows you to assign values to internal variables. These variables can be used to create complex macros with counters for example.
 
  
  __EXEC(cat = 5 + 1; lev = 0)
+
This '''config parser''' macro allows you to assign values to internal variables or just execute arbitrary code. The code inside <tt>__EXEC</tt> macros runs in [[parsingNamespace]] and variables defined in it will also be created in [[parsingNamespace]]. The variables can then be used to create more complex macros:
  
This macro terminates at the first '')'' it encounters, so the following will not be possible:
+
__EXEC(cat = 5 + 1;)
 +
__EXEC(lev = cat - 2;)
 +
_cat = [[parsingNamespace]] [[getVariable]] "cat"; {{cc|6}}
 +
_lev = [[parsingNamespace]] [[getVariable]] "lev"; {{cc|4}}
  
  __EXEC(string1 = "if ((_this select 0) == 22) then {true}")
+
{{Important | <tt>__EXEC</tt> macros are not suitable for <tt>SQF/SQS</tt> scripts but can be used in configs, including [[description.ext]]}}
 +
{{Warning | <tt>__EXEC</tt> doesn't like round brackets <tt>()</tt> inside expressions. If you need to have grouping, perhaps you could calculate values inside the brackets separately and assign to local variables:
 +
<code>__EXEC(a {{=}} (1+2);) {{cc|ERROR}}</code>
 +
<div><code>__EXEC(_expr {{=}} 1+2;)
 +
__EXEC(a {{=}} _expr;) {{cc|OK}}</code></div>
 +
}}
  
When you evaluate ''string1'' it returns ''"if ((_this select 0"'' and can cause unexpected results. The variables that receive expression result inside __EXEC are available in [[parsingNamespace]]:
+
=== __EVAL ===
  
_cat = [[parsingNamespace]] [[getVariable]] "cat"; //6
+
With this '''config parser''' macro you can evaluate expressions, including previously assigned internal variables. Unlike with <tt>__EXEC</tt>, <tt>__EVAL</tt> supports multiple parentheses
_lev = [[parsingNamespace]] [[getVariable]] "lev"; //0
 
  
'''NOTE:''' Config parser macros are not suitable for sqf/sqs scripts but can be used in configs, including [[description.ext]].
+
w = __EVAL([[safeZoneW]] - (5 * ((1 / ([[getResolution]] [[select]] 2)) * 1.25 * 4)));
  
=== __EVAL ===
+
<tt>__EVAL</tt> macros MUST be assigned to a config property and the expression MUST be terminated with <tt>;</tt>. <tt>__EVAL</tt> can return only 2 types of data: [[Number]] and [[String]]. Any other type is represented as [[String]], even [[Boolean]] type, which will result in either <tt>"true"</tt> or <tt>"false"</tt>.
With this '''config parser''' macro you can evaluate expressions, including previously assigned internal variables. Unlike with __EXEC, __EVAL supports multiple parentheses
 
  
  w = __EVAL(safezoneW - (5 * ((1 / (getResolution select 2)) * 1.25 * 4)));
+
{{Important | <tt>__EVAL</tt> macros are not suitable for <tt>SQF/SQS</tt> scripts but can be used in configs, including [[description.ext]]. Both global and local variables set in <tt>__EXEC</tt> are available in <tt>__EVAL</tt>}}
 +
{{Warning | <tt>__EVAL</tt> doesn't like curly brackets <tt>{}</tt>, if you need to have code in your expression use [[compile]] [[String]] instead:
 +
<code>result <nowiki>=</nowiki> __EVAL([[call]] {123}); {{cc|ERROR}}</code>
 +
<code>result <nowiki>=</nowiki> __EVAL([[call]] [[compile]] "123"); {{cc|OK}}</code>}}
  
'''NOTE:''' Config parser macros are not suitable for sqf/sqs scripts but can be used in configs, including [[description.ext]]. Both global and local variables set in __EXEC are available in __EVAL.
 
  
 
=== __LINE__ ===
 
=== __LINE__ ===
 +
 
This keyword gets replaced with the line number in the file where it is found. For example, if __LINE__ is found on the 10th line of a file, the word __LINE__ will be replaced with the number 10.
 
This keyword gets replaced with the line number in the file where it is found. For example, if __LINE__ is found on the 10th line of a file, the word __LINE__ will be replaced with the number 10.
  
 
=== __FILE__ ===
 
=== __FILE__ ===
 +
 
This keyword gets replaced with the CURRENT file being processed.
 
This keyword gets replaced with the CURRENT file being processed.
 +
 +
 +
== Errors ==
 +
 +
=== Error 2 ===
 +
 +
;Problem: Preprocessor failed error 2.
 +
 +
;How to fix: Add quotation marks in the title, or the file path. (''e.g.'' <tt>#include "soGood.sqf"</tt>).
 +
 +
=== Error 6 ===
 +
 +
;Problem: Preprocessor failed on file X - error 6.
 +
 +
;Known reasons:
 +
* "The problem is using <tt>#ifdef #ifdef #endif #endif</tt>, a.k.a nested <tt>#ifdef</tt>. This doesn't work in Arma. It's only possible to use <tt>#ifdef</tt> and <tt>#endif</tt> once and not nested."
 +
* <tt>#endif</tt> without preceding <tt>#ifdef</tt> or <tt>#ifndef</tt>
 +
 +
=== Error 7 ===
 +
 +
;Problem: Preprocessor failed on file X - error 7.
 +
 +
;Known reasons: The preprocessor encountered an unknown directive. Read, you have probably a typo in the file (something like <tt>#inlcude</tt> or <tt>#defien</tt>). Double check all preprocessor directives in that file.
  
  
 
== External links ==
 
== External links ==
* http://ofp-faguss.com/files/ofp_preprocessor_explained.pdf
+
 
 +
* http://ofp-faguss.com/files/ofp_preprocessor_explained.pdf ([https://web.archive.org/web/20170319190732/http://ofp-faguss.com/files/ofp_preprocessor_explained.pdf Wayback Machine])
 +
* [https://github.com/Krzmbrzl/ArmaPreprocessorTestCases Collection of preprocessor test-cases]
 +
 
 +
 
 +
[[Category:Scripting_Topics]]

Latest revision as of 13:22, 21 March 2020

The parser allows you to use macros in configs. Macros are a bit similar to functions in programming and allow you to use a single definition many times in the config, without having to duplicate the whole definition again and again. It also gives you a centralized place to correct errors in this definition. This page mainly refers to Operation Flashpoint, some examples won't work for Armed Assault and Arma 2.
If you really want to dig into the depths of the preprocessor you'll need to confront it with a bunch of edge cases and see how it behaves. If you are interested in this kind of thing, you might want to have a look at the collection of test-cases linked at the end of this page.

Arma 3 logo black.png
In Arma 3, preprocessor commands are case-sensitive!


Parsing


Macros

Comments

A comment is a line within code that is not actually processed by the game engine. They are used to make code more readable or to add notes for future reference. The preprocessor removes all comments from the file before it is processed. Therefore, comments are never actually "seen" by the game engine.

Comments may span multiple lines, or only part of a line if needed.

// this is a single-line comment

/* this is a
multi-line
comment */

mycode = something; // only this part of the line is commented out

myArray = ["apple"/*,"banana*/,"pear"]; // // a portion in the middle of this line is commented out

#define

Using the #define instruction, you can define a keyword and assign a definition to it. The keyword may contain any letter, digit or underscore in arbitrary order, as long as it doesn't start with a digit (RegEx: [a-zA-Z_][0-9a-zA-Z_]*). As an example:

#define true 1

The above means that whenever true is used in a config, the parser will replace this with the value 1.

The define-statement does swallow all spaces in between the macro-keyword and any non-space-character in the body (Note that tabs aren't spaces! They don't get removed)

#define MACRO                     test
MACRO // preprocesses to test (without any spaces)

#define MACRO	test // There's a tab between MACRO and test
MACRO // preprocesses to "	test" (without quotes - they are only used to show that the tab character didn't get removed)

The space between the macro-keyword and the body is also fully optional (though very useful to tell the preprocessor where the macro name ends and where the body begins):

#define MACRO#test
MACRO // preprocesses to "test"

Arguments

You can add arguments to more complex macros, by including them between brackets after the keyword. For the name of the arguments the same rule as for the macro-keyword (see above) apply.

#define CAR(NAME) displayName = NAME;

If you now use CAR("Mini"), this will be replaced with displayName = "Mini";. Multiple arguments can also be used:

#define BLASTOFF(UNIT,RATE) UNIT setVelocity [0,0,RATE];

Macro arguments may be composed of any characters, as long as they do not contain a comma (because commas are used as argument-delimiters). If quotes are being used, they have to be balanced. The same applies to single-quotes This is because String detection is working in macro arguments - Therefore you can even pass in commas as macro argument as long as they are part of a String (This only works with Strings wrapped in double-quotes though). Note however that although the macro gets resolved properly, the comma gets removed from the String (probably a bug).

#define MACRO(arg) arg
MACRO("Some, content") // preprocesses to "Some content" (note the missing comma)

Quote escaping is also not supported in this context (neither with double- nor with single-quotes)

#define MACRO(arg) arg
MACRO("Some ""content""") // preprocesses to "Some ""content"""

Passing arrays with more than one element [el1,el2,...] as arguments into macros as well as any argument containing comas "some, sentence", will need a small workaround:

#define HINTARG(ARG) hint ("Passed argument: " + str ARG)

Incorrect usage:

HINTARG([1,2,3,4,5,6,7,8,9,0]); // ERROR, won't even compile

Correct usage:

#define array1 [1,2,3,4,5,6,7,8,9,0] 
HINTARG(array1); // SUCCESS

The argument replacement is performed before expansion of the macro body. That means one doesn't have to worry about name-conflicts between argument-names of the current macro and already defined macros:

#define ONE foo
#define TWO(ONE) ONE
TWO(bar) // will preprocess to bar

Replacing parts of words

By default you can only replace whole words by arguments. If you need to replace only part of a word, you can use the ## instruction. This is necessary when either the start or the end of the argument connects to another character that is not a ; (semi-colon) or   (space).

class NAME##_Button_Slider: RscText \
{ \
	model = \OFP2\Structures\Various\##FOLDER##\##FOLDER; \

You can also use the single # to convert an argument to a string.

statement = (this animate [#SEL, 0]); \

Multi-line

For longer definitions, you can stretch the macro across multiple lines. To create a multi-line definition, each line except the last one should end with a \ character:

#define DRAWBUTTON(NAME)\
	__EXEC(idcNav = idcNav + 4) \
	...
The backslash must be the last character in a line when defining a multi-line macro. Any character (including spaces) after the backslash will cause issues.

#undef

Undefine (delete) a macro previously set by the use of #define.

#undef NAME

#ifdef

You can use a simple if-then construction to check whether a certain set of definitions has already been made:

#ifdef NAME
	...text that will be used if NAME is defined...
#endif

IFDEFs cannot be nested. The preprocessor will generate errors for all inner definitions if the outer definition doesn't exist.

#ifndef

Same as #ifdef, but checks for absence of definition instead.

#ifndef NAME
	...text that will be used if NAME ''isn't'' defined...
#endif

#else

#ifndef NAME
	...text that will be used if NAME is -not- defined...
#else
	...text that will be used if NAME -is- defined...
#endif

#endif

This ends a conditional block as shown in the descriptions of #ifdef and #ifndef above.

#include

Copies the code from a target file and pastes it where #include directive is.

#include "file.hpp"
#include <file.txt> // Brackets are equivalent to quotation marks and may be used in their place.

Source directory is:


You can define a path beginning with:

  • drive (only with Arma_3_Startup_Parameters#Developer_Options -filePatching enabled):
    #include "D:\file.txt"
    
  • PBO with PBOPREFIX:
     #include "\myMod\myAddon\file.txt"
    
  • PBO (keep in mind that in this case, if the PBO's file name will be changed, all '#include' referencing it will need to be updated):
    #include"\myMod\myAddon\file.txt" // Arma 3\@myMod\addons\myAddon.pbo\file.txt;
    


To move to parent directory use '..' (two dots) (Supported in Arma 3 since v1.49.131707):

#include "..\file.sqf"

Preprocessor does not support the use of macros for pre-defined file names.

#define path "codestrip.txt"
#include path // this will cause an error

#

'#' (single hash) operator wraps the text with quotation marks.

#define STRINGIFY(s) #s;
#define FOO 123
test1 = STRINGIFY(123); //test1 = "123";
test2 = STRINGIFY(FOO); //test2 = "123";

This operator does only work on keywords following the rules for macro-names (see #define-section). If one wants to stringify anything else (like e.g. a number), one has to use a stringify-macro that takes an argment and stringifies that (as in the example above).

#define MACRO Test #123
MACRO // preprocesses to Test 123 - note that there aren't any quotes inserted

##

'##' (double hash) operator concatenates what's before the ## with what's after it.

#define GLUE(g1,g2) g1##g2
#define FOO 123
#define BAR 456
test1 = GLUE(123,456); //test1 = 123456;
test2 = GLUE(FOO,BAR); //test2 = 123456;

__EXEC

This config parser macro allows you to assign values to internal variables or just execute arbitrary code. The code inside __EXEC macros runs in parsingNamespace and variables defined in it will also be created in parsingNamespace. The variables can then be used to create more complex macros:

__EXEC(cat = 5 + 1;)
__EXEC(lev = cat - 2;)
_cat = parsingNamespace getVariable "cat"; // 6
_lev = parsingNamespace getVariable "lev"; // 4
__EXEC macros are not suitable for SQF/SQS scripts but can be used in configs, including description.ext
__EXEC doesn't like round brackets () inside expressions. If you need to have grouping, perhaps you could calculate values inside the brackets separately and assign to local variables:

__EXEC(a = (1+2);) // ERROR

__EXEC(_expr = 1+2;) __EXEC(a = _expr;) // OK

__EVAL

With this config parser macro you can evaluate expressions, including previously assigned internal variables. Unlike with __EXEC, __EVAL supports multiple parentheses

w = __EVAL(safeZoneW - (5 * ((1 / (getResolution select 2)) * 1.25 * 4)));

__EVAL macros MUST be assigned to a config property and the expression MUST be terminated with ;. __EVAL can return only 2 types of data: Number and String. Any other type is represented as String, even Boolean type, which will result in either "true" or "false".

__EVAL macros are not suitable for SQF/SQS scripts but can be used in configs, including description.ext. Both global and local variables set in __EXEC are available in __EVAL
__EVAL doesn't like curly brackets {}, if you need to have code in your expression use compile String instead:

result = __EVAL(call {123}); // ERROR

result = __EVAL(call compile "123"); // OK


__LINE__

This keyword gets replaced with the line number in the file where it is found. For example, if __LINE__ is found on the 10th line of a file, the word __LINE__ will be replaced with the number 10.

__FILE__

This keyword gets replaced with the CURRENT file being processed.


Errors

Error 2

Problem
Preprocessor failed error 2.
How to fix
Add quotation marks in the title, or the file path. (e.g. #include "soGood.sqf").

Error 6

Problem
Preprocessor failed on file X - error 6.
Known reasons
  • "The problem is using #ifdef #ifdef #endif #endif, a.k.a nested #ifdef. This doesn't work in Arma. It's only possible to use #ifdef and #endif once and not nested."
  • #endif without preceding #ifdef or #ifndef

Error 7

Problem
Preprocessor failed on file X - error 7.
Known reasons
The preprocessor encountered an unknown directive. Read, you have probably a typo in the file (something like #inlcude or #defien). Double check all preprocessor directives in that file.


External links