Because some commands and many Express tools are written in AutoLISP, most of us use AutoLISP programs on a regular basis without knowing it. The C:Program FilesAutoCAD 2007Express directory contains 70 AutoLISP programs, including the following programs that are so useful you might think they're native commands.

You can find other AutoLISP programs at countless websites, in books, in magazines, and on the computers of your friends and colleagues. For a great place to start, visit the Autodesk User Group International website at www.AUGI.com. Other sites come and go, so I won't list them here, but a web search will turn up millions of AutoLISP programs on hundreds of thousands of sites. Many of them are free, because AutoLISP programmers are generous with their work. (Remember this when you become good enough to create useful programs.) Check the copyright information of any program you find, and always follow the author's requirements. After all, an AutoLISP program is the intellectual property of its author.

AutoLISP programs range from simple to complex, and they require a thorough knowledge of AutoCAD commands. Because you already know the AutoCAD command structure, you're ready to start programming in AutoLISP.

I want you to get started writing programs, but to avoid some common pitfalls, you should understand something about the structure of AutoLISP programs. These rules for program structure apply to all AutoLISP programs. They have the same importance to programming that the rules for sentence structure have to writing:

Let's take a computational function as an example. Because the division function in AutoLISP is represented by the forward slash, the syntax for dividing two numbers is as follows: (/ 4.0 2).

An open parenthesis is followed by the function / which is followed by at least one space, which is followed by at least two arguments separated by spaces—the numerator 4.0 and the divisor 2—followed by a closing parenthesis. This function would be translated into English as "divide 4.0 by 2." Other functions, such as (* 4.0 2), (+ 4.0 2), and (− 4.0 2) are formatted the same way. This isn't the same structure you may expect from having studied math, so don't try using (2 + 2). It won't work, because the first element after the parenthesis is an integer, not a function.

You can do all the programming you want in your mind, but until you enter your programs into AutoCAD they won't do anything. Unfortunately, there is no way to dump the contents of your head directly into AutoCAD, so you have to do some typing. There are three ways to get AutoCAD to use an AutoLISP program:

Typing at the command line is generally used only for testing short lines of code. However, I often write a very short program this way when I need to do something that's so specific to the current drawing that there's no reason to save it. I did that recently to create polyline circles. I didn't think I'd need to do it again, so I just wrote a program at the command line. When I exited AutoCAD, the program ceased to exist.

Let's get the command-line procedure out of the way first.

Command-Line Entry

Go back to the program introduced in the introduction to this chapter. To enter that AutoLISP program at the command line, you did this:

1. You typed (defun C:OO()(setvar "osmode" 4143))

   

2. To test the program, you cleared your existing running osnaps.

3. To use the new command you created, you typed OO at the command line. You should have seen "4143" returned.

4. When you checked again, you should have had the following object snap settings: End, Mid, Cen, Nod, Int, Ext.

You just defined a new AutoCAD command with the name OO. When you type it, the setting for OSMODE, which controls your object snap settings, is changed to 4143. That happens to be the value of my standard running osnaps. I like this little command, because I often change to a single running object snap for a series of actions. When I want my old settings back, typing OO is much quicker than opening the Drafting Settings dialog box.

Note

AutoCAD uses system variables (sometimes referred to as setvars) to control many aspects of the program. All of AutoCAD's system variables (there are nearly 550 of them in AutoCAD 2007) can be read from AutoLISP using the GETVAR function, and many of them can be changed using the SETVAR function. OSMODE is such a setvar, for example. The more familiar you are with system variables, the more effectively you can use AutoLISP. You can view all setvars by typing setvar

There's one problem. This nifty new command is stored in RAM, so it won't be available if you open another drawing, and it will disappear if you close the current drawing. If you want to use it again, you have to save it.

Creating and Saving AutoLISP Text Files

To create reusable programs, you must save them in a text file with an .lsp extension. Like the acad.pgp file, AutoLISP files are American Standard Code for Information Interchange (ASCII) text files and can be created in Notepad or any other text editor. However, I far prefer AutoCAD's Visual LISP text editor, which you can start from the command line by typing VLISP or by selecting it from Tools → AutoLISP → Visual LISP Editor.

Figure 8.1. Load/Unload Applications Startup Suite

Once you've saved an AutoLISP file, you can load it using the APPLOAD (AP) command in AutoCAD. If you want it loaded every time you start AutoCAD, put the file in the Startup Suite of the Load/Unload Applications dialog box shown in Figure 8.1.

The Visual LISP Editor

Visual LISP has a couple of quirks. You can start Visual LISP by typing VLISP at the command line, but VLISP is actually an alias for Visual LISP Integrated Development Environment (VLIDE). It differs significantly from programs like Notepad. Because it's integrated into AutoCAD itself, it won't run on its own and must be started from an active AutoCAD drawing. While you're using it, it interacts with the AutoCAD drawing, so you should have an empty or dummy drawing open, not one that matters to you.

Unlike Notepad, the Visual LISP editor uses more than one window while you're editing a file:

• The text editor in which you type your program (more than one can be open)

• The Visual LISP Console, where you can type variable names or try small pieces of code

• The Trace window, which can be used while debugging

• The Build Output window, which shows the results of using the Check Edit Window button to check the program, including warnings and error messages

Figure 8.2. Four windows of the Visual LISP editor

The four different windows are shown in Figure 8.2. Note that in the lower-right corner of the Visual LISP editor window is a report of both the line you're on and the character within that line (L00004 C 00001 in the illustration).

Although this illustration shows the four windows that can be open, they don't normally appear in this form. They may be minimized, placed on top of each other, or otherwise arranged. To keep them straight, notice that the three bottom windows have names that don't change: Visual LISP Console, Trace, and Build Output. You can minimize the Trace window and the Build Output window until you need them. The Visual LISP Console can be used for testing, but be careful—it's not where you type your program. That happens in the text editor, which in the illustration is the top window with the name TXTSCALE.LSP.

The text used in the text editor is displayed using different colors. The default colors are described in Table 8.1.

One more thing before you try your next AutoLISP text program. The tools I think you'll use most often are illustrated in Figure 8.3 on the Visual LISP toolbar. The Load Active Edit Window, Check Edit Window, and Format Edit Window tools apply to the entire file, but each of these buttons has a tool button to its right. These buttons have the same functions but apply only to text you've selected. They're helpful when you're testing only a portion of the file.

Figure 8.3. Selected toolbar buttons from the Visual LISP editor

Table 8.1. Colors Used in the Visual LISP Text Editor

COLOR	USED FOR
Blue	AutoLISP functions like /, DEFUN, and SETQ
Magenta	Strings, which are always between quotation marks
Black	User-created items, such as program variables and function names
Green	Integer values
Teal	Real numbers, which must have a decimal point
Maroon on gray	Comments, which are preceded by a semicolon

Continue Continues running a program that you're testing after it stops at a break point.

Quit Stops the process when you're testing your program by executing it in a controlled fashion.

Note

You'll also see this button if you switch from AutoCAD to the Visual LISP editor while a command is still active. The Reset button won't be available then. You have to go back to AutoCAD and exit the command.

Toggle Breakpoint Stops (breaks) the program at the cursor location as it runs so you can check for errors. A breakpoint is denoted by a red parenthesis.

Activate AutoCAD Switches from the Visual LISP editor to the AutoCAD drawing editor.

Watch Window Opens a window in which you can keep track of the value of your program variables, even local program variables, while debugging your program.

Load Active Edit Window Loads every line of code in the edit window—unless there are errors. The button to its right loads only text in the window that's been selected.

Check Edit Window Checks the structure (balanced parentheses, proper number of arguments, and so on) of the entire contents of the window. The results are displayed in the Build Output window. If an error is detected, place your cursor on the highlighted area in the Build Output window, and double-click to find the error in your program. The button to its right checks only highlighted text in the window.

Format Edit Window Formats the text in the entire window using rules that you can modify if you choose. Formatting doesn't affect how the code runs; it only affects how it looks. Until you have some experience writing AutoLISP programs, you should probably use the default settings. Like the two prior buttons, this one has a version to its right that you can use to format only highlighted text.

Comment Block Adds semicolons in front of the highlighted lines of text so AutoLISP won't try to execute them as part of the program. This is how you annotate your code.

I'll return to some of these tools in the debugging section.

When you double-click the scroll wheel on your mouse, AutoCAD ZOOMs to the extents of your drawing, but that often puts entities too close to the edge of the screen. So, you roll the scroll wheel to zoom out just a little, but the screen zooms out too far. If only there were a command that would zoom to 95 percent of the extents, no matter what the current zoom magnification. Why not create one?

First, you have to identify the steps for performing the task manually. Then you can write an AutoLISP program that will execute the steps automatically.

To do a 95 percent zoom at the keyboard, you would have to go through the following steps:

The solution here is to combine all four steps into a single new AutoCAD command named ZX. To create the program, use the following steps:

That's it. These three lines compose an entire AutoLISP program, which creates a new command named ZX that can be typed at the command line like any other command. By duplicating this basic format, you can create hundreds of other new commands. Make sure you review and understand the following explanations for each line:

(defun C:ZX () This line begins with an opening parenthesis, indicating to AutoCAD that an AutoLISP function will follow. You must enclose all elements in parentheses, and you must have a closing parenthesis for every opening parenthesis. Notice that this line has two opening, but only one closing, parenthesis. The second closing parenthesis appears at the end of the program on line 3, all by itself.

An AUTOLISP expression name must appear first after an opening parenthesis. The word DEFUN is an AutoLISP expression, which stands for define function. It's blue when you type it in the Visual LISP editor.

The C:ZX means that the AutoLISP function you're defining will operate as if it were an AutoCAD command. This code is black when typed in the Visual LISP editor. The C: means new AutoCAD command. ZX is the name of the new AutoCAD command you're creating, which can be called like any native command—typed, assigned to a toolbar button, assigned to a key, added to a cursor menu, or assigned to a mouse button. You can name your new command nearly anything you want except an existing command name. Well, you could use an existing command name if you undefined the command first, but let's avoid using existing commands or aliases for now. ZX makes sense to me—your command names should make sense to you.

The two parentheses () at the end of the line are empty for this program, but they must be there. In other programs, they may contain arguments or user-defined local program variables—more on that later.

(command "._ZOOM" "_E" "._ZOOM" ".95x") Once again, you start with an open parenthesis, so the first thing to appear must be the AutoLISP function. The COMMAND AutoLISP function allows you to use any native AutoCAD command within a new AutoLISP program. Use a command here, not an alias. "ZOOM" will work, but "Z" won't. Placing the dot and the underscore before the command name is optional.

This line of the code controls what happens on the screen when you use the ZX command. It issues the AutoCAD ZOOM command, followed by the E option. Then, it issues the ZOOM command again, followed by the scale option .95x. The entire line must be enclosed in parentheses. Anything you would normally type at the keyboard must be enclosed in quotes. In AutoLISP, anything in quotes is known as a string. Spaces between a closing quote and the next opening quote aren't necessary, but they make it easier to read your code.

Note

When you place a command like "ZOOM" in quotes, it's the same as typing it at the command line in AutoCAD followed by a

) This line is simple: It closes the first parenthesis in the program. Placing it by itself at the end of a program makes it easier for you to see where each program ends and to match it with its opening parenthesis. When you're trying to debug a program, formatting parentheses in this way is very helpful.

The Visual LISP editor does some formatting of your code as you type, and most AutoLISP programmers do even more as they're writing (or coding). Use the Format Edit Window button to clean up the whole program when it's done.

A cardinal rule of programming is to reuse code (either yours or someone else's) whenever possible. With these three lines, you have the basic syntax to write dozens of new commands. ZA and ZP require only that you simplify the command by replacing E with A and removing the second call to the ZOOM command. Other commands can be substituted for ZOOM, with their own options. Once you understand the format for creating these commands, the sky is the limit.

circle-dia.lsp
        (defun C:C()
          (command "._CIRCLE" pause "D")
        )

Inserting Drawing Files

Now let's apply what you've learned to a new command that will automatically insert an existing title block drawing into the current drawing (see Listing 8.2). You've already seen almost everything you need in order to understand this. In order to try the program as it's written, you have to place a title block drawing with the name tbinch.dwg in C:locks. When you're done typing, select the Load Active Edit Window tool again.

Each line of this code is described in Table 8.3.

Example 8.2. Listing 8.2

ITB.lsp
        (defun C:ITB()
          (command "._INSERT" "c:/blocks/tbinch.dwg" "0,0" "" "" "")
        )

Table 8.3. ITB.lsp

LINE OF CODE	PURPOSE
(defun C:ITB()	This line defines a new command named ITB. I use uppercase for command names, but that isn't necessary.
(command "._INSERT" "c:/blocks/ tbinch.dwg" "0,0" "" "" "")	This line executes the AutoCAD INSERT command, gives the path and name of a file to insert, places it at 0,0, and accepts the next three default settings for X-scale, Y-scale, and rotation.
	Notice anything about the path? You can't use a backslash to separate folders in AutoLISP. You can use a double backslash or a single forward slash.
	The other thing to notice is that using the three pairs of double quotes is equivalent to entering
)	This closing parenthesis matches the opening parenthesis and ends the DEFUN function.

Note

When you try the steps of this program at the command line in AutoCAD, suppress the dialog box that normally pops up by placing a minus in front of the command. -INSERT is the command-line version of INSERT. Do the same for the LAYER command. You don't have to include the dash within your program. AutoLISP understands when not to open a dialog box.

Using Variables

Let's clear up any potential confusion about the term variables. AutoCAD has something called system variables; these are values that control the appearance or behavior of AutoCAD in some way. OSMODE is a system variable. You can determine the current setting for any system variable using the GETVAR function with the format (getvar "osmode").

You can also define your own program variables. You create these using the SETQ function of AutoLISP. The program variable you define can be used to represent almost anything: numbers, entities, anything typed by the user lists of coordinates, and so on.

To further complicate this distinction, the program variables that you define can be either global or local. If they're global, then once they're assigned a value of some kind, they keep that value even when your program is finished running. If the same variable name shows up again, it already has a value. To avoid unintended consequences, most users define program variables in AutoLISP programs as local—but not until they finish testing the program to make sure it works.

The program that created ZX required no additional information, either from the drawing or from the user. The ITB program you just wrote doesn't either, but maybe you can improve it. Wouldn't it be nice if the program automatically placed the title block on a particular layer? And wouldn't it be nice if it created the layer automatically after asking the user for a layer name and color? Although you'd probably prefer to put a standard layer name and color into the program by using a template, I'll show you the program in Listing 8.3 anyway, so you'll know how to get input from the user and save it to a program variable.

Example 8.3. Listing 8.3

InsertTB.lsp
        (defun C:InsertTB (/ lname lcolor ss1)
          (setq lname (getstring T "
Destination layer: "))
          (setq lcolor (getstring "
Layer Color: "))
          (command "._INSERT" "c:/blocks/tbinch.dwg" "0,0" "" "" "")
          (setq ss1 (entlast))
          (command "._LAYER" "N" lname "C" lcolor lname ""
                    "_CHPROP" ss1 "" "LA"      lname "")
        )

Each line of this code is described in Table 8.4. An explanation of the new functions follows.

Table 8.4. InsertTB.lsp

LINE OF CODE	PURPOSE
(defun C:InsertTB(/ lname lcolor ss1)	This line defines the new function that will act as a command named InsertTB with three local program variables. Local program variables are added here when you've finished the program and you know it works. Until you place them in this location, they're global program variables, not local.
(setq lname (getstring T " Destination layer: "))	This line sets the variable lname equal to whatever the user types in response to the prompt Destination Layer:. The T after getstring allows spaces to be included in the name. The is a control character meaning new line that tells AutoCAD to display the prompt on its own line. It must be lowercase.
(setq lcolor (getstring " Layer Color: "))	This sets the variable lcolor equal to what the user types in response to the prompt that follows.
(command "._INSERT" "c:/blocks/ tbinch.dwg" "0,0" "" "" "")	This executes INSERT, identifies the path and name of the drawing to insert, gives 0,0 as the insertion point, and accepts the default values of 1, 1, and 0 for the options X-scale, Y-scale, and rotation.
(setq ss1 (entlast))	This line uses the function ENTLAST to set variable ss1 equal to the last object created, which is the inserted title block.
(command "_LAYER" "N" lname "C" lcolor lname "" "_CHPROP" ss1 "" "LA" lname "")	This line creates a new layer if it doesn't already exist, giving it the name stored as a string in lname and the color saved in lcolor. Then it executes another AutoCAD command, CHPROP, selects the object represented by the variable named ss1, issues
)	This line closes the DEFUN statement.

This program is a little more involved and introduces three new functions:

• SETQ creates program variables so values can be saved and used later in the program. There's a more involved discussion of the SETQ function later in the chapter, but you don't need to know anything else about it for now. Just use it as shown to store data.

• GETSTRING is a function that returns anything the user types at the keyboard. If you want users to be able to type something that contains spaces, you must include the letter T as one argument—(getstring T " Name of layer: "). The T can be either uppercase or lowercase, but the must be lowercase.

• ENTLAST selects the last entity created. Then, that entity can be assigned to a program variable.

Three program variables are created by the program: lname, lcolor, and ss1. I just made up their names. You can give program variables nearly any name, but here are some things to keep in mind:

• Use variable names that will make sense to you a month from now when you may be trying to understand what your program does. I use a consistent naming convention for similar types of program variables. If I have multiple program variables representing selection sets, strings points, angles, distances, radiuses, diameter, and so on, I try to use program variables names like ss1, st1, pt1, ang1, dist1, rad1, and dia1. However, this system works only on relatively simple programs. On longer programs, you should use more descriptive names.

• Don't use existing AutoLISP functions as variable names. You'll know you've done so when the name is colored blue instead of black when you type it into the Visual LISP editor. For example, PI, SET, and SETQ are AutoLISP functions and shouldn't be redefined as program variables. Once you've redefined a built-in function, it's no longer interpreted as a function.

• You can use numbers in variable names, but a variable name can't be all numbers. The name must include at least one letter and no spaces; the only other characters allowed are $, _, <, >, and -.

GETSTRING isn't the only GET function. Table 8.5 shows all the functions designed to get information, with a brief description of each. These functions get information from the user, the drawing, or the environment (operating system).

Let's use some GET functions in another program to demonstrate how you can take points apart and put them back together.

Two methods are especially useful for creating new points from user input. The first is to construct new points by calculating an X, a Y, and a Z coordinate, and then putting them into a list of three values using the LIST function. The second is to determine how far and at what angle a point is from another point, using the POLAR function.

Creating Points from Coordinates

In this next program, the user is prompted for two points. The program draws a rectangle using those points as corners and then adds lines across the corners to create an end-section symbol for a piece of structural lumber.

Example 8.4. Listing 8.4

SSECT.lsp
        (defun C:SSECT (/ pt1 pt2 pt3 pt4)
          (setq pt1 (getpoint "
First corner of rectangle: "))
          (setq pt2 (getcorner "
Diagonal corner of rectangle: " pt1))
          (setq pt3 (list (nth 0 pt1) (nth 1 pt2)))
          (setq pt4 (list (nth 0 pt2) (nth 1 pt1)))
          (command "._RECTANG" pt1 pt2 "._LINE" pt1 pt2 "" "._LINE" pt3 pt4 "")
        )

Each line of this code is described in Table 8.6.

Table 8.6. SSECT.lsp

LINE OF CODE	PURPOSE
(defun C:SSECT (/ pt1 pt2 pt3 pt4)	This line creates a new command named SSECT and identifies the program variables as local. Local variables retain the value given to them only while the program is running. If you hadn't placed them in the parentheses, they would be global program variables and would retain their values after the program ended. Note the space after the forward slash.
(setq pt1 (getpoint " First corner of rectangle: "))	This line sets the variable pt1 equal to a point supplied by the user. The quoted string will be displayed at the command line. The (must be lowercase) is a control character that means new line. If you leave it out, the prompt is placed on the same line in the AutoCAD command window as the last information printed there.
(setq pt2 (getcorner " Diagonal corner of rectangle " pt1))	This line sets the variable pt2 equal to the point supplied by the user in response to the prompt for the GETCORNER function. GETCORNER differs from GETPOINT because it displays a rectangle on the screen as the user moves the cursor to select the second point. Note that the first point (pt1) must be referenced in this line either before or after the prompt.
(setq pt3 (list (nth 0 pt1) (nth 1 pt2)))	Working from the inside out, you can say that this line takes the X value of pt1 and the Y value of pt2 and combines them into a new point.
	In AutoLISP, a coordinate point is a list of three values. To create a new point, you need to create a list of at least two values. The function LIST is used to create a new list.
	To create pt3, you use the X coordinate of pt1 using (nth 0 pt1) and the Y coordinate of pt2 using (nth 1 pt2). The list of two values is assigned to the variable pt3 by the SETQ function.
(setq pt4 (list (nth 0 pt2) (nth 1 pt1)))	This line sets the variable pt4 equal to the X value of pt2 (nth 0 pt2) and the Y value of pt1 (nth 1 pt1) and combines them using LIST to create a new list, which is assigned to variable pt3 using the SETQ function.
(command "._RECTANG" pt1 pt2 "._LINE" pt1 pt2 "" "._LINE" pt3 pt4 "")	Now that you have program variables representing the four points, the rest is easy. The COMMAND function is used to call up the RECTANG command and feed it pt1 and pt2, which draws a rectangle. While the COMMAND function is open, you can call another AutoCAD command, LINE, and use your four points to create the two lines of the section symbol.
)	This closes the DEFUN function, as you've seen before.

Creating Points with Distances and Angles

The POLAR function lets you create a new point from an existing point when you know, or can calculate, how far and at what angle from the existing point you want the next point to appear. The example in Listing 8.5 uses the POLAR function to calculate a point halfway between any two points selected by the user. It then uses the AutoCAD POINT command to place a point at that location. The purpose of the program is to provide a convenient means of adding dimensions to floor plans when the location of walls is determined to their center. Because there's nothing that you can snap to between the lines representing walls, dimensioning them can be tricky. But if you place points there, the Node object snap can be used as the origin of dimensions. If you want a better view of the points, set a new point style by choosing Fomat → Point Style and picking one you like.

This program uses the SETVAR function seen in the first program you wrote; it demonstrates how to change existing system variables and then politely return them to their original form. This program, like all programs, should have error trapping, but I'm leaving that subject for Chapter 9, "AutoLISP by Example: Getting Better."

Each line of this program is described in Table 8.7.

Example 8.5. Listing 8.5

mid.lsp
        (defun C:MID (/ pt1 pt2 os ap mid)
          (setq os (getvar "osmode")
                ap (getvar "aperture"))
          (setvar "osmode" 512)
          (setvar "aperture" 3)
          (initget 1)

(setq pt1 (getpoint "
First point: "))
 (initget 1)
 (setq pt2 (getpoint "
Second point: " pt1))
 (setq mid (polar pt1
           (angle pt1 pt2)
           (/ (distance pt1 pt2) 2.0)))
 (command "._POINT" "non" mid)
 (setvar "osmode" os)
 (setvar "aperture" ap)
 (princ)
)

Table 8.7. mid.lsp

LINE OF CODE	PURPOSE
(defun C:MID (/ pt1 pt2 os ap mid)	Defines the new function that will act as an AutoCAD command. Each variable is made local.
(setq os (getvar "osmode")	Gets the current value of the OSMODE variable from the drawing and stores it by assigning it to variable os. You do this because the program will change OSMODE, and you want to change it back when the program is complete.
ap (getvar "aperture"))	Gets the current value of the APERTURE variable from the drawing and stores it by assigning it to variable ap. If the aperture is too large, it can be difficult for the user to snap to a line in a cluttered area. Because the program will change the setting for this variable, you need to save the current setting so you can change that back also.
(setvar "osmode" 512)	Sets OSMODE to 512, which is the Nearest osnap.
(setvar "aperture" 3)	Sets APERTURE to 3 pixels to make it small enough to prevent snapping to the wrong line on the drawing.
(initget 1)	Prevents the user from using a
(setq pt2 (getpoint " Second point: "))	Prompts the user to select the first point, and then assigns the point they selected to the variable pt1 as a list of three values: X, Y, Z of the point.
(initget 1)	Prevents
(setq pt2 (getpoint " Second point: " pt1))	Prompts the user to select the second point, and then assigns the point they selected to the variable pt2 as a list. Referencing pt1 after the prompt causes a rubber-band line to be used from pt1 during the selection.
(setq mid (polar pt1	Assigns a value to the variable mid using the POLAR function. That function requires a starting point, which is given in this line as pt1. The next two lines complete the SETQ function that is started here.
(angle pt1 pt2)	Provides the angle needed by the POLAR function by using the ANGLE function to determine the angle from pt1 to pt2.
(/ (distance pt1 pt2) 2.0)))	Provides the last piece of information needed by the POLAR function. The distance is calculated so that variable mid can be assigned a point halfway between pt1 and pt2. To calculate that distance, the / function is used to divide the distance between pt1 and pt2 by the real number 2.0.
(command "._POINT" "non" mid)	Uses the AutoCAD command POINT to place a point at the location assigned to the variable mid. "non" is used to temporarily turn off the running osnap so it can't override the location by snapping to an object.
(setvar "osmode" os)	Resets the AutoCAD variable OSMODE to the value it had at the beginning of the program.
(setvar "aperture" ap)	Resets the AutoCAD variable APERTURE to the value it had at the beginning of the program.
(princ)	Prints a clear line at the command prompt to prevent the program from returning the value nil.
)	Ends the DEFUN function.

AutoLISP programs often require mathematical calculations, so this is a good time to reiterate the syntax of all AutoLISP functions. The function always comes first, immediately after the opening parenthesis in AutoLISP. The function is then followed by arguments. AutoLISP uses two kinds of numbers: integers, which have no decimal point; and real numbers (also known as floating-point decimals), which have a decimal point but no other characters. $1.00 isn't a real number, but 1.00 is.

Calculating Within a Program

The program in Listing 8.6 converts from inches to millimeters. As you know, 25.4 millimeters equals 1 inch. After trying this program, see if you can write a program that does the conversion in the other direction—from millimeters to inches.

Figure 8.5. Using an alert box in AutoLISP

Each line of this code is described in Table 8.8.

The result of using this program to convert 126.78″ into millimeters is shown in Figure 8.5.

Example 8.6. Listing 8.6

I2M.lsp
        (defun C:I2M (/ in mm st1 st2)
          (setq in (getdist "
Value in inches: "))
          (setq mm (* in 25.4))
          (setq st1 (rtos in 2 3))
          (setq st2 (rtos mm 2 2))
          (alert (strcat "Value of " st1 " inches is " st2 " mm"))
          (princ)
        )

Table 8.8. I2M.lsp

LINE OF CODE	PURPOSE
(defun C:I2M (/ in mm st1 st2)	Defines a new command function, and identifies local program variables.
(setq in (getdist " Value in inches: "))	Sets the variable in equal to a real number that's either typed or returned by picking two points.
(setq mm (* in 25.4))	Sets the variable mm equal to the result of multiplying the variable in by 25.4.
(setq st1 (rtos in 2 3))	Converts a real number into a string using the AutoLISP function RTOS. The value is reported in an alert box. The integers 2 and 3 used here control the format in which the numerical string is displayed. In this case, it will be in decimal format to a precision of three decimal places. The string is assigned to variable st1.
(setq st2 (rtos mm 2 2))	Performs the same conversion as the previous line for the metric value stored in mm. It's also in decimal format, but only to two decimal places, which is more likely when using metric. This string is assigned to variable st2.
(alert (strcat "Value of " st1 " inches is " st2 " mm"))	Displays a string in a dialog box using the ALERT function. In this case, you have several strings that you want displayed. Because ALERT accepts only a single string as an argument, all the pieces must be added together into one long string. That is what STRCAT does: It concatenates the strings that follow it into one string.
(princ)	Prints a clear line.
)	Closes the DEFUN function.

Note

The values used with the RTOS function to format units are the same values used for the LUNITS system variable in AutoCAD. They're shown in the next section.

Converting Between Radians and Degrees

Why do computers use radians? It's faster and more accurate to do complex computations when using radians, so that's what computers use to compute angles. Table 8.9 shows how radians compare to degrees.

WHAT'S A RADIAN?

Geometrically, a radian is the angle between two lines drawn from the center of a circle that create an arc with an arc length equal to the radius. One radian is a little less than 57.30 degrees. Why do you have to know this? Because if you think you're giving your AutoLISP program an angular measurement in degrees, but the program interprets it as radians, you can get some odd results.

What do you do when you have a program that rotates objects, but it doesn't give you the results you expect? First, recognize that if you think an object should rotate 90°, and it appears to rotate about 117°, you're probably feeding a value in degrees (90) into a function that expects radians (approximately 1.507). Rotating something 90 radians would require 14.3239 full revolutions. That 0.3239 of a revolution lands at about 117°. Likewise, if you thought you were feeding radians into your program but the result is a rotation of a few degrees, you should probably be using degrees instead.

Table 8.9. Degrees and Radians Compared

DEGREES	RADIANS
0	0
90	ω/2
180	ω
270	3ω/2
360	2ω

The sample program in Listing 8.7 rotates a copy of a selection set using a base point and rotation angle provided by the user. You can rotate and copy with grips, but it involves several steps. In AutoCAD 2006, the ROTATE command has a Copy option, but if you need this function often, a dedicated command would be helpful.

The following code illustrates the problems new programmers often have with angles. You may think it looks like it will work, but it won't give you the results you probably expect. Try it. When you type 90, hoping to rotate a copy of the object 90°, you'll get the results shown on the right in Figure 8.6 instead. What's wrong?

Example 8.7. Listing 8.7

rc_broken_version.lsp

        (defun c:rc(/ ss1 pt1 ang1)
          (setq ss1 (ssget))
          (setq pt1 (getpoint "
Basepoint: "))
          (setq ang1 (getangle "
Angle of rotation: "))
          (command "._COPY" ss1 "" pt1 pt1
                   "._ROTATE" ss1 "" pt1 ang1)
        )

Each line is described in Table 8.10.

There's a clue in the command line shown with the object in Figure 8.6. When prompted for a rotation angle, I typed in 90, but the command line shows 1.570796326794897. That looks like ½ of ω. If you look at Table 8.9, 90 = ω/2. AutoLISP must have converted the 90 into radians. It did, because I used the GETANGLE function.

Table 8.10. rc_broken_version.lsp

LINE OF CODE	PURPOSE
(defun c:rc( ss1 pt1 ang1)	The new command is named RC.
(setq ss1 (ssget))	The SSGET function prompts the user to make a selection set. The selection in this case is assigned to the variable ss1.
(setq pt1 (getpoint " Basepoint: "))	The point provided in response to GETPOINT is saved as variable pt1.
(setq ang1 (getangle " Angle of rotation: "))	The angle provided in response to GETANGLE is saved as variable ang1. This creates a problem, because the value is returned in radians. If 90 is typed or selected, 1.570796326794896 is returned. Your objects rotates only about 1.6 degrees when the value is fed to the ROTATE command.
(command "._COPY" ss1 "" pt1 pt1	The selected objects are copied directly on top of themselves. Note that there is no closing parenthesis, so the next line is part of this one.
"._ROTATE" ss1 "" pt1 ang1)	This line is part of the COMMAND function in the previous line. Your original selection set is rotated at the base point by ang1. You expect the results on the left in Figure 8.6, but you get the results on the right.
)	This line ends the DEFUN function.

Figure 8.6. Results of using degrees instead of radians

Oddly enough, this program would have worked fine if I'd used GETSTRING instead of GETANGLE, because the value is supplied to the ROTATE command literally. I didn't use GETSTRING, however, because it doesn't allow the user to pick two points at the prompt. That would make this program behave differently from every other AutoCAD program, which is something you should make every effort to avoid.

Now that you know why your program may be acting up, let's see how you can fix it by creating a new function that can be called in other functions.

CREATING AUTOLISP FUNCTIONS: RTD AND DTR

Before we look at the code required to fix this problem, let's clarify one important AutoLISP concept. There are two different kinds of functions. The kind you've been writing act like AutoCAD commands. Without the C: as part of the function name, it doesn't act like an AutoCAD command, but it can be used as an AutoLISP function. This is pretty potent stuff: You can create your own AutoCAD commands using AutoLISP functions, and you can define your own AutoLISP functions too. Now that's power! Let's solve the conflict between radians and degrees with a new AutoLISP function or two.

You'll find the code in Listing 8.8 in virtually every AutoLISP reference book, because every AutoLISP programmer runs into the radians/degrees problem at some point. Notice that the two new functions are a little different from the programs you've been writing, in two ways: They don't have a C: in front of the function name, and they have a single argument in the parentheses after the function name instead of the name of local program variables. RTD converts radians into degrees, and DTR converts degrees into radians.

Example 8.8. Listing 8.8

angconv.lsp
        (defun rtd (r)
           (* 180.0(/ r pi))
        )  ;end defun

        (defun dtr (d)
           (* pi (/ d 180.0))
        )  ;end defun

Table 8.11 describes this program.

Because 180° = ω radians, the math here is easy. Degrees = (180 × radians)/ω. Using the structure of AutoLISP, you'd say "multiply 180 times the result of dividing radians by ω." Because functions always come first, the AutoLISP code reads (* 180 (/ r pi)) where r = radians. Once you write these two conversion functions, they must be loaded before you can use them. You could load them manually each time you want to use them, but there are some automatic ways to load AutoLISP programs so they're always available. In this case, I'd place the functions in a file named acaddoc.lsp, which is discussed later in this chapter.

Note

For clarity, I display most of the programs in this chapter as individual LSP files. It's also possible to combine many AutoLISP programs into a single LSP file. Each one starts and ends with a DEFUN function.

Table 8.11. angconv.lsp

LINE OF CODE	PURPOSE
(defun rtd (r)	This line defines a function named RTD. The r is the argument necessary for this function. Any letter can be used. Notice that there's no C: and no /
(* 180.0(/ r pi))	The value provided, r, is divided by ω and multiplied by 180.
);end defun	This line ends the DEFUN function and places a note to that effect to make it easier to find the end of each function in a file that contains multiple AutoLISP programs.
	This is a blank space for clarity, which is OK anywhere in an AutoLISP program.
(defun dtr (d)	This line defines a function named DTR. The d is the argument necessary for this function. Any letter can be used. Notice that there's no C: and no /.
(* pi (/ d 180.0))	The value provided as an argument is divided by 180 and multiplied by ω.
);end defun	This line ends the DEFUN function and places a note to that effect to make it easier to find the end of each function in a file that contains multiple AutoLISP programs.

The two angular conversion functions can be executed at the AutoCAD command prompt using the same format you use in a program: (rtd 2) converts 2 radians into degrees and returns 114.592; (dtr 30) converts 30° into radians and returns 0.523599.

Listing 8.9 shows how the rc.lsp program looks if you use the RTD function to convert the angle from radians to degrees before using it. The RTD function must be loaded before it can be used.

Example 8.9. Listing 8.9

rc.lsp
       (defun c:rc(/ ss1 pt1 ang1)
         (setq ss1 (ssget))
         (setq pt1 (getpoint "
Basepoint: "))
         (setq ang1 (rtd (getangle "
Angle of rotation: ")))
         (command "._COPY" ss1 "" pt1 pt1
                  "._ROTATE" ss1 "" pt1 ang1)
       )

It's a subtle difference. In the fourth line, the RTD function is used before the GETANGLE function, requiring one more set of parentheses. You may find it easier to understand how the RTD function works if I rewrite it to add an additional step. Listing 8.10 adds one more line that redefines the variable ang1. Note the inline annotation that follows the ; in line 5. Don't be surprised to see the program variable ang1 appear twice on that line. That's how program variables are assigned a new value that's based on their existing value. It's very logical.

Example 8.10. Listing 8.10

rc2.lsp
         (defun c:rc(/ ss1 pt1 ang1)
           (setq ss1 (ssget))
           (setq pt1 (getpoint "
Basepoint: "))
           (setq ang1 (getangle "
Angle of rotation: "))
           (setq ang1 (rtd ang1));converts ang1 from radians to degrees
           (command "._COPY" ss1 "" pt1 pt1
                    "._ROTATE" ss1 "" pt1 ang1)
         )

Note

A point about multiple releases: If you think this program could be simplified by using the Copy option of the ROTATE command, you're right. However, prior to AutoCAD 2006, ROTATE had no Copy option. The code as written here (command "._COPY" ss1 "" pt1 pt1 "._ROTATE" ss1 "" pt1 ang1) works in any release, not just those since AUTOCAD 2006. That's good practice when writing code.

Using AutoLISP Functions Transparently

You know that you can execute AutoLISP functions directly from the command line, but you may wonder if the command line has to be empty. It doesn't. You can run an AutoLISP function transparently while you're in a command. Let's create an AutoLISP function that converts inches into millimeters and that you can use on the fly when drawing or editing in AutoCAD. You already created an AutoCAD command to do this earlier, so creating a function requires only that you modify the program with a little editing; see Listing 8.11.

Example 8.11. Listing 8.11

ii.lsp
       (defun ii (in)
         (* in 25.4)
        )

Let's say you're using the LINE command, and you've selected a start point and established a polar tracking line. You know the length of the line in inches, but you're in a metric drawing. Can you have AutoCAD convert into millimeters while you're drawing the line? Here's how. Once you've loaded the II function, use it in response to a request for input. Just remember to type the parentheses. And if the number is smaller than 1, you must include the leading 0, as shown in Figure 8.7.

Note

You can't use this system in a dialog box, nor can it follow the @ symbol. But it works great for values that can be entered at the command line; particularly direct distances.

Figure 8.7. Using AutoLISP functions transparently

Combining AutoLISP Functions

When you're writing a new program, don't overlook programs that you or others have already written. One of the reasons I use so many examples in this chapter is to provide sample code for you to copy into other programs for a variety of situations.

Let's take an element from rc2.lsp, the Rotate/Copy program, and add it to the structural section program ssect.lsp so the symbol can be drawn at any angle. You'll borrow lines 4 and 5 from rc2.lsp and use them to get an angle for rotating the UCS before calculating the points for the other two corners of the rectangle, as shown in Figure 8.8.

First, copy the RTD function and both programs into a new file—you don't want to mess up programs that already work. Next, open a space in the C:SSECT program and copy the key lines from the C:RC function, which is below it. Delete the entire C:RC function so none of that code interferes with your new program. Then, make a few more changes so you can use the new angle to rotate the UCS; see Listing 8.12. Of course, if your program changes a system variable, don't forget to change it back—see the error-checking section in Chapter 9.

Figure 8.8. Borrowing code

Example 8.12. Listing 8.12

structural_section.lsp

         (defun C:SSECT (/ ang1 pt1 pt2 pt3 pt4)
           (setq ang1 (getangle "
Angle of structural section: "))
           (setq ang1 (rtd ang1))
           (command "._UCS" "Z" ang1)
           (setq pt1 (getpoint "
First corner of rectangle: "))
           (setq pt2 (getcorner "
Diagonal corner of rectangle " pt1))
           (setq pt3 (list (nth 0 pt1) (nth 1 pt2)))
           (setq pt4 (list (nth 0 pt2) (nth 1 pt1)))
           (command "._RECTANG" pt1 pt2 "._LINE" pt1 pt2 "" "._LINE" pt3 pt4 "")
           (command "._UCS" "P")
         )

Figure 8.9 shows the command in action. It would be nice if the rubber-band rectangle rotated with the UCS, but I want to keep this program simple for now. As you can see in Figure 8.10, when the command is used to place the two structural section symbols, you get the result you want.

You may also be thinking that the user should be able to press

Figure 8.9. Using C:SSECT

Figure 8.10. Result of C:SSECT

TEN BASIC RULES FOR AUTOLISP PROGRAMMING

I hope this chapter gets you interested in developing your own AutoLISP programs. I chose the programs for this chapter to give you examples of how AutoLISP programs are structured, and how many of the most useful functions can be used. This isn't the whole story, of course. Chapter 9 contains some important additions, including strategies for debugging your programs, techniques for adding error trapping to your programs, methods for annotating programs, and some more advanced examples of functions, including IF, WHILE, and COND functions.

Now that you have a handle on programming, here are some basic rules you should follow:

1. Save your programs as ASCII text files.

2. There must be an equal number of opening and closing parentheses. The last closing parenthesis generally appears alone on the last line.

3. DEFUN means define function. It's followed by the name of the function you're defining. If the name includes the C:, you've defined a function that can be used as a new AutoCAD command. If it doesn't, the function can be used in the form (dtr 180) either in another AutoLISP routine or at the command line.

4. Manage your quotation marks. Every opening quote requires a closing quote. If you want to accept a default in a command, "" will do it because it represents a

   

5. The backslash has a meaning in an AutoLISP program, and it isn't used to separate subdirectories. (To do that, use a forward slash or a double backslash.) To insert a drawing using AutoLISP, the program line looks like this: (command "._INSERT" "c:\dwg\dsize.dwg" "0,0" "1" "1" "0").

6. The parentheses after the DEFUN expression can have two kinds of values: argument names or variable names. When local program variables are included, they must be preceded by both a space and a forward slash. If the parentheses are empty, the function has no arguments and all the program variables in the function are global. Place variable names here only after you know your program works. And don't forget to leave a space after the forward slash. You can check the value of a global variable by typing it at the AutoCAD command line preceded by a exclamation point (!varname) or by typing the variable name in the Visual LISP Console.

7. To get a new line for a prompt to the user, always place the characters (a lowercase n) after the opening quote and before the text of the prompt.

8. Use one or more semicolons before comments.

9. When designing a program, get any values you need from the user or the drawing at the beginning of the program. Use the SETQ function to assign the values to program variables so you can use the values later in the program.

10. Don't get discouraged if a new program doesn't work the first time. It probably won't; that's what makes programming so interesting.

We looked briefly at the Load/Unload Applications dialog box earlier in the chapter. It can be used to load all kinds of programs, not just AutoLISP. The file extensions don't always tell you exactly what kind programming language was used to create them, so let's look at them in Table 8.12.

Any programs with these file types can be placed in the Startup Suite, but think about what you put in there. You should place program files in the Startup Suite only if you want constant access to them. Suppose you have a complex stair-design program that you use only once in a while. You can use the APPLOAD command to load it only when you want to use it. If you have a complex program to help you design cams, on the other hand, and you use it every day, it should be in the Startup Suite.

AutoCAD doesn't ship with either an acaddoc.lsp file or an acad.lsp file, but if you create either one, AutoCAD recognizes them and automatically loads them on startup. It's like using the Startup Suite, with a difference: The Startup Suite is loaded only for the user who puts files in it. If either an acaddoc.lsp or an acad.lsp file is placed in the AutoCAD search path, its programs load for all users.

What's the difference between an acaddoc.lsp file and an acad.lsp file, and why are there two of them? Well, for historical reasons. For as long as I've used AutoCAD, it's been possible to place programs in a file named acad.lsp, put the file in the search path of AutoCAD, and have the file automatically load when AutoCAD starts up. But when AutoCAD was updated in AutoCAD 2000 to allow multiple drawings to be opened in a single session, acad.lsp was assigned the behavior of loading only for the first drawing opened or created in any one session. The acaddoc.lsp file became an alternative to the acad.lsp file because it loads in each new drawing as it's opened or created.

If you have a file named acad.lsp from an earlier era and want it loaded with every drawing, either rename it acaddoc.lsp or set the variable ACADLSPASDOC to 1. Doing so forces AutoCAD to treat an acad.lsp file as though it's an acaddoc.lsp file.

There is another file that loads AutoLISP programs automatically if you're using a release prior to AutoCAD 2006. The acad.mnl file contains AutoLISP code that is loaded whenever the acad.mns file is loaded. It contains a number of functions that work in conjunction with the menu file. Now, with the CUI, that file exists but contains no code. In its place is a file name acad2007doc.lsp, which loads automatically in each drawing and defines a number of command functions using AutoLISP. I suggest that you avoid editing this file so you don't inadvertently change the behavior of the commands it contains. If you want programs to load automatically, add them to an acaddoc.lsp file.

I hope that after reading this chapter, you want to develop some of your own LSP files. If so, you'll have to decide how to manage them. Do you want them loaded all the time, only once, or only when you need them? As you develop more AutoLISP programs, I recommend you use the following steps:

While we're on the subject of automatic loading, let's look at one special AutoLISP function that is often placed at the beginning of the acaddoc.lsp file. The S::STARTUP function runs an AutoLISP program as soon as acaddoc.lsp is loaded. The user doesn't have to do anything. This can be handy for setting system variables, creating automatic layouts, and adding layers—processes that can also be completed with template files and profiles, of course; but that you may want to automate. The S::STARTUP function is occasionally used for undefining commands so they can be replaced with your own definitions.

Why replace an existing command with a new definition? Maybe you don't like the new-fangled version of a command, and you want it to behave like the old command it replaced. You can undefine the new one and create a new definition that just calls up the old one. The Help system in the Visual LISP editor uses the HATCH and BHATCH commands as an example.

You may also want certain things to happen whenever someone uses a particular command. Perhaps you want all text to be placed on a specific layer. You can undefine the MTEXT command and then define a new one that sets a text layer current. If you want to keep yourself from accidentally placing dimensions in Paper Space, you can replace the standard dimension commands with ones that check to see whether a layout is active before placing dimensions.

Listing 8.13 shows an example of how you can use the S::STARTUP function if you want to force yourself to use polylines instead of lines, and you want to make sure polylines are always drawn on the OBJ layer. Note that the REDEFINE command can be used to redefine a native command that has been turned off with UNDEFINE. Note also that placing a period in front of a native command name calls that command even if it's been undefined. That's why you often see the leading period in front of AutoCAD command names in AutoLISP programs.

startupexample.lsp

        (defun-q S::STARTUP ()
          (command "._UNDEFINE" "._LINE")
          (Alert
            "The LINE command will draw polylines on Layer OBJ.
            
Type ".LINE" to use the native LINE command.
            
Use the REDEFINE command to redefine LINE"
        )
      )
      (defun c:LINE()
        (setvar "cmdecho" 0)
        (command ".LAYER" "M" "obj" "C" "white" "" "LW" "0.5" "" ""
            ".PLINE")
        (setvar "cmdecho" 1)
      )