1 /* Call a Lisp function interactively.
2 Copyright (C) 1985, 1986, 1993 Free Software Foundation, Inc.
4 This file is part of GNU Emacs.
6 GNU Emacs is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Emacs is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Emacs; see the file COPYING. If not, write to
18 the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. */
29 extern char *index ();
31 Lisp_Object Vprefix_arg
, Vcurrent_prefix_arg
, Qminus
;
32 Lisp_Object Qcall_interactively
;
33 Lisp_Object Vcommand_history
;
35 Lisp_Object Vcommand_debug_status
, Qcommand_debug_status
;
36 Lisp_Object Qenable_recursive_minibuffers
;
38 /* Non-nil means treat the mark as active
39 even if mark_active is 0. */
40 Lisp_Object Vmark_even_if_inactive
;
43 Lisp_Object preserved_fns
;
45 /* This comment supplies the doc string for interactive,
46 for make-docfile to see. We cannot put this in the real DEFUN
47 due to limits in the Unix cpp.
49 DEFUN ("interactive", Ffoo, Sfoo, 0, 0, 0,
50 "Specify a way of parsing arguments for interactive use of a function.\n\
52 (defun foo (arg) \"Doc string\" (interactive \"p\") ...use arg...)\n\
53 to make ARG be the prefix argument when `foo' is called as a command.\n\
54 The \"call\" to `interactive' is actually a declaration rather than a function;\n\
55 it tells `call-interactively' how to read arguments\n\
56 to pass to the function.\n\
57 When actually called, `interactive' just returns nil.\n\
59 The argument of `interactive' is usually a string containing a code letter\n\
60 followed by a prompt. (Some code letters do not use I/O to get\n\
61 the argument and do not need prompts.) To prompt for multiple arguments,\n\
62 give a code letter, its prompt, a newline, and another code letter, etc.\n\
63 Prompts are passed to format, and may use % escapes to print the\n\
64 arguments that have already been read.\n\
65 If the argument is not a string, it is evaluated to get a list of\n\
66 arguments to pass to the function.\n\
67 Just `(interactive)' means pass no args when calling interactively.\n\
68 \nCode letters available are:\n\
69 a -- Function name: symbol with a function definition.\n\
70 b -- Name of existing buffer.\n\
71 B -- Name of buffer, possibly nonexistent.\n\
73 C -- Command name: symbol with interactive function definition.\n\
74 d -- Value of point as number. Does not do I/O.\n\
75 D -- Directory name.\n\
76 e -- Parametrized event (i.e., one that's a list) that invoked this command.\n\
77 If used more than once, the Nth `e' returns the Nth parameterized event.\n\
78 This skips events that are integers or symbols.\n\
79 f -- Existing file name.\n\
80 F -- Possibly nonexistent file name.\n\
81 k -- Key sequence (string).\n\
82 m -- Value of mark as number. Does not do I/O.\n\
83 n -- Number read using minibuffer.\n\
84 N -- Prefix arg converted to number, or if none, do like code `n'.\n\
85 p -- Prefix arg converted to number. Does not do I/O.\n\
86 P -- Prefix arg in raw form. Does not do I/O.\n\
87 r -- Region: point and mark as 2 numeric args, smallest first. Does no I/O.\n\
90 v -- Variable name: symbol that is user-variable-p.\n\
91 x -- Lisp expression read but not evaluated.\n\
92 X -- Lisp expression read and evaluated.\n\
93 In addition, if the string begins with `*'\n\
94 then an error is signaled if the buffer is read-only.\n\
95 This happens before reading any arguments.\n\
96 If the string begins with `@', then Emacs searches the key sequence\n\
97 which invoked the command for its first mouse click (or any other\n\
98 event which specifies a window), and selects that window before\n\
99 reading any arguments. You may use both `@' and `*'; they are\n\
100 processed in the order that they appear." */
103 DEFUN ("interactive", Finteractive
, Sinteractive
, 0, UNEVALLED
, 0,
104 0 /* See immediately above */)
111 /* Quotify EXP: if EXP is constant, return it.
112 If EXP is not constant, return (quote EXP). */
115 register Lisp_Object exp
;
117 if (XTYPE (exp
) != Lisp_Int
&& XTYPE (exp
) != Lisp_String
118 && !NILP (exp
) && !EQ (exp
, Qt
))
119 return Fcons (Qquote
, Fcons (exp
, Qnil
));
124 /* Modify EXP by quotifying each element (except the first). */
129 register Lisp_Object tail
;
130 register struct Lisp_Cons
*ptr
;
131 for (tail
= exp
; CONSP (tail
); tail
= ptr
->cdr
)
134 ptr
->car
= quotify_arg (ptr
->car
);
139 char *callint_argfuns
[]
140 = {"", "point", "mark", "region-beginning", "region-end"};
145 Lisp_Object tem
= Fmarker_buffer (current_buffer
->mark
);
146 if (NILP (tem
) || (XBUFFER (tem
) != current_buffer
))
147 error ("The mark is not set now");
148 if (NILP (current_buffer
->mark_active
) && NILP (Vmark_even_if_inactive
))
149 error ("The mark is not active now");
153 DEFUN ("call-interactively", Fcall_interactively
, Scall_interactively
, 1, 2, 0,
154 "Call FUNCTION, reading args according to its interactive calling specs.\n\
155 The function contains a specification of how to do the argument reading.\n\
156 In the case of user-defined functions, this is specified by placing a call\n\
157 to the function `interactive' at the top level of the function body.\n\
158 See `interactive'.\n\
160 Optional second arg RECORD-FLAG non-nil\n\
161 means unconditionally put this command in the command-history.\n\
162 Otherwise, this is done only if an arg is read using the minibuffer.")
164 Lisp_Object function
, record
;
166 Lisp_Object
*args
, *visargs
;
167 unsigned char **argstrings
;
173 int speccount
= specpdl_ptr
- specpdl
;
175 /* The index of the next element of this_command_keys to examine for
176 the 'e' interactive code. */
179 Lisp_Object prefix_arg
;
180 unsigned char *string
;
183 /* If varies[i] > 0, the i'th argument shouldn't just have its value
184 in this call quoted in the command history. It should be
185 recorded as a call to the function named callint_argfuns[varies[i]]. */
193 int arg_from_tty
= 0;
194 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
;
196 /* Save this now, since use of minibuffer will clobber it. */
197 prefix_arg
= Vcurrent_prefix_arg
;
201 if (XTYPE (function
) == Lisp_Symbol
)
202 enable
= Fget (function
, Qenable_recursive_minibuffers
);
204 fun
= indirect_function (function
);
209 /* Decode the kind of function. Either handle it and return,
210 or go to `lose' if not interactive, or go to `retry'
211 to specify a different function, or set either STRING or SPECS. */
213 if (XTYPE (fun
) == Lisp_Subr
)
215 string
= (unsigned char *) XSUBR (fun
)->prompt
;
219 function
= wrong_type_argument (Qcommandp
, function
);
222 if ((int) string
== 1)
223 /* Let SPECS (which is nil) be used as the args. */
226 else if (XTYPE (fun
) == Lisp_Compiled
)
228 if (XVECTOR (fun
)->size
<= COMPILED_INTERACTIVE
)
230 specs
= XVECTOR (fun
)->contents
[COMPILED_INTERACTIVE
];
232 else if (!CONSP (fun
))
234 else if (funcar
= Fcar (fun
), EQ (funcar
, Qautoload
))
236 GCPRO2 (function
, prefix_arg
);
237 do_autoload (fun
, function
);
241 else if (EQ (funcar
, Qlambda
))
243 specs
= Fassq (Qinteractive
, Fcdr (Fcdr (fun
)));
246 specs
= Fcar (Fcdr (specs
));
248 else if (EQ (funcar
, Qmocklisp
))
249 return ml_apply (fun
, Qinteractive
);
253 /* If either specs or string is set to a string, use it. */
254 if (XTYPE (specs
) == Lisp_String
)
256 /* Make a copy of string so that if a GC relocates specs,
257 `string' will still be valid. */
258 string
= (unsigned char *) alloca (XSTRING (specs
)->size
+ 1);
259 bcopy (XSTRING (specs
)->data
, string
, XSTRING (specs
)->size
+ 1);
261 else if (string
== 0)
266 /* Compute the arg values using the user's expression. */
267 specs
= Feval (specs
);
268 if (i
!= num_input_chars
|| !NILP (record
))
270 /* We should record this command on the command history. */
271 Lisp_Object values
, car
;
272 /* Make a copy of the list of values, for the command history,
273 and turn them into things we can eval. */
274 values
= quotify_args (Fcopy_sequence (specs
));
275 /* If the list of args was produced with an explicit call to `list',
276 look for elements that were computed with (region-beginning)
277 or (region-end), and put those expressions into VALUES
278 instead of the present values. */
282 Lisp_Object intail
, valtail
;
283 for (intail
= Fcdr (input
), valtail
= values
;
285 intail
= Fcdr (intail
), valtail
= Fcdr (valtail
))
291 Lisp_Object presflag
;
292 presflag
= Fmemq (Fcar (elt
), preserved_fns
);
293 if (!NILP (presflag
))
294 Fsetcar (valtail
, Fcar (intail
));
299 = Fcons (Fcons (function
, values
), Vcommand_history
);
301 return apply1 (function
, specs
);
304 /* Here if function specifies a string to control parsing the defaults */
306 /* Set next_event to point to the first event with parameters. */
307 for (next_event
= 0; next_event
< this_command_key_count
; next_event
++)
308 if (EVENT_HAS_PARAMETERS
309 (XVECTOR (this_command_keys
)->contents
[next_event
]))
312 /* Handle special starting chars `*' and `@'. */
318 if (!NILP (current_buffer
->read_only
))
319 Fbarf_if_buffer_read_only ();
321 else if (*string
== '@')
324 XVECTOR (this_command_keys
)->contents
[next_event
];
326 if (EVENT_HAS_PARAMETERS (event
)
327 && XTYPE (event
= XCONS (event
)->cdr
) == Lisp_Cons
328 && XTYPE (event
= XCONS (event
)->car
) == Lisp_Cons
329 && XTYPE (event
= XCONS (event
)->car
) == Lisp_Window
)
330 Fselect_window (event
);
336 /* Count the number of arguments the interactive spec would have
337 us give to the function. */
339 for (j
= 0; *tem
; j
++)
341 /* 'r' specifications ("point and mark as 2 numeric args")
342 produce *two* arguments. */
343 if (*tem
== 'r') j
++;
344 tem
= (unsigned char *) index (tem
, '\n');
348 tem
= (unsigned char *) "";
352 args
= (Lisp_Object
*) alloca ((count
+ 1) * sizeof (Lisp_Object
));
353 visargs
= (Lisp_Object
*) alloca ((count
+ 1) * sizeof (Lisp_Object
));
354 argstrings
= (unsigned char **) alloca ((count
+ 1) * sizeof (char *));
355 varies
= (int *) alloca ((count
+ 1) * sizeof (int));
357 for (i
= 0; i
< (count
+ 1); i
++)
364 GCPRO4 (prefix_arg
, function
, *args
, *visargs
);
365 gcpro3
.nvars
= (count
+ 1);
366 gcpro4
.nvars
= (count
+ 1);
369 specbind (Qenable_recursive_minibuffers
, Qt
);
372 for (i
= 1; *tem
; i
++)
374 strncpy (prompt1
, tem
+ 1, sizeof prompt1
- 1);
375 prompt1
[sizeof prompt1
- 1] = 0;
376 tem1
= index (prompt1
, '\n');
378 /* Fill argstrings with a vector of C strings
379 corresponding to the Lisp strings in visargs. */
380 for (j
= 1; j
< i
; j
++)
382 = EQ (visargs
[j
], Qnil
)
383 ? (unsigned char *) ""
384 : XSTRING (visargs
[j
])->data
;
386 doprnt (prompt
, sizeof prompt
, prompt1
, 0, j
- 1, argstrings
+ 1);
390 case 'a': /* Symbol defined as a function */
391 visargs
[i
] = Fcompleting_read (build_string (prompt
),
392 Vobarray
, Qfboundp
, Qt
, Qnil
, Qnil
);
393 /* Passing args[i] directly stimulates compiler bug */
395 args
[i
] = Fintern (teml
, Qnil
);
398 case 'b': /* Name of existing buffer */
399 args
[i
] = Fcurrent_buffer ();
400 if (EQ (selected_window
, minibuf_window
))
401 args
[i
] = Fother_buffer (args
[i
], Qnil
);
402 args
[i
] = Fread_buffer (build_string (prompt
), args
[i
], Qt
);
405 case 'B': /* Name of buffer, possibly nonexistent */
406 args
[i
] = Fread_buffer (build_string (prompt
),
407 Fother_buffer (Fcurrent_buffer (), Qnil
),
411 case 'c': /* Character */
413 args
[i
] = Fread_char ();
414 /* Passing args[i] directly stimulates compiler bug */
416 visargs
[i
] = Fchar_to_string (teml
);
419 case 'C': /* Command: symbol with interactive function */
420 visargs
[i
] = Fcompleting_read (build_string (prompt
),
421 Vobarray
, Qcommandp
, Qt
, Qnil
, Qnil
);
422 /* Passing args[i] directly stimulates compiler bug */
424 args
[i
] = Fintern (teml
, Qnil
);
427 case 'd': /* Value of point. Does not do I/O. */
428 XFASTINT (args
[i
]) = point
;
429 /* visargs[i] = Qnil; */
433 case 'D': /* Directory name. */
434 args
[i
] = Fread_file_name (build_string (prompt
), Qnil
,
435 current_buffer
->directory
, Qlambda
, Qnil
);
438 case 'f': /* Existing file name. */
439 args
[i
] = Fread_file_name (build_string (prompt
),
440 Qnil
, Qnil
, Qlambda
, Qnil
);
443 case 'F': /* Possibly nonexistent file name. */
444 args
[i
] = Fread_file_name (build_string (prompt
),
445 Qnil
, Qnil
, Qnil
, Qnil
);
448 case 'k': /* Key sequence (string) */
449 args
[i
] = Fread_key_sequence (build_string (prompt
), Qnil
);
451 visargs
[i
] = Fkey_description (teml
);
454 case 'e': /* The invoking event. */
455 if (next_event
>= this_command_key_count
)
456 error ("%s must be bound to an event with parameters",
457 (XTYPE (function
) == Lisp_Symbol
458 ? (char *) XSYMBOL (function
)->name
->data
460 args
[i
] = XVECTOR (this_command_keys
)->contents
[next_event
++];
463 /* Find the next parameterized event. */
464 while (next_event
< this_command_key_count
465 && ! (EVENT_HAS_PARAMETERS
466 (XVECTOR (this_command_keys
)->contents
[next_event
])))
471 case 'm': /* Value of mark. Does not do I/O. */
473 /* visargs[i] = Qnil; */
474 XFASTINT (args
[i
]) = marker_position (current_buffer
->mark
);
478 case 'N': /* Prefix arg, else number from minibuffer */
479 if (!NILP (prefix_arg
))
480 goto have_prefix_arg
;
481 case 'n': /* Read number from minibuffer. */
483 args
[i
] = Fread_minibuffer (build_string (prompt
), Qnil
);
484 while (! NUMBERP (args
[i
]));
485 visargs
[i
] = last_minibuf_string
;
488 case 'P': /* Prefix arg in raw form. Does no I/O. */
490 args
[i
] = prefix_arg
;
491 /* visargs[i] = Qnil; */
495 case 'p': /* Prefix arg converted to number. No I/O. */
496 args
[i
] = Fprefix_numeric_value (prefix_arg
);
497 /* visargs[i] = Qnil; */
501 case 'r': /* Region, point and mark as 2 args. */
503 /* visargs[i+1] = Qnil; */
504 foo
= marker_position (current_buffer
->mark
);
505 /* visargs[i] = Qnil; */
506 XFASTINT (args
[i
]) = point
< foo
? point
: foo
;
508 XFASTINT (args
[++i
]) = point
> foo
? point
: foo
;
512 case 's': /* String read via minibuffer. */
513 args
[i
] = Fread_string (build_string (prompt
), Qnil
);
516 case 'S': /* Any symbol. */
517 visargs
[i
] = Fread_string (build_string (prompt
), Qnil
);
518 /* Passing args[i] directly stimulates compiler bug */
520 args
[i
] = Fintern (teml
, Qnil
);
523 case 'v': /* Variable name: symbol that is
525 args
[i
] = Fread_variable (build_string (prompt
));
526 visargs
[i
] = last_minibuf_string
;
529 case 'x': /* Lisp expression read but not evaluated */
530 args
[i
] = Fread_minibuffer (build_string (prompt
), Qnil
);
531 visargs
[i
] = last_minibuf_string
;
534 case 'X': /* Lisp expression read and evaluated */
535 args
[i
] = Feval_minibuffer (build_string (prompt
), Qnil
);
536 visargs
[i
] = last_minibuf_string
;
540 error ("Invalid control letter \"%c\" (%03o) in interactive calling string",
547 if (NILP (visargs
[i
]) && XTYPE (args
[i
]) == Lisp_String
)
548 visargs
[i
] = args
[i
];
550 tem
= (unsigned char *) index (tem
, '\n');
552 else tem
= (unsigned char *) "";
554 unbind_to (speccount
, Qnil
);
560 if (arg_from_tty
|| !NILP (record
))
562 visargs
[0] = function
;
563 for (i
= 1; i
< count
+ 1; i
++)
565 visargs
[i
] = Fcons (intern (callint_argfuns
[varies
[i
]]), Qnil
);
567 visargs
[i
] = quotify_arg (args
[i
]);
568 Vcommand_history
= Fcons (Flist (count
+ 1, visargs
),
574 specbind (Qcommand_debug_status
, Qnil
);
576 val
= Ffuncall (count
+ 1, args
);
578 return unbind_to (speccount
, val
);
582 DEFUN ("prefix-numeric-value", Fprefix_numeric_value
, Sprefix_numeric_value
,
584 "Return numeric meaning of raw prefix argument ARG.\n\
585 A raw prefix argument is what you get from `(interactive \"P\")'.\n\
586 Its numeric meaning is what you would get from `(interactive \"p\")'.")
592 /* Tag val as an integer, so the rest of the assignments
598 else if (EQ (raw
, Qminus
))
600 else if (CONSP (raw
))
601 XSETINT (val
, XINT (XCONS (raw
)->car
));
602 else if (XTYPE (raw
) == Lisp_Int
)
612 preserved_fns
= Fcons (intern ("region-beginning"),
613 Fcons (intern ("region-end"),
614 Fcons (intern ("point"),
615 Fcons (intern ("mark"), Qnil
))));
616 staticpro (&preserved_fns
);
618 Qlist
= intern ("list");
621 Qminus
= intern ("-");
624 Qcall_interactively
= intern ("call-interactively");
625 staticpro (&Qcall_interactively
);
627 Qcommand_debug_status
= intern ("command-debug-status");
628 staticpro (&Qcommand_debug_status
);
630 Qenable_recursive_minibuffers
= intern ("enable-recursive-minibuffers");
631 staticpro (&Qenable_recursive_minibuffers
);
633 DEFVAR_LISP ("prefix-arg", &Vprefix_arg
,
634 "The value of the prefix argument for the next editing command.\n\
635 It may be a number, or the symbol `-' for just a minus sign as arg,\n\
636 or a list whose car is a number for just one or more C-U's\n\
637 or nil if no argument has been specified.\n\
639 You cannot examine this variable to find the argument for this command\n\
640 since it has been set to nil by the time you can look.\n\
641 Instead, you should use the variable `current-prefix-arg', although\n\
642 normally commands can get this prefix argument with (interactive \"P\").");
645 DEFVAR_LISP ("current-prefix-arg", &Vcurrent_prefix_arg
,
646 "The value of the prefix argument for this editing command.\n\
647 It may be a number, or the symbol `-' for just a minus sign as arg,\n\
648 or a list whose car is a number for just one or more C-U's\n\
649 or nil if no argument has been specified.\n\
650 This is what `(interactive \"P\")' returns.");
651 Vcurrent_prefix_arg
= Qnil
;
653 DEFVAR_LISP ("command-history", &Vcommand_history
,
654 "List of recent commands that read arguments from terminal.\n\
655 Each command is represented as a form to evaluate.");
656 Vcommand_history
= Qnil
;
658 DEFVAR_LISP ("command-debug-status", &Vcommand_debug_status
,
659 "Debugging status of current interactive command.\n\
660 Bound each time `call-interactively' is called;\n\
661 may be set by the debugger as a reminder for itself.");
662 Vcommand_debug_status
= Qnil
;
664 DEFVAR_LISP ("Vmark-even-if-inactive", &Vmark_even_if_inactive
,
665 "*Non-nil means you can use the mark even when inactive.\n\
666 This option makes a difference in Transient Mark mode.\n\
667 When the option is non-nil, deactivation of the mark\n\
668 turns off region highlighting, but commands that use the mark\n\
669 behave as if the mark were still active.");
670 Vmark_even_if_inactive
= Qnil
;
672 defsubr (&Sinteractive
);
673 defsubr (&Scall_interactively
);
674 defsubr (&Sprefix_numeric_value
);