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_*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.

Debugging

DEBUG_MODE_*

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_* (Default setting if none specified).
DEBUG_MODE_MINIMALOnly ERROR(MESSAGE) and ERROR_WITH_TITLE(TITLE,MESSAGE) 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"

LOG(MESSAGE)

Log a timestamped message into the RPT log.

Only run if DEBUG_MODE_NORMAL or higher is defined.

WARNING(MESSAGE)

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

Only run if DEBUG_MODE_NORMAL or higher is defined.

ERROR(MESSAGE)

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.

ERROR_WITH_TITLE(TITLE,MESSAGE)

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.

TRACE_*

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.

Example

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

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.  Shows a warning in RPT each time the obsolete function it is used.

Example

OBSOLETE(fMyWeapon,{ currentWeapon player });

IS_*

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.

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

Note that this does not make the created variables private.

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.

Example

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

Managing Function Parameters

PARAMS_*

Setting variables based on parameters passed to a function.

PARAMS_1(A)Get 1 parameter from the _this 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.

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

DEFAULT_PARAM(INDEX,NAME,DEF_VALUE)

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

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

Assertions

ASSERT_TRUE(CONDITION,MESSAGE)

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

Example

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

ASSERT_FALSE(CONDITION,MESSAGE)

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

Example

ASSERT_FALSE(_frogIsDead,"The frog died");

ASSERT_OP(A,OPERATOR,B,MESSAGE)

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

Example

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

ASSERT_DEFINED(VARIABLE,MESSAGE)

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

Examples

ASSERT_DEFINED("_anUndefinedVar","Too few fish!");
ASSERT_DEFINED({ obj getVariable "anUndefinedVar" },"Too many fish!");
Log a message and 1-8 variables to the RPT log.
Record a timestamped, critical error in the RPT log.
Record a timestamped, critical error in the RPT log.
All debugging except TRACE_* (Default setting if none specified).
Full debugging output.
Boolean
Code block (i.e a compiled function)
Floating point number.
Setting variables based on parameters passed to a function.
Close