Writing and Running Lisp Code in the IDE: a Tutorial

Go to the tutorial main page.

This tutorial tells you how to immediately begin working on Lisp code in the IDE, without first setting up a project. (A project is necessary when laying out a user interface interactively, but you will not be doing that here.)

The IDE startup sequence changed significantly between Allegro CL 6.2 and Allegro CL 7.0. Therefore the initial instructions for organizing the IDE for Lisp code only are quite different for the two versions. Section 1 discusses starting Allegro CL 6.2. Section 2 discusses starting Allegro CL 7.0. Section 3 discusses using the IDE for Lisp code after you have started Allegro CL and organized the windows for that purpose. Section 3 applies to both version 6.2 and 7.0.

1. Start Allegro CL 6.2

Start up the Allegro IDE (Integrated Development Environment) from the Windows Start menu by running Start | Programs | Allegro CL 6.2 | Modern ACL Images | Allegro CL 6.2 (w IDE, Modern) or Start | Programs | Allegro CL 6.2 | Modern ACL Images | Allegro CL 6.2 (w IDE, ANSI). (If you are using the Trial version, the second may be your only Allegro choice and some of the submenu items may be different.)

Now get rid of a couple of windows that you won't be using. Find the window that shows a grid of small dots, and click the close button at the right end of its title bar. That's a form window where you would interactively create a dialog for an application's user interface. Similarly close the inspector window at the left that shows a table with two columns. This leaves only two IDE windows: (1) the one at the top with the IDE menu bar, toolbar, and status bar, and (2) the Debug Window.

Tip For Later: To avoid showing a form window and inspector at all when the IDE starts up, see the doc page for new-project-show-form. (You'll see below how to find help for a particular symbol.)

2. Start Allegro CL 7.0

When Allegro CL 7.0 starts up, a Startup Action modal dialog will appear, asking whether you want to open or create a project. Press the Escape key to proceed without using a project at all. (Alternately click the dialog's Cancel button.) You should now see two windows: one window along the top of the screen that contains the IDE menu bar, tool bar, and status bar, and another window called the Debug Window.

3. Using the IDE for Lisp once Allegro CL has started

The Debug Window contains a Lisp Listener pane where Lisp expressions may be evaluated, and where printed output appears by default. You can evaluate expressions by typing them at the listener's prompt, and then pressing the Enter key. (The prompt is the string like "cg-user(1): " at the very end of the window's text.)

You first need to move the keyboard focus to the prompt. You can do this by clicking on the Debug Window, and then (if needed) clicking again near the bottom of the listener pane to move the flashing text cursor after the prompt string. Alternately you can use the View | Debug Window command (F9). (That notation refers to the Debug Window choice on the View menu on the Allegro menu bar at the top of the screen. Its keyboard shortcut is the F9 function key.) That command also generates a fresh prompt in case there's unwanted text after the current prompt. Try pressing the F9 key a couple of times now, and see that a new prompt is printed each time.

Enter a simple lisp expression such as (+ 3 4) after the prompt, and then press the Enter key. The answer should be printed just below the expression you entered. If an error dialog appears, just abort from it and try again. If nothing is printed, then make sure that the expression you typed contains as many closing parentheses as opening parentheses, because the listener will not evaluate until you have entered a complete lisp form (this allows you to press Enter in the middle of a long form to enter it on multiple lines).

Tip For Later: Be sure to check out the toolbar at the top of listener pane, which is handy for quickly reusing expressions that you've evaluated earlier, after optionally editing them.

While a listener is fine for entering short lisp expressions on the fly, you need to use an editor to write significant lisp code and to save it to disk. You can use the IDE Editor for this, or Emacs with our Emacs-Lisp Interface (ELI). The trade-off is that Emacs is a more powerful text editor, but in the IDE Editor you can apply many general IDE commands to symbols and forms in your code. Here we will be using the IDE Editor.

Create a new IDE Editor buffer by using the File | New command (control-N). An editor window should appear, showing a blank pane where you can enter lisp code to be saved as a new file. If you want, you can move and/or resize these windows now however you like, perhaps side-by-side rather than overlapping --- when you restart the IDE later, the windows will come back where you left them.

Copy the following function definition into the empty IDE Editor pane. (As in most applications, control-V will paste into the editor or other IDE window; this is the Edit | Paste command.)

(defun triangle (num)
  (let* ((sum 0))
    (dotimes (i num)
      (incf sum (1+ i)))
    sum))

This function returns the "triangle number" of a given number. The triangle number of 4 (for example) is 1+2+3+4, or 10. Use the File | Save command (control-S) to save the code to a file. You'll need to specify the file to create on the File dialog. (Remember to periodically save this file through the rest of this tutorial; an asterisk on the tab for this editor pane tells you that the buffer has unsaved changes.)

Click the mouse somewhere inside (or just after) the function definition in the editor. Then select the Tools | Incremental Compile command (control-D). This finds the top-level lisp form that surrounds the text cursor, and compiles that single function or other definition.

Now that you've compiled the triangle function, you can test calling it. Enter the expression (triangle 4) after the prompt in the Debug Window's listener pane and press Enter. The answer 10 should be printed there.

You can also evaluate forms in the editor. Paste the following form into the editor pane below the triangle function. This is a test form to make a list of the first eight positive integers paired with their triangle numbers.

(let* ((answer nil))
  (dotimes (j 8)
    (push (list (1+ j)(triangle (1+ j))) answer))
  (nreverse answer))

As before, place the text cursor somewhere inside this form or just after it. But instead of using the Tools | Incremental Compile command, use the Tools | Incremental Evaluation command instead (control-E). This evaluates the form just as if you had entered it in the listener, and it still prints the returned value(s) in the listener. Placing the test form into the editor allows you to save it for quick re-evaluation anytime later.

Another way to evaluate an expression in the editor is to place the text cursor just before the form and then to press alt-Enter (or press the numeric keypad's Enter key by itself). Try this now with the test form. This technique also works on sub-forms rather than on top-level forms only.

You will probably want to comment out test forms so that they don't get evaluated when you load the entire file. The Tools | Incremental Evaluation command will work as long as the form begins in column zero, so you could use a block comment for that, leaving the whole test file like this:

(defun triangle (num)
  (let* ((sum 0))
    (dotimes (i num)
      (incf sum (1+ i)))
    sum))

#|

(let* ((answer nil))
  (dotimes (j 8)
    (push (list (1+ j)(triangle (1+ j))) answer))
  (nreverse answer))

|#

The IDE Editor is integrated with the other IDE tools, allowing you to use many of the IDE menu bar commands in the editor. Place the text cursor on the symbol "dotimes" in the triangle function, and then press the F1 key. This invokes the Help | Help on Selected Symbol command to show the doc page for the dotimes operator. (If you are using the Trial version, which doesn't include the documentation, make sure that you are connected to the Internet so that our online doc pages can be found.)

Now select the Help | Help on Selected Dialog command. This will show the help page for the IDE Editor, which is the selected dialog, rather than for the symbol that was selected in that dialog.

When you use most any menu bar command in the IDE, it will attempt to find a value to which that command can be applied, looking in whatever window or widget has the keyboard focus. For example, if you place the text cursor on the number 0 in the triangle function and then invoke the Tools | Browse Class command, it will browse the fixnum class. So remember to experiment with menu bar commands.

As a last exercise, let's see how to get our code back when we start up the IDE again in the future. First exit the IDE by using the File | Exit command, or by clicking the close button at the right end of the menu bar window. (If it asks whether to save the editor file because it has unsaved changes, then do so.) Then start the IDE up as you did before.

Now drop down the Recent menu and go into its Open Editor File submenu. The file that you saved in the previous lisp session should be listed there. Select it, and an editor window should appear for it. (If your file is not in the Recent menu, then use File | Open to select any existing source code file to edit. Perhaps you had turned off the Tools | Save Options On Exit option.)

At this time you could use Tools | Incremental Compile as before to compile the triangle function, but typically you would have many functions in the file, and compiling each one individually would be tedious. So instead use the File | Compile and Load command to compile and load the whole file. The file dialog that appears should default to the file that was selected in the editor, so you just need to press the OK button to choose that file. At this point you are ready to continue developing and testing your code.

This is the end of the tutorial. The documentation for the IDE is in doc/cgide.htm.

Go to the tutorial main page.