native repl

1.0.0

A portable, native, drop-in REPL for interactive command lines.

Table of Contents

About native-repl

This library lets you quickly and easily build customisable REPLs, including debuggers and so on. It provides nice defaults, a command system, and a plethora of debugging features like source viewing, frame restarting, and so forth.

If you ever find yourself needing or building a REPL, consider using the protocols from this library instead. By default it depends on no specific terminal or output features, instead being implemented purely with native Lisp character streams – hence the name.

However, building a more capable REPL that makes use of advanced terminal or graphical capabilities is of course also possible by hooking into the system and customising the input and output handling functions.

How To

The basic quick entry is to just run (org.shirakumo.native-repl:run T). This will provide a REPL with sane defaults and a nice presentation for a Unicode capable output stream. If you'd like to customise the output, you can instead subclass standard-repl, implement methods on its various IO functions, and call run on an instance of your class. The debugger is similarly extensible, by subclassing unicode-debugger and binding it via with-debugger.

See the respective classes' docstrings for more hints on the involved functions, how they work, and how you might override their default behaviour to suit your needs.

System Information

Version: 1.0.0

Dependencies:

Author: Yukari Hafner

License: zlib

Homepage: https://shinmera.com/docs/native-repl/

Bug Tracker: https://shinmera.com/project/native-repl/issues

Sources: https://shinmera.com/project/native-repl.git

Definition Index

ORG.SHIRAKUMO.NATIVE-REPL

No documentation provided.

EXTERNAL SPECIAL-VARIABLE

DEBUGGER

When the debugger is active, holds the debugger instance.

See DEBUGGER
See WITH-DEBUGGER
See WITHOUT-DEBUGGER

EXTERNAL CLASS

DEBUGGER

Representation of a debugger instance.

See WITH-DEBUGGER
See WITHOUT-DEBUGGER
See INVOKE
See ACTIVATE-DEBUGGER
See PRINT-RESTART
See PRINT-LOCAL-VARIABLE
See PRINT-BACKTRACE

EXTERNAL CLASS

HISTORY

Representation of a history of command records.

The history keeps a stateful record of commands that the user inputs,
lets you step through that history, and persist it to a backing
storage.

See RECORDS
See CURRENT-RECORD
See FIRST-RECORD
See LAST-RECORD
See NEXT-RECORD
See PREVIOUS-RECORD
See CLEAR-HISTORY
See RECORD
See SAVE-HISTORY
See LOAD-HISTORY

EXTERNAL CLASS

REPL

Representation of a REPL.

See PROMPT-STREAM
See VALUE-STREAM
See PRINT-INPUT-LINE
See INPUT-COMPLETE-P
See GET-INPUT
See READ-INPUT
See HANDLE-INPUT
See EVAL-FORM
See PRINT-VALUE
See PROCESS
See RUN
See COMMAND-NAMES
See DEFINE-REPL-COMMAND

EXTERNAL CLASS

SAVED-HISTORY

History that automatically saves to a file.

The file can be specified via the :FILE initarg.

See HISTORY (type)
See FILE

EXTERNAL CLASS

STANDARD-REPL

Standard convenient REPL class.

Combines a UNICODE-REPL with a SAVED-HISTORY, handles END-OF-FILE on
the input stream, and binding of a UNICODE-DEBUGGER during REPL
execution for unified error handling.

See UNICODE-REPL
See UNICODE-DEBUGGER
See SAVED-HISTORY

EXTERNAL CLASS

UNICODE-DEBUGGER

Debugger subclass that uses nicer unicode characters for value presentations.

See DEBUGGER
See PRINT-INPUT-LINE
See PRINT-VALUE
See PRINT-RESTART
See PRINT-LOCAL-VARIABLE
See PRINT-BACKTRACE
See INVOKE
See PREFIX

EXTERNAL CLASS

UNICODE-REPL

REPL subclass that uses nicer unicode characters for prompt and value presentation.

See REPL
See PRINT-INPUT-LINE
See PRINT-VALUE

EXTERNAL STRUCTURE

RECORD

Representation of a command history record.

See HISTORY (type)
See RECORD-INPUT
See RECORD-TIME
See RECORD-PACKAGE

EXTERNAL FUNCTION

EXIT-DEBUGGER

&OPTIONAL
LEVEL

Convenience function to invoke the EXIT-DEBUGGER restart.

The LEVEL may be the number of the debugger level to exit, allowing
multiple nested levels to be exited at once.

See DEBUGGER
See INVOKE

EXTERNAL FUNCTION

EXIT-REPL

&REST
VALUES

Invokes the EXIT-REPL restart.

See REPL
See RUN

EXTERNAL FUNCTION

FIND-PACKAGE-FUZZY

NAME
&OPTIONAL
ERRORP

Find a package of the given fuzzy name.

Both package names and package nicknames are considered. If multiple
matches occur, the lexicographically sorted first matching package is
returned.

If no matches occur and ERRORP is true an error is signalled, and if
it is NIL, NIL is returned.

See FUZZY-MATCHES.

EXTERNAL FUNCTION

FUZZY-MATCH-P

NAME
FUZZY

Returns true if the name fuzzily matches the fuzzy query.

The match succeeds if:
  Both are string-equal, or
  Considering parts of both (separated by either period, dash, or
  slash):
    There's fewer or the same number of parts in the fuzzy as in the
    name being matched against, and
    The fuzzy parts given each are a prefix of another part in the
    name, in the same order.

See FUZZY-MATCHES

EXTERNAL FUNCTION

FUZZY-MATCHES

FUZZY
OPTIONS
&KEY
KEY

Returns the options for which FUZZY is a fuzzy match.

Each option is transformed by KEY before passing it to FUZZY-MATCH-P.

See FUZZY-MATCH-P

EXTERNAL FUNCTION
PACKAGE-SHORT-NAME
- PACKAGE
Source
```
Return a shortened name for the given package.
```

EXTERNAL FUNCTION

RECORD-INPUT

INSTANCE

Accesses the input that was processed when the command was input.

This is the raw string that was entered by the user.

See RECORD (type)

EXTERNAL FUNCTION
(SETF RECORD-INPUT)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

RECORD-PACKAGE

INSTANCE

Accesses the package that was active when the command was input.

This is relevant when READing the input string.

See RECORD (type)

EXTERNAL FUNCTION
(SETF RECORD-PACKAGE)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

RECORD-TIME

INSTANCE

Accesses the universal-time timestamp at which the command was input.

See RECORD (type)

EXTERNAL FUNCTION
(SETF RECORD-TIME)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL GENERIC-FUNCTION

ACTIVATE-DEBUGGER

DEBUGGER

Primes the debugger to be invoked on the next unhandled condition.

See *DEBUGGER*
See DEBUGGER

EXTERNAL GENERIC-FUNCTION

CLEAR-HISTORY

HISTORY

Clears all records from the history.

See HISTORY (type)

EXTERNAL GENERIC-FUNCTION

COMMAND-NAMES

REPL

Returns a list of REPL command names.

When defining new REPL commands you should add a method to this
function that returns a list of your new command names.

See REPL
See DEFINE-REPL-COMMAND
See HANDLE-INPUT

EXTERNAL GENERIC-FUNCTION

CURRENT-RECORD

HISTORY

Accesses the current record in the history, if any.

When set to NIL the current record is removed from the history.

See RECORD (type)
See HISTORY (type)

EXTERNAL GENERIC-FUNCTION
(SETF CURRENT-RECORD)
- REMOVE
- HISTORY
No documentation provided.
EXTERNAL GENERIC-FUNCTION
EVAL-FORM
- REPL
- FORM
Source
```
Evaluates the given Lisp form.

See REPL
```

EXTERNAL GENERIC-FUNCTION

FIRST-RECORD

HISTORY

Rewinds the history to the first record made in the history, if any, and returns it.

See RECORD (type)
See HISTORY (type)

EXTERNAL GENERIC-FUNCTION

GET-INPUT

REPL
STREAM

Retrieves a singular input token from the stream as a string.

By default this will read lines from the stream and concatenate them
together until the concatenated string is complete as per
INPUT-COMPLETE-P.

See REPL
See INPUT-COMPLETE-P

EXTERNAL GENERIC-FUNCTION

HANDLE-INPUT

REPL
EXPR
&REST
MORE

Handles the input expressions

This is used to potentially transform the input before it is
evaluated, and in order to implement special REPL commands.

By default this will check if the given expression is a bound symbol
and if so, simply return the input again. If not, it will check if the
expression exactly matches a command-name, and if so, proceed with the
primary method which should handle that command. If not, it tries to
fuzzy-match the expression against all known command-names. If
multiple names match, the input is ignored an a message is output to
the value-stream. If there is exactly one matching name, handle-input
is invoked again with that name for the expression. If there are no
matches, the input is returned again.

Commands should provide primary methods specialising on the
expression. To do this, please use DEFINE-REPL-COMMAND.

You may add further methods to perform other input transformations and
commands as is appropriate for your specific REPL extension.

See REPL
See FUZZY-MATCHES
See DEFINE-REPL-COMMAND
See COMMAND-NAMES

EXTERNAL GENERIC-FUNCTION

HANDLED-CONDITION

OBJECT

Returns the condition the debugger is handling, if any.

See DEBUGGER

EXTERNAL GENERIC-FUNCTION
(SETF HANDLED-CONDITION)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

INPUT-COMPLETE-P

REPL
INPUT

Returns true if the given input string presents a complete expression that can be READ.

See REPL

EXTERNAL GENERIC-FUNCTION

INVOKE

DEBUGGER
CONDITION

Invokes the debugger for the given condition at the current program point.

This will set the debugger up to handle the current condition and
enters its repl. When the debugger is active (via WITH-DEBUGGER), this
function is automatically called when an unhandled condition occurs.

Will call RUN on the debugger after setting it up. During RUN, a
restart called EXIT-DEBUGGER will be available, which takes an
optional argument indicating the debugger level to exit from.

See WITH-DEBUGGER
See EXIT-DEBUGGER
See RUN
See LEVEL
See DEBUGGER

EXTERNAL GENERIC-FUNCTION

LAST-RECORD

HISTORY

Forwards the history to the last record made in the history, if any, and returns it.

See RECORD (type)
See HISTORY (type)

EXTERNAL GENERIC-FUNCTION

LEVEL

OBJECT

Returns the nesting level of the debugger.

If an error happens during debugging, this level will be increased by
one for the debugger handling that error.

See DEBUGGER

EXTERNAL GENERIC-FUNCTION
(SETF LEVEL)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

LOAD-HISTORY

HISTORY
SOURCE

Restores the history from the given source storage.

Returns the history object.
By default restoring from files and streams is supported.
You may add methods on this function to customise the supported input
sources and storage methods.

See HISTORY (type)

EXTERNAL GENERIC-FUNCTION

NEXT-RECORD

HISTORY
&KEY
WRAP

Forwards the history to the next record and returns it.

If WRAP is true, when reaching the end, it will wrap back around to
the first entry in the history, otherwise it will simply return the
last record, if any.

See RECORD (type)
See HISTORY (type)

EXTERNAL GENERIC-FUNCTION

PREFIX

OBJECT

The per-line prefix string that is printed for the debugger.

By default this is a number of vertical bars corresponding to the
debugger's nesting level.

See DEBUGGER

EXTERNAL GENERIC-FUNCTION
(SETF PREFIX)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

PREVIOUS-RECORD

HISTORY
&KEY
WRAP

Rewinds the history to the previous record and returns it.

If WRAP is true, when reaching the start, it will wrap back around to
the last entry in the history, otherwise it will simply return the
first record, if any.

See RECORD (type)
See HISTORY (type)

EXTERNAL GENERIC-FUNCTION

PRINT-BACKTRACE

DEBUGGER
TRACE
OUTPUT

Prints a backtrace to the stream.

The trace is a list of stack frames.

See DEBUGGER
See DISSECT:CALL

EXTERNAL GENERIC-FUNCTION

PRINT-INPUT-LINE

REPL
OUTPUT

Prints the prompt input line to the given stream.

If the stream is T, the REPL's prompt-stream is used.

See REPL
See PROMPT-STREAM

EXTERNAL GENERIC-FUNCTION

PRINT-LOCAL-VARIABLE

DEBUGGER
LOCAL
OUTPUT

Prints a local variable to the stream.

The local variable is a cons of variable name and value.

See DEBUGGER

EXTERNAL GENERIC-FUNCTION

PRINT-RESTART

DEBUGGER
N
RESTART
OUTPUT

Causes a restart to be printed to the stream.

N is the restart's index in the list of available restarts.

See DEBUGGER
See DISSECT:RESTART

EXTERNAL GENERIC-FUNCTION

PRINT-VALUE

REPL
N
VALUE
STREAM

Prints the given value to the REPL's value-stream.

N is the value's index in the list of returned values.

See REPL

EXTERNAL GENERIC-FUNCTION

PROCESS

REPL
PROMPT-STREAM
VALUE-STREAM

Handles a single processing step of the REPL.

This is the REP part of the REPL. It takes care of waiting for
complete input, reading the input, performing special handling,
evaluating it, printing the results, and managing the various REPL
state variables like ***, **, *, etc.

See REPL
See GET-INPUT
See READ-INPUT
See HANDLE-INPUT
See EVAL-FORM
See PRINT-VALUE

EXTERNAL GENERIC-FUNCTION

PROMPT-STREAM

OBJECT

The stream on which the input prompt is presented, and from which user input is read.

See REPL

EXTERNAL GENERIC-FUNCTION
(SETF PROMPT-STREAM)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

READ-INPUT

REPL
INPUT

Reads the given input into a Lisp expression.

See REPL

EXTERNAL GENERIC-FUNCTION

RECORD

RECORD
HISTORY
&KEY
TRUNCATE
&ALLOW-OTHER-KEYS

Store a new input record in the history.

If TRUNCATE is true, then records after the current record will be
removed before entering this new record. Otherwise the history will
jump to the end before inserting.

See RECORD (type)
See HISTORY (type)

EXTERNAL GENERIC-FUNCTION

RECORDS

OBJECT

Access the backing storage vector of history records.

See RECORD (type)
See HISTORY (type)

EXTERNAL GENERIC-FUNCTION
(SETF RECORDS)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

RESTARTS

OBJECT

Returns the list of restarts active at the time the debugger was invoked.

See DEBUGGER
See DISSECT:RESTART

EXTERNAL GENERIC-FUNCTION
(SETF RESTARTS)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

RUN

REPL

Runs the REPL.

This basically calls PRINT-INPUT-LINE and PROCESS in a loop, with an
EXIT-REPL restart bound.

See REPL
See PRINT-INPUT-LINE
See PROCESS
See EXIT-REPL

EXTERNAL GENERIC-FUNCTION

SAVE-HISTORY

HISTORY
TARGET

Persists the history to the given target storage.

Returns the history object.
By default outputting to files and streams is supported.
You may add methods on this function to customise the supported output
targets and storage methods.

See HISTORY (type)
See LOAD-HISTORY

EXTERNAL GENERIC-FUNCTION

STACK

OBJECT

Returns the list of call frames active at the time the debugger was invoked.

See DEBUGGER
See DISSECT:CALL

EXTERNAL GENERIC-FUNCTION
(SETF STACK)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

VALUE-STREAM

OBJECT

The stream to which the output is printed.

See REPL

EXTERNAL GENERIC-FUNCTION
(SETF VALUE-STREAM)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL MACRO

DEFINE-REPL-COMMAND

NAME
ARGS
&BODY
BODY

Defines a new command for the repl.

NAME may either be the name of the command, or a list composed of the
class name for which to provide the command and the name of the
command. ARGS should be a lambda-list of the arguments for the
command.

This expands into a function definition with the name COMMAND-name in
the native-repl package, and a method on HANDLE-INPUT specialised on
the class and the command name, which in turn calls the mentioned
function if the provided extra input expressions match the command
arguments. If not, a syntax note is printed to the REPL's value-stream
and the inputs are ignored.

After defining a command, you must also make sure that it appears in
the COMMAND-NAMES list of your class, otherwise the help and fuzzy
completion logic will not work properly.

See REPL
See HANDLE-INPUT

EXTERNAL MACRO

WITH-DEBUGGER

DEBUGGER
&BODY
BODY

Installs the debugger for use within the dynamic extent of the body.

INVOKE will be called on the debugger for any unhandled condition that
is signalled from BODY.

See WITHOUT-DEBUGGER
See DEBUGGER
See *DEBUGGER*

EXTERNAL MACRO

WITHOUT-DEBUGGER

&BODY
BODY

Disables the repl debugger within the dynamic extent of the body.

This will cause the standard debugger to be invoked on unhandled
errors again instead.

See WITH-DEBUGGER
See DEBUGGER
See *DEBUGGER*

EXTERNAL SOURCE-TRANSFORM
RECORD-INPUT
No documentation provided.
EXTERNAL SOURCE-TRANSFORM
(SETF RECORD-INPUT)
No documentation provided.
EXTERNAL SOURCE-TRANSFORM
RECORD-PACKAGE
No documentation provided.
EXTERNAL SOURCE-TRANSFORM
(SETF RECORD-PACKAGE)
No documentation provided.
EXTERNAL SOURCE-TRANSFORM
RECORD-TIME
No documentation provided.
EXTERNAL SOURCE-TRANSFORM
(SETF RECORD-TIME)
No documentation provided.