Harry's Code Class: Tips for Programmers (February 2007)

Tools of the Visual LISP Craft

This month, Harry chips away at a few basic programming aids
that will get you started using AutoCAD's VLIDE environment

Most people are tool users. It's one of the traits that differentiates humans from most other animals. Tools enhance our ability to do things, or allow us to do something we couldn't do without the tool. For instance, have you ever tried to push a nail into a board with your hand? Chances are you probably went looking for a hammer.

The craft of programming in Visual LISP requires tools. And in the same way that hammering is best learned with experience and maybe a little coaching, Visual LISP programming takes a bit of introduction and a lot of hands-on practice.

If your job is to build LISP programs, you'll want to master all the tools you can to enhance your abilities. This month, I'll open the toolbox for Visual LISP programmers, known as the VLIDE, and begin to explore some of the tools inside. I'll introduce you to a few of the basics -- enough to get you started -- and then you can hammer away.

Getting Started
To access AutoCAD's Visual LISP toolbox, launch AutoCAD and type VLIDE when the Command prompt appears. This will open another display window, the Visual LISP for AutoCAD Developer Environment, our toolbox.

   (setq AA 100)

Similar to opening a traditional toolbox that's new to you, the Visual LISP toolbox will hold some tools you recognize -- icons that are familiar to all Windows users -- and others that likely defy understanding at first glance.

Upon launching VLIDE, you'll find two windows open in the MDI (Multiple Document Interface): the Trace and Console windows.

Trace Window. The Trace window is where Visual LISP reports system-level activity, such as starting and loading functions. Generally you can ignore the Trace window when writing code.

Console Window. The Console window is where you can communicate with the LISP evaluation system by typing in symbols and expressions. A command prompt "_$" is shown when the console is ready for your input. The primary use of the Console window is to query a symbol or begin the evaluation of one of your custom functions. Keep in mind these windows are for you, the programmer, and will not be seen when your functions are running inside AutoCAD. The VLIDE is a programmer's interface and meant to be used by programmers only.

Create a Program
Start by creating a new file while VLIDE is the active program. Type Control + N, select the icon for a New File, or pick the File / New File option from the pull-down menu to open a new window in the MDI to input your program. Use this window as you would any other text editor window, but keep in mind it also offers some great advantages when you are entering your code. After all, this is a LISP program editor!

In your new window, type the following example program, which I'll call "Harry Says Hello."

   (defun Harry ()
     (alert "Hello!")
   )

It is not a very long program, and each character you see is important. Beginners will note the abundance of parentheses in play, which is why LISP is often known as Lost In Stupid Parentheses. You will get used to them, and after a while you will even find a certain level of comfort in using them inside deeply nested expressions.

Colorful Code
Note that as you input the program code, the text will shift colors. Parentheses will appear in red, function symbols in blue and text constants between quotes in magenta.

(defun Harry ()(alert"Hello!"))

A few other colors can appear as you create code in the MDI. Numbers display in green. Comments -- helpful annotations included for the human eye but invisible to the computer -- appear grayed out.

You didn't know code could be so colorful? Turns out that this code presentation is a fantastic tool for the programming craft and is found in a variety of programming environments, albeit in different fashions. Color coding primary items helps greatly reduce the number of typographic mistakes that can render your code inoperable. When you forget to close off a string constant with the required matching double quote mark, for example, every line of text that follows will display in magenta, signaling your simple yet common coding mistake. You could also say that this color coding is part of the "visual" in Visual LISP!

An aside about that blue code: Function symbols that appear in blue are "reserve" words used throughout Visual LISP, and Visual LISP attempts to protect them. If you use these symbol names in your LISP programming for non-function purposes, your program will break and the function will stop. Visual LISP sets off these symbols in their own color so they stand out.

Load and Run
Running your LISP function is a two-step process: First you load it, then you invoke it. Both steps are accomplished using the heart of LISP, the evaluator. LISP's evaluator reads an expression and performs the required actions.

Load. Loading a function presents the program code to the evaluator in the form of a defun expression. The symbol defun is used to define a function in LISP. The function contents follow the defun symbol, a symbol name to use for the function, and a list of parameters to be supplied to the function.

When you load a function of your creation, you are adding its name to the LISP system. The name serves as a reference to the remainder of your function. You can run the program only after the name, parameter list and expressions that comprise the function have been loaded or defined in the LISP system. Think of this step as a translation. The function you created is being translated by the load step into something the computer can use. After loading, you can reference a function by just supplying a name.

In our simple example, the defun establishes a symbol named Harry as a function. The function Harry has no parameters -- thus, it includes the open and close parentheses for an empty parameter list, with the alert expression inside. When the defun expression is presented to the evaluator, the result is the symbol Harry, now bound as a function.

Run. The next step is to run Harry. At the Console window, type in (harry). The parentheses are required. If you type in harry without the parentheses, you will be shown the current binding or value assigned to the harry symbol.

Save Your Work As You Go
To save your program source code, click the Save File icon, type Ctrl+S or pick File / Save in the pull-down menu of the Visual LISP window. Saving frequently is a good practice when programming. Avoid the temptation to run code without saving it first.

Looking Good
Now let us turn our attention to another helpful icon in the VLIDE: Format Code in Editor. Once you've created a LISP routine, use this tool to clean it up. (Judging by the code that Cadalyst readers submit to Hot Tip Harry, I'd say very few LISP programmers are currently using the Format Code in Editor tool.)

LISP is a freeform programming language. It allows you to format code any way you like; there's no set standard for presenting code, and as a result it's easy for work to get messy. Early on, a style was created that became known as the Pretty Print format. Format Code in Editor performs a Pretty Print on your code, adjusting it so all the indentations and parentheses are consistently displayed.

If you have not already discovered this tool, I strongly suggest you explore it. Finding that missing parenthesis and seeing the layout of a complexly nested IF-THEN-ELSE structure is easy using the Format Code in Editor tool in the VLIDE. To activate the Format Code in Editor, either select the icon with the 45 triangle, type Ctrl+Alt+F, or select menu option Tools / Format Code in Editor.

Experiment with the VLIDE using LISP routines you have on file (or download past Hot Tip Harry routines from Cadalyst's Get the Code!) Launch VLIDE and open any .LSP file. Note that the color coding is applied to the program text you open. (Again, keep in mind that the color coding only appears when you open a file inside the VLIDE environment and not in the saved .LSP file itself.) After opening the LISP source code, apply the Format Code in Editor tool. The code in the window will be adjusted automatically into the Pretty Print format, making it much easier to follow.

Summing Up
The VLIDE is a tool chest full of tools for the Visual LISP programmer. For more information, select the Help menu option while inside the VLIDE. Visual LISP Help is divided into three main sections. The AutoLISP Reference section lists available functions. The AutoLISP Developers Guide contains more details about using the VLIDE as well as other topics pertaining to programming in Visual LISP. A tutorial section walks you through a complex programming project.

The best Visual LISP teacher is experience, and the best Visual LISP experience is gained using the VLIDE and the tools inside -- so just start pounding away!

Until next time, keep on programmin'!