[Programming In Lisp With Cusp
Sergey Kolos
Ver 0.0.3
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 (up to several minutes) while Cusp starts and connects to lisp process.
- 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-lisp1do the following (these operations are overkill for such a short sourcecode, 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 and wish to launch "Unreal Tournament" youwill want to close Eclipse. Go ahead and just close it, you don‘t needto do anything special to your Lisp session.
To get back to your code you open Eclipse, then make sure that you arein Lisp Perspective, if not select it. Before you can continue codingyour program, you need to load it. To do this, right click on .asd filein 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 the describes why Lisp stopped the program
- Then debugger display 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 isdescribed as "a search engine for documentation of the Common Lispprogramming language and many of its libraries". When you requestLispDoc search on a symbol with Alt+L(or LispDoc from Lisp menu) you get a page in a browser with examplecode of this symbol and a bunch of links to Lisp documents, books ormanuals that mention this symbol:
AutoHelp
The environment supports automaticdisplay of help information. It can sugest completions of symbols andshow call signature and documentation string. The examples below showhow this feature works ( Notice how functions defined in our code alsodisplay this information ):
Cusp also support fuzzy way for proposing autocompletion, but it has tobe turned on in preferences. To do this, openWindows->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:
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. Thepatch cusp-patch0.8.49.zip contains Lisp regex library cl-ppcre.
You can load cl-ppcre library by clicking on "Load installed package" button:
This open "Load package" dialog:
In this dialog box select cl-ppcre and click OK. The library will becompiled 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 tosbcl/site-systems folder. We‘ll try installing split-sequence library.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 sbcl/site-systems folder:
This is all to make library available for loading throug "Loadinstalled package". After the library is loaded, we can runsplit-sequence function:
It is also possible to install library into a custome folder, not justsbcl/site-systems. For this you need to add root folder to libraries inpreferences. To do this go to Windows->Preferences... menu, andselect Lisp->Implementations page:
With such settings it is now possible to extract split-sequence.tar.gzto any subfolder of c:/temp/system folder for library to be immidiatelyvisible to lisp.
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
TODO: Add links here.
[ScratchPad]
parent nodes: LispWithCusp
Scratch Pad
[WikiSettings]
parent nodes: LispWithCusp
Wiki Settings
These are your default global settings.
[global.importance.low.color: grey]
[global.importance.high.bold: true]
[global.contact.icon: contact]
[global.todo.bold: true]
[global.todo.icon: pin]
[global.wrap: 70]
[icon: cog]
