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. |
Debugging | |
DEBUG_MODE_* | Managing debugging based on debug level. |
LOG(MESSAGE) | Log a timestamped message into the RPT log. |
WARNING(MESSAGE) | Record a timestamped, non-critical error in the RPT log. |
ERROR(MESSAGE) | Record a timestamped, critical error in the RPT log. |
ERROR_WITH_TITLE(TITLE,MESSAGE) | Record a timestamped, critical error in the RPT log. |
TRACE_* | Log a message and 1-8 variables to the RPT log. |
General | |
OBSOLETE(OLD_FUNCTION,COMMAND_FUNCTION) | Replace an obsolete OLD_FUNCTION (which will have PREFIX_ prepended) with a simple COMMAND_FUNCTION, with the intention that it will be replaced ASAP. |
IS_* | Checking the data types of variables. |
SCRIPT(NAME) | Sets name of script (relies on PREFIX and COMPONENT values being #defined). |
EXPLODE_* | Splitting an ARRAY into a number of variables (A, B, C, etc). |
Managing Function Parameters | |
PARAMS_* | Setting variables based on parameters passed to a function. |
DEFAULT_PARAM(INDEX,NAME,DEF_VALUE) | Getting a default function parameter. |
Assertions | |
ASSERT_TRUE(CONDITION,MESSAGE) | Asserts that a CONDITION if true. |
ASSERT_FALSE(CONDITION,MESSAGE) | Asserts that a CONDITION if false. |
ASSERT_OP(A,OPERATOR,B,MESSAGE) | Asserts that (A OPERATOR B) is true. |
ASSERT_DEFINED(VARIABLE,MESSAGE) | Asserts that a VARIABLE is defined. |
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_* (Default setting if none specified). |
DEBUG_MODE_MINIMAL | Only ERROR(MESSAGE) and ERROR_WITH_TITLE(TITLE,MESSAGE) 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"
Log a timestamped message into the RPT log.
Only run if DEBUG_MODE_NORMAL or higher is defined.
Record a timestamped, non-critical error in the RPT log.
Only run if DEBUG_MODE_NORMAL or higher is defined.
Record a timestamped, critical error in the RPT log. The heading is ERROR (use ERROR_WITH_TITLE(TITLE,MESSAGE) for a specific title. Newlines (\n) in the MESSAGE will be put on separate lines.
TODO: Popup an error dialog & throw an exception.
Record a timestamped, critical error in the RPT log. The title can be specified (in ERROR(MESSAGE) 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.
Log a message and 1-8 variables to the RPT log.
Only run if DEBUG_MODE_FULL is defined.
TRACE_3("After takeoff",_vehicle player,getPos (_vehicle player), getPosASL (_vehicle player));
Replace an obsolete OLD_FUNCTION (which will have PREFIX_ prepended) with a simple COMMAND_FUNCTION, with the intention that it will be replaced ASAP. Shows a warning in RPT each time the obsolete function it is used.
OBSOLETE(fMyWeapon,{ currentWeapon player });
Checking the data types of variables.
IS_ARRAY(VAR) | Array |
IS_BOOL(VAR) | Boolean |
IS_BOOLEAN(VAR) | UI display handle(synonym for IS_BOOL(VAR)) |
IS_CODE(VAR) | Code block (i.e a compiled function) |
IS_CONFIG(VAR) | Configuration |
IS_CONTROL(VAR) | UI control handle. |
IS_DISPLAY(VAR) | UI display handle. |
IS_FUNCTION(VAR) | A compiled function (synonym for IS_CODE(VAR)) |
IS_GROUP(VAR) | Group. |
IS_INTEGER(VAR) | Is a number a whole number? |
IS_LOCATION(VAR) | World location. |
IS_NUMBER(VAR) | A floating point number (synonym for IS_SCALAR(VAR)) |
IS_OBJECT(VAR) | World object. |
IS_SCALAR(VAR) | Floating point number. |
IS_SCRIPT(VAR) | A script handle (as returned by execVM and spawn commands). |
IS_SIDE(VAR) | Game side. |
IS_STRING(VAR) | World object. |
IS_TEXT(VAR) | Structured text. |
Splitting an ARRAY into a number of variables (A, B, C, etc).
Note that this does not make the created variables private.
_array = ["fred", 156.8, 120.9]; EXPLODE_3(_array,_name_height,_weight);
Setting variables based on parameters passed to a function.
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... };
Getting a default function parameter. This may be used together with PARAMS_* to have a mix of required and optional parameters.
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... };