Tweak previous doc fix.
[emacs.git] / src / undo.c
blobb9e615086f9bad291e9e87c722aee4888f9b6feb
1 /* undo handling for GNU Emacs.
2 Copyright (C) 1990, 1993, 1994, 2000, 2001, 2002, 2003, 2004,
3 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
5 This file is part of GNU Emacs.
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
10 (at your option) any later version.
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.
17 You should have received a copy of the GNU General Public License
18 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
21 #include <config.h>
22 #include "lisp.h"
23 #include "buffer.h"
24 #include "commands.h"
25 #include "window.h"
27 /* Limits controlling how much undo information to keep. */
29 EMACS_INT undo_limit;
30 EMACS_INT undo_strong_limit;
32 Lisp_Object Vundo_outer_limit;
34 /* Function to call when undo_outer_limit is exceeded. */
36 Lisp_Object Vundo_outer_limit_function;
38 /* Last buffer for which undo information was recorded. */
39 /* BEWARE: This is not traced by the GC, so never dereference it! */
40 struct buffer *last_undo_buffer;
42 /* Position of point last time we inserted a boundary. */
43 struct buffer *last_boundary_buffer;
44 EMACS_INT last_boundary_position;
46 Lisp_Object Qinhibit_read_only;
48 /* Marker for function call undo list elements. */
50 Lisp_Object Qapply;
52 /* The first time a command records something for undo.
53 it also allocates the undo-boundary object
54 which will be added to the list at the end of the command.
55 This ensures we can't run out of space while trying to make
56 an undo-boundary. */
57 Lisp_Object pending_boundary;
59 /* Nonzero means do not record point in record_point. */
61 int undo_inhibit_record_point;
63 /* Record point as it was at beginning of this command (if necessary)
64 and prepare the undo info for recording a change.
65 PT is the position of point that will naturally occur as a result of the
66 undo record that will be added just after this command terminates. */
68 static void
69 record_point (pt)
70 int pt;
72 int at_boundary;
74 /* Don't record position of pt when undo_inhibit_record_point holds. */
75 if (undo_inhibit_record_point)
76 return;
78 /* Allocate a cons cell to be the undo boundary after this command. */
79 if (NILP (pending_boundary))
80 pending_boundary = Fcons (Qnil, Qnil);
82 if ((current_buffer != last_undo_buffer)
83 /* Don't call Fundo_boundary for the first change. Otherwise we
84 risk overwriting last_boundary_position in Fundo_boundary with
85 PT of the current buffer and as a consequence not insert an
86 undo boundary because last_boundary_position will equal pt in
87 the test at the end of the present function (Bug#731). */
88 && (MODIFF > SAVE_MODIFF))
89 Fundo_boundary ();
90 last_undo_buffer = current_buffer;
92 if (CONSP (current_buffer->undo_list))
94 /* Set AT_BOUNDARY to 1 only when we have nothing other than
95 marker adjustment before undo boundary. */
97 Lisp_Object tail = current_buffer->undo_list, elt;
99 while (1)
101 if (NILP (tail))
102 elt = Qnil;
103 else
104 elt = XCAR (tail);
105 if (NILP (elt) || ! (CONSP (elt) && MARKERP (XCAR (elt))))
106 break;
107 tail = XCDR (tail);
109 at_boundary = NILP (elt);
111 else
112 at_boundary = 1;
114 if (MODIFF <= SAVE_MODIFF)
115 record_first_change ();
117 /* If we are just after an undo boundary, and
118 point wasn't at start of deleted range, record where it was. */
119 if (at_boundary
120 && current_buffer == last_boundary_buffer
121 && last_boundary_position != pt)
122 current_buffer->undo_list
123 = Fcons (make_number (last_boundary_position), current_buffer->undo_list);
126 /* Record an insertion that just happened or is about to happen,
127 for LENGTH characters at position BEG.
128 (It is possible to record an insertion before or after the fact
129 because we don't need to record the contents.) */
131 void
132 record_insert (beg, length)
133 int beg, length;
135 Lisp_Object lbeg, lend;
137 if (EQ (current_buffer->undo_list, Qt))
138 return;
140 record_point (beg);
142 /* If this is following another insertion and consecutive with it
143 in the buffer, combine the two. */
144 if (CONSP (current_buffer->undo_list))
146 Lisp_Object elt;
147 elt = XCAR (current_buffer->undo_list);
148 if (CONSP (elt)
149 && INTEGERP (XCAR (elt))
150 && INTEGERP (XCDR (elt))
151 && XINT (XCDR (elt)) == beg)
153 XSETCDR (elt, make_number (beg + length));
154 return;
158 XSETFASTINT (lbeg, beg);
159 XSETINT (lend, beg + length);
160 current_buffer->undo_list = Fcons (Fcons (lbeg, lend),
161 current_buffer->undo_list);
164 /* Record that a deletion is about to take place,
165 of the characters in STRING, at location BEG. */
167 void
168 record_delete (beg, string)
169 int beg;
170 Lisp_Object string;
172 Lisp_Object sbeg;
174 if (EQ (current_buffer->undo_list, Qt))
175 return;
177 if (PT == beg + SCHARS (string))
179 XSETINT (sbeg, -beg);
180 record_point (PT);
182 else
184 XSETFASTINT (sbeg, beg);
185 record_point (beg);
188 current_buffer->undo_list
189 = Fcons (Fcons (string, sbeg), current_buffer->undo_list);
192 /* Record the fact that MARKER is about to be adjusted by ADJUSTMENT.
193 This is done only when a marker points within text being deleted,
194 because that's the only case where an automatic marker adjustment
195 won't be inverted automatically by undoing the buffer modification. */
197 void
198 record_marker_adjustment (marker, adjustment)
199 Lisp_Object marker;
200 int adjustment;
202 if (EQ (current_buffer->undo_list, Qt))
203 return;
205 /* Allocate a cons cell to be the undo boundary after this command. */
206 if (NILP (pending_boundary))
207 pending_boundary = Fcons (Qnil, Qnil);
209 if (current_buffer != last_undo_buffer)
210 Fundo_boundary ();
211 last_undo_buffer = current_buffer;
213 current_buffer->undo_list
214 = Fcons (Fcons (marker, make_number (adjustment)),
215 current_buffer->undo_list);
218 /* Record that a replacement is about to take place,
219 for LENGTH characters at location BEG.
220 The replacement must not change the number of characters. */
222 void
223 record_change (beg, length)
224 int beg, length;
226 record_delete (beg, make_buffer_string (beg, beg + length, 1));
227 record_insert (beg, length);
230 /* Record that an unmodified buffer is about to be changed.
231 Record the file modification date so that when undoing this entry
232 we can tell whether it is obsolete because the file was saved again. */
234 void
235 record_first_change ()
237 Lisp_Object high, low;
238 struct buffer *base_buffer = current_buffer;
240 if (EQ (current_buffer->undo_list, Qt))
241 return;
243 if (current_buffer != last_undo_buffer)
244 Fundo_boundary ();
245 last_undo_buffer = current_buffer;
247 if (base_buffer->base_buffer)
248 base_buffer = base_buffer->base_buffer;
250 XSETFASTINT (high, (base_buffer->modtime >> 16) & 0xffff);
251 XSETFASTINT (low, base_buffer->modtime & 0xffff);
252 current_buffer->undo_list = Fcons (Fcons (Qt, Fcons (high, low)), current_buffer->undo_list);
255 /* Record a change in property PROP (whose old value was VAL)
256 for LENGTH characters starting at position BEG in BUFFER. */
258 void
259 record_property_change (beg, length, prop, value, buffer)
260 int beg, length;
261 Lisp_Object prop, value, buffer;
263 Lisp_Object lbeg, lend, entry;
264 struct buffer *obuf = current_buffer, *buf = XBUFFER (buffer);
265 int boundary = 0;
267 if (EQ (buf->undo_list, Qt))
268 return;
270 /* Allocate a cons cell to be the undo boundary after this command. */
271 if (NILP (pending_boundary))
272 pending_boundary = Fcons (Qnil, Qnil);
274 if (buf != last_undo_buffer)
275 boundary = 1;
276 last_undo_buffer = buf;
278 /* Switch temporarily to the buffer that was changed. */
279 current_buffer = buf;
281 if (boundary)
282 Fundo_boundary ();
284 if (MODIFF <= SAVE_MODIFF)
285 record_first_change ();
287 XSETINT (lbeg, beg);
288 XSETINT (lend, beg + length);
289 entry = Fcons (Qnil, Fcons (prop, Fcons (value, Fcons (lbeg, lend))));
290 current_buffer->undo_list = Fcons (entry, current_buffer->undo_list);
292 current_buffer = obuf;
295 DEFUN ("undo-boundary", Fundo_boundary, Sundo_boundary, 0, 0, 0,
296 doc: /* Mark a boundary between units of undo.
297 An undo command will stop at this point,
298 but another undo command will undo to the previous boundary. */)
301 Lisp_Object tem;
302 if (EQ (current_buffer->undo_list, Qt))
303 return Qnil;
304 tem = Fcar (current_buffer->undo_list);
305 if (!NILP (tem))
307 /* One way or another, cons nil onto the front of the undo list. */
308 if (!NILP (pending_boundary))
310 /* If we have preallocated the cons cell to use here,
311 use that one. */
312 XSETCDR (pending_boundary, current_buffer->undo_list);
313 current_buffer->undo_list = pending_boundary;
314 pending_boundary = Qnil;
316 else
317 current_buffer->undo_list = Fcons (Qnil, current_buffer->undo_list);
319 last_boundary_position = PT;
320 last_boundary_buffer = current_buffer;
321 return Qnil;
324 /* At garbage collection time, make an undo list shorter at the end,
325 returning the truncated list. How this is done depends on the
326 variables undo-limit, undo-strong-limit and undo-outer-limit.
327 In some cases this works by calling undo-outer-limit-function. */
329 void
330 truncate_undo_list (b)
331 struct buffer *b;
333 Lisp_Object list;
334 Lisp_Object prev, next, last_boundary;
335 int size_so_far = 0;
337 /* Make sure that calling undo-outer-limit-function
338 won't cause another GC. */
339 int count = inhibit_garbage_collection ();
341 /* Make the buffer current to get its local values of variables such
342 as undo_limit. Also so that Vundo_outer_limit_function can
343 tell which buffer to operate on. */
344 record_unwind_protect (set_buffer_if_live, Fcurrent_buffer ());
345 set_buffer_internal (b);
347 list = b->undo_list;
349 prev = Qnil;
350 next = list;
351 last_boundary = Qnil;
353 /* If the first element is an undo boundary, skip past it. */
354 if (CONSP (next) && NILP (XCAR (next)))
356 /* Add in the space occupied by this element and its chain link. */
357 size_so_far += sizeof (struct Lisp_Cons);
359 /* Advance to next element. */
360 prev = next;
361 next = XCDR (next);
364 /* Always preserve at least the most recent undo record
365 unless it is really horribly big.
367 Skip, skip, skip the undo, skip, skip, skip the undo,
368 Skip, skip, skip the undo, skip to the undo bound'ry. */
370 while (CONSP (next) && ! NILP (XCAR (next)))
372 Lisp_Object elt;
373 elt = XCAR (next);
375 /* Add in the space occupied by this element and its chain link. */
376 size_so_far += sizeof (struct Lisp_Cons);
377 if (CONSP (elt))
379 size_so_far += sizeof (struct Lisp_Cons);
380 if (STRINGP (XCAR (elt)))
381 size_so_far += (sizeof (struct Lisp_String) - 1
382 + SCHARS (XCAR (elt)));
385 /* Advance to next element. */
386 prev = next;
387 next = XCDR (next);
390 /* If by the first boundary we have already passed undo_outer_limit,
391 we're heading for memory full, so offer to clear out the list. */
392 if (INTEGERP (Vundo_outer_limit)
393 && size_so_far > XINT (Vundo_outer_limit)
394 && !NILP (Vundo_outer_limit_function))
396 Lisp_Object tem;
397 struct buffer *temp = last_undo_buffer;
399 /* Normally the function this calls is undo-outer-limit-truncate. */
400 tem = call1 (Vundo_outer_limit_function, make_number (size_so_far));
401 if (! NILP (tem))
403 /* The function is responsible for making
404 any desired changes in buffer-undo-list. */
405 unbind_to (count, Qnil);
406 return;
408 /* That function probably used the minibuffer, and if so, that
409 changed last_undo_buffer. Change it back so that we don't
410 force next change to make an undo boundary here. */
411 last_undo_buffer = temp;
414 if (CONSP (next))
415 last_boundary = prev;
417 /* Keep additional undo data, if it fits in the limits. */
418 while (CONSP (next))
420 Lisp_Object elt;
421 elt = XCAR (next);
423 /* When we get to a boundary, decide whether to truncate
424 either before or after it. The lower threshold, undo_limit,
425 tells us to truncate after it. If its size pushes past
426 the higher threshold undo_strong_limit, we truncate before it. */
427 if (NILP (elt))
429 if (size_so_far > undo_strong_limit)
430 break;
431 last_boundary = prev;
432 if (size_so_far > undo_limit)
433 break;
436 /* Add in the space occupied by this element and its chain link. */
437 size_so_far += sizeof (struct Lisp_Cons);
438 if (CONSP (elt))
440 size_so_far += sizeof (struct Lisp_Cons);
441 if (STRINGP (XCAR (elt)))
442 size_so_far += (sizeof (struct Lisp_String) - 1
443 + SCHARS (XCAR (elt)));
446 /* Advance to next element. */
447 prev = next;
448 next = XCDR (next);
451 /* If we scanned the whole list, it is short enough; don't change it. */
452 if (NILP (next))
454 /* Truncate at the boundary where we decided to truncate. */
455 else if (!NILP (last_boundary))
456 XSETCDR (last_boundary, Qnil);
457 /* There's nothing we decided to keep, so clear it out. */
458 else
459 b->undo_list = Qnil;
461 unbind_to (count, Qnil);
464 DEFUN ("primitive-undo", Fprimitive_undo, Sprimitive_undo, 2, 2, 0,
465 doc: /* Undo N records from the front of the list LIST.
466 Return what remains of the list. */)
467 (n, list)
468 Lisp_Object n, list;
470 struct gcpro gcpro1, gcpro2;
471 Lisp_Object next;
472 int count = SPECPDL_INDEX ();
473 register int arg;
474 Lisp_Object oldlist;
475 int did_apply = 0;
477 #if 0 /* This is a good feature, but would make undo-start
478 unable to do what is expected. */
479 Lisp_Object tem;
481 /* If the head of the list is a boundary, it is the boundary
482 preceding this command. Get rid of it and don't count it. */
483 tem = Fcar (list);
484 if (NILP (tem))
485 list = Fcdr (list);
486 #endif
488 CHECK_NUMBER (n);
489 arg = XINT (n);
490 next = Qnil;
491 GCPRO2 (next, list);
492 /* I don't think we need to gcpro oldlist, as we use it only
493 to check for EQ. ++kfs */
495 /* In a writable buffer, enable undoing read-only text that is so
496 because of text properties. */
497 if (NILP (current_buffer->read_only))
498 specbind (Qinhibit_read_only, Qt);
500 /* Don't let `intangible' properties interfere with undo. */
501 specbind (Qinhibit_point_motion_hooks, Qt);
503 oldlist = current_buffer->undo_list;
505 while (arg > 0)
507 while (CONSP (list))
509 next = XCAR (list);
510 list = XCDR (list);
511 /* Exit inner loop at undo boundary. */
512 if (NILP (next))
513 break;
514 /* Handle an integer by setting point to that value. */
515 if (INTEGERP (next))
516 SET_PT (clip_to_bounds (BEGV, XINT (next), ZV));
517 else if (CONSP (next))
519 Lisp_Object car, cdr;
521 car = XCAR (next);
522 cdr = XCDR (next);
523 if (EQ (car, Qt))
525 /* Element (t high . low) records previous modtime. */
526 Lisp_Object high, low;
527 int mod_time;
528 struct buffer *base_buffer = current_buffer;
530 high = Fcar (cdr);
531 low = Fcdr (cdr);
532 mod_time = (XFASTINT (high) << 16) + XFASTINT (low);
534 if (current_buffer->base_buffer)
535 base_buffer = current_buffer->base_buffer;
537 /* If this records an obsolete save
538 (not matching the actual disk file)
539 then don't mark unmodified. */
540 if (mod_time != base_buffer->modtime)
541 continue;
542 #ifdef CLASH_DETECTION
543 Funlock_buffer ();
544 #endif /* CLASH_DETECTION */
545 Fset_buffer_modified_p (Qnil);
547 else if (EQ (car, Qnil))
549 /* Element (nil PROP VAL BEG . END) is property change. */
550 Lisp_Object beg, end, prop, val;
552 prop = Fcar (cdr);
553 cdr = Fcdr (cdr);
554 val = Fcar (cdr);
555 cdr = Fcdr (cdr);
556 beg = Fcar (cdr);
557 end = Fcdr (cdr);
559 if (XINT (beg) < BEGV || XINT (end) > ZV)
560 error ("Changes to be undone are outside visible portion of buffer");
561 Fput_text_property (beg, end, prop, val, Qnil);
563 else if (INTEGERP (car) && INTEGERP (cdr))
565 /* Element (BEG . END) means range was inserted. */
567 if (XINT (car) < BEGV
568 || XINT (cdr) > ZV)
569 error ("Changes to be undone are outside visible portion of buffer");
570 /* Set point first thing, so that undoing this undo
571 does not send point back to where it is now. */
572 Fgoto_char (car);
573 Fdelete_region (car, cdr);
575 else if (EQ (car, Qapply))
577 /* Element (apply FUN . ARGS) means call FUN to undo. */
578 struct buffer *save_buffer = current_buffer;
580 car = Fcar (cdr);
581 cdr = Fcdr (cdr);
582 if (INTEGERP (car))
584 /* Long format: (apply DELTA START END FUN . ARGS). */
585 Lisp_Object delta = car;
586 Lisp_Object start = Fcar (cdr);
587 Lisp_Object end = Fcar (Fcdr (cdr));
588 Lisp_Object start_mark = Fcopy_marker (start, Qnil);
589 Lisp_Object end_mark = Fcopy_marker (end, Qt);
591 cdr = Fcdr (Fcdr (cdr));
592 apply1 (Fcar (cdr), Fcdr (cdr));
594 /* Check that the function did what the entry said it
595 would do. */
596 if (!EQ (start, Fmarker_position (start_mark))
597 || (XINT (delta) + XINT (end)
598 != marker_position (end_mark)))
599 error ("Changes to be undone by function different than announced");
600 Fset_marker (start_mark, Qnil, Qnil);
601 Fset_marker (end_mark, Qnil, Qnil);
603 else
604 apply1 (car, cdr);
606 if (save_buffer != current_buffer)
607 error ("Undo function switched buffer");
608 did_apply = 1;
610 else if (STRINGP (car) && INTEGERP (cdr))
612 /* Element (STRING . POS) means STRING was deleted. */
613 Lisp_Object membuf;
614 int pos = XINT (cdr);
616 membuf = car;
617 if (pos < 0)
619 if (-pos < BEGV || -pos > ZV)
620 error ("Changes to be undone are outside visible portion of buffer");
621 SET_PT (-pos);
622 Finsert (1, &membuf);
624 else
626 if (pos < BEGV || pos > ZV)
627 error ("Changes to be undone are outside visible portion of buffer");
628 SET_PT (pos);
630 /* Now that we record marker adjustments
631 (caused by deletion) for undo,
632 we should always insert after markers,
633 so that undoing the marker adjustments
634 put the markers back in the right place. */
635 Finsert (1, &membuf);
636 SET_PT (pos);
639 else if (MARKERP (car) && INTEGERP (cdr))
641 /* (MARKER . INTEGER) means a marker MARKER
642 was adjusted by INTEGER. */
643 if (XMARKER (car)->buffer)
644 Fset_marker (car,
645 make_number (marker_position (car) - XINT (cdr)),
646 Fmarker_buffer (car));
650 arg--;
654 /* Make sure an apply entry produces at least one undo entry,
655 so the test in `undo' for continuing an undo series
656 will work right. */
657 if (did_apply
658 && EQ (oldlist, current_buffer->undo_list))
659 current_buffer->undo_list
660 = Fcons (list3 (Qapply, Qcdr, Qnil), current_buffer->undo_list);
662 UNGCPRO;
663 return unbind_to (count, list);
666 void
667 syms_of_undo ()
669 Qinhibit_read_only = intern ("inhibit-read-only");
670 staticpro (&Qinhibit_read_only);
672 Qapply = intern ("apply");
673 staticpro (&Qapply);
675 pending_boundary = Qnil;
676 staticpro (&pending_boundary);
678 last_undo_buffer = NULL;
679 last_boundary_buffer = NULL;
681 defsubr (&Sprimitive_undo);
682 defsubr (&Sundo_boundary);
684 DEFVAR_INT ("undo-limit", &undo_limit,
685 doc: /* Keep no more undo information once it exceeds this size.
686 This limit is applied when garbage collection happens.
687 When a previous command increases the total undo list size past this
688 value, the earlier commands that came before it are forgotten.
690 The size is counted as the number of bytes occupied,
691 which includes both saved text and other data. */);
692 undo_limit = 20000;
694 DEFVAR_INT ("undo-strong-limit", &undo_strong_limit,
695 doc: /* Don't keep more than this much size of undo information.
696 This limit is applied when garbage collection happens.
697 When a previous command increases the total undo list size past this
698 value, that command and the earlier commands that came before it are forgotten.
699 However, the most recent buffer-modifying command's undo info
700 is never discarded for this reason.
702 The size is counted as the number of bytes occupied,
703 which includes both saved text and other data. */);
704 undo_strong_limit = 30000;
706 DEFVAR_LISP ("undo-outer-limit", &Vundo_outer_limit,
707 doc: /* Outer limit on size of undo information for one command.
708 At garbage collection time, if the current command has produced
709 more than this much undo information, it discards the info and displays
710 a warning. This is a last-ditch limit to prevent memory overflow.
712 The size is counted as the number of bytes occupied, which includes
713 both saved text and other data. A value of nil means no limit. In
714 this case, accumulating one huge undo entry could make Emacs crash as
715 a result of memory overflow.
717 In fact, this calls the function which is the value of
718 `undo-outer-limit-function' with one argument, the size.
719 The text above describes the behavior of the function
720 that variable usually specifies. */);
721 Vundo_outer_limit = make_number (3000000);
723 DEFVAR_LISP ("undo-outer-limit-function", &Vundo_outer_limit_function,
724 doc: /* Function to call when an undo list exceeds `undo-outer-limit'.
725 This function is called with one argument, the current undo list size
726 for the most recent command (since the last undo boundary).
727 If the function returns t, that means truncation has been fully handled.
728 If it returns nil, the other forms of truncation are done.
730 Garbage collection is inhibited around the call to this function,
731 so it must make sure not to do a lot of consing. */);
732 Vundo_outer_limit_function = Qnil;
734 DEFVAR_BOOL ("undo-inhibit-record-point", &undo_inhibit_record_point,
735 doc: /* Non-nil means do not record `point' in `buffer-undo-list'. */);
736 undo_inhibit_record_point = 0;
739 /* arch-tag: d546ee01-4aed-4ffb-bb8b-eefaae50d38a
740 (do not change this comment) */