Back to index

LispMe User Interface

The Main dialog

Output field

Main dialog This is a read-only text field occupying the biggest area on the main dialog where the value computed by an evaluation is printed. Additionally output from display, newline, and write is printed here. Use the hardware scroll buttons to scroll the output field up and down one page at a time or use the scroll bar right (or left!) to the output field. The number of characters displayable in this field can be selected in the preferences dialog The positions of the scrollbar and the output field can be swapped with the lefthander option.

The output field is available to LispMe programs as a port stored in the global variable *outfield*.

Input field

These are the three underlined lines above the command buttons on the main dialog. You enter expressions to be evaluated here. At most 4096 characters can be input into this field. Depending on the selection (inverted text) different portions of the input field are evaluated, see Eval button for details.

Symbols

Symbol list Selecting this trigger pops up an alphabetically sorted list of all symbols known to LispMe, or a list of possible completions of the partial symbol to the left of the cursor (or, if any text is selected, the selected text). You can scroll the list and select any symbol in this list and it is immediately inserted into the Input field at the current cursor position.

You can also start writing a name when the list is popped up and the selection will jump to the first symbol matching the letters entered. This incremental search is a very little known Pilot feature, but speeds up entering LispMe code significantly! Unfortunately, this feature was known so little, that Palm forgot to put it into PalmOS5 :-(

You can also use the menu complete command. When a symbol is entered this way, LispMe automatically displays its argument list when the global option Show parms on completion is set.

Sessions

The currently active session is displayed here. Selecting this trigger goes to the sessions dialog where you can change to other sessions etc. Look here for a general description of LispMe's session concept.

Load button

Use this button to load a memo containing LispMe source code. This button invokes the Load dialog. To make this command work, you must have created a category named LispMe (case does matter) in the MemoPad, or you'll see the message *** Category 'LispMe' not found *** in the list box. Additionally, this category must contain at least one memo or you'll see *** No memo in 'LispMe' found *** in the list box. If you installed LispMe as described in installation, both conditions are met automatically.

Reload button

This button is just a shortcut to pop the current memo and load it again and thus saves several taps. Only the last loaded memo is recorded, but this is done for each session separately.

Pop button

Use this button to remove the most recent definition set from LispMe's memory. You'll get an error, if there are no definitions loaded. Note that this button does not remove unused symbols from the atom table, so popping definitions when you got the error Atom space exhausted won't help, use the menu command Reset heap instead.

Names button

Names listing All defined names are displayed as a list of lists in the output field. Each sublist corresponds to a loaded memo, or to a set of definitions entered into the input field. The most recent definitions appear at the front of the list. Each sublist is a list of the names defined (at top-level) in the corresponding memo. You can remove the most recent definitions with the Pop button. If no memo is loaded, the names list has a single sublist containing LispMe's global variables.

Info button

Argument display This button displays the argument list for the current symbol. If no text is selected, the current symbol is the text immediate to the left of the cursor in the input field. If any text is selected (both in the input or in the output field) the selection is the current symbol. It is displayed: When you set the option Show parms on completion, the info is displayed automatically when selecting a symbol from the symbol list.

Eval button

Starts evaluating the expression entered into the input field. During evaluation, all command buttons are disabled and replaced by the Break button, which interrupts evaluation. Switching to another application during evaluation will resume the evaluation when restarting LispMe.

To allow evaluation of sub-expressions, LispMe uses this logic:

You can also evaluate the second and third expression (either in the entire input field or in the selected text) with a menu command. Each expression evaluated is added to the history list to be re-evaluated later.

History popup list

History list Tapping the small triangle right to the Eval button pops up a list of the expressions evaluated recently (most recent at the bottom). You can re-evaluate any of them by simply tapping it left to the middle of the screen without modification of the input field. However, when you select an expression right to the middle of the screen, it is not evaluated but pasted into the input field, so you can modify it before evaluating it.

To make the list disappear without evaluating just tap outside the list. Since the history entries are stored as S-expressions, they may not exactly resemble the string you entered. The history list is stored together with the session database. Only expression not already in the history list (determined by equal?) are added.

The history list is available to LispMe via the global variable *hist*, so you can clear it by (set! *hist* '()) to reclaim its memory, e.g., or assemble typical invocations of your functions and let the user select them from the history list. (The poor man's menu system :-)

Break button

This button replaces the four other buttons, while LispMe is evaluating an expression or loading a memo. You can interrupt the evaluation by tapping this button, which displays a message box and cancels the evaluation. There's no way to resume an interrupted evaluation.

Menu commands

View menu

Runtime [/T]

Displays a message box showing the resources needed by the last evaluation: You can use this command during evaluation, the amounts displayed are the amounts comsumed upto now. Runtime will always be 0 seconds in this case.

Memory usage [/M]

Displays a message box showing the amount of memory currently in use. A garbage collection is always done before displaying this box, so the actual amounts are displayed. (Even during an evaluation!) All amounts display as current/maximum and are measured in bytes:

Redraw [/W]

Enables and redraws all controls and fields in the main form. Use this command when graphic output has overwritten some of LispMe's UI controls or when the dialog had been disabled by own-gui.

Edit menu

This is a standard edit menu like in other PalmPilot applications, e.g. MemoPad. These commands work on either the input or the output field, so one of them must have the focus. The modifying operations (undo, cut, and paste) work only with the input field.

Undo [/U]

Undoes the last change in the input field.

Cut [/X]

Copies the selected text in the input field to the clipboard and removes it from the input field.

Copy [/C]

Copies the selected text to the clipboard.

Paste [/P]

Pastes the text from the clipboard into the input field at cursor position.

Select All [/S]

Select all text in either input or output field.

Keyboard [/K]

Brings up the keyboard dialog.

Graffiti [/G]

Displays the Graffiti reference dialog.

Clear output [/D]

Clears the output field.

Clear input [/I]

Clears the input field.

Complete [/ ]

Tries to complete the partial symbol to the left of the cursor. (The shortcut is menu stroke space, if you wonder.)

Commands menu

Global settings [/Y]

Use this option to change global LispMe options. This menu command goes to the Global settings dialog.

Session settings [/Z]

Use this option to change the amount of memory used for the current session. This menu command goes to the Session Settings dialog. A running evaluation is interrupted before entering the sizes dialog.

Reset heap [/H]

Reset screen After displaying a confirmation box, this option re-initializes all LispMe memory and displays the reset screen. This means, that all your loaded and entered definitions are forgotten. Additionally, the atom table is cleared, in contrast to repeated popping, which doesn't remove unused symbols from the atom table.

Load [/L], Reload [/R], Pop [/O], Names [/N], Info [/?], Eval [/E]

All these menu commands do the same as the corresponding buttons. They are provided only to define a shortcut command stroke for users using the GoType keyboard.

Eval 2nd [/2], Eval 3rd [/3]

Same as Eval, but evaluates the second or third expression in the input field. Very useful when you want to test some expressions in turn.

Help menu

About [/A]

Copyright and version info.

General [/Q]

General help how to use LispMe's user interface.

Functions [/F]

Describes how to retrieve help for all builtin functions and special forms. Beginning with version 3.0, the earlier (hard-coded) function list available here has been replaced by a more general and extensible mechanism.

The Load dialog

Load screen Using the radiobuttons next to Format: you can select a source format. Currently supported formats are: With the Memo and Memo32 formats, a list of all memos in category Lisp is displayed. Only the first line of each memo is displayed, so it's a very good idea to start each memo with a one-line comment. With the DOC format, all DOC files are displayed by filename.

Select the file you want to load and tap the OK button to load and compile it, or tap Cancel to return to the Main form.

Note that loading a memo twice is not forbidden and can happen easily, if you edit a memo with MemoPad and reload it in LispMe. You should pop the memo before reloading it after modifications, or else both versions will occupy valuable heap. Use the Names button to see which memos are actually loaded. Loading a memo does not change the global variable it.

Tap the Memo button to jump directly to MemoPad to edit the currently selected Memo. If the last error while loading was a Syntax Error, tapping the Memo button directly goes to the offending source text.

The Edit buttons works likewise, but opens LispMe's internal editor.

If you installed pedit, there is also a pedit button which works like the Memo button but calls pedit

Jumping directly to a DOC editor is currently not supported.

The LispMe editor dialog

LispMe editor This is a very simple text editor, but it has four big advantages:
  1. Terminating it with the Done button leads back to the Load dialog.
  2. It can match parentheses even with PalmOS5, where hacks won't work anymore.
  3. There is the symbols list known from the main dialog, which greatly speeds up source code entry.
  4. The Eval selection button evaluates the selected text by copying it to the input field in the main dialog, leaving the editor and loader dialogs and simulates tapping Eval.

The Sessions dialog

Sessions This table shows all LispMe sessions on your Pilot (all databases with LispMe's creator ID fbLM) Select a sessions and tap the Switch button to make it the active session and return to the Main dialog.

Select a session and tap the Delete button to remove the session database (and the associated starter application) from your Pilot (after a confirmation message)

The number displayed left to the session name is the amount of memory (in kBytes) occupied by the session. You can change pre-allocated memory sizes with the Size button, which leads to the Memory Sizes dialog.

The checkbox at the very left indicates if a starter application exists for this session. A starter application is a tiny program which appears in the Pilot application launcher and starts LispMe with a selected session database and simulates tapping the Eval button. You can create/destroy starter applications by tapping this checkbox.

Tapping the New button invokes the New Session dialog.

If there are more than 10 sessions, you can scroll them with the hardware scroll buttons.

The New Session dialog

New session Enter the name of the new session here. As LispMe tries to create a new database with this name, the name must be different from all other database names on your Pilot. For example, you can't name a session MemoDB or LispMe, as those databases already exist. As database names are case-sensitive, you could name a database memodb, though this is not recommended because backing up those databases to a desktop with a cases-insensitive file system (Windows!) may cause trouble.

An error message is displayed when the session database couldn't be created.

A new session database is created with the smallest possible size settings, so the next step you should do is selecting appropriate Memory Sizes.

The Session Settings dialog

Session settings screen This dialog can be invoked from either the Main dialog using the Session settings menu option or from the Session dialog.

You can use the Memory usage menu command to see the amount of memory actually used for each kind of LispMe memory.

Changing one of the first 3 settings will reinitialize LispMe's memory, so you have to re-load all memos afterwards. Changing the output size only just clears the output field, but leaves LispMe's memory image intact.

In tight memory situation it's possible that a size increase fails, which displays this error message. Normally, you can continue to work with the old size, but in some situations PalmOS2 displays a Fatal Error and requires a soft reset. Sometimes this even happens when changing the sizes takes an unusual long time, but does not fail. I have currently no idea what's going wrong here, as this never occurred with PalmOS3 (Palm III). Any comments? A way to avoid this is reducing the size to minimum, leaving the dialog, reentering it and now selecting the bigger size.

Heap Size

This is the size in bytes allocated for cons cells and strings. Each cons-cell occupies 4 bytes.

Atom Size

This is the size in bytes allocated for symbols (atoms).

FP Size

This is the size in bytes allocated for floating point numbers. Each floating point number occupies 8 bytes (IEEE double precision).

Output Size

This is the maximum number of characters the output field can display. Longer output will be truncated and a message be displayed.

Case-sensitive symbols

This option determines if symbols differing only by their case are considered different or not. When it is unchecked, all symbols are converted to lower-case on reading. Note that all predefined names are in lower-case, so LispMe won't recognise DEFINE when this option is checked. To avoid confusion with symbols entered before and after this option changed, the heap is reset when changing case sensitivity.

The Global Settings dialog

Preferences screen In this dialog you choose global settings valid for all sessions.

UI Watchdog

Select the time limit an user interface event handler is allowed to run before it is interrupted to avoid unstoppable endless loops.

Print Depth

This option controls the maximum depth lists and vectors are printed to the output field.

Print quotes

Checking this option makes LispMe print expressions of the form (quote anything) in the abbreviated form 'anything. This applies to quasiquote, unquote and unquote-splicing as well.

No auto-off while eval

Checking this option will disable the auto-off timer while LispMe is computing. When the evaluation has finished, the auto-off feature is re-enabled. Use this for long lasting evaluations, but remember that this option together with an endless loop is an easy way to waste your batteries!

I'm a lefthander

Checking this option will place the scrollbar left to the output field, so lefthanders can use it more comfortably.

Allow oversized memos

The builtin MemoPad application has a limit of 4k texts. However, it's perfectly possibly to have bigger records in the MemoDB database, but not all applications handles them properly. LispMe has no problems with larger memos, but several other apps have.

Checking this option allows bigger memos than the MemoPad limit (upto 32k chars) within the internal editor. There is a number of problems with oversized (>4k) memos:

However, if you use a third party tool like the plink utility suite, bigger memos are no problem, you can install them, load them, and backup your modified memos.

Just play around with them, test it all, and see: the 4k limit is in the original MemoPad design, not in the database nor 3rd party tools.

Thus, if you're exclusivly using the Windows desktop, don't select this option.

Linux tools like pilot-xfer and install-memo work perfectly with oversized memos. Oversized memos are not important any more since pedit and DOC support is available now.

Set! already defined vars

When this option is selected, any definition evaluated will be converted to a set! of the variable being defined, if the name already exists. Thus, adding a new frame to the top-level environment when re-defining the name is avoided.

Show parms on completion

Setting this option makes LispMe display the argument list automatically when a symbol is selected from the symbol list or a symbol is entered by completion.

Match parentheses

Setting this option enables parentheses matching for all entryfields within LispMe, even when Parentheses Hack isn't active (or isn't available at all like in PalmOS5)

On the other hand, this option is suppressed when Parentheses Hack is active.