LispWithCusp

[

Programming In Lisp With Cusp

Sergey Kolos

Ver 0.0.3

Installation

• Download and install Eclipse SDK (at least version 3.2) from http://www./downloads/
• Download version of Cusp for your platform from http://www./lisp/cusp/cusp.htm . Unzip it into the plugins folder in the Eclipse directory.
• Download recent svn build of Cusp http://www./cusp . Unzip it over Cusp in plugins folder in the Eclipse directory.
• That‘s it. IDE should be ready for Lisp coding. If you have problems, check out http://www./lisp/cusp/faq.htm . If you believe you find a bug or have an idea for improvement, add a ticket at http://cusp./.
  

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-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 and wish to launch "Unreal Tournament" 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 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 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. The patch 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 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 sbcl/site-systems folder. We‘ll try installing split-sequence library. First go to cliki webpage of this library: http://www./SPLIT-SEQUENCE. At the end of this page there is a link where you can get this library from: http://ww./cclan/split-sequence.tar.gz. Download it and extract to sbcl/site-systems folder:



This is all to make library available for loading throug "Load installed package". After the library is loaded, we can run split-sequence function:



It is also possible to install library into a custome folder, not just sbcl/site-systems. 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 any subfolder of c:/temp/system folder for library to be immidiately visible 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:

1. Add the library to :depends-on clause of .asd file.
2. Add the library to :use clause of defpackage.lisp file.
3. 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.

• WikiSettings

---

[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]

---