The variables in this chapter concern the proof shell mode, and are the largest group. They are split into several subgroups. The first subgroup are commands invoked at various points. The second subgroup of variables are concerned with matching the output from the proof assistant. The final subgroup contains various hooks which you can set to add lisp customization to Proof General in various points (some of them are also used internally for behaviour you may wish to adjust).
Variables for configuring the proof shell are put into the customize
group proof-shell
.
These should be set in the shell mode configuration, before
proof-shell-config-done
is called.
To understand the way the proof assistant runs inside Emacs, you may
want to refer to the comint.el
(Command interpreter) package
distributed with Emacs. This package controls several shell-like modes
available in Emacs, including the proof-shell-mode
and
all specific shell modes derived from it.
Settings in this section configure Proof General with commands to send to the prover to activate certain actions.
proof-pre-shell-start-hook
from
a variable which is in the proof assistant's customization
group. This allows different proof assistants to coexist
(albeit in separate Emacs sessions).
proof-shell-invisible-command
', Proof General will check to see if it
ends with proof-terminal-char
, and add it if not.
If proof-terminal-char
is nil, this has no effect.
It is better to configure the proof assistant for this purpose via command line options if possible, in which case this variable does not need to be set.
See also `proof-shell-init-cmd
'.
See also `proof-shell-pre-sync-init-cmd
'.
proof-shell-quit-cmd
.
proof-shell-filename-escapes
' are
applied to the filename.
This setting is used to define the function proof-cd
which
changes to the value of (default-directory
) for script buffers.
For files, the value of (default-directory
) is simply the
directory the file resides in.
NB: By default, proof-cd
is called from proof-activate-scripting-hook
,
so that the prover switches to the directory of a proof
script every time scripting begins.
proof-shell-stop-silent-cmd
.
NB: terminator not added to command.
proof-shell-start-silent-cmd
.
NB: Terminator not added to command.
proof-format-filename
' for other possibilities
to process the filename.
This setting used to interface with the proof assistant's internal management of multiple files, so the proof assistant is kept aware of which files have been processed. Specifically, when scripting is deactivated in a completed buffer, it is added to Proof General's list of processed files, and the prover is told about it by issuing this command.
If this is set to nil, no command is issued.
See also: proof-shell-inform-file-retracted-cmd
,
proof-shell-process-file
, proof-shell-compute-new-files-list
.
proof-format-filename
' for other
possibilities to process the filename.
This is used to interface with the proof assistant's internal management of multiple files, so the proof assistant is kept aware of which files have been processed. Specifically, when scripting is activated, the file is removed from Proof General's list of processed files, and the prover is told about it by issuing this command. The action may cause the prover in turn to suggest to Proof General that files depending on this one are also unlocked.
If this is set to nil, no command is issued.
See also: proof-shell-inform-file-processed-cmd
,
proof-shell-process-file
, proof-shell-compute-new-files-list
.
Generally, commands from the proof script are sent verbatim to the proof
process running in the proof shell. For historical reasons, carriage
returns are stripped by default. You can set
proof-shell-strip-crs-from-input
to adjust that. For more
sophisticated pre-processing of the sent string, you may like to set
proof-shell-insert-hook
.
proof-shell-insert
before inserting a command.
This hook is called inside a save-excursion
with the proof-shell-buffer
current, just before inserting and sending the text in the
variable `string'. The hook can massage `string' or insert additional
text directly into the proof-shell-buffer
.
Before sending `string', it will be stripped of carriage returns.
Additionally, the hook can examine the variable `action'. It will be a symbol, set to the callback command which is executed in the proof shell filter once `string' has been processed. The `action' variable suggests what class of command is about to be inserted:
'proof-done-invisible
A non-scripting command'proof-done-advancing
A "forward" scripting command'proof-done-retracting
A "backward" scripting command
Caveats: You should be very careful about setting this hook. Proof General relies on a careful synchronization with the process between inputs and outputs. It expects to see a prompt for each input it sends from the queue. If you add extra input here and it causes more prompts than expected, things will break! Extending the variable `string' may be safer than inserting text directly, since it is stripped of carriage returns before being sent.
Example uses: lego uses this hook for setting the pretty printer width if the window width has changed; Plastic uses it to remove literate-style markup from `string'. The x-symbol support uses this hook to convert special characters into tokens for the proof assistant.
These settings control the way Proof General reacts to process output.
The single most important setting is
proof-shell-annotated-prompt-regexp
, which must be set as
part of the prover configuraton. This is used to configure the
communication with the prover process.
this IS THE most important setting TO configure!!
Output is grabbed between pairs of lines matching this regexp, and the appearance of this regexp is used by Proof General to recognize when the prover has finished processing a command.
To help speed up matching you may be able to annotate the
proof assistant prompt with a special character not appearing
in ordinary output. The special character should appear in
this regexp, and should be the value of proof-shell-wakeup-char
.
We assume that an error message corresponds to a failure in the last
proof command executed. So don't match mere warning messages with
this regexp. Moreover, an error message should not be matched as an
eager annotation (see proof-shell-eager-annotation-start
) otherwise it
will be lost.
Error messages are considered to begin from proof-shell-error-regexp
and continue until the next prompt. The variable
`proof-shell-truncate-before-error
' controls whether text before the
error message is displayed.
The engine matches interrupts before errors, see proof-shell-interrupt-regexp
.
It is safe to leave this variable unset (as nil).
proof-shell-eager-annotation-start
) otherwise it
will be lost.
The engine matches interrupts before errors, see proof-shell-error-regexp
.
It is safe to leave this variable unset (as nil).
NB: the default setting for this is `t' to be compatible with behaviour in Proof General before version 3.4. The more obvious setting for new instances is probably `nil'.
Interrupt messages are treated in the same way.
See `proof-shell-error-regexp
' and `proof-shell-interrupt-regexp
'.
When output which matches this regexp is seen, we clear the goals buffer in case this is not also marked up as a `goals' type of message.
We also enable the QED function (save a proof) and we may automatically close off the proof region if another goal appears before a save command, depending on whether the prover supports nested proofs or not.
proof-shell-start-goals-regexp
'
and `proof-shell-end-goals-regexp
' will be pasted into the goals buffer
and possibly analysed further for proof-by-pointing markup.
proof-shell-start-goals-regexp
.
At the moment, this setting is not used in the generic Proof General.
In the future it will be used for a generic implementation for `pg-topterm-goalhyp-fn
',
used to help parse the goals buffer to annotate it for proof by pointing.
Among the various dialogue messages that the proof assistant outputs during proof, Proof General can consider certain messages to be "urgent". When processing many lines of a proof, Proof General will normally supress the output, waiting until the final message appears before displaying anything to the user. Urgent messages escape this: typically they include messages that the prover wants the user to notice, for example, perhaps, file loading messages, or timing statistics.
So that Proof General notices, these urgent messages should be marked-up with "eager" annotations.
It is nice to recognize (starts of) warnings or file-reading messages
with this regexp. You must also recognize any special messages
from the prover to PG with this regexp (e.g. `proof-shell-clear-goals-regexp
',
`proof-shell-retract-files-regexp
', etc.)
See also `proof-shell-eager-annotation-start-length
',
`proof-shell-eager-annotation-end
'.
Set to nil to disable this feature.
proof-shell-eager-annotation-start
' (at least 1).
If this value is too low, eager annotations may be lost!
This value is used internally by Proof General to optimize the process filter to avoid unnecessary searching.
See also `proof-shell-eager-annotation-start
'.
It is nice to recognize (ends of) warnings or file-reading messages
with this regexp. You must also recognize (ends of) any special messages
from the prover to PG with this regexp (e.g. `proof-shell-clear-goals-regexp
',
`proof-shell-retract-files-regexp
', etc.)
The default value is "\n" to match up to the end of the line.
The default action for urgent messages is to display them in the response buffer, highlighted. But we also allow for some control messages, issued from the proof assistant to Proof General and not intended for the user to see. These are recognized in the same way as urgent messages (marked with eager annotations), so they will be acted on as soon as they are issued by the prover.
If the regexp matches output from the proof assistant, there should be
two match strings: (match-string
1) should be the name of the elisp
variable to be set, and (match-string
2) should be the value of the
variable (which will be evaluated as a lisp expression).
A good markup for the second string is to delimit with #'s, since these are not valid syntax for elisp evaluation.
Elisp errors will be trapped when evaluating; set
proof-show-debug-messages
to be informed when this happens.
Example uses are to adjust PG's internal copies of proof assistant's settings, or to make automatic dynamic syntax adjustments in Emacs to match changes in theory, etc.
If you pick a dummy variable name (e.g. `proof-dummy-setting') you can just evaluation arbitrary elisp expressions for their side effects, to adjust menu entries, or even launch auxiliary programs. But use with care -- there is no protection against catastrophic elisp!
This setting could also be used to move some configuration settings from PG to the prover, but this is not really supported (most settings must be made before this mechanism will work). In future, the PG standard protocol, pgip, will use this mechanism for making all settings.
dependencies OF X Y Z ARE A B C
with X Y Z, A B C separated by whitespace or somehow else (see
`proof-shell-theorem-dependency-list-split
'. This variable should
be set to a regexp to match the overall message (which should
be an urgent message), with two sub-matches for X Y Z and A B C.
This is an experimental feature, currently work-in-progress.
Two important control messages are recognized by
proof-shell-process-file
and
proof-shell-retract-files-regexp
, used for synchronizing Proof
General with a file loading mechanism built into the proof assistant.
See section 8. Handling multiple files, for more details about how to use the
final three settings described here.
If regexp matches output, then the function function is invoked on the output string chunk. It must return the name of a script file (with complete path) that the system has successfully processed. In practice, function is likely to inspect the match data. If it returns the empty string, the file name of the scripting buffer is used instead. If it returns nil, no action is taken.
Care has to be taken in case the prover only reports on compiled
versions of files it is processing. In this case, function needs to
reconstruct the corresponding script file name. The new (true) file
name is added to the front of `proof-included-files-list
'.
At this stage, Proof General's view of the processed files is out of
date and needs to be updated with the help of the function
`proof-shell-compute-new-files-list
'.
It needs to return an up to date list of all processed files. Its
output is stored in `proof-included-files-list
'. Its input is the
string of which `proof-shell-retract-files-regexp
' matched a
substring. In practice, this function is likely to inspect the
previous (global) variable `proof-included-files-list
' and the match
data triggered by `proof-shell-retract-files-regexp
'.
'(("\\\\" . "\\\\") ("\"" . "\\\""))
achieves this. This does not apply to lego, which does not need backslash escapes and does not allow filenames with quote characters.
This setting is used inside the function `proof-format-filename
'.
process-connection-type
for the proof shell.
proof-prog-name
proof-mode-for-shell
proof-mode-for-response
proof-mode-for-goals
proof-shell-trace-output-regexp
This is the bare minimum needed to get a shell buffer and
its friends configured in the function proof-shell-start
.
proof-shell-error-or-interrupt-seen
' to
determine whether the cause was an error or interrupt.
comint-interrupt-subjob
' is called.
proof-shell-process-output
'.
All other output from the proof engine is simply reported to the
user in the response buffer.
To catch further special cases, set this variable to a pair of
functions '(condf . actf). Both are given (cmd string) as arguments.
`cmd' is a string containing the currently processed command.
`string' is the response from the proof system. To change the
behaviour of `proof-shell-process-output
', (condf cmd string) must
return a non-nil value. Then (actf cmd string) is invoked.
See the documentation of `proof-shell-process-output
' for the required
output format.
Go to the first, previous, next, last section, table of contents.