A brief introduction to Autolisp®

Variables exist as long as the drawing remains open, and values they hold exist until they are replaced by new values - one by one. This means that you can store values for the duration of a drawing session. To reassign a value to an existing variable simply use SETQ in the above manner.

Before ending this chapter let's make a few notes on datatypes. For obvious reasons, different types of data varies in size. The computer doesn't like to waste memory, so each datatype has a predefined size in memory when it is stored. AutoLISP doesn't put restraints on the user when using variables, unlike other languages where you have to declare a variable in order to reserve space in memory before it can be used. Variables in AutoLISP are declared dynamically - i.e. AutoLISP determines how much space to reserve when reading the value it has to store.

This chapter was written to get you quickly started with AutoLISP without going into serious discussions about syntax, function evaluation or how to build functions yourself.

There are two main rules to remember when dealing with AutoLISP, one syntactical - the other functional:

• 
  Every AutoLISP expression is enclosed within a set of parantheses. The left paranthesis signals the start of the expression and the right signals the end.
  
• 
  Every AutoLISP expression returns a value.
  

The generic syntax of an AutoLISP expression is like this:

Each function is enclosed by a pair of parentheses; the rightmost part within the parantheses is the function name and everything to the right is arguments to that function. Arguments are datatype specific (with a few exceptions) and can be anything that represents or evaluates to the datatype in question.

A simpel expression in AutoLISP can look like this:

(polar myPoint 0.7854 45.5)

This built-in function returns a point that lies at an angle of 0.7854 radians and in a distance of 45.5 units from the point stored in variable myPoint. It follows the syntax described above - function name to the left, arguments to the right and enclosed by a set of parantheses. More commonly you will see expressions looking like this:

(setq myvar (polar myPoint 0.7854 45.5))

This is actually two functions, a SETQ function and a POLAR function. Each function is enclosed by its own set of parantheses. If the expression is written with an indented notation as is often used in AutoLISP, the parantheses become clearer:

(setq myvar
(polar myPoint 0.7854 45.5)
)

Any function in AutoLISP returns a value. If function A is calling another function B then function B will return a value to function A. Popular speaking you can say that a function is replaced by a value after execution, and that is important to understand in order to nest functions. Nested functions are simply functions used a arguments - as the example above shows.

Below is a stylized diagram of parts involved in the expression shown above:

start and name of main function

1st argument to main function

start and name of nested function

1st argument to nested function

2nd argument to nested function

3rd argument to nested function

end of nested function

end of main function

return value of nested function becomes 2nd argument to main function SETQ
(setq

myvar

myPoint

45.5

)
In the remainder of this text the term expression or statement is used to describe anything within a pair of parentheses, whether it be pieces of executable code or not and whether it consists of nested functions or not.

When a series of separate expressions are executed their return values are "overridden" by each other and only the last result is returned, but SETQ or one of the other assigment functions can at any time be used to grab a value by assigning it to a variable.

Consider the following series of expressions:

(setq var1 (* 5 110)) ; assign 5*110=550 to variable var1
(setq var2 (+ 20 200)) ; assign 20+200=220 to variable var2
(/ var1 var2)

During execution these expressions return a value each, but only the return value of the last executed expression remains available, for example, to a function that called the sequence (visually the value will be printed to the screen). Of course, during execution the return values from the first two functions were stored into variables with SETQ and they can now be used for further processing.

Before moving on to learn how to put together code into user-defined functions and routines let's have a look at some important and helpful notation syntax in AutoLISP.
By the way, AutoLISP is a registrered trademark by Autodesk - it is the name of this language and is used throughout this text. VisualLISP is the registrered trademark name of a programming environment for AutoLISP - it is a product owned by Autodesk Inc. and is shipped with AutoCAD 2000 or later (though available for release 14.01 by special purchase).

Notational (lexical) syntax
AutoLISP source code and programs destined for interpretation (as opposed to compiled code which is also an option) are written in ASCII text and is as such handled by any editor that handles ASCII text. As for any programming language there are some notational rules that apply when writing the code.

The most important syntactical rules are the ones described above. Besides the sequence of the parts inside an expression it is imperative that parantheses are paired. Also, double quotes are used for string datatypes and it is equally important that double quotes are paired.

Spaces or tabs divide the different parts in an expression, but as long as there is at least one space or tab between the parts it doesn't matter how many spaces/tabs are used:

( setq myvar (/ 5 40.0) ) ;this silly example is just
;as valid as the functions above

In AutoLISP files linefeeds are not important either - they don't terminate an expression and you can use as many as you like. Only parantheses determine where an expression begins and where it ends.

( ) ' " ; [space] [end of line]

A semicolon in AutoLISP signals the start of a comment - as shown in the previous examples. Everything after the semicolon until the end of the line is regarded as a comment. Thus, the end-of-comment sign is the end of the line. Normally, if you want to expand comments for more than one line you have to start each line with at least one semicolon. There is one way of expanding comments over several lines, though - with the special two-character pairs ;| and |; (the character | has ascii code 124).

Some characters aren't allowed in symbol names. Otherwise symbol names can consist of any sequence of printable character, except that they can't consist of numeric characters only. The charcters not allowed are:

( ) . ' " ;

When using symbol names, take care that you don't use predefined names of functions, symbols and constants - in other words: don't use reserved names. A typical example is the name pi that in AutoLISP is a constant for .. you guessed it .. pi.

Notes: When writing AutoLISP in menus, a plus-sign has to end a line if the expression continues on the next line. Semicolon in menu files means Enter or CR - therefore it is not allowed to use semicolons as comments in menus.
When using VisualLISP different numbers of semicolons have different meanings, but they are still signalling start-of-comment.

Other notational and syntactical conventions are:

• 
  Symbol and function names are not case sensitive
  
• 
  Integer constants can begin with + or - (minus). These are optional.
  
• 
  Real constants consist of one or more digits, a decimal point (period) followed by one or more digits. Omitting digits in front of the decimal point produces an error. Real numbers can be in scientific notation with the letter e or E written in front of the exponent, e.g. 4.514E10 or 4.514e10.
  
• 
  Single quotes are commonly used instead of the QUOTE function.
  
• 
  Within quoted strings a backslash denotes a control character. As an example the sequence \" can be used to return a single double quote - this is used within strings where the string has to contain a double quote. Control characters are:
  

In part II we looked at function syntax and evaluation as well as some notational syntax that is used when writing AutoLISP code. Part III will introduce you to the steps of piecing together a user-defined function.

To write a user-defined function in AutoLISP use DEFUN. The easiest way to explain how to get started is .. well, to get started. Fire up AutoCAD and VisualLISP or some text editor and let's write a function that returns a point relative to another point. The point returned by the function will lie in an angle of, say, 0.7854 radians and a distance of 45.5 units from the input point. The function will also put the returned point into the system variabel LASTPOINT so it can be accessed with @ in AutoCAD:

(defun myPolar (pt / myVar)
(setq myVar (polar pt 0.7854 45.5))
(setvar "LASTPOINT" myVAR)
)

You will immediately notice that all expressions that make up the function body (all two of'em) is enclosed by the parantheses of the DEFUN statement. This is a because of LISP's list-processing features - everything that starts with a left and ends with a right paranthesis is regarded a list, and in LISP there are only two fundamental parts: atoms and lists. Atoms are the components of a list and a list is a series or collection of atoms that has to be processed. Within any particular list atoms can be lists themselves, but broken down you are left with the single components and those are what is called atoms.

A DEFUN statement starts with the name DEFUN followed by the function name that will be used when calling the function. Next is a special list that describes any arguments used in the function, followed by a slash character and local variable names used in the function. This slash character is not a division function in this case but merely separates arguments and local variables - more about local variables later.

Let's add some comments to this function:

(defun myPolar (pt / myVar) ; function name is myPolar
; function takes one argument, named pt
; function has one local variable, named myVar
(setq myVar (polar pt 0.7854 45.5)) ; calculate the point relative to pt and store
; the result in variable myVar
(setvar "LASTPOINT" myVAR) ; store the value of myVar in sysvar LASTPOINT
) ; end of defun

How is this function used and how does it return a value? As you learned in part II any function returns a value. In a DEFUN all expressions within the function body returns a value and the value returned by the last expression executed is the value that is returned by the DEFUN statement. This means that any code that calls this function with a valid argument will get access to the return value:

(setq newPoint (myPolar aPoint))

This call invokes myPolar with the argument aPoint. Given that aPoint contains a valid point datatype it is processed and the last expression in myPolar will return the point stored in system variable LASTPOINT. This is the value returned to the calling function which in turn stores the return value in a new variable, newPoint. You now have a point in newPoint that is placed in relation to aPoint exactly as calculated by the function myPolar.

A function doesn't need to return a value - it can merely execute in order to take some kind of action. After calculating the new point you can have the function draw a point in AutoCAD without ever worrying about a return value:

(defun myPolar (pt / myVar)

The last statement is now a COMMAND function that enters the current AutoCAD drawing and simply draws a point. COMMAND is used to invoke any AutoCAD command programmatically in AutoLISP. It takes as arguments the command name followed by any sequence that is expected by that particular command in AutoCAD. If you wish to draw a line between aPoint and the new point you simply follow the sequence in the LINE command:

(setq newPoint (myPolar aPoint))
(command "LINE" aPoint newPoint "")

As you know the LINE command assumes that you want to draw more lines and continues to ask for next endpoint. To terminate the command in AutoCAD you hit enter, return, space or escape. To terminate the command in AutoLISP you insert an empty string to simulate Enter being hit. That is why the last argument in the above COMMAND function is an empty string ("").

Now you can have a main function that, for example, gets a point picked in a drawing, invokes myPolar in order to calculate the new point and then draws a line between the point that is picked and the new point:

(defun myPolar (pt / myVar)

(defun C:Relative ()

These two functions can be written to a lisp file, loaded into AutoCAD and executed like any other command (more about loading a function later). Notice that the name of the main function is preceded by a C and a colon. Whenever AutoLISP loads such a function it is made accessible by AutoCAD to be used as a built-in command. There is no other difference in the DEFUN statement than preceding the name with "C:".

Command: relative

Upon picking a point it draws the line. Notice that "nil" got written to the screen. This is because all expressions return a value and COMMAND always returns nil. To avoid that the last value is written to the screen use a PRINC statement without arguments as the last expression in your code. PRINC issued without an argument returns a null symbol which, of course, is invisible on screen. This technique is known as "silent exit" and is used whenever terminating a routine that has no point in returning a value to the user:

(defun C:Relative ()
(setq aPoint (getpoint "Line relative from point: "))
(setq newPoint (myPolar aPoint))
(command "LINE" aPoint newPoint "")
(princ)
)

Let's go through some steps that make the code available, not only to the current drawing but in whatever drawing you wish. First save your code as a separate text file with the extension .lsp - take care that it is stored as an ASCII file, i.e. an unformatted text file. Place the file in one of AutoCAD's search paths. If you are not clear on your search paths then open the Options dialog, click on the Files tab and expand the Support File Search Path item. You can have lisp files whereever you want, but if they are not placed in a search path you will have to specify the whole path in the next procedure.

(load "relative")

LOAD is an AutoLISP function like any other - it takes one argument, a file name with or without extension, reads the file and attempts to load any code found. If succesfull it will return the value of the last expression in the file - in this case it will return "C:RELATIVE" because the last expression is the DEFUN of that name. If you are using VisualLISP you can still save the file and use the statement above, or you can choose Tools->Load text in Editor or simply click the load button in the toolbar.
All the functions in Relative.lsp is now available whether they are defined as commands or not. Because each drawing has its own environment in memory the lisp functions are normally only available to the drawing that was active upon loading of the lisp file. Some techniques exist to make functions available to all drawing but that lies beyond the scope of this text.

Loading and executing your newly defined command concludes this chapter and this little AutoLISP primer. That wasn't too hard, was it? It is my hope that you will continue your journey into the world of AutoLISP. Of course, if you are new to any programming it is kinda rough getting started, no matter how easy people tell you it is. I've heard people who are programming in LISP and other languages refer to AutoLISP as a toy programming language. Yes, it is a kind of macro language in nature and yes, it is a very small subset of Common Lisp, but it is nevertheless a fully grown programming language that is merely designed for a very specific purpose - and very well designed for that purpose it is too.

By the way, you may have noticed that more languages have been introduced to the AutoCAD product family, and you may also have heard of some languages being introduced and later becoming obsolete. AutoCAD is like any other software product - it has to keep up with demands but also with technology. From time to time it is being discussed whether or not a language like AutoLISP will ever loose its support by its creators. Although it's been constantly improved over time it once seemed to be standing pretty still and especially with the withdrawals of AutoCAD from all other platforms than Windows and the implementation of the Windows "standard" programming environment Visual Basic it became an even more valid discussion if AutoLISP was to become obsolete.

AutoCAD, AutoLISP and VisualLISP are registered trademarks by Autodesk, Inc. In case of listing, describing or mentioning another brand or product it is most probably also a trademark or registered trademark by Autodesk, Inc. Other brand and product names mentioned or described in these pages are trademarks or registered trademarks of their respective companies.