Userguide

"Beware the Jabberwock, my son!
The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
The frumious Bandersnatch!"

Getting Started

  1. First create a directory to contain your lisp sources, if you have not yet done this.
  2. Start the IDE by running 'Jabberwocky'
  3. Now a window like this should appear.The right pane is the project explorer and contains the project directories and source files. For each source file a list of function definitions and macro definitions is visible.
  4. Right click on 'Projects' and choose <Add Project>. This will start a open file dialog box. Choose the directory that you have created to contain your source files. This dialog box also allows you to create a directory if you have not done this in (1). For a description of project management see project management
  5. Right click on your directory in the project pane and choose <New File>, a dialog box asking for the name of the file will now appear. Be sure not to enter the .lisp extension. Jabberwocky will automatically add this extension for you and will recognize lisp files by this extension. The right pane of Jabberwocky contains now a editor buffer, you can enter now your LISP code. For a description of the editor see Editing documents.
  6. Right click in the middle of the editor buffer, choose <File><Save> to save your code.
  7. Type in the following code to test debugging
    (defun fac (n) (if (zerop n) 1 (* n (fac (1- n)))))
  8. From the <Interaction> menu choose <New Interaction with CMUCL> or <New Interaction with CLISP> depending on the LISP version that you have used during install. In the bottom pane of Jabberwocky you will now see a interaction buffer which allows you to communicate with the chosen LISP. For a description of the interaction with a LISP process see Interacting with a LISP process.
  9. Click back on the editor buffer and click then on the button. This will add instrumentation code to your source and load the instrumented version of your code in the LISP system. The button bar should now change to contain the buttons needed for debugging. See Debugging for a description of debugging.
  10. Click on the word fac in the editor buffer and press <F9>, you have placed now a breakpoint on the lisp form (defun fac (n) (if (zerop n) 1 (* n (fac (1- n))))), this is indicated by a change in background color.
  11. Go to the interaction buffer and type (fac 3), the system will now highlight the lisp form defining fac, you can now step through the code using <F7>
  12. When finished, close Jabberwocky via <File><Exit>

User interface Jabberwocky

The user interface of Jabberwocky contains the following components (see figure)

Project Management

Jabberwocky contains a explorer pane allowing you manage (in a limited way) a project. Project management in Jabberwocky is based on the file system and uses the directory structure of the file system to define the folders containing the lisp source files, no project configuration files are used (and I plan to keep it that way, (I'm really sick of corrupt or incorrect project and solution files in Visual Studio from Microsoft)). Because projects are essential directories it is very easy to copy or archive projects (just copy or archive the directory). Of course project management needs more then just folders and sourcefiles, but all the extra information is generated by analyzing the source files when a project is opened (this happens in background but for a big project it can have some performance impact on the editing of a buffer). Jabberwocky will remember all the open projects as part of its state when you stop Jabberwocky.

The first level of the explorer window contains repository nodes (currently only a lisp repository is possible) and the projects node. The following node types exist:

Editing documents

Typing in lisp code can be done via a editor buffer. Editor buffers are used in the following cases:

When you type in text in a editor buffer (or when you move the cursor around) the editor automatically highlight the opening and closing parenthesis of the lowest level list containing the cursor. The editor tries to take in account the existing of comments, character literals and strings to do a correct highlighting of the parentheses. At the left bottom of the IDE window (the message area) you will also find a text containing the first few beginning and the last ending characters of the containing list, this will help you to ensure parenthesis balancing even when a lisp spans more then one page.

With each editor buffer is also a syntax analyzer associated, this analyzer will whenever you modify something analyze the modified piece of code and provide you with syntax coloring. Keywords, variables,string literals,vector literals, character literals and the head of a lispform will all have their own color which can be changed via <Option><Color>. The syntax coloring will be done in background, so your typing speed will not be influenced, this means also that you have to wait a little bit before you see the effect of syntax coloring. The editor is smart enough to not analyze the whole source whenever you type something but only the minimum part of the document that is influenced by your modification. Once the syntax is determined the background color of the containing list is changed to give you a visible clue that syntax coloring is done and which list you have modified. During syntax analyzing a list of lexical variables, function definitions and macro definitions is also maintained. When in the project explorer you will be able to see the defined functions (normal,generic and methods) and of the defined macros. The hint window is also able to show the lexical variables that can be used or in addition to the predefined functions (macros), the functions (macros) in all open projects can be shown in the hint window. The syntax analyzer does more than just recognizing keywords, if you have for example some syntax errors in the lambda list of a function definition, the color of the defun keyword is different then when you have no syntax errors, this should in theory allows you to recognize most syntax errors during typing. Syntax of the standard ANSI COMMON LISP lispforms is recognized but you can add your own syntax if needed see Extending the syntax analyzer for more details.

Code completion, when you type in a ( the editor will automatically add the closing ) the cursor is then placed in the middle of the empty list. The same thing happens with ". Code completion can be turned on/of with <Option><Character Completion. Be aware of the fact that turning off code completion can slow down syntax coloring, starting a opening hook or a opening double quote makes the rest of the document part of a big list (string), which will be changed if you type the closing hook (double quote). The effect is that a very big part of the document needs to be reanalyzed. If code completion is on you can insert a single ( or " by pressing <ctrl><shift><(> or <ctrl><shift><">. If code completion is off, these keysequences will give you a () or a ""

The editor can help you to indent you code correctly, pressing <tab> on a line add enough blanks at the beginning of the line so that it is indentated correctly. If you have enabled <Options><Indentate on enter> then pressing enter to create a new line will automatically indentate this new line correctly.

During editing you can also display a hint window that can give you syntax information and a list of words that can complete the word you are typing in, see hintwindow for a picture. Press <alt-space> to toggle the display of the hint window. The hint window contains two panes. The top one gives you syntax information about the current lisp form, this information comes from a lisp process, so its empty if no interaction buffer is running (the CMUCL process gives the most useful information for the moment). The bottom pane gives you a list of possible choices to complete the word containing the cursor. If you are in a empty list or a the begin of a list representing a LispForm the list of known macros, functions, generic functions and methods is displayed, if you are at the second position in the definition of a function,macro, generic function or method a list of the undefined function (macro calls) is displayed (this allows you to see in a quick glance which functions and macros are used but not yet defined), finally in the other cases a list of the lexical defined variables is shown. Jabberwocky waits on the syntax analyzer before displaying the hint window (this to ensure that he bases himself on the correct information), so it can take a short time before the hint window is displayed. You can scroll through the list of choices via <ctrl-up> and <ctrl-down>. To replace the current word with the choice selected in the list choose <alt-enter>.

A editor buffer editing a source can be splitted horizontal (or vertical) in two editor buffers editing the same source (via <Workarea><Split Vertical(horizontal)>. Both new editor buffers will refer to the same document, edits done in one buffer will be visible in the other buffer. The document edited in one editor buffer can be changed to a document in another buffer via <Workarea><Replace Document>. These features allows you viewing different portions of the same document and copy and paste between different regions of the same document.

The editor buffer has like all modern editors the following editing commands.

Delete the previous character <backspace>
Delete the next character <delete>
Selecting a piece of text Press <shift> and move the cursor around
You can also use the mouse to select a piece of text
Copy the selected text to the clipboard <ctrl-insert>
Copy the selected text to the clipboard
and delete the selected text
<ctrl-delete>
Delete the selected text <delete>
Replace the selected text Start typing the new text
Send the selected text to the current interaction buffer <ctrl-enter>
Paste the text in the clipboard <shift-insert
Undo last edit <Edit><Undo Last Edit>
Redo last edit <Edit><Redo Last Edit>
Move to the begin of a line <ctrl-a>
Move to the end of a line <ctrl-e>
Move to the begin of a list <alt-left>
Move to the end of a list <alt-right>
Move to the begin of the next leaf <ctrl-right>
Move to the end of the previous leaf <ctrl-left>

Search and replace

There are basically three ways to do a search:

Incremental search

You start a incremental search via <ctrl-n> (forward search) , <ctrl-p> (backward search) or via the Edit menu. During a incremental search you can enter your search string in the Input Area. Jabberwocky will highlight the first occurance of a match found against your search string. This highlight will automatically be adjusted if you modify your search string. Once in incremental search mode you can clear the search string with <ctrl-delete> or change the search direction with <ctrl-n> (forward search) , <ctrl-p> (backward search). If you have reached the end (begin) of the buffer a automatic wrap around takes place. You leave the incremental search mode by clicking in a editor buffer.

Incremental search and replace

You start a incremental search and replace session via <ctrl-r>, you get then the same functionality as for a incremental search to search for a occurance of a search string. Once you have typed in the correct search string, you can press <enter> and can then type in a replace string, when you press then <enter> the found occurance will be replaced by your replace string and Jabberwocky search for the next occurance of your search string, pressing <enter> replace again this occurance and so on.

Interactive search

A interactive search allows you to do a multifile search using regular expression matching or case sensitive(insensitive) simple string matching. The occurances are shown in a table which display a checkbox, the filename of the source searched, the line containing the occurance and the begin position of the occurance. The following picture should clarify this:

To use interactive search press <ctrl=f> or the <Edit><Find and replace> menu. Once the dialog box is opened type in your search expression and choose <Regular expression search>, <Case Sensitive search> or <Case Insensitive search>. If you want to search in all the files in a project, enable <Search all project files> and choose the project to search in via the combobox. Press now <Search> and all the occurances will be displayed in the table. If the source containing a occurances is displayed in the Editor Area you click on the occurance and the editor buffer containing the occurance will become current, the occurance is highlighted and shown in the editor buffer. If you double click on a occurance the file containing the occurance will be loaded in a editor buffer and the same thing happens. For the replace operation you can type in now the replace string and use the checkboxes in the first column of the table to specify which occurances should be replaced by the replace string. Pressing <Replace> will the replace all the marked occurances by the replace string. You can also replace all the occurances by the replace string by pressing <Replace All>. To stop the interactive search press <Close>.

Indentation

You can indentate the source code in the following ways:

You can always undo the indentation operation via the undo facility of the editor. The indentation follows the following rules:

Auto indentation

Indentate element/document

In contrast with auto indentation indentation of a element or document can add/remove newlines and spaces to get properly indentated code. The indentation algorithm tries to put as much as is possible on one line without causing lines longer then a specific max line length and following the indentation rules for special lisp forms. The maximum line length can be set via <Options><Max Line length> The rules are as follow :

Help

The following help facilities are available for Jabberwocky

The documentation can be shown via the following browsers: To set the Help Browser use <Options/Set the browser for help>.

To configure the HyperSpec support you must first download it. The HyperSpec is maintained at Harlequin and can be downloaded from Common Lisp HyperSpec. Expand then the downloaded file to a directory on you filesystem and use then <Options/Directory of Hyperspec files> to tell Jabberwocky where the HyperSpec files are.

Don't forget to save the configuration settings via <Options/Save Configuration>

Macro Recording

It is possible to let Jabberwocky record the activation of the actions, the text typed in the Input Area and keystrokes send to a editor buffer. Jabberwocky will however not record mouse events (like drag and click), this due to the fact that in that case replaying would require user input, which is not a very good idea when replaying takes place. Once recorded you can do a replay of the macros. When replaying a macro the new context (current editor buffer and cursor position) will be used. Jabberwocky saves the named recorded macros during exiting so named macros can be reused in the next session. To use macro recording use the following steps. The following figure shows the macro explorer to interact with a macro.

Macro Explorer

Interacting with a LISP process

Task window

The task window shows you a overview of the tasks, errors and warnings that Jabberwocky finds in our code. The content can be filtered on the type of the entry and on the file referred to in the entry. Sorting can be done on Document, Message, Time and Type. When you click on a entry, the editor buffer containing the document that is the source of the entry is selected (opening the file in a new editor buffer if needed) and the cursor is posisioned on the lisp form that caused the creation of the entry. This allows you to quickly find a form that contains a error or that causes a problem in Jabberwocky. The following types of entries are possible:

Interaction buffers

To start a interaction buffer with a LISP process use <Interaction><New Interaction with CMUCL(CLISP)>. This will start a process running the chosen LISP interpreter and opens also a editor buffer to interact with this process. When you type <enter> Jabberwocky tries to find the last lisp expression in the editor buffer and sends it to the LISP process via stdin, the output from stdout(stderr) is then displayed in the editor buffer. Communicating with the LISP process happens in background, so a problems in the LISP process should not cause a hang of Jabberwocky (hopefully). A interaction buffer is needed if you want to debug some source code or if you want some syntax information in the hint window. If you close the interaction buffer, all sources debugged by this interaction buffer will be put back in editor mode and all watches using this buffer will be deleted.

Once a interaction buffer is established you can work with it in the following ways:

Watch Windows

A watch window is a editor buffer that allows you to send a form to the lisp subsystem for evaluation. The difference with a editor buffer is that the stdin, stdout is not used and that a error in the evaluation does not cause a break in the lisp process. This allows you te evaluate forms when debugging code or when running code is waiting on input from the console.

Debugging

Before you can debug a document, make sure that you started a LISP interaction window and that you have made it current, select then the editor buffer containing the source that you want to debug and press on to put the editor buffer in debug mode. When a editor buffer is place in debug mode, its content will be saved to a temporary file. Instrumentation code is then added to this file and the file is loaded by the LISP process of the current interaction buffer. A association between the instrumented code and the editor buffer is then made, thanks to this the debugger can bring the editor buffer to the foreground when a breakpoint is encountered. Once a editor buffer is in debug mode no editing of the document inside in it is possible. When you put back the buffer in edit mode the readonly flag is removed from the document and the original source code is loaded in the LISP process removing the instrumentation code. Everytime you select a editor buffer in debug mode a debug menu is added to the menubar and the following buttons are added to the button bar. If a editor buffer contains not just definitions but also some forms to execute (like testcode) it is better to use the following method (instead of debugging the whole source) (the editor goes in debugmode only when all the instrumented code is loaded and this can take some time for large source). It is also possible to control the generation of the instrumented code. Two options exist for this :

These options are considered advanced options, you should use them for example to make the instrumented code smaller, to improve load times (or compile times if you want to compile intstrumented code (be warned that the CMUCL compiler has some problems with dense code)).

It is also possible to debug selected code or the current form in a editor buffer without putting the editor buffer itself in debug mode. To do this select a piece of code or position the cursor in a form and press <ctrl-d> or choose <Interaction><Debug Selection/Form>. The selected code or the current toplevel form will then be copied in a new buffer which is placed in debug mode so that you debug only the selected code (current toplevel form). Disabling debugging of this extra buffer will automatically close it.

Return editor buffer to edit mode
Toggle a breakpoint
Toggle a conditional breakpoint
Step Into
Step Over
Stop At
Continue
Stop After
Add Watchpoint
Change Return Value
Step Backward In Time
Step Forward In Time
Start (reset) Profiling
Stop Profiling

Once a buffer is in debug mode, you can set a (conditional) breakpoint by placing the cursor on a lisp form and pressing () . The background color of the LISP form containing the cursor is then changed to indicate that a breakpoint is set on this LISP form. If you have set a conditional breakpoint, a popup editor buffer appears to specify the condition of the conditional breakpoint. The (conditional) breakpoint is entered whenever the LISP form is executed (for a conditional breakpoint, the condition has to evaluate to something else then NIL). When debugging code the following states exist :

Controlling the execution of code

Once control is given to the debugger the following is possible:

Time Traveling

The debugger has also a feature called time traveling, when a form is executed a history of the call to the form is maintained (currently the history depth is 100, but this can be changed with (DEBUGGER::prepare-time depth)). Each entry in the history contains a reference to the lisp form executed and a save of the lexical environment at the moment of the call). With time traveling you can step back or forward in time, highlighting the lisp forms which where executed at the chosen time and restoring the lexical environment so that you can watch the variables at that time. The following controls are possible for traveling:

Error handling

When during the run of debugged code a error occurs in the running code, the debugger is entered and the form which caused the error is highlighted. You can then use Change Return Value to set the return value of this form and continues execution.

Watching

When a editor buffer is in debug mode the state of a running program can be consulted on the following ways:

Profiling

Profiling allows you to do coverage analysis, when profiling is enabled the system will maintain for each lisp form executed a count of how many times this form is called. A slider is provided to allow you to highlight these forms executed at least as many times as the slider indicates. The following controls are possible:

ASDF support

It is possible to install asdf packages using Jabberwocky. Be aware of the following limitations:

For more information on asdf see asdf and asdf-install.

Adding asdf support.

Asdf support is not automatically enable, to enable it choose <Options><General><Configure ASDF for Jabberwocky> the following window appears then:

When the Ok button is pressed, Jabberwocky will compile the asdf.lisp file for the different available lisp interaction buffers, and if succeeded will compile and install asdf-install. Don't forget to do a save of the options to ensure that Jabberwocky remembers that asdf support is added. The bottom text box contains a output of the compilation and installation process, you should include the contents of this window when you send a bugreport.

Installing asdf packages

To install a asdf-package select <Interaction;><Use asdf-intall to install a lisp package>, the following window will then appear: