How to learn functions?

Introduction

Functions are preserved chunks of code you that you can do almost anything with. You can bind them to events, pass them as arguments, use them for callbacks, the list just goes on.

For now, you should just focus on how to properly create one, and that a function actually is it's own individual data type. A data type is exactly what is sounds like - a type of data.

Just for a quick example of what exactly I mean by "type" of data, here's a list of data types:

string - Any string value(e.g, [[string]], "string", 'string')

number - Any number value (e.g, 1,2,3...)

boolean - Any boolean value (e.g, true, false)

table - Any table value (e.g, { })

function - Any function value (e.g, function() end)

userdata - Any userdata value (e.g, newproxy())

Certain data types on this list including userdata and tables can be a bit tricky to understand if you've just started learning. However, this explanation is about functions, so we'll save that for another time!

How to create a function

Keeping in mind that a function is a value (as explained above), we MUST apply the same rules to it, as we would any other value (with variables!).

If you don't already know, if we wanted to declare a number value of 5 in our script, we can't just type "5". We need to create a variable (or in other words, a key) to hold that value's information. We can do so like this:

-- All valid examples of creating a variable (or key) to represent the number 5

local a = 5
local b = 5
local variable = 5

We do the exact same thing with functions. Here's what plain old function looks like:

function() end -- This is a function value.

This is actually a "special" kind of function, known as an anonymous function. An anonymous function is basically a function, without a variable. Much like just typing "true", or "5" in your script, you could call those anonymous data types if you really wanted to.

Assigning anonymous functions

Now, because anonymous functions are just plain, undefined (no variable) data types, we can't just have them thrown around our script willy nilly. There are very specific times and places to use anonymous functions, but for just creating a function that you want to reference over and over again, we'll need a variable for it. Here's an example:

local example = function() end

Boom, now we have a function value stored inside of our "example" variable. Now what can we do with it?

Calling functions

If you refer back to my opening statement about functions, you'll find: Functions are preserved chunks of code

This means it's code in your script that won't execute, until you tell it to. When you tell it to execute, this process is called calling the function.

This procedure of calling the function is done by placing two parenthesis "()" after something that represents your function value.

---

In our case, our variable named: example represents our function value, so we may call it using the parenthesis. Here's an example:

local example = function() end -- This code is not running

example() -- Now it is!

The most efficient part about functions, is their ability to re-use code, instead of typing it over and over again whenever you need it. Using our example above, and some common sense, you can clearly see that we may call this function wherever, and whenever we want in our script!

local example = function() end

example() -- Running it for the first time
example() -- Running it again!
example() -- Yet again!
example() -- This is all running the same code in the same function!

This is all very exciting, but this is still just a function with nothing to run inside of it. So, how do we do that ... ?

Putting code in your function

Now we're at the peak of understanding why functions are so awesome. Think of a function as a container, and anything between the function keyword, and the end statement is the content of your container, that's executed when the function is called. Here's an example of a function that prints 'hello world' when called:

-- It's a very common (if not always) used format to have your function set up like this. With the variable and function keyword at the beginning, your code in the middle, and your "end" statement (obviously) at the end.

local example = function()
    print("Hello world")
end

A very common mistake that confuses a lot of people, and even eventually causes bugs for advanced scripters / programmers, is forgetting to call your function.

If you ran the code above, you'll see nothing happen in the output window. This is because we never called our function, it's just sitting there, relaxing. Let's make this function actually run by calling it:

local example = function()
    print("Hello world")
end

example() -- Yay, we ran the code inside the function "example".

Now, the function will execute, including all the code after declaring it all the up to it's end statement.

Arguments and parameters?

Something you've probably heard me mention a few times, is the term arguments. What what is and argument?

An argument is a value you can return to the function. That's right, you can actually input information to the function you just created. We can achieve this by giving our function some parameters when we're declaring it.

You can think of parameters as little variables your function has to work with. This is how we'd create a function with some parameters:

-- in this example, "a" is the function's parameter, and this is the variable the code inside the function can use to reference whatever argument was returned to it.

local example = function(a)
    print(a) -- print our parameter's value
end

example() -- run the function

If you run the code above, you'll see a strange little text called nil in the output window. nil is the default value of anything that doesn't exist in your script.

The reason it's printing nil, is because we have that print(a) section. Since we didn't return any arguments to the function, it's parameters will all be nil. Let's try this again, but this time, give our parameter of a, a value.

local example = function(a) -- 'a' will be our "output" value.
    print(a) 
end

example(100) -- Here is where we return the information to the function (our input). In this case, the number '100' is our argument. This is the value that will be passed to the parameter 'a', where we can then use 'a' to represent 100.

-- This code will print 100 in the output window.

So that's how arguments and parameters work. This logic can be applied to as many arguments or parameters as you want, and the process of what argument goes to what parameters, depends on it's position in the input (calling the function):

local example = function(a,b,c) -- 3 parameters
    print(a,b,c)
end

example(1,2,3) -- assigning value '1', to parameter 'a', assigning value '2', to parameter 'b', and assigning value '3' to parameter 'c'

-- In other words:

-- a = 1
-- b = 2
-- c = 3

-- We can only reference these variables INSIDE our function.

Formatting your function?

The way you can "format" your function is pretty flexible. Throughout all these examples you've seen me use the format of variable = function, but there are actually other ways to write them as well. The way you write a function is completely up to you, as long as it's syntactically correct.

Here are some different ways you can write your functions:

Using the function keyword first

-- This is probably the most commonly used format

function example() -- "example" is still a variable
    print("Still works")
end

example() -- we still call it the same way

-- this would be an example of making it local, which you should really consider learning about.
local function example()
    print("Still works")
end

example() -- still the same result

This is all I'm going to cover for the basics of how functions work in this explanation, but if you have any questions just let me know.