MessageLineVariables(4)

NAME

@mn, @mna, @ml, @mc, @mx, @mxa - Message line input

SYNOPSIS

@mn
@mna

@ml[f][h] "prompt" ["default"] ["initial"] ["com-list"] ["buffer-name"]
@mc[f] prompt [valid-list]

@mx "command-line"
@mxa "command-line"

DESCRIPTION

The Message Line Variables provide a method to prompt the user for an input returning the data to the caller. The @mn variable cause MicroEmacs to input data from the user in the default way for that command's argument, i.e. the normal prompt with the normal history and completion etc. Similarly @mna causes MicroEmacs to input the current argument and any subsequent arguments in the default way.

The @ml variable can be used to get a string (or Line) of text from the user using the message-line in a very flexible way. The first optional flag f is a bitwise flag where each bit has the following meaning

0x01


The default value will be specified and this will be returned by default.

0x02


The initial value will be specified and this will be initial value given on the input line.

If no value is specified then default value is 0 and h can not be specified. The default value is returned when the user enters an empty string. If the initial string is specified the the input buffer will be initialized to the given string instead of and empty one.

The flag h specifies what type of data is to be entered, this specifies the history to be used and the semantics allowed, h can have the following values

0 For a general string input using the general history.
1 For an absolute file name, with completion and history.
2 For a MicroEmacs '99 buffer name, with completion and history.
3 For a MicroEmacs '99 command name, with completion and history.
4 For a file name, with completion and history.
5 For a search string, with history.
6 For a MicroEmacs '99 mode name, with completion and history.
7 For a MicroEmacs '99 variable name, with completion and history.
8 For a general string using no history.
9 For a user supplied completion list (com-list).
a For a user supplied completion list (buffer-name).

A default value of 0 is used if no value is specified. At first glance type 1 and 4 appear to be the same. They differ only when a non absolute file name is entered, such as "foobar". Type 1 will turn this into an absolute path, i.e. if the current directory is "/tmp" then it will return "/tmp/foobar". Type 4 however will return just "foobar", this is particularly useful with the &find(4) directive to then find the file "foobar".

When a value of 9 is used the argument com-list must be given which specifies a list of completion values in the form of a MicroEmacs list (see help on &lget(4) for further information on lists). The user may enter another value which is not in the list, which will be returned.

Alternatively a completion list may be given in the form of a buffer using a value of a. The argument buffer-name must be given to specify the buffer name from which to extract the completion list; each line of the buffer is taken as a completion value. This option is particularly useful for large completion lists as there is no size restrictions.

The @mc variable can be used to get a single character from the user using the message-line. The optional flag f is a bitwise flag where each bit has the following meaning

0x01 The valid-list specifies all valid letters.

The default value for f is 0. When @mc is used, the user is prompted, with the given prompt, for a single character. If a valid-list is specified then only a specified valid character or an error can be returned. For example, a yes/no prompt can be implemented by the following

!if &iseq @mc1 "Are you bored [y/n]? " "yYnN" "y" 
    save-buffers-exit-emacs 
!endif 

By using the &isequal(4) operator a return of "Y" or "y" will match with "y".

When the @mx variable is used MicroEmacs sets the system variable $result(5) to the input prompt, it will then execute the given command-line. If this command aborts then so does the calling command, if it succeeds then the input value is taken from the $result variable. Similarly @mxa causes MicroEmacs to get the current and any subsequent arguments in this way.

These variables are useful when trying to use existing commands in a different way, such as trying to provide a GUI to an existing command. See the delete-buffer example below.

EXAMPLE

The following example can be used to prompt the user to save any buffer changes, the use of @mna ensures the user will be prompted as usual regardless of the number of buffers changed:

save-some-buffers @mna 

The following example sets %language to a language supplied by the user from a given list, giving the current setting as a default

set-variable %languages "|American|British|French|Spanish|" 
set-variable %language "American" 

set-variable %language @ml19 "Language" %language %languages 

The following example is taken from diff-changes in tools.emf, it uses @mc to prompt the user to save the buffer before continuing:-

define-macro diff-changes 
    !if &seq $buffer-fname "" 
        ml-write "[Current buffer has no file name]" 
        !abort 
    !endif 
    !if &bmod "edit" 
        !if &iseq @mc1 "Save buffer first [y/n]? " "nNyY" "y" 
            save-buffer 
        !endif 
    !endif 
        . 
        . 

Note that the input is case insensitive. The following version would not work as the user may expect when the buffer has not been edited:

        . 
        . 
    !if &and &bmod "edit" &iseq @mc1 "Save buffer first [y/n]? " "nNyY" "y" 
        save-buffer 
        . 
        . 

Unlike C and other similar languages MicroEmacs macro language always evaluates both &and arguments. This means that the user will be prompted to save the buffer regardless of whether the buffer has been edited.

The @mx variables are useful when using existing commands in a new environment. For example, consider providing a GUI for the delete-buffer(2) command, when executed the calling GUI may not be aware that changes could be lost or a process may still be active. These variables can be used as a call back mechanism to handle this problem:

define-macro osd-delete-buffer-callback 
    !if &sin "Discard changes" $result 
        2 osd-xdialog "Delete Buffer" "  Dicard changes?  " 2 10 6 "&Yes" "&No" 
        set-variable $result &cond &equ $result 1 "y" "n" 
    !elif &sin "Kill active process" $result 
        2 osd-xdialog "Delete Buffer" "  Kill active process?  " 2 10 6 "&Yes" "&No" 
        set-variable $result &cond &equ $result 1 "y" "n" 
    !else 
        1000 ml-write &spr "[Unknown prompt %s]" $result 
        !abort 
    !endif 
!emacro 

define-macro osd-delete-buffer 
    . 
    . set #l0 to buffer name to be deleted 
    . 
    delete-buffer #l0 @mxa osd-delete-buffer-callback 
!emacro 

SEE ALSO

define-macro(2).

(c) Copyright JASSPA 1999
Last Modified: 1999/11/29
Generated On: 1999/12/01