File: //usr/share/doc/jed/html/jed019.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.35">
<link rel="stylesheet" type="text/css" href="jed.css">
<title>Customization</title>
</head>
<body >
<a href="jed018.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="jed020.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h2 id="sec36" class="section">18 Customization</h2>
<p>To extend <span style="font-weight:bold">jed</span>, it is necessary to become familiar with the <span style="font-weight:bold">S-Lang</span>
programming language. <span style="font-weight:bold">S-Lang</span> not a standalone programming language like
C, Pascal, etc. Rather it is meant to be embedded into a C program. The
<span style="font-weight:bold">S-Lang</span> programming language itself provides only arithmetic, looping, and
branching constructs. In addition, it defines a few other primitive
operations on its data structures. It is up to the application to define
other built-in operations tailored to the application. That is what has
been done for the <span style="font-weight:bold">jed</span> editor. See the document <code class="verb">slang.txt</code> for
<span style="font-weight:bold">S-Lang</span> basics as well as the <span style="font-weight:bold">jed</span> Programmer’s Manual for functions <span style="font-weight:bold">jed</span> has
added to the language. In any case, look at the <code class="verb">*.sl</code> files for
explicit examples.</p><p>For the most part, the average user will simply want to rebind some keys
and change some variables (e.g., tab width). Here I discuss setting keys
and the predefined global variables.</p>
<h3 id="sec37" class="subsection">18.1 Setting Keys</h3>
<p>Defining a key to invoke a certain function is accomplished using the
<code class="verb">setkey</code> function. This function takes two arguments: the function to
be executed and the key binding. For example, suppose that you want to
bind the key <span style="font-variant:small-caps">Ctrl-A</span> to cause the cursor to go to the beginning of
the current line. The <span style="font-weight:bold">jed</span> function that causes this is <code class="verb">bol</code> (See
the <span style="font-weight:bold">jed</span> Programmer’s Manual for a complete list of functions). Putting
the line:
</p><pre class="verbatim"> setkey ("bol", "^A");
</pre><p>
in the startup file <code class="verb">jed.rc</code> (<code class="verb">.jedrc</code>) file will perform the
binding. Here <code class="verb">^A</code> consists of the two characters <code class="verb">^</code> and
<span style="font-family:monospace">A</span> which <span style="font-weight:bold">jed</span> will interpret as the single character <code class="verb">Ctrl-A</code>.
For more examples, see either of the <span style="font-weight:bold">S-Lang</span> files <code class="verb">emacs.sl</code> or
<code class="verb">edt.sl</code>.</p><p>The first argument to the <code class="verb">setkey</code> function may be <em>any</em> <span style="font-weight:bold">S-Lang</span>expression. Well, almost any. The only restriction is that the newline
character cannot appear in the expression. For example, the line
</p><pre class="verbatim">
setkey ("bol();skip_white ();", "^A");
</pre><p>
defines the <code class="verb">Ctrl-A</code> key such that when it is pressed, the editing
point will move the beginning of the line and then skip whitespace up to
the first non-whitespace character on the line.</p><p>In addition to being able to define keys to execute functions, it is also
possible to define a key to directly insert a string of characters. For
example, suppose that you want to define a key to insert the string
<span style="font-family:monospace">int main(int argc, char **argv)</span> whenever you press the key
<span style="font-variant:small-caps">Esc m</span>. This may be accomplished as follows:
</p><pre class="verbatim"> setkey (" int main(int argc, char **argv)", "\em");
</pre><p>Notice two things. First of all, the key sequence <span style="font-variant:small-caps">Esc m</span> has
been written as <code class="verb">"\em"</code> where <code class="verb">\e</code> will be interpreted by <span style="font-weight:bold">jed</span> as
<span style="font-variant:small-caps">Esc</span>. The other salient feature is that the first argument to
<code class="verb">setkey</code>, the “function” argument, begins with a space. This tells
<span style="font-weight:bold">jed</span> that it is not be interpreted as the name of a function; rather, the
characters following the space are to be inserted into the buffer.
Omitting the space character would cause <span style="font-weight:bold">jed</span> to execute a function called
<span style="font-family:monospace">int main(int argc, char **argv)</span> which would fail and generate an
error.</p><p>Finally, it is possible to define a key to execute a series of keystrokes
similar to a keyboard macro. This is done by prefixing the “function”
name with the <span style="font-family:monospace">@</span> character. This instructs <span style="font-weight:bold">jed</span> to interpret the
characters following the <span style="font-family:monospace">@</span> character as characters entered from the
keyboard and execute any function that they are bound to. For example,
consider the following key definition which will generate a C language
comment to comment out the current line of text. In C, this may be
achieved by inserting symbol <span style="font-family:monospace">"/*"</span> at the beginning of the line and
inserting <span style="font-family:monospace">"*/"</span> at the end of the line. Hence, the sequence is clear
(Emacs keybindings):</p><ol class="enumerate" type=1><li class="li-enumerate">
Goto the beginning of the line: <span style="font-variant:small-caps">Ctrl-A</span> or decimal <code class="verb">"\001"</code>.</li><li class="li-enumerate">Insert <span style="font-family:monospace">/*</span>.</li><li class="li-enumerate">Goto end of the line: <span style="font-variant:small-caps">Ctrl-E</span> or decimal <code class="verb">\005</code>.</li><li class="li-enumerate">Insert <span style="font-family:monospace">*/</span>
</li></ol><p>To bind this sequence of steps to the key sequence <span style="font-variant:small-caps">Esc ;</span>, simply use
</p><pre class="verbatim"> setkey("@\001/*\005*/", "\e;");
</pre><p>Again, the prefix <span style="font-family:monospace">@</span> lets <span style="font-weight:bold">jed</span> know that the remaining characters will
carry out the functions they are currently bound to. Also pay particular
attention to the way <span style="font-variant:small-caps">Ctrl-A</span> and <span style="font-variant:small-caps">Ctrl-E</span> have been written. Do
not attempt to use the <code class="verb">^</code> to represent “<span style="font-variant:small-caps">Ctrl</span>”. It does not
have the same meaning in the first argument to the <code class="verb">setkey</code> function
as it does in the second argument. To have control characters in the
first argument, you must enter them as <code class="verb">\</code><em>xyz</em> where <em>xyz</em> is
a three digit decimal number coinciding with the ASCII value of the
character. In this notation, the <span style="font-variant:small-caps">Esc</span> character could have been
written as <code class="verb">\027</code>. See the <span style="font-weight:bold">S-Lang</span> Programmer’s Reference Manual for
further discussion of this notation.</p><p>The <code class="verb">setkey</code> function sets a key in the <code class="verb">global</code> keymap from
which all others are derived. It is also possible to use the function
<code class="verb">local_setkey</code> which operates only upon the current keymap which may
or may not be the <code class="verb">global</code> map.</p>
<h3 id="sec38" class="subsection">18.2 Predefined Variables</h3>
<p><span style="font-weight:bold">jed</span> includes some predefined variables which the user may change. By
convention, predefined variables are in uppercase. The variables which
effect all modes include:</p><p><code class="verb">BLINK</code><br>
(1) if non-zero, blink matching parenthesis.</p><p><code class="verb">TAB_DEFAULT</code><br>
(8) sets default tab setting for newly created buffers
to specified number of columns.</p><p><code class="verb">TAB</code><br>
Value of tab setting for current buffer.</p><p><code class="verb">ADD_NEWLINE</code><br>
(1) adds newline to end of file if needed when writing it out to the
disk.</p><p><code class="verb">META_CHAR</code><br>
(-1) prefix for chars with high bit set (see section on eight bit
clean issues for details)</p><p><code class="verb">DISPLAY_EIGHT_BIT</code><br>
see section on eight bit clean issues.</p><p><code class="verb">COLOR</code><br>
(23) IBMPC background color (see <code class="verb">jed.rc</code> for meaning)</p><p><code class="verb">LINENUMBERS</code><br>
(0) if 1, show current line number on status line</p><p><code class="verb">WANT_EOB</code><br>
(0) if 1, [EOB] denotes end of buffer.</p><p><code class="verb">TERM_CANNOT_INSERT</code><br>
(0) if 1, do not put the terminal in insert mode when writing to the
screen.</p><p><code class="verb">IGNORE_BEEP</code><br>
(0) do not beep the terminal when signalling errors</p><p>In addition to the above, there are variables which affect only certain
modes. See the section on modes for details.</p>
<h3 id="sec39" class="subsection">18.3 Hooks</h3>
<p>A hook is a user defined function that <span style="font-weight:bold">jed</span> calls under certain conditions
which allow the user to modify default actions. For example, when <span style="font-weight:bold">jed</span>
starts up it looks for the existence of a user defined function
<code class="verb">command_line_hook</code>. If this function exists, <span style="font-weight:bold">jed</span> calls the
function. What the function does is completely arbitrary and is left to
the discretion of the user. The startup file, <code class="verb">site.sl</code>, defines
such a function which reads in the files listed on the command line. It is
also this function which loads the <code class="verb">jed.rc</code> startup file. Unlike the
other hooks, this one must be present in the file <code class="verb">site.sl</code> since it
is the only file loaded before calling the hook.</p><p>After the startup files are loaded, <span style="font-weight:bold">jed</span> calls the hook
<code class="verb">jed_startup_hook</code> immediately before entering the main editor loop.
This hook is useful to modify certain data structures which may not have
existed when the startup files were loaded.</p><p>In addition to the above hooks, <span style="font-weight:bold">jed</span> currently also looks for:</p><p><code class="verb">suspend_hook</code><br>
function to be executed before suspending</p><p><code class="verb">resume_hook</code><br>
function that gets carried out after suspension</p><p><code class="verb">exit_hook</code><br>
gets executed before exiting <span style="font-weight:bold">jed</span></p><p><code class="verb">mode_hook</code><br>
sets buffer mode based on filename extension</p><p><code class="verb">find_file_hook</code><br>
called before file is read into a buffer. It currently
checks for presence of autosave file and warns user if
it is more recent than file.</p><p>See <code class="verb">site.sl</code> for explicit examples of the above hooks.</p><p>Another useful hook is <code class="verb">is_paragraph_separator</code>. This hook is called
when <span style="font-weight:bold">jed</span> searches for the beginning or end of a paragraph. This search
is performed by all paragraph formatting functions as well as the forward
and backward paragraph movement commands. As <span style="font-weight:bold">jed</span> performs the search,
it moves from one line to another testing the line to see if it separates
a paragraph. The function of the hook is to make this decision and return
zero if the line does not separate paragraphs or return one if it does.
The default value of this hook may be written in <span style="font-weight:bold">S-Lang</span> as</p><pre class="verbatim"> define is_paragraph_separator ()
{
bol ();
if (looking_at ("\\")) return 1;
if (looking_at ("%")) return 1;
skip_white(); eolp ();
}
</pre><p>A related hook called after a paragraph is formatted is
<code class="verb">format_paragraph_hook</code>. This hook is only called if either
<code class="verb">format_paragraph</code> or <code class="verb">narrow_paragraph</code> is called with a prefix
digit argument. For example, <code class="verb">format_paragraph</code> is bound to
<span style="font-variant:small-caps">Esc q</span>. Simply pressing this key sequence will call
<code class="verb">format_paragraph</code> but <code class="verb">format_paragraph_hook</code> will not be called.
However, pressing <span style="font-variant:small-caps">Esc 1</span> followed by <span style="font-variant:small-caps">Esc q</span> will
result in a call to <code class="verb">format_paragraph_hook</code>. Currently, this hook
simply justifies the paragraph. That is, it fills each line in the
paragraph such that the line ends at the right margin, which is defined by
the <code class="verb">WRAP</code> variable.</p>
<h3 id="sec40" class="subsection">18.4 S-Lang Programming Hints (Debugging)</h3>
<p>This section assumes some knowledge about <span style="font-weight:bold">S-Lang</span> and is designed to
explain how to debug <span style="font-weight:bold">S-Lang</span> routines quickly. For information about
<span style="font-weight:bold">S-Lang</span>, read <code class="verb">slang.txt</code>.</p><p>There are two ways of loading a file of <span style="font-weight:bold">S-Lang</span> code into <span style="font-weight:bold">jed</span>. The
most common way is through the function <code class="verb">evalfile</code>. If an error
occurs while loading a file, <span style="font-weight:bold">jed</span> will give some indication of where the
problem lies by displaying the line number and the offending bit of
<span style="font-weight:bold">S-Lang</span> code in the minibuffer. In practice though, this can be quite
inefficient. The <code class="verb">evalfile</code> function is primarily designed to load
debugged and tested <span style="font-weight:bold">S-Lang</span> code.</p><p>The best way to develop and test <span style="font-weight:bold">S-Lang</span> code with <span style="font-weight:bold">jed</span> is to use the
function <code class="verb">evalbuffer</code>. Simply load the piece of code into <span style="font-weight:bold">jed</span> as an
ordinary file, press <span style="font-variant:small-caps">Esc X</span> and enter the function
<code class="verb">evalbuffer</code> If the piece of code in the buffer has any syntax
errors, <span style="font-weight:bold">jed</span> will put the cursor on the error. This is the best way to
spot compile time errors such as syntax errors. However, this will not
catch runtime errors.</p><p>When a runtime error occurs, <span style="font-weight:bold">jed</span> will put the cursor on the top level
function where the original call was made and NOT the actual location of
the function. To aid in determining where an error occurs, <span style="font-weight:bold">jed</span> can be
made to give a symbolic traceback. As the <span style="font-weight:bold">S-Lang</span> runtime stack unwinds,
<span style="font-weight:bold">S-Lang</span> will simply print the name of function at that particular level.
If the function includes local variables, their values will be dumped as
well. Hence, it is easy to quickly narrow the location of an error down
to function where the error occurs. By default, the traceback is
disabled. The traceback is enabled by setting the <span style="font-weight:bold">S-Lang</span> variable
<code class="verb">_traceback</code> to a non-zero value. It is simpliest to just press
<span style="font-variant:small-caps">Ctrl-X Esc</span> and enter <code class="verb">_traceback = 1</code> at the <span style="font-family:monospace">S-Lang</span>
prompt. This is one of those times where one needs access to the
<span style="font-family:monospace">S-Lang></span> prompt and not the <span style="font-family:monospace">M-x</span> prompt. For example, consider
the following piece of code:
</p><pre class="verbatim"> define fun_two () {forever {}} % loops forever
define fun_one () {fun_two ()} % calls fun_two-- never returns
</pre><p>
Simply enter the above into an empty <span style="font-weight:bold">jed</span> <code class="verb">*scratch*</code> buffer, then
press <span style="font-variant:small-caps">Ctrl-X Esc</span> and enter:
</p><pre class="verbatim">
_traceback = 1; () = evalbuffer (); fun_one ();
</pre><p>
This will turn on tracebacks, evaluate the buffer and call the
function <code class="verb">fun_one</code>. <span style="font-weight:bold">jed</span> will then be put into an infinite loop which
can only be stopped by pressing the abort character which by default is
<span style="font-variant:small-caps">Ctrl-G</span>. Doing so, will produce the traceback messages
</p><pre class="verbatim"> S-Lang Traceback: fun_two
S-Lang Traceback: fun_one
</pre><p>
in addition to the error message <span style="font-family:monospace">User Break!</span>. Of course, this
technique only narrows down the source of an error to a particular
function. To proceed further, it may necessary to put “print” statements
at suitable places in the function. There are several ways to do this:
</p><ol class="enumerate" type=1><li class="li-enumerate">
Use the <code class="verb">insert</code> function to insert the contents of a variable
into the current buffer.</li><li class="li-enumerate">Use the <code class="verb">error</code> function to abort the function and display the
value of a variable in the minibuffer.</li><li class="li-enumerate">Use the <code class="verb">message</code> function to display the value of a variable in
the minibuffer. Unlike <code class="verb">error</code>, the <code class="verb">message</code> function does
not abort the execution of the function.
</li></ol><p>Since each of these functions require a string argument, it is usually
best to call the <code class="verb">string</code> function first for the conversion followed
by the output function. This has to be done anyway if it is desired to
get the contents of an integer variable. Although the second approach is
prehaps the most useful in practice, it is somtimes appropriate to use a
combination of these techniques.</p><p>Finally, to print the entire stack, one can use the <code class="verb">print_stack</code>
function. This function dumps the <span style="font-weight:bold">S-Lang</span> runtime stack into the
<span style="font-family:monospace">*traceback*</span> buffer.</p><p>Since <span style="font-weight:bold">S-Lang</span> is an interpreted language, judicious application of the
above techniques should lead very quickly to the source of any errors.</p>
<hr>
<a href="jed018.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="jed020.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>