Other Built-in Functions

Script Functions

There are three other built-in functions that may prove useful to you: dofile, require, and type.

dofile

Loads and executes a script file. The contents of the file will be executed as though it was typed directly into the script. The syntax is:

dofile(file_path);

For example, say we typed the following script into a file called MyScript.lua (just a text file containing this script, created with notepad or some other text editor):

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

Now we include the file as a primer file in our installation.

Now, wherever we add the following line of script to an event:

dofile(SessionVar.Expand("%TempLaunchFolder%\\MyScript.lua"));

...that script file will be read in and executed immediately. In this case, you would see a message box with the friendly �hello world� message.

Note: The SessionVar.Expand action is used to retrieve the primer file path from the session variable %TempLaunchFolder%. Actions will be discussed later.

Tip: Use the dofile function to save yourself from having to re-type or re-paste a script into your projects over and over again.

require

Loads and runs a script file into the scripting engine. It is similar to dofile except that it will only load a given file once per session, whereas dofile will re-load and re-run the file each time it is used. The syntax is:

require(file_path);

If the file is a primer file located in %TempLaunchFolder%, you should not include the file extension.

So, for example, even if you do two requires in a row:

require("MyScript");
require("MyScript"); -- this line won't do anything

...only the first one will ever get executed. After that, the scripting engine knows that the file has been loaded and run, and future calls to require that file will have no effect.

Note that when using require the file must be extracted to %TempLaunchFolder% (from a primer file) and should not contain a path.

Since require will only load a given script file once per session, it is best suited for loading scripts that contain only variables and functions. Since variables and functions are global by default, you only need to �load� them once; repeatedly loading the same function definition would just be a waste of time.

This makes the require function a great way to load external script libraries. Every script that needs a function from an external file can safely require() it, and the file will only actually be loaded the first time it�s needed.

type

This function will tell you the type of value contained in a variable. It returns the string name of the variable type. Valid return values are �nil,� �number,� �string,� �boolean,� �table,� �function, � "thread," and "userdata." For example:

a = 989;
strType = type(a);  -- sets strType to "number"

a = "Hi there";
strType = type(a);  -- sets strType to "string"

The type function is especially useful when writing your own functions that need certain data types in order to operate. For example, the following function uses type() to make sure that both of its arguments are numbers:

-- find the maximum of two numbers
function Max(Number1, Number2)

     -- make sure both arguments are numeric
     if (type(Number1) ~= "number") or (type(Number2) ~= "number") then
         Dialog.Message("Error", "Please enter numbers");
         return nil -- we're using nil to indicate an error condition
     else
         if Number1 >= Number2 then
             return Number1;
         else
             return Number2;
         end
     end
end

Actions

Setup Factory comes with a large number of built-in functions. In the program interface, these built-in functions are commonly referred to as actions. For scripting purposes, actions and functions are essentially the same; however, the term �actions� is generally reserved for those functions that are built into the program and are included in the alphabetical list of actions in the online help. When referring to functions that have been created by other users or yourself, the term �functions� is preferred.