PreProcessor Commands: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (minor spelling typo in example)
m (removed previous incorrect note about brackets. conclusion was based on __EVAL being incapable of doing format[] for some reason.)
 
(143 intermediate revisions by 25 users not shown)
Line 1: Line 1:
=Introduction =
{{TOC|side|0.9}}
The PreProcessor and the Config Parser allow to use macros in configs. The purpose of macros is to re-use the same definition in scripts and configs multiple times.
It also gives a centralized place to correct errors in this definition.
Know that edge cases may arise - see the collection of test-cases linked at the end of this page.
{{Feature|arma3|In {{arma3}}, preprocessor commands are '''case-sensitive!'''}}


Preprocessor commands refer to the C(++) syntax used by the engine to 'pre process' the text inside a config.cpp, mission.sqm, or description.ext file. In fact, preprocessor commands apply to '''any''' BI game text file containing class statements, since these statements are 'scrunched' by the engine's internal C processor. The majority use however is in addons, and specifically, the config.cpp of the addon.


Preprocessor commands can also be used in script files, as long as the script is loaded using the preprocessfile command, or run via the execVM command.
== Parsing ==


There are a number of preprocessor commands recognized by the OFP and ArmA engine:
See {{Link|#Config Parser}} below:
* '''[[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.
* '''[[Description.ext]]''' - parsed when mission is loaded or previewed in missions list.
* '''[[SQF Syntax|SQF]] script''' - parsed when [[preprocessFile]], [[preprocessFileLineNumbers]], [[compileScript]] or [[execVM]] is used.


Comments


#include
== Macros ==
#define
#undef
#ifdef
#ifndef
#else
#endif


__LINE__
=== Comments ===
__FILE__


(The macros __EXEC & __EVAL are discussed in the [[Config_Parser|Config Parser article]].)
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.
{{Feature|warning|Sometimes a problematic string can fail to purge these comment outs during preprocessing!
<sqf>private _a = '"';
// this is just a comment, but failed to remove upon the preprocess so will return an error. Caused by that string</sqf>}}
<syntaxhighlight lang="cpp">
// this is a single-line comment
/*
this is a
multi-line
comment
*/
myValue = something; // only this part of the line is commented out


==Note for experienced users==
myArray = { "apple"/*, "banana"*/, "pear" }; // a portion in the middle of this line is commented out
</syntaxhighlight>


The preprocessor mimics a subset of [http://en.wikipedia.org/wiki/C_preprocessor C preprocessor]. While basic functionality is similar, the preprocessor is not fully C-conformant, as order of substitution of arguments in macro invocation is different than in C, which means some intricate nested macro constructs, especially when using token concatenation operator, may produce different results than in C.
=== #define ===


= Preprocessor commands =
Using the {{hl|#define}} instruction, it is possible to 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 does not start with a digit (RegEx: {{hl|[a-zA-Z_][0-9a-zA-Z_]*}}).
As an example:
<syntaxhighlight lang="cpp">
#define true 1
</syntaxhighlight>


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


Though not technically a command, comments are handled by the preprocessor.
The define-statement does swallow all spaces in between the macro-keyword and any non-space-character in the body (Note that tabs are not spaces! They don't get removed)
<syntaxhighlight lang="cpp">
#define MACRO                    test
MACRO // preprocesses to test (without any spaces)


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.
#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>


There are two types of comments: single line comments and multi line comments.
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>


//this is a single line comment
==== Arguments ====
mycode = something; //only this part of the line is commented out
Arguments can be added 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.
/* this
<syntaxhighlight lang="cpp">
is a multi line
#define CAR(NAME) displayName = NAME;
comment */
</syntaxhighlight>


A single line comment begins after two forward slashes //, and ends at the next line break.
If ''CAR("Mini")'' is used, it 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>


A multi line comment spans across line breaks. It starts with the characters /* and ends with the characters */
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 commas can even get passed in as a 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>


Both comment types can start anywhere in a line (they don't have to be at the beginning of a line).
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>


==#include==
Passing arrays with more than one element {{hl|[el1,el2,...]}} as arguments into macros as well as any argument containing comas {{hl|"some, sentence"}}, will need a small workaround:
<syntaxhighlight lang="cpp">
#define HINTARG(ARG) hint ("Passed argument: " + str ARG)
</syntaxhighlight>


'''Syntax:'''
Incorrect usage:
#include <PathAndFileName>
<syntaxhighlight lang="cpp">
#include "PathAndFileName"
HINTARG([1,2,3,4,5,6,7,8,9,0]); // ERROR, won't even compile
</syntaxhighlight>


The purpose of an include statement is to share common definitions among several files (e.g. constants or functions).
Correct usage:
<syntaxhighlight lang="cpp">
#define array1 [1,2,3,4,5,6,7,8,9,0]
HINTARG(array1); // SUCCESS
</syntaxhighlight>


The number of 'chunks' (ie, the number of included files) is solely at the author's discretion. In general, they will put similar elements together. For example, all icons will be in one file, all buildings in another, all cars in another, and so on. It is particularly common to put base characteristics of similar 'models' into a single 'base' file, and then include this file into multiple variations of that base model. For example, a base file may define a soldier with khaki trousers. A second soldier class could include this standard base, and then define specific variations (which may change the trousers to pink, and so on). The base characteristics of the model do not need to be repeated in the main body of the text for the second soldier, as it's duplicating work and contains no new information.
The argument replacement is performed before the 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:
<syntaxhighlight lang="cpp">
#define ONE foo
#define TWO(ONE) ONE
TWO(bar) // will preprocess to bar
</syntaxhighlight>


From the perspective of the game engine, the use of #include files is of <u>no consequence</u>, since the engine effectively processes all files as one file. All of the 'chunks' (the #included files) are merged into a single file for the purpose of compiling. Irrespective of how many #included files are used, the result is a single config.bin (config.bin is the resultant output of all this processing).
==== Replacing parts of words ====
By default, only whole words can be replaced by arguments. If only a part of the word should be replaced, use the {{hl|##}} instruction.
This is necessary when either the start or the end of the argument connects to another character that is not a {{hl|;}} (semi-colon) or {{hl|&nbsp;}} (space).
<syntaxhighlight lang="cpp">
class NAME##_Button_Slider: RscText \
{ \
model = \OFP2\Structures\Various\##FOLDER##\##FOLDER; \
</syntaxhighlight>


Processing continues at the beginning of the included file until it's end, at which point, processing continues at the statement after the initial #include. Thus, anything required by that included file (if anything at all), must have 'appeared' before the #include statement. It is quite common for included files to have #include statement(s) of their own, under which circumstance, processing continues at the beginning of that included file, and so on.
It is also possible to use the single ''#'' to convert an argument to a string.
<syntaxhighlight lang="cpp">
statement = (this animate [#SEL, 0]); \
</syntaxhighlight>


Example:
==== Multi-line ====
#include "someAddon\somePathInTheAddon\someFile.someExtension"
For longer definitions, one 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>


Note that the #include syntax string does not use a preceding backslash, unlike other file references (such as icons or models, etc.) used in BI game files. Also note, that there is no default file extension, and no trailing semi-colon.
{{Feature|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.}}


Preprocessor commands do not have to be left-aligned, but can be indented, just like any other command.
=== #undef ===


:''NOTE'' - ArmA Tools Suite v1.14 Binarize.exe processing of #include is out of step with the capabilities of CfgConvert.exe.
Undefine (delete) a macro previously set by the use of #define.
:: If you desire single common include files in your addon config.cpp files in ArmA, CfgConvert.exe will support & process #includes that are
<syntaxhighlight lang="cpp">
#undef NAME
</syntaxhighlight>


::: 1. Relative both above & below the current folder of the config.cpp being processed.
=== #if  ===
:::    ie. ''#include "..\inc\common.hpp"''
:::        ''#include "inc\common.hpp"''


::: 2. Absolute paths.
'''Description:''' Checks condition and processes content if condition returns 1. Skips content if it returns 0
:::    ie. ''#include "P:\Synide\common.hpp"
<syntaxhighlight lang="cpp">
:::
#if __GAME_VER_MAJ__ != 2
// Do something...
#endif
</syntaxhighlight>


::: Basically, all the various ways you would want to use #include works perfectly with CfgConvert.exe. The same cannot be said of Binarize.exe however. If you wish to make use of the virtues of true relative #include statements in ArmA config's I suggest prior to running BinPBO the user manually converts the config to it's rapified/binarized format. There is one issue to this approach and that is you should not have the text version of the config named config.cpp as binarize.exe will attempt to process it and if it has #include statements like ''#include "..\common.hpp"'' will fail. So, call your text version (for example) config.cfg and make use of #include's full gambit of functionality and use CfgConvert.exe to pre-convert it to a config.bin which when BinPBO is run binarize.exe will quite happily make use of. All, this can be automated in a simple dos batch file.
==== Comparison Operators ====
The following operations are supported:
* <
* >
* <=
* >=
* ==
* !=
'''Example:'''
<syntaxhighlight lang="cpp">
#if __GAME_VER_MAJ__ != 2
// Do something...
#endif
</syntaxhighlight>


==#define==
=== #ifdef ===


'''Syntax:'''
A simple if-then construction to check whether a certain set of definitions has already been made:
#define NAME VALUE
<syntaxhighlight lang="cpp">
The referenced name is case sensitive when used. Within define arguments, the token 'concatenation operator' ##, and 'stringize operator' # may be used.
#ifdef NAME
// config that will be used if NAME is defined
#endif
</syntaxhighlight>


Define statements may be referred to by the term 'macro'. It is a macro in the same way macros are used in Microsoft Word - one macro can expand into a (very large) sequence of keystrokes. You can effectively understand #defines as
IFDEFs ''cannot'' be nested. The preprocessor will generate errors for all inner definitions if the outer definition doesn't exist.
defineName = defineValue;
For example:
#define true  1
#define false 0
Macros can be expanded to the following example:
#define ICONS(icn) icon=\SomeAddon\icons\##icn;  \
                    model=\SomeAddon\##icn.p3d;  \
                    picture=\SomeAddon\##icn.paa
Then, using: 
ICONS(Peter);
ICONS(Fred);
will be expanded during processing into:
icon=\SomeAddon\icons\Peter;
model=\SomeAddon\Peter.p3d;
picture=\SomeAddon\Peter.paa;
icon=\SomeAddon\icons\Fred;
model=\SomeAddon\Fred.p3d;
picture=\SomeAddon\Fred.paa;


The purpose of expanded macros as illustrated above is to allow simplified syntax, and to reduce typing load (and the likelihood of typos). In the case of the first example above, the #define macro creates more explicit, legible files, at the expense of increased typing.
=== #ifndef ===


Defines that span more than one line need the line-continuation symbol ("\") at the end of each line (see ICONS example above). '''Nothing''' is allowed to follow after this symbol - no comments, and not even spaces!
Same as #ifdef, but checks for absence of definition instead.
<syntaxhighlight lang="cpp">
#ifndef NAME
// config that will be used if NAME is -not- defined
#endif
</syntaxhighlight>


Nested defines:
=== #else ===


Defines can be nested in each other, and they are all expanded. You can't seem to put a multi-line define inside of a multi-line define, nor can you pass a multi-line define in as a parameter of a macro.
Provides alternative code to {{hl|#if}}, {{hl|#ifdef}}, {{hl|#ifndef}} checks.
<syntaxhighlight lang="cpp">
#ifndef NAME
// config that will be used if NAME is -not- defined
#else
// config that will be used if NAME -is- defined
#endif
</syntaxhighlight>


When including defines in defines, the # operator works after expanding all defines. For example:
=== #endif ===


  1. define fn_myfunc compile preprocessfile 'myfile.sqf'
This ends a conditional block as shown in the descriptions of #ifdef and #ifndef above.
  2. define addquotes(x) #x
 
=== #include ===
 
Copies the code from a target file and pastes it where #include directive is.
<syntaxhighlight lang="cpp">
#include "file.hpp"
#include <file.txt> // Brackets are equivalent to quotation marks and may be used in their place.
</syntaxhighlight>
 
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|-filePatching]] enabled)
 
A path beginning can be defined as follow:
* drive (only with [[Arma 3: Startup Parameters|-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 since {{GVI|arma3|1.50}}):
<syntaxhighlight lang="cpp">
#include "..\file.sqf"
</syntaxhighlight>
 
Preprocessor does not support the use of macros for pre-defined file names.
<syntaxhighlight lang="cpp">
#define path "codestrip.txt"
#include path // this will cause an error
</syntaxhighlight>
 
=== # ===
 
'#' (single hash) operator wraps the text with quotation marks.
<syntaxhighlight lang="cpp">
#define STRINGIFY(s) #s
#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 {{hl|#define}}-section).
If one wants to stringify anything else (like e.g. a number), one has to use a stringify-macro that takes an argument and stringifies that (as in the example above).
<syntaxhighlight lang="cpp">
#define MACRO Test #123
MACRO // preprocesses to Test 123 - note that there are not any quotes inserted
</syntaxhighlight>
 
=== ## ===
 
'##' (double hash) operator concatenates what's before the ## with what's after it.
<syntaxhighlight lang="cpp">
#define GLUE(g1,g2) g1##g2
#define FOO 123
#define BAR 456
test1 = GLUE(123,456); //test1 = 123456;
test2 = GLUE(FOO,BAR); //test2 = 123456;
</syntaxhighlight>
 
=== __LINE__ ===
 
This keyword gets replaced with the line number in the file where it is found. For example, if {{hl|__LINE__}} is found on the 10th line of a file, the word {{hl|__LINE__}} will be replaced with the number 10.
 
=== __FILE__ ===
 
This keyword gets replaced with the CURRENT file being processed.
e.g
"userconfig\file1.sqf"
 
{{ArgTitle|3|__FILE_NAME__|{{GVI|arma3|2.18}}}}
 
This keyword gets replaced with the '''name''' of the current file being processed.
e.g
"file1.sqf"
 
{{ArgTitle|3|__FILE_SHORT__|{{GVI|arma3|2.18}}}}
 
This keyword gets replaced with the '''name''' of the current file being processed, without extension.
e.g
"file1"
 
{{ArgTitle|3|__has_include|{{GVI|arma3|2.02}}}}
 
'''Description:''' Checks if given file exists. Returns 1 if it does, 0 if it does not exist.
{{Feature|important|
* The file path must start with the backslash {{hl|\}} otherwise it would fail silently (returns {{hl|0}} so does nothing unless you put something in {{hl|#else}})!
* If you wanted to make an addon that can change its config dynamically depending on mods that loaded along, '''do not''' binarize the ''config.cpp''!
}}
{{Feature|informative|
To validate that the file exists in your game, you can use [[fileExists]] command to check.
<sqf>
fileExists "\a3\data_f\config.bin"; // returns true
fileExists "\z\ace\addons\main\script_component.hpp"; // returns true if ACE is loaded, false otherwise
</sqf>
}}
<syntaxhighlight lang="cpp">
#if __has_include("\z\ace\addons\main\script_component.hpp")
// file exists! Do something with it
#else
// file does not exist
#endif
</syntaxhighlight>
 
{{ArgTitle|3|__DATE_ARR__|{{GVI|arma3|2.02}}}}
 
'''Description:''' Is replaced for current date in format [[Array|array]].
<syntaxhighlight lang="cpp">
__DATE_ARR__ // 2020,10,28,15,17,42
</syntaxhighlight>
 
{{ArgTitle|3|__DATE_STR__|{{GVI|arma3|2.02}}}}
 
'''Description:''' Is replaced for current date in format [[String|string]].
<syntaxhighlight lang="cpp">
__DATE_STR__  // "2020/10/28, 15:17:42"
</syntaxhighlight>
 
{{ArgTitle|3|__DATE_STR_ISO8601__|{{GVI|arma3|2.02}}}}
 
'''Description:''' Is replaced for current date in format [[String|string]]. The date is presented in ISO8601 standard.
<syntaxhighlight lang="cpp">
__DATE_STR_ISO8601__ // "2020-10-28T14:17:42Z"
</syntaxhighlight>
 
{{ArgTitle|3|__TIME__|{{GVI|arma3|2.02}}}}
 
'''Description:''' Is replaced for current time.
<syntaxhighlight lang="cpp">
__TIME__ // 15:17:42
</syntaxhighlight>
 
{{ArgTitle|3|__TIME_UTC__|{{GVI|arma3|2.02}}}}
 
'''Description:''' Is replaced for UTC time.
<syntaxhighlight lang="cpp">
__TIME_UTC__ // 14:17:42
</syntaxhighlight>
 
{{ArgTitle|3|__DAY__|{{GVI|arma3|2.16}}}}
 
'''Description:''' Is replaced for UTC day.
<syntaxhighlight lang="cpp">
__DAY__ // 20
</syntaxhighlight>
 
{{ArgTitle|3|__MONTH__|{{GVI|arma3|2.16}}}}
 
'''Description:''' Is replaced for UTC month.
<syntaxhighlight lang="cpp">
__MONTH__ // 11
</syntaxhighlight>
 
{{ArgTitle|3|__YEAR__|{{GVI|arma3|2.16}}}}
 
'''Description:''' Is replaced for UTC year.
<syntaxhighlight lang="cpp">
__YEAR__ // 2023
</syntaxhighlight>
 
{{ArgTitle|3|__COUNTER__|{{GVI|arma3|2.02}}}}
 
'''Description:''' Counts 1 up everytime it is defined.
<syntaxhighlight lang="cpp">
__COUNTER__ // 0
__COUNTER__ // 1
__COUNTER__ // 2
__COUNTER__ // 3
__COUNTER_RESET__
__COUNTER__ // 0
__COUNTER__ // 1
__COUNTER__ // 2
</syntaxhighlight>
 
{{ArgTitle|3|__TIMESTAMP_UTC__|{{GVI|arma3|2.06}}}}
 
'''Description:''' Is replaced to the current timestamp in UNIX timestamp.
<syntaxhighlight lang="cpp">
__TIMESTAMP_UTC__ // 1622639059
</syntaxhighlight>
 
{{ArgTitle|3|__COUNTER_RESET__|{{GVI|arma3|2.02}}}}
 
'''Description:''' Resets counter. See example above.
 
{{ArgTitle|3|__RAND_INT{{hl|N}}__|{{GVI|arma3|2.02}}}}


addquotes(call fn_myfunc) result is: "call compile preprocessfile 'myfile.sqf'"
'''Description:''' Gets replaced by a random {{hl|N}} bit integer. {{hl|N}} can be 8, 16, 32 or 64, e.g:
<syntaxhighlight lang="cpp">
__RAND_INT8__
__RAND_INT16__
__RAND_INT32__
__RAND_INT64__
</syntaxhighlight>


==#undef==
<syntaxhighlight lang="cpp">
'''Syntax:'''
__RAND_INT8__ // e.g -102
#undef NAME
</syntaxhighlight>


This will undefine (delete) a macro previously set by the use of #define.
{{ArgTitle|3|__RAND_UINT{{hl|N}}__|{{GVI|arma3|2.02}}}}


'''Description:''' Gets replaced by a random ''unsigned'' {{hl|N}} bit integer. {{hl|N}} can be 8, 16, 32 or 64, e.g:
<syntaxhighlight lang="cpp">
__RAND_UINT8__
__RAND_UINT16__
__RAND_UINT32__
__RAND_UINT64__
</syntaxhighlight>


==#ifdef==
<syntaxhighlight lang="cpp">
'''Syntax:'''
__RAND_UINT8__ // 108
#ifdef NAME
</syntaxhighlight>
  ...text that will be used if NAME is defined...
#endif
IFDEFs ''cannot'' be nested, as the preprocessor will generate an error if the outer definition doesn't exist.


==#ifndef==
{{ArgTitle|3|__GAME_VER__|{{GVI|arma3|2.02}}}}
'''Syntax:'''
#ifndef NAME
  ...text that will be used if NAME ''isn't'' defined...
#endif


'''Description:''' Gets replaced by the game version.
<syntaxhighlight lang="cpp">
__GAME_VER__ // 02.00.146790
</syntaxhighlight>


==#else==
{{ArgTitle|3|__GAME_VER_MAJ__|{{GVI|arma3|2.02}}}}
'''Syntax:'''
#ifndef NAME
  ...text that will be used if NAME ''isn't'' defined...
#else
  ...text that will be used if NAME ''is'' defined...
#endif


'''Description:''' Gets replaced by the ''major'' game version.
<syntaxhighlight lang="cpp">
__GAME_VER_MAJ__ // 02
</syntaxhighlight>


==#endif==
{{ArgTitle|3|__GAME_VER_MIN__|{{GVI|arma3|2.02}}}}
This ends a conditional block as shown in the descriptions of #ifdef and #ifndef above.
 
'''Description:''' Gets replaced by the ''minor'' game version.
<syntaxhighlight lang="cpp">
__GAME_VER_MIN__ // 00
</syntaxhighlight>
 
{{ArgTitle|3|__GAME_BUILD__|{{GVI|arma3|2.02}}}}
 
'''Description:''' Gets replaced by the build number.
<syntaxhighlight lang="cpp">
__GAME_BUILD__ // 146790
</syntaxhighlight>
 
{{ArgTitle|3|__A3_DIAG__|{{GVI|arma3|2.12}}}}
 
'''Description:''' Gets replaced by 1 on diag, undefined otherwise.
<syntaxhighlight lang="cpp">
__GAME_BUILD__ // 1
</syntaxhighlight>
 
{{ArgTitle|3|__ARMA__|{{GVI|arma3|2.02}}}}
 
'''Description:''' {{Wiki|stub}}
<syntaxhighlight lang="cpp">
__ARMA__ // 1
</syntaxhighlight>
 
{{ArgTitle|3|__ARMA3__|{{GVI|arma3|2.02}}}}
 
'''Description:''' {{Wiki|stub}}
<syntaxhighlight lang="cpp">
__ARMA3__ // 1
</syntaxhighlight>
 
{{ArgTitle|3|__A3_DEBUG__|{{GVI|arma3|2.02}}}}
 
'''Description:''' This macro is only set when the [[Arma 3: Startup Parameters|-debug parameter]] was provided. It can be used to switch mods or scripts to debug mode dynamically.
<syntaxhighlight lang="cpp">
__A3_DEBUG__ // 1 (if -debug was enabled)
</syntaxhighlight>
 
{{ArgTitle|3|__A3_EXPERIMENTAL__|{{GVI|arma3|2.15}}}}
 
'''Description:''' This macro is only set in experimental game builds ([[Arma_3:_Steam_Branches|Development branch]] or [[Arma_3:_Steam_Branches|Profiling branch]])
<syntaxhighlight lang="cpp">
__A3_EXPERIMENTAL__ // 1 (if on dev or profiling branch)
</syntaxhighlight>
can be combined with game build to check for bugfixes added to profiling branch (in case a stable branch hotfix is released with a higher buildnumber but that doesn't include the fix)
<syntaxhighlight lang="cpp">
#if __GAME_VER_MIN__ >= 16 //#TODO remove this workaround when 2.16 is released
#define BUG_FIXED
#endif
 
#if __GAME_BUILD__ > 151035 // Builds newer than this
#if __A3_EXPERIMENTAL__ // But on experimental only
#define BUG_FIXED
#endif
#endif
 
#ifdef BUG_FIXED
use the thing
#else
don't use the thing and have some workaround
#endif
</syntaxhighlight>
 
{{ArgTitle|3|__A3_PROFILING__|{{GVI|arma3|2.15}}}}
 
'''Description:''' This macro is only set when Profiling commands are available ([[Arma_3:_Steam_Branches|Development branch]] diag binary or in [[Arma_3:_Steam_Branches|Profiling branch]] profiling binary)
<syntaxhighlight lang="cpp">
#if __A3_PROFILING__
diag_captureFrame 1;
#endif
</syntaxhighlight>
 
== Config Parser ==
 
{{Feature|important|
* {{hl|__EXEC}} and {{hl|__EVAL}} '''cannot''' be used in preprocessor {{Link|#Macros}}, e.g '''{{Link|##if}}'''!
}}
{{Feature|informative|
* {{hl|__EXEC}} and {{hl|__EVAL}} can be used in configs (such as [[config.cpp]], [[Description.ext]], [[Rvmat File Format|RVMat]] etc) but are not suitable for [[SQF Syntax|SQF]] or [[SQS Syntax|SQS]] scripts.
* As they use [[parsingNamespace]], both global and local variables set in {{hl|__EXEC}} are available in {{hl|__EVAL}}.
* [[parsingNamespace]] can then be accessed through scripting; see the {{Link|#EXEC|__EXEC}} example below.
}}
 
=== __EXEC ===
 
This '''Config Parser''' macro allows to assign values to internal variables or just execute arbitrary code.
The code inside {{hl|__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:
 
<syntaxhighlight lang="cpp">
__EXEC(cat = 5 + 1;)
__EXEC(lev = cat - 2;)
</syntaxhighlight>
<sqf>
_cat = parsingNamespace getVariable "cat"; // 6
_lev = parsingNamespace getVariable "lev"; // 4
</sqf>
 
{{Feature|warning|
{{hl|__EXEC}} does not like round brackets {{hl|()}} inside expressions. If grouping is needed, perhaps values could be calculated inside the brackets separately and assigned to local variables:
<syntaxhighlight lang="cpp">__EXEC(a = (1+2);) // ERROR</syntaxhighlight>
<syntaxhighlight lang="cpp">
__EXEC(_expr = 1+2;)
__EXEC(a = _expr;) // OK
</syntaxhighlight>
}}
 
=== __EVAL ===
 
With this '''Config Parser''' macro expressions can be evaluated, including previously assigned internal variables. Unlike {{hl|__EXEC}}, {{hl|__EVAL}} supports multiple parentheses:
 
<syntaxhighlight lang="cpp">
w = __EVAL(safeZoneW - (5 * ((1 / (getResolution select 2)) * 1.25 * 4)));
</syntaxhighlight>
 
* {{hl|__EVAL}} macros '''must''' be assigned to a config property and the expression '''must''' be terminated with {{hl|;}}.
* {{hl|__EVAL}} can only return [[Number]] or [[String]]. Any other type is represented as [[String]], even [[Boolean]] type (which would result in either {{hl|"true"}} or {{hl|"false"}}).
 
{{Feature|informative|
if code is needed in the expression, use [[compile]] [[String]] instead. Like so:
<syntaxhighlight lang="cpp">result = __EVAL(call compile "123");</syntaxhighlight>
that is because {{hl|__EVAL}} is incapable of dealing with curly brackets {{hl|{}}}
 
}}
 
== Errors ==
 
=== Error 2 ===
 
; Problem: Preprocessor failed error 2.
 
; How to fix: Add quotation marks in the title, or the file path. (''e.g.'' {{hl|#include "soGood.sqf"}}).
 
=== Error 6 ===
 
; Problem: Preprocessor failed on file X - error 6.
 
; Known reasons:
: "The problem is using {{hl|#ifdef #ifdef #endif #endif}}, a.k.a nested {{hl|#ifdef}}. This doesn't work in Arma. It's only possible to use {{hl|#ifdef}} and {{hl|#endif}} once and not nested."
: {{hl|#endif}} without preceding {{hl|#ifdef}} or {{hl|#ifndef}}


==__LINE__==
=== Error 7 ===


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.
; Problem: Preprocessor failed on file X - error 7.


==__FILE__==
; Known reasons: The preprocessor encountered an unknown directive. Read, as a typo most has likely found a way into the file (something like {{hl|#inlcude}} or {{hl|#defien}}).<!--
--> Double-check all preprocessor directives in that file.


This keyword gets replaced with the path to the file where it is found.


For scripts packed into an addon, a relative path is displayed (relative to the program's exe file). For scripts in a mission folder, a direct path is displayed (drive letter and full path). [Note: untested what happens when this is used inside of a config]
== External links ==


Example:
* {{Link|https://web.archive.org/web/20170319190732/http://ofp-faguss.com/files/ofp_preprocessor_explained.pdf|{{ofp}} - Preprocessor Guide (Wayback Machine)}}
<pre>//recurse.sqf
* {{Link|https://github.com/Krzmbrzl/ArmaPreprocessorTestCases|Collection of preprocessor test-cases}}
_i = _this select 0;
if (_i < 100) then {[_i + 1] execVM __FILE__};</pre>




[[category:Operation Flashpoint: Editing]]
[[Category:Scripting Topics]]
[[Category:ArmA: Addon Configuration]]

Latest revision as of 17:28, 19 May 2024

The PreProcessor and the Config Parser allow to use macros in configs. The purpose of macros is to re-use the same definition in scripts and configs multiple times. It also gives a centralized place to correct errors in this definition. Know that edge cases may arise - see the collection of test-cases linked at the end of this page.

Arma 3
In Arma 3, preprocessor commands are case-sensitive!


Parsing

See Config Parser below:


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.

⚠
Sometimes a problematic string can fail to purge these comment outs during preprocessing!
private _a = '"'; // this is just a comment, but failed to remove upon the preprocess so will return an error. Caused by that string
// this is a single-line comment
 
/*
	this is a
	multi-line
	comment
*/
 
myValue = 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, it is possible to 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 does not 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 are not 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

Arguments can be added 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 CAR("Mini") is used, it 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 commas can even get passed in as a 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 the 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, only whole words can be replaced by arguments. If only a part of the word should be replaced, 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; \

It is also possible to use the single # to convert an argument to a string. 

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

Multi-line

For longer definitions, one 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

#if

Description: Checks condition and processes content if condition returns 1. Skips content if it returns 0 

#if __GAME_VER_MAJ__ != 2
// Do something...
#endif

Comparison Operators

The following operations are supported:

  • <
  • >
  • <=
  • >=
  • ==
  • !=

Example: 

#if __GAME_VER_MAJ__ != 2
// Do something...
#endif

#ifdef

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

#ifdef NAME
	// config 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
	// config that will be used if NAME is -not- defined
#endif

#else

Provides alternative code to #if, #ifdef, #ifndef checks. 

#ifndef NAME
	// config that will be used if NAME is -not- defined
#else
	// config 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:

  • For any file without starting the include path with \ - the file's current directory
  • When starting with \ - the internal filesystem root (see Addon Development) or the Game's working directory (only with -filePatching enabled)

A path beginning can be defined as follow:

  • drive (only with -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 since Arma 3 logo black.png1.50): 

#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 argument and stringifies that (as in the example above). 

#define MACRO Test #123
MACRO // preprocesses to Test 123 - note that there are not 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;

__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. e.g 

"userconfig\file1.sqf"

__FILE_NAME__

This keyword gets replaced with the name of the current file being processed. e.g 

"file1.sqf"

__FILE_SHORT__

This keyword gets replaced with the name of the current file being processed, without extension. e.g 

"file1"

__has_include

Description: Checks if given file exists. Returns 1 if it does, 0 if it does not exist.

⚠
  • The file path must start with the backslash \ otherwise it would fail silently (returns 0 so does nothing unless you put something in #else)!
  • If you wanted to make an addon that can change its config dynamically depending on mods that loaded along, do not binarize the config.cpp!
ⓘ
To validate that the file exists in your game, you can use fileExists command to check.
fileExists "\a3\data_f\config.bin"; // returns true fileExists "\z\ace\addons\main\script_component.hpp"; // returns true if ACE is loaded, false otherwise
#if __has_include("\z\ace\addons\main\script_component.hpp")
// file exists! Do something with it
#else
// file does not exist
#endif

__DATE_ARR__

Description: Is replaced for current date in format array. 

__DATE_ARR__ // 2020,10,28,15,17,42

__DATE_STR__

Description: Is replaced for current date in format string. 

__DATE_STR__  // "2020/10/28, 15:17:42"

__DATE_STR_ISO8601__

Description: Is replaced for current date in format string. The date is presented in ISO8601 standard. 

__DATE_STR_ISO8601__ // "2020-10-28T14:17:42Z"

__TIME__

Description: Is replaced for current time. 

__TIME__ // 15:17:42

__TIME_UTC__

Description: Is replaced for UTC time. 

__TIME_UTC__ // 14:17:42

__DAY__

Description: Is replaced for UTC day. 

__DAY__ // 20

__MONTH__

Description: Is replaced for UTC month. 

__MONTH__ // 11

__YEAR__

Description: Is replaced for UTC year. 

__YEAR__ // 2023

__COUNTER__

Description: Counts 1 up everytime it is defined. 

__COUNTER__ // 0
__COUNTER__ // 1
__COUNTER__ // 2
__COUNTER__ // 3
__COUNTER_RESET__
__COUNTER__ // 0
__COUNTER__ // 1
__COUNTER__ // 2

__TIMESTAMP_UTC__

Description: Is replaced to the current timestamp in UNIX timestamp. 

__TIMESTAMP_UTC__ // 1622639059

__COUNTER_RESET__

Description: Resets counter. See example above.

__RAND_INTN__

Description: Gets replaced by a random N bit integer. N can be 8, 16, 32 or 64, e.g: 

__RAND_INT8__
__RAND_INT16__
__RAND_INT32__
__RAND_INT64__

__RAND_INT8__ // e.g -102

__RAND_UINTN__

Description: Gets replaced by a random unsigned N bit integer. N can be 8, 16, 32 or 64, e.g: 

__RAND_UINT8__
__RAND_UINT16__
__RAND_UINT32__
__RAND_UINT64__

__RAND_UINT8__ // 108

__GAME_VER__

Description: Gets replaced by the game version. 

__GAME_VER__ // 02.00.146790

__GAME_VER_MAJ__

Description: Gets replaced by the major game version. 

__GAME_VER_MAJ__ // 02

__GAME_VER_MIN__

Description: Gets replaced by the minor game version. 

__GAME_VER_MIN__ // 00

__GAME_BUILD__

Description: Gets replaced by the build number. 

__GAME_BUILD__ // 146790

__A3_DIAG__

Description: Gets replaced by 1 on diag, undefined otherwise. 

__GAME_BUILD__ // 1

__ARMA__

Description:

This article is a Stub. You can help BI Community Wiki by expanding it.
__ARMA__ // 1

__ARMA3__

Description:

This article is a Stub. You can help BI Community Wiki by expanding it.
__ARMA3__ // 1

__A3_DEBUG__

Description: This macro is only set when the -debug parameter was provided. It can be used to switch mods or scripts to debug mode dynamically. 

__A3_DEBUG__ // 1 (if -debug was enabled)

__A3_EXPERIMENTAL__

Description: This macro is only set in experimental game builds (Development branch or Profiling branch) 

__A3_EXPERIMENTAL__ // 1 (if on dev or profiling branch)

can be combined with game build to check for bugfixes added to profiling branch (in case a stable branch hotfix is released with a higher buildnumber but that doesn't include the fix) 

#if __GAME_VER_MIN__ >= 16 //#TODO remove this workaround when 2.16 is released
#define BUG_FIXED
#endif

#if __GAME_BUILD__ > 151035 // Builds newer than this
#if __A3_EXPERIMENTAL__ // But on experimental only
#define BUG_FIXED
#endif
#endif

#ifdef BUG_FIXED
use the thing
#else
don't use the thing and have some workaround
#endif

__A3_PROFILING__

Description: This macro is only set when Profiling commands are available (Development branch diag binary or in Profiling branch profiling binary) 

#if __A3_PROFILING__
diag_captureFrame 1;
#endif

Config Parser

⚠
  • __EXEC and __EVAL cannot be used in preprocessor Macros, e.g #if!
ⓘ

__EXEC

This Config Parser macro allows 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 does not like round brackets () inside expressions. If grouping is needed, perhaps values could be calculated inside the brackets separately and assigned to local variables: 
__EXEC(a = (1+2);) // ERROR

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

__EVAL

With this Config Parser macro expressions can be evaluated, including previously assigned internal variables. Unlike __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 only return Number or String. Any other type is represented as String, even Boolean type (which would result in either "true" or "false").
ⓘ
if code is needed in the expression, use compile String instead. Like so: 
result = __EVAL(call compile "123");
that is because __EVAL is incapable of dealing with curly brackets {}

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, as a typo most has likely found a way into the file (something like #inlcude or #defien). Double-check all preprocessor directives in that file.


External links

Retrieved from "https://community.bistudio.com/wiki?title=PreProcessor_Commands&oldid=364599"