This chapter describes Emacs VLS commands that work the same way
regardless of the Lisp specification or implementation. In some rare
cases a specific Lisp may completely change the semantics of the vanilla
command, See section Mechanism Specifics Parameters. The Emacs documentation
of such commands will reflect accurately what it does and it usually
does what you would expect the vanilla command to do in that special
Lisp type case. In some common cases where the vanilla command for a
specific Lisp just differs in a small way, such as a slightly different
meaning of a command prefix argument, those command differences are
covered in another chapter, See section Other Flavored Commands. In all
cases the Emacs documentation (C-h d or describe-function)
for any VLS command should accurately reflect what the command does for
the current Lisp process.
The Instrumentation commands are in this same category of vanilla commands but deserve a separate chapter, See section Instrumenting Code.
When we talk about "eval" commands we mean commands that send some data to the Lisp process for interpretation. A common case of this is sending a Lisp s-expression to the Lisp process read-eval-print loop. And in all cases when the Lisp process returns a value or it wants to print some text, the Lisp shell will print the value or values or text in the Lisp shell buffer.
The basic Lisp read-eval-print loop is simple and the only thing that it can evaluate is a Lisp s-expression. But modern Lisps are not this simple and allow other kinds of interpretation. For example non-s-expression commands to a debugger are now vogue. These kinds of modern divergences from the old basic Lisp read-eval-print loop creates two interesting issues for the modern Lisp shell. The first is that there are many different classes of things to evaluate or interpret: s-expression, a line, a region, a letter, a word ... etc. The second issue is that it opens up the possibility of different kinds of evaluation paradigms. For example one paradigms might be to operate the Lisp shell buffer as something like a prompt-enter-return paradigm of a Unix shell. Another paradigm might be to operate the Lisp shell buffer as a free form scratch pad. VLS attacks deals with these issues by giving the user all possible choices rather than imposing a single style.
The default settings are more inclined to more of a free form scratch
pad paradigm. But VLS makes it easy for the user to set up things they
way they like it. The way that VLS does this is to have a one eval
command vls-eval that is easily customized. Basically the way
that vls-eval works is to execute one of a collection of evals
commands that VLS or the user provides. The user can easily change
these evals commands in his ~/.emacs file.
First we describe vls-eval and then each of the commands that by
default it can execute.
Command: vls-eval Keys: M-RET Action: Execute the 0th
(first) eval command on the list vls-evals. By default this is
vls-eval-previous. A numeric prefix argument N will execute the
Nth eval command in vls-evals. A C-u prefix argument will
list all of the eval commands in vls-evals.
Variable: vls-evals Meaning: Contains a list of eval commands to
be executed by vls-eval. The user can set this list to their
choosing by setting it in their ~/.emacs file. For example
(setq vls-evals '(vls-send-input my-special-eval vls-eval-previous))
would cause vls-eval to execute the vls-send-input
command. And with a prefix argument of 1 it would execute a command
called my-special-eval.
To have vls-eval execute a command with a specific prefix
argument just specify a list form in vls-evals that is similar to
a function call with arguments. For example if in the previous example
my-special-eval does an even more special thing with a prefix
argument of 9 you could do something like
(setq vls-evals '(my-special-eval vls-eval-previous (my-special-eval 9)))
Then vls-eval with no prefix argument would execute
my-special-eval and vls-eval with a prefix argument of 2
would execute my-special-eval as if given a prefix argument of 9.
Command: vls-eval-previous Action: Send the previous s-expression
from point to the current Lisp process. This is the default evaluator
for vls-eval and supports the idea of a free form scratch pad
paradigm for talking to the Lisp process because any expression or
sub-expression in the Lisp shell buffer, Lisp file buffer or any Lisp
buffer can be evaluated with this command. To send Lisp data that is
not on the form of a s-expression use vls-send-input or
vls-send-region.
Command: vls-send-input Keys: C-c RET Action: Send the
last entered input into the Lisp shell buffer to the current Lisp
process. Note that this command is not intended to work on other points
in the buffer other than the last entered data and only works in
a VLS shell buffer. It is also useful for sending non-s-expression
data to the current Lisp process from the current Lisp shell buffer.
Command: vls-send-region Action: Send the Emacs region (from
point ro mark) to the current Lisp process.
Command: vls-eval-definition Keys: C-M-x Action: Send the
top level definition that point is in in to the current Lisp process.
This section describes the VLS commands related to the Lisp Shell Buffer itself and associated Lisp process.
Command: vls-exit-lisp Keys: C-c ! Action: Exits the
Lisp process associated with the current Lisp shell buffer and asks to
delete the buffer.
Command: vls-make-current Keys: C-c C-x c Action: Makes
the current buffer, if it is a VLS Lisp Shell buffer, the Current Lisp
shell buffer and process.
Command: vls-interrupt-lisp-process Keys: C-c C-c Action:
Interrupts the current Lisp process and usually causes an immediate
exception stack break in the current Lisp buffer so that the user can
examine the state of the Lisp process.
Command: vls-kill-last-output Keys: C-c C-o Action:
Kills all output from the Lisp process since the last manual eval in the
current Lisp Shell Buffer. The output is placed onto the top of the
Emacs kill stack so that you can yank it back with the yank
command.
Command: vls-yank-last-input Keys: C-c C-y Action: Yanks
the last input set to the current Lisp process at point. Successively
repeating this command will yank previous inputs from the input ring of
the current Lisp process. Each Lisp shell has its own input ring.
Variable: vls-input-ring-size Meaning: Indicates the maximum size
of Lisp shell input rings. The default setting is 16.
Command: vls-focus-process Keys: C-c C-x f Action: Some
Lisps have a multiprocessing capability. For the ones that do there is
usually an available list of processes. A VLS Lisp Shell can only be
focused on one of those processes at at time. What it means to be
focused on a Lisp process in a VLS Lisp shell buffer is that when you
send s-expressions or other data to the Lisp process to be evaluated the
focused process is the one that will receive the s-expressions or data
and respond. In other terminology the focused process is the active
Lisp Listener. This command focuses the current Lisp shell on the first
process in the current Lisp process list. A numeric prefix argument N
focuses on the Nth Lisp process. A C-u prefix argument prints
the list in the Lisp shell buffer so that you know which is which.
Command: vls-reload-specifics Keys: "C-c C-x R" Action:
Reloads the Lisp specifics file associated with current Lisp Shell
buffer. This is useful when you want to modify a Lisp specifics file
and want it to take effect without rerunning the Lisp shell.
Most VLS Lisp commands work the same way whether in a Lisp file buffer or in a Lisp shell buffer. The commands in this section have a slightly different meaning if the current buffer does not have a file associated with it; in that case one will be prompted for. This provides a convenient way to operate on a prompted Lisp file by going to a VLS Lisp shell buffer and executing any one of these commands.
Command: vls-compile-file Keys: C-c c Action: The current
buffer's Lisp file is compiled in the current Lisp process. A
C-u prefix argument will evaluate and compile just the current
definition that point is in.
Command: vls-load-source Keys: C-c l Action: The current
buffer's file Lisp source is loaded into the current Lisp process. A
C-u prefix argument causes the result of each expression to be
printed in the current Lisp buffer as it is loaded.
Command: vls-load-source-or-binary Keys: C-c C-l Action:
The current buffer's file Lisp source or binary file is loaded into the
current Lisp process. Which ever is loaded depends on the rules for the
current Lisp for what gets loaded when a file minus it's extension is
specified to be loaded. A C-u prefix argument causes the result
of each expression to be printed in the current Lisp buffer as it is
loaded.
This section lists the VLS commands for getting information from the current Lisp process or VLS program.
Command: vls-apropos Keys: C-c i a Action: In Lisps that
have an apropos facility do an apropos on the symbol that point is on.
Command: vls-describe Keys: C-c i d Action: Describe the
symbol of the current Lisp process that point is on in the current
buffer.
Command: vls-help Keys: C-c h Action: Prints out a list of
Lisp special mode commands in the current Lisp shell buffer. Typically
this list is useful when debugging but in some Lisps can contain other
helpful commands.
Command vls-version Keys: C-c i v Action: Show the
currently running version of VLS.
Some Lisps, such as Common Lisp, have symbol package systems. This section only applies to those kinds of Lisps.
When evaluating expressions in a Lisp file with any VLS eval command VLS
automatically searches the file for an expression that declares what
package a following expression should be evaluated in. For example in
Common Lisp this is an in-package expression. If for some reason
you don't want that to happen you can narrow the Lisp file buffer to
just the expression or region being evaluated.
VLS also provides the following commands for easily setting and inquiring what the symbol current package is.
Command: vls-what-package Keys: C-c C-p Action: Reports
the current Lisp current package in the current Lisp shell buffer.
Command: vls-in-package Keys: C-c p Action: Searches the
current buffer backwards for an in-package expression and sends
to the current Lisp process. A numeric prefix argument N searches for
Nth previous in-package expression. If N is negative it searches
forward for the -Nth. A C-u prefix argument pushes the previous
in-package expression on the Emacs kill ring.
Most Lisps have the capability to examine the execution call stack when
a program encounters an error or certain exceptions. There are usually
a whole raft of stack based functions specific to each Lisp that can
usually be printed with the vls-help command. VLS provides some
of the more important ones as vanilla commands. VLS also provides some
of the specific stack functionality that work differently for each
specific Lisp, See section Other Flavored Commands.
The vls-up-stack and vls-down-stack commands move up and
down the run time stack frames. What it means to position to a stack
frame is to be in the same call and variable binding environment
associated with that stack frame. The direction "down" means earlier
stack frames and "up" means later stack frames.
Command: vls-back-trace Keys: C-c C-b Action: Prints out a
backtrace of the run time stack in the current Lisp shell buffer. For
specific Lisp type prefix argument functionality, See section Other Flavored Commands.
Command: vls-current-frame Keys: C-c C-f Action: Prints
out information about the current stack frame in the current Lisp shell
buffer.
Command: vls-down-stack Keys: C-c C-d Action: Move down
the run time stack one stack frame in the current Lisp shell. A numeric
prefix argument N means move down N frames. A C-u prefix
argument means move to bottom of stack.
Command: vls-reset-listener Keys: C-c C-r Action: Reset
the Lisp listeners to the top level listener. So for example no matter
how nested into break listeners this command will unwind all of those to
the top level listener. If given a numeric prefix argument N it will
reset only N listeners. So for example if you are in a break listener
and then create another error, a 1 prefix argument here will return you
to the previous break listener.
Command: vls-return-frame Keys: C-c r Action: Return
nil from the current stack frame and continue execution. With a
C-u prefix argument enter a value to return and continue.
Command: vls-step Keys: C-c C-s Action: For Lisps that
have a code stepper facility and when in a stepping mode this command
steps one expression. A numeric prefix argument N steps over the next N
expressions. A C-u prefix argument evaluates the current
expression in non-stepping mode.
Command: vls-up-stack Keys: C-c C-u Action: Move up the
run time stack one stack frame in the current Lisp shell. A numeric
prefix argument N means move up N frames. A C-u prefix argument
means move to top of stack.
Command: vls-var-value Keys: C-c C-v Action: For Lisps
that have the capability to probe the local value of a variable
symbolically this command will allow examining the variable binding.
Usually this is done in some binding environment. An example would be
when in a break listener examining the value of some variable within the
scope of where the code broke. After executing this command Emacs
prompts for a variable name in the mini-buffer and then value of that
variable is then echoed in the current Lisp shell buffer. In some Lisps
just entering a RET to the variable name prompt will do something
special like print the local lexical environment.
Command: vls-what-error Keys: C-c C-e Action: Prints the
current error in the current Lisp shell buffer. The current error was
due to evaluating the last Lisp expression that was in error.
Go to the first, previous, next, last section, table of contents.