Tutorial 02: Scripting

Although scripting is usually an advanced topic, the way mortic handles Python scripts makes it remarkably easy. This tutorial will show you the basics of using scripts in your code. Unlike the previous tutorials, this article will not show you any complete programs. Rather, it will show you how to use the Script Manager and explain code fragments.

Introduction to the Script Manager

The script manager is a class that can be accessed through the root. It provides an interface to all of the code that handles Python scripts.

mortic::IScriptManager* sm = root->getScriptManager();

Once you have the script manager, you can create individual scripts through two functions. One creates a Python script from a string:

mortic::IScript* s = sm->createScriptFromString("def print_hello():\n\tprint \"Hello!\"\n");

Another function creates a script from a file. It loads the entire file into memory, and then creates the script from the contents:

mortic::IScript* s = sm->createScript("/print_hello.py");

How to Use Script Objects

Once you have an object representing your script, there are a few functions you should know. The first, and simplest, is runSimpleString():

s->runSimpleString("print_hello()\n");

This function is, as it's name implies, very simple. It merely runs the code given inside the script. In this case, it calls the function "print_hello".

Another function that is almost as simple is variableExists():

if (s->variableExists("someVar")) ...

This function returns true if the variable named exists inside the script.

callFunction()

Now, these functions are useful in their own right, but are useless if you want to transfer variables back and forth between C++ and Python. This is where callFunction() comes in. This simple-to-use function makes it easy to call Python functions almost like you do C++ functions. Let's see an example usage:

s->callFunction("print_hello", "");

This example does the same thing as the runSimpleString() example above. What's the big deal, right? Look closely at the next example:

s->callFunction("printVars", "i", 42);

Let's assume that printVars() is a simple Python function that prints out each of it's arguments on it's own line. This could be written in python as:

def printVars(*args):
        for i in args:
                print i

So, the example above would print out 42. Let's look closer at this function. The first argument is the name of the function to call. This much is obvious. However, the rest of the arguments work a bit like the C function printf(). The second argument is the format string. Every letter in this string corresponds to an argument. If the letter is "i", it's an integer. If it's "b", it's a boolean. Finally, if it's a "f", it's a float. Now, let's test something...

s->callFunction("printVars", "bif", true, 42, 13.37);

The above function prints out False, 42, and 13.37 on seperate lines. Easy, right? Well, what about passing objects? Lets try it...

s->callFunction("printVars", "b<FileManager>if", true, root->getFileManager(), 42, 13.37);

The filemanager comes out on the other side, with methods intact! You can use it like you would in C++, but with the power of Python! Easy!

---