script_macros_common.hpp

Description

A general set of useful macro functions for use by CBA itself or by any module that uses CBA.

Authors

Sickboy <sb_at_dev-heaven.net> and Spooner

Summary
script_macros_common.hppA general set of useful macro functions for use by CBA itself or by any module that uses CBA.
Debugging
DEBUG_MODE_xManaging debugging based on debug level.
LOG()Log a timestamped message into the RPT log.
WARNING()Record a timestamped, non-critical error in the RPT log.
ERROR()Record a timestamped, critical error in the RPT log.
ERROR_WITH_TITLE()Record a timestamped, critical error in the RPT log.
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.
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.
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()Splitting an ARRAY into a number of variables (A, B, C, etc).
Managing Function Parameters
PARAMS_n()Setting variables based on parameters passed to a function.
DEFAULT_PARAM()Getting a default function parameter.
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.
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.

Debugging

DEBUG_MODE_x

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_FULLFull debugging output.
DEBUG_MODE_NORMALAll debugging except TRACE_n() and LOG() (Default setting if none specified).
DEBUG_MODE_MINIMALOnly ERROR() and ERROR_WITH_TITLE() enabled.

Examples

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"

Author

Spooner

LOG()

Log a timestamped message into the RPT log.

Only run if DEBUG_MODE_FULL or higher is defined.

Parameters

MESSAGEMessage to record [String]

Example

LOG("Initiated clog-dancing simulator.");

Author

Spooner

WARNING()

Record a timestamped, non-critical error in the RPT log.

Only run if DEBUG_MODE_NORMAL or higher is defined.

Parameters

MESSAGEMessage to record [String]

Example

WARNING("This function has been deprecated. Please don't use it in future!");

Author

Spooner

ERROR()

Record a timestamped, critical error in the RPT log.

The heading is “ERROR” (use ERROR_WITH_TITLE() for a specific title).

TODO: Popup an error dialog & throw an exception.

Parameters

MESSAGEMessage to record [String]

Example

ERROR("Value not found","value of frog not found in config ...yada...yada...");

Author

Spooner

ERROR_WITH_TITLE()

Record a timestamped, 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.

TODO: Popup an error dialog & throw an exception.

Parameters

TITLETitle of error message [String]
MESSAGEBody of error message [String]

Example

ERROR_WITH_TITLE("Value not found","Value of frog not found in config ...yada...yada...");

Author

Spooner

RETNIL()

If a variable is undefined, return the value nil.  Otherwise, return the variable itself.

Parameters

VARIABLEthe variable to check

Example

// _var is undefined
hintSilent format ["_var=%1", RETNIL(_var) ]; // "_var=any"

Author

Alef (see CBA issue #8514)

TRACE_n()

Log a message and 1-8 variables to the RPT log.

Only run if DEBUG_MODE_FULL is defined.

TRACE_1(MESSAGE,A)Log 1 variable.
TRACE_2(MESSAGE,A,B)Log 2 variables.
TRACE_3(MESSAGE,A,B,C)Log 3 variables.
TRACE_4(MESSAGE,A,B,C,D)Log 4 variables.
TRACE_5(MESSAGE,A,B,C,D,E)Log 5 variables.
TRACE_6(MESSAGE,A,B,C,D,E,F)Log 6 variables.
TRACE_7(MESSAGE,A,B,C,D,E,F,G)Log 7 variables.
TRACE_8(MESSAGE,A,B,C,D,E,F,G,H)Log 8 variables.
TRACE_9(MESSAGE,A,B,C,D,E,F,G,H,I)Log 9 variables.

Parameters

MESSAGEMessage to add to the trace [String]
A..HVariable names to log values of [Any]

Example

TRACE_3("After takeoff",_vehicle player,getPos (_vehicle player), getPosASL (_vehicle player));

Author

Spooner

General

INC()

Description

Increase a number by one.

Parameters

VARVariable to increment [Number]

Example

_counter = 0;
INC(_counter);
// _counter => 1

Author

Spooner

DEC()

Description

Decrease a number by one.

Parameters

VARVariable to decrement [Number]

Example

_counter = 99;
DEC(_counter);
// _counter => 98

Author

Spooner

ADD()

Description

Add a value to a variable.  Variable and value should be both Numbers or both Strings.

Parameters

VARVariable to add to [Number or String]
VALUEValue to add [Number or String]

Examples

_counter = 2;
ADD(_counter,3);
// _counter => 5
_str = "hello";
ADD(_str," ");
ADD(_str,"Fred");
// _str => "hello Fred"

Author

Sickboy

SUB()

Description

Subtract a value from a number variable.  VAR and VALUE should both be Numbers.

Parameters

VARVariable to subtract from [Number]
VALUEValue to subtract [Number]

Examples

_numChickens = 2;
SUB(_numChickens,3);
// _numChickens => -1

REM()

Description

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.

Parameters

ARRAYArray to modify [Array]
ELEMENTElement to remove [Any]

Examples

_array = [1, 2, 3, 4, 3, 8];
REM(_array,3);
// _array = [1, 2, 4, 8];

Author

Spooner

PUSH()

Description

Appends a single value onto the end of an ARRAY.  Change is made to the ARRAY itself, not creating a new array.

Parameters

ARRAYArray to push element onto [Array]
ELEMENTElement to push [Any]

Examples

_fish = ["blue", "green", "smelly"];
PUSH(_fish,"monkey-flavoured");
// _fish => ["blue", "green", "smelly", "monkey-flavoured"]

Author

Spooner

ISNILS()

Description

Sets a variable with a value, but only if it is undefined.

Parameters

VARIABLEVariable to set [Any, not nil]
DEFAULT_VALUEValue to set VARIABLE to if it is undefined [Any, not nil]

Examples

// _fish is undefined
ISNILS(_fish,0);
// _fish => 0
_fish = 12;
// ...later...
ISNILS(_fish,0);
// _fish => 12

Author

Sickboy

GVAR()

Get full variable identifier for a global variable owned by this component.

Parameters

VARIABLEPartial name of global variable owned by this component [Any].

Example

GVAR(frog) = 12;
// In SPON_FrogDancing component, equivalent to SPON_FrogDancing_frog = 12

Author

Sickboy

GVARMAIN()

Get full variable identifier for a global variable owned by this addon.

Parameters

VARIABLEPartial name of global variable owned by this addon [Any].

Example

GVARMAIN(frog) = 12;
// In SPON_FrogDancing component, equivalent to SPON_frog = 12

Author

Sickboy

ARG_#()

Select from list of array arguments

Parameters

VARIABLE(1-8)elements for the list

Author

Rommel

ARR_#()

Create list from arguments.  Useful for working around , in macro parameters.  1-8 arguments possible.

Parameters

VARIABLE(1-8)elements for the list

Author

Nou

FORMAT_#(STR, ARG1)

FormatUseful for working around , in macro parameters.  1-8 arguments possible.

Parameters

STRINGstring used by format
VARIABLE(1-8)elements for usage in format

Author

Nou & Sickboy

IS_x()

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.

Parameters

VARIABLEVariable to check if it is of a particular type [Any, not nil]

Author

Spooner

SCRIPT()

Sets name of script (relies on PREFIX and COMPONENT values being #defined).

Parameters

NAMEName of script [Indentifier]

Example

SCRIPT(eradicateMuppets);

Author

Spooner

EXPLODE_n()

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.

EXPLODE_1(ARRAY,A,B)Split a 1-element array into separate variable.
EXPLODE_2(ARRAY,A,B)Split a 2-element array into separate variables.
EXPLODE_3(ARRAY,A,B,C)Split a 3-element array into separate variables.
EXPLODE_4(ARRAY,A,B,C,D)Split a 4-element array into separate variables.
EXPLODE_5(ARRAY,A,B,C,D,E)Split a 5-element array into separate variables.
EXPLODE_6(ARRAY,A,B,C,D,E,F)Split a 6-element array into separate variables.
EXPLODE_7(ARRAY,A,B,C,D,E,F,G)Split a 7-element array into separate variables.
EXPLODE_8(ARRAY,A,B,C,D,E,F,G,H)Split a 8-element array into separate variables.
EXPLODE_9(ARRAY,A,B,C,D,E,F,G,H,I)Split a 9-element array into separate variables.

Parameters

ARRAYArray to read from [Array]
A..HNames of variables to set from array [Identifier]

Example

_array = ["fred", 156.8, 120.9];
EXPLODE_3(_array,_name_height,_weight);

Author

Spooner

Managing Function Parameters

PARAMS_n()

Setting variables based on parameters passed to a function.

Each parameter is defines as private and set to the appropriate value from _this.

PARAMS_1(A)Get 1 parameter from the _this array (or _this if it’s not an array).
PARAMS_2(A,B)Get 2 parameters from the _this array.
PARAMS_3(A,B,C)Get 3 parameters from the _this array.
PARAMS_4(A,B,C,D)Get 4 parameters from the _this array.
PARAMS_5(A,B,C,D,E)Get 5 parameters from the _this array.
PARAMS_6(A,B,C,D,E,F)Get 6 parameters from the _this array.
PARAMS_7(A,B,C,D,E,F,G)Get 7 parameters from the _this array.
PARAMS_8(A,B,C,D,E,F,G,H)Get 8 parameters from the _this array.

Parameters

A..HName of variable to read from _this [Identifier]

Example

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...
};

Author

Spooner

DEFAULT_PARAM()

Getting a default function parameter.  This may be used together with PARAMS_n() to have a mix of required and optional parameters.

Parameters

INDEXIndex of parameter in _this [Integer, 0+]
NAMEName of the variable to set [Identifier]
DEF_VALUEDefault value to use in case the array is too short or the value at INDEX is nil [Any]

Example

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...
};

Author

Spooner

KEY_PARAM()

Get value from key in _this list, return default when key is not included in list.

Parameters

KEYKey name [String]
NAMEName of the variable to set [Identifier]
DEF_VALUEDefault value to use in case key not found [ANY]

Example

Author

Muzzleflash

Assertions

ASSERT_TRUE()

Asserts that a CONDITION is true.  When an assertion fails, an error is raised with the given MESSAGE.

Parameters

CONDITIONCondition to assert as true [Boolean]
MESSSAGEMessage to display if (A OPERATOR B) is false [String]

Example

ASSERT_TRUE(_frogIsDead,"The frog is alive");

Author

Spooner

ASSERT_FALSE()

Asserts that a CONDITION is false.  When an assertion fails, an error is raised with the given MESSAGE.

Parameters

CONDITIONCondition to assert as false [Boolean]
MESSSAGEMessage to display if (A OPERATOR B) is true [String]

Example

ASSERT_FALSE(_frogIsDead,"The frog died");

Author

Spooner

ASSERT_OP()

Asserts that (A OPERATOR B) is true.  When an assertion fails, an error is raised with the given MESSAGE.

Parameters

AFirst value [Any]
OPERATORBinary operator to use [Operator]
BSecond value [Any]
MESSSAGEMessage to display if (A OPERATOR B) is false.  [String]

Example

ASSERT_OP(_fish,>,5,"Too few fish!");

Author

Spooner

ASSERT_DEFINED()

Asserts that a VARIABLE is defined.  When an assertion fails, an error is raised with the given MESSAGE..

Parameters

VARIABLEVariable to test if defined [String or Function].
MESSAGEMessage to display if variable is undefined [String].

Examples

ASSERT_DEFINED("_anUndefinedVar","Too few fish!");
ASSERT_DEFINED({ obj getVariable "anUndefinedVar" },"Too many fish!");

Author

Spooner

Managing Deprecation

DEPRECATE_SYS()

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.

Parameters

OLD_FUNCTIONFull name of old function [Identifier for function that does not exist any more]
NEW_FUNCTIONFull name of new function [Function]

Example

// After renaming CBA_fnc_frog as CBA_fnc_fish
DEPRECATE_SYS(CBA_fnc_frog,CBA_fnc_fish);

Author

Sickboy

DEPRECATE()

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.

Parameters

OLD_FUNCTIONName of old function, assuming PREFIX [Identifier for function that does not exist any more]
NEW_FUNCTIONName of new function, assuming PREFIX [Function]

Example

// After renaming CBA_fnc_frog as CBA_fnc_fish
DEPRECATE(fnc_frog,fnc_fish);

Author

Sickboy

OBSOLETE_SYS()

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.

Parameters

OLD_FUNCTIONFull name of old function [Identifier for function that does not exist any more]
COMMAND_CODECode to replace the old function [Function]

Example

// In Arma2, currentWeapon command made the CBA_fMyWeapon function obsolete:
OBSOLETE_SYS(CBA_fMyWeapon,{ currentWeapon player });

Author

Spooner

OBSOLETE()

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.

Parameters

OLD_FUNCTIONName of old function, assuming PREFIX [Identifier for function that does not exist any more]
COMMAND_CODECode to replace the old function [Function]

Example

// In Arma2, currentWeapon command made the CBA_fMyWeapon function obsolete:
OBSOLETE(fMyWeapon,{ currentWeapon player });

Author

Spooner

Log a message and 1-8 variables to the RPT log.
Log a timestamped message into the RPT log.
Record a timestamped, critical error in the RPT log.
Record a timestamped, critical error in the RPT log.
Full debugging output.
All debugging except TRACE_n() and LOG() (Default setting if none specified).
Boolean
Code block (i.e a compiled function)
Floating point number.
Setting variables based on parameters passed to a function.
Close