The AutoLisp Beginner

Welcome to the world of AutoLisp.   Soon you will know what the hell a car of a cdr is.

Let's get to it.  But how?

    When I say "type this at the command line" I will put the actual key strokes in red except for the enter key.  This will mean that you should type the red letters in at the Command Prompt inside AutoCAD as if you were typing the command "Line".  To clarify, If I say "type this at the command line: Line and press the enter key, you would type the word "Line" at the command prompt inside of AutoCAD and press the enter key afterwards.  Got it?  No? Oh, never mind.  Just keep reading.  I won't leave you behind.

The first thing you should know about AutoLisp:

AutoLisp always has as many opens "(" as it does closes ")". 

Every AutoLisp program should look similar to this:

(defun myProg()
      (princ "Jeff")
      (princ)
)

You can execute AutoLisp at the Command Prompt inside AutoCAD.   This is where we will start.  

    AutoLisp is a language that returns a value after executing.  Every function that executes will return or echo it's answer.   Let's test this.     Open AutoCAD and type this at the command line: (+ 1 2) and press the enter key. (The + function adds numbers together).  Look at the command line. You should see something that looks like this:

    Notice the 3 below the line you typed and the Command Prompt?  AutoLisp returned the value of the function you typed in.  Try it again. This time change the 1 to 3 and the 2 to 5.  As in (+ 3 5).  What did it return?  AutoLisp ALWAYS returns the answer.

Variables

     What the hell is a variable?  Variables are names or placeholders if you will, for values.   Remember algebra?  (Your going to wish you would have paid attention to Mrs. Johnson instead of that cheerleader on the first row with the blond hair and the big...well ...nevermind.) X=1 Y=2.  Look familiar?  X and Y are variables.  They could mean anything.   If you need to store data, such as a string or integer, you will need to assign a variable name to the data.  The way to do this is to use the setq function.  Ex. (setq a 1).  This set's the variable a to the value 1.  Anytime you use the variable a in your program, it will actually use the value 1.  If you typed (+ a 2) and pressed enter, AutoLisp would return 3.

    You can use any variable name you want.  (Practically)  Upper case and lower case does not matter.  I would suggest you do not use any names that AutoCAD has in use. How do you know which ones are being used by AutoCAD?  Good question Jeff.  The simplest method to find out if AutoCAD is using a name is to type in the name at the Command Prompt inside of AutoCAD and press the enter key.  If nothing happens,  use it. 

    If you were to write a program named Line.lsp and load the program, AutoCAD's built in LINE command will seem to be replaced.  When you type Line you will run your program instead of the Line command.  You will get the built in functions back next time you open a new drawing or you could use a period in front of the command to make it execute an AutoCAD built in function.  Ex. .LINE  would execute the AutoCAD built in function instead of your program.  I do not suggest toying with this. 

     Name your variables and programs something unique.  AutoCAD does not have any built in functions that are a single character.  So a through z are fair game.   Some safe examples are:

(setq a 1)

(setq b1 3)

(setq aa1 4)

(setq jeffsVarForHisProgram 1)

(setq thisVarA 2)

Some bad examples are:

(setq line 1)

(setq acad 4)

(setq ltscale 7)

(setq car 12)

(setq cdr 400) 

Again with the car and cdr stuff?  What is it man?

    I suggest you use variable names that are somewhat descriptive.  If you had to name a variable for a string that contains people's names then I would use something like this (setq strName "Jeff").

    If you have a variable name for a integer that holds the data for a value that represents a title block selection then I would use something like this (setq intTBSelection 3).

   A couple of important last minute things:

While inside AutoCAD you can check your variables to see what they are set to.  This is very handy when debugging a program.  Type (setq aa1 454) and press enter.  To check the value of the variable we just declared, simply type !aa1 at the command prompt.  Go ahead.   Try it.  AutoLisp echo's the value to the command line.  Using an exclamation point in front of the variable prints the value of the variable to the command line.

New!  Have you ever seen an AutoLisp program crash?   Ever try to debug it?   It looks like a bunch of garbled mess.  How in the heck can you cipher through all of this:

   It's not as tough as it looks.  You only have to worry about the first or second lines returned.  In this case the culprit that crashed the program is  (+ CANT 1).  Let's look at the variable CANT.  At the command prompt type !CANT<enter>  It will return nil.  You can't add nil to 1.  Why is CANT set to nil?  Let's look at the next line.      (SETQ CNT(+ CANT 1))   This looks like a counter of some type.  I'll bet the variable name CANT should have been CNT.  A typo!  At this point I would open the program with NotePad and search for the text string CANT.  If this is the only place it shows up then my first explanation would be correct.  I would retype the CANT variable to be CNT.  Save the program and try it again.

Okay, enough for variables for now.  Let's move on.

Functions

Let's take it a step further and create our very own function.  Every defined function begins with the declaration defun.

Ex. (defun myProg()  or (defun C:myProg()

The difference between using the C: and not using the C: will be explained later.  For now. let's learn another AutoLisp function to use in our first program.  The function princ simply prints to the command line. Ex. (princ "Jeff") would print Jeff on the command line.   Alrighty then, let's type this at the command prompt:

(defun myProg()(princ "Jeff")) and press enter.

You should see something that looks like this:

Now type (myprog) at the command prompt and press the enter key.  You should see something that looks like this:

     The program executed and printed "Jeff" on the command line.  Then the program echoed the last statement to the command line.   AutoLisp always returns the answer right?  That is why you ended up with Jeff"Jeff" on the command line.  The way to get rid of the echo is to use a princ statement without any parameters as the last statement in your program.  Ex. (princ).

   Let's rewrite the program using the (princ) function to stop the echo.  Type this is in at the command prompt:

   (defun myProg()(princ "Jeff")(princ))

    Then type (myprog) and press enter.  What happened?  No echo.  Cool.

    Let's back track and explain the C: we mentioned earlier.  The C: tells AutoCAD that you want this program to be executed at the Command Prompt like a built in function.  Let's redo our program.  Type this at the command line:

  (defun C:myProg()(princ "Sanders")(princ))

    Now type (myprog) and press enter.  What happened?  Why did it print Jeff?  We used the C: in front of the function.  We do not have to put the program inside of quotes to execute it. (There are some other differences, we will get to that in the advanced levels.)   To execute a function that was declared with a C: you only have to type the name of the program at the command prompt.  Let's do that now.  Type myProg at the command prompt and press enter.  It printed "Sanders" to the command line.  Wow!   Don't rush off to show everyone yet.  The next time you open a drawing your new function will disappear and you will have to type it in again.  Dang!

   Wait!  We could save it to disk and reload it whenever we needed it.  Let's do that.  I will assume you have a  windows operating system for the following instructions.  Yes.  I know what happens when you assume something.  Let's not go there.

   Click on the Start button.   Go to Programs.  Go to Accessories.   Go to NotePad.

Notepad should open.  When it does, type in:

(defun C:myProg() 
      (princ "Jeff")
      (princ "Sanders")
      (princ "AutoLisp")
      (princ)
)

Now, go to the "File" drop down menu in NotePad and select "SaveAs".  Type in myProg.lsp for the name of the program.  Wait!  Don't hit the SAVE button yet.   NotePad has a bad habit of assuming you want to save it as a text file with the extension txt.  Go to the "SAVE AS TYPE" drop down box and select "ALL FILES".  Look at the top of NotePad in the "Save in:" location.   Make sure you save the file in a location where AutoCAD can find your file in it's search path.  I suggest creating a directory on your hard drive to keep all of your AutoLisp files in.  I would suggest a directory such as : "C:\ACAD\lsp".   Change the "Save in: " location to point to this directory.  Now press the SAVE button.   Go back to AutoCAD.  Go to the "Tools" drop down menu and go to "Preferences".  Click the "Files" tab.   Click the + sign in front of "Support File Search Path".  Click the "ADD" button.  Type in the directory you saved the "myProg" lisp file in. Ex. "C:\ACAD\lsp" .  Click the "APPLY" button.  Click OK to the alert box.  Click the OK button to exit the dialog box.

At the command prompt inside AutoCAD type (load "myProg") and press enter.  Then type myprog and press enter.  If you hit the F2 button to bring up the text screen, you should see something that looks like this:

You have successfully created an AutoLisp program.  Congratulations!  

One last thing about functions:

We discussed the defun() statement and what it meant.  We did not discuss the open and close parenthesis "()" after the defun statement.  We will do that in the intermediate tutorial level.   The point I wanted to get to here is, if you put  your variable names inside these parenthesis and after a / you will reset these variables to nothing...or nil as AutoLisp defines it.  Therefore the exclamation point before the variable name will return nil.  This saves room in RAM and also keeps your program from getting corrupted by other programs that do not reset the variables to nil. Always include the variables you use inside the parenthesis after debugging your program.  

An example of this is (defun C:myProg(/ varA varB varC).

You are so, so, close to uncovering the mysteries surrounding the car and cdr quandaries. Move on to the next level. 

AutoLisp Tutorial Home