# MessageLineVariables(4)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## 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] [help-string]
@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.

`0x04`

Auto-complete using the initial value, usually used with bit `0x02`.

`0x08`

Hide the input string, the characters in the current input string are all displayed as `'*'`s.

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 2009 buffer name, with completion and history.
`3` For a MicroEmacs 2009 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 2009 mode name, with completion and history.
`7` For a MicroEmacs 2009 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) function 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.

`0x02`

Quote the typed character, this allows keys such as '`C-g`' which is bound to the abort command to be entered.

`0x04`

A help-string is given which will be displayed if the user presses '`?`'.

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 (yn) ? " "yYnN" "y"
        save-buffers-exit-emacs
    !endif

By using the &isequal(4) operator a return of "Y" or "y" will match with "y". However, there are two problems with this, firstly if the user aborts by pressing '`C-g`' a macro error will be generated because the &iseq operator failed to get 2 arguments. The second problem is that the meaning of "`(yn)`" may not be obvious to all users so a help string should be supplied. To address these 2 issues the following should be used in preference:

    set-variable #l0 @mc5 "Are you bored (?yn) ? " "yYnN" "(Y)es, (N)no, (C-g)Abort ? "
    !if &iseq #l0 "y"
        save-buffers-exit-emacs
    !endif

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"
            set-variable #l0 @mc5 "Save buffer first (?yn) ? " "nNyY" "(Y)es, (N)o, (C-g)Abort ? "
            !if &iseq #l0 "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 (?yn) ? " "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 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>