Pixel Graphics, Inc. - Litigation & Court Graphics
LITIGATION GRAPHICS - COMPUTER ANIMATION - TECHNICAL ILLUSTRATION - CAD DRAFTING - AUTOLISP PROGRAMMING
3423 Rivers Edge Trail
Houston, Texas 77339
281.359.1187
Copyright 2008 - Pixel Graphics, Inc. All rights reserved.
AutoLisp Tutorial: Creating and Using Functions in Autolisp
What is an Autolisp function?

A function can be thought of as a "black box" that either you create, or has already been created and is
available in Autolisp. These black boxes are independent blocks of code that perform a specific task or
function, hence the name. You send data (i.e. a number, a time, a date, text, a list, etc.) to the function
and then that function spits out or "returns" an answer back to you. Functions work like calculators that
are preprogrammed to perform a very specific task on the entry data. For example, we could easily write
a function that receives a list of numbers, and spits out or returns the average of those numbers.

Why are functions important?

Functions are vitally important to understand and use because they organize and compact your
program code, and most importantly, they are reusable.  For instance, if you were writing a program that
required you to find the average of ten different sets of numbers, and each of those sets had a different
count of numbers in them, instead of rewriting the code to average the numbers ten times in the main
program, you could simply write a function called "average", and send each of the ten lists to the single
"average" function code block which would reduce the amount of code writing considerably.

The other advantage of using functions is that when you create a function like "average", and the
program code is proven to work, you can forget how the function works internally, and just use it as
many times as you wish.  It's also wise to store these functions in libraries, so that you will always know
where they are when you need them.

How do I create a function?

To create a function you begin by calling the "defun" function, then giving that function a name. This is
the same way we create a "command" in Autolisp, except note that we don't use a "c:" in front of the
function name. All of the code that falls within the parentheses before and after "defun" are self
contained in the function itself. For example, to create the "average" function, we'd begin as follows:
Jeff Winship - Computer Graphics Consultant                                                                                                                                        Revised May 24, 2008
(defun average (numlist)
<The program code that will calculate the average begins here>
)  ;This is the end of the function definition
Note that we are using numbers before each line for reference only.  You never use line numbers in
Autolisp.

Line 1 calls the "defun" function which defines the function code. The second parameter in the "defun"
function is the name you'd like to call the function, in this case we'll use "average". Anything is valid,
except for functions that are already used in the Autolisp language, or function names that you've
already used.

Again, the parentheses preceding the "defun" and the parentheses on line 3 in this example constitute
the self contained block of program code that is the function. You can place this function code block
anywhere in the Autolisp file, but if you want it to function properly, don't place it inside another function
or block of code. Remember, it's a stand alone unit.

The third parameter in the first line "(numlist)" tells the "average" function that we will sending our input
data (in this case the list of numbers to be averaged) into the function through a variable we've decided
to name "numlist".

Line 2 will be the starting point for the code that we will use to do the actual calculation of the average.

The code needed to calculate the average of the values in the list numlist is as follows:
(defun average (numlist)
    (setq n (length numlist))
    (setq sum 0)
    (setq k 0)
    (repeat n
    (setq sum (+ sum (nth k numlist)))
    (setq k (+ k 1))
    )
    (setq avg (/ sum n))
)
You can see that in line 2, we first assigned the length of the list of numbers to the variable "n". The
length function already contained in Autolisp simply counts the number of items in the list that is sent
to it, and then returns that number.

Lines 3 and 4 initialize the variables "sum" and "k " to 0. The variable "k" is a incremental counter that is
used to get the next item in the "numlist" variable.

Next we loop
"n" times through the list using the repeat command, setting the "sum" variable (which
was initially 0 by default), to equal the it's previous value plus the value of the next item in the list.

We then calculate the average of the numbers in the list by dividing the sum by the number of items in
the list.  We've now created a function that will average a list of numbers. Pretty easy, huh?

It's important to note that the last line of interior code (in this case line 6) will be what the function spits
out or returns as the answer.

How do I use a function?

Now that we've created a function, it's time to make it go to work for us. First we need to create a list of
numbers that we want to average.  In this case, let's assume you wanted to average the number of
times a co-worker went to the water cooler every day. You'd have five days worth of data, with each
number being the number of water cooler visits. At the command prompt, type the following:
Command: (setq visits (list 4 6 2 7 6))
We've now defined a list variable named "visits" that contains the data you collected on the number
of water cooler visits your pal made each day.
To find the average, simply call the
average function and send it the list variable "visits" as follows.
Command: (average visits)
This returns a value of 5.0 meaning your co-worker visited the water cooler an average of 5 times a day.

How do I use a function in my Autolisp program

Simple. You just call the function the same way you did at the command prompt, except you assign the
results of the function to a variable. The following example shows how to do exactly what we did above,
but this time only using Autolisp code.
1
2
3
1
2
3
4
5
6
7
8
9
10
HOME  |  3D ANIMATION  |  DIGITAL IMAGES  |  AUTOCAD DRAFTING  |  AUTOLISP PROGRAMMING  |  CONTACT & OTHER INFO  |  F.A.Q.
I hope this free tutorial helps clarify what an Autolisp function is, how to create one, and how to use it in
you own Autolisp program code. I've noticed that copying pasting the code from these tutorials really
messes it up, so you can
download the Autolisp code for this tutorial here.

If you have any comments or questions regarding this technique or code, feel free to e-mail me at:            
                                            
support@pixelgraphicsinc.com
(defun c:go ()
(setq visits (list 4 6 2 7 6))
(setq avg_visits (average visits))
(princ (strcat "\nAverage visits to cooler: " (rtos avg_visits)))
(princ)
)

(defun average (numlist / n k sum avg)
(setq n (length numlist))
(setq sum 0)
(setq k 0)
(repeat n
(setq sum (+ sum (nth k numlist)))
(setq k (+ k 1))
)
(setq avg (/ sum n))
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Line 3 is where we call the "average" function at lines 8 through 17 to do it's magic. Line 3 reads literally
"Send the list contained in the variable "visits" to the "average" function and store the result (what the
"average" function returns) in a new variable "avg_visits".

Functions and Variable Scope

You might have noticed that I snuck something into the average function on line 8. I'll discuss this in a
future article, but suffice to say that adding the
"/ n k sum avg" to line 8 keeps all of the variables
used inside the "average" function invisible to the program code outside the function. That way, you
don't have to worry about thinking up unique variable names inside the function code.