Phantom Documentation

[Help Home] [Phantom Home]
User Functions Tutorial

This tutorial describes how to create and use user-defined functions. User defined functions are Phantom statements grouped together so they can be called by a function name. User defined functions can accept parameters and return variables, and are called like any other 'internal' function.

Start by creating an ASCII text file that will contain the script as described in the Hello World tutorial. Save the script as "UserFunctions.psc".

In the first section, a simple user-defined function will be created. The function will be called 'SampleFunction', and its only job will be to return an integer with the value of '10'. Note that this will only declare that the function exists and define what the function does. The function will not actually do anything until it is called later in the tutorial.

The function is declared using the 'function' keyword, followed by the return type of the function (in this case 'int'), followed by the function name. After the function name, the parameter list is contained in parentheses. This function accepts no parameters, so no parameters are in the parentheses.

The statements within the braces ({}) are the function statements. It is these statements that are processed by Phantom whenever the function is called. This is a simple function, and only declares a variable (an int), gives it a value (10), and returns it. The return statement is used to pass the variable 'i' back to the calling statement. The return type must match the type in the declaration header (after the function keyword). If no variable is returned, the return statement can be used without a parameter, and the return type is 'void'. The ending brace (}) marks the end of the function.

Note that the variable 'i' declared inside the function is only available in the function (in other words, its 'scope' is only in the function). Once the function exits, the variable 'i' is destroyed.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}


The next section will declare another user-defined function. This function returns nothing and so has a return type of 'void'. The name of this second function is 'SampleFunction2', and it accepts two parameters: an int and a string. The int parameter will have the name 'i', and the string parameter will have the name 's'. These are the names they will be referred to in the function, however a variable with any name can be passed to the function when it is called, as long as it is of the correct type.

Note that this function could also have been called 'SampleFunction' like the first function. Phantom allows for multiple functions with the same name, as long as the parameter lists are different.

This function will simply display the values of the input parameters. It will also display the value of an as yet undefined global variable. Phantom functions can access global variables (that is, variables declared outside a function). The variable 'r' will be declared globally later, before this function is called. Notice how the parameter int and the global real must be converted to a string using the string function. This is because the string concatenation operator (+) requires two strings.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

# Declare a function with parameters,
# and that accesses a global variable.
# Set the return type to 'void' to
# indicate nothing is returned.
function void SampleFunction2(int i, string s){
  disp("Integer entered: " + string(i));
  disp("String entered: " + s);
  disp("Global real: " + string(r));
}


As with the first function, no actions have actually been performed. The functions have only been declared and defined. They wont perform any actions until they are called.

The next section of code uses the what function to see what function packages are available. The what function, without a parameter, will display the available package names on the screen. This is most often used in Console mode, but is used here for illustration purposes. One of the packages that will be listed will be the "User Defined" package. This is the package that will contain the functions just created (to use other package names, see the package keyword). To see that the functions have been declared correctly, the parameter "User Defined" will be passed to the what function. This will display all user defined functions (not in another package) to the screen. This will include the function name, return type, and parameter types.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

# Declare a function with parameters,
# and that accesses a global variable.
# Set the return type to 'void' to
# indicate nothing is returned.
function void SampleFunction2(int i, string s){
  disp("Integer entered: " + string(i));
  disp("String entered: " + s);
  disp("Global real: " + string(r));
}

# See now that the "User Defined" package
# is available.
what();

# Check what functions are in "User Defined"
what("User Defined");


Now the functions will actually be called. An integer (i) will be created. This is a global variable, not to be confused with the SampleFunction variable 'i' which is only visible within the SampleFunction. Its value will be set to the return value of the SampleFunction. Notice how the SampleFunction is called like any normal function - there is no distinction between calling a user-defined function and calling a built-in function.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

# Declare a function with parameters,
# and that accesses a global variable.
# Set the return type to 'void' to
# indicate nothing is returned.
function void SampleFunction2(int i, string s){
  disp("Integer entered: " + string(i));
  disp("String entered: " + s);
  disp("Global real: " + string(r));
}

# See now that the "User Defined" package
# is available.
what();

# Check what functions are in "User Defined"
what("User Defined");

# Call the sample functions
int i = SampleFunction();
disp(i);


Finally, the SampleFunction2 function is called. Recall that it accesses a global variable called 'r'. Therefore, 'r' must be declared and assigned a value, or else SampleFunction2 will produce an error. The constant '42' is passed in as the integer parameter, and the string "Sample" is passed in as the string parameter. SampleFunction2 will access these as 'i' and 's', respectively. (Again, in this case, since 'i' is a parameter to the function, it is not to be confused with the global variable 'i'. If a local variable in a function has the same name as a global variable, when that name is used, the local variable is accessed). While constants are passed to the function, they could just as well be variables, as long as they are of the correct type.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

# Declare a function with parameters,
# and that accesses a global variable.
# Set the return type to 'void' to
# indicate nothing is returned.
function void SampleFunction2(int i, string s){
  disp("Integer entered: " + string(i));
  disp("String entered: " + s);
  disp("Global real: " + string(r));
}

# See now that the "User Defined" package
# is available.
what();

# Check what functions are in "User Defined"
what("User Defined");

# Call the sample functions
int i = SampleFunction();
disp(i);

real r = 32.2;
SampleFunction2(42, "Sample");


The script can now be run as described in the Hello World tutorial. The output should look like:

Output
Available Data Types:
int, real, bool, string, void
exception, file, bitmap, options, window
regkey

Available Packages:
Standard
Phantom
User Defined
Package 'User Defined'
Function Names Return Parameters
-----------------------------------------------------------
SampleFunction int
SampleFunction2 void int,string
10
Integer entered: 42
String entered: Sample
Global real: 32.20000000000000


The next tutorial describes how to handle errors and warning through exceptions and try-catch statements.


Copyright 2000-2011 Phantom Automated Solutions