LispPad

Lightweight Scheme Development on macOS and iOS

LispPad Manual

LispPad Manual

    Sessions

    Using the interpreter

    Sessions

    LispPad allows users to manage four different types of documents: for sessions, for code, for text documents, and for drawings. Sessions are used to load, debug and execute Lisp code. A new session is created via the "File > New Session" menu item.

    Each LispPad session represents a virtual machine for executing Scheme code. Users can run multiple sessions simultaneously. Sessions are isolated and cannot interact with each other. The primary means to interact with the virtual machine is the read-eval-print loop:

    • Users enter Scheme code after the prompt . Pressing Return will submit the code only if parenthesis are balanced. This makes it possible to write Scheme code spanning multiple lines also in the read-eval-print loop.
    • The Scheme code gets compiled and executed
    • The result gets printed below the prompt. Results are printed in blue.

    Here is an example for an interaction with the read-eval-print loop:

    
    ➤ (+ 3 8)
    11
    ➤ (map fx1+ '(1 2 3 4))
    (2 3 4 5)
    

    The expression (+ 3 8) was entered by the user and evaluates to 11. The expression entered on the second prompt evaluates to the list (2 3 4 5).

    Session window

    The session window typically looks like this:

    Stacks Image 5

    The buttons in the toolbar have the following functionality:

    • Load will load a new program into the session and execute it, modifying the state of the session.
    • Stop will stop the current execution of code. This is the only way to stop non-terminating loops.
    • Reset discards the current state of the session and completely restarts it from scratch.
    • Clear will wipe the content of the session window (the transcript) without discarding any internal state.
    • Save will save the content of the session window (the transcript) into a file.
    • Print will print the content of the session window (the transcript).

    Within session (and editor) windows, invoking the "Help > Show Quick Help..." menu item (e.g. via ⌘D) will trigger a documentation lookup for the identifier at the cursor position. Documentation for the selected identifier is shown as a popover dialog. The Environment inspector provides means to browse and search identifiers of the interaction environment of sessions. It also displays documentation for selected identifiers.

    Within a read-eval-print loop, the results of the past 3 evaluations is available via the symbols *1, *2, and *3. The following key shortcuts are available in the read-eval-print loop:

    • ⌥↑ (option + cursor-up) and ⌥↓ (option + cursor-down) can be used to browse through the history of past commands.
    • ⌘↑ (command + cursor-up) and ⌘← jumps to the beginning of the current command that is being entered
    • ⌘↓ (command + cursor-down) and ⌘→ jumps to the end of the current command that is being entered
    • ⇧⌘↑ (shift + command + cursor-up) and ⇧⌘← selects the text between the start of the current command and the current cursor position
    • ⇧⌘↓ (shift + command + cursor-down) and ⇧⌘→ selects the text between the current cursor position and the end of the current command
    • ⌘⌫ (command + delete) deletes the current command

    Session inspectors

    Selecting the Show Sidebar button in the toolbar will toggle the sidebar, revealing four different inspectors:

    • Info will display information about the state of the Scheme interpreter.
    • Libraries will show a list of all loaded libraries, including references to the documentation of the libraries.
    • Environment will show a list of all bound symbols together with the corresponding values they are bound to and allow for searching, filtering, and displaying documentation.
    • Expressions allows users to enter Scheme expressions which are being evaluated every time the interpreter is going through a read-eval-print loop iteration.

    Here is a screenshot of the Libraries inspector:

    Stacks Image 11

    The following screenshot showcases the Environment inspector:

    Stacks Image 15

    Session log

    Session interactions are logged in a central logging system. It can be accessed via the menu item "Window -> Session Log".

    Stacks Image 19

    The log can be filtered by session, severity, and by a string which applies to the log messages and/or logging tags. The scope of the free-form text filter can be adjusted by clicking on the lens symbol. Individual columns can be switched on and of by right/control-clicking on the table header. There is also a button for exporting the log into a text file and a button for clearing the full log.

    The LispPad session log is also used by the libraries (lispkit log) and (lisppad log) so that all log messages, also from Scheme code itself are centrally collected and available via the session log window.

    Editor

    Editing code

    LispPad allows you to write Scheme code directly using the built-in code editor. There are two different types of code documents that can be edited: programs (usually with file name suffix .scm) and _libraries (with suffix .sld).

    Programs

    Programs consist of executable code. They can be loaded into a session and executed with the "Session > Load File..." menu item, or the corresponding button in the session toolbar. Alternatively, the code editor window allows users to load the current code into the last active session via the "Session > Run" menu item.

    Libraries

    Libraries define reusable modules of Scheme definitions. Libraries import functionality from other libraries and export a named set of definitions. Just like programs, libraries can be loaded into a session, but all this does is to make the library available for import. As an example, (import (lispkit datatype)) will import the library (lispkit datatype). The library definition for (lispkit datatype) needs to be stored in a file with path name lispkit/datatype.sld within a libraries directory defined in the LispPad preferences.

    Editor window

    The editor window typically looks like this:

    Stacks Image 33

    The buttons in the toolbar have the following functionality:

    • Run loads the content of the window into the last active session and executes it there.
    • Definitions shows a list of all definitions (values, functions, record types, etc.). Selecting a definition will jump to the line where the definition is made.
    • Jump to line jumps to the line with the entered line number
    • Auto-indent re-indents all the lines that are selected
    • Indent inserts a space character at the beginning of all selected lines.
    • Outdent removes a space character (if it exists) at the beginning of all selected lines.
    • Comment inserts a semicolon (;) character at the beginning of all selected lines.
    • Uncomment removes a semicolon (;) character (if it exists) at the beginning of all selected lines.
    • Print prints out the content of the editor window.

    Via LispPad's preferences, it is possible to customize editor windows in the following way:

    • Line numbers can be enabled/disabled
    • Page guides can be enabled/disabled and it can be defined where those are drawn in terms of number of characters per line
    • The current line can be highlighted
    • Matching parenthesis can be highlighted
    • Syntax coloring can be enabled/disabled
    • Automatic line indentation can be enabled/disabled

    All settings are applicable to all editor windows, but changes to the settings will only take effect for new windows, or when the application is restarted or windows reopened.

    Preferences

    Customizing preferences

    Preferences of LispPad are defined on four different tabs for configuring the Lisp environment, the console with the read-eval-print loop, the built-in text editor, as well as syntax highlighting used in editor and session windows.

    Environment

    Every time a new session is created, a prelude is being loaded into the interpreter and executed. The prelude is a Scheme program (a .scm file) which is used to set up a session. The "Prelude" setting on the environment tab can be set to two different values:

    • Default loads the default/internal prelude of LispPad
    • Custom loads the prelude from a custom file

    It is possible to load the default/internal LispPad prelude file into an editor window by opening the "File" menu and pressing the "control" key. This will show the menu item "Open LispPad...". Selecting it will bring up an "Open File" dialog for the folder that contains all LispPad-internal files. "Prelude.scm" is the default prelude file.

    Similarly, it is possible to browse LispKit-internal files by opening the "File" menu and pressing the "option" key.

    Libraries referenced from Scheme code are looked up from a set of folders. The "Libraries" setting controls how libraries are found. It can be set to two different values:

    • Internal only finds library definitions automatically that come natively installed with LispPad.
    • Custom allows users to define a root folder from which library definitons are looked up. This folder can be located outside of the application sandbox. If libraries are not found there, they are being looked up in the set of natively installed libraries. This mechanism allows users to override default libraries by providing alternative implementations in the custom library folder.

    LispPad provides a similar mechanism to reference asset files (e.g. images, videos, files, etc.) from Scheme code. The "Assets" setting controls how such asset files are found. It can be set to two different values:

    • Internal only finds assets that come natively installed with LispPad.
    • Custom allows users to define a root folder from which asset files are looked up. This folder can be located outside of the application sandbox. If asset files are not found there, they are being looked up in the set of natively installed asset folders. This mechanism allows users to override default assets by providing alternative versions in the custom asset folder.

    Since the LispPad application is sandboxed, it is difficult to read and write files from outside of the sandbox. In order to work around this limitation, LispPad allows users to define a custom Project folder. This is controlled via the "Project" setting:

    • Sandbox assumes that the project folder is located within the sandbox of the application
    • Custom allows users to define a custom project folder outside of the sandbox.
    Stacks Image 42

    Console

    LispPad allows users to configure the following aspects of sessions:

    • Console font: The font used by the read-eval-print loop in the console of a session.
    • Highlight matching parenthesis: Shows matching parenthesis when entering code in the read-eval-print loop in the console of a session.
    • Require balanced parenthesis: When this option is set, the read-eval-print loop does not allow users to submit unbalanced code.
    • Highlight syntax: When this option is set, syntax will be highlighted when entering code in the read-eval-print loop in the console of a session.
    • Markup identifiers with documentation: When this option is set and Highlight syntax is enabled, identifiers for which LispPad has documentation available are marked up in a color that can be specified in the Syntax preferences pane.
    • Automatically show completions after N seconds: When this option is set, LispPad shows possible completions for the currently typed identifier after N seconds of typing inactivity.
    • Command history: The number of read-eval-print loop inputs remembered in a session. Users can switch between those by using the key combinations <option>+<cursor up> and <option>+<cursor down>.
    • Prompt: Defines the prompt used for indicating input in the read-eval-print loop.
    • Log: Commands and results: When this option is set, all commands executed in the read-eval-print loop will be logged and are accessible in the session log, which can be displayed by selecting "Session Log" from the "Window" menu.
    • Log: Garbage collection: When this option is set, all garbage collector runs are logged and are accessible in the session log, which can be displayed by selecting "Session Log" from the "Window" menu.
    • Log history: The number of entries to keep in the session log. As soon as the number of session log entries has reached its limit, the oldest entries are getting purged when new entries are being added.
    Stacks Image 46

    Editor

    LispPad allows users to configure the following aspects of editor windows:

    • Editor font: The font used in editor windows.
    • Highlight current line: When set, the line in which text is being edited is highlighted in yellow.
    • Show page guide: When set, each text editor window will show a page guide at a certain text column specified by the setting "Page guide at column".
    • Show line numbers: When set, each text window will display line numbers at left side of the text.editor
    • Highlight matching parenthesis: When set, matching parenthesis are highlighted while code is being edited.
    • Automatically show completions after N seconds: When this option is set, LispPad shows possible completions for the currently typed identifier after N seconds of typing inactivity.
    • Page guide at column: Show a page guide on editor windows after the given amount of characters.
    • Tab size: Size of a single tab expressed in number of characters.
    Stacks Image 50

    Syntax

    LispPad allows users to configure syntax highlighting for both Scheme as well as Markdown formats. Syntax highlighting can be controlled in three different ways:

    1. Syntax highlighting can be switched on/off on a per-format basis
    2. Automatic indentation can be switched on/off on a per-format basis
    3. Colors that are used by the syntax highlighter can be freely configured.

    There are two checkboxes with the following semantics:

    • Highlight syntax: When this option is set, syntax will be highlighted while code is being edited.
    • Automatic indentation: When set, code is automatically indented in each editor window.
    • Markup identifiers with documentation: When this option is set and Highlight syntax is enabled, identifiers for which LispPad has documentation available are marked up in the specified color.
    Stacks Image 54