Lisp With Cusp
Sergey Kolos
Ver 0.0.5
Table of Contents
Installation
Getting Started: Your First Lisp Program
Create Lisp Project
Start Eclipse.
Go to Window > Open Perspective > Other...
Choose Lisp. You'll need to wait while Cusp starts and connects to lisp process. The first time Cusp starts it compiles code that connects to Lisp, and it might take couple minutes on slow machines, so be patient. Next time you'll start Cusp it will load Lisp and will connect to it much quicker.
Start new project: File > New > Lisp Project
In New Lisp Project dialog box don't change anything and just hit Finish.
Project wizard will create three files: new-lisp1.asd, main.lisp, defpackage.lisp
- new-lisp1.asd - it is a sort of make file for your program, we'll look at it later
- defpackage.lisp - it is a sort of header file, here you declare functions and other symbols that are exported from the package
- main.lisp - this file will hold your code
Once project is created it will be automatically compiled and loaded. We'll discuss later what this mean.
Writing Code and Basic Navigation
Open file main.lisp and after (in-package :new-lisp1) write the following code: (defun f () "hello, world!")
Save the file. As file is saved it is immidiately compiled. You can check this by typing in lower part of REPL (new-lisp1::f) and hitting Enter key or pressing Send button:
The result is displayed in upper part of REPL:
To export the function f from the package new-lisp1 do the following (these operations are overkill for such a short source code, but they show important navigation features of Cusp IDE):Select in-package :new-lisp1 in outline window to jump to the location of this statement in the code.
Ctrl+Click on :new-lisp1 to find location where this symbol is defined.
This operation brings up dialog box Definitions. Select (DEFPACKAGE :NEW-LISP1) and hit OK:
The previous operation will bring up the file defpackage.lisp. Type f in :export and save file:
Now the function f is exported from the package new-lisp1 which can be checked by typing (new-lisp1:f) in REPL (note single : instead of double :: in previous test, which signifies the fact that we just called a symbol exported from the package).
To get back to the definition of function f just type Alt-BackArrow Alt-BackArrow or use navigation buttons on main toolbar:
Quitting And Starting Again
Once you tired of coding you will want to close Eclipse. Go ahead and just close it, you don't need to do anything special to your Lisp session.
To get back to your code you open Eclipse, then make sure that you are in Lisp Perspective, if not select it. Before you can continue coding your program, you need to load it. To do this, right click on .asd file in your project and select Load asd :
This will compile and load all files for your package. You can check this by running new-lisp1:f
Dealing With Problems
Debugging
If something goes wrong in your code, you get into debugger. For example, enter g in REPL:
Hitting send, opens debugger:
The debugger has three regions:At the top is the error message that describes why Lisp stopped the programThen debugger displays options to resolve the problem. The default option which aborts previous command is highlighted so if you satisfied with this default you can just hit Enter to go back to REPL (or press q). To choose any other option you can select it and hit Enter or press number that corresponds to the option.Backtrace shows what evaluations Lisp performed before it arrived to this error condition.
In this case the error happened because symbol g is not defined.
Inspector
Some regions of upper part of REPL are hyperlinks. These are objects that can be inspected. To inspect you just click on a hyperlink. For example, enter *package* in REPL:
and follow #<PACKAGE "COMMON-LISP-USER"> hyperlink. You'll get into Inspector:
which prints details of the object #<PACKAGE "COMMON-LISP-USER">.
Compilation Warnings and Errors
Add to main.lisp following code:
(defun h()
"Call function that is not defined"
(hh))
When you save the file, Cusp tries to send it for compilation. In this case saving generates item in Problems list:
It is generated because we tried to compile main.lisp before we loaded package new-lisp1.asd. See section "Quitting And Starting Again".
Now, if you load new-lisp1.asd compilation produces a warning, which is added to Problems tab and put on bar left to the code:
Getting Help
HyperSpec and LispDoc
HyperSpec
The main Lisp reference is HyperSpec. To find description of a symbol in HyperSpec put a cursor at the symbol and hit Alt+H (or select HyperSpec in Lisp menu):
This will open a browser window in Eclipse with page describing the symbol:
LispDoc
The other good source of documentation is LispDoc. On its website it is described as "a search engine for documentation of the Common Lisp programming language and many of its libraries". When you request LispDoc search on a symbol with Alt+L (or LispDoc from Lisp menu) you get a page in a browser with example code of this symbol and a bunch of links to Lisp documents, books or manuals that mention this symbol:
AutoHelp
The environment supports automatic display of help information. It can sugest completions of symbols and show call signature and documentation string. The examples below show how this feature works ( Notice how functions defined in our code also display this information ):
Cusp also support fuzzy way for proposing autocompletion, but it has to be turned on in preferences. To do this, open Windows->Preferences... menu, and set corresponding options:
Then typing m-v-b will suggest multiple-value-bind:
Apropos
You can also search internal documentation using Apropos. For non-Unix types, Appropos gives a brief one-line summary for a given command.
Big Projects
Advanced Navigation Features
There are several features in Cusp that help in working with big Lisp projects.
Task list: You can automatically add task by putting 'TODO:' in ';' comment:
Sections: You can divide your code into sections by using comments that start with ;;;;<:
;;;;<Section name> description
Then a section can be folded in the editor and you can quickly navigate between sections using Outline:
Bookmarks: Cusp supports regular bookmarking facility of Eclipse. Read Eclipse manual on bookmarks.
KeyBindings: Navigational (and other) operations in Eclipse can be performed using a key combination. To see and customize key settings, go to Window->Preferences->General->Keys
Adding Files to the Project
To add another file to the project you have two options:
Create new file from Eclipse: Right-Click on the project in Lisp Navigator and in context menu select New->Lisp File
This opens dialog box, where you can select name of new file. Hitting Finish will create new file.
Also, you can just copy file to the folder and Refresh Project : Right-Click on the project in Lisp Navigator and in context menu select Refresh
Then you need to do two more things:- put correct in-package statement at the top of the file
- add code (:file "file-name" :depends-on ("defpackage")) to :components clause of .asd file:
Using Libraries
Loading Installed Library
First we will see how to use library that is already installed. One of the library preinstalled by Cusp is CL regex library cl-ppcre.
You can load cl-ppcre library by clicking on "Load installed package" button:
This opens "Load package" dialog:
In this dialog box select cl-ppcre and click OK. The library will be compiled and loaded, as can be seen in "Change package" dialog box:
To check that the library is loaded run the following in REPL: (cl-ppcre:scan "(a)*b" "xaaabd") :
Installing New Library
Installing new library is as simple as extracting its contents to one of the folders that are checked by cusp on startup. The default folder is: jasko.tim.lisp.libs/libs foder in Eclipse plugins directory. Although split-sequence library comes with Cusp I show how we'd install it. First go to cliki webpage of this library: http://www.cliki.net/SPLIT-SEQUENCE. At the end of this page there is a link where you can get this library from: http://ww.telent.net/cclan/split-sequence.tar.gz. Download it and extract to a library folder. Now restart Eclipse. This is all to make library available for loading through "Load installed package" dialog. After the library is loaded, we can run split-sequence function:
It is also possible to install library into a custome folder, not just jasko.tim.lisp.libs/libs. For this you need to add root folder to libraries in preferences. To do this go to Windows->Preferences... menu, and select Lisp->Implementations page:
With such settings it is now possible to extract split-sequence.tar.gz to c:/temp/system folder for library to be immidiately visible to lisp after Cusp restarts.
Using External Library in Your Package
Once a library is installed you can use functions it exports in your code. To do this you need to perform three steps:Add the library to :depends-on clause of .asd file.Add the library to :use clause of defpackage.lisp file.Use library functions in your .lisp files.
As an example let's use library split-sequence in our new-lisp1 package (note that at this point this library should be loaded into lisp with (require 'split-sequence) statement):
Specify that our new-lisp1 package should load split-sequence before it can operate correctly. To do this, open new-lisp1.asd file and add :split-sequence to :depends-on clause (don't forget to save file):
Declare that package new-lisp1 uses library split-sequence. To do this go to file defpackage.lisp and add :split-sequence to :use clause (don't forget to save file):
Define function split-path in the package new-lisp1 as follows:
Now we can test the new function by running (new-lisp1::split-path "usr/bin"):
When you next time start new lisp session you no longer need to load split-sequence library - it will be loaded automatically when you choose Load asd in context menu of new-lisp1.asd file.
What's Next
There are several excellent books and other resources for CL available online: