Customisation
*************

This chapter talks about various topics relevant to adapting the behavior of af in minor ways.  All kinds of customisation affect only the particular af session that you do them in.  They are completely lost when you kill af, and have no effect on other af sessions you may run later.  The only way an af session can affect anything outside of it is by writing a file; in particular, the only way to make a customisation `permanent' is to put something in your .afrc file to do the customisation in each session.  (see Startup Files).

You can easily customise af in several different ways:

Setting Variables
     Af has many configuration variables, which you can set to alter the behaviour of certain commands.  (see Variables).

Keyboard Macros
     Keyboard macros allow you to combine af commands to create new ones. Keyboard macros are not very powerful, but they are a very simple way to add new commands to af.

Binding Keys
     You can change which commands are bound to which keys, so you can change the effect of a keypress.

Afl
     You will also eventually be able to write powerful functions in af's extension language afl.  This is not yet supported.

The Startup File, ~/.afrc
=========================

When af is started, it normally loads an afl program from the file .afrc in your home directory.  We call this file your Startup file because it is read when you start af.  You can use the command line switches -n and -l to tell af whether to load a startup file, and which one (see Entering Af).

Your site may also have a global startup file; this is named afrc.afl, if it exists.  The af distribution contains no such library; your site may create one for local customisations.  If this library exists, it is loaded whenever you start af; and then your own startup file, if any, is loaded.

By far the simplest way to create a startup file is for af to write one for you.  The command M-x write-configuration will prompt you for a file name (defaulting to ~/.afrc), and then write an afl program into that file.  When you run that program (by loading the file), it will recreate any changed variables or key bindings, or any new keymaps or named keyboard macros that were in existence when you ran M-x write-configuration.

You can use M-x write-configuration to create a startup file, and then modify that file with an editor; it is a text file.  This is also a good way to become familiar with afl.

Emulation
=========

Af can be programmed to emulate (more or less) several other mail readers.  The commands to do this are stored in several afl libraries (see Afl).  Note that the only way to turn an emulation off once you've loaded it is to exit af and start again.

The emulations aren't in any way intended to be true emulations of the mail readers.  The intent is to let people who are already used to some other mail reader get started with af quickly, by making most of the common keys do what they expect.

To set up af to work like another mail reader there must be an emulation library for the mail reader.  To load the library for (as an example) elm, type type M-x load-library RET elm RET.

The available emulations are:

elm
     Reconfigures af to do a fairly close emulation of elm.

mush
     Not a perfect emulation by any means, but enough to get people used to mush started.

pine
     A close enough emulation to satisfy advanced PINE users.  Doesn't hold your hand nearly enough for many of PINE's target users.

ream
     Not too far from the target, anyone who's used to using ream will probably find this emulation helpful.

vm
     Silly though it seems, the VM emulator is quite different from af's normal personality.  If you've been using the VM package under Emacs to read mail, then this library may help.

Variables
=========

Af presents two interfaces to its variables:  The underlying system which is used by Afl (see Afl), or a simpler system which af uses to allow users to handle configuration variables.

A variable is a symbol which has a value.  The symbol's name is also called the name of the variable.  Variable names usually consist of words separated by hyphens.  Af's configuration variables can each hold a specified kind of value.  Sometimes this is a simple type such as a number, or a string, but sometimes a variable will require a more complex value, such as the formats for the screen display.

To examine the value of a single configuration variable, use C-h v (describe-variable), which reads a variable name using the minibuffer, with completion.  It displays both the value of and the documentation for the variable.  If you want to see the values of all the configuration variables, then use C-h C-v (list-variables), which lists all the configuration variables and their values to typeout.

The most convenient way to set a specific variable is with C-x a (set-variable).  This reads the variable name with the minibuffer (with completion), and then reads a new value using the minibuffer a second time.  For example,

     C-x a ask-cc RET true RET

sets ask-cc to true.

Whenever you use C-x a, the value of the variable will be checked when you enter it.  You can't break af by changing variables, although you can make it behave very strangely if you set some variables to odd values.

When a variable's description says that it contains a list of items, then C-x a will expect the items in the list to be separated by colons.  If you set the variable by afl of course, then you would use a list object as the value (see Afl).  For example

     C-x a viewable-charsets RET us-ascii:iso-8859-1 RET

set the value of viewable-charsets to the list containing us-ascii and iso-8859-1.

It is usually worth using C-h v (describe-variable) to check the on-line help for a variable you intend to change; often the description is far more detailed than is given in this manual.

Keyboard Macros
===============

A keyboard macro is a command defined by the user to stand for another sequence of keys.  For example, if you discover that you are about to type C-t t a RET C-n forty times, you can speed your work by defining a keyboard macro to do C-t t a RET C-n and calling it with a repeat count of forty.

C-x (
     Start defining a keyboard macro (start-kbd-macro).

C-x )
     End the definition of a keyboard macro (end-kbd-macro).

C-x e
     Execute the most recent keyboard macro (call-last-kbd-macro).

C-u C-x (
     Re-execute last keyboard macro, then add more keys to its definition.

C-x q
     When this point is reached during macro execution, ask for confirmation (kbd-macro-query).

M-x name-last-kbd-macro
     Give a command name (for the duration of the session) to the most recently defined keyboard macro.

Keyboard macros differ from ordinary af commands in that they are written in the af command language rather than in C or afl.  This makes it easier for the novice to write them, and makes them more convenient as temporary hacks.  However, the af command language is not powerful enough as a programming language to be useful for writing anything intelligent or general (Neither is afl yet, but that will change).

You define a keyboard macro while executing the commands which are the definition.  Put differently, as you define a keyboard macro, the definition is being executed for the first time.  This way, you can see what the effects of your commands are, so that you don't have to figure them out in your head.  When you are finished, the keyboard macro is defined and also has been, in effect, executed once.  You can then do the whole thing over again by invoking the macro.

Basic Use
---------

To start defining a keyboard macro, type the C-x ( command (start-kbd-macro).  From then on, your keys continue to be executed, but also become part of the definition of the macro. Def appears in the mode line to remind you of what is going on. When you are finished, the C-x ) command (end-kbd-macro) terminates the definition (without becoming part of it!).  For example,

     C-x ( M-+ +foobar RET C-n C-x )

defines a macro to save the current message to the folder +foobar, and then move down a line.

The macro thus defined can be invoked again with the C-x e command (call-last-kbd-macro), which may be given a repeat count as a numeric argument to execute the macro many times.  C-x ) can also be given a repeat count as an argument, in which case it repeats the macro that many times right after defining it, but defining the macro counts as the first repetition (since it is executed as you define it). Therefore, giving C-x ) an argument of 4 executes the macro immediately 3 additional times.  An argument of zero to C-x e or C-x ) means repeat the macro indefinitely (until it gets an error or you type C-g).

If you wish to repeat an operation at regularly spaced places in the text, define a macro and include as part of the macro the commands to move to the next place you want to use it.  For example, if you want to change each line, you should position point at the start of a line, and define a macro to change that line and leave point at the start of the next line.  Then repeating the macro will operate on successive lines.

After you have terminated the definition of a keyboard macro, you can add to the end of its definition by typing C-u C-x (.  This is equivalent to plain C-x ( followed by retyping the whole definition so far.  As a consequence it re-executes the macro as previously defined.

Naming Keyboard Macros
----------------------

If you wish to save a keyboard macro for longer than until you define the next one, you must give it a name using M-x name-last-kbd-macro. This reads a name as an argument using the minibuffer and defines that name to execute the macro.  Defining the macro in this way makes it a valid command name for calling with M-x or for binding a key to with global-set-key (see Keymaps).  If you specify a name that has a prior definition other than another keyboard macro, an error message is printed and nothing is changed.

Executing Macros with Variations
--------------------------------

Using C-x q (kbd-macro-query), you can make a macro ask you each time around whether to make a change.  While defining the macro, type C-x q at the point where you want the query to occur. During macro definition, the C-x q does nothing, but when you run the macro later, C-x q asks you interactively whether to continue.

The valid responses are SPC to continue, and RET to skip the rest of this repetition of the macro and start right away with the next repetition.  ESC means to skip the rest of this repetition and cancel further repetitions.  C-l redraws the screen and asks you again for a character to say what to do.

Customising Key Bindings
========================

This section describes key bindings which map keys to commands, and the keymaps which record key bindings.  It also explains how to customise key bindings.

Keymaps
-------

The bindings between key sequences and command functions are recorded in data structures called keymaps.  Af has many of these, each used on particular occasions.

Recall that a key sequence (key, for short) is a sequence of key presses that have a meaning as a unit.  A key sequence gets its meaning from its binding, which says what command it runs.  The function of keymaps is to record these bindings.

The global keymap is the most important keymap because it is always in effect.  The global keymap defines keys which are common to most or all of the major modes.  Each major mode has its own keymap which overrides the global definitions of some keys.

For example, the key C-n move to the next line because the global keymap binds it to the command next-line.  Commands to rebind keys, such as M-x global-set-key, actually work by storing the new binding in the proper place in the keymaps.  See Rebinding.

Meta characters work differently; af translates each Meta character into a pair of characters starting with ESC.  When you type the character M-r in a key sequence, af replaces it with ESC r.  A meta key comes in as a single key press, but becomes two events for purposes of key bindings.  The reason for this is historical; most older terminals didn't support a meta key.

A keymap records definitions for single characters.  Interpreting a key sequence of multiple characters involves a chain of keymaps.  The first keymap gives a definition for the first character; this definition is another keymap, which is used to look up the second character in the sequence, and so on.

You can find out what keymaps are defined in af with the command M-x list-keymaps.  This lists the keymaps, with the prefix keys they handle, to typeout.

Prefix Keymaps
--------------

A prefix key such as C-x or ESC has its own keymap, which holds the definition for the character that immediately follows that prefix.

The definition of a prefix key is usually the keymap to use for looking up the following event.  Thus, the binding of C-x is the keymap control-x-prefix, the keymap for C-x commands.  The definitions of C-c, C-t, C-x, C-h and ESC as prefix keys appear in the global map, so these prefix keys are always available.

The C-c prefix has been assigned as a "user prefix".  By default, nothing will be bound in the C-c keymap; it is reserved for your own key bindings.  There is a separate C-c prefix keymap for each of af's major modes.  See Local Keymaps.

Local Keymaps
-------------

So far we have explained the ins and outs of the global map.  Major modes customise af by providing their own key bindings in local keymaps.  For example, minibuffer mode overrides the printable characters to bind them to the command self-insert-command, so that the characters insert themselves into the minibuffer at point.

A local keymap can locally redefine a key as a prefix key by defining it as a prefix keymap.  If the key is also defined globally as a prefix, then its local and global definitions (both keymaps) effectively combine: both of them are used to look up the character that follows the prefix key.  Thus, if the mode's local keymap defines C-x as another keymap, and that keymap defines C-z as a command, this provides a local meaning for C-x C-z.  This does not affect other sequences that start with C-x; if those sequences don't have their own local bindings, their global bindings remain in effect.

Another way to think of this is that af handles a multi-event key sequence by looking in several keymaps, one by one, for a binding of the whole key sequence.  First it checks the minor mode keymaps for minor modes that are enabled, then it checks the major mode's keymap, and then it checks the global keymap.  This is not precisely how key lookup works, but it's good enough for understanding ordinary circumstances.

Designing af keymaps is made more complicated because several commands will only work in one or two of the major modes.  You should be careful using global bindings; local bindings will usually achieve what you want, and are less confusing to work with.

Changing Key Bindings Interactively
-----------------------------------

The way to redefine an af key is to change its entry in a keymap. You can change the global keymap, in which case the change is effective in all major modes (except those that have their own overriding local definitions for the same key).  Or you can change the current buffer's local map, which affects all buffers using the same major mode.

M-x global-set-key RET KEY CMD RET
     Define KEY globally to run CMD.

M-x global-unset-key RET KEY
     Make KEY undefined in the global map.

M-x local-set-key RET KEY CMD RET
     Define KEY locally (in the major mode now in effect) to run CMD.

M-x local-unset-key RET KEY
     Make KEY undefined locally (in the major mode now in effect).

M-x typeout-set-key RET KEY CMD RET
     Define KEY to run CMD in the typeout keymap.

M-x typeout-unset-key RET KEY
     Make KEY undefined in the typeout map.

M-x minibuffer-set-key RET KEY CMD RET
     Define KEY to run CMD in the minibuffer keymap.

M-x minibuffer-unset-key RET KEY
     Make KEY undefined in the minibuffer map.

M-x make-keymap RET MAP RET
     Create a new keymap MAP, which you can then use to add your own prefix keys.

For example, suppose you like to execute commands in a subshell, instead of suspending af and executing commands in your login shell.  Normally, C-z is bound to the function suspend-af, but you can change C-z to invoke a subshell by binding it to shell as follows:

     M-x global-set-key RET C-z shell RET

global-set-key reads the command name after the key.   After you press the key, a message like this appears so that you can confirm that you are binding the key you want:

     Set key C-z to command:

You can rebind a key that contains more than one character in the same way.  Af keeps reading the key to rebind until it is a complete key (that is, not a prefix key).  Thus, if you type C-f for KEY, that's the end; the minibuffer is entered immediately to read CMD. But if you type C-x, another character is read; if that is 4, another character is read, and so on.  For example,

     M-x global-set-key RET C-x 4 $ scroll-other-window RET

redefines C-x 4 $ to run the command scroll-other-window.

The commands typeout-set-key and minibuffer-set-key are a convenience; they bind keys in the typeout or minibuffer keymaps rather than the global or local maps.

You can remove the global definition of a key with global-unset-key.  This makes the key undefined; if you type it, af will just beep.  Similarly, local-unset-key makes a key undefined in the current major mode keymap, which makes the global definition (or lack of one) come back into effect in that major mode.

If you have redefined (or undefined) a key and you subsequently wish to retract the change, undefining the key will not do the job---you need to redefine the key with its standard definition.  The documentation of keys in this manual also lists their command names.

If you want to define a new prefix key, you will need to create a new keymap to handle the prefix key.  To do this, use the command M-x make-keymap, which will prompt you for the name of the keymap to create.  If you specify a name that already has a definition an error message is printed and nothing is changed.

There are two variables which can be important when you are binding keys.  The variable meta-prefix-char names the character which is used as a prefix when you type a metacharacter at the keyboard.  If you change the binding of ESC, then you should change the value of meta-prefix-char to reflect this.  Similarly, the variable quit-char names the character which is used to quit from confirm prompts, and similar; so it should probably reflect the usual binding of keyboard-quit in the keymaps.

Afl
***

Afl is the af extension language, a simple programming language which allows you to write files containing af commands.  Afl is similar to the Lisp programming language, so Lisp programmers should find afl easy to learn.  Afl should be simple enough that it is easy for other programmers to learn.

Afl is designed for programmers to use, although once a programmer has written an afl program anyone should be able to use that program.

Basic Afl Concepts
==================

Afl programs are made up of one or more afl objects; pieces of data used and manipulated by afl programs.  For our purposes, a type or data type is a set of possible objects.

When you run an afl program, the afl reader is called to read the textual representations of the afl objects in the program, and convert them to actual afl objects.  If you try to display an object, the afl printer is called to generate a printed representation of the object.

The evaluation of expressions in afl is performed by the afl interpreter; a program that receives an afl object as input and computes its value as an expression.  How it does this depends on the data type of the object.  An afl object that is intended for evaluation is called an expression or a form.

The most useful type of afl object to evaluate is lists.  When you evaluate an afl list, the head of the list is evaluated as a function, and then the remaining items in the list are passed as arguments to the function.  Arguments are always evaluated in left-to-right order, although there are a few functions, known as special forms, which may not evaluate all of their arguments.  These functions' handling of arguments will be explained in the function's description.

Afl Data Types
==============

Each data type in afl has a read syntax and a printed representation.  The read syntax is the way the data type should be written in an afl program.  The printed representation is the way that the data type will be displayed by the afl printer.  These may be the same or different.

Comments
--------

A comment is text that is written in a program only for the sake of humans that read the program, and that has no effect on the meaning of the program.  In afl, a semicolon (;) starts a comment if it is not within a string or character constant.  The comment continues to the end of line.  The afl reader discards comments; they do not become part of the afl objects which represent the program.

Special Constants
-----------------

In afl, the symbol nil is overloaded with three meanings: it is a symbol with the name nil; it is the logical truth value FALSE; and it is the empty list---the list of zero elements. When used as a variable, nil always has the value nil.

As far as the afl reader is concerned, () and nil are identical: they stand for the same object, the symbol nil.  The different ways of writing the symbol are intended entirely for human readers.  After the afl reader has read either () or nil, there is no way to determine which representation was actually written by the programmer.

In contexts where a truth value is expected, any non-nil value is considered to be TRUE.  However, t is the preferred way to represent the truth value TRUE.  When you need to choose a value which represents TRUE, and there is no other basis for choosing, use t.  The symbol t always has value t.

For convenience, the constant a is defined to be the value ask or accept in af's tristate configuration variables. This is the preferred way to set, for example, the variable copy-on-reply to ask.

In afl, nil, t and a, are special symbols that always evaluate to themselves.  This is so that you do not need to quote them to use them as constants in a program.  An attempt to change their values results in an error.

Lists
-----

A list of objects of any data type (including lists).  A list is read or printed as a set of objects enclosed in parentheses; for example (a b c), or (a b (c d e) f).

Lists are evaluated by evaluating the symbol at their head as a function. The remaining objects are evaluated (unless the function is a special form), and passed as arguments to the function.

Numbers
-------

Af only supports integer numbers.  A number is read or printed as an optional sign, followed by one or more digits; for example 42, or -999.

There is a system-defined limit to the maximum value of a number, usually 32 bits.  Larger values will be truncated to fit within these bounds, which will leave them with unexpected values.

Numbers always evaluate to themselves.

Characters
----------

In afl, characters are interchangeable with numbers, and are always printed as a number.  They can be read either as a number, or as a question mark followed by the character; for example ?a.  If the character is not a normal alphanumeric one, then it is often necessary to prefix it with a backslash '\' to make sure it is treated as a character.  If the character is '\' then you need a second '\' to quote it; for example. ?\\.

You can write the characters Control-g, backspace, tab, newline, vertical tab, formfeed, return, and escape as ?\a, ?\b, ?\t, ?\n, ?\v, ?\f, ?\r, and ?\e, respectively.

Rather than quoting a control character with \, another read syntax may be used.  If a character is a backslash followed by a caret and another non-control character, then it represents the control character.  For example, ?\^I is read syntax for the character C-i.  You may also use C- rather than ^, so \C-i is also read syntax for C-i.

A meta character is one that has the top bit set, and can be typed with a meta key on some keyboards.  Read syntax for metacharacters is ?\M- followed by the character.  This may be combined with control character read sequence, hence ?\C-\M-i is read syntax for C-M-i.

Finally, the most general read syntax for characters is a question mark followed by a backslash and the numeric value of the character in octal (up to three digits are allowed).  So ?\001 is read syntax for the character C-a.

An invalid control or meta character sequence (such as ?\C-\^a or ?\C-1) will be flagged as an error by the afl reader.

As with numbers, there is a system-defined limit to the maximum value of a character, usually 8 bits.  Larger values will be truncated to fit within these bounds, which will leave them with unexpected values.

Characters always evaluate to themselves.

Strings
-------

The read syntax and printed representation of afl strings is the string enclosed in double quotes; for example "A string".  All the special ways of writing characters can be used within strings.  In addition, a backslash followed by a newline is ignored within a string, so strings can be broken to fit on the screen better; for example:

     "This string is broken here \
     by a \\\\n sequence"

would be read as This string is broken here by a \\n sequence.

Strings always evaluate to themselves.

Symbols
-------

A symbol name can contain any characters you require.  Any use of the characters '"();?.,\ \t\n should be quoted with a \ character.  If the symbol name looks like a number, then it can be prefixed with a \ to force it to be treated as a symbol.  Note that unlike its use in strings, the \ simply quotes the next character in the symbol name.

Evaluating a symbol works differently according to the context in which the symbol is being evaluated.  An afl symbol can store a variable or a function, or both.  The afl evaluator will usually look up the value of the symbol as a variable, but will use the value as a function if the symbol is at the head of a list.

Afl Primitive Functions
=======================

Afl has several primitive functions, which are predefined in af, and can be called from your afl programs.  In addition, an afl program can call any af command as a function; af commands are simply functions that have made provision for interactive use.

The appearance of the keyword &optional in the parameter list of a function indicates that the arguments for subsequent parameters may be omitted (omitted parameters default to nil).  Do not write &optional when you call the function.

The keyword &rest (which will always be followed by a single parameter) indicates that any number of arguments can follow.  The value of the single following parameter will be a list of all these arguments. Do not write &rest when you call the function.

Quoting Forms
-------------

(quote FORM)
     Quote FORM, protecting it from evaluation.

Sometimes, you may not want a form to be evaluated, for example the name of a symbol to assign a value to with set.  You can prevent a form from being evaluated by using the special form quote.  So (quote list-functions) expands to the symbol list-functions.

Because quote is used so often, there is a special notation for it.  Writing 'FORM is equivalent to writing (quote FORM).  So 'list-functions is equivalent to the example above.

Controlling Program Flow
------------------------

cindex comparing afl objects

(if CONDITION THEN &optional ELSE)
     Execute THEN if CONDITION evaluates to non-nil, ELSE otherwise.

(progn &rest FORMS)
     Evaluates FORMS from left to right, returning the value of the last form evaluated.

(equal OBJECT1 OBJECT2)
     Returns t if OBJECT1 and OBJECT2 have the same afl type and contents, nil otherwise.

(and &rest CONDITIONS)
     Evaluates CONDITIONS until one returns nil. Returns the value of the last condition evaluated.

(or &rest CONDITIONS)
     Evaluates CONDITIONS until one returns non-nil. Returns the value of the last condition evaluated.

(not CONDITION)
     Returns t if CONDITION evaluates to nil, nil otherwise.

To evaluate code only if a condition is true, use (if CONDITION TRUE FALSE).  This evaluates CONDITION, and then evaluates TRUE if CONDITION returned non-nil, or FALSE (if specified) otherwise.

You can use progn to group a set of forms, for example to use in an if.  progn evaluates its arguments from left-to-right, and returns the value returned by the last argument.

You can compare the value of two afl objects with equal.  This will return t if the two objects have the same afl type and contents, or nil otherwise.

To combine one or more logical expressions, you can use and, or, and not.  The special form and evaluates its arguments from left to right until one of them returns nil, and then returns nil; the remaining arguments are never evaluated. If no argument returns nil, then the value returned by the last argument evaluated is returned.

The special form or is more-or-less the opposite of and; it evaluates its arguments from left to right until one of them returns non-nil, and then returns the value the argument returned; the remaining forms are never evaluated.  If no argument evaluates to non-nil, then or returns nil.

To reverse a test use not.  This returns t if the argument evaluates to nil, or nil otherwise.

Configuring Af From Afl
-----------------------

(set SYMBOL VALUE)
     Set SYMBOL to contain VALUE.

(setq SYMBOL VALUE)
     Equivalent to (set 'SYMBOL VALUE).

(define-key KEYMAP "KEY" VALUE)
     Bind key KEY in keymap KEYMAP to VALUE.

(define-kbd-macro MACRO "KEYS")
     Define a keyboard macro MACRO to execute KEYS.

To set an af configuration variable, use the function set.  This sets the variable to the value supplied.  The value will be checked to make sure that it is a valid value for the variable.

Since set is a function you will need to quote the symbol to be set.  For convenience, the special form setq is equivalent to set, but does not evaluate the object which is to be set. So (setq ask-cc t) is equivalent to (set 'ask-cc t).

To bind a key in a keymap use (define-key KEYMAP "KEY" OBJECT).  This binds KEY in keymap KEYMAP to OBJECT, which must be a command, a keymap, a keyboard macro, or nil.  To find the name of the keymap you want to bind the key in use the list-keymaps command.  Since define-key is a function you will need to quote KEYMAP and OBJECT.

To define a new keyboard macro, or redefine an existing one, use the function (define-kbd-macro MACRO "KEYS").  This defines MACRO to execute KEYS.  Since define-kbd-macro is a function you will need to quote MACRO.

Interacting With the Environment
--------------------------------

(message &rest FORMS)
     Display the print format of FORMS in the echo area.

(error &rest FORMS)
     Beep and display FORMS in the echo area.

(getenv "NAME")
     Return the value of the environment variable NAME, or nil if name is not set in the environment.

The functions message and error display messages or error messages in the echo area.  While message returns the forms that it printed, error returns an error condition, which will halt the] execution of the afl program.

You can extract values from the environment by using (getenv "VARIABLE"), which looks up and returns the definition of VARIABLE in the environment.  This can be very useful for terminal-dependent customisation of af.

Running Afl Programs
====================

M-x load-file RET FILE RET
     Load FILE as an afl program.

M-x load-library RET LIB RET
     Search for and load a file LIB or LIB.afl.

Once you have created a file containing af commands (known as an afl program or afl library, you can load it.  When you load an afl program, the file is opened, and its contents are passed to the afl reader.  Once all the file has been read and evaluated, then the file is closed.  If any form in the file is invalid, or produces an error, then the afl reader will abort, and the file will be closed.

The simplest way to load an afl program is to use the the command load-file, which loads a named file.  You must specify the full name of the file.

The load-library command will search for an afl program in a set of directories defined by the load-path variable.  It checks for the file name with .afl appended, as well as the filename alone.

If you want to modify where af looks for library files, there are two ways to do so.  You can set the environment variable AFLOADPATH to a colon-separated list of directories to search; or you can set the configuration variable load-path to the same value.  For example:

     (setq load-path '("/usr/lib/af" "/usr/local/lib/af"))

would make af look for afl libraries in the directories /usr/lib/af and /usr/local/lib/af.

Examples of Afl Code
====================

Here are a few examples of afl code, with brief explanations.

Load the library ansi.afl if you are using an ANSI terminal (under one of several common names):

     (if (or (equal (getenv "TERM") "ansi")
     	(equal (getenv "TERM") "xterm")
     	(equal (getenv "TERM") "vt100"))
         (load-library "ansi"))

Set the viewable-charsets variable to allow displaying the iso-8859-1 character set if running on an xterm:

     (if (equal (getenv "TERM") "xterm")
         (setq viewable-charsets '("iso-8859-1" "us-ascii")))

Complain if the user isn't running on an xterm:

     (if (not (equal (getenv "TERM") "xterm"))
         (error "Must be running on an xterm"))

Define a keyboard macro to move to the next message from typeout:

     (define-kbd-macro 'typeout-next-message "\C-g\C-n\r")

Bind the above macro to the key M-n in the typeout maps:

     (define-key 'typeout-prefix-command "n" 'typeout-next-message)