Learn AutoLISP and Increase Your Productivity!

Increased productivity, isn’t that what everyone wants? Although this should be one benefit of using a CAD program such as AutoCAD, however, in many cases, this benefit is not automatically derived by using the program out of the box. There are many ways to increase your productivity when using AutoCAD, and writing your own AutoLISP programs can be an easy one to implement.

Another is thinking through the process in which you draw to accomplish more than one task at a time. Certainly, if you could do two things at once you could get twice as much done in the same amount of time. Though this may not be practical in every case, you can increase your productivity by making each task more automated. That’s what this site is all about, getting more done in less time using AutoLISP to automate everyday drafting tasks.

Functions as listed in the “AutoLISP Reference” Manual, are of two types: Internal and User Defined

Internal, or predefined functions, are those that are resident within AutoLISP such as the ones listed in the “Reference” Manual. Many common Math functions that you may already be familiar with are included in these functions:

(+) add
(-) subtract
(*) multiple
(/) divide

and the logical operators:

(<) less than
(>) greater than
(=) equal to
(/=) not equal to

are a part of the many internal functions. These functions are called simply by giving their name as the first element of a list, with the arguments to that function following. Consider the next list:

(+ 1 2 3)

Here, the first element of the list (+), is an internal function that will evaluate the arguments (1 2 3) that follow, and return 6 as the result. Functions will always return a result.

Command: (+ (* 3 2) (/ 12 4) 2)
Lisp Returns: 11

As you can see from this example, a list may contain other lists with functions as their first element. Since lists are made up of elements, lists themselves can be elements of other lists. This is referred to as “Nesting.” In this example we have a four element list: (+) is the first element, the entire expression (* 3 2) is the second element, (/ 12 4) is the third, and 2 is the fourth. It is easy to see that (* 3 2) produces 6, (/ 12 4) produces 3, then adding 6, 3, and 2 give 11 as the result.

Functions

LISP is an acronym for LISt Processing and is a programming language that consists of only three elements: atoms, lists, and functions. An atom is the basic unit of any LISP program, simple defined as a single computer word or element. You could say that atoms represent the basic building elements of data in LISP.

A Function can be defined as a LISP program which always returns a result. Functions may be user defined or already built into AutoLISP such as the common math functions +, -, *, and /. Each function is called simply by giving its name as the first element of a list, with any arguments to that function as the subsequent elements of the list.

A list therefore, is a group of atoms that are contained within an opening parenthesis “(” and a closing parenthesis “)”. These lists may contain any number of reals, integers, strings, variables, or other lists and are treated as one expression stored in a single variable. Lists can be used to organize and process groups of information.

Sample list’s are:

(“A” “B”) ;;two elements

(table) ;;one element

((desk chair) (files)) ;;two elements

(1 (2 3) “test” (c d)) ;;four elements

Point Lists

Graphic coordinates such as 2D points are expressed as a list of two real numbers

(X Y), as in:

(12.435678 7.134000)

3D coordinates are expressed in the same manner with the third value of the list being the Z coordinate.

(12.435678 7.134000 1.000000)

This predefined structure, referred to as a point list, accommodates the interface between AutoLISP and AutoCAD.

AutoLISP was first implemented in AutoCAD v2.15, in the form of “Variables and Expressions.” There are many ways to increase your productivity when using AutoCAD and writing your own AutoLISP programs can be an easy one to implement. This feature, built right inside AutoCAD, offers an amazing amount of utility without requiring any programming experience.  

Variables and expressions provide the ability to create parametric menu macros and scripts. This article will discuss some of the AutoLISP expressions and how they can be used at the AutoCAD command line.

All AutoLISP expressions are enclosed in parentheses. A valid expression must begin with an open parenthesis and every open parenthesis must be balanced by a closing parenthesis. Otherwise, the AutoCAD LISP interpreter (that portion of AutoCAD that evaluates and executes the AutoLISP functions) will respond with an error message. If you ever see the response “1>” or “(_>” after trying an AutoLISP expression, AutoCAD is telling you that you omitted one or more closing parenthesis.

At its simplest, you can perform addition, subtraction, multiplication, and division using simple numbers and arithmetic operators directly from the AutoCAD command line:

Command: (+ 1 2 3)
 6

Command: (* 2.5 2)
5.000000

Command: (+ (* 3 2) 4)
10

In AutoLISP, the operator precedes the values being operated upon, much like Reverse notation of the early Hewlett Packard calculators. Notice also that AutoLISP evaluates from the innermost parentheses outward. You can use an AutoLISP expression to provide the response in the middle of an AutoCAD Command prompt:

Command: CIRCLE
Specify center point for circle or [3P/2P/Ttr (tan tan radius)]: 5,5
Specify radius of circle or [Diameter]: (/ 10.0 2.0)

In the beginning, these examples might not appear very useful, but AutoLISP is a powerful programming language built within AutoCAD, that brings supercomputer power to your drafting needs. With AutoLISP any repetitive task can usually be automated to reduce time or improve accuracy.

You can use the AutoLISP command function to invoke the AutoCAD or DOS commands under control of
an AutoLISP program. Your program may compute parameters on the fly and pass them one at a time to
AutoCAD via a series of command function calls, or all the arguments may be prepared and delivered to
AutoCAD at once with a single Command function call. There are three methods of using the command function.

1. (command) by itself acts as a Ctrl-C, terminating any current AutoCAD command.

2. (command  “autocad-command”  ARG1 ARG2…. ARGN) invokes an AutoCAD command and passes the supplied argument values as responses to the command prompts.

Partially complete command functions can be used, as in the following series of calls:

Command: (command)
Command: (command “LINE”)
Command: (command “0,0”)
Command: (command (list 2 0))
Command: (command “@2<135” “C”)

The above is functionhe 35″d “(list 2 0))ommand functions can be used, as in the following series of calls:e command promds of using the command funally equivalent to the next example, a more efficient way of accomplishing the same thing:

Command: (command “LINE” “0,0” (list 2 0) “@2<135” “_C”)

This expression draws a line from 0,0 to 2,0 to 0.5858,1.4142 (which is 135 degrees from 2,0) then closes back to 0,0 completing a triangle.

A null string is equivalent to a carriage return, and you may use it to terminate many AutoCAD commands. The following example may be used to change the color of the current layer to Red, (getvar) is used to retrieve an AutoCAD system variable. In this case it returns the name of the current layer:

Command: (command “LAYER” “_C” “RED” (getvar “CLAYER”) “”)

3. (command “DOS”-command” “command line”) invokes a DOS command or external program via an entry in ACAD.PGP. You can read more about how to modify ACAD.PGP in the AutoCAD Help section. Examples in this tutorial will not use this format because most readers will not have the appropriate entries in the ACAD.PGP file. Invoking the DOS command cad be accomplished as follows:

Command: (command “SHELL” “dos-command-parameter”)

The only restriction in the use of the Command function is that the user dialog is not permitted within the AutoLISP function once a Command function is pending. For example some functions which cannot be used with an open dialog  in order to obtain input include (getstring), (getreal), (getdist) and (getcorner).

AutoLISP variables can be created to store numbers, text and coordinates of interest to you. A variable’s value may be retrieved and supplied in response to AutoCAD prompts. Thus variables are rather like the memory keys of a calculator. Expressions involving variables may be used alone or in combination to perform computations.

Create variables and assign a value to them with the AutoLISP SetQ function. SetQ function is the most basic AutoLISP function. Variables are referred to by name, and a name may be one or more characters. For example, you can create a variable called X1 and store the value 3 into it by typing:

Command: (setq X1 3)
3

Notice that the value 3 supplied was echoed back to indicate the SetQ had finished. This is a fundamental concept for expressions and AutoLISP programming in general. Almost all functions return a value. In some versions of AutoCAD the command prompt does not always return a value after an AutoLISP expression—this is normal, don’t worry. Also note that AutoLISP is not case sensitive. Functions and variable names may be entered in any combination of upper and lower case letters. Thus SetQ and setq mean exactly the same thing.

The above example stored an integer into the variable X1. Because it contains an integer value, X1 is therefore called an integer variable. If you enter a number and include a decimal point followed by one or more numeric digits, the variable is recognized as a “real.” In the next example the variable RVAR is a real:

Command: (setq RVAR 3.0)
3.000000

You may also store a text string in a variable. The variable STR in the following example is a string variable:

Command: (setq STR “This is a string”)
“This is a string”

Use caution when dividing two numbers. If they are both integers then the result is also an integer and the fractional part of the result is discarded. Notice the difference in the two examples below:

Command: (/ 5 2)
2

Command: (/ 5.0 2)
2.500000

You can also supply the result of one expression to another expression. In the first three examples below the new expression uses some of the variables we already assigned. The fourth example assigns the result of a mathematical operation on one of our original variables to a new variable:

Command: (* X1 2)
6

Command: (- RVAR X1)
0.000000

Command: (* X1 X1 X1)
27

Command: (setq R2D2 (/ 9.0 RVAR))
3.000000

Some variables are pre-assigned. The value of PI is predefined to be 3.141593:

Command: (setq RTOD (/ 180.0 PI))
57.2958

LIST Function

AutoLISP provides many functions for building and manipulating lists. The (list) function takes any number of elements and strings them together to form a list:

Command: (setq A (list “A” “B” 12.40 24))
Lisp returns: (“A” “B” 12.400000 24)

REVERSE Function

The list may be reversed by using the (reverse) function:

Command: (reverse A)
Lisp returns: (24 12.400000 “B” “A”)

LISTP Function

Functions for testing lists are also included such as (listp), which return T if the test argument is a list, and nil otherwise.

Command: (listp A)
Lisp returns: T

NULL Function

The (null) function returns T if the test argument is bound to nil, and nil otherwise.

Command: (null A)
Lisp returns: nil

LENGTH Function

The number of elements in a given list are determined by the (length) function:

Command: (length A)
Lisp returns: 4

LAST Function

Since lists are a group of elements, you need a way to extract the element that you want. The function (last) returns the last element in a given list, provided the list is not nil:

Command: (last A)
Lisp returns: 24

NTH Function

You can also use another function called the (nth) function which has the form:

(nth <number> <list>)

This function will return the nth element of the <list> specified by the <number> of the element to return (zero being the first). Nil will be returned if the <number> is greater than the highest element number in the <list>.

Command: (nth 2 A)
Lisp returns: 12.400000

CAR Functions

AutoLISP has other built-in functions called (car), (cdr), (cadr), and (cadar), that extract elements within a list. CAR returns the first element of a list and CDR returns a list of all elements, except the first:

Command: (car A)
Lisp returns: “A”

Command: (cdr A)
Lisp returns: (“B” 12.400000 24)

CADR returns the second element of the list and can also be expressed as:

Command: (car (cdr A))
Lisp returns: “B”

Now let’s see how the functions (car), (cadr), and (list) are put together to draw a rectangle.

(setq PT1 (getpoint “nFirst corner: “))
(setq PT3 (getpoint “nSecond corner: “))
(setq PT2 (list (car PT1) (cadr PT3)))
(setq PT4 (list (car PT3) (cadr PT1)))
(command “line” PT1 PT2 PT3 PT4 “c”)

The point list for the variable PT2 is created by extracting the first (X) coordinate from the PT1 list, and the second (Y) coordinate from the PT3 list, creating a new list using the (list) command. The point list for the variable PT4 is created in a similar manner. The line is then drawn from PT1 to PT4 and closed using the “c” option.

Another preset structure is an entity list returned by the (entget) function, which returns an association list and consists of group codes with data:

((-1 . <Entity name: 6000003C>) (0 . “LINE”) (8 . “2″)
(6 . “1″) (62 . 0) (10 1.416586 6.922966)
(11 5.317930 6.689012))

Note that the structure of these lists are determined by AutoLISP and can not be altered by the programmer, but the data inside the lists can be manipulated and changed as we will see later.

Now lets take a closer look at the LISP interpreter. LISP has only one syntax form-the function call. For example:

Command: (setq X (+ 2 4))
Lisp returns: 6

The list (+ 2 4) above is called a sublist. When the List Evaluator sees a list that does not have a single quote in front of the list, it tries to evaluate it. It takes the atom of the deepest sublist (+) and checks to see if there is a function available called “+”. If it finds the function “+” it will pass the arguments to the function to be evaluated. In this example the value returned from the function “+” is 6. When the first sublist is
evaluated, the expression now looks like this to the List Evaluator:

(setq X 6)

The List Evaluator now looks for a function called (setq). The function (setq) says set the value of the atom named in the first argument “X” to the value of the second argument “6″, and return the value of the last evaluated function to the Command line.

Now let’s see what happens when you quote a list. Type the same list into the Command line, but put a quote in front of the sublist like this:

Command: (setq X ‘(+ 2 4))
Lisp returns: (+ 2 4)

Because the list (+ 2 4) was quoted, it wasn’t evaluated by the List Evaluator and it simply set the value of X to the list (+ 2 4). This list may be thought of as data and may be used as a function elsewhere in a program.

User Defined functions are created by using the internal AutoLISP function (defun), which is short for DEfine FUNction. New commands can be added to AutoCAD by using (defun) to define functions implementing those commands. A (defun) function takes the form:

(defun <name> (<arguments> / <local variables>)
  (<expressions>………………..)
)

The <name> portion is simply the name of the function you are defining and must not duplicate any AutoCAD command, built-in or external. The <arguments> following the function name are independent variables that take the values given them when the function is called, and use those values within the function. An optional “/” slash may follow and then the names of one or more <local variables>.

Local & Global Variables

A local variable will only have a value bound to it while the function is executing. Once the function has finished the value of the variable will be set to nil. Variables that are not local are considered global and will retain their value after the function has executed.

By retaining their values, global variables may then be used by other functions. If no <arguments> or <local variables> are to be declared, you must supply an empty set of parentheses ( ) after the function name. Following are examples of functions with local variables and arguments.

Function with no arguments or local variables:
(defun NEWFUNC ( ) ………..)

Function with two local variables:
(defun NEWFUNC (/ C D) ……)

Function with two arguments:
(defun NEWFUNC (A B) ……..)

Function with one argument & one local variable:
(defun NEWFUNC (A / C) ……)

Expressions

One or more <expressions> may then follow the <local variables> that will be evaluated when the function is executed. The following new function will double any number passed to it:

Command: (defun DOUBLE (NUM) (* NUM 2))

This function uses one <argument> and no <local variables> and may be called by another function with the following function call:

Command: (DOUBLE 12)
Lisp Returns: 24

This call to the function (DOUBLE) is simply another list that contains the name of the function as the first element and the value (12) from which the function will derive an answer.

User Defined Commands

New commands may be added to AutoCAD by using a “C:” before the function name following the defun. The function must be of the form “C:NAME” in order for the new command to be entered directly from the Command prompt. The “C:” simply informs AutoLISP to define this function as an AutoCAD command. The <argument> list must be nil but <local variables> are permitted as follows:

(defun C:DOUBLE (/ NUM)
  (setq NUM (getreal “nEnter number to double: “))
  (setq DNUM (* NUM 2))
)

LOAD Function

Functions may be typed using your favorite word processor in ASCI format (or nondocument mode). Several functions may also be grouped into one file as long as the filename has a “.LSP” extension. Before the functions in the “.LSP” file can be used they must be loaded into AutoCAD using the “LOAD” function:

Command: (load <filename>)

Always remember to enclose the <filename> in quotes. Although the file itself must have the required “.LSP” extension, do not include this when loading functions. Once loaded, the name of the last function in the file is returned on the screen. If the LISP file is in another directory you will need to include a path in the LOAD function:

Command: (load “/path/filename”)
or
(load “\path\filename”)

A forward slash ” / ” or two backslashes ” \ ” may be used to indicate the directory that the file is located in.

GET Functions

AutoLISP provides several operator input specific expressions often referred to as the GET expressions. There are a variety of data types that can be input and a result is always returned that is either the type of data requested or nil. Also note that you cannot enter another LISP expression or variable as the response to the AutoLISP GET expressions.

User input in the form of a number is provided by the (getint) and (getreal) functions. These functions will pause for user input from the keyboard. A number, of the proper data type, or nil will be returned as a result of evaluating these expressions.

GETINT Function

The (getint) function pauses for user input of an integer. Entering characters other than whole numbers or the plus/minus will result in the following prompt:

Requires an integer value.
Try again:

This will continue until the proper data type has been input. An optional prompt string may also be supplied:

Command: (setq NUM (getint “nEnter Number: “))
Enter Number: 123
Lisp returns: 123

GETREAL Function

Real numbers are input with the (getreal) function. This function is exactly like (getint) except it pauses for input of a real number. Real numbers are digits [0..9], plus/minus sign, floating point decimals and the exponent characters for scientific notation. Entering an integer returns a real number:

Command: (setq NUM (getreal “nEnter Number: “))
Enter Number: 123
Lisp returns: 123.000000

These commands should not be used to request distances and angles because your entry must be in the lowest units. The indicators for ‘ (feet) and ” (inches) will not be accepted when using this function.

GETDIST Function

The (getdist) function is a better function to use and will accept ‘ (feet) and “ (inches) as valid input when using architectural units.

Command: (setq DIST (getdist “nSelect Two Points:”))
Select Two Points: <Now pick two points>