By far the coolest and most powerful feature of the scripting engine is functions. You have already seen a lot of functions used throughout this document, such as "Dialog.Message." Functions are simply portions of script that you can define, name and then call from anywhere else.

Although there are a lot of built-in LuaScript functions, you can also make your own custom functions to suit your specific needs. In general, functions are defined as follows:

function function_name (arguments)

    function script here

    return return_value;

end

The first part is the keyword "function." This tells the scripting engine that what follows is a function definition. The function_name is simply a unique name for your function. The arguments are parameters (or values) that will be passed to the function every time it is called. A function can receive any number of arguments from 0 to infinity (well, not infinity, but don't get technical on me). The "return" keyword tells the function to return one or more values back to the script that called it.

The easiest way to learn about functions is to look at some examples. In this first example, we will make a simple function that shows a message box. It does not take any arguments and does not return anything.

function HelloWorld()

   Dialog.Message("Welcome","Hello World");

end

Notice that if you run this script, nothing happens. Well, that is true and not true. It is true that nothing visible happens but the magic is in what you don't see. When the function script is executed, the function called "HelloWorld" becomes part of the scripting engine.

This brings up an important point about scripting in LuaScript. When making a function, the function does not get "into" the engine until the script is executed.

Let’s add a line to actually call the function:

function HelloWorld()

    Dialog.Message("Welcome","Hello World");

end

 

HelloWorld();

The "HelloWorld();"  line tells the scripting engine to "go perform the function named HelloWorld." When that line gets executed, you would see a welcome message with the text "Hello World" in it.

Function Arguments

Let’s take this a bit further and tell the message box which text to display by adding an argument to the function.

function HelloWorld(Message)

   Dialog.Message("Welcome", Message);

end

 

HelloWorld("This is an argument");

Now the message box shows the text that was "passed" to the function.

In the function definition, "Message" is a variable that will automatically receive whatever argument is passed to the function. In the function call, we pass the string "This is an argument" as the first (and only) argument for the HelloWorld function.

Here is an example of using multiple arguments.

function HelloWorld(Title, Message)

   Dialog.Message(Title, Message);

end

 

HelloWorld("This is argument one", "This is argument two");

HelloWorld("Welcome", "Hi there");

This time, the function definition uses two variables, one for each of its two arguments...and each function call passes two strings to the HelloWorld function.

Note that by changing the content of those strings, you can send different arguments to the function, and achieve different results.

Returning Values

The next step is to make the function return values back to the calling script. Here is a function that accepts a number as its single argument, and then returns a string containing all of the numbers from one to that number.

function Count(n)

 

   -- start out with a blank return string

   ReturnString = "";

 

   for num = 1,n do

      -- add the current number (num) to the end of the return string

      ReturnString = ReturnString..num;

 

      -- if this isn't the last number, then add a comma and a space

      -- to separate the numbers a bit in the return string

      if (num ~= n) then

         ReturnString = ReturnString..", ";

      end

   end

 

   -- return the string that we built

   return ReturnString;

end

 

CountString = Count(10);

Dialog.Message("Count", CountString);

The last two lines of the above script uses the Count function to build a string counting from 1 to 10, stores it in a variable named CountString, and then displays the contents of that variable in a dialog message box.

Returning Multiple Values

You can return multiple values from functions as well:

function SortNumbers(Number1, Number2)

  if Number1 <= Number2 then

      return Number1, Number2

  else

      return Number2, Number1

  end

end

 

firstNum, secondNum = SortNumbers(102, 100);

Dialog.Message("Sorted", firstNum ..", ".. secondNum);

The above script creates a function called SortNumbers that takes two arguments and then returns two values. The first value returned is the smaller number, and the second value returned is the larger one. Note that we specified two variables to receive the return values from the function call on the second last line. The last line of the script displays the two numbers in the order they were sorted into by the function.

Redefining Functions

Another interesting thing about functions is that you can override a previous function definition simply by re-defining it.

function HelloWorld()

  Dialog.Message("Message","Hello World");

end

 

function HelloWorld()

  Dialog.Message("Message","Hello Earth");

end

 

HelloWorld();

The script above shows a message box that says "Hello Earth," and not "Hello World." That is because the second version of the HelloWorld() function overrides the first one.

Putting Functions in Tables

One really powerful thing about tables is that they can be used to hold functions as well as other values. This is significant because it allows you to make sure that your functions have unique names and are logically grouped. (This is how all of the LuaScript functions are implemented.) Here is an example:

-- Make the functions:

function HelloEarth()

  Dialog.Message("Message","Hello Earth");

end

 

function HelloMoon()

  Dialog.Message("Message","Hello Moon");

end

 

-- Define an empty table:

Hello = {};

 

-- Assign the functions to the table:

Hello.Earth = HelloEarth;

Hello.Moon = HelloMoon;

 

-- Now call the functions:

Hello.Earth();

Hello.Moon();

It is also interesting to note that you can define functions right in your table definition:

Hello = {

Earth = function () Dialog.Message("Message","Hello Earth") end,

Moon = function () Dialog.Message("Message","Hello Moon") end   };

 

-- Now call the functions:

Hello.Earth();

Hello.Moon();

Learn More: Indigo Rose Software - MSI Factory - Buy Now - Contact Us