https://github.com/aartaka/trivial-toplevel-prompt

Portability library to customize CL implementations' REPL prompt.
https://github.com/aartaka/trivial-toplevel-prompt

common-lisp lisp listener prompt repl

Last synced: about 1 month ago
JSON representation

Portability library to customize CL implementations' REPL prompt.

• Host: GitHub
• URL: https://github.com/aartaka/trivial-toplevel-prompt
• Owner: aartaka
• License: bsd-3-clause
• Created: 2023-09-09T14:39:50.000Z (over 1 year ago)
• Default Branch: master
• Last Pushed: 2024-02-25T23:14:15.000Z (11 months ago)
• Last Synced: 2024-02-26T00:24:06.137Z (11 months ago)
• Topics: common-lisp, lisp, listener, prompt, repl
• Language: Common Lisp
• Homepage:
• Size: 41 KB
• Stars: 5
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

        
#+TITLE:Trivial Toplevel Prompt

Trivial Toplevel Prompt is a petty portability library to set the

implementation-specific REPL prompt to a new, possibly more useful,

value. It allows showing the inspect/debug/stepping statuses alongside

the command number, current package, and current process or thread.

Tested on SBCL, CCL, ECL, ABCL, CLISP, Allegro CL (basically all the

implementations I can run), and CMUCL (untested, incomplete). Help in

supporting other implementations (like [[http://www.lispworks.com/documentation/lw80/lw/lw-lispworks-87.htm#lispworks_marker-line-3817][LispWorks with its *prompt*]]) is

much appreciated!

* Getting started

Clone the Git repository:

#+begin_src sh

  git clone https://github.com/aartaka/trivial-toplevel-prompt ~/common-lisp/

#+end_src

And then load ~:trivial-toplevel-prompt~ in the REPL:

#+begin_src lisp

  (asdf:load-system :trivial-toplevel-prompt)

  ;; or, if you use Quicklisp

  (ql:quickload :trivial-toplevel-prompt)

#+end_src

You can also install Trivial Toplevel Prompt via Guix, using the

bundled =guix.scm= file:

#+begin_src sh

  guix package -f guix.scm

#+end_src

* APIs

The main API function is =set-toplevel-prompt=. The values that it

accepts are:

- String :: use it as a format control.

- Function :: use it to print the prompt to the REPL stream.

Arguments provided to both the format control and the printing

function are (mostly modeled after Allegro CL APIs):

- Stream to print the prompt to. Only provided for the function, implied for the string.

- The current process/thread name (a string) or NIL when not provided/meaningless.

- The shortest possible name/nickname of the current package (=cl:*package*=).

- A number indicating the command/expression number.

- A number indicating the current break/debug level.

- A boolean indicating whether stepping is enabled.

- A boolean indicating whether =inspect= is in progress.

Note that some implementations have custom REPLs for stepping and

inspection, so =set-toplevel-prompt= will be useless for inspect and

stepping arguments.

Then there's =reset-toplevel-prompt= to undo the effect of =set-toplevel-prompt=, basically restoring the previous prompt state.

* Examples

Here's a simple format control example: just skip the process name, print package name and command number.

#+begin_src lisp

  (trivial-toplevel-prompt:set-toplevel-prompt "~*~a~@[(~d)~]: ")

  ;; CL-USER(7):

#+end_src

And a more involved, Allegro-style (=[4si] CL-USER(29):=) prompt:

#+begin_src lisp

  (trivial-toplevel-prompt:set-toplevel-prompt

   (lambda (stream process/thread-name package-name

            command-number debug-level stepping-p inspect-p)

     (declare (ignorable process/thread-name))

     (when (or debug-level stepping-p inspect-p)

       (format stream "[~@[~d~]~@[s~*~]~@[i~*~]] "

               debug-level stepping-p inspect-p))

     (format stream "~a~@[(~d)~]: " package-name command-number)))

  ;; [4si] CL-USER(29):

#+end_src

And then reset it:

#+begin_src lisp

  (trivial-toplevel-prompt::reset-toplevel-prompt)

  ;; CL-USER(7):

  (trivial-toplevel-prompt::reset-toplevel-prompt)

  ;; Back to implementation-specific prompt.

#+end_src