AutoLISP Lesson 4 - PROGRAM FORMAT - Draftsperson.

net

1 of 4

http://www.draftsperson.net/index.php?title=AutoLISP_Lesson_4_-_PR...

From Draftsperson.net
(April 1999)
An AutoLISP program can be written many ways, but there are certain structural points that are common to all programs. Here you will learn how to put
together a program, structured in the manner that best suits your current application.
One of the main differences between programming in AutoLISP and programming in other languages, is AutoLISP is an interpreted language, as I have stated
before. That means it will take one line of code at a time and evaluate it by itself. You don't have to write a complete program for AutoLISP to be of value to
you.
AutoLISP has three different forms a program can take.
An expression: is a line of code that evaluates and returns a value.
A function: is used in an expression to do the actual work.
A command function. A command function can be called from the AutoCAD command line. This is what we normally think about when we think of an
AutoLISP program.
Every line of code you write in AutoLISP will be a list. The one thing all lists have in common is that they are all enclosed in parenthesis "()". This is the most
important point to get right now. You must put everything in parenthesis, and for every open parenthesis, there must be a closing parenthesis.

Contents
1 The Expression
2 The Function
3 The Command Function
4 AutoLISP Programs
5 Summary
6 More Lessons

The Expression
An expression is a list that starts with a function as the first item in the list, the remainder of the list is passed to the function as arguments. The function used
in the expression can be a predefined function from AutoLISP, or it can be a function you have defined yourself. The remainder of the list must pass the
correct number of arguments to the function, or it will not run.
Example:
(/ 50 25.4)

The example above converts 50 in metric to standard units. It can be entered from the command line, or used as part of a larger program.
If I had only passed one number to the / function above, you can be certain it would not have ran. The same rule will apply to the functions you write later.
You must pass the correct number of arguments to a function.

The Function
A Function is one or more expressions gathered into a form where they can do work. A function must be defined before it can be used. A function is defined
in AutoLISP using the DEFUN statement.
Example:
(defun m ( / )
(/ 50 25.4)
)

The example above shows the form for defining functions. The list starts with DEFUN as the function doing the work. DEFUN needs three or more
arguments. The first argument is the name for the function you are defining, in the example this was "m". The second argument is the parameter list, and in

8/16/2012 8:08 AM

AutoLISP Lesson 4 - PROGRAM FORMAT - Draftsperson.net

2 of 4

http://www.draftsperson.net/index.php?title=AutoLISP_Lesson_4_-_PR...

the example there are no parameters. You will notice in the parameter list a slash separator, this is to separate the arguments to the function on the left of the
slash, from the local variables on the right side of the slash. The third and all subsequent arguments are expressions for the function to perform when it is run.
In the example the function will always return 50 divided by 25.4.
The function can be called by: (m)

The Command Function

The function definition for the command function has exactly the same form as a normal function definition with one exception. When it is being defined "c:"
is placed in front of the command name argument.
Example:
(defun c:m ( / )
(/ 50 25.4)
)

When making the call to this type of function you must call the name just as it's written in the function definition.
Example: (c:m)
When called from inside the lisp interpreter the command function must be treated as any other function. The real power of the command function comes
when calling it from the command line. Any function may be called from the command line, but the command function does not need the parenthesis when
calling it from the command line.
Example: Normal function call from the command line:
Command: (m)
Command function call from the command line:
Command: m

As you can see it will be much easier for the user to deal will command function than normal functions. Command functions are what we will use to build
future programs.

AutoLISP Programs
Now it is time to put it all together and see what a real program will look like. Every program you write should come out looking basically the same. It will
contain certain components that are going to be common to all your programs.
The first thing we will do is create our header comment so we know what we are working on, and more importantly, when we return later to modify it, we
will know what we worked on. The next thing you will need, is the program definition.
;; Title: Program
;; Purpose: Program to do things
;; Written: YZ
;; Creation: 2-5-1998
(defun c:prog ( / )
(stuff_to_do)
)

The first thing you will notice in the program above is I have defined a command function. The filename for the lisp should be the same as the command
name given.In this case the filename will be PROG.LSP. The next thing that stands out is the parameter list. In this case it is empty, but I have included the
separator anyway. I do this so I will know later when I come back to it, that I intentionally have no parameters, or local variables. With the parameter and
local variable list there, I will be less likely to forget to add values to the list, as I need them.
Next we see the stuff_to_do function which will be defined later.
Then finally we close the program with the closing parenthesis to match the opening one at the beginning of our definition.
The next thing we need is some sort of error trapping routine so if something unforeseen happens the entire program will not go flashing across the screen,
leaving our user totally confused.
(defun c:prog ( / )
(stuff_to_do)
(defun *ERROR* (ErrStr)
(print ErrStr)
)
)

Now we have an error checking routine, which is quite basic, but will get the job done for now. All it will do is catch the error string passed back from
AutoLISP when the error occurs and print the error string on the command line.
The program listing shown above is sufficient to make a simple program that can be used at the command line. As programs get more complex you will find it
necessary to do a little more work to keep things in order. If for example we wanted to pass some parameters to our program and do a little logic based on
what we pass in, the program gets more complex. Our job is to keep it from getting so complex we no longer understand what is going on.

8/16/2012 8:08 AM

AutoLISP Lesson 4 - PROGRAM FORMAT - Draftsperson.net

3 of 4

http://www.draftsperson.net/index.php?title=AutoLISP_Lesson_4_-_PR...

(defun c:prog ( Param1 Param2 / )

(if (= Param1 Param2)
(progn
(do_this_stuff)
(do_that_stuff))
(progn
(do_this_other_stuff)
(do_that_other_stuff)))
(defun *ERROR* (ErrStr)
(print ErrStr)
)
)

As you can see I have to parameters I'm checking against each other, and I've decided I need to do several things if my cases work out.
Now things are starting to get a little harder and it might be best if I broke certain things into their own functions, just to make it clearer what is going on. The
first thing I will do is create a main function so all the logic can happen in the same place. What I want from my main function is to only to see the logic part
of the program, and leave the actual work to be done for the other functions.
(defun c:prog ( Param1 Param2 / prog_main check_params stuff_to_do do_other_stuff *error* )
(defun prog_main ( / )
(if (check_params Param1 Param2)
(stuff_to_do)
(do_other_stuff))
)
(defun check_params ( Item1 Item2 / )
(= Item1 Item2)
)
(defun stuff_to_do ( / )
(do_this_stuff)
(do_that_stuff)
)
(defun do_other_stuff ( / )
(do_this_other_stuff)
(do_that_other_stuff)
)
(defun *ERROR* (ErrStr)
(print ErrStr)
)
(prog_main)
)

As you can see the program grows but is less complex because we now have our logic contained within a few lines of code. You can follow the logic without
having to understand the details of what the program is doing. The larger a program becomes the more important it is to hide the details, and leave only the
logic out front. Many other things have happened here, that makes this style work so well. We now have local variables in the parameter list for our program.
Putting the function names in the parameter list means when our program ends, the life of the functions we are using end also. If we had not included them in
the parameter list they would still be occupying memory, even after our program had ended. We must leave memory as clean as possible when we end our
program, and parameter lists are the easiest way to keep memory clean.
You may have noticed that Param1 and Param2 are not included in the parameter list. This is because Param1 and Param2 are parameters being passed to a
function and their life ends when the function ends, so no cleanup is necessary. Also notice when passing Param1 and Param2 to check_params I have given
them different names in the function definition for check_params. When passing variables to a function you should use different names inside the function so
no confusion over which variable is being worked on.
The variable named in the parameter list is not the variable that exists outside the function. Even if they have the same name they are not the same variable.
The variable in the parameter list is local to the function being called, and is just a copy of the variable being passed. What that means is, if you change the
variable inside the function the variable being passed to the function is not changed. This shouldn't really matter though, because it's not a good idea to work
on variables passed to a function. Variables passed to a function should only be used for working on the value you are trying to return from the function.
You may have noticed I have given the check in the IF statement its own function. This makes the logic in the prog_main function easier to follow. The way
it is written I don't have to know what is being checked, I only have to know whether it was true or not.

Summary
You now should know the basic layout of an AutoLISP program. The reasons we need to structure our programs are varied but certain reasons keep coming
up again and again, so I will list them here.
1. Areas likely to change.
2. Complex data
3. Complex logic
Any area, which seems complex, should probably be moved to its own function where you can control the interface to the function.
Your program should clean up memory. Functions should be localized to only those areas of the program needing them. Variables should be kept local to the
function using them. Global variables should be avoided if at all possible.
Proper commenting should be included to make every part of the program obvious. If you name your functions and variables correctly you can cut down on
the number of comments needed to clarify things.

More Lessons
AutoLISP Lesson 1 - Introduction to Lisp Programming

8/16/2012 8:08 AM

AutoLISP Lesson 4 - PROGRAM FORMAT - Draftsperson.net

4 of 4

http://www.draftsperson.net/index.php?title=AutoLISP_Lesson_4_-_PR...

AutoLISP Lesson 2 - THE AutoLISP ENVIRONMENT

AutoLISP Lesson 3 - COMMENTS
AutoLISP Lesson 4 - PROGRAM FORMAT
AutoLISP Lesson 5 - VARIABLES
AutoLISP lesson 6 - NUMBERS
AutoLISP Lesson 7 - PROGRAM CONTROL
AutoLISP Lesson 8 - LOOPING
AutoLISP Lesson 9 - DATA STRUCTURES
AutoLISP Lesson 10 - INPUT AND OUTPUT

Retrieved from "http://www.draftsperson.net/index.php?title=AutoLISP_Lesson_4_-_PROGRAM_FORMAT"

Categories: AutoCAD Tutorials | AutoCAD Articles
Printed from www.draftsperson.net

8/16/2012 8:08 AM