So, for example, even if you do two requires in a row:
require("foo.lua");
require("foo.lua"); -- 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 as long as you put the .lua file into your project's Scripts folder, you don't even have to provide a full path to the file. For example:
require("MyScript.lua");
...is the same as:
require(_SourceFolder.."\\AutoPlay\\Scripts\\MyScript.lua");
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
Ac t ion s
AutoPlay Media Studio 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.
D e b u gg i n g Y o u r S c r i p t s
Debugging Your Scripts
Scripting (or any kind of programming) is relatively easy once you get used to it. However, even the best programmers make mistakes, and need to iron the occasional wrinkle out of their code. Being good at debugging scripts will reduce the time to market for your projects and increase the amount of sleep you get at night. Please read this section for tips on using Auto Play Media Studio as smartly and effectively as possible!
This section will explain AutoPlay Media Studio's error handling methods as well as cover a number of debugging techniques.
E rr o r Ha ndling
All of the built-in AutoPlay Media Studio actions use the same basic error handling techniques. However, this is not necessarily true of any third-party functions, modules, or scripts-even scripts developed by Indigo Rose Corporation that are not built into the product. Although these externally developed scripts can certainly make use of AutoPlay's error handling system, they may not necessarily do so. Therefore, you should always consult a script or module's author or documentation in order to find out how error handling is, well, handled.
There are two kinds of errors that you can have in your scripts when calling AutoPlay Media Studio actions: syntax errors, and functional errors.
S y n t ax E rr o r s
Syntax errors occur when the syntax (or "grammar") of a script is incorrect, or a function receives arguments that are not appropriate. Some syntax errors are caught by AutoPlay Media Studio when you build or preview your application.
For example, consider the following script:
foo =
This is incorrect because we have not assigned anything to the variable foo-the script is incomplete. This is a pretty obvious syntax error, and would be caught by the scripting engine at build time (when you build your project).
Another type of syntax error is when you do not pass the correct type or number of arguments to a function. For example, if you try and run this script:
Dialog.Message("Hi There");
...the project will build fine, because there are no obvious syntax errors in the script. As far as the scripting engine can tell, the function call is well formed. The name is valid, the open and closed parentheses match, the quotes are in the right places, and there's even a terminating semi-colon at the end. Looks good!
However, at run time you would see something like the following:
Looks like it wasn't so good after all. Note that the message says two arguments are required for the Dialog.Message function. Ah. Our script only provided one argument.
According to the function prototype for Dialog.Message, it looks like the function can actually accept up to five arguments:
Looking closely at the function prototype, we see that the last three arguments have default values which will be used if those arguments are omitted from the function call. The first two arguments-Title and Text-don't have default values, so they cannot be omitted without generating an error. To make a long story short, it's okay to call the Dialog.Message action with anywhere from 2 to 5 arguments...but 1 argument isn't enough.
Fortunately, syntax errors like these are usually caught at build time or when you test your application. The error messages are usually quite clear, making it easy for you to locate and identify the problem.
Fun c t ion a l E rr o r s
Functional errors are those that occur because the functionality of the action itself fails. They occur when an action is given incorrect information, such as the path to a file that doesn't exist. For example, the following code will produce a functional error:
filecontents = TextFile.ReadToString("this_file_don't exist.txt");
If you put that script into an event right now and try it, you will see that nothing appears to happen. This is because AutoPlay Media Studio's functional errors are not automatically displayed the way syntax errors are. We leave it up to you to handle (or to not handle) such functional errors yourself.
The reason for this is that there may be times when you don't care if a function fails. In fact, you may expect it to. For example, the following code tries to remove a folder called C:\My Temp Folder:
Folder.Delete("C:\\My Temp Folder");
However, in this case you don't care if it really gets deleted, or if the folder didn't exist in the first place. You just want to make sure that if that particular folder exists, it will be removed. If the
folder isn't there, the Folder.Delete action causes a functional error, because it can't find the folder you told it to delete...but since the end result is exactly what you wanted, you don't need to do anything about it. And you certainly don't want the user to see any error messages.
Conversely, there may be times when it is very important for you to know if an action fails. Say for instance that you want to copy a very important file:
File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");
In this case, you really want to know if it fails and may even want to exit the program or inform the user. This is where the Debug actions come in handy. Read on.
De bug Ac t ion s
AutoPlay Media Studio comes with some very useful functions for debugging your applications. This section will look at a number of them.
Application.GetLastError
This is the most important action to use when trying to find out if a problem has occurred. At run time there is always an internal value that stores the status of the last action that was executed. At the start of an action, this value is set to 0 (the number zero). This means that everything is OK. If a functional error occurs inside the action, the value is changed to some non-zero value instead.
This last error value can be accessed at any time by using the Application.GetLastError action. The syntax is:
last_error_code = Application.GetLastError(); Here is an example that uses this action:
File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");
error_code = Application.GetLastError(); if (error_code ~= 0) then
-- some kind of error has occurred! Dialog.Message("Error", "File copy error: "..error_code); Application.Exit();
end
The above script will inform the user that an error occurred and then exit the application. This is not necessarily how all errors should be handled, but it illustrates the point. You can do anything you want when an error occurs, like calling a different function or anything else you can dream up.
The above script has one possible problem. Imagine the user seeing a message like this:
It would be much nicer to actually tell them some information about the exact problem. Well, you are in luck! At run time there is a table called _tblErrorMessages that contains all of the possible error messages, indexed by the error codes. You can easily use the last error number to get an actual error message that will make more sense to the user than a number like "1182."
For example, here is a modified script to show the actual error string:
File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");
error_code = Application.GetLastError(); if (error_code ~= 0) then
-- some kind of error has occurred! Dialog.Message("Error", "File copy error: " ..
_tblErrorMessages[error_code]);
end
Application.Exit();
Now the script will produce the following error message:
Much better information!
Just remember that the value of the last error gets reset every time an action is executed. For example, the following script would not produce an error message:
File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");
-- At this point Application.GetLastError() could be non-zero, but... Dialog.Message("Hi There","Hello World");
-- Oops, now the last error number will be for the Dialog.Message action,
-- and not the File.Copy action. The Dialog.Message action will reset the
-- last error number to 0, and the following lines will not catch any
-- error that happened in the File.Copy action. error_code = Application.GetLastError();
if (error_code ~= 0) then
-- some kind of error has occurred! Dialog.Message("Error",
"File copy error: "..
_tblErrorMessages[error_code]); Application.Exit();
end
Debug.ShowWindow
The AutoPlay Media Studio runtime has the ability to show a debug window that can be used to display debug messages. This window exists throughout the execution of your application, but is only visible when you tell it to be.
The syntax is:
Debug.ShowWindow(show_window);