calc: Customizing Embedded Mode
17.5 Customizing Embedded Mode
==============================
You can modify Embedded mode’s behavior by setting various Lisp
variables described here. These variables are customizable (
Customizing Calc), or you can use ‘M-x set-variable’ or ‘M-x
edit-options’ to adjust a variable on the fly. (Another possibility
would be to use a file-local variable annotation at the end of the file;
Local Variables in Files (emacs)File Variables.) Many of the
variables given mentioned here can be set to depend on the major mode of
the editing buffer (Customizing Calc).
The ‘calc-embedded-open-formula’ variable holds a regular expression
for the opening delimiter of a formula. Regular Expression
Search (emacs)Regexp Search, to see how regular expressions work.
Basically, a regular expression is a pattern that Calc can search for.
A regular expression that considers blank lines, ‘$’, and ‘$$’ to be
opening delimiters is ‘"\\`\\|^\n\\|\\$\\$?"’. Just in case the meaning
of this regular expression is not completely plain, let’s go through it
in detail.
The surrounding ‘" "’ marks quote the text between them as a Lisp
string. If you left them off, ‘set-variable’ or ‘edit-options’ would
try to read the regular expression as a Lisp program.
The most obvious property of this regular expression is that it
contains indecently many backslashes. There are actually two levels of
backslash usage going on here. First, when Lisp reads a quoted string,
all pairs of characters beginning with a backslash are interpreted as
special characters. Here, ‘\n’ changes to a new-line character, and
‘\\’ changes to a single backslash. So the actual regular expression
seen by Calc is ‘\`\|^ (newline) \|\$\$?’.
Regular expressions also consider pairs beginning with backslash to
have special meanings. Sometimes the backslash is used to quote a
character that otherwise would have a special meaning in a regular
expression, like ‘$’, which normally means “end-of-line,” or ‘?’, which
means that the preceding item is optional. So ‘\$\$?’ matches either
one or two dollar signs.
The other codes in this regular expression are ‘^’, which matches
“beginning-of-line,” ‘\|’, which means “or,” and ‘\`’, which matches
“beginning-of-buffer.” So the whole pattern means that a formula begins
at the beginning of the buffer, or on a newline that occurs at the
beginning of a line (i.e., a blank line), or at one or two dollar signs.
The default value of ‘calc-embedded-open-formula’ looks just like
this example, with several more alternatives added on to recognize
various other common kinds of delimiters.
By the way, the reason to use ‘^\n’ rather than ‘^$’ or ‘\n\n’, which
also would appear to match blank lines, is that the former expression
actually “consumes” only one newline character as _part of_ the
delimiter, whereas the latter expressions consume zero or two newlines,
respectively. The former choice gives the most natural behavior when
Calc must operate on a whole formula including its delimiters.
See the Emacs manual for complete details on regular expressions.
But just for your convenience, here is a list of all characters which
must be quoted with backslash (like ‘\$’) to avoid some special
interpretation: ‘. * + ? [ ] ^ $ \’. (Note the backslash in this list;
for example, to match ‘\[’ you must use ‘"\\\\\\["’. An exercise for
the reader is to account for each of these six backslashes!)
The ‘calc-embedded-close-formula’ variable holds a regular expression
for the closing delimiter of a formula. A closing regular expression to
match the above example would be ‘"\\'\\|\n$\\|\\$\\$?"’. This is
almost the same as the other one, except it now uses ‘\'’
(“end-of-buffer”) and ‘\n$’ (newline occurring at end of line, yet
another way of describing a blank line that is more appropriate for this
case).
The ‘calc-embedded-word-regexp’ variable holds a regular expression
used to define an expression to look for (a “word”) when you type ‘C-x *
w’ to enable Embedded mode.
The ‘calc-embedded-open-plain’ variable is a string which begins a
“plain” formula written in front of the formatted formula when ‘d p’
mode is turned on. Note that this is an actual string, not a regular
expression, because Calc must be able to write this string into a buffer
as well as to recognize it. The default string is ‘"%%% "’ (note the
trailing space), but may be different for certain major modes.
The ‘calc-embedded-close-plain’ variable is a string which ends a
“plain” formula. The default is ‘" %%%\n"’, but may be different for
different major modes. Without the trailing newline here, the first
line of a Big mode formula that followed might be shifted over with
respect to the other lines.
The ‘calc-embedded-open-new-formula’ variable is a string which is
inserted at the front of a new formula when you type ‘C-x * f’. Its
default value is ‘"\n\n"’. If this string begins with a newline
character and the ‘C-x * f’ is typed at the beginning of a line, ‘C-x *
f’ will skip this first newline to avoid introducing unnecessary blank
lines in the file.
The ‘calc-embedded-close-new-formula’ variable is the corresponding
string which is inserted at the end of a new formula. Its default value
is also ‘"\n\n"’. The final newline is omitted by ‘C-x * f’ if typed at
the end of a line. (It follows that if ‘C-x * f’ is typed on a blank
line, both a leading opening newline and a trailing closing newline are
omitted.)
The ‘calc-embedded-announce-formula’ variable is a regular expression
which is sure to be followed by an embedded formula. The ‘C-x * a’
command searches for this pattern as well as for ‘=>’ and ‘:=’
operators. Note that ‘C-x * a’ will not activate just anything
surrounded by formula delimiters; after all, blank lines are considered
formula delimiters by default! But if your language includes a
delimiter which can only occur actually in front of a formula, you can
take advantage of it here. The default pattern is ‘"%Embed\n\\(%
.*\n\\)*"’, but may be different for different major modes. This
pattern will check for ‘%Embed’ followed by any number of lines
beginning with ‘%’ and a space. This last is important to make Calc
consider mode annotations part of the pattern, so that the formula’s
opening delimiter really is sure to follow the pattern.
The ‘calc-embedded-open-mode’ variable is a string (not a regular
expression) which should precede a mode annotation. Calc never scans
for this string; Calc always looks for the annotation itself. But this
is the string that is inserted before the opening bracket when Calc adds
an annotation on its own. The default is ‘"% "’, but may be different
for different major modes.
The ‘calc-embedded-close-mode’ variable is a string which follows a
mode annotation written by Calc. Its default value is simply a newline,
‘"\n"’, but may be different for different major modes. If you change
this, it is a good idea still to end with a newline so that mode
annotations will appear on lines by themselves.
Info Catalog
calc: Mode Settings in Embedded Mode
calc: Embedded Mode