1 /* Call a Lisp function interactively.
2 Copyright (C) 1985, 1986, 1993, 1994, 1995 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 Vcurrent_prefix_arg
, Qminus
, Qplus
;
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
;
42 Lisp_Object Vmouse_leave_buffer_hook
, Qmouse_leave_buffer_hook
;
45 static Lisp_Object preserved_fns
;
47 /* Marker used within call-interactively to refer to point. */
48 static Lisp_Object point_marker
;
51 /* This comment supplies the doc string for interactive,
52 for make-docfile to see. We cannot put this in the real DEFUN
53 due to limits in the Unix cpp.
55 DEFUN ("interactive", Ffoo, Sfoo, 0, 0, 0,
56 "Specify a way of parsing arguments for interactive use of a function.\n\
58 (defun foo (arg) \"Doc string\" (interactive \"p\") ...use arg...)\n\
59 to make ARG be the prefix argument when `foo' is called as a command.\n\
60 The \"call\" to `interactive' is actually a declaration rather than a function;\n\
61 it tells `call-interactively' how to read arguments\n\
62 to pass to the function.\n\
63 When actually called, `interactive' just returns nil.\n\
65 The argument of `interactive' is usually a string containing a code letter\n\
66 followed by a prompt. (Some code letters do not use I/O to get\n\
67 the argument and do not need prompts.) To prompt for multiple arguments,\n\
68 give a code letter, its prompt, a newline, and another code letter, etc.\n\
69 Prompts are passed to format, and may use % escapes to print the\n\
70 arguments that have already been read.\n\
71 If the argument is not a string, it is evaluated to get a list of\n\
72 arguments to pass to the function.\n\
73 Just `(interactive)' means pass no args when calling interactively.\n\
74 \nCode letters available are:\n\
75 a -- Function name: symbol with a function definition.\n\
76 b -- Name of existing buffer.\n\
77 B -- Name of buffer, possibly nonexistent.\n\
79 C -- Command name: symbol with interactive function definition.\n\
80 d -- Value of point as number. Does not do I/O.\n\
81 D -- Directory name.\n\
82 e -- Parametrized event (i.e., one that's a list) that invoked this command.\n\
83 If used more than once, the Nth `e' returns the Nth parameterized event.\n\
84 This skips events that are integers or symbols.\n\
85 f -- Existing file name.\n\
86 F -- Possibly nonexistent file name.\n\
87 k -- Key sequence (downcase the last event if needed to get a definition).\n\
88 K -- Key sequence to be redefined (do not downcase the last event).\n\
89 m -- Value of mark as number. Does not do I/O.\n\
90 n -- Number read using minibuffer.\n\
91 N -- Raw prefix arg, or if none, do like code `n'.\n\
92 p -- Prefix arg converted to number. Does not do I/O.\n\
93 P -- Prefix arg in raw form. Does not do I/O.\n\
94 r -- Region: point and mark as 2 numeric args, smallest first. Does no I/O.\n\
97 v -- Variable name: symbol that is user-variable-p.\n\
98 x -- Lisp expression read but not evaluated.\n\
99 X -- Lisp expression read and evaluated.\n\
100 In addition, if the string begins with `*'\n\
101 then an error is signaled if the buffer is read-only.\n\
102 This happens before reading any arguments.\n\
103 If the string begins with `@', then Emacs searches the key sequence\n\
104 which invoked the command for its first mouse click (or any other\n\
105 event which specifies a window), and selects that window before\n\
106 reading any arguments. You may use both `@' and `*'; they are\n\
107 processed in the order that they appear." */
110 DEFUN ("interactive", Finteractive
, Sinteractive
, 0, UNEVALLED
, 0,
111 0 /* See immediately above */)
118 /* Quotify EXP: if EXP is constant, return it.
119 If EXP is not constant, return (quote EXP). */
122 register Lisp_Object exp
;
124 if (!INTEGERP (exp
) && !STRINGP (exp
)
125 && !NILP (exp
) && !EQ (exp
, Qt
))
126 return Fcons (Qquote
, Fcons (exp
, Qnil
));
131 /* Modify EXP by quotifying each element (except the first). */
136 register Lisp_Object tail
;
137 register struct Lisp_Cons
*ptr
;
138 for (tail
= exp
; CONSP (tail
); tail
= ptr
->cdr
)
141 ptr
->car
= quotify_arg (ptr
->car
);
146 char *callint_argfuns
[]
147 = {"", "point", "mark", "region-beginning", "region-end"};
153 tem
= Fmarker_buffer (current_buffer
->mark
);
154 if (NILP (tem
) || (XBUFFER (tem
) != current_buffer
))
155 error ("The mark is not set now");
156 if (!NILP (Vtransient_mark_mode
) && NILP (Vmark_even_if_inactive
)
157 && NILP (current_buffer
->mark_active
))
158 Fsignal (Qmark_inactive
, Qnil
);
162 DEFUN ("call-interactively", Fcall_interactively
, Scall_interactively
, 1, 2, 0,
163 "Call FUNCTION, reading args according to its interactive calling specs.\n\
164 Return the value FUNCTION returns.\n\
165 The function contains a specification of how to do the argument reading.\n\
166 In the case of user-defined functions, this is specified by placing a call\n\
167 to the function `interactive' at the top level of the function body.\n\
168 See `interactive'.\n\
170 Optional second arg RECORD-FLAG non-nil\n\
171 means unconditionally put this command in the command-history.\n\
172 Otherwise, this is done only if an arg is read using the minibuffer.")
174 Lisp_Object function
, record
;
176 Lisp_Object
*args
, *visargs
;
177 unsigned char **argstrings
;
183 int speccount
= specpdl_ptr
- specpdl
;
185 /* The index of the next element of this_command_keys to examine for
186 the 'e' interactive code. */
189 Lisp_Object prefix_arg
;
190 unsigned char *string
;
193 /* If varies[i] > 0, the i'th argument shouldn't just have its value
194 in this call quoted in the command history. It should be
195 recorded as a call to the function named callint_argfuns[varies[i]]. */
203 int arg_from_tty
= 0;
204 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
;
206 /* Save this now, since use of minibuffer will clobber it. */
207 prefix_arg
= Vcurrent_prefix_arg
;
211 if (SYMBOLP (function
))
212 enable
= Fget (function
, Qenable_recursive_minibuffers
);
214 fun
= indirect_function (function
);
219 /* Decode the kind of function. Either handle it and return,
220 or go to `lose' if not interactive, or go to `retry'
221 to specify a different function, or set either STRING or SPECS. */
225 string
= (unsigned char *) XSUBR (fun
)->prompt
;
229 function
= wrong_type_argument (Qcommandp
, function
);
232 if ((EMACS_INT
) string
== 1)
233 /* Let SPECS (which is nil) be used as the args. */
236 else if (COMPILEDP (fun
))
238 if ((XVECTOR (fun
)->size
& PSEUDOVECTOR_SIZE_MASK
) <= COMPILED_INTERACTIVE
)
240 specs
= XVECTOR (fun
)->contents
[COMPILED_INTERACTIVE
];
242 else if (!CONSP (fun
))
244 else if (funcar
= Fcar (fun
), EQ (funcar
, Qautoload
))
246 GCPRO2 (function
, prefix_arg
);
247 do_autoload (fun
, function
);
251 else if (EQ (funcar
, Qlambda
))
253 specs
= Fassq (Qinteractive
, Fcdr (Fcdr (fun
)));
256 specs
= Fcar (Fcdr (specs
));
258 else if (EQ (funcar
, Qmocklisp
))
260 single_kboard_state ();
261 return ml_apply (fun
, Qinteractive
);
266 /* If either specs or string is set to a string, use it. */
269 /* Make a copy of string so that if a GC relocates specs,
270 `string' will still be valid. */
271 string
= (unsigned char *) alloca (XSTRING (specs
)->size
+ 1);
272 bcopy (XSTRING (specs
)->data
, string
, XSTRING (specs
)->size
+ 1);
274 else if (string
== 0)
279 /* Compute the arg values using the user's expression. */
280 specs
= Feval (specs
);
281 if (i
!= num_input_chars
|| !NILP (record
))
283 /* We should record this command on the command history. */
284 Lisp_Object values
, car
;
285 /* Make a copy of the list of values, for the command history,
286 and turn them into things we can eval. */
287 values
= quotify_args (Fcopy_sequence (specs
));
288 /* If the list of args was produced with an explicit call to `list',
289 look for elements that were computed with (region-beginning)
290 or (region-end), and put those expressions into VALUES
291 instead of the present values. */
295 Lisp_Object intail
, valtail
;
296 for (intail
= Fcdr (input
), valtail
= values
;
298 intail
= Fcdr (intail
), valtail
= Fcdr (valtail
))
304 Lisp_Object presflag
;
305 presflag
= Fmemq (Fcar (elt
), preserved_fns
);
306 if (!NILP (presflag
))
307 Fsetcar (valtail
, Fcar (intail
));
312 = Fcons (Fcons (function
, values
), Vcommand_history
);
314 single_kboard_state ();
315 return apply1 (function
, specs
);
318 /* Here if function specifies a string to control parsing the defaults */
320 /* Set next_event to point to the first event with parameters. */
321 for (next_event
= 0; next_event
< this_command_key_count
; next_event
++)
322 if (EVENT_HAS_PARAMETERS
323 (XVECTOR (this_command_keys
)->contents
[next_event
]))
326 /* Handle special starting chars `*' and `@'. Also `-'. */
327 /* Note that `+' is reserved for user extensions. */
331 error ("`+' is not used in `interactive' for ordinary commands");
332 else if (*string
== '*')
335 if (!NILP (current_buffer
->read_only
))
336 Fbarf_if_buffer_read_only ();
338 /* Ignore this for semi-compatibility with Lucid. */
339 else if (*string
== '-')
341 else if (*string
== '@')
345 event
= XVECTOR (this_command_keys
)->contents
[next_event
];
346 if (EVENT_HAS_PARAMETERS (event
)
347 && (event
= XCONS (event
)->cdr
, CONSP (event
))
348 && (event
= XCONS (event
)->car
, CONSP (event
))
349 && (event
= XCONS (event
)->car
, WINDOWP (event
)))
351 if (MINI_WINDOW_P (XWINDOW (event
))
352 && ! (minibuf_level
> 0 && EQ (event
, minibuf_window
)))
353 error ("Attempt to select inactive minibuffer window");
355 /* If the current buffer wants to clean up, let it. */
356 if (!NILP (Vmouse_leave_buffer_hook
))
357 call1 (Vrun_hooks
, Qmouse_leave_buffer_hook
);
359 Fselect_window (event
);
366 /* Count the number of arguments the interactive spec would have
367 us give to the function. */
369 for (j
= 0; *tem
; j
++)
371 /* 'r' specifications ("point and mark as 2 numeric args")
372 produce *two* arguments. */
373 if (*tem
== 'r') j
++;
374 tem
= (unsigned char *) index (tem
, '\n');
378 tem
= (unsigned char *) "";
382 args
= (Lisp_Object
*) alloca ((count
+ 1) * sizeof (Lisp_Object
));
383 visargs
= (Lisp_Object
*) alloca ((count
+ 1) * sizeof (Lisp_Object
));
384 argstrings
= (unsigned char **) alloca ((count
+ 1) * sizeof (char *));
385 varies
= (int *) alloca ((count
+ 1) * sizeof (int));
387 for (i
= 0; i
< (count
+ 1); i
++)
394 GCPRO4 (prefix_arg
, function
, *args
, *visargs
);
395 gcpro3
.nvars
= (count
+ 1);
396 gcpro4
.nvars
= (count
+ 1);
399 specbind (Qenable_recursive_minibuffers
, Qt
);
402 for (i
= 1; *tem
; i
++)
404 strncpy (prompt1
, tem
+ 1, sizeof prompt1
- 1);
405 prompt1
[sizeof prompt1
- 1] = 0;
406 tem1
= index (prompt1
, '\n');
408 /* Fill argstrings with a vector of C strings
409 corresponding to the Lisp strings in visargs. */
410 for (j
= 1; j
< i
; j
++)
412 = EQ (visargs
[j
], Qnil
)
413 ? (unsigned char *) ""
414 : XSTRING (visargs
[j
])->data
;
416 doprnt (prompt
, sizeof prompt
, prompt1
, (char *)0,
417 j
- 1, argstrings
+ 1);
421 case 'a': /* Symbol defined as a function */
422 visargs
[i
] = Fcompleting_read (build_string (prompt
),
423 Vobarray
, Qfboundp
, Qt
, Qnil
, Qnil
);
424 /* Passing args[i] directly stimulates compiler bug */
426 args
[i
] = Fintern (teml
, Qnil
);
429 case 'b': /* Name of existing buffer */
430 args
[i
] = Fcurrent_buffer ();
431 if (EQ (selected_window
, minibuf_window
))
432 args
[i
] = Fother_buffer (args
[i
], Qnil
);
433 args
[i
] = Fread_buffer (build_string (prompt
), args
[i
], Qt
);
436 case 'B': /* Name of buffer, possibly nonexistent */
437 args
[i
] = Fread_buffer (build_string (prompt
),
438 Fother_buffer (Fcurrent_buffer (), Qnil
),
442 case 'c': /* Character */
444 args
[i
] = Fread_char ();
445 /* Passing args[i] directly stimulates compiler bug */
447 visargs
[i
] = Fchar_to_string (teml
);
450 case 'C': /* Command: symbol with interactive function */
451 visargs
[i
] = Fcompleting_read (build_string (prompt
),
452 Vobarray
, Qcommandp
, Qt
, Qnil
, Qnil
);
453 /* Passing args[i] directly stimulates compiler bug */
455 args
[i
] = Fintern (teml
, Qnil
);
458 case 'd': /* Value of point. Does not do I/O. */
459 Fset_marker (point_marker
, make_number (PT
), Qnil
);
460 args
[i
] = point_marker
;
461 /* visargs[i] = Qnil; */
465 case 'D': /* Directory name. */
466 args
[i
] = Fread_file_name (build_string (prompt
), Qnil
,
467 current_buffer
->directory
, Qlambda
, Qnil
);
470 case 'f': /* Existing file name. */
471 args
[i
] = Fread_file_name (build_string (prompt
),
472 Qnil
, Qnil
, Qlambda
, Qnil
);
475 case 'F': /* Possibly nonexistent file name. */
476 args
[i
] = Fread_file_name (build_string (prompt
),
477 Qnil
, Qnil
, Qnil
, Qnil
);
480 case 'k': /* Key sequence. */
481 args
[i
] = Fread_key_sequence (build_string (prompt
), Qnil
, Qnil
, Qnil
);
483 visargs
[i
] = Fkey_description (teml
);
486 case 'K': /* Key sequence to be defined. */
487 args
[i
] = Fread_key_sequence (build_string (prompt
), Qnil
, Qt
, Qnil
);
489 visargs
[i
] = Fkey_description (teml
);
492 case 'e': /* The invoking event. */
493 if (next_event
>= this_command_key_count
)
494 error ("%s must be bound to an event with parameters",
496 ? (char *) XSYMBOL (function
)->name
->data
498 args
[i
] = XVECTOR (this_command_keys
)->contents
[next_event
++];
501 /* Find the next parameterized event. */
502 while (next_event
< this_command_key_count
503 && ! (EVENT_HAS_PARAMETERS
504 (XVECTOR (this_command_keys
)->contents
[next_event
])))
509 case 'm': /* Value of mark. Does not do I/O. */
511 /* visargs[i] = Qnil; */
512 args
[i
] = current_buffer
->mark
;
516 case 'N': /* Prefix arg, else number from minibuffer */
517 if (!NILP (prefix_arg
))
518 goto have_prefix_arg
;
519 case 'n': /* Read number from minibuffer. */
521 args
[i
] = Fread_minibuffer (build_string (prompt
), Qnil
);
522 while (! NUMBERP (args
[i
]));
523 visargs
[i
] = last_minibuf_string
;
526 case 'P': /* Prefix arg in raw form. Does no I/O. */
528 args
[i
] = prefix_arg
;
529 /* visargs[i] = Qnil; */
533 case 'p': /* Prefix arg converted to number. No I/O. */
534 args
[i
] = Fprefix_numeric_value (prefix_arg
);
535 /* visargs[i] = Qnil; */
539 case 'r': /* Region, point and mark as 2 args. */
541 Fset_marker (point_marker
, make_number (PT
), Qnil
);
542 /* visargs[i+1] = Qnil; */
543 foo
= marker_position (current_buffer
->mark
);
544 /* visargs[i] = Qnil; */
545 args
[i
] = point
< foo
? point_marker
: current_buffer
->mark
;
547 args
[++i
] = point
> foo
? point_marker
: current_buffer
->mark
;
551 case 's': /* String read via minibuffer. */
552 args
[i
] = Fread_string (build_string (prompt
), Qnil
, Qnil
);
555 case 'S': /* Any symbol. */
556 visargs
[i
] = Fread_string (build_string (prompt
), Qnil
, Qnil
);
557 /* Passing args[i] directly stimulates compiler bug */
559 args
[i
] = Fintern (teml
, Qnil
);
562 case 'v': /* Variable name: symbol that is
564 args
[i
] = Fread_variable (build_string (prompt
));
565 visargs
[i
] = last_minibuf_string
;
568 case 'x': /* Lisp expression read but not evaluated */
569 args
[i
] = Fread_minibuffer (build_string (prompt
), Qnil
);
570 visargs
[i
] = last_minibuf_string
;
573 case 'X': /* Lisp expression read and evaluated */
574 args
[i
] = Feval_minibuffer (build_string (prompt
), Qnil
);
575 visargs
[i
] = last_minibuf_string
;
578 /* We have a case for `+' so we get an error
579 if anyone tries to define one here. */
582 error ("Invalid control letter `%c' (%03o) in interactive calling string",
589 if (NILP (visargs
[i
]) && STRINGP (args
[i
]))
590 visargs
[i
] = args
[i
];
592 tem
= (unsigned char *) index (tem
, '\n');
594 else tem
= (unsigned char *) "";
596 unbind_to (speccount
, Qnil
);
602 if (arg_from_tty
|| !NILP (record
))
604 visargs
[0] = function
;
605 for (i
= 1; i
< count
+ 1; i
++)
608 visargs
[i
] = Fcons (intern (callint_argfuns
[varies
[i
]]), Qnil
);
610 visargs
[i
] = quotify_arg (args
[i
]);
612 Vcommand_history
= Fcons (Flist (count
+ 1, visargs
),
616 /* If we used a marker to hold point, mark, or an end of the region,
617 temporarily, convert it to an integer now. */
618 for (i
= 1; i
<= count
; i
++)
619 if (varies
[i
] >= 1 && varies
[i
] <= 4)
620 XSETINT (args
[i
], marker_position (args
[i
]));
622 single_kboard_state ();
626 specbind (Qcommand_debug_status
, Qnil
);
628 val
= Ffuncall (count
+ 1, args
);
630 return unbind_to (speccount
, val
);
634 DEFUN ("prefix-numeric-value", Fprefix_numeric_value
, Sprefix_numeric_value
,
636 "Return numeric meaning of raw prefix argument ARG.\n\
637 A raw prefix argument is what you get from `(interactive \"P\")'.\n\
638 Its numeric meaning is what you would get from `(interactive \"p\")'.")
645 XSETFASTINT (val
, 1);
646 else if (EQ (raw
, Qminus
))
648 else if (CONSP (raw
) && INTEGERP (XCONS (raw
)->car
))
649 XSETINT (val
, XINT (XCONS (raw
)->car
));
650 else if (INTEGERP (raw
))
653 XSETFASTINT (val
, 1);
660 point_marker
= Fmake_marker ();
661 staticpro (&point_marker
);
663 preserved_fns
= Fcons (intern ("region-beginning"),
664 Fcons (intern ("region-end"),
665 Fcons (intern ("point"),
666 Fcons (intern ("mark"), Qnil
))));
667 staticpro (&preserved_fns
);
669 Qlist
= intern ("list");
672 Qminus
= intern ("-");
675 Qplus
= intern ("+");
678 Qcall_interactively
= intern ("call-interactively");
679 staticpro (&Qcall_interactively
);
681 Qcommand_debug_status
= intern ("command-debug-status");
682 staticpro (&Qcommand_debug_status
);
684 Qenable_recursive_minibuffers
= intern ("enable-recursive-minibuffers");
685 staticpro (&Qenable_recursive_minibuffers
);
687 Qmouse_leave_buffer_hook
= intern ("mouse-leave-buffer-hook");
688 staticpro (&Qmouse_leave_buffer_hook
);
690 DEFVAR_KBOARD ("prefix-arg", Vprefix_arg
,
691 "The value of the prefix argument for the next editing command.\n\
692 It may be a number, or the symbol `-' for just a minus sign as arg,\n\
693 or a list whose car is a number for just one or more C-U's\n\
694 or nil if no argument has been specified.\n\
696 You cannot examine this variable to find the argument for this command\n\
697 since it has been set to nil by the time you can look.\n\
698 Instead, you should use the variable `current-prefix-arg', although\n\
699 normally commands can get this prefix argument with (interactive \"P\").");
701 DEFVAR_LISP ("current-prefix-arg", &Vcurrent_prefix_arg
,
702 "The value of the prefix argument for this editing command.\n\
703 It may be a number, or the symbol `-' for just a minus sign as arg,\n\
704 or a list whose car is a number for just one or more C-U's\n\
705 or nil if no argument has been specified.\n\
706 This is what `(interactive \"P\")' returns.");
707 Vcurrent_prefix_arg
= Qnil
;
709 DEFVAR_LISP ("command-history", &Vcommand_history
,
710 "List of recent commands that read arguments from terminal.\n\
711 Each command is represented as a form to evaluate.");
712 Vcommand_history
= Qnil
;
714 DEFVAR_LISP ("command-debug-status", &Vcommand_debug_status
,
715 "Debugging status of current interactive command.\n\
716 Bound each time `call-interactively' is called;\n\
717 may be set by the debugger as a reminder for itself.");
718 Vcommand_debug_status
= Qnil
;
720 DEFVAR_LISP ("mark-even-if-inactive", &Vmark_even_if_inactive
,
721 "*Non-nil means you can use the mark even when inactive.\n\
722 This option makes a difference in Transient Mark mode.\n\
723 When the option is non-nil, deactivation of the mark\n\
724 turns off region highlighting, but commands that use the mark\n\
725 behave as if the mark were still active.");
726 Vmark_even_if_inactive
= Qnil
;
728 DEFVAR_LISP ("mouse-leave-buffer-hook", &Vmouse_leave_buffer_hook
,
729 "Hook to run when about to switch windows with a mouse command.\n\
730 Its purpose is to give temporary modes such as Isearch mode\n\
731 a way to turn themselves off when a mouse command switches windows.");
732 Vmouse_leave_buffer_hook
= Qnil
;
734 defsubr (&Sinteractive
);
735 defsubr (&Scall_interactively
);
736 defsubr (&Sprefix_numeric_value
);