euslime

Interactive interpreter for EusLisp with support for completion, on-spot referencing, auto-documetation, definition search, and more. Euslime is built on top of slime and runs on emacs.

For a quick guide to emacs try the following links: - GNU Emacs - Guided Tour - Absolute Beginner's Guide to Emacs - Prof. Inaba Suggested Commands

Quick Start

1. Install

    apt install ros-melodic-euslime

1. Configure your emacs init file

    ;; ~/.emacs.el
    (add-to-list 'load-path "/opt/ros/melodic/share/euslime")
    (require 'euslime-config)
    (setq inferior-euslisp-program "roseus")
    (slime-setup '(slime-fancy slime-banner slime-repl-ansi-color))

1. Run

   Open emacs and type the command:

    M-x euslime

Using with eus10

Compile from source with the eus10 branch: https://github.com/jsk-ros-pkg/euslime/tree/eus10.

The following command allows to automatically shift between apt and source euslisp builds.

;; ~/.emacs.el
(if (string-prefix-p "/opt" (getenv "EUSDIR"))
    (progn
      (add-to-list 'load-path "/opt/ros/melodic/share/euslime")
      (setq euslime-compile-path (expand-file-name "~/.euslime_opt/")))
  (add-to-list 'load-path "/home/affonso/euslime_ws/install/share/euslime"))
(require 'euslime-config)
(setq inferior-euslisp-program "roseus")
(slime-setup '(slime-fancy slime-banner slime-repl-ansi-color))

Logging

The following setting will save logs of all your sessions on exit.

;; ~/.emacs.el
(defun euslime-save-logs ()
  (when (get-buffer "*slime-events*")
    (with-current-buffer (get-buffer "*slime-events*")
      (let* ((logdir (concat (file-name-as-directory euslime-compile-path) "log"))
             (filename (concat "euslog." (format-time-string "%s" (current-time)))))
        (unless (file-exists-p logdir)
          (make-directory logdir t))
        (write-file (expand-file-name filename logdir))))))
(add-hook 'kill-emacs-hook 'euslime-save-logs)

Cheat sheet

Build from Source

1. Setup

    # Clone code
    mkdir ~/catkin_ws/src -p
    cd euslime_ws/src
    git clone https://github.com/jsk-ros-pkg/euslime.git
    # Install dependencies
    rosdep install -yr --from-paths . --ignore-src

1. Build

    cd ~/catkin_ws
    catkin build

1. Configure your emacs init file with the source directory

    ;; ~/.emacs.el
    (add-to-list 'load-path "~/catkin_ws/src/euslime")
    (require 'euslime-config)
    (setq inferior-euslisp-program "roseus")
    (slime-setup '(slime-fancy slime-banner slime-repl-ansi-color))

1. Run

   Source the package

    source ~/euslime_ws/install/setup.bash

Then open emacs and type the command:

    M-x euslime

Run tests

# Run all tests
tests/euslime_tests.py

# RUN TESTS FOR EUSLISP PROGRAM
tests/euslime_tests.py eus
tests/euslime_tests.py irteusgl
tests/euslime_tests.py roseus

# RUN A SINGLE TEST
tests/euslime_tests.py eus.test_eval_1

# RUN MATCHING TESTS
tests/euslime_tests.py eus.test_eval_*
tests/euslime_tests.py *.test_eval_1

How it Works

Euslime is composed by several layers of software, ultimately connecting the emacs interface to the EusLisp interpreter.

EMACS acts as the front-end interface, accepting user input and displaying output correspondingly. It also provides a series of modes, commands and key bindings for improved user experience, which are introduced at the original slime framework and slightly customized at euslime.el and euslime-config.el.

SWANK is the original slime backend, which handles interactions with emacs by delimiting a protocol that translates emacs commands into s-expressions. Such expressions are sent to and from the inferior lisp client (originally Common Lisp, in this case EusLisp) during an exchange which is logged at the *slime-events* buffer on emacs. A simple example is given below, illustrating an evaluation request for (1+ 1) followed by an output request for 2.

(:emacs-rex
 (swank-repl:listener-eval "(1+ 1)\n")
 "COMMON-LISP-USER" :repl-thread 6)
(:write-string "2" :repl-result)

PYTHON WRAPPER is responsible for encoding and decoding swank commands into actual EusLisp input/output, as well as managing the communications between the swank and the EusLisp layers. In the above example, this means that the python middleware would forward the expression (1+ 1) for evaluation in the EusLisp client, and then wrap the result into a suitable :write-string form which is finally sent to the emacs in order to display it on the screen. Although such functionality was originally implemented on slime as a part of the native common lisp framework, here we opt to establish an additional python layer due to its ability to (i) handle multithreading; (ii) cope with EusLisp crashes without compromising the emacs session; and (iii) minimize changes done to the EusLisp lexical environment.

The python middleware is divided into six files with well determined functionality, as detailed in the following.

server.py configures a socket server that communicates with the swank layer, receiving and answering to requests.

protocol.py parses incoming s-expressions into python functions, and also defines utility used to generate common swank forms, such as evaluation results or errors.

handler.py holds the actual definitions of the python functions responsible for handling the swank requests. For instance, the swank_repl_listener_eval function which answers to :swank-repl:listener-eval requests.

bridge.py deals with the communications with the EusLisp layer. The EusLisp interpreter is started as a subprocess and interacts with the python layer through pipes and sockets. Pipes are used to pass user input and program output, while sockets are used to transmit evaluation results, errors, and to process other internal requests while avoiding updating the REPL history and variables.

logger.py configures the logging function, which is displayed in the *inferior-lisp* emacs buffer.

cli.py bundles all of the above and arranges command line arguments for an euslime executable invoked upon startup.

Finally, in the EUSLISP layer a new package named SLIME is defined and a few overwrites are performed in order to establish a framework for properly dealing with socket communications and handler requests. Such functionality is distributed among the following three files:

slime-util.l gathers utility function designed to promptly respond to handler requests which would be hard to define solely with python coding, such as autodoc and completion.

slime-connection.l configures the socket communication framework, defining two different socket channels: one started from another thread allowing parallel evaluation and the other added to the top-selector allowing access to thread special variables. A custom input stream which communicates to swank at every read attempt is also defined here, allowing for the slime framework to differentiate user input answering to read functions from new evaluation requests.

slime-toplevel.l mainly overwrites lisp repl functions and error handlers so that they can send suitable socket information at each step of the evaluation. It is also responsible for setting up the sockets and streams defined at slime-connection and starting the main evaluation loop.

A more detailed explanation can be found in technical-report.md.