root/src/macros.c

DEFINITIONS

1. end_kbd_macro
2. store_kbd_macro_char
3. finalize_kbd_macro_chars
4. DEFUN
5. DEFUN
6. pop_kbd_macro
7. init_macros
8. syms_of_macros

     1 /* Keyboard macros.
     2 
     3 Copyright (C) 1985-1986, 1993, 2000-2023 Free Software Foundation, Inc.
     4 
     5 This file is part of GNU Emacs.
     6 
     7 GNU Emacs is free software: you can redistribute it and/or modify
     8 it under the terms of the GNU General Public License as published by
     9 the Free Software Foundation, either version 3 of the License, or (at
    10 your option) any later version.
    11 
    12 GNU Emacs is distributed in the hope that it will be useful,
    13 but WITHOUT ANY WARRANTY; without even the implied warranty of
    14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    15 GNU General Public License for more details.
    16 
    17 You should have received a copy of the GNU General Public License
    18 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
    19 
    20 
    21 #include <config.h>
    22 
    23 #include "lisp.h"
    24 #include "macros.h"
    25 #include "window.h"
    26 #include "keyboard.h"
    27 
    28 /* Number of successful iterations so far
    29    for innermost keyboard macro.
    30    This is not bound at each level,
    31    so after an error, it describes the innermost interrupted macro.  */
    32 
    33 EMACS_INT executing_kbd_macro_iterations;
    34 
    35 /* This is the macro that was executing.
    36    This is not bound at each level,
    37    so after an error, it describes the innermost interrupted macro.
    38    We use it only as a kind of flag, so no need to protect it.  */
    39 
    40 Lisp_Object executing_kbd_macro;
    41 
    42 DEFUN ("start-kbd-macro", Fstart_kbd_macro, Sstart_kbd_macro, 1, 2, "P",
    43        doc: /* Record subsequent keyboard input, defining a keyboard macro.
    44 The commands are recorded even as they are executed.
    45 Use \\[end-kbd-macro] to finish recording and make the macro available.
    46 Use \\[name-last-kbd-macro] to give it a permanent name.
    47 Non-nil arg (prefix arg) means append to last macro defined;
    48 this begins by re-executing that macro as if you typed it again.
    49 If optional second arg, NO-EXEC, is non-nil, do not re-execute last
    50 macro before appending to it.  */)
    51   (Lisp_Object append, Lisp_Object no_exec)
    52 {
    53   if (!NILP (KVAR (current_kboard, defining_kbd_macro)))
    54     error ("Already defining kbd macro");
    55 
    56   if (!current_kboard->kbd_macro_buffer)
    57     {
    58       current_kboard->kbd_macro_buffer = xmalloc (30 * word_size);
    59       current_kboard->kbd_macro_bufsize = 30;
    60       current_kboard->kbd_macro_ptr = current_kboard->kbd_macro_buffer;
    61       current_kboard->kbd_macro_end = current_kboard->kbd_macro_buffer;
    62     }
    63   update_mode_lines = 19;
    64   if (NILP (append))
    65     {
    66       if (current_kboard->kbd_macro_bufsize > 200)
    67         {
    68           current_kboard->kbd_macro_buffer
    69             = xrealloc (current_kboard->kbd_macro_buffer,
    70                         30 * word_size);
    71           current_kboard->kbd_macro_bufsize = 30;
    72         }
    73       current_kboard->kbd_macro_ptr = current_kboard->kbd_macro_buffer;
    74       current_kboard->kbd_macro_end = current_kboard->kbd_macro_buffer;
    75       message1 ("Defining kbd macro...");
    76     }
    77   else
    78     {
    79       int incr = 30;
    80       ptrdiff_t i, len;
    81       bool cvt;
    82 
    83       /* Check the type of last-kbd-macro in case Lisp code changed it.  */
    84       len = CHECK_VECTOR_OR_STRING (KVAR (current_kboard, Vlast_kbd_macro));
    85 
    86       /* Copy last-kbd-macro into the buffer, in case the Lisp code
    87          has put another macro there.  */
    88       if (current_kboard->kbd_macro_bufsize - incr < len)
    89         current_kboard->kbd_macro_buffer =
    90           xpalloc (current_kboard->kbd_macro_buffer,
    91                    &current_kboard->kbd_macro_bufsize,
    92                    len - current_kboard->kbd_macro_bufsize + incr, -1,
    93                    sizeof *current_kboard->kbd_macro_buffer);
    94 
    95       /* Must convert meta modifier when copying string to vector.  */
    96       cvt = STRINGP (KVAR (current_kboard, Vlast_kbd_macro));
    97       for (i = 0; i < len; i++)
    98         {
    99           Lisp_Object c;
   100           c = Faref (KVAR (current_kboard, Vlast_kbd_macro), make_fixnum (i));
   101           if (cvt && FIXNATP (c) && (XFIXNAT (c) & 0x80))
   102             XSETFASTINT (c, CHAR_META | (XFIXNAT (c) & ~0x80));
   103           current_kboard->kbd_macro_buffer[i] = c;
   104         }
   105 
   106       current_kboard->kbd_macro_ptr = current_kboard->kbd_macro_buffer + len;
   107       current_kboard->kbd_macro_end = current_kboard->kbd_macro_ptr;
   108 
   109       /* Re-execute the macro we are appending to,
   110          for consistency of behavior.  */
   111       if (NILP (no_exec))
   112         Fexecute_kbd_macro (KVAR (current_kboard, Vlast_kbd_macro),
   113                             make_fixnum (1), Qnil);
   114 
   115       message1 ("Appending to kbd macro...");
   116     }
   117   kset_defining_kbd_macro (current_kboard, Qt);
   118 
   119   return Qnil;
   120 }
   121 
   122 /* Finish defining the current keyboard macro.  */
   123 
   124 void
   125 end_kbd_macro (void)
   126 {
   127   kset_defining_kbd_macro (current_kboard, Qnil);
   128   update_mode_lines = 20;
   129   kset_last_kbd_macro
   130     (current_kboard,
   131      Fvector ((current_kboard->kbd_macro_end
   132                - current_kboard->kbd_macro_buffer),
   133               current_kboard->kbd_macro_buffer));
   134 }
   135 
   136 DEFUN ("end-kbd-macro", Fend_kbd_macro, Send_kbd_macro, 0, 2, "p",
   137        doc: /* Finish defining a keyboard macro.
   138 The definition was started by \\[start-kbd-macro].
   139 The macro is now available for use via \\[call-last-kbd-macro],
   140 or it can be given a name with \\[name-last-kbd-macro] and then invoked
   141 under that name.
   142 
   143 With numeric arg, repeat macro now that many times,
   144 counting the definition just completed as the first repetition.
   145 An argument of zero means repeat until error.
   146 
   147 In Lisp, optional second arg LOOPFUNC may be a function that is called prior to
   148 each iteration of the macro.  Iteration stops if LOOPFUNC returns nil.  */)
   149   (Lisp_Object repeat, Lisp_Object loopfunc)
   150 {
   151   if (NILP (KVAR (current_kboard, defining_kbd_macro)))
   152     error ("Not defining kbd macro");
   153 
   154   if (NILP (repeat))
   155     XSETFASTINT (repeat, 1);
   156   else
   157     CHECK_FIXNUM (repeat);
   158 
   159   if (!NILP (KVAR (current_kboard, defining_kbd_macro)))
   160     {
   161       end_kbd_macro ();
   162       message1 ("Keyboard macro defined");
   163     }
   164 
   165   if (XFIXNAT (repeat) == 0)
   166     Fexecute_kbd_macro (KVAR (current_kboard, Vlast_kbd_macro), repeat, loopfunc);
   167   else if (XFIXNUM (repeat) > 1)
   168     {
   169       XSETINT (repeat, XFIXNUM (repeat) - 1);
   170       Fexecute_kbd_macro (KVAR (current_kboard, Vlast_kbd_macro),
   171                           repeat, loopfunc);
   172     }
   173   return Qnil;
   174 }
   175 
   176 /* Store character c into kbd macro being defined.  */
   177 
   178 void
   179 store_kbd_macro_char (Lisp_Object c)
   180 {
   181   struct kboard *kb = current_kboard;
   182 
   183   if (!NILP (KVAR (kb, defining_kbd_macro)))
   184     {
   185       if (kb->kbd_macro_ptr - kb->kbd_macro_buffer == kb->kbd_macro_bufsize)
   186         {
   187           ptrdiff_t ptr_offset = kb->kbd_macro_ptr - kb->kbd_macro_buffer;
   188           ptrdiff_t end_offset = kb->kbd_macro_end - kb->kbd_macro_buffer;
   189           kb->kbd_macro_buffer = xpalloc (kb->kbd_macro_buffer,
   190                                           &kb->kbd_macro_bufsize,
   191                                           1, -1, sizeof *kb->kbd_macro_buffer);
   192           kb->kbd_macro_ptr = kb->kbd_macro_buffer + ptr_offset;
   193           kb->kbd_macro_end = kb->kbd_macro_buffer + end_offset;
   194         }
   195 
   196       *kb->kbd_macro_ptr++ = c;
   197     }
   198 }
   199 
   200 /* Declare that all chars stored so far in the kbd macro being defined
   201  really belong to it.  This is done in between editor commands.  */
   202 
   203 void
   204 finalize_kbd_macro_chars (void)
   205 {
   206   current_kboard->kbd_macro_end = current_kboard->kbd_macro_ptr;
   207 }
   208 
   209 DEFUN ("cancel-kbd-macro-events", Fcancel_kbd_macro_events,
   210        Scancel_kbd_macro_events, 0, 0, 0,
   211        doc: /* Cancel the events added to a keyboard macro for this command.  */)
   212   (void)
   213 {
   214   current_kboard->kbd_macro_ptr = current_kboard->kbd_macro_end;
   215   return Qnil;
   216 }
   217 
   218 DEFUN ("store-kbd-macro-event", Fstore_kbd_macro_event,
   219        Sstore_kbd_macro_event, 1, 1, 0,
   220        doc: /* Store EVENT into the keyboard macro being defined.  */)
   221   (Lisp_Object event)
   222 {
   223   store_kbd_macro_char (event);
   224   return Qnil;
   225 }
   226 
   227 DEFUN ("call-last-kbd-macro", Fcall_last_kbd_macro, Scall_last_kbd_macro,
   228        0, 2, "p",
   229        doc: /* Call the last keyboard macro that you defined with \\[start-kbd-macro].
   230 
   231 A prefix argument serves as a repeat count.  Zero means repeat until error.
   232 
   233 To make a macro permanent so you can call it even after
   234 defining others, use \\[name-last-kbd-macro].
   235 
   236 In Lisp, optional second arg LOOPFUNC may be a function that is called prior to
   237 each iteration of the macro.  Iteration stops if LOOPFUNC returns nil.  */)
   238   (Lisp_Object prefix, Lisp_Object loopfunc)
   239 {
   240   /* Don't interfere with recognition of the previous command
   241      from before this macro started.  */
   242   Vthis_command = KVAR (current_kboard, Vlast_command);
   243   /* C-x z after the macro should repeat the macro.  */
   244   Vreal_this_command = KVAR (current_kboard, Vlast_kbd_macro);
   245 
   246   if (! NILP (KVAR (current_kboard, defining_kbd_macro)))
   247     error ("Can't execute anonymous macro while defining one");
   248   else if (NILP (KVAR (current_kboard, Vlast_kbd_macro)))
   249     error ("No kbd macro has been defined");
   250   else
   251     Fexecute_kbd_macro (KVAR (current_kboard, Vlast_kbd_macro), prefix, loopfunc);
   252 
   253   /* command_loop_1 sets this to nil before it returns;
   254      get back the last command within the macro
   255      so that it can be last, again, after we return.  */
   256   Vthis_command = KVAR (current_kboard, Vlast_command);
   257 
   258   return Qnil;
   259 }
   260 
   261 /* Restore Vexecuting_kbd_macro and executing_kbd_macro_index.
   262    Called when the unwind-protect in Fexecute_kbd_macro gets invoked.  */
   263 
   264 static void
   265 pop_kbd_macro (Lisp_Object info)
   266 {
   267   Lisp_Object tem;
   268   Vexecuting_kbd_macro = XCAR (info);
   269   tem = XCDR (info);
   270   integer_to_intmax (XCAR (tem), &executing_kbd_macro_index);
   271   Vreal_this_command = XCDR (tem);
   272   run_hook (Qkbd_macro_termination_hook);
   273 }
   274 
   275 DEFUN ("execute-kbd-macro", Fexecute_kbd_macro, Sexecute_kbd_macro, 1, 3, 0,
   276        doc: /* Execute MACRO as a sequence of events.
   277 If MACRO is a string or vector, then the events in it are executed
   278 exactly as if they had been input by the user.
   279 
   280 If MACRO is a symbol, its function definition is used.  If that is
   281 another symbol, this process repeats.  Eventually the result should be
   282 a string or vector.  If the result is not a symbol, string, or vector,
   283 an error is signaled.
   284 
   285 COUNT is a repeat count, or nil for once, or 0 for infinite loop.
   286 
   287 Optional third arg LOOPFUNC may be a function that is called prior to
   288 each iteration of the macro.  Iteration stops if LOOPFUNC returns nil.
   289 
   290 The buffer shown in the currently selected window will be made the current
   291 buffer before the macro is executed.  */)
   292   (Lisp_Object macro, Lisp_Object count, Lisp_Object loopfunc)
   293 {
   294   Lisp_Object final;
   295   Lisp_Object tem;
   296   specpdl_ref pdlcount = SPECPDL_INDEX ();
   297   EMACS_INT repeat = 1;
   298   EMACS_INT success_count = 0;
   299 
   300   executing_kbd_macro_iterations = 0;
   301 
   302   if (!NILP (count))
   303     {
   304       count = Fprefix_numeric_value (count);
   305       repeat = XFIXNUM (count);
   306     }
   307 
   308   final = indirect_function (macro);
   309   if (!STRINGP (final) && !VECTORP (final))
   310     error ("Keyboard macros must be strings or vectors");
   311 
   312   tem = Fcons (Vexecuting_kbd_macro,
   313                Fcons (make_int (executing_kbd_macro_index),
   314                       Vreal_this_command));
   315   record_unwind_protect (pop_kbd_macro, tem);
   316 
   317   do
   318     {
   319       Vexecuting_kbd_macro = final;
   320       executing_kbd_macro = final;
   321       executing_kbd_macro_index = 0;
   322 
   323       kset_prefix_arg (current_kboard, Qnil);
   324 
   325       if (!NILP (loopfunc))
   326         {
   327           Lisp_Object cont;
   328           cont = call0 (loopfunc);
   329           if (NILP (cont))
   330             break;
   331         }
   332 
   333       command_loop_2 (list1 (Qminibuffer_quit));
   334 
   335       executing_kbd_macro_iterations = ++success_count;
   336 
   337       maybe_quit ();
   338     }
   339   while (--repeat
   340          && (STRINGP (Vexecuting_kbd_macro) || VECTORP (Vexecuting_kbd_macro)));
   341 
   342   executing_kbd_macro = Qnil;
   343 
   344   Vreal_this_command = Vexecuting_kbd_macro;
   345 
   346   return unbind_to (pdlcount, Qnil);
   347 }
   348 
   349 void
   350 init_macros (void)
   351 {
   352   Vexecuting_kbd_macro = Qnil;
   353   executing_kbd_macro = Qnil;
   354 }
   355 
   356 void
   357 syms_of_macros (void)
   358 {
   359   DEFVAR_LISP ("kbd-macro-termination-hook", Vkbd_macro_termination_hook,
   360                doc: /* Normal hook run whenever a keyboard macro terminates.
   361 This is run whether the macro ends normally or prematurely due to an error.  */);
   362   Vkbd_macro_termination_hook = Qnil;
   363   DEFSYM (Qkbd_macro_termination_hook, "kbd-macro-termination-hook");
   364 
   365   defsubr (&Sstart_kbd_macro);
   366   defsubr (&Send_kbd_macro);
   367   defsubr (&Scall_last_kbd_macro);
   368   defsubr (&Sexecute_kbd_macro);
   369   defsubr (&Scancel_kbd_macro_events);
   370   defsubr (&Sstore_kbd_macro_event);
   371 
   372   DEFVAR_KBOARD ("defining-kbd-macro", defining_kbd_macro,
   373                  doc: /* Non-nil while a keyboard macro is being defined.  Don't set this!
   374 The value is the symbol `append' while appending to the definition of
   375 an existing macro.  */);
   376 
   377   DEFVAR_LISP ("executing-kbd-macro", Vexecuting_kbd_macro,
   378                doc: /* Currently executing keyboard macro (string or vector).
   379 This is nil when not executing a keyboard macro.  */);
   380 
   381   DEFVAR_INT ("executing-kbd-macro-index", executing_kbd_macro_index,
   382               doc: /* Index in currently executing keyboard macro; undefined if none executing.  */);
   383 
   384   DEFVAR_KBOARD ("last-kbd-macro", Vlast_kbd_macro,
   385                  doc: /* Last kbd macro defined, as a string or vector; nil if none defined.  */);
   386 }