euslime repository

Repository Summary

Checkout URI https://github.com/jsk-ros-pkg/euslime.git
VCS Type git
VCS Version master
Last Updated 2020-10-13
Dev Status DEVELOPED
CI status No Continuous Integration
Released RELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

Name Version
euslime 1.1.0

README

euslime

Slime for EusLisp

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

Build from Source

  1. Setup
    # Clone code
    mkdir ~/euslime_ws/src -p
    cd euslime_ws/src
    git clone https://github.com/jsk-ros-pkg/euslime.git
    # Update submodules
    cd euslime
    git submodule init
    git submodule update
    # Install dependencies
    rosdep install -yr --from-paths . --ignore-src

  1. Build
    cd ~/euslime_ws
    catkin config --install
    catkin build

1. Configure your emacs init file


```lisp
    ;; ~/.emacs.el
    (add-to-list 'load-path "~/euslime_ws/install/share/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

Cheat sheet

On slime buffer
[TAB] completion
C-c C-d d describe/ help
C-c C-d a apropos
C-c C-d p apropos package
M-. look for definition
C-c [RET] macroexpansion
,quit quit session
,restart-inferior-lisp restart session
On editing buffers
C-c TAB completion
C-c C-c load expression
C-c C-l load-file
On other slime buffers
q quit buffer
[RET] select option

How it Works

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

euslime-communications

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 euslime.el, euslime-config.el, and at the original slime framework.

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 result or errors.

handler.py holds the actual definitions of the python functions responsible for handling the swank requests. For instance, the swank_eval function to answer 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 slime package 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.

CONTRIBUTING

No CONTRIBUTING.md found.