ArmA 3 Alpha: TL_fnc_getParameter, a function for easily handling required and optional parameters in your scripts

Overview

I recently wanted to start customizing the gear my player was wearing in ArmA 3. In order to do that, I would first need to remove the default gear that my player started out with. I started writing a function to remove the default gear, when I decided I wanted to be able to specify which gear would be removed. With options, I could reuse the function in multiple missions to customize any unit’s gear depending on the situation.

I had never dealt with optional parameters in my functions before, and by default, .sqf functions don’t have a way to handle optional parameters nor do they assign a default value if the parameter isn’t provided. I wanted to quickly check for an optional parameter, but also didn’t want to code multiple parameter checks for every function I wrote.

The result is TL_fnc_getParameter. An easy way to handle required and optional parameters in any script.

Stop wasting time writing if-statements

If your function was passed an array of arguments, you have access to a magic variable named _this. _this is an array that contains all of the parameters that were passed to your script.

When I first started checking which parameters had been passed in _this, I started writing if-statements. I soon realized that the more optional parameters I wanted, the more time I was spending writing if-statements. I also began to think of what would happen if the parameter was passed, but wasn’t the data type that I expected it to be. I wanted the script to fail gracefully, which meant falling back on default values. This lead to writing more if-statements to check for those conditions.

I found this method caused me to spend more time writing supporting code, rather than the actual features of my project. I didn’t want to do this for every script I was going to create that used required or optional parameters.

Code faster with TL_fnc_getParameter

To include TL_fnc_getParameter in your scripts, use:

In it’s most basic form, TL_fnc_getParameter can quickly check if a single parameter was passed to your script. If it wasn’t passed, Nil will be returned. This allows for an easy check to see if the parameter exists or not. You can then fail gracefully with a debug message rather than a code error.

You can easily check for multiple parameters by passing the index as the second argument.

The third argument specifies the expected data type of the parameter if it exists. The parameter must match the data type in order to be returned. If it doesn’t match, then Null will be returned if no default value is specified as the fourth argument.

Visit the biki for a list of acceptable data types.

When setting the fourth argument, you can create optional parameters. If the parameter wasn’t passed, then the default value will be returned. In the example below, false will be returned if parameter 1 was not passed to the script.

Debugging

To quickly determine which value is being returned from TL_fnc_getParameter, you can pass true as the fifth argument. When debugging is enabled, messages will be displayed indicating which value has been returned.

Here are some screenshots of example debug messages:

TL_fnc_removeGear. A real-world example.

In the overview, I mentioned that I was creating a gear removal function. The function is called TL_fnc_removeGear, and it implements required and optional parameters by using TL_fnc_getParameter. This provides a real-world example of how this function can be useful for your scripts.

Read more about TL_fnc_removeGear and it’s use of TL_fnc_getParameter.

TL_fnc_getParameter.sqf

At the time of writing this, I have only tested this script with the TL_fnc_removeGear example. When implementing into your own scripts, if you experience any problems or errors, please leave a comment or send me an email with a way to replicate the problem. I will attempt to fix any problems the script has, and will update it if I develop it further.

I hope this function helps with your scripting, and please leave feedback if you think this script can be improved.

Download

Changelog

April 5, 2013 – Version 1.2

• Instead of returning objNull, nil is now returned.
• Known Issue: isNull check only works for Objects, Controls, Displays, Groups, Locations, Tasks, Team Members. Using isNull to check for the objNull default value when expecting a string, results in an error. A work around is to set the default value to an empty string and use if(_param == “”) exitWith
  • Using if(isNil “_param”) should effectively check if a parameter has been passed regardless of type.
• More accurate debug messages
• If no parameters are passed, a debug message is displayed regardless of debug mode

April 3, 2013 – Version 1.1

• Various bug fixes
• More accurate checking if array doesn’t exist
• Known Issue: isNull check only works for Objects, Controls, Displays, Groups, Locations, Tasks, Team Members. Using isNull to check for the objNull default value when expecting a string, results in an error. A work around is to set the default value to an empty string and use if(_param == “”) exitWith