Function: call-interactively
call-interactively is a function defined in callint.c.
Signature
(call-interactively FUNCTION &optional RECORD-FLAG KEYS)
Documentation
Call FUNCTION, providing args according to its interactive calling specs.
Return the value FUNCTION returns.
The function contains a specification of how to do the argument reading.
In the case of user-defined functions, this is specified by placing a call
to the function interactive at the top level of the function body.
See interactive.
Optional second arg RECORD-FLAG non-nil
means unconditionally put this command in the variable command-history(var)/command-history(fun).
Otherwise, this is done only if an arg is read using the minibuffer.
Optional third arg KEYS, if given, specifies the sequence of events to
supply, as a vector, if FUNCTION inquires which events were used to
invoke it (via an interactive spec that contains, for instance, an
"e" code letter). If KEYS is omitted or nil, the return value of
this-command-keys-vector is used.
Probably introduced at or before Emacs version 19.30.
Source Code
// Defined in /usr/src/emacs/src/callint.c
// Skipping highlighting due to helpful-max-highlight.
{
specpdl_ref speccount = SPECPDL_INDEX ();
bool arg_from_tty = false;
ptrdiff_t key_count;
bool record_then_fail = false;
Lisp_Object save_this_command = Vthis_command;
Lisp_Object save_this_original_command = Vthis_original_command;
Lisp_Object save_real_this_command = Vreal_this_command;
Lisp_Object save_last_command = KVAR (current_kboard, Vlast_command);
/* Bound recursively so that code can check the current command from
code running from minibuffer hooks (and the like), without being
overwritten by subsequent minibuffer calls. */
specbind (Qcurrent_minibuffer_command, Vthis_command);
if (NILP (keys))
keys = this_command_keys, key_count = this_command_key_count;
else
{
CHECK_VECTOR (keys);
key_count = ASIZE (keys);
}
/* Save this now, since use of minibuffer will clobber it. */
Lisp_Object prefix_arg = Vcurrent_prefix_arg;
Lisp_Object enable = (SYMBOLP (function)
? Fget (function, Qenable_recursive_minibuffers)
: Qnil);
/* If k or K discard an up-event, save it here so it can be retrieved with
U. */
Lisp_Object up_event = Qnil;
/* Set SPECS to the interactive form, or barf if not interactive. */
Lisp_Object form = calln (Qinteractive_form, function);
if (! CONSP (form))
wrong_type_argument (Qcommandp, function);
Lisp_Object specs = Fcar (XCDR (form));
/* At this point the value of SPECS could help provide a way to
specify how to represent the arguments in command history.
The feature is not fully implemented. */
/* If SPECS is not a string, invent one. */
if (! STRINGP (specs))
{
Lisp_Object funval = Findirect_function (function, Qt);
uintmax_t events = num_input_events;
Lisp_Object env = CLOSUREP (funval) && CONSP (AREF (funval, CLOSURE_CODE))
? AREF (funval, CLOSURE_CONSTANTS) : Qnil;
/* Compute the arg values using the user's expression. */
specs = Feval (specs, env);
if (events != num_input_events || !NILP (record_flag))
{
/* We should record this command on the command history.
Make a copy of the list of values, for the command history,
and turn them into things we can eval. */
Lisp_Object values = quotify_args (Fcopy_sequence (specs));
fix_command (function, values);
calln (Qadd_to_history, Qcommand_history,
Fcons (function, values), Qnil, Qt);
}
Vthis_command = save_this_command;
Vthis_original_command = save_this_original_command;
Vreal_this_command = save_real_this_command;
kset_last_command (current_kboard, save_last_command);
return unbind_to (speccount, CALLN (Fapply, Qfuncall_interactively,
function, specs));
}
/* SPECS is set to a string; use it as an interactive prompt.
Copy it so that STRING will be valid even if a GC relocates SPECS. */
USE_SAFE_ALLOCA;
ptrdiff_t string_len = SBYTES (specs);
char *string = SAFE_ALLOCA (string_len + 1);
memcpy (string, SDATA (specs), string_len + 1);
char *string_end = string + string_len;
/* The index of the next element of this_command_keys to examine for
the 'e' interactive code. Initialize it to point to the first
event with parameters. When `inhibit_mouse_event_check' is non-nil,
the command can accept an event without parameters,
so don't search for the event with parameters in this case. */
ptrdiff_t next_event = 0;
if (!inhibit_mouse_event_check)
for (; next_event < key_count; next_event++)
if (EVENT_HAS_PARAMETERS (AREF (keys, next_event)))
break;
/* Handle special starting chars `*' and `@'. Also `-'. */
/* Note that `+' is reserved for user extensions. */
for (;; string++)
{
if (*string == '+')
error ("`+' is not used in `interactive' for ordinary commands");
else if (*string == '*')
{
if (!NILP (BVAR (current_buffer, read_only)))
{
if (!NILP (record_flag))
{
for (char *p = string + 1; p < string_end; p++)
if (! (*p == 'r' || *p == 'R'
|| *p == 'p' || *p == 'P' || *p == '\n'))
Fbarf_if_buffer_read_only (Qnil);
record_then_fail = true;
}
else
Fbarf_if_buffer_read_only (Qnil);
}
}
/* Ignore this for semi-compatibility with Lucid. */
else if (*string == '-')
;
else if (*string == '@')
{
Lisp_Object w, event = (next_event < key_count
? AREF (keys, next_event)
: Qnil);
if (EVENT_HAS_PARAMETERS (event)
&& (w = XCDR (event), CONSP (w))
&& (w = XCAR (w), CONSP (w))
&& (w = XCAR (w), WINDOWP (w)))
{
if (MINI_WINDOW_P (XWINDOW (w))
&& ! (minibuf_level > 0 && BASE_EQ (w, minibuf_window)))
error ("Attempt to select inactive minibuffer window");
/* If the current buffer wants to clean up, let it. */
run_hook (Qmouse_leave_buffer_hook);
Fselect_window (w, Qnil);
}
}
else if (*string == '^')
call0 (Qhandle_shift_selection);
else break;
}
/* Count the number of arguments, which is two (the function itself and
`funcall-interactively') plus the number of arguments the interactive spec
would have us give to the function. */
ptrdiff_t nargs = 2;
for (char const *tem = string; tem < string_end; tem++)
{
/* 'r'/'R' specifications ("point and mark as 2 numeric args")
produce *two* arguments. */
nargs += 1 + (*tem == 'r' || *tem == 'R');
tem = memchr (tem, '\n', string_len - (tem - string));
if (!tem)
break;
}
if (MOST_POSITIVE_FIXNUM < min (PTRDIFF_MAX, SIZE_MAX) / word_size
&& MOST_POSITIVE_FIXNUM < nargs)
memory_full (SIZE_MAX);
/* ARGS will contain the array of arguments to pass to the function.
VISARGS will contain the same list but in a nicer form, so that if we
pass it to Fformat_message it will be understandable to a human.
Allocate them all at one go. This wastes a bit of memory, but
it's OK to trade space for speed. */
Lisp_Object *args;
SAFE_NALLOCA (args, 3, nargs);
Lisp_Object *visargs = args + nargs;
/* If varies[I] > 0, the Ith argument shouldn't just have its value
in this call quoted in the command history. It should be
recorded as a call to the function named callint_argfuns[varies[I]]. */
signed char *varies = (signed char *) (visargs + nargs);
memclear (args, nargs * (2 * word_size + 1));
if (!NILP (enable))
specbind (Qenable_recursive_minibuffers, Qt);
char const *tem = string;
for (ptrdiff_t i = 2; tem < string_end; i++)
{
char const *pnl = memchr (tem + 1, '\n', string_len - (tem + 1 - string));
ptrdiff_t sz = pnl ? pnl - (tem + 1) : string_end - (tem + 1);
visargs[1] = make_string (tem + 1, sz);
callint_message = Fformat_message (i - 1, visargs + 1);
switch (*tem)
{
case 'a': /* Symbol defined as a function. */
visargs[i] = Fcompleting_read (callint_message,
Vobarray, Qfboundp, Qt,
Qnil, Qnil, Qnil, Qnil);
args[i] = Fintern (visargs[i], Qnil);
break;
case 'b': /* Name of existing buffer. */
args[i] = Fcurrent_buffer ();
if (BASE_EQ (selected_window, minibuf_window))
args[i] = Fother_buffer (args[i], Qnil, Qnil);
args[i] = Fread_buffer (callint_message, args[i], Qt, Qnil);
break;
case 'B': /* Name of buffer, possibly nonexistent. */
args[i] = Fread_buffer (callint_message,
Fother_buffer (Fcurrent_buffer (),
Qnil, Qnil),
Qnil, Qnil);
break;
case 'c': /* Character. */
/* Prompt in `minibuffer-prompt' face. */
Fput_text_property (make_fixnum (0),
make_fixnum (SCHARS (callint_message)),
Qface, Qminibuffer_prompt, callint_message);
args[i] = Fread_char (callint_message, Qnil, Qnil);
message1_nolog (0);
/* See bug#8479. */
if (! CHARACTERP (args[i]))
error ("Non-character input-event");
visargs[i] = Fchar_to_string (args[i]);
break;
case 'C': /* Command: symbol with interactive function. */
visargs[i] = Fcompleting_read (callint_message,
Vobarray, Qcommandp,
Qt, Qnil, Qnil, Qnil, Qnil);
args[i] = Fintern (visargs[i], Qnil);
break;
case 'd': /* Value of point. Does not do I/O. */
set_marker_both (point_marker, Qnil, PT, PT_BYTE);
args[i] = point_marker;
/* visargs[i] = Qnil; */
varies[i] = 1;
break;
case 'D': /* Directory name. */
args[i] = read_file_name (BVAR (current_buffer, directory), Qlambda,
Qnil, Qfile_directory_p);
break;
case 'f': /* Existing file name. */
args[i] = read_file_name (Qnil, Qlambda, Qnil, Qnil);
break;
case 'F': /* Possibly nonexistent file name. */
args[i] = read_file_name (Qnil, Qnil, Qnil, Qnil);
break;
case 'G': /* Possibly nonexistent file name,
default to directory alone. */
args[i] = read_file_name (Qnil, Qnil, empty_unibyte_string, Qnil);
break;
case 'i': /* Ignore an argument -- Does not do I/O. */
varies[i] = -1;
break;
case 'k': /* Key sequence. */
{
specpdl_ref speccount1 = SPECPDL_INDEX ();
specbind (Qcursor_in_echo_area, Qt);
/* Prompt in `minibuffer-prompt' face. */
Fput_text_property (make_fixnum (0),
make_fixnum (SCHARS (callint_message)),
Qface, Qminibuffer_prompt, callint_message);
args[i] = Fread_key_sequence (callint_message,
Qnil, Qnil, Qnil, Qnil,
Qnil);
unbind_to (speccount1, Qnil);
visargs[i] = Fkey_description (args[i], Qnil);
/* If the key sequence ends with a down-event,
discard the following up-event. */
Lisp_Object teml
= Faref (args[i], make_fixnum (XFIXNUM (Flength (args[i])) - 1));
if (CONSP (teml))
teml = XCAR (teml);
if (SYMBOLP (teml))
{
teml = Fget (teml, Qevent_symbol_elements);
/* Ignore first element, which is the base key. */
Lisp_Object tem2 = Fmemq (Qdown, Fcdr (teml));
if (! NILP (tem2))
up_event = Fread_event (Qnil, Qnil, Qnil);
}
}
break;
case 'K': /* Key sequence to be defined. */
{
specpdl_ref speccount1 = SPECPDL_INDEX ();
specbind (Qcursor_in_echo_area, Qt);
/* Prompt in `minibuffer-prompt' face. */
Fput_text_property (make_fixnum (0),
make_fixnum (SCHARS (callint_message)),
Qface, Qminibuffer_prompt, callint_message);
args[i] = Fread_key_sequence_vector (callint_message,
Qnil, Qt, Qnil, Qnil,
Qnil);
visargs[i] = Fkey_description (args[i], Qnil);
unbind_to (speccount1, Qnil);
/* If the key sequence ends with a down-event,
discard the following up-event. */
Lisp_Object teml
= Faref (args[i], make_fixnum (ASIZE (args[i]) - 1));
if (CONSP (teml))
teml = XCAR (teml);
if (SYMBOLP (teml))
{
teml = Fget (teml, Qevent_symbol_elements);
/* Ignore first element, which is the base key. */
Lisp_Object tem2 = Fmemq (Qdown, Fcdr (teml));
if (! NILP (tem2))
up_event = Fread_event (Qnil, Qnil, Qnil);
}
}
break;
case 'U': /* Up event from last k or K. */
if (!NILP (up_event))
{
args[i] = make_vector (1, up_event);
up_event = Qnil;
visargs[i] = Fkey_description (args[i], Qnil);
}
break;
case 'e': /* The invoking event. */
if (next_event >= key_count)
error ("%s must be bound to an event with parameters",
(SYMBOLP (function)
? SSDATA (SYMBOL_NAME (function))
: "command"));
args[i] = AREF (keys, next_event);
varies[i] = -1;
/* `inhibit_mouse_event_check' allows non-parameterized events. */
if (inhibit_mouse_event_check)
next_event++;
else
/* Find the next parameterized event. */
do
next_event++;
while (next_event < key_count
&& ! EVENT_HAS_PARAMETERS (AREF (keys, next_event)));
break;
case 'm': /* Value of mark. Does not do I/O. */
check_mark (false);
/* visargs[i] = Qnil; */
args[i] = BVAR (current_buffer, mark);
varies[i] = 2;
break;
case 'M': /* String read via minibuffer with
inheriting the current input method. */
args[i] = Fread_string (callint_message,
Qnil, Qnil, Qnil, Qt);
break;
case 'N': /* Prefix arg as number, else number from minibuffer. */
if (!NILP (prefix_arg))
goto have_prefix_arg;
FALLTHROUGH;
case 'n': /* Read number from minibuffer. */
args[i] = calln (Qread_number, callint_message);
visargs[i] = Fnumber_to_string (args[i]);
break;
case 'P': /* Prefix arg in raw form. Does no I/O. */
args[i] = prefix_arg;
/* visargs[i] = Qnil; */
varies[i] = -1;
break;
case 'p': /* Prefix arg converted to number. No I/O. */
have_prefix_arg:
args[i] = Fprefix_numeric_value (prefix_arg);
/* visargs[i] = Qnil; */
varies[i] = -1;
break;
case 'R': /* Active region, point and mark as 2 args. */
if (NILP (calln (Quse_region_p)))
{
/* args[i] = args[i + 1] = visargs[i] = visargs[i + 1]
= Qnil; */
varies[i] = 5;
varies[++i] = 6;
break;
}
FALLTHROUGH;
case 'r': /* Region, point and mark as 2 args. */
{
check_mark (true);
set_marker_both (point_marker, Qnil, PT, PT_BYTE);
ptrdiff_t mark = marker_position (BVAR (current_buffer, mark));
/* visargs[i] = visargs[i + 1] = Qnil; */
args[i] = PT < mark ? point_marker : BVAR (current_buffer, mark);
varies[i] = *tem == 'R' ? 5 : 3;
args[++i] = PT > mark ? point_marker : BVAR (current_buffer, mark);
varies[i] = *tem == 'R' ? 6 : 4;
}
break;
case 's': /* String read via minibuffer without
inheriting the current input method. */
args[i] = Fread_string (callint_message,
Qnil, Qnil, Qnil, Qnil);
break;
case 'S': /* Any symbol. */
visargs[i] = Fread_string (callint_message,
Qnil, Qnil, Qnil, Qnil);
args[i] = Fintern (visargs[i], Qnil);
break;
case 'v': /* Variable name: symbol that is
custom-variable-p. */
args[i] = Fread_variable (callint_message, Qnil);
visargs[i] = last_minibuf_string;
break;
case 'x': /* Lisp expression read but not evaluated. */
args[i] = calln (Qread_minibuffer, callint_message);
visargs[i] = last_minibuf_string;
break;
case 'X': /* Lisp expression read and evaluated. */
args[i] = calln (Qeval_minibuffer, callint_message);
visargs[i] = last_minibuf_string;
break;
case 'Z': /* Coding-system symbol, or ignore the
argument if no prefix. */
if (NILP (prefix_arg))
{
/* args[i] = Qnil; */
varies[i] = -1;
}
else
{
args[i]
= Fread_non_nil_coding_system (callint_message);
visargs[i] = last_minibuf_string;
}
break;
case 'z': /* Coding-system symbol or nil. */
args[i] = Fread_coding_system (callint_message, Qnil);
visargs[i] = last_minibuf_string;
break;
/* We have a case for `+' so we get an error
if anyone tries to define one here. */
case '+':
default:
{
/* How many bytes are left unprocessed in the specs string?
(Note that this excludes the trailing null byte.) */
ptrdiff_t bytes_left = string_len - (tem - string);
unsigned letter;
/* If we have enough bytes left to treat the sequence as a
character, show that character's codepoint; otherwise
show only its first byte. */
if (bytes_left >= BYTES_BY_CHAR_HEAD (*((unsigned char *) tem)))
letter = STRING_CHAR ((unsigned char *) tem);
else
letter = *((unsigned char *) tem);
error (("Invalid control letter `%c' (#o%03o, #x%04x)"
" in interactive calling string"),
(int) letter, letter, letter);
}
}
if (varies[i] == 0)
arg_from_tty = true;
if (NILP (visargs[i]) && STRINGP (args[i]))
visargs[i] = args[i];
tem = memchr (tem, '\n', string_len - (tem - string));
if (tem) tem++;
else tem = string_end;
}
unbind_to (speccount, Qnil);
maybe_quit ();
args[0] = Qfuncall_interactively;
args[1] = function;
if (arg_from_tty || !NILP (record_flag))
{
/* We don't need `visargs' any more, so let's recycle it since we need
an array of just the same size. */
visargs[1] = function;
for (ptrdiff_t i = 2; i < nargs; i++)
visargs[i] = (varies[i] > 0
? list1 (intern (callint_argfuns[varies[i]]))
: quotify_arg (args[i]));
calln (Qadd_to_history, Qcommand_history,
Flist (nargs - 1, visargs + 1), Qnil, Qt);
}
/* If we used a marker to hold point, mark, or an end of the region,
temporarily, convert it to an integer now. */
for (ptrdiff_t i = 2; i < nargs; i++)
if (varies[i] >= 1 && varies[i] <= 4)
XSETINT (args[i], marker_position (args[i]));
if (record_then_fail)
Fbarf_if_buffer_read_only (Qnil);
Vthis_command = save_this_command;
Vthis_original_command = save_this_original_command;
Vreal_this_command = save_real_this_command;
kset_last_command (current_kboard, save_last_command);
specbind (Qcommand_debug_status, Qnil);
Lisp_Object val = Ffuncall (nargs, args);
return SAFE_FREE_UNBIND_TO (speccount, val);
}