Optional Arguments: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
 
(19 intermediate revisions by 13 users not shown)
Line 1: Line 1:
[[Optional Arguments]] are arguments that are sent to a command but are not required for the command to run.
'''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.


When loolking at the Syntax for an argument, Optional arguments are always enclosed in Square brackets
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.


Example:
Let's take a look at this common function:


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


In this example, '''rx''', '''ry''', and '''rz''' are [[Optional Arguments]].
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.


==Using Optional Arguments==
==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.


[[Optional Arguments]] have one limitation. You cannot use any optional arguments unless ''all previous arguments are also supplied.''
==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).


This means that in the previous example, if you wanted to supply '''rz''', you would also need to supply '''rx''', and '''ry''' ''in order.''
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>
 
You can use:
 
<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.
{{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 functions with optional arguments is as easy as using ''if'' statements:
 
<syntaxhighlight lang="lua">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</syntaxhighlight>
 
You can also use [http://en.wikipedia.org/wiki/Short-circuit_evaluation short-circuit evaluation], if you prefer to:
 
<syntaxhighlight lang="lua">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</syntaxhighlight>
 
[[hu:Optional Arguments]]
[[pl:Argumenty opcjonalne]]
[[Category:Scripting Concepts]]
[[ru:Optional Arguments]]
[[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