&atoi(4)

NAME

&ato, &gmod, &bmo, &ind, &inw, &exi - Miscellaneous functions

SYNOPSIS

&atoi char
&itoa num

&gmode mode
&bmode mode
&nbmode buffer mode
&inword char

&indirect str

&exist str

DESCRIPTION

These are a selection of miscellaneous functions providing tests and exchanging of information.

The functions may all be abbreviated to their three letter abbreviation (i.e. &indirect may be expressed as &ind). In all cases the first argument is completely evaluated before the second argument.

&atoi char


Converts the given character char to it's ASCII number which is returned. (see &itoa). Abbreviated command is &ato.

&itoa num


Converts an integer num to it's ASCII character representation which is returned to the caller. Abbreviated command is &ito.

&gmode mode


Returns 1 if the given mode mode is globally enabled. Allows macros to test the global mode state (see Operating Modes). Abbreviated command is &gmo.

&bmode mode


Returns 1 if the mode mode is enabled in the current buffer. Allows macros to test the state of the buffer mode. Abbreviated command is &bmo.

&nbmode buffer mode


Returns 1 if the mode mode is enabled in buffer buffer . Allows macros to test the state of a buffer mode other than the current. Abbreviated command is &nbm.

&inword char


TRUE. If the given character char is a 'word' character, see forward-word(2) for a description of a 'word' character. Abbreviated command is &inw.

&indirect str


Evaluate str as a variable. The str argument is evaluated and takes the resulting string, and then uses it as a variable name. i.e. a variable may reference another variable which contains the data to be referenced. Abbreviated command is &ind.

&exist str


Tests for the existance of str which may be a buffer, variable or a command/macro name, returning TRUE if the buffer, variable or command does currently exist. Note that when testing for the existence of a buffer the buffer name must be encased in ':'s, e.g. ":*scratch*:" to distinguish it from a check command/macro name. Abbreviated command is &exi.

EXAMPLE

The &exi function is etremely useful in initializing, for example:

!if &not &exi %my-init 
    ; %my-init is not yet defined so this is the first call 
    set-variable %my-init 1 
    . 
    . 

Or in all the file hooks a user defined extension is checked for and executed if defined:

define-macro fhook-c 
    . 
    . 
    ; execute user extensions if macro is defined 
    !if &exi my-fhook-c 
        my-fhook-c 
    !endif 
!emacro 

The &ind function deserves more explanation. &ind evaluates its string argument str, takes the resulting string and then uses it as a variable name. For example, given the following code sequence:

; set up reference table 

set-variable  %one      "elephant" 
set-variable  %two      "giraffe" 
set-variable  %three    "donkey" 

set-variable  %index "%two" 
insert-string &ind %index 

the string "giraffe" would have been inserted at the point in the current buffer.

The &bmode invocation allows a calling macro to determine the buffer mode state (see Operating Modes). Consider the following example which is a macro to perform a case insensitive alphabetic sort using the sort-lines(2) function. sort-list sorts according to the state of the exact(2m) mode, hence the macro has to determine the buffer state in order to be able to do the sort.

define-macro sort-lines-ignore-case 
    set-variable #l0 &bmod exact 
    -1 buffer-mode "exact" 
    !if @? 
        @# sort-lines 
    !else 
        sort-lines 
    !endif 
    &cond #l0 1 -1 buffer-mode "exact" 
!emacro 

The &inword function is shown in the following example. In this case the mouse is positioned over a word. The &inword function is used to determine if the cursor is on a valid word character, if so the cursor is placed at the start of the word.

define-macro mouse-control-drop-left 
    set-cursor-to-mouse 
    !if &inword @wc 
        backward-word 
        set-mark 
        forward-word 
    !else 
        ... 
    !endif 
    copy-region 
    set-cursor-to-mouse 
!emacro 

SEE ALSO

Operating Modes, Variable Functions, &sprintf(4), &equal(4).

Ref: &atoi(4) File: m4fil005.4 Date: 2026/02/17

(c) Copyright JASSPA 2026