Optional Arguments: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(Corrected some facts about the need of providing optional arguments which are before other (maybe OOP did change this?))
 
(4 intermediate revisions by 3 users not shown)
Line 15: Line 15:
Optional argument are used just like normal arguments. The only difference is that they will default to a certain value if no provided (in other words, if optionalArgument == nil then optionalArgument = defaultValue).
Optional argument are used just like normal arguments. The only difference is that they will default to a certain value if no provided (in other words, if optionalArgument == nil then optionalArgument = defaultValue).


One common problem to new scripters is when they want to provide only an optional argument, without setting the ones that are before it. Well, this is really simple to "fix". Normally, you can set them to ''[[nil]]'', so they will default to its corresponding values while you are still able to set the one you really want to. For example, if you want to only set the rotation in Z axis of the [[createVehicle]] function (and don't know that ''rx'' and ''ry'' defualt to zero):
One common problem to new scripters is when they want to provide only an optional argument, without setting the ones that are before it. Well, this is really simple to "fix". Normally, they can be set to ''[[nil]]'', so they will default to its corresponding values while the scripter is still able to set the one he really wants to. For example, if you want to only set the rotation in Z axis of the [[createVehicle]] function (and don't know that ''rx'' and ''ry'' default to zero):


<syntaxhighlight lang="lua">vehicle createVehicle ( int model, float x, float y, float z, [ float rx, float ry, float rz ] )</syntaxhighlight>
<syntaxhighlight lang="lua">vehicle createVehicle ( int model, float x, float y, float z, [ float rx, float ry, float rz ] )</syntaxhighlight>
Line 21: Line 21:
You can use:
You can use:


<syntaxhighlight lang="lua">local myAwensomeVehicle = createVehicle( getVehicleModelFromName( "Infernus" ), 0, 0, 5, nil, nil, 180 )</syntaxhighlight>
<syntaxhighlight lang="lua">local myAwesomeVehicle = createVehicle( getVehicleModelFromName( "Infernus" ), 0, 0, 5, nil, nil, 180 )</syntaxhighlight>


And the result will be an Infernus rotated 180 degrees in the Z axis in the center of the map.
And the result will be an Infernus rotated 180 degrees in the Z axis in the center of the map.
{{Warning|There are some built-in MTA: SA functions that don't follow this convention, especially when some optional argument is closely related to another (e.g. color arguments in DX functions, and probably others): instead of replacing the ''nil'' value, they output a 'bad argument' error and do nothing. '''Always check if this works with a function before using it in a script'''.|1}}
{{Warning|There are some built-in MTA: SA functions that don't follow this convention, especially when an optional argument is closely related to another (e.g. color arguments in DX functions, and probably others): instead of replacing the ''nil'' value, they output a 'bad argument' error and do nothing. '''Always check if this works with a function before using it in a script'''.|1}}
 
==Scripting custom functions with optional arguments==
==Scripting custom functions with optional arguments==
Scripting functions with optional arguments is as easy as using ''if'' statements:
Scripting functions with optional arguments is as easy as using ''if'' statements:
Line 49: Line 50:
end</syntaxhighlight>
end</syntaxhighlight>


[[hu:Optional Arguments]]
[[pl:Argumenty opcjonalne]]
[[pl:Argumenty opcjonalne]]
[[Category:Scripting Concepts]]
[[Category:Scripting Concepts]]
[[ru:Optional Arguments]]
[[ru:Optional Arguments]]
[[de:Optionale Argumente]]
[[de:Optionale Argumente]]

Latest revision as of 16:52, 4 August 2023

Optional arguments are arguments which can be optionally passed to any Lua function, including MTA: SA built-in ones. They are not required for the function to run, and can be unset (value == nil). Often, this kind of arguments do not make a huge difference in the behaviour of the function.

It's a Lua convention that the arguments written between square brackets are optional, so in this Wiki you can find functions with some arguments between square brackets too. That means they are optional and that providing them is not necessary.

Let's take a look at this common function:

vehicle createVehicle ( int model, float x, float y, float z, [ float rx, float ry, float rz ] )

In this example, rx, ry, and rz are optional arguments, because they are between square brackets. They do not need to be provided to the function; it will default to no rotation in every axis. If provided, the function will use the rotations specified instead.

Why are optional arguments used?

More often than not, it's boring having to provide all the arguments of a certain function, especially if they are the same over and over again. The optional arguments allow the scripter to only pass the data that is really needed for his script, and that helps improving code readibility and size.

Use of the optional arguments

Optional argument are used just like normal arguments. The only difference is that they will default to a certain value if no provided (in other words, if optionalArgument == nil then optionalArgument = defaultValue).

One common problem to new scripters is when they want to provide only an optional argument, without setting the ones that are before it. Well, this is really simple to "fix". Normally, they can be set to nil, so they will default to its corresponding values while the scripter is still able to set the one he really wants to. For example, if you want to only set the rotation in Z axis of the createVehicle function (and don't know that rx and ry default to zero):

vehicle createVehicle ( int model, float x, float y, float z, [ float rx, float ry, float rz ] )

You can use:

local myAwesomeVehicle = createVehicle( getVehicleModelFromName( "Infernus" ), 0, 0, 5, nil, nil, 180 )

And the result will be an Infernus rotated 180 degrees in the Z axis in the center of the map.

Dialog-warning.png Warning: There are some built-in MTA: SA functions that don't follow this convention, especially when an optional argument is closely related to another (e.g. color arguments in DX functions, and probably others): instead of replacing the nil value, they output a 'bad argument' error and do nothing. Always check if this works with a function before using it in a script.

Scripting custom functions with optional arguments

Scripting functions with optional arguments is as easy as using if statements:

function aNotSoUsefulFunction( text )
    if type( text ) == "string" or type( text ) == "nil" then -- Check if correct arguments have been provided
        local realTextToOutput
        if text == nil then
            realTextToOutput = "I <3 optional arguments" -- If the text is nil (not specified), use a default one
        else
            realTextToOutput = text -- Use the text that the user specified if defined
        end
        outputChatBox( realTextToOutput ) -- Output the text
    end
end

You can also use short-circuit evaluation, if you prefer to:

function aNotSoUsefulFunction( text )
    local realTextToOutput = ( type( text ) == "string" or type( text ) == "nil" ) and ( type( text ) == "string" and text or "I <3 optional arguments" ) or nil
    if realTextToOutput then -- Check if there is something to output
        outputChatBox( realTextToOutput ) -- Output the text
    end
end