Portability library to customize REPL prompts.

trivial-toplevel-prompt

#+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


trivial-toplevel-prompt

Upstream URL

Author

License

trivial-toplevel-prompt

Version:

License:

Authors:

Dependencies:

Dependencies (0)

Dependents (0)