ARGUMENTS


Many programmers use the terms "argument" and "parameter" as synonyms. It is so common that it is generally accepted even though it often leads to confusion or misunderstanding. It is important therefore to know the difference between these two terms and be able to communicate about functions accurately.


Parameters

A parameter (often shortened to "param") is any data that your function is expecting to receive. You name the parameters in the parentheses when creating your function. These will then become local variables within the function, holding the values that are passed to the function.

function f( param1, param2 ) --set function and params
Arguments

An argument (often shortened to "arg") is any data that you pass to your function. You place arguments inside of the parentheses when you call the function to run. 

f( arg1, arg2 )  --call function, pass args

Important to Remember:

- Arguments pass values; Parameters catch and hold them.

- The order of the parameters determines the order of arguments you must follow.


The first function we all learn in any language is how to output text to the screen. In Lua, this is print(). And the very first argument we traditionally learn how to pass is the text, "hello world". Like this:

print("hello world")

Print is the function name.

( ) parentheses hold the arguments.

"hello world" is the first argument, a string.


Passing Multiple Arguments

The print function can take more than one argument, and we can list the arguments inside the parentheses. It is important to know the order that these arguments need to be passed. When you read about how to use pre-built functions ("API") in PICO-8, you'll want to pay attention to the arguments each function needs, found inside the parentheses. For example, here is how we display all of the arguments that the print function can take:

print( string, [x], [y], [color] )

Notice how some arguments have square brackets "[]" around them. This is commonly used in documentation (like this PICO-8 Guide, or the Official Manual) to show optional arguments. So this function will work even if you only pass one argument, the string, which is the only required argument.

Many built-in functions like print() have default values to use if you do not pass explicit values in the optional arguments. For example, the print() function will use the last cursor position that was set to be the default x and y parameters, and the last color that was set to be the default color parameter. For example:

print("h")          --"h" at last cursor and last color
print("e", 5, 3)    --"e" at (5,3) and in last color
print("y", 5, 3, 7) --"y" at (5,3) and in color 7

Sometimes, functions can handle arguments that are given out of order, though this is uncommon. These functions are built specifically to handle the arguments differently based on the number of arguments passed. For example, if print() is given only 2 arguments, it will treat the second argument as the color number, instead of as X. For example:

print("hello", 5) --"hello" at last cursor, in color 5


[ not for beginners ]

Variable Arguments (varargs) ...

Most functions that you will create will have a set number of parameters. But at some point you may want to create a function that is able to recieve a variable amount of arguments. This is called a "variable argument function" or "vararg function". In PICO-8, three dots (...) are used to represent a variable number of arguments that can be passed to a function.

From the Lua Manual:

When a Lua function is called, it adjusts its list of arguments to the length of its list of parameters, unless the function is a vararg function, which is indicated by three dots ('...') at the end of its parameter list. A vararg function does not adjust its argument list; instead, it collects all extra arguments and supplies them to the function through a vararg expression, which is also written as three dots. The value of this expression is a list of all actual extra arguments, similar to a function with multiple results.

Varargs are useful when you want to create a function that can accept a varying number of arguments. For example, let’s say you want to create a function that calculates the sum of any number of values. You could use varargs to achieve this:

function sum(...)
	local args = {...}  --turns varargs list into table
	local sum = 0

	--loop and add each arg
	for i=1, #args do
		sum += args[i]
	end

	return sum
end

Calling this function with varying number of arguments:

sum(1,2)        --3
sum(1,2,3)      --6
sum(1,2,3,4)    --10
sum(1,2,3,4,5)  --15

You could pass this function any number of values, and it will add them all together. In the above example, we first turned the list of varargs (...) into a table with local args = {...}.  You can also handle varargs with the select() function. Let's take the exact same function that creates sums above and rewrite it using select:

function sum(...)
	local sum = 0

	--loop and add each arg
	for i=1, select("#",...) do
		sum += select(i,...)
	end

	return sum
end

Instead of creating a table, we use select("#",...) to get the total number of varargs, then select(i,...) to get the value of each argument out of the varargs list.

526

14 May 2023

Font