Go to the first, previous, next, last section, table of contents.


Vanilla Commands

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.

Eval Commands

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.

Shell Buffer Commands

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.

Lisp File Commands

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.

Information Commands

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.

Package Commands

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.

Debugging Commands

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.