User Defined Functions
Functions
A function is code that can be called repeatedly from other places. Functions can have parameters passed into them, and may return a resulting value. Some functions, like len, are built-in. Some functions, like system.gui.messageBox(), are part of the scripting libraries provided by Ignition. Some functions, like math.sqrt(), are provided by the Python standard library. However, functions can also be defined in a script that can be used later on in the script. In these user defined functions, you give the function a name and some code that will run when the function is called. Then later on in the script, you can call the function by its name and it will run the code specified in the function. This is useful, because it allows you to run a segment of code many times without having to repeat it within the script.
Functions are invoked by using their name followed by an argument list surrounded in parentheses. If there are no arguments, you still need an open and close parenthesis.
Defining Functions
Functions are defined using the def keyword. A function needs a name and a list of the arguments that it can be passed. For example, this code defines a function that prints "Hello World!".
# First we define our function.
def printHW():
print "Hello World!"
# We can then call our function.
printHW()
Functions Arguments
When a function accepts arguments, the names of those arguments become variables in the function's namespace. Whatever value was passed to the function when it was invoked becomes the value of those variables. Arguments can have default values, which makes them optional. If an argument is omitted, then its default value will be used. The following code defines a function called cap, which will take a number, and make sure it is within an upper and lower limit. The limits default to 0 and 100.
# We first define our function. Notice that we have 3 different arguments.
# x, min, and max. The min and the max are set to equal 0 and 100 respectively.
def cap(x, min=0, max=100):
# Check if x is less than the min, return the min if true.
if x < min:
return min
# Check if x is greater than the max, return the max if true.
elif x > max:
return max
# Return the value if it is within the bounds.
else:
return x
# We can then see the outcome by running our function with a few different parameters.
# This will print out a 40, since it is within the bounds.
print cap(40)
# This will print out "0", since it is less than the min of 0.
print cap(-1)
# This will print out "100", since it is greater than the max of 100.
print cap(150)
# This will print out "150", because it uses a max of 200 instead of the default 100.
print cap(150, 0, 200)
Keyword Arguments
In Ignition, some complicated script functions are designed to take keyword arguments instead of normal parameters. In the description for those functions, you may see the following info box in this User Manual:
This function accepts keyword arguments.
Arguments can also be specified by keyword instead of by position. In the example above, the only way someone would know that the 200 in the last call to cap specified the max is by its position. This can lead to hard-to-read function invocations for functions with lots of optional arguments. You can use keyword-style invocation to improve readability. The following code is equivalent to the last line above, using 200 for the max and the default for the min.
print cap(150, max=200)
Because we used a keyword to specify that 200 was the max, we were able to omit the min argument altogether, using its default. However, using a keyword argument before a non-keyword or positional argument is not allowed.
# This would fail, because the function isn't sure what 150 is being used for.
print cap(max=200, 150)
Functions Are Objects
Perhaps one of the most foreign concepts for new Python users is that in Python, functions are first-class objects. This means that functions can be passed around to other functions (this concept is similar to the idea of function pointers in C or C++).
Suppose we wanted a general way to filter a list. Maybe sometimes we want the odd entries, while other times we want even ones. We can define a function called extract that takes a list and another function, and returns only entries that "pass" through the other function.
# We define a function that checks if the value passed in is odd.
def isOdd(num):
return num % 2 == 1
# We define a function that checks if the value passed in is even.
def isEven(num):
return num % 2 == 0
# We define a function that inserts our list into the appropriate function and returns valid values.
def extract(filterFunction, list):
newList = []
for entry in list:
if filterFunction(entry):
newList.append(entry)
return newList
# Prints out [0, 2, 4, 6, 8]
# Notice that isEven as not invoked, but passed to the filter function.
print extract(isEven, range(10))
Where Can Functions Be Defined
User Defined Functions can be defined anywhere that a script is used. As stated before, they are useful to run segments of code multiple times without having to repeat it. They are also used extensively in project and shared script modules where multiple functions can be defined in a single script module. Finally, some special Ignition System functions like system.gui.createPopupMenu or the runScript Expression function use functions as arguments.
Function Scope
The concept of scope is very important in all programming, and Python is no exception. Scope defines what names are directly accessible without any qualifiers. Another way to put this is that the scope determines what variables are defined. In Python, a variable is defined at the time that it is assigned. What scope it belongs to is also defined by where the assignment occurs.
# On this line, there is no variable 'x' in scope.
doSomeWork()
# Now 'x' is defined in our scope, because we've assigned a value to it
x = 5
# This will work because x is in scope.
print x
When you define a function, that function gets its own scope. Variables that are assigned within that function body will not be available outside of the function.
# x is local to myFunction() because this is where it is defined.
def myFunction():
x = 15
print x
# This will fail, because x is not available in the outer scope
y = x + 10