A general set of useful macro functions for use by CBA itself or by any module that uses CBA.
Sickboy <sb_at_dev-heaven.net> and Spooner
| script_macros_common.hpp | A general set of useful macro functions for use by CBA itself or by any module that uses CBA. |
| VERSION_CONFIG | Define CBA Versioning System config entries. |
| Debugging | |
| DEBUG_MODE_x | Managing debugging based on debug level. |
| LOG() | Log a debug message into the RPT log. |
| INFO() | Record a message without file and line number in the RPT log. |
| WARNING() | Record a non-critical error in the RPT log. |
| ERROR() | Record a critical error in the RPT log. |
| ERROR_MSG() | Record a critical error in the RPT log and display on screen error message. |
| ERROR_WITH_TITLE() | Record a critical error in the RPT log. |
| MESSAGE_WITH_TITLE() | Record a single line in the RPT log. |
| RETDEF() | If a variable is undefined, return the default value. |
| RETNIL() | If a variable is undefined, return the value nil. |
| TRACE_n() | Log a message and 1-8 variables to the RPT log. |
| General | |
| INC() | Increase a number by one. |
| DEC() | Decrease a number by one. |
| ADD() | Add a value to a variable. |
| SUB() | Subtract a value from a number variable. |
| REM() | Remove an element from an array each time it occurs. |
| PUSH() | Appends a single value onto the end of an ARRAY. |
| MAP() | Applies given code to each element of the array, then assigns the resulting array to the original Parameters: ARRAY - Array to be modified CODE - Code that’ll be applied to each element of the array. |
| FILTER() | Filters an array based on given code, then assigns the resulting array to the original Parameters: ARRAY - Array to be filtered CODE - Condition to pick elements Example: |
| UNIQUE() | Removes duplicate values in given array Parameters: ARRAY - The array to be modified Example: |
| INTERSECTION() | Finds unique common elements between two arrays and assigns them to the first array Parameters: ARRAY0 - The array to be modified ARRAY1 - The array to find intersections with Example: |
| ISNILS() | Sets a variable with a value, but only if it is undefined. |
| GVAR() | Get full variable identifier for a global variable owned by this component. |
| GVARMAIN() | Get full variable identifier for a global variable owned by this addon. |
| PREP() | Defines a function. |
| PATHTO_FNC() | Defines a function inside CfgFunctions. |
| ARG_#() | Select from list of array arguments |
| ARR_#() | Create list from arguments. |
| FORMAT_#(STR, ARG1) | |
| IS_x() | Checking the data types of variables. |
| SCRIPT() | Sets name of script (relies on PREFIX and COMPONENT values being #defined). |
| EXPLODE_n() | |
| xSTRING() | Get full string identifier from a stringtable owned by this component. |
| Managing Function Parameters | |
| PARAMS_n() | |
| DEFAULT_PARAM() | |
| KEY_PARAM() | Get value from key in _this list, return default when key is not included in list. |
| Assertions | |
| ASSERT_TRUE() | Asserts that a CONDITION is true. |
| ASSERT_FALSE() | Asserts that a CONDITION is false. |
| ASSERT_OP() | Asserts that (A OPERATOR B) is true. |
| ASSERT_DEFINED() | Asserts that a VARIABLE is defined. |
| Unit tests | |
| TEST_TRUE() | Tests that a CONDITION is true. |
| TEST_FALSE() | Tests that a CONDITION is false. |
| TEST_OP() | Tests that (A OPERATOR B) is true. |
| TEST_DEFINED_AND_OP() | Tests that A and B are defined and (A OPERATOR B) is true. |
| TEST_DEFINED() | Tests that a VARIABLE is defined. |
| Managing Deprecation | |
| DEPRECATE_SYS() | Allow deprecation of a function that has been renamed. |
| DEPRECATE() | Allow deprecation of a function, in the current component, that has been renamed. |
| OBSOLETE_SYS() | Replace a function that has become obsolete. |
| OBSOLETE() | Replace a function, in the current component, that has become obsolete. |
| IS_ADMIN | Check if the local machine is an admin in the multiplayer environment. |
| IS_ADMIN_LOGGED | Check if the local machine is a logged in admin in the multiplayer environment. |
| FILE_EXISTS | Check if a file exists |
Define CBA Versioning System config entries.
VERSION should be a floating-point number (1 separator). VERSION_STR is a string representation of the version. VERSION_AR is an array representation of the version.
VERSION must always be defined, otherwise it is 0. VERSION_STR and VERSION_AR default to VERSION if undefined.
None
#define VERSION 1.0
#define VERSION_STR 1.0.1
#define VERSION_AR 1,0,1
class CfgPatches {
class MyMod_main {
VERSION_CONFIG;
};
};?, Jonpas
Managing debugging based on debug level.
According to the highest level of debugging that has been defined before script_macros_common.hpp is included, only the appropriate debugging commands will be functional. With no level explicitely defined, assume DEBUG_MODE_NORMAL.
| DEBUG_MODE_FULL | Full debugging output. |
| DEBUG_MODE_NORMAL | All debugging except TRACE_n() and LOG() (Default setting if none specified). |
| DEBUG_MODE_MINIMAL | Only ERROR() and ERROR_WITH_TITLE() enabled. |
In order to turn on full debugging for a single file,
// Top of individual script file. #define DEBUG_MODE_FULL #include "script_component.hpp"
In order to force minimal debugging for a single component,
// Top of addons\<component>\script_component.hpp // Ensure that any FULL and NORMAL setting from the individual files are undefined and MINIMAL is set. #ifdef DEBUG_MODE_FULL #undef DEBUG_MODE_FULL #endif #ifdef DEBUG_MODE_NORMAL #undef DEBUG_MODE_NORMAL #endif #ifndef DEBUG_MODE_MINIMAL #define DEBUG_MODE_MINIMAL #endif #include "script_macros.hpp"
In order to turn on full debugging for a whole addon,
// Top of addons\main\script_macros.hpp #ifndef DEBUG_MODE_FULL #define DEBUG_MODE_FULL #endif #include "\x\cba\addons\main\script_macros_common.hpp"
Spooner
Log a debug message into the RPT log.
Only run if DEBUG_MODE_FULL is defined.
| MESSAGE | Message to record STRING |
LOG("Initiated clog-dancing simulator.");Spooner
Record a message without file and line number in the RPT log.
| MESSAGE | Message to record STRING |
INFO("Mod X is loaded, do Y");commy2
Record a non-critical error in the RPT log.
Only run if DEBUG_MODE_NORMAL or higher is defined.
| MESSAGE | Message to record STRING |
WARNING("This function has been deprecated. Please don't use it in future!");Spooner
Record a critical error in the RPT log.
| MESSAGE | Message to record STRING |
ERROR("value of frog not found in config ...yada...yada...");Spooner
Record a critical error in the RPT log and display on screen error message.
Newlines (\n) in the MESSAGE will be put on separate lines.
| MESSAGE | Message to record STRING |
ERROR_MSG("value of frog not found in config ...yada...yada...");commy2
Record a critical error in the RPT log.
The title can be specified (in ERROR() the heading is always just “ERROR”) Newlines (\n) in the MESSAGE will be put on separate lines.
| TITLE | Title of error message STRING |
| MESSAGE | Body of error message STRING |
ERROR_WITH_TITLE("Value not found","Value of frog not found in config ...yada...yada...");Spooner
If a variable is undefined, return the default value. Otherwise, return the variable itself.
| VARIABLE | the variable to check |
| DEFAULT_VALUE | the default value to use if variable is undefined |
// _var is undefined hintSilent format ["_var=%1", RETDEF(_var,5)]; // "_var=5" _var = 7; hintSilent format ["_var=%1", RETDEF(_var,5)]; // "_var=7"
Author: 654wak654
Log a message and 1-8 variables to the RPT log.
Only run if DEBUG_MODE_FULL is defined.
| MESSAGE | Message to add to the trace [String] |
| A..H | Variable names to log values of [Any] |
TRACE_3("After takeoff",_vehicle player,getPos (_vehicle player), getPosASL (_vehicle player));Spooner
Add a value to a variable. Variable and value should be both Numbers or both Strings.
| VAR | Variable to add to [Number or String] |
| VALUE | Value to add [Number or String] |
_counter = 2; ADD(_counter,3); // _counter => 5
_str = "hello"; ADD(_str," "); ADD(_str,"Fred"); // _str => "hello Fred"
Sickboy
Remove an element from an array each time it occurs.
This recreates the entire array, so use BIS_fnc_removeIndex if modification of the original array is required or if only one of the elements that matches ELEMENT needs to be removed.
| ARRAY | Array to modify [Array] |
| ELEMENT | Element to remove [Any] |
_array = [1, 2, 3, 4, 3, 8]; REM(_array,3); // _array = [1, 2, 4, 8];
Spooner
Appends a single value onto the end of an ARRAY. Change is made to the ARRAY itself, not creating a new array.
| ARRAY | Array to push element onto [Array] |
| ELEMENT | Element to push [Any] |
_fish = ["blue", "green", "smelly"]; PUSH(_fish,"monkey-flavoured"); // _fish => ["blue", "green", "smelly", "monkey-flavoured"]
Spooner
Applies given code to each element of the array, then assigns the resulting array to the original Parameters: ARRAY - Array to be modified CODE - Code that’ll be applied to each element of the array. Example:
_array = [1, 2, 3, 4, 3, 8]; MAP(_array,_x + 1); // _array is now [2, 3, 4, 5, 4, 9];
Author: 654wak654
Finds unique common elements between two arrays and assigns them to the first array Parameters: ARRAY0 - The array to be modified ARRAY1 - The array to find intersections with Example:
_someArray = [1, 2, 3, 4, 5, 5]; _anotherArray = [4, 5, 6, 7]; INTERSECTION(_someArray,_anotherArray); // _someArray is now [4, 5]
Author: 654wak654
Sets a variable with a value, but only if it is undefined.
| VARIABLE | Variable to set [Any, not nil] |
| DEFAULT_VALUE | Value to set VARIABLE to if it is undefined [Any, not nil] |
// _fish is undefined ISNILS(_fish,0); // _fish => 0
_fish = 12; // ...later... ISNILS(_fish,0); // _fish => 12
Sickboy
Defines a function.
’\MAINPREFIX\PREFIX\SUBPREFIX\COMPONENT\fnc_<FNC>.sqf’
’PREFIX_COMPONENT_<FNC>’
The PREP macro should be placed in a script run by a XEH preStart and XEH preInit event.
The PREP macro allows for CBA function caching, which drastically speeds up load times. Beware though that function caching is enabled by default and as such to disable it, you need to #define DISABLE_COMPILE_CACHE above your #include “script_components.hpp” include!
The function will be defined in ui and mission namespace. It can not be overwritten without a mission restart.
| FUNCTION NAME | Name of the function, unquoted STRING |
PREP(banana); call FUNC(banana);
dixon13
Defines a function inside CfgFunctions.
’\MAINPREFIX\PREFIX\SUBPREFIX\COMPONENT\fnc_<FNC>.sqf’ Define ‘RECOMPILE’ to enable recompiling. Define ‘SKIP_FUNCTION_HEADER’ to skip adding function header.
| FUNCTION NAME | Name of the function, unquoted STRING |
// file name: fnc_addPerFrameHandler.sqf
class CfgFunctions {
class CBA {
class Misc {
PATHTO_FNC(addPerFrameHandler);
};
};
};
// -> CBA_fnc_addPerFrameHandlerdixon13, commy2
Checking the data types of variables.
| IS_ARRAY() | Array |
| IS_BOOL() | Boolean |
| IS_BOOLEAN() | UI display handle(synonym for IS_BOOL()) |
| IS_CODE() | Code block (i.e a compiled function) |
| IS_CONFIG() | Configuration |
| IS_CONTROL() | UI control handle. |
| IS_DISPLAY() | UI display handle. |
| IS_FUNCTION() | A compiled function (synonym for IS_CODE()) |
| IS_GROUP() | Group. |
| IS_INTEGER() | Is a number a whole number? |
| IS_LOCATION() | World location. |
| IS_NUMBER() | A floating point number (synonym for IS_SCALAR()) |
| IS_OBJECT() | World object. |
| IS_SCALAR() | Floating point number. |
| IS_SCRIPT() | A script handle (as returned by execVM and spawn commands). |
| IS_SIDE() | Game side. |
| IS_STRING() | World object. |
| IS_TEXT() | Structured text. |
| VARIABLE | Variable to check if it is of a particular type [Any, not nil] |
Spooner
| DEPRECATED | Use param/params commands added in Arma 3 1.48 |
Splitting an ARRAY into a number of variables (A, B, C, etc).
Note that this NOT does make the created variables private. _PVT variants do.
| ARRAY | Array to read from [Array] |
| A..H | Names of variables to set from array [Identifier] |
_array = ["fred", 156.8, 120.9]; EXPLODE_3(_array,_name,_height,_weight);
Spooner
Get full string identifier from a stringtable owned by this component.
| VARIABLE | Partial name of global variable owned by this component [Any]. |
ADDON is CBA_Balls.
// Localized String (localize command must still be used with it) LSTRING(Example); // STR_CBA_Balls_Example; // Config String (note the $) CSTRING(Example); // $STR_CBA_Balls_Example;
Jonpas
| DEPRECATED | Use param/params commands added in Arma 3 1.48 |
Setting variables based on parameters passed to a function.
Each parameter is defines as private and set to the appropriate value from _this.
| A..H | Name of variable to read from _this [Identifier] |
A function called like this:
[_name,_address,_telephone] call recordPersonalDetails;
expects 3 parameters and those variables could be initialised at the start of the function definition with:
recordPersonalDetails = {
PARAMS_3(_name,_address,_telephone);
// Rest of function follows...
};Spooner
| DEPRECATED | Use param/params commands added in Arma 3 1.48 - Will not work with HEMTT 1.13.2+ |
Getting a default function parameter. This may be used together with PARAMS_n() to have a mix of required and optional parameters.
| INDEX | Index of parameter in _this [Integer, 0+] |
| NAME | Name of the variable to set [Identifier] |
| DEF_VALUE | Default value to use in case the array is too short or the value at INDEX is nil [Any] |
A function called with optional parameters:
[_name] call myFunction; [_name, _numberOfLegs] call myFunction; [_name, _numberOfLegs, _hasAHead] call myFunction;
1 required parameter and 2 optional parameters. Those variables could be initialised at the start of the function definition with:
myFunction = {
PARAMS_1(_name);
DEFAULT_PARAM(1,_numberOfLegs,2);
DEFAULT_PARAM(2,_hasAHead,true);
// Rest of function follows...
};Spooner
Asserts that (A OPERATOR B) is true. When an assertion fails, an error is raised with the given MESSAGE.
| A | First value [Any] |
| OPERATOR | Binary operator to use [Operator] |
| B | Second value [Any] |
| MESSSAGE | Message to display if (A OPERATOR B) is false. [String] |
ASSERT_OP(_fish,>,5,"Too few fish!");
Spooner
Asserts that a VARIABLE is defined. When an assertion fails, an error is raised with the given MESSAGE..
| VARIABLE | Variable to test if defined [String or Function]. |
| MESSAGE | Message to display if variable is undefined [String]. |
ASSERT_DEFINED("_anUndefinedVar","Too few fish!");
ASSERT_DEFINED({ obj getVariable "anUndefinedVar" },"Too many fish!");Spooner
Tests that (A OPERATOR B) is true. If the test fails, an error is raised with the given MESSAGE.
| A | First value [Any] |
| OPERATOR | Binary operator to use [Operator] |
| B | Second value [Any] |
| MESSSAGE | Message to display if (A OPERATOR B) is false. [String] |
TEST_OP(_fish,>,5,"Too few fish!");
Killswitch
Tests that A and B are defined and (A OPERATOR B) is true. If the test fails, an error is raised with the given MESSAGE.
| A | First value [Any] |
| OPERATOR | Binary operator to use [Operator] |
| B | Second value [Any] |
| MESSSAGE | Message to display [String] |
TEST_OP(_fish,>,5,"Too few fish!");
Killswitch, PabstMirror
Tests that a VARIABLE is defined.
| VARIABLE | Variable to test if defined [String or Function]. |
| MESSAGE | Message to display if variable is undefined [String]. |
TEST_DEFINED("_anUndefinedVar","Too few fish!");
TEST_DEFINED({ obj getVariable "anUndefinedVar" },"Too many fish!");Killswitch
Allow deprecation of a function that has been renamed.
Replaces an old OLD_FUNCTION (which will have PREFIX_ prepended) with a NEW_FUNCTION (PREFIX_ prepended) with the intention that the old function will be disabled in the future.
Shows a warning in RPT each time the deprecated function is used, but runs the new function.
| OLD_FUNCTION | Full name of old function [Identifier for function that does not exist any more] |
| NEW_FUNCTION | Full name of new function [Function] |
// After renaming CBA_fnc_frog as CBA_fnc_fish DEPRECATE_SYS(CBA_fnc_frog,CBA_fnc_fish);
Sickboy
Allow deprecation of a function, in the current component, that has been renamed.
Replaces an OLD_FUNCTION (which will have PREFIX_ prepended) with a NEW_FUNCTION (PREFIX_ prepended) with the intention that the old function will be disabled in the future.
Shows a warning in RPT each time the deprecated function is used, but runs the new function.
| OLD_FUNCTION | Name of old function, assuming PREFIX [Identifier for function that does not exist any more] |
| NEW_FUNCTION | Name of new function, assuming PREFIX [Function] |
// After renaming CBA_fnc_frog as CBA_fnc_fish DEPRECATE(fnc_frog,fnc_fish);
Sickboy
Replace a function that has become obsolete.
Replace an obsolete OLD_FUNCTION with a simple COMMAND_FUNCTION, with the intention that anyone using the function should replace it with the simple command, since the function will be disabled in the future.
Shows a warning in RPT each time the deprecated function is used, and runs the command function.
| OLD_FUNCTION | Full name of old function [Identifier for function that does not exist any more] |
| COMMAND_CODE | Code to replace the old function [Function] |
// In Arma2, currentWeapon command made the CBA_fMyWeapon function obsolete:
OBSOLETE_SYS(CBA_fMyWeapon,{ currentWeapon player });Spooner
Replace a function, in the current component, that has become obsolete.
Replace an obsolete OLD_FUNCTION (which will have PREFIX_ prepended) with a simple COMMAND_CODE, with the intention that anyone using the function should replace it with the simple command.
Shows a warning in RPT each time the deprecated function is used.
| OLD_FUNCTION | Name of old function, assuming PREFIX [Identifier for function that does not exist any more] |
| COMMAND_CODE | Code to replace the old function [Function] |
// In Arma2, currentWeapon command made the CBA_fMyWeapon function obsolete:
OBSOLETE(fMyWeapon,{ currentWeapon player });Spooner