File: macros.html

package info (click to toggle)
vile 9.7ze-1
links: PTS, VCS
area: main
in suites: squeeze
size: 8,372 kB
ctags: 9,314
sloc: ansic: 95,840; lex: 11,395; sh: 3,416; perl: 3,200; cpp: 3,180; makefile: 982; awk: 271; sed: 14
file content (1722 lines) | stat: -rw-r--r-- 96,915 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!--
  $Id: macros.html,v 1.12 2010/04/11 21:56:52 tom Exp $
-->
<HTML>
<HEAD>
<TITLE>
Programmed Macros in vile
</TITLE>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rev="made" href="mailto:dickey@invisible-island.net">
<link rel="SHORTCUT ICON" href="/img/icons/vile.ico" type="image/x-icon">
</HEAD>
<BODY>

<h1 id="toplevel-id"><a name="toplevel">Programmed Macros in vile</a></h1>
<p>
	vile presents a couple of forms of what are commonly called
	"macros".  This document presents information on those
	written in the builtin "macro language".  (The other form of
	macro is a "keyboard macro", a simple stored sequence of vile
	keystrokes, which can be replayed on command.) Macros written
	in the macro language can be bound to keys, run from files or
	buffers, given names (in which case they're known as
	"procedures"), and in the last case, those names may be
	directly introduced into vile's command set.
<p>
	The language can execute any valid vile command, using one of it's
	"named" forms.  I.e. the command that would be executed would
	be "down-line", "forward-line", or "next-line", but it would
	not work to write the macro to use 'j'.
<p>
	vile commands can be linked together in repetitive or
	conditional ways using various builtin directives (e.g.
	"if", "else", "while", "break", etc), and intermediate
	results can be stored in string-valued temporary variables.
	Other forms of variable can be used to reference parts of
	vile's current state, e.g. the current line number.
	Finally, there is a set of functions that can act on
	variables, to concatenate them, compare them, increment them,
	change their representation, etc.
<p>
	Each of these language aspects will be described in turn, but first
	the execution framework must be explained.

<h2 id="creating-id"><a name="creating">Creating, executing, storing macros</a></h2>
<p>
	In the simplest case, valid macro language constructs are placed in
	a file or buffer and subsequently executed with one of these editor
	commands:
<table border="1" summary="Selection Techniques">
<colgroup></colgroup>
<tr>
<th>command</th>
<th>applies to</th>
<th>example</th>
</tr>
<tr>
	       <td>execute-buffer</td><td>buffer</td><td>execute-buffer cfgcmds</td>
</tr>
<tr>
	       <td>execute-file</td><td>disk file</td><td>execute-file ~/.projcfg</td>
</tr>
<tr>
	       <td>source</td><td>disk file</td><td>source c:/utils/proj.cfg</td>
</tr>
</table>
<p>
	The most common example of this usage is vile's startup file,
	which is "sourced" during the editor's invocation.  Typically, the
	startup file configures the user's preferences and looks something
	like this:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;<strong><font color="#000080">ai</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;<strong><font color="#000080">ts</font></strong><strong><font color="#800000">=</font></strong><strong><font color="#008080">4</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;<strong><font color="#000080">flash</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;etc.&gt;<br>
<!--atr2html}}--></p>
	A startup/configuration file might also use macro language
	directives to conditionally configure the editor.  For example, if
	xvile executes this startup file fragment:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;sequal</font>&nbsp;<font color="#008080">$progname</font>&nbsp;<font color="#800080">"xvile"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">$title</font>&nbsp;<font color="#008080">$cbufname</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
<!--atr2html}}--></p>
	then the editor's X window titlebar changes.  However, "standard"
	vile (i.e., non-gui vile) ignores this fragment and thus, a single
	startup file can be used to configure both the gui and non-gui
	versions of the editor.
<p>
	vile also provides constructs that encapsulate macro language
	elements as numbered and named programs.  These programs represent
	the entity that most programmers identify as a "true" macro.
	And in fact, the remainder of this document will simply assume that
	the word "macro" refers to one of aforementioned program types.

    <h3 id="numbered-id"><a name="numbered">Numbered macros (anachronism</a>)</h3>
	The numbered macro syntax looks like so:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;<strong><font color="#000080">number</font></strong>&gt;&nbsp;<strong><font color="#000080">store-macro</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;language&nbsp;element&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;language&nbsp;element&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
	A numbered macro is executed using this command:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">execute-macro</font></strong>-&lt;<strong><font color="#000080">number</font></strong>&gt;<br>
<!--atr2html}}--></p>
	To bind a keystroke to this macro, use this command:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;<strong><font color="#000080">execute-macro</font></strong>-&lt;<strong><font color="#000080">number</font></strong>&gt;&nbsp;&lt;keystroke&gt;<br>
<!--atr2html}}--></p>
	Here's an actual example:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#008080">30</font></strong>&nbsp;<strong><font color="#000080">store-macro</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#800080">"this&nbsp;is&nbsp;a&nbsp;test&nbsp;macro"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;<strong><font color="#000080">execute-macro-30</font></strong>&nbsp;<font color="#800080">#h</font><br>
<!--atr2html}}--></p>
	Now, whenever "#h" is pressed, a message is written on the editor's
	message line.
<p>
	Although this syntax serves a purpose, it's obvious that numbered
	programs don't lend themselves to easy recall (quick, what does
	macro 22 do?).  But this format was an integral part of vile for
	many years, simply because named macros could not be bound to
	keystrokes.  This restriction has been removed, rendering this
	feature essentially obsolete.  The only advantage of numbered
	macros over named macros is that the former do not share the same
	namespace as vile's commands.  This attribute can be advantageous
	when creating macros recalled solely via key bindings.
<p>
	For completeness sake, it should be mentioned that numbered macros
	are allocated from a fixed pool (default is 40 macros).  This fixed
	pool can be increased via the following configuration option:
<pre>
	--with-exec-macros=N    specify count of numbered macros
</pre>
    <h3 id="named-id"><a name="named">Named macros</a></h3>
	A named macro, aka "stored procedure", uses this syntax:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;&lt;unique-name&gt;&nbsp;["help-string"]</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;language&nbsp;element&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;language&nbsp;element&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
	where:
<dl>
<dt>unique-name
	<dd>is an alpha-numeric identifier that does not conflict with the name
	of any existing editor command (the show-commands command generates a
	list of all existing commands).
<dt>help-string
	<dd>is an optional description of the macro.  This string is displayed
	in the listing created by show-commands.
</dl>
<p>
	A stored procedure is executed by simply referencing its name.  To
	bind a keystroke to this macro, use this command:
<pre>
	bind-key &lt;unique-name&gt; &lt;keystroke&gt;
</pre><p>
	Here's the stored procedure equivalent of macro number 30 above:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;write-msg-tst&nbsp;"displays&nbsp;test&nbsp;message"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#800080">"this&nbsp;is&nbsp;a&nbsp;test&nbsp;macro"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;write-msg-tst&nbsp;<font color="#800080">#h</font><br>
<!--atr2html}}--></p>
	Two mechanisms now exist for executing this macro:
<ul>
	<li>press "#h" within the editor, or

	<li>simply use the name "write-msg-tst" as if it were any other
	  built-in editor command.  This means that "write-msg-tst" can be
	  invoked from another macro, from a startup/configuration file, or
	  from vile's command line, like so:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;:write-msg-tst<br>
<!--atr2html}}--></p>
</ul>
<p>
	Named macros may have parameters.  Like Bourne shell, the parameters
	are denoted '$' followed by a number, e.g., $1 for the first parameter.
<ul>
	<li>$# gives the number of parameters.

	<li>$* gives a blank-separated list of all parameters.

	<li>$@ gives a blank-separated list of all parameters, quoted.

	<li>$0 is the name of the current procedure, not expanded in the lists.
</ul>
<p>
	The individual parameters are evaluated when the macro is invoked, and
	may consist of expressions.  They are stored as strings.
<p>
	The macro interpreter uses a template in the definition to define the
	types of parameters which are accepted.  For each parameter, a keyword,
	optionally followed by the prompt string is required.  Keywords (which
	may be abbreviated) include
<pre>
	bool
	buffer
	directory
	enum		(see below)
	file
	integer
	majormode
	mode
	string
	variable
</pre><p>
	Unless overridden, the prompt for each parameter is named after the
	keyword.  Override the prompt by an assignment, e.g.,
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;Filter&nbsp;f="Input"&nbsp;f="Output"</font><br>
<!--atr2html}}--></p>
	to begin a macro 'Filter' with two parameters, Input and Output,
	internally referenced by $1 and $2.
<p>
	Here is a simple macro which accepts two parameters and uses them to
	position the cursor on a given line and zero-based character offset.
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;macro&nbsp;for&nbsp;wingrep&nbsp;and&nbsp;similar&nbsp;applications&nbsp;that&nbsp;can&nbsp;pass</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;both&nbsp;line-&nbsp;and&nbsp;column-number&nbsp;to&nbsp;external&nbsp;tools.</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;usage:&nbsp;"winvile&nbsp;+WinGrep&nbsp;$L&nbsp;$C&nbsp;$F"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;WinGrep&nbsp;i="Line"&nbsp;i="Offset"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~local</font>&nbsp;<font color="#008080">%col</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%col</font>&nbsp;<font color="#008080">&amp;sub</font>&nbsp;<font color="#008080">$2</font>&nbsp;<strong><font color="#008080">1</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008080">$1</font>&nbsp;<strong><font color="#000080">goto-line</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">beginning-of-line</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;ge</font>&nbsp;<font color="#008080">%col</font>&nbsp;<strong><font color="#008080">1</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008080">%col</font>&nbsp;<strong><font color="#000080">forward-character-to-eol</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
	The 'enum' parameter type is special; it requires a second keyword
	which denotes the symbol table which is used for name-completion.
	The table name (which cannot be abbreviated) follows the 'enum'
	after a colon (:), e.g.,
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;Scheme&nbsp;e:fcolor="Foreground"</font><br>
<!--atr2html}}--></p>
	The 'enum' tables correspond to the enumerated modes:
<pre>
	*bool
	backup-style
	bcolor
	byteorder-mark
	ccolor
	color-scheme
	cursor-tokens
	fcolor
	file-encoding
	for-buffers
	mcolor
	mini-hilite
	popup-choices
	qualifiers
	reader-policy
	record-attrs (VMS only)
	record-format (VMS only)
	recordseparator
	showformat
	video-attrs
	visual-matches
	vtflash
</pre>
    <h3 id="returning-id"><a name="returning">Returning values</a></h3>
	Any macro can return a value to a calling script.  This is done
	using special variables:
<dl>
<dt>
$return
<dd>
			is a symbol that a macro can set to any string.

<dt>
$_
<dd>
			is copied from $return when completing a macro.
			If no string was assigned to $return within the
			macro, $_ will contain a readable form of the
			exit status.  These are the standard values used
			within vile:
<pre>
TRUE
	FALSE
	ABORT
	SORTOFTRUE
</pre><p>
			$_ may also contain the special symbol ERROR if
			the macro could not run, e.g., due to too much
			recursion, or if the exit status was none of the
			standard values.
</dl>

    <h3 id="storing-id"><a name="storing">Storing macros</a></h3>
	In general, macros are stored in the editor's startup file.
	Prolific macro authors may instead opt to sprinkle their macros
	across one or more external text files and source those file(s)
	from the startup file.


<hr>
This concludes the discussion of the macro language execution framework.
<p>
The remainder of this document describes individual language constructs.
The presentation is bottom-up (i.e., reference format), so individual
sections may be read in any order.
<hr>


<h2 id="comments-id"><a name="comments">Comments</a></h2>
<p>
	A semi-colon (;) or double-quote (") denotes a comment that extends
	from the delimiter to end of line.  The semi-colon is inherited
	from MicroEMACS, the double-quote is for vi compatibility.
<p>
	Note 1:  The double-quote also delimits string arguments, but the
	command parser correctly distinguishes the various use cases.
<p>
	Note 2:  Inline comments (comment text that follows a command)
	are permitted except when used in conjunction with commands that take
	optional arguments.  Here follow two examples of unacceptable usage:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;winopen&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;invoke&nbsp;win32&nbsp;common&nbsp;open&nbsp;dialog</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-file</font></strong>&nbsp;<font color="#800000">;&nbsp;flush&nbsp;curr&nbsp;buffer&nbsp;to&nbsp;disk</font><br>
<!--atr2html}}--></p>
<p>
	In the first case, the winopen command attempts to browse ';'
	as a directory.  In the second case, write-file flushes the
	current buffer to disk using ';' as the filename.

<h2 id="joining-id"><a name="joining">Misc macro syntax features</a></h2>
<p>
	Lines ending with '\' are joined before interpretation.


<h3 id="limits-id"><a name="limits">Limits</a></h3>
<p>
	The length of a variable name may not exceed 255 (NLINE-1) bytes of
	storage.  Most other strings are allocated dynamically.


<h3 id="strings-id"><a name="strings">Strings</a></h3>
<p>
	Like many simple language, the macro language operates exclusively on
	strings.  That is to say, variables are always of type "string", and
	need not be declared in advance.
<p>
	Strings may be surrounded by double quotes.  As in C-like languages, a
	few special characters may be represented using an "escape" notation,
	using a backslash and another character to represent the "special
	character:"

<table border="1" summary="Escape Notation">
<colgroup><col width="100px"><col width="200px"></colgroup>
<tr>
<th align="left">Escape code</th>
<th align="left">Actual character</th>
<th align="left">Example</th></tr>
<tr>
	<td>\n</td><td>newline character</td><td>(control-J)
</tr>
<tr>
	<td>\r</td><td>carriage return</td><td>(control-M)
</tr>
<tr>
	<td>\\</td><td>backslash</td><td>(itself: '\')
</tr>
<tr>
	<td>\b</td><td>backspace</td><td>(control-H)
</tr>
<tr>
	<td>\f</td><td>formfeed</td><td>(control-L)
</tr>
<tr>
	<td>\t</td><td>tab</td><td>(control-I)
</tr>
<tr>
	<td>\a</td><td>bell</td><td>(control-G)
</tr>
<tr>
	<td>\s</td><td>space</td><td>(ASCII SPACE)
</tr>
<tr>
	<td>\"</td><td>quote</td><td>(the '"' character)
</tr>
<tr>
	<td>\xNN</td><td>the character in hex (i.e. 0xNN)</td><td></td>
</tr>
<tr>
	<td>\NNN</td><td>the character in octal (i.e. 0NNN)</td><td></td>
</tr>
<tr>
	<td>\C</td><td>(any char)</td><td>itself</td>
</tr>
</table>
<p>
	It is permissible to omit the double quotes surrounding a
	string if the parser will not confuse it with another element
	of the macro language, and if it contains no whitespace, but
	it's probably better practice to use the quotes all the time,
	to reinforce the idea that all values are strings.
<p>
	You may also use strings surrounded by single quotes.  The single
	quotes override double quotes and backslashes, making it simpler
	to enter regular expressions.  Double a single quote to insert
	one into a string.

<h2 id="variables-id"><a name="variables">Variables</a></h2>
<p>
	As noted above, variables hold strings.  These strings may
	represent words, text, numerical values, logical values, etc,
	depending on the context in which they are used.  There
	are several distinct classes of variables, distinguished
	syntactically by the character preceding their name.

<table border="1" summary="Variable Classes">
<colgroup><col width="50%"><col width="50%"></colgroup>
<tr>
<th align="left">Class</th>
<th align="left">Example</th>
</tr>
<tr>
	<td>Temporary variable</td><td>%foo</td>
</tr>
<tr>
	<td>State variable</td><td>$curcol</td>
</tr>
<tr>
	<td>Buffer variable</td><td>&lt;main.c</td>
</tr>
<tr>
	<td>Interactive variable</td><td>@"Enter a filename: "</td>
</tr>
<tr>
	<td>Mode variable</td><td>$autoindent</td>
</tr>
</table>
<p>
	All temporary variables, and some state variables, may be
	assigned to, using the "set-variable" command, or "setv"
	for short:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">$search</font>&nbsp;<font color="#800080">"new&nbsp;pattern&nbsp;to&nbsp;look&nbsp;for"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%index</font>&nbsp;<font color="#800080">"1"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%index2</font><strong><font color="#800000">=</font></strong><font color="#800080">"2"</font><br>
<!--atr2html}}--></p>
	An assignment may use either an equals (=) sign, or whitespace
	to delimit the left/right sides of the assignment, as shown.

<h2 id="tempvars-id"><a name="tempvars">Temporary variables</a></h2>
<p>
	Temporary variables are used in macros to hold intermediate
	values.  They are only temporary in that they aren't a
	"fixed" part of vile &mdash; but they _are_ persistent across
	invocations of one or more macros.  (That is, they have
	global scope.) Temporary variables are prefixed with the %
	character, and their names may be constructed from any
	printing character.

<h2 id="statevars-id"><a name="statevars">State Variables</a></h2>
<p>
	State variables allow a macro to refer to and change some
	aspects of vile's behavior.  State variables are prefixed
	with a $ character, and are always referred to in lowercase.
	Not all state variables are settable &mdash; some are read-only,
	and are so marked in the table below.
<dl>
<dt>$abufname
			<dd>[READ ONLY] Name of the "other" buffer, the one most
			recently visited.  This is what you would get if you
			typed '#' at a prompt.  (E.g. ":e #")
<dt>$autocolor-hook
			<dd>name of the hook to run when attempting to do
			automatic syntax coloring.
<dt>$bchars
			<dd>[READ ONLY] Number of characters in current buffer.
<dt>$bchanged
			<dd>[READ ONLY] Number of characters in current buffer.
<dt>$bflags
			<dd>[READ ONLY] Status flags for current buffer, as shown
			in [Buffer List].

<table border="1" summary="$sres versus screen size">
<colgroup><col width="100px"></colgroup>
<tr>
<th align="left">Flag</th>
<th align="left">Description</th></tr>
<tr><td>a</td><td>autobuffer caused this to be created</td></tr>
<tr><td>d</td><td>directory listing</td></tr>
<tr><td>i</td><td>invisible, e.g., tags</td></tr>
<tr><td>m</td><td>modified</td></tr>
<tr><td>s</td><td>scratch, will be removed when popped down</td></tr>
<tr><td>u</td><td>unread</td></tr>
</table>
<dt>$blines
			<dd>[READ ONLY] Number of lines in current buffer.
<dt>$brightness
			<dd>RGB levels for gray, normal, bright in the 0-255 range
			(winvile version only).
<dt>$buf-encoding
			<dd>[READ ONLY]  Shows the character encoding for the
			current buffer.  The values are the same as for the
			file-encoding mode, but are always resolved, i.e., no
			"auto" or "locale".
<dt>$buf-fname-expr
			<dd>[READ ONLY] Combines bufname-expr and pathname-expr
			modes for the current buffer.
<dt>$buffer-hook
			<dd>Name of procedure to run when switching to a buffer.
<dt>$bufname
			<dd>current buffer-name under the cursor.
			This is computed from the bufname-expr and
			pathname-expr patterns.
<dt>$bwindows
			<dd>[READ ONLY] Number of windows open on current buffer.
<dt>$cbufname
			<dd>The current buffer's "buffername".  (As opposed
			to the name of the file it may contain.)
<dt>$cd-hook
			<dd>Name of procedure to run when changing directories.
<dt>$cdpath
			<dd>editor's copy of the $CDPATH env var (read/write)
<dt>$cfgopts
			<dd>[READ ONLY] Comma-delimited list of "interesting"
			compiled options.  Currently tracked options include:
<table border="1" summary="Configure Options">
<colgroup><col width="100px"></colgroup>
<tr><th align="left">Option</th><th align="left">Description</th></tr>
<tr><td>athena      </td><td>xvile built with Athena widgets</td></tr>
<tr><td>curses      </td><td>editor uses curses terminal driver</td></tr>
<tr><td>locale      </td><td>editor uses system's LC_CTYPE locale</td></tr>
<tr><td>motif       </td><td>xvile built with Motif libraries</td></tr>
<tr><td>nextaw      </td><td>xvile built with Athena widgets (NeXtaw)</td></tr>
<tr><td>noshell     </td><td>shell commands are disabled</td></tr>
<tr><td>oleauto     </td><td>editor supports OLE automation.</td></tr>
<tr><td>openlook    </td><td>xvile built with OpenLook libraries</td></tr>
<tr><td>perl        </td><td>editor includes perl interpreter</td></tr>
<tr><td>termcap     </td><td>editor reads TERMCAP db for screen info.</td></tr>
<tr><td>terminfo    </td><td>editor reads TERMINFO db for screen info.</td></tr>
<tr><td>xaw         </td><td>xvile built with Athena widgets (Xaw)</td></tr>
<tr><td>xaw3d       </td><td>xvile built with Athena widgets (Xaw3D)</td></tr>
</table><p>
			If none of the above options are in effect, $cfgopts
			will be empty ("").
<dt>$cfilname
			<dd>Full pathname of the current buffer, unless it
			is a special vile buffer, in which case it will
			return the empty string.
<dt>$char
			<dd>Decimal representation of the ASCII character at
			the cursor location.
<dt>$cmd-count
			<dd>[READ ONLY] Counts repetition of the current macro,
			from 1 up to the given repeat count.  If not in a
			macro, this is zero.
<dt>$cmd-encoding
			<dd>Character set to use for the minibuffer, i.e.,
			the buffer used for commands and messages.  The
			default (auto) tells vile to set it to match the
			character set of the current buffer.
<dt>$cmd-motion
			<dd>[READ ONLY] Returns the motion (keyword) associated
			with the current macro if it was defined using
			store-operator.  Use with $cmd-count to compose the
			complete motion, e.g.,
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">$search</font>&nbsp;<font color="#800080">"new&nbsp;pattern&nbsp;to&nbsp;look&nbsp;for"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%index</font>&nbsp;<font color="#800080">"1"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%index2</font><strong><font color="#800000">=</font></strong><font color="#800080">"2"</font><br>
<!--atr2html}}--></p>
<dt>$cryptkey
			<dd>[WRITE ONLY] encryption key.
<dt>$curchar
			<dd>The index of the cursor in the buffer, in characters
			(counting from 1).
<dt>$curcol
			<dd>The cursor's column number (counting from 1).
<dt>$curline
			<dd>The cursor's line number (counting from 1).
<dt>$cwd
			<dd>Current working directory.
<dt>$cwline
			<dd>The relative line number of the cursor in the
			current window.
<dt>$debug
			<dd>Boolean value which enables runtime tracing
			of macro execution.  This can be set in the
			~trace command (described in detail below) as
			well as via set-variable.
<dt>$directory
			<dd>Location of temp files.  This is unused, but
			its initial value is set from the user's
			TMP environment variable.
<dt>$discmd
			<dd>Boolean value which will prevent vile from
			printing some status messages.
			
			It is automatically set to FALSE while sourcing a
			file, or while executing a macro (after prompting for
			missing parameters).

			Set it to TRUE to allow nested macros to show a
			prompt-string for missing parameters.
<dt>$disinp
			<dd>Boolean value which will prevent vile from
			displaying command line input characters.
<dt>$encoding
			<dd>[READ ONLY] The character encoding, e.g., ISO-8859-1.
<dt>$end-of-cmd
			<dd>Boolean which is true if user entered the cmd with a
			carriage return (Some commands may expect to
			receive additional arguments if their name is
			terminated with a space character rather than
			a carriage return.)
<dt>$error-buffer
			<dd>Buffer name associated with vile's error-buffer
			feature.  This variable commonly appears in a
			~local statement in macros that temporarily
			reassign error-buffer (e.g., the ShowManpage macro
			in macros/manpage.rc).
<dt>$error-expr
			<dd>Regular expression expanded from [Error Expressions]
			which matched the most recent find-next-error command.
<dt>$error-match
			<dd>Text from the current buffer which which was matched
			in the most recent find-next-error command.
<dt>$error-tabstop
			<dd>Tabstop value to use when computing the column that
			a "%C" pattern will produce.  If zero or negative,
			use the current buffer's tabstop, otherwise use the
			given value.  The default is 8.
<dt>$exec-path
			<dd>[READ ONLY] Where to find vile.
<dt>$exec-suffix
			<dd>[READ ONLY] suffix, if any, for execable programs.
			Use this in portable macros, with &amp;lookup, to get the
			actual program path.
<dt>$exit-hook
			<dd>Name of procedure to run when quitting.
<dt>$favorites
			<dd>[READ ONLY] Path to favorites folder (win32 only)
<dt>$fchanged
			<dd>Boolean, true if file for current buffer is modified.
<dt>$fence-limit
			<dd>iteration limit for complex fences, in seconds.
<dt>$filename-expr
			<dd>actual pattern for %F in [Error Expressions].  Note
			that vile wraps this in "\(" and "\+\)", so the
			1-or-more applies to the last subexpression in %F.
			We use this side-effect in the win32 port, for example
				'\([a-zA-Z]:\)\?[^ \t:]'
			to make the last range repeat 1-or-more times.
<dt>$filename-ic
			<dd>[READ ONLY] Boolean indicating if the host system's
			filenames are matched ignoring their case.
<dt>$filter-list
			<dd>[READ ONLY] list of builtin-filters.
<dt>$findpath
			<dd>editor's copy of the $VILE_FINDPATH environment var
			(read/write).  Available on win32 and unix hosts.
			For more details, refer to that section of the help
			file entitled "Working in a project hierarchy".
<dt>$find-cmd
			<dd>[READ ONLY] last shell command spawned via the
			capture command's builtin "find" interface.
			Available on win32 and unix hosts.
<dt>$font
			<dd>Name of the current font (in xvile/winvile only).
<dt>$forward-search
			<dd>Boolean value indicating search direction.
<dt>$helpfile
			<dd>Filename referred to when help is requested (usually
			vile.hlp).
<dt>$iconname
			<dd>With xvile, contains current icon name.
<dt>$identifier
			<dd>The current "identifier-like" word under the cursor.
			This is computed from the identifier-expr pattern.
			Also see the "tagword" mode.
<dt>$kbd-macro
			<dd>[READ ONLY]  This is the contents of the keyboard
			macro buffer.
<dt>$kill
			<dd>[READ ONLY]  This is vile's "unnamed" yank register,
			which contains the result of the last line-oriented
			yank or delete.
<dt>$lastkey
			<dd>[READ ONLY]  Character most recently entered at
			the keyboard.
<dt>$latin1-expr
			<dd>pattern to match locales using ISO-8859-1 in case
			they are not installed.  Normally vile looks for a
			narrow locale to correspond with the wide (UTF-8
			encoding) locale.  If locale data is incomplete,
			vile can still support ISO-8859-1 encoding, but checks
			to ensure that the locale is compatible.
			Some systems lack a full set of locale data.
			This pattern helps it decide if the (missing) narrow
			locale would use ISO-8859-1 encoding.
<dt>$lcols
			<dd>[READ ONLY] The length (in columns) of the current line.
<dt>$libdir-path
			<dd>This value will be used to augment the user's PATH
			environment variable when running filters, so that
			vile-specific filters needn't clutter general purpose
			bin directories.
<dt>$line
			<dd>Contains the text of the current line of the
			current buffer starting with the cursor position.
<dt>$llength
			<dd>[READ ONLY] The length (in characters, not columns)
			of the current line.
<dt>$locale
			<dd>[READ ONLY] The character locale, e.g., en_US.
<dt>$majormode
			<dd>[READ ONLY] Current majormode, if any.
<dt>$majormode-hook
			<dd>name of the hook to run when attempting to determine
			the majormode for the current buffer.  If this is not
			defined, vile uses the prefixes and suffixes values
			to decide.
<dt>$match
			<dd>[READ ONLY] After a successful search, contains
			the text that matched the search pattern.
<dt>$menu-file
			<dd>The name of the menu file (e.g. .vilemenu)
<dt>$mode
			<dd>[READ ONLY] "insert", "command", or "overwrite" mode.
<dt>$modeline-format
			<dd>Format of mode lines.  See "Mode line customization"
			in the vile help file.
<dt>$modified
			<dd>[READ ONLY] is current buffer modified or not?
<dt>$ncolors
			<dd>Number of displayed colors, must be power of two.
<dt>$ntildes
			<dd>Percent of window filled by ~ chars, at end of buffer.
<dt>$ocwd
			<dd>[READ ONLY]  Previous current directory.
<dt>$os
			<dd>[READ ONLY]  "Operating system" for which was vile
			was built.  Currently "unix" (if no more-specific
			name is derived from the configure script), "dos",
			"os/2", "vms" and "win32".
<dt>$pagelen
			<dd>Length of the vile screen.
<dt>$pagewid
			<dd>Width of the vile screen.
<dt>$palette
			<dd>Some versions of vile implement screen coloring.
			The variable consists of digits which control
			the current color set, usually one digit per
			color.
<dt>$patchlevel
			<dd>[READ ONLY] current patch-level (empty for release).
<dt>$pathlist-separator
			<dd>separates directory names in lists such as $PATH.
<dt>$pathname
			<dd>current "path-like" word, under the cursor.
			This is computed from the pathname-expr pattern.
			If the current buffer is a directory, use the
			entire line, overriding the regular expression.
<dt>$pathname-separator
			<dd>separates levels of directory names in a path.
			Usually this is '/', for Unix.
<dt>$pending
			<dd>[READ ONLY]  Boolean which is true when the user
			has "typed ahead", i.e. there are waiting keystrokes.
<dt>$pid
			<dd>[READ ONLY]  vile's process-id.
<dt>$position-format
			<dd>Format of ^G command.  See "Mode line customization"
			in the vile help file.
<dt>$progname
			<dd>[READ ONLY] The string "vile", "xvile", or "winvile"
			as appropriate.
<dt>$prompt
			<dd>The string ": ", used in command-line prompts.
<dt>$qidentifier
			<dd>the name of the current "qualified-identifier-like"
			word under the cursor, useful for C++ programmers.
<dt>$read-hook
			<dd>Name of procedure to run after a file is read.
<dt>$replace
			<dd>The current replacement strings, used in
			substitutions.
<dt>$search
			<dd>The current search pattern.
<dt>$seed
			<dd>The seed for the internal random number generator.
<dt>$shell
			<dd>Name of the shell program for spawned commands.
			For Unix, this corresponds to $SHELL, while DOS,
			OS/2 and related systems use $COMSPEC.
<dt>$sres
			<dd>Current screen size on a DOS PC (meaningless on a
			Win32 host).  Values:

<table border="1" summary="$sres versus screen size">
<colgroup><col width="200px"></colgroup>
<tr>
<th align="left">$sres</th>
<th align="left">screen size</th></tr>
<tr><td>"2"</td><td>"25"</td></tr>
<tr><td>"4"</td><td>"43"</td></tr>
<tr><td>"5"</td><td>"50"</td></tr>
<tr><td>"6"</td><td>"60"</td></tr>
<tr><th align="left">Values for VMS:</th></tr>
<tr><td>"WIDE"</td><td>"NORMAL"</td></tr>
</table>

			Other drivers ignore the value.
<dt>$startup-file
			<dd>The name of the startup file (e.g. .vilerc)
<dt>$startup-path
			<dd>Where to find the startup file
<dt>$status
			<dd>[READ  ONLY]  Boolean representing success of
			most recent command.  Since a failed command will
			usually cause an entire macro to fail, the
			~force directive is often used to suppress a
			command's failure.  $status preserves its exit status.
<dt>$term-encoding
			<dd>[READ ONLY]  Shows the character encoding which the
			terminal/display driver can handle.  The values are
			the same as for the file-encoding mode.  If it can
			display UTF-8 (terminfo/termcap) or UTF-16 (winvile),
			and the terminal is initialized to match, vile shows
			the corresponding "utf-8" or "utf-16" value.
<dt>$title
			<dd>The current window title (X11, win32 versions only).
<dt>$title-encoding
			<dd>Tell whether to send title-change escape sequences
			to xterm in ISO-8859-1 (8bit) or UTF-8 (utf-8).
			A "locale" setting is provided, which tells vile to
			use UTF-8 if the locale encoding uses UTF-8, and
			ISO-8859-1 otherwise.
			ISO-8859-1 is standard; some terminal emulators
			require UTF-8.
			Even with this, other programs such as GNU screen
			interfere with setting titles with non-ASCII content.
<dt>$title-format
			<dd>The format for the window title (X11, win32 versions).
			If this variable is not set, the title is the program
			name and the current buffer, separated by a dash, e.g.,
				%{$progname} - %{$cbufname}
			Use the swap-title mode to control the order of those
			strings.  If $title-format is set, swap-title has no
			effect.  See "Mode line customization" in the vile
			help file.
<dt>$version
			<dd>[READ ONLY] Contains vile's version string.
<dt>$with-prefix
			<dd>[READ ONLY] String which is set by "~with" directive
			in macros.  If no prefix was set, this returns ERROR.
<dt>$wlines
			<dd>Height of current window.
<dt>$word
			<dd>The "word" at the cursor location.
<dt>$write-hook
			<dd>Name of procedure to run before a file is written
<dt>$xdisplay
			<dd>The value to set $DISPLAY when running $xshell.
<dt>$xshell
			<dd>Name of the terminal program for spawned xvile
			commands.  The default is "xterm", but may also
			be set by the environment variable $XSHELL.
<dt>$xshell-flags
			<dd>Command-line flags after $xshell, normally "-e"
			The $XSHELLFLAGS environment variable determines
			the default value.
</dl>

<h2 id="modevars-id"><a name="modevars">Mode variables</a></h2>
<p>
	You may set and use the values of the editor modes (i.e., universal
	modes, buffer-only modes or window-only modes) as if they were
	state variables (e.g., "setv $errorbells=true").  The global
	values of the editor modes are not visible to the expression
	evaluator.
<p>
	Realistically, this feature is little used, since vile's set/setl
	commands, as well as the &amp;global/&amp;local functions, serve the same
	purpose.

<h2 id="bufvars-id"><a name="bufvars">Buffer variables</a></h2>
<p>
	Buffer variables (a '&lt;' followed by a buffer name) return the
	current line of the specified buffer, automatically setting the
	position to the next line.

<h2 id="reponses-id"><a name="reponses">Interactive variables</a></h2>
	Interactive variables are not actually "variables" at all &mdash;
	they're really more like functions that return a string,
	entered by the user in response to a prompt.  The prompt
	is the name of the "variable".
<p>
	They are so similar to a query function that there is
	function which serves this exact purpose, and which should be
	used in preference.  Thus, one might have previously written:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%file</font>&nbsp;@<font color="#800080">"What&nbsp;file?"</font><br>
<!--atr2html}}--></p>
	Instead, one should now write:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%file</font>&nbsp;<font color="#008080">&amp;query</font>&nbsp;<font color="#800080">"What&nbsp;file?"</font><br>
<!--atr2html}}--></p>

<h2 id="functions-id"><a name="functions">Functions</a></h2>
<p>
	Functions always return strings.  Functions can take 0, 1, 2, or 3
	arguments.  Function names are always preceded by the &amp; character, and
	can usually be shortened to just three characters, though there is
	little reason to do so.
<p>
	Tasks that are usually implemented as "operators" in other
	languages are implemented as functions in vile's macro language.
	Thus, for example, arithmetic division which is usually
	written as "6 / 2" is written as "&amp;div 6 2".  (I believe this
	is sometimes called "prefix" notation, as opposed to the
	normal operator "infix" notation, or the "postfix" notation
	used on a stack-oriented calculator, i.e. "6&nbsp;2&nbsp;/".)
<p>
	Depending on the function, arguments may be expected to
	represent generic strings, numeric values, or logical
	(boolean) values.
<ul>
	<li>Numeric arguments can be any of the following:
<ul>
		<li>hexadecimal values (digits beginning with leading "0x")
		<li>octal values (digits beginning with leading "0")
		<li>decimal values (other strings of digits)
		<li>character constants (single character in single quotes: 'C')
		<li>any other string will be interpreted as 0.
</ul>
	 <li>Boolean (or "logical") arguments will be interpreted as
	   follows (without regard to upper/lowercase):
<ul>
		<li>Logically "true" values:<br>
		    "true", "t", "yes", "y", "on", and non-zero numerics.

		<li>Logically "false" values:<br>
		    "false", "f", "no", "n", "off", and zero-valued numerics
</ul>
</ul>
<p>
	Arithmetic functions &mdash;
<p>
	  These all return numeric values:
<dl>
<dt>&amp;add    "N1" "N2"
	<dd>Add "N1" and "N2".
<dt>&amp;sub    "N1" "N2"
	<dd>Subtract "N2" from "N1".
<dt>&amp;times  "N1" "N2"
	<dd>Multiply "N1" by "N2".
<dt>&amp;divide "N1" "N2"
	<dd>Divide the "N1" by "N2"
<dt>&amp;mod    "N1" "N2"
	<dd>Divide the "N1" by "N2", return remainder.
<dt>&amp;negate "N"
	<dd>Return -(N).
<dt>&amp;ascii  "S"
	<dd>Return the ASCII code of the first character in "S"
<dt>&amp;random "N"
<dt>&amp;rnd    "N"
	<dd>Random number between 1 and N
<dt>&amp;abs    "N"
	<dd>Absolute value of "N"
<dt>&amp;ftime  "N"
	<dd>The modification time of the file "N"
<dt>&amp;stime
	<dd>The system time.
</dl>
<p>
	String manipulation functions &mdash;
<p>
	  These two return numeric values:
<dl>
<dt>&amp;length "S"
	<dd>Returns length of string "S".
<dt>&amp;sindex "S1" "S2"
	<dd>Returns index of "S2" within "S1", or 0.
</dl>
<p>
	  The rest return strings:
<dl>
<dt>&amp;bind   "S"
	<dd>Return the function name bound to the key sequence "S".
<dt>&amp;cat    "S1" "S2"
	<dd>Concatenate S1 and string "S".
<dt>&amp;chr    "N"
	<dd>Converts numeric "N" to an ASCII character.
<dt>&amp;cclass "S"
	<dd>Character class (see "show-printable")
<dt>&amp;env    "S"
	<dd>Return the value of the user's environment variable named "S".
<dt>&amp;gtkey
	<dd>Get a single raw keystroke from the user.
<dt>&amp;gtmotion "N"
	<dd>Get a key sequence from user which must be bound to a motion.  The
	parameter is one of the binding names:
<ul>
<li>"command"
<li>"default"
<li>"insert"
<li>"select"
</ul>
	If successful, the name of the corresponding motion function is
	returned.
<dt>&amp;gtsequence
	<dd>Get a complete vile key sequence from user.
<dt>&amp;left   "S" "N"
	<dd>Extract first "N" characters from "S"
<dt>&amp;lower  "S"
	<dd>Return lowercase version of "S".
<dt>&amp;right  "S" "N"
	<dd>Extract chars from position "N" onward.
<dt>&amp;middle "S" "N1" "N2"
	<dd>Extract "N2" chars at position "N1".
<dt>&amp;upper  "S"
	<dd>Return uppercase version of "S".
<dt>&amp;trim   "S"
	<dd>Remove whitespace at either end of "S", reduce multiple spaces
	within "S" to just one space each.
</dl><p>
	Boolean/logical functions &mdash;
<p>
	  These all return TRUE or FALSE:
<dl>
<dt>&amp;not    "B"
	<dd>Return inverse of boolean "B".
<dt>&amp;and    "B1" "B2"
	<dd>Return logical AND of "B1" and "B2".
<dt>&amp;or	    "B1" "B2"
	<dd>Return logical OR of "B1" and "B2".

<dt>&amp;equal  "N1" "N2"
	<dd>Is "N1" numerically equal to "N2"?
<dt>&amp;geq    "N1" "N2"
	<dd>Is "N1" numerically not less than "N2"?
<dt>&amp;greater "N1" "N2"
	<dd>Is "N1" numerically greater than "N2"?
<dt>&amp;gt	    "N1" "N2"
	<dd>(same as &amp;greater)
<dt>&amp;isa    "C"  "N"
	<dd>Is "N" a member of class "C".  Classes include:  buffer, color,
	mode, submode, Majormode.
<dt>&amp;leq    "N1" "N2"
	<dd>Is "N1" numerically not greater than "N2"?
<dt>&amp;lessthan "N1" "N2"
	<dd>Is "N1" numerically less than "N2"?
<dt>&amp;lt	    "N1" "N2"
	<dd>(same as &amp;lessthan)
<dt>&amp;neq    "N1" "N2"
	<dd>Is "N1" numerically not equal to "N2"?
<dt>&amp;sequal "S1" "S2"
	<dd>Is "S1" the same string as "S2"?
<dt>&amp;sgeq   "S1" "S2"
	<dd>Is "S1" lexically not less than "S2"?
<dt>&amp;sgreater "S1" "S2"
	<dd>Is "S1" lexically greater than "S2"?
<dt>&amp;sgt    "S1" "S2"
	<dd>(same as &amp;slessthan)
<dt>&amp;sleq   "S1" "S2"
	<dd>Is "S1" lexically not greater than "S2"?
<dt>&amp;slessthan "S1" "S2"
	<dd>Is "S1" lexically less than "S2"?
<dt>&amp;slt    "S1" "S2"
	<dd>(same as &amp;slessthan)
<dt>&amp;sneq   "S1" "S2"
	<dd>Is "S1" lexically not equal to "S2"?
<dt>&amp;readable "S"
<dt>&amp;rd	    "S"
	<dd>Is the named file "S" readable?
<dt>&amp;writable "S"
	<dd>Is the named file "S" writable?
<dt>&amp;execable "S"
	<dd>Is the named file "S" exec'able?
<dt>&amp;bchanged "S"
	<dd>Is given buffer "S" modified?
<dt>&amp;fchanged "S"
	<dd>Is file for given buffer "S" modified?
<dt>&amp;cmatch "R" "V"
	<dd>Does the given regular expression "R" match the value "V" (ignoring
	case)?
<dt>&amp;error "S"
	<dd>Was the string set with the ERROR token?  For example, a &amp;query
	that is aborted will return an ERROR result.
<dt>&amp;match "R" "V"
	<dd>Does the given regular expression "R" match the value "V"?
<dt>&amp;filter "M"
	<dd>Does the given majormode have a built-in highlighting filter?
<dt>&amp;stoken "T" "D" "S"
	<dd>Is token "T" in string "S", given delimiters "D"?
</dl>
<p>
	Miscellaneous functions &mdash;
<p>
	  These all return string values:
<dl>
<dt>&amp;classof "N"
	<dd>Retrieves the class(es) to which the given name may return. 
	Usually this is a single name, e.g., one of those checked by &amp;isa. 
	If multiple matches are found, the result contains each classname
	separated by a space.

<dt>&amp;default "MODENAME"
	<dd>Retrieves initial/default value for the given mode or state
	variable.

<dt>&amp;global "MODENAME"
	<dd>Retrieves universal/global mode setting.

<dt>&amp;indirect "S"
	<dd>Evaluate value of "S" as a macro language variable itself.  Thus if
	%foo has value "HOME", then
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008080">&amp;env</font>&nbsp;<font color="#008080">&amp;indirect</font>&nbsp;<font color="#008080">%foo</font><br>
<!--atr2html}}--></p>
	will return the home directory pathname.

<dt>&amp;local  "MODENAME"
	<dd>Retrieves local mode setting (for current buffer).
<dt>&amp;lookup   "N" "P"
	<dd>The "N" keyword tells which field to use looking for the file "P":
	<p>
		bin &ndash; look in vile's directory<br>
		current &ndash; look in the current directory<br>
		home &ndash; look in user's $HOME directory<br>
		libdir &ndash; look along $libdir-path<br>
		path &ndash; look along user's $PATH<br>
		startup &ndash; look along $startup-path
	<p>
	as well as associated access tests:
	<p>
		execable - test if file is exec'able<br>
		readable - test if file is readable<br>
		writable - test if file is writable
	<p>
	The search order is fixed:  current, home, bin, startup, path, libdir. 
	Note that the directory lists may overlap.
<dt>&amp;mclass "M"
	<dd>Retrieve the class to which the given mode belongs.  This is
	different from &amp;mclass since it distinguishes the modes Return
	values include:  universal buffer window submode Majormode.
<dt>&amp;qpasswd  "S"
	<dd>Present "S" to the user and return their response.  Each typed
	character is echoed as '*'.  The response is not recallable via the
	editor's history mechanism.
<dt>&amp;query  "S"
	<dd>Present "S" to the user, and return their typed response.
<dt>&amp;date "F" "T"
	<dd>If strftime() is found, format the time "T" using the "F" format. 
	Otherwise, use ctime() to format the time.  Times are numbers (see
	&amp;ftime and &amp;stime).
<dt>&amp;dquery  "S" "D"
	<dd>Present "S" to the user, and return their typed response.  If "D"
	is given, use that as the default response.  Otherwise use the previous
	response as the default.
<dt>&amp;path   "N" "P"
	<dd>The "N" keyword tells which field to extract from the pathname "P":
<p>
	end &ndash; suffix of the filename<br>
	full &ndash; absolute path<br>
	head &ndash; directory<br>
	root &ndash; filename without suffix<br>
	short &ndash; relative path<br>
	tail &ndash; filename
<dt>&amp;pcat   "D" "F"
	<dd>Concatenate directory and filename, handing syntax and ensuring
	that if the filename is absolute, that the directory is ignored.
<dt>&amp;pquote "P"
	<dd>Quote the pathname if it contains characters such as space that
	cannot be passed to the shell without special handling.
<dt>&amp;register "S"
	<dd>Return contents of register "S".  Only the first character of "S"
	is used for the name.  Note that the contents may be more than one
	line.
<dt>&amp;token  "N" "D" "S"
	<dd>Select N'th token of string "S", given delimiters "D".
<dt>&amp;translate  "F" "T" "S"
	<dd>Translate from "F" to "T" each character of string "S".  The "F"
	and "T" are strings of equal length; characters from "S" found in "F"
	are translated to the character in "T" at the same index.
<dt>&amp;word   "N" "S"
	<dd>Select N'th word of string "S", blank separated.
</dl>

<h2 id="directives-id"><a name="directives">Directives</a></h2>
<p>
	The macro language has the capability for controlling flow
	and repetition through conditional, branching, and looping
	instructions.  Complex text processing or user input tasks
	can be constructed in this way.  The keywords that introduce
	this control are called "directives".  They are always
	prefixed with the ~ character, and they are always in all
	lowercase.

    <h3 id="endm-id">~<a name="endm">endm</a></h3>
<p>
	The "store-procedure" and "store-macro" commands both indicate
	the start of the body of a macro routine.  ~endm indicates
	the end of that routine.

    <h3 id="force-id">~<a name="force">force</a></h3>
<p>
	To prevent a failed command from terminating the macro which
	invokes it, the ~force directive can be used to "hide" a
	bad return code.  For instance, the "up-line" command might
	fail if executed at the top of a buffer.  "~force up-line"
	will suppress the failure.  The $status variable can be used
	to determine whether the command succeeded or not.

    <h3 id="hidden-id">~<a name="hidden">hidden</a></h3>
<p>
	You can suppress not only the check for success or failure of a macro
	as in ~force, but also the screen refresh, making macros run more
	rapidly.  For example
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#008080">30</font></strong>&nbsp;<strong><font color="#000080">store-macro</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#800080">"[Attaching&nbsp;C/C++&nbsp;attributes...]"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~local</font>&nbsp;<font color="#008080">$curcol</font>&nbsp;<font color="#008080">$curline</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~hidden</font>&nbsp;<strong><font color="#000080">goto-beginning-of-file</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~hidden</font>&nbsp;<strong><font color="#000080">attribute-from-filter</font></strong>&nbsp;<strong><font color="#000080">end-of-file</font></strong>&nbsp;<font color="#800080">"vile-c-filt"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#800080">"[Attaching&nbsp;C/C++&nbsp;attributes...done&nbsp;]"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;<strong><font color="#000080">execute-macro-30</font></strong>&nbsp;<font color="#800080">^X-q</font><br>
<!--atr2html}}--></p>
	causes the screen updates from moving the current position to the
	beginning of the file and then filtering (which moves the position to
	the end-of-file) to be suppressed.  The screen will be updated after
	completion of the macro, after the current position has been restored
	from the values saved with the ~local directive.

    <h3 id="quiet-id">~<a name="quiet">quiet</a></h3>
<p>
	Rather than suppress all screen updates, you may suppress any messages
	that are written as the command progresses.

    <h3 id="conditionals-id">~<a name="conditionals">if, ~elseif, ~else, and ~endif</a></h3>
<p>
	These control execution of macro commands in the expected manner.
	The ~if directive is followed by a string which is evaluated
	for truth or falsehood according to the rules outlines for
	boolean variables, above.  The following fragment demonstrates the
	use of this family of directives:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">beginning-of-line</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;test&nbsp;for&nbsp;'#'</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;equ</font>&nbsp;<font color="#008080">$char</font>&nbsp;<strong><font color="#008080">35</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%comment-type</font>&nbsp;<font color="#800080">"shell&nbsp;comment"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;test&nbsp;for&nbsp;';'</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~elseif</font>&nbsp;<font color="#008080">&amp;equ</font>&nbsp;<font color="#008080">$char</font>&nbsp;<strong><font color="#008080">59</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%comment-type</font>&nbsp;<font color="#800080">"vile&nbsp;macro&nbsp;language&nbsp;comment"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~else</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#800080">"Not&nbsp;an&nbsp;expected&nbsp;comment&nbsp;type"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~return</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#800080">"The&nbsp;current&nbsp;line&nbsp;is&nbsp;a&nbsp;"</font>&nbsp;<font color="#008080">%comment-type</font><br>
<!--atr2html}}--></p>
<h3 id="goto-id">~<a name="goto">goto</a></h3>
<p>
	What would a decent programming language be without a "goto"?
	The ~goto directive is followed by the name of a label.  Labels
	may appear anywhere in the current macro definition, and
	are themselves preceded with a * character.
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~force</font>&nbsp;<strong><font color="#000080">up-line</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;<font color="#008080">&amp;not</font>&nbsp;<font color="#008080">$status</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~goto</font>&nbsp;foundtop<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*foundtop<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#800080">"At&nbsp;top&nbsp;of&nbsp;buffer"</font><br>
<!--atr2html}}--></p>

<h3 id="while-id">~<a name="while">while and ~endwhile</a></h3>
<p>
	The block of statements bracketed by ~while and ~endwhile are
	executed repeatedly, until the condition being tested by
	~while becomes false.
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;how&nbsp;many&nbsp;occurrences&nbsp;of&nbsp;a&nbsp;given&nbsp;pattern&nbsp;in&nbsp;a&nbsp;buffer?</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;<strong><font color="#000080">nowrapscan</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%lookfor</font>&nbsp;somepattern<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;we'll&nbsp;count&nbsp;one&nbsp;too&nbsp;many</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%howmany</font>&nbsp;<font color="#800080">"-1"</font><br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%continue</font>&nbsp;yes<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~while</font>&nbsp;<font color="#008080">%continue</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~force</font>&nbsp;<strong><font color="#000080">search-forward</font></strong>&nbsp;<font color="#008080">%lookfor</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%continue</font>&nbsp;<font color="#008080">$status</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%howmany</font>&nbsp;<font color="#008080">&amp;add</font>&nbsp;<font color="#008080">%howmany</font>&nbsp;<font color="#800080">"1"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endwhile</font><br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">%howmany</font>&nbsp;<font color="#800080">"&nbsp;appearances&nbsp;of&nbsp;"</font>&nbsp;<font color="#008080">%lookfor</font><br>
<!--atr2html}}--></p>
<h3 id="break-id">~<a name="break">break</a></h3>
<p>
	The ~break directive allows early termination of an enclosing
	while-loop.  Extending the above example:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;count&nbsp;the&nbsp;occurrences&nbsp;of&nbsp;a&nbsp;pattern&nbsp;in&nbsp;all&nbsp;buffers</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;<strong><font color="#000080">nowrapscan</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;<strong><font color="#000080">noautobuffer</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">rewind</font></strong><br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%lookfor</font>&nbsp;pgf<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%howmany</font>&nbsp;<font color="#800080">"0"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%buffers</font>&nbsp;<font color="#800080">"1"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%cont</font>&nbsp;yes<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~while</font>&nbsp;true<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">goto-beginning-of-file</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~while</font>&nbsp;true<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~force</font>&nbsp;<strong><font color="#000080">search-forward</font></strong>&nbsp;<font color="#008080">%lookfor</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;not</font>&nbsp;<font color="#008080">$status</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~break</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%howmany</font>&nbsp;<font color="#008080">&amp;add</font>&nbsp;<font color="#008080">%howmany</font>&nbsp;<font color="#800080">"1"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endwhile</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~force</font>&nbsp;<strong><font color="#000080">next-buffer</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;not</font>&nbsp;<font color="#008080">$status</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~break</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%buffers</font>&nbsp;<font color="#008080">&amp;add</font>&nbsp;<font color="#008080">%buffers</font>&nbsp;<font color="#800080">"1"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endwhile</font><br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%msg</font>&nbsp;&nbsp;<font color="#008080">%lookfor</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%msg</font>&nbsp;&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#800080">"&nbsp;appeared&nbsp;"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%msg</font>&nbsp;&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">%howmany</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%msg</font>&nbsp;&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">%msg</font>&nbsp;<font color="#800080">"&nbsp;times&nbsp;in&nbsp;"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%msg</font>&nbsp;&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">%msg</font>&nbsp;<font color="#008080">%buffers</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">%msg</font>&nbsp;&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">%msg</font>&nbsp;<font color="#800080">"&nbsp;buffers."</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#008080">%msg</font><br>
<!--atr2html}}--></p>
<h3 id="return-id">~<a name="return">return</a></h3>
<p>
	This causes immediate exit of the current macro, back to the
	calling macro, or to user control, as appropriate.

<h3 id="local-id">~<a name="local">local</a></h3>
<p>
	The ~local directive causes the variables which are listed to
	be saved at that point (once if the directive is within a loop),
	and automatically restored at the end of the current macro.
	If the directive specifies a temporary variable which was not
	defined before, it will be deleted rather than restored.
<p>
	For example:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~local</font>&nbsp;<font color="#008080">$curcol</font>&nbsp;<font color="#008080">$curline</font><br>
<!--atr2html}}--></p>
	will restore the cursor position.  The order is important in this
	example, because vile restores the variables in the reverse order
	of the ~local declaration.  If $curline is set, $curcol will be
	reset to the first column as a side effect.  So we specify that
	$curcol is restored last.
<p>
	~local can save/restore the state of mode variables [1], user
	variables and the state variables shown with show-variables.  Note
	that setting certain variables, such as the cursor position, will
	have side effects, i.e., modifying the display.  If these are
	distracting, use ~hidden or ~quiet to suppress display updates until
	the macro completes.
<p>
	[1] Subject to the limitations described above for "Mode
	variables".  Namely, "global values of the editor modes are not
	visible to the expression evaluator."

<h3 id="withblocks-id">~<a name="withblocks">with, ~elsewith and ~endwith</a></h3>
<p>
	Tokens following the ~with directive will be prepended to succeeding
	lines of macro until the next ~endwith directive, or the end of the
	current macro.	This is useful for simplifying majormode directives,
	which are repetitive.  Use ~elsewith as a convenience for fences;
	otherwise it functions just as ~with does.
<p>
	For example, use
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">define-mode</font></strong>&nbsp;<em>txt</em><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~with</font>&nbsp;<strong><font color="#000080">define-submode</font></strong>&nbsp;<em>txt</em><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">suf</font></strong>&nbsp;<font color="#800080">"\\.txt$"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">comment-prefix</font></strong>&nbsp;<font color="#800080">"^\\s*/\\?--"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">comments</font></strong>&nbsp;<font color="#800080">"^\\s*/\\?--\\s+/\\?\\s*$"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endwith</font><br>
<!--atr2html}}--></p>
	rather than
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">define-mode</font></strong>&nbsp;<em>txt</em><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">define-submode</font></strong>&nbsp;<em>txt</em>&nbsp;<strong><font color="#000080">suf</font></strong>&nbsp;<font color="#800080">"\\.txt$"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">define-submode</font></strong>&nbsp;<em>txt</em>&nbsp;<strong><font color="#000080">comment-prefix</font></strong>&nbsp;<font color="#800080">"^\\s*/\\?--"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">define-submode</font></strong>&nbsp;<em>txt</em>&nbsp;<strong><font color="#000080">comments</font></strong>&nbsp;<font color="#800080">"^\\s*/\\?--\\s+/\\?\\s*$"</font><br>
<!--atr2html}}--></p>
    <h3 id="tracing-id">~<a name="tracing">trace</a></h3>
	No program is complete without a few bugs.  Use vile's builtin
	macro tracing to see what the macros really do.  The ~trace command
	sets the $debug variable, which controls whether vile appends to
	the [Trace] buffer a copy of each line executed, the local
	variables saved/restored and intermediate states of expression
	evaluation.
<p>
	For example,
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~trace</font>&nbsp;on<br>
<!--atr2html}}--></p>
	activates tracing,
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~trace</font>&nbsp;off<br>
<!--atr2html}}--></p>
	deactivates it, and
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~trace</font><br>
<!--atr2html}}--></p>
	prints a message telling if tracing is active.

<h2 id="commands-id"><a name="commands">Editor commands</a></h2>
<p>
	The "show-commands" command lists _all_ available editor commands.
	This is, admittedly, a large list and generally grows with
	successive releases of the editor.  Fortunately, most editor
	commands include short help strings that describe their purpose.
	To winnow the list to a particular area of interest, use the
	"apropos" command (e.g., "apropos append").  To determine the
	command bound to a specific key, use "describe-key".  The format of
	the apropos, describe-key, and show-commands listing is as follows:
<pre>
	command-name             optional-key-binding(s)
	optional-command-name-aliases
	(help-string)
</pre><p>
	Commands fall into three broad categories:  simple, motion, operator.

    <h3 id="simplecommands-id"><a name="simplecommands">Simple commands</a></h3>
	A simple command neither acts on a region nor does it explicitly
	move the cursor through a region (the "region" concept is explained
	in the "Motion commands" section below).  An example of a simple
	command is "find-tag", and here's the listing returned by
	show-commands:
<pre>
	"find-tag"               ^]
	  or            "ta"
	  or            "tag"
	  ( look up the given (or under-cursor) name as a "tag" )
</pre>
	From the perspective of writing a macro, it can be seen that
	find-tag has two aliases, either of which may be substituted for
	the "find-tag" name within a macro definition.	Notice that the
	help string mentions a "name" argument and sure enough, if you type
	":find-tag" within the editor, you'll be prompted for a "Tag name".
	This gives us enough information to write a contrived macro that
	finds a fixed tag name:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;tryit</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">tag</font></strong>&nbsp;<font color="#800080">"filterregion"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
	Note also that some help strings include a "CNT" keyword, which
	indicates that the command name may be preceded by an integer count
	that repeats the command action that many times (default CNT value
	is 1).	For example, here's the "join-lines" listing:
<pre>
	"join-lines"     J
	  ( join CNT lines together with the current one )
</pre>
	And here's a macro that joins 4 lines:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;join4</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#008080">4</font></strong>&nbsp;<strong><font color="#000080">join-lines</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
<h3 id="motioncommands-id"><a name="motioncommands">Motion commands</a></h3>
	Motions move the cursor and, consequently, may be used to define a
	region.	 This latter property is an important aspect of an
	"operator command".  The "show-motions" command lists the editor's
	motion commands.
<p>
	Within a macro, the following general syntax invokes a motion:
<pre>
	[count] region-spec
</pre><p>
	The optional "count" specifies the number of affected region-specs
	(default value is 1).  An example motion is "back-line", and here
	is its show-commands listing:
<pre>
	"back-line"              k         #-A
	  or    "previous-line"
	  or    "up-arrow"
	  or    "up-line"
	  (motion: move up CNT lines )
</pre><p>
	Note that the help string is prefixed with the word "motion", which
	unambiguously identifies the nature of this command.  Given the
	above information, we can write a contrived macro to move the
	cursor up three lines:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;upthree</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#008080">3</font></strong>&nbsp;<strong><font color="#000080">back-line</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
<h3 id="operatorcommands-id"><a name="operatorcommands">Operator commands</a></h3>
<p>
	Operators manipulate regions.  The "show-operators" command lists
	the editor's operator commands.  By convention, most operator names
	end with "-til" (short for "until").
<p>
	Within a macro, the following general syntax invokes an operator:
<pre>
	[count] operator-name region-spec [args...]
</pre><p>
	where:
<dl>
<dt>region-spec
			<dd>may be replaced with any motion command or the special
		       word "lines" (the latter is a synonym for a single
		       buffer line).
<dt>count
			<dd>optionally specifies the number of region-specs
		       affected by operator-name (default value is 1).
<dt>args
			<dd>denotes optional string arguments(s) required by
		       some operators (e.g., "filter-til").
</dl>
	An example operator is "flip-til", and here's its show-commands
	info:
<pre>
	"flip-til"               ^A-~
	  or    "~"
	  (operator:  exchange upper and lowercase on characters in the
	  region) (may follow global command)
</pre><p>
	A salient point to note within the help string is the "operator"
	keyword, which unambiguously identifies the purpose of this command.
	Given the above information, we can write a macro to flip the case
	of the current paragraph.
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;flippara</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">up-paragraph</font></strong>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;move&nbsp;to&nbsp;beginning&nbsp;of&nbsp;para</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">flip-til</font></strong>&nbsp;<strong><font color="#000080">down-paragraph</font></strong>&nbsp;<font color="#800000">;&nbsp;flip&nbsp;case&nbsp;of&nbsp;entire&nbsp;para</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
	One might be tempted to bind this macro to a key using this syntax:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;flippara&nbsp;<strong><font color="#000080">g</font></strong><br>
<!--atr2html}}--></p>
	and then attempt to use a numerical argument to control the number
	of affected paragraphs.  I.E., type "3g" to flip three paragraphs.
	But this actually invokes "flippara" three times in a row, which
	(due to the sequential up- and down-paragraph motions), flips the
	case of the _same_ paragraph three times.  However, we can workaround
	that obstacle with the use of an interactive variable:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;flippara</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%dflt</font>&nbsp;<strong><font color="#008080">1</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%quest</font>&nbsp;@<font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#800080">"Flip&nbsp;how&nbsp;many&nbsp;para&nbsp;["</font>&nbsp;<font color="#008080">%dflt</font>&nbsp;<font color="#800080">"]?&nbsp;"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;sequal</font>&nbsp;<font color="#008080">%quest</font>&nbsp;<font color="#800080">""</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%quest</font>&nbsp;<font color="#008080">%dflt</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">up-paragraph</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008080">%quest</font>&nbsp;<strong><font color="#000080">flip-til</font></strong>&nbsp;<strong><font color="#000080">down-paragraph</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
<h2 id="debuggingmacros-id"><a name="debuggingmacros">Debugging macros</a></h2>
<p>
	vile's popup-msgs mode pops up the [Messages] buffer to show text
	written to the message line.  Closing the [Messages] buffer window
	clears its content until the next message is written.  This mode is
	most useful when debugging macros, since many messages may appear,
	each overwriting a previous one.
<p>
	Let's use this macro fragment for illustration:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;greater</font>&nbsp;<font color="#008080">$blines</font>&nbsp;<strong><font color="#008080">0</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;buffer&nbsp;has&nbsp;at&nbsp;least&nbsp;one&nbsp;line&nbsp;of&nbsp;data,&nbsp;proceed</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~else</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;this&nbsp;is&nbsp;unexpected!</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
<!--atr2html}}--></p>
	Suppose the macro is taking the unexpected code path in one of
	several buffers, but you don't know which.  To trace the path,
	modify the macro like so:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;greater</font>&nbsp;<font color="#008080">$blines</font>&nbsp;<strong><font color="#008080">0</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;buffer&nbsp;has&nbsp;at&nbsp;least&nbsp;one&nbsp;line&nbsp;of&nbsp;data,&nbsp;proceed</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~else</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;this&nbsp;is&nbsp;unexpected!</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%msg</font>&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#800080">"Error:&nbsp;Buffer&nbsp;"</font>&nbsp;<font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">$cbufname</font>&nbsp;<font color="#800080">"&nbsp;empty"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#008080">%msg</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
<!--atr2html}}--></p>
	Next, enable popup-msgs (i.e., set popup-msgs) and then start the
	macro.  When the "write-message" command is executed, the
	[Messages] buffer pops up and displays the string written by the
	unexpected code path.
<p>
	Disable popup-msgs using this command:
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;:<strong><font color="#000080">set</font></strong>&nbsp;<strong><font color="#000080">nopopup-msgs</font></strong><br>
<!--atr2html}}--></p>

<h2 id="example-id"><a name="example">Example startup file</a></h2>
<p>
	The startup file included below illustrates several of the language
	constructs described in this document.  This example is crafted for
	the win32 environment, but its syntax and usage are applicable to
	any host OS supported by vile.
<!--{{atr2html--><p style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;<strong><font color="#000080">ai</font></strong>&nbsp;<strong><font color="#000080">aw</font></strong>&nbsp;<strong><font color="#000080">ts</font></strong><strong><font color="#800000">=</font></strong><strong><font color="#008080">4</font></strong>&nbsp;<strong><font color="#000080">sw</font></strong><strong><font color="#800000">=</font></strong><strong><font color="#008080">4</font></strong>&nbsp;<strong><font color="#000080">flash</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;<strong><font color="#000080">next-window</font></strong>&nbsp;<font color="#800080">^N</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;<strong><font color="#000080">previous-window</font></strong>&nbsp;<font color="#800080">^P</font><br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;sequal</font>&nbsp;<font color="#008080">$progname</font>&nbsp;<font color="#800080">"winvile"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set-variable</font></strong>&nbsp;<font color="#008080">$font</font>&nbsp;<font color="#800080">"r_ansi,8"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;equal</font>&nbsp;<strong><font color="#008080">0</font></strong>&nbsp;<font color="#008080">&amp;sindex</font>&nbsp;<font color="#008080">&amp;lower</font>&nbsp;<font color="#008080">$shell</font>&nbsp;<font color="#800080">"command.com"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;w32pipes<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~else</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;now32pipes<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;not</font>&nbsp;<font color="#008080">&amp;equal</font>&nbsp;<strong><font color="#008080">0</font></strong>&nbsp;<font color="#008080">&amp;sindex</font>&nbsp;<font color="#008080">$cfgopts</font>&nbsp;<font color="#800080">"perl"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">perl</font></strong>&nbsp;<font color="#800080">"use&nbsp;hgrep"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">perl</font></strong>&nbsp;<font color="#800080">"use&nbsp;dirlist"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;not</font>&nbsp;<font color="#008080">&amp;equal</font>&nbsp;<strong><font color="#008080">0</font></strong>&nbsp;<font color="#008080">&amp;sindex</font>&nbsp;<font color="#008080">$cfgopts</font>&nbsp;<font color="#800080">"oleauto"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">set</font></strong>&nbsp;redirect-keys<strong><font color="#800000">=</font></strong><font color="#008080">&amp;cat</font>&nbsp;<font color="#008080">&amp;global</font>&nbsp;redirect-keys&nbsp;<font color="#800080">",MULTIPLY:A:S"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;modify&nbsp;^A-i&nbsp;and&nbsp;^A-o&nbsp;so&nbsp;that&nbsp;they&nbsp;don't&nbsp;wrap&nbsp;inserted&nbsp;text.</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;save-wrap-state</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%wm</font><strong><font color="#800000">=</font></strong><font color="#008080">$wrapmargin</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setv</font></strong>&nbsp;<font color="#008080">%ww</font><strong><font color="#800000">=</font></strong><font color="#008080">$wrapwords</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setl</font></strong>&nbsp;<strong><font color="#000080">nowrapwords</font></strong>&nbsp;<strong><font color="#000080">wm</font></strong><strong><font color="#800000">=</font></strong><strong><font color="#008080">0</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;restore-wrap-state</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setl</font></strong>&nbsp;<strong><font color="#000080">wrapmargin</font></strong><strong><font color="#800000">=</font></strong><font color="#008080">%wm</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">%ww</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setl</font></strong>&nbsp;<strong><font color="#000080">wrapwords</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~else</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">setl</font></strong>&nbsp;<strong><font color="#000080">nowrapwords</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;insert-chars-noai-nowrap</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;save-wrap-state<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">insert-chars-no-autoindent</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;restore-wrap-state<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;insert-chars-noai-nowrap&nbsp;<font color="#800080">^A-i</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;open-line-below-noai-nowrap</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;save-wrap-state<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">open-line-below-no-autoindent</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;restore-wrap-state<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">bind-key</font></strong>&nbsp;open-line-below-noai-nowrap&nbsp;<font color="#800080">^A-o</font><br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;Rather&nbsp;than&nbsp;composing&nbsp;documents&nbsp;in&nbsp;a&nbsp;word&nbsp;processor,&nbsp;it's&nbsp;much</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;more&nbsp;efficient&nbsp;to&nbsp;use&nbsp;vile.&nbsp;&nbsp;But&nbsp;pasting&nbsp;vile-formatted&nbsp;text&nbsp;into,</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;say,&nbsp;MS&nbsp;Word&nbsp;is&nbsp;a&nbsp;pain&nbsp;in&nbsp;the&nbsp;neck&nbsp;because&nbsp;each&nbsp;paragraph&nbsp;needs</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;to&nbsp;be&nbsp;reformatted.&nbsp;&nbsp;Example:</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;vile&nbsp;txt</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;========</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;para&nbsp;1&nbsp;line1,</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;line&nbsp;2,</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;line&nbsp;3,</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;line&nbsp;4</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;para&nbsp;2&nbsp;line&nbsp;1,</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;line&nbsp;2,</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;line&nbsp;3,</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;line&nbsp;4</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;If&nbsp;"vile&nbsp;txt"&nbsp;is&nbsp;copied&nbsp;and&nbsp;pasted&nbsp;into&nbsp;Word,&nbsp;it&nbsp;looks&nbsp;awful&nbsp;because</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;the&nbsp;lines&nbsp;of&nbsp;the&nbsp;paragraphs&nbsp;do&nbsp;not&nbsp;flow&nbsp;together&nbsp;(i.e.,&nbsp;the&nbsp;new&nbsp;lines</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;terminating&nbsp;each&nbsp;vile&nbsp;paragraph&nbsp;serve&nbsp;as&nbsp;a&nbsp;"hard"&nbsp;paragraph&nbsp;break).</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;'Twould&nbsp;be&nbsp;nice&nbsp;if&nbsp;vile&nbsp;could&nbsp;join&nbsp;each&nbsp;paragraph&nbsp;so&nbsp;that&nbsp;"vile&nbsp;txt"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;above&nbsp;looked&nbsp;like&nbsp;this:</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;vile&nbsp;txt</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;========</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;para&nbsp;1&nbsp;line1,&nbsp;line&nbsp;2,&nbsp;line&nbsp;3,&nbsp;line&nbsp;4</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;para&nbsp;2&nbsp;line&nbsp;1,&nbsp;line&nbsp;2,&nbsp;line&nbsp;3,&nbsp;line&nbsp;4</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;Then,&nbsp;when&nbsp;this&nbsp;version&nbsp;is&nbsp;pasted&nbsp;into&nbsp;Word,&nbsp;all&nbsp;paragraphs&nbsp;are</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800000">;automatically&nbsp;reformatted.&nbsp;&nbsp;Here's&nbsp;a&nbsp;macro&nbsp;that&nbsp;adds&nbsp;this&nbsp;feature:</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">store-procedure</font></strong><font color="#800080">&nbsp;join-all-para</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">goto-beginning-of-file</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">write-message</font></strong>&nbsp;<font color="#800080">"[joining&nbsp;all&nbsp;paragraphs...]"</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~while</font>&nbsp;true<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~force</font>&nbsp;<strong><font color="#000080">join-lines-til</font></strong>&nbsp;<strong><font color="#000080">down-paragraph</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;not</font>&nbsp;<font color="#008080">$status</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~break</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<strong><font color="#000080">goto-bol</font></strong><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~force</font>&nbsp;<strong><font color="#008080">2</font></strong>&nbsp;<strong><font color="#000080">down-line</font></strong>&nbsp;<font color="#800000">;skip&nbsp;to&nbsp;next&nbsp;para</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~if</font>&nbsp;<font color="#008080">&amp;not</font>&nbsp;<font color="#008080">$status</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~break</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endif</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endwhile</font><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#008000">~endm</font><br>
<!--atr2html}}--></p>
<h2 id="credits-id"><a name="credits">Credits</a></h2>
<p>
	This document, and the macro language it describes, owes
	a debt of thanks to Dan Lawrence and his MicroEMACS text
	editor.  Many of the features described herein first appeared
	in this form in MicroEMACS.

</body>