428
+ − 1 ;;; subr.el --- basic lisp subroutines for XEmacs
+ − 2
+ − 3 ;; Copyright (C) 1985, 1986, 1992, 1994-5, 1997 Free Software Foundation, Inc.
+ − 4 ;; Copyright (C) 1995 Tinker Systems and INS Engineering Corp.
+ − 5 ;; Copyright (C) 1995 Sun Microsystems.
563
+ − 6 ;; Copyright (C) 2000, 2001 Ben Wing.
428
+ − 7
+ − 8 ;; Maintainer: XEmacs Development Team
+ − 9 ;; Keywords: extensions, dumped
+ − 10
+ − 11 ;; This file is part of XEmacs.
+ − 12
+ − 13 ;; XEmacs is free software; you can redistribute it and/or modify it
+ − 14 ;; under the terms of the GNU General Public License as published by
+ − 15 ;; the Free Software Foundation; either version 2, or (at your option)
+ − 16 ;; any later version.
+ − 17
+ − 18 ;; XEmacs is distributed in the hope that it will be useful, but
+ − 19 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
+ − 20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ − 21 ;; General Public License for more details.
+ − 22
+ − 23 ;; You should have received a copy of the GNU General Public License
+ − 24 ;; along with XEmacs; see the file COPYING. If not, write to the Free
+ − 25 ;; Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
+ − 26 ;; 02111-1307, USA.
+ − 27
+ − 28 ;;; Synched up with: FSF 19.34.
+ − 29
+ − 30 ;;; Commentary:
+ − 31
+ − 32 ;; This file is dumped with XEmacs.
+ − 33
+ − 34 ;; There's not a whole lot in common now with the FSF version,
+ − 35 ;; be wary when applying differences. I've left in a number of lines
+ − 36 ;; of commentary just to give diff(1) something to synch itself with to
+ − 37 ;; provide useful context diffs. -sb
+ − 38
+ − 39 ;;; Code:
+ − 40
+ − 41
+ − 42 ;;;; Lisp language features.
+ − 43
+ − 44 (defmacro lambda (&rest cdr)
+ − 45 "Return a lambda expression.
+ − 46 A call of the form (lambda ARGS DOCSTRING INTERACTIVE BODY) is
+ − 47 self-quoting; the result of evaluating the lambda expression is the
+ − 48 expression itself. The lambda expression may then be treated as a
+ − 49 function, i.e., stored as the function value of a symbol, passed to
+ − 50 funcall or mapcar, etc.
+ − 51
+ − 52 ARGS should take the same form as an argument list for a `defun'.
+ − 53 DOCSTRING is an optional documentation string.
+ − 54 If present, it should describe how to call the function.
+ − 55 But documentation strings are usually not useful in nameless functions.
+ − 56 INTERACTIVE should be a call to the function `interactive', which see.
+ − 57 It may also be omitted.
+ − 58 BODY should be a list of lisp expressions."
+ − 59 `(function (lambda ,@cdr)))
+ − 60
+ − 61 (defmacro defun-when-void (&rest args)
+ − 62 "Define a function, just like `defun', unless it's already defined.
+ − 63 Used for compatibility among different emacs variants."
+ − 64 `(if (fboundp ',(car args))
+ − 65 nil
+ − 66 (defun ,@args)))
+ − 67
+ − 68 (defmacro define-function-when-void (&rest args)
+ − 69 "Define a function, just like `define-function', unless it's already defined.
+ − 70 Used for compatibility among different emacs variants."
+ − 71 `(if (fboundp ,(car args))
+ − 72 nil
+ − 73 (define-function ,@args)))
+ − 74
+ − 75
+ − 76 ;;;; Keymap support.
+ − 77 ;; XEmacs: removed to keymap.el
+ − 78
+ − 79 ;;;; The global keymap tree.
+ − 80
+ − 81 ;;; global-map, esc-map, and ctl-x-map have their values set up in
+ − 82 ;;; keymap.c; we just give them docstrings here.
+ − 83
+ − 84 ;;;; Event manipulation functions.
+ − 85
+ − 86 ;; XEmacs: This stuff is done in C Code.
+ − 87
+ − 88 ;;;; Obsolescent names for functions.
+ − 89 ;; XEmacs: not used.
+ − 90
+ − 91 ;; XEmacs:
+ − 92 (defun local-variable-if-set-p (sym buffer)
+ − 93 "Return t if SYM would be local to BUFFER after it is set.
+ − 94 A nil value for BUFFER is *not* the same as (current-buffer), but
+ − 95 can be used to determine whether `make-variable-buffer-local' has been
+ − 96 called on SYM."
+ − 97 (local-variable-p sym buffer t))
+ − 98
+ − 99
+ − 100 ;;;; Hook manipulation functions.
+ − 101
+ − 102 ;; (defconst run-hooks 'run-hooks ...)
+ − 103
+ − 104 (defun make-local-hook (hook)
+ − 105 "Make the hook HOOK local to the current buffer.
+ − 106 When a hook is local, its local and global values
+ − 107 work in concert: running the hook actually runs all the hook
+ − 108 functions listed in *either* the local value *or* the global value
+ − 109 of the hook variable.
+ − 110
+ − 111 This function works by making `t' a member of the buffer-local value,
+ − 112 which acts as a flag to run the hook functions in the default value as
+ − 113 well. This works for all normal hooks, but does not work for most
+ − 114 non-normal hooks yet. We will be changing the callers of non-normal
+ − 115 hooks so that they can handle localness; this has to be done one by
+ − 116 one.
+ − 117
+ − 118 This function does nothing if HOOK is already local in the current
+ − 119 buffer.
+ − 120
442
+ − 121 Do not use `make-local-variable' to make a hook variable buffer-local.
+ − 122
+ − 123 See also `add-local-hook' and `remove-local-hook'."
428
+ − 124 (if (local-variable-p hook (current-buffer)) ; XEmacs
+ − 125 nil
+ − 126 (or (boundp hook) (set hook nil))
+ − 127 (make-local-variable hook)
+ − 128 (set hook (list t))))
+ − 129
+ − 130 (defun add-hook (hook function &optional append local)
+ − 131 "Add to the value of HOOK the function FUNCTION.
+ − 132 FUNCTION is not added if already present.
+ − 133 FUNCTION is added (if necessary) at the beginning of the hook list
+ − 134 unless the optional argument APPEND is non-nil, in which case
+ − 135 FUNCTION is added at the end.
+ − 136
+ − 137 The optional fourth argument, LOCAL, if non-nil, says to modify
+ − 138 the hook's buffer-local value rather than its default value.
+ − 139 This makes no difference if the hook is not buffer-local.
+ − 140 To make a hook variable buffer-local, always use
+ − 141 `make-local-hook', not `make-local-variable'.
+ − 142
+ − 143 HOOK should be a symbol, and FUNCTION may be any valid function. If
+ − 144 HOOK is void, it is first set to nil. If HOOK's value is a single
442
+ − 145 function, it is changed to a list of functions.
+ − 146
+ − 147 You can remove this hook yourself using `remove-hook'.
+ − 148
+ − 149 See also `add-local-hook' and `add-one-shot-hook'."
428
+ − 150 (or (boundp hook) (set hook nil))
+ − 151 (or (default-boundp hook) (set-default hook nil))
+ − 152 ;; If the hook value is a single function, turn it into a list.
+ − 153 (let ((old (symbol-value hook)))
+ − 154 (if (or (not (listp old)) (eq (car old) 'lambda))
+ − 155 (set hook (list old))))
+ − 156 (if (or local
+ − 157 ;; Detect the case where make-local-variable was used on a hook
+ − 158 ;; and do what we used to do.
+ − 159 (and (local-variable-if-set-p hook (current-buffer)) ; XEmacs
+ − 160 (not (memq t (symbol-value hook)))))
+ − 161 ;; Alter the local value only.
+ − 162 (or (if (consp function)
+ − 163 (member function (symbol-value hook))
+ − 164 (memq function (symbol-value hook)))
+ − 165 (set hook
+ − 166 (if append
+ − 167 (append (symbol-value hook) (list function))
+ − 168 (cons function (symbol-value hook)))))
+ − 169 ;; Alter the global value (which is also the only value,
+ − 170 ;; if the hook doesn't have a local value).
+ − 171 (or (if (consp function)
+ − 172 (member function (default-value hook))
+ − 173 (memq function (default-value hook)))
+ − 174 (set-default hook
+ − 175 (if append
+ − 176 (append (default-value hook) (list function))
+ − 177 (cons function (default-value hook)))))))
+ − 178
+ − 179 (defun remove-hook (hook function &optional local)
+ − 180 "Remove from the value of HOOK the function FUNCTION.
+ − 181 HOOK should be a symbol, and FUNCTION may be any valid function. If
+ − 182 FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the
+ − 183 list of hooks to run in HOOK, then nothing is done. See `add-hook'.
+ − 184
+ − 185 The optional third argument, LOCAL, if non-nil, says to modify
+ − 186 the hook's buffer-local value rather than its default value.
+ − 187 This makes no difference if the hook is not buffer-local.
+ − 188 To make a hook variable buffer-local, always use
+ − 189 `make-local-hook', not `make-local-variable'."
+ − 190 (if (or (not (boundp hook)) ;unbound symbol, or
+ − 191 (not (default-boundp 'hook))
+ − 192 (null (symbol-value hook)) ;value is nil, or
+ − 193 (null function)) ;function is nil, then
+ − 194 nil ;Do nothing.
442
+ − 195 (flet ((hook-remove
+ − 196 (function hook-value)
+ − 197 (flet ((hook-test
+ − 198 (fn hel)
+ − 199 (or (equal fn hel)
+ − 200 (and (symbolp hel)
+ − 201 (equal fn
+ − 202 (get hel 'one-shot-hook-fun))))))
+ − 203 (if (and (consp hook-value)
+ − 204 (not (functionp hook-value)))
+ − 205 (if (member* function hook-value :test 'hook-test)
+ − 206 (setq hook-value
+ − 207 (delete* function (copy-sequence hook-value)
+ − 208 :test 'hook-test)))
+ − 209 (if (equal hook-value function)
+ − 210 (setq hook-value nil)))
+ − 211 hook-value)))
+ − 212 (if (or local
+ − 213 ;; Detect the case where make-local-variable was used on a hook
+ − 214 ;; and do what we used to do.
+ − 215 (and (local-variable-p hook (current-buffer))
+ − 216 (not (memq t (symbol-value hook)))))
+ − 217 (set hook (hook-remove function (symbol-value hook)))
+ − 218 (set-default hook (hook-remove function (default-value hook)))))))
+ − 219
+ − 220 ;; XEmacs addition
+ − 221 ;; #### we need a coherent scheme for indicating compatibility info,
+ − 222 ;; so that it can be programmatically retrieved.
+ − 223 (defun add-local-hook (hook function &optional append)
+ − 224 "Add to the local value of HOOK the function FUNCTION.
+ − 225 This modifies only the buffer-local value for the hook (which is
+ − 226 automatically make buffer-local, if necessary), not its default value.
+ − 227 FUNCTION is not added if already present.
+ − 228 FUNCTION is added (if necessary) at the beginning of the hook list
+ − 229 unless the optional argument APPEND is non-nil, in which case
+ − 230 FUNCTION is added at the end.
+ − 231
+ − 232 HOOK should be a symbol, and FUNCTION may be any valid function. If
+ − 233 HOOK is void, it is first set to nil. If HOOK's value is a single
+ − 234 function, it is changed to a list of functions.
+ − 235
+ − 236 You can remove this hook yourself using `remove-local-hook'.
+ − 237
+ − 238 See also `add-hook' and `make-local-hook'."
+ − 239 (make-local-hook hook)
+ − 240 (add-hook hook function append t))
+ − 241
+ − 242 ;; XEmacs addition
+ − 243 (defun remove-local-hook (hook function)
+ − 244 "Remove from the local value of HOOK the function FUNCTION.
+ − 245 This modifies only the buffer-local value for the hook, not its default
+ − 246 value. (Nothing happens if the hook is not buffer-local.)
+ − 247 HOOK should be a symbol, and FUNCTION may be any valid function. If
+ − 248 FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the
+ − 249 list of hooks to run in HOOK, then nothing is done. See `add-hook'.
+ − 250
+ − 251 See also `add-local-hook' and `make-local-hook'."
+ − 252 (if (local-variable-p hook (current-buffer))
+ − 253 (remove-hook hook function t)))
+ − 254
+ − 255 (defun add-one-shot-hook (hook function &optional append local)
+ − 256 "Add to the value of HOOK the one-shot function FUNCTION.
+ − 257 FUNCTION will automatically be removed from the hook the first time
+ − 258 after it runs (whether to completion or to an error).
+ − 259 FUNCTION is not added if already present.
+ − 260 FUNCTION is added (if necessary) at the beginning of the hook list
+ − 261 unless the optional argument APPEND is non-nil, in which case
+ − 262 FUNCTION is added at the end.
+ − 263
+ − 264 HOOK should be a symbol, and FUNCTION may be any valid function. If
+ − 265 HOOK is void, it is first set to nil. If HOOK's value is a single
+ − 266 function, it is changed to a list of functions.
+ − 267
+ − 268 You can remove this hook yourself using `remove-hook'.
+ − 269
+ − 270 See also `add-hook', `add-local-hook', and `add-local-one-shot-hook'."
+ − 271 (let ((sym (gensym)))
+ − 272 (fset sym `(lambda (&rest args)
+ − 273 (unwind-protect
+ − 274 (apply ',function args)
+ − 275 (remove-hook ',hook ',sym ',local))))
+ − 276 (put sym 'one-shot-hook-fun function)
+ − 277 (add-hook hook sym append local)))
+ − 278
+ − 279 (defun add-local-one-shot-hook (hook function &optional append)
+ − 280 "Add to the local value of HOOK the one-shot function FUNCTION.
+ − 281 FUNCTION will automatically be removed from the hook the first time
+ − 282 after it runs (whether to completion or to an error).
+ − 283 FUNCTION is not added if already present.
+ − 284 FUNCTION is added (if necessary) at the beginning of the hook list
+ − 285 unless the optional argument APPEND is non-nil, in which case
+ − 286 FUNCTION is added at the end.
+ − 287
+ − 288 The optional fourth argument, LOCAL, if non-nil, says to modify
+ − 289 the hook's buffer-local value rather than its default value.
+ − 290 This makes no difference if the hook is not buffer-local.
+ − 291 To make a hook variable buffer-local, always use
+ − 292 `make-local-hook', not `make-local-variable'.
+ − 293
+ − 294 HOOK should be a symbol, and FUNCTION may be any valid function. If
+ − 295 HOOK is void, it is first set to nil. If HOOK's value is a single
+ − 296 function, it is changed to a list of functions.
+ − 297
+ − 298 You can remove this hook yourself using `remove-local-hook'.
+ − 299
+ − 300 See also `add-hook', `add-local-hook', and `add-local-one-shot-hook'."
+ − 301 (make-local-hook hook)
+ − 302 (add-one-shot-hook hook function append t))
428
+ − 303
+ − 304 (defun add-to-list (list-var element)
+ − 305 "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet.
+ − 306 The test for presence of ELEMENT is done with `equal'.
+ − 307 If you want to use `add-to-list' on a variable that is not defined
+ − 308 until a certain package is loaded, you should put the call to `add-to-list'
+ − 309 into a hook function that will be run only after loading the package.
+ − 310 `eval-after-load' provides one way to do this. In some cases
+ − 311 other hooks, such as major mode hooks, can do the job."
+ − 312 (or (member element (symbol-value list-var))
+ − 313 (set list-var (cons element (symbol-value list-var)))))
+ − 314
+ − 315 ;; XEmacs additions
+ − 316 ;; called by Fkill_buffer()
+ − 317 (defvar kill-buffer-hook nil
+ − 318 "Function or functions to be called when a buffer is killed.
+ − 319 The value of this variable may be buffer-local.
+ − 320 The buffer about to be killed is current when this hook is run.")
+ − 321
+ − 322 ;; in C in FSFmacs
+ − 323 (defvar kill-emacs-hook nil
+ − 324 "Function or functions to be called when `kill-emacs' is called,
+ − 325 just before emacs is actually killed.")
+ − 326
+ − 327 ;; not obsolete.
+ − 328 ;; #### These are a bad idea, because the CL RPLACA and RPLACD
+ − 329 ;; return the cons cell, not the new CAR/CDR. -hniksic
+ − 330 ;; The proper definition would be:
+ − 331 ;; (defun rplaca (conscell newcar)
+ − 332 ;; (setcar conscell newcar)
+ − 333 ;; conscell)
+ − 334 ;; ...and analogously for RPLACD.
+ − 335 (define-function 'rplaca 'setcar)
+ − 336 (define-function 'rplacd 'setcdr)
+ − 337
+ − 338 (defun copy-symbol (symbol &optional copy-properties)
+ − 339 "Return a new uninterned symbol with the same name as SYMBOL.
+ − 340 If COPY-PROPERTIES is non-nil, the new symbol will have a copy of
+ − 341 SYMBOL's value, function, and property lists."
+ − 342 (let ((new (make-symbol (symbol-name symbol))))
+ − 343 (when copy-properties
+ − 344 ;; This will not copy SYMBOL's chain of forwarding objects, but
+ − 345 ;; I think that's OK. Callers should not expect such magic to
+ − 346 ;; keep working in the copy in the first place.
+ − 347 (and (boundp symbol)
+ − 348 (set new (symbol-value symbol)))
+ − 349 (and (fboundp symbol)
+ − 350 (fset new (symbol-function symbol)))
+ − 351 (setplist new (copy-list (symbol-plist symbol))))
+ − 352 new))
+ − 353
442
+ − 354 (defun set-symbol-value-in-buffer (sym val buffer)
+ − 355 "Set the value of SYM to VAL in BUFFER. Useful with buffer-local variables.
+ − 356 If SYM has a buffer-local value in BUFFER, or will have one if set, this
+ − 357 function allows you to set the local value.
+ − 358
+ − 359 NOTE: At some point, this will be moved into C and will be very fast."
+ − 360 (with-current-buffer buffer
+ − 361 (set sym val)))
444
+ − 362
428
+ − 363 ;;;; String functions.
+ − 364
+ − 365 ;; XEmacs
+ − 366 (defun replace-in-string (str regexp newtext &optional literal)
+ − 367 "Replace all matches in STR for REGEXP with NEWTEXT string,
+ − 368 and returns the new string.
+ − 369 Optional LITERAL non-nil means do a literal replacement.
442
+ − 370 Otherwise treat `\\' in NEWTEXT as special:
+ − 371 `\\&' in NEWTEXT means substitute original matched text.
+ − 372 `\\N' means substitute what matched the Nth `\\(...\\)'.
+ − 373 If Nth parens didn't match, substitute nothing.
+ − 374 `\\\\' means insert one `\\'.
+ − 375 `\\u' means upcase the next character.
+ − 376 `\\l' means downcase the next character.
+ − 377 `\\U' means begin upcasing all following characters.
+ − 378 `\\L' means begin downcasing all following characters.
+ − 379 `\\E' means terminate the effect of any `\\U' or `\\L'."
428
+ − 380 (check-argument-type 'stringp str)
+ − 381 (check-argument-type 'stringp newtext)
442
+ − 382 (if (> (length str) 50)
+ − 383 (with-temp-buffer
+ − 384 (insert str)
+ − 385 (goto-char 1)
+ − 386 (while (re-search-forward regexp nil t)
+ − 387 (replace-match newtext t literal))
+ − 388 (buffer-string))
+ − 389 (let ((start 0) newstr)
+ − 390 (while (string-match regexp str start)
+ − 391 (setq newstr (replace-match newtext t literal str)
+ − 392 start (+ (match-end 0) (- (length newstr) (length str)))
+ − 393 str newstr))
+ − 394 str)))
428
+ − 395
+ − 396 (defun split-string (string &optional pattern)
+ − 397 "Return a list of substrings of STRING which are separated by PATTERN.
+ − 398 If PATTERN is omitted, it defaults to \"[ \\f\\t\\n\\r\\v]+\"."
+ − 399 (or pattern
+ − 400 (setq pattern "[ \f\t\n\r\v]+"))
+ − 401 (let (parts (start 0) (len (length string)))
+ − 402 (if (string-match pattern string)
+ − 403 (setq parts (cons (substring string 0 (match-beginning 0)) parts)
+ − 404 start (match-end 0)))
+ − 405 (while (and (< start len)
+ − 406 (string-match pattern string (if (> start (match-beginning 0))
+ − 407 start
+ − 408 (1+ start))))
+ − 409 (setq parts (cons (substring string start (match-beginning 0)) parts)
+ − 410 start (match-end 0)))
+ − 411 (nreverse (cons (substring string start) parts))))
+ − 412
+ − 413 ;; #### #### #### AAaargh! Must be in C, because it is used insanely
+ − 414 ;; early in the bootstrap process.
+ − 415 ;(defun split-path (path)
+ − 416 ; "Explode a search path into a list of strings.
+ − 417 ;The path components are separated with the characters specified
+ − 418 ;with `path-separator'."
+ − 419 ; (while (or (not stringp path-separator)
+ − 420 ; (/= (length path-separator) 1))
+ − 421 ; (setq path-separator (signal 'error (list "\
+ − 422 ;`path-separator' should be set to a single-character string"
+ − 423 ; path-separator))))
+ − 424 ; (split-string-by-char path (aref separator 0)))
+ − 425
+ − 426 (defmacro with-output-to-string (&rest forms)
+ − 427 "Collect output to `standard-output' while evaluating FORMS and return
+ − 428 it as a string."
+ − 429 ;; by "William G. Dubuque" <wgd@zurich.ai.mit.edu> w/ mods from Stig
442
+ − 430 `(with-current-buffer (get-buffer-create
+ − 431 (generate-new-buffer-name " *string-output*"))
428
+ − 432 (setq buffer-read-only nil)
+ − 433 (buffer-disable-undo (current-buffer))
+ − 434 (erase-buffer)
+ − 435 (let ((standard-output (current-buffer)))
+ − 436 ,@forms)
+ − 437 (prog1
+ − 438 (buffer-string)
+ − 439 (erase-buffer))))
+ − 440
+ − 441 (defmacro with-current-buffer (buffer &rest body)
+ − 442 "Temporarily make BUFFER the current buffer and execute the forms in BODY.
+ − 443 The value returned is the value of the last form in BODY.
+ − 444 See also `with-temp-buffer'."
+ − 445 `(save-current-buffer
+ − 446 (set-buffer ,buffer)
+ − 447 ,@body))
+ − 448
444
+ − 449 (defmacro with-temp-file (filename &rest forms)
+ − 450 "Create a new buffer, evaluate FORMS there, and write the buffer to FILENAME.
428
+ − 451 The value of the last form in FORMS is returned, like `progn'.
+ − 452 See also `with-temp-buffer'."
+ − 453 (let ((temp-file (make-symbol "temp-file"))
+ − 454 (temp-buffer (make-symbol "temp-buffer")))
444
+ − 455 `(let ((,temp-file ,filename)
428
+ − 456 (,temp-buffer
+ − 457 (get-buffer-create (generate-new-buffer-name " *temp file*"))))
+ − 458 (unwind-protect
+ − 459 (prog1
+ − 460 (with-current-buffer ,temp-buffer
+ − 461 ,@forms)
+ − 462 (with-current-buffer ,temp-buffer
+ − 463 (widen)
+ − 464 (write-region (point-min) (point-max) ,temp-file nil 0)))
+ − 465 (and (buffer-name ,temp-buffer)
+ − 466 (kill-buffer ,temp-buffer))))))
+ − 467
+ − 468 (defmacro with-temp-buffer (&rest forms)
+ − 469 "Create a temporary buffer, and evaluate FORMS there like `progn'.
+ − 470 See also `with-temp-file' and `with-output-to-string'."
+ − 471 (let ((temp-buffer (make-symbol "temp-buffer")))
+ − 472 `(let ((,temp-buffer
+ − 473 (get-buffer-create (generate-new-buffer-name " *temp*"))))
+ − 474 (unwind-protect
+ − 475 (with-current-buffer ,temp-buffer
+ − 476 ,@forms)
+ − 477 (and (buffer-name ,temp-buffer)
+ − 478 (kill-buffer ,temp-buffer))))))
+ − 479
+ − 480 ;; Moved from mule-coding.el.
+ − 481 (defmacro with-string-as-buffer-contents (str &rest body)
+ − 482 "With the contents of the current buffer being STR, run BODY.
+ − 483 Returns the new contents of the buffer, as modified by BODY.
+ − 484 The original current buffer is restored afterwards."
442
+ − 485 `(with-temp-buffer
+ − 486 (insert ,str)
+ − 487 ,@body
+ − 488 (buffer-string)))
428
+ − 489
+ − 490 (defun insert-face (string face)
+ − 491 "Insert STRING and highlight with FACE. Return the extent created."
+ − 492 (let ((p (point)) ext)
+ − 493 (insert string)
+ − 494 (setq ext (make-extent p (point)))
+ − 495 (set-extent-face ext face)
+ − 496 ext))
+ − 497
+ − 498 ;; not obsolete.
+ − 499 (define-function 'string= 'string-equal)
+ − 500 (define-function 'string< 'string-lessp)
+ − 501 (define-function 'int-to-string 'number-to-string)
+ − 502 (define-function 'string-to-int 'string-to-number)
+ − 503
+ − 504 ;; These two names are a bit awkward, as they conflict with the normal
+ − 505 ;; foo-to-bar naming scheme, but CLtL2 has them, so they stay.
+ − 506 (define-function 'char-int 'char-to-int)
+ − 507 (define-function 'int-char 'int-to-char)
+ − 508
771
+ − 509 (defun string-width (string)
+ − 510 "Return number of columns STRING occupies when displayed.
+ − 511 With international (Mule) support, uses the charset-columns attribute of
+ − 512 the characters in STRING, which may not accurately represent the actual
+ − 513 display width when using a window system. With no international support,
+ − 514 simply returns the length of the string."
+ − 515 (if (featurep 'mule)
+ − 516 (let ((col 0)
+ − 517 (len (length string))
+ − 518 (i 0))
+ − 519 (while (< i len)
+ − 520 (setq col (+ col (charset-width (char-charset (aref string i)))))
+ − 521 (setq i (1+ i)))
+ − 522 col)
+ − 523 (length string)))
+ − 524
428
+ − 525
+ − 526 ;; alist/plist functions
+ − 527 (defun plist-to-alist (plist)
+ − 528 "Convert property list PLIST into the equivalent association-list form.
+ − 529 The alist is returned. This converts from
+ − 530
+ − 531 \(a 1 b 2 c 3)
+ − 532
+ − 533 into
+ − 534
+ − 535 \((a . 1) (b . 2) (c . 3))
+ − 536
+ − 537 The original plist is not modified. See also `destructive-plist-to-alist'."
+ − 538 (let (alist)
+ − 539 (while plist
+ − 540 (setq alist (cons (cons (car plist) (cadr plist)) alist))
+ − 541 (setq plist (cddr plist)))
+ − 542 (nreverse alist)))
+ − 543
+ − 544 (defun destructive-plist-to-alist (plist)
+ − 545 "Convert property list PLIST into the equivalent association-list form.
+ − 546 The alist is returned. This converts from
+ − 547
+ − 548 \(a 1 b 2 c 3)
+ − 549
+ − 550 into
+ − 551
+ − 552 \((a . 1) (b . 2) (c . 3))
+ − 553
+ − 554 The original plist is destroyed in the process of constructing the alist.
+ − 555 See also `plist-to-alist'."
+ − 556 (let ((head plist)
+ − 557 next)
+ − 558 (while plist
+ − 559 ;; remember the next plist pair.
+ − 560 (setq next (cddr plist))
+ − 561 ;; make the cons holding the property value into the alist element.
+ − 562 (setcdr (cdr plist) (cadr plist))
+ − 563 (setcar (cdr plist) (car plist))
+ − 564 ;; reattach into alist form.
+ − 565 (setcar plist (cdr plist))
+ − 566 (setcdr plist next)
+ − 567 (setq plist next))
+ − 568 head))
+ − 569
+ − 570 (defun alist-to-plist (alist)
+ − 571 "Convert association list ALIST into the equivalent property-list form.
+ − 572 The plist is returned. This converts from
+ − 573
+ − 574 \((a . 1) (b . 2) (c . 3))
+ − 575
+ − 576 into
+ − 577
+ − 578 \(a 1 b 2 c 3)
+ − 579
+ − 580 The original alist is not modified. See also `destructive-alist-to-plist'."
+ − 581 (let (plist)
+ − 582 (while alist
+ − 583 (let ((el (car alist)))
+ − 584 (setq plist (cons (cdr el) (cons (car el) plist))))
+ − 585 (setq alist (cdr alist)))
+ − 586 (nreverse plist)))
+ − 587
+ − 588 ;; getf, remf in cl*.el.
+ − 589
444
+ − 590 (defmacro putf (plist property value)
+ − 591 "Add property PROPERTY to plist PLIST with value VALUE.
+ − 592 Analogous to (setq PLIST (plist-put PLIST PROPERTY VALUE))."
+ − 593 `(setq ,plist (plist-put ,plist ,property ,value)))
428
+ − 594
444
+ − 595 (defmacro laxputf (lax-plist property value)
+ − 596 "Add property PROPERTY to lax plist LAX-PLIST with value VALUE.
+ − 597 Analogous to (setq LAX-PLIST (lax-plist-put LAX-PLIST PROPERTY VALUE))."
+ − 598 `(setq ,lax-plist (lax-plist-put ,lax-plist ,property ,value)))
428
+ − 599
444
+ − 600 (defmacro laxremf (lax-plist property)
+ − 601 "Remove property PROPERTY from lax plist LAX-PLIST.
+ − 602 Analogous to (setq LAX-PLIST (lax-plist-remprop LAX-PLIST PROPERTY))."
+ − 603 `(setq ,lax-plist (lax-plist-remprop ,lax-plist ,property)))
428
+ − 604
+ − 605 ;;; Error functions
+ − 606
442
+ − 607 (defun error (datum &rest args)
+ − 608 "Signal a non-continuable error.
+ − 609 DATUM should normally be an error symbol, i.e. a symbol defined using
+ − 610 `define-error'. ARGS will be made into a list, and DATUM and ARGS passed
+ − 611 as the two arguments to `signal', the most basic error handling function.
+ − 612
428
+ − 613 This error is not continuable: you cannot continue execution after the
442
+ − 614 error using the debugger `r' command. See also `cerror'.
+ − 615
+ − 616 The correct semantics of ARGS varies from error to error, but for most
+ − 617 errors that need to be generated in Lisp code, the first argument
+ − 618 should be a string describing the *context* of the error (i.e. the
+ − 619 exact operation being performed and what went wrong), and the remaining
+ − 620 arguments or \"frobs\" (most often, there is one) specify the
+ − 621 offending object(s) and/or provide additional details such as the exact
+ − 622 error when a file error occurred, e.g.:
+ − 623
+ − 624 -- the buffer in which an editing error occurred.
+ − 625 -- an invalid value that was encountered. (In such cases, the string
+ − 626 should describe the purpose or \"semantics\" of the value [e.g. if the
+ − 627 value is an argument to a function, the name of the argument; if the value
+ − 628 is the value corresponding to a keyword, the name of the keyword; if the
+ − 629 value is supposed to be a list length, say this and say what the purpose
+ − 630 of the list is; etc.] as well as specifying why the value is invalid, if
+ − 631 that's not self-evident.)
+ − 632 -- the file in which an error occurred. (In such cases, there should be a
+ − 633 second frob, probably a string, specifying the exact error that occurred.
+ − 634 This does not occur in the string that precedes the first frob, because
+ − 635 that frob describes the exact operation that was happening.
+ − 636
+ − 637 For historical compatibility, DATUM can also be a string. In this case,
+ − 638 DATUM and ARGS are passed together as the arguments to `format', and then
+ − 639 an error is signalled using the error symbol `error' and formatted string.
+ − 640 Although this usage of `error' is very common, it is deprecated because it
+ − 641 totally defeats the purpose of having structured errors. There is now
+ − 642 a rich set of defined errors you can use:
+ − 643
563
+ − 644 quit
+ − 645
442
+ − 646 error
+ − 647 invalid-argument
563
+ − 648 syntax-error
+ − 649 invalid-read-syntax
+ − 650 invalid-regexp
+ − 651 structure-formation-error
+ − 652 list-formation-error
+ − 653 malformed-list
+ − 654 malformed-property-list
+ − 655 circular-list
+ − 656 circular-property-list
+ − 657 invalid-function
+ − 658 no-catch
+ − 659 undefined-keystroke-sequence
+ − 660 invalid-constant
442
+ − 661 wrong-type-argument
+ − 662 args-out-of-range
+ − 663 wrong-number-of-arguments
428
+ − 664
442
+ − 665 invalid-state
+ − 666 void-function
+ − 667 cyclic-function-indirection
+ − 668 void-variable
+ − 669 cyclic-variable-indirection
509
+ − 670 invalid-byte-code
563
+ − 671 stack-overflow
+ − 672 out-of-memory
+ − 673 invalid-key-binding
+ − 674 internal-error
442
+ − 675
+ − 676 invalid-operation
+ − 677 invalid-change
+ − 678 setting-constant
563
+ − 679 protected-field
442
+ − 680 editing-error
+ − 681 beginning-of-buffer
+ − 682 end-of-buffer
+ − 683 buffer-read-only
+ − 684 io-error
509
+ − 685 file-error
+ − 686 file-already-exists
+ − 687 file-locked
+ − 688 file-supersession
563
+ − 689 end-of-file
+ − 690 process-error
+ − 691 network-error
509
+ − 692 tooltalk-error
563
+ − 693 gui-error
+ − 694 dialog-box-error
+ − 695 sound-error
+ − 696 conversion-error
+ − 697 text-conversion-error
+ − 698 image-conversion-error
+ − 699 base64-conversion-error
+ − 700 selection-conversion-error
442
+ − 701 arith-error
+ − 702 range-error
+ − 703 domain-error
+ − 704 singularity-error
+ − 705 overflow-error
+ − 706 underflow-error
509
+ − 707 search-failed
563
+ − 708 printing-unreadable-object
+ − 709 unimplemented
509
+ − 710
563
+ − 711 Note the semantic differences between some of the more common errors:
442
+ − 712
563
+ − 713 -- `invalid-argument' is for all cases where a bad value is encountered.
+ − 714 -- `invalid-constant' is for arguments where only a specific set of values
+ − 715 is allowed.
+ − 716 -- `syntax-error' is when complex structures (parsed strings, lists,
+ − 717 and the like) are badly formed. If the problem is just a single bad
+ − 718 value inside the structure, you should probably be using something else,
+ − 719 e.g. `invalid-constant', `wrong-type-argument', or `invalid-argument'.
442
+ − 720 -- `invalid-state' means that some settings have been changed in such a way
+ − 721 that their current state is unallowable. More and more, code is being
+ − 722 written more carefully, and catches the error when the settings are being
+ − 723 changed, rather than afterwards. This leads us to the next error:
+ − 724 -- `invalid-change' means that an attempt is being made to change some settings
+ − 725 into an invalid state. `invalid-change' is a type of `invalid-operation'.
+ − 726 -- `invalid-operation' refers to all cases where code is trying to do something
563
+ − 727 that's disallowed, or when an error occurred during an operation. (These
+ − 728 two concepts are merged because there's no clear distinction between them.)
+ − 729 -- `io-error' refers to errors involving interaction with any external
+ − 730 components (files, other programs, the operating system, etc).
442
+ − 731
+ − 732 See also `cerror', `signal', and `signal-error'."
+ − 733 (while t (apply
+ − 734 'cerror datum args)))
+ − 735
+ − 736 (defun cerror (datum &rest args)
428
+ − 737 "Like `error' but signals a continuable error."
442
+ − 738 (cond ((stringp datum)
+ − 739 (signal 'error (list (apply 'format datum args))))
+ − 740 ((defined-error-p datum)
+ − 741 (signal datum args))
+ − 742 (t
+ − 743 (error 'invalid-argument "datum not string or error symbol" datum))))
428
+ − 744
+ − 745 (defmacro check-argument-type (predicate argument)
+ − 746 "Check that ARGUMENT satisfies PREDICATE.
442
+ − 747 This is a macro, and ARGUMENT is not evaluated. If ARGUMENT is an lvalue,
+ − 748 this function signals a continuable `wrong-type-argument' error until the
+ − 749 returned value satisfies PREDICATE, and assigns the returned value
+ − 750 to ARGUMENT. Otherwise, this function signals a non-continuable
+ − 751 `wrong-type-argument' error if the returned value does not satisfy PREDICATE."
+ − 752 (if (symbolp argument)
+ − 753 `(if (not (,(eval predicate) ,argument))
+ − 754 (setq ,argument
+ − 755 (wrong-type-argument ,predicate ,argument)))
+ − 756 `(if (not (,(eval predicate) ,argument))
+ − 757 (signal-error 'wrong-type-argument (list ,predicate ,argument)))))
428
+ − 758
+ − 759 (defun signal-error (error-symbol data)
+ − 760 "Signal a non-continuable error. Args are ERROR-SYMBOL, and associated DATA.
+ − 761 An error symbol is a symbol defined using `define-error'.
+ − 762 DATA should be a list. Its elements are printed as part of the error message.
+ − 763 If the signal is handled, DATA is made available to the handler.
+ − 764 See also `signal', and the functions to handle errors: `condition-case'
+ − 765 and `call-with-condition-handler'."
+ − 766 (while t
+ − 767 (signal error-symbol data)))
+ − 768
+ − 769 (defun define-error (error-sym doc-string &optional inherits-from)
+ − 770 "Define a new error, denoted by ERROR-SYM.
+ − 771 DOC-STRING is an informative message explaining the error, and will be
+ − 772 printed out when an unhandled error occurs.
+ − 773 ERROR-SYM is a sub-error of INHERITS-FROM (which defaults to `error').
+ − 774
+ − 775 \[`define-error' internally works by putting on ERROR-SYM an `error-message'
+ − 776 property whose value is DOC-STRING, and an `error-conditions' property
+ − 777 that is a list of ERROR-SYM followed by each of its super-errors, up
+ − 778 to and including `error'. You will sometimes see code that sets this up
+ − 779 directly rather than calling `define-error', but you should *not* do this
+ − 780 yourself.]"
+ − 781 (check-argument-type 'symbolp error-sym)
+ − 782 (check-argument-type 'stringp doc-string)
+ − 783 (put error-sym 'error-message doc-string)
+ − 784 (or inherits-from (setq inherits-from 'error))
+ − 785 (let ((conds (get inherits-from 'error-conditions)))
+ − 786 (or conds (signal-error 'error (list "Not an error symbol" error-sym)))
+ − 787 (put error-sym 'error-conditions (cons error-sym conds))))
+ − 788
442
+ − 789 (defun defined-error-p (sym)
+ − 790 "Returns non-nil if SYM names a currently-defined error."
+ − 791 (and (symbolp sym) (not (null (get sym 'error-conditions)))))
+ − 792
428
+ − 793 ;;;; Miscellanea.
+ − 794
+ − 795 ;; This is now in C.
444
+ − 796 ;(defun buffer-substring-no-properties (start end)
+ − 797 ; "Return the text from START to END, without text properties, as a string."
+ − 798 ; (let ((string (buffer-substring start end)))
428
+ − 799 ; (set-text-properties 0 (length string) nil string)
+ − 800 ; string))
+ − 801
+ − 802 (defun get-buffer-window-list (&optional buffer minibuf frame)
+ − 803 "Return windows currently displaying BUFFER, or nil if none.
+ − 804 BUFFER defaults to the current buffer.
+ − 805 See `walk-windows' for the meaning of MINIBUF and FRAME."
+ − 806 (cond ((null buffer)
+ − 807 (setq buffer (current-buffer)))
+ − 808 ((not (bufferp buffer))
+ − 809 (setq buffer (get-buffer buffer))))
+ − 810 (let (windows)
+ − 811 (walk-windows (lambda (window)
+ − 812 (if (eq (window-buffer window) buffer)
+ − 813 (push window windows)))
+ − 814 minibuf frame)
+ − 815 windows))
+ − 816
+ − 817 (defun ignore (&rest ignore)
+ − 818 "Do nothing and return nil.
+ − 819 This function accepts any number of arguments, but ignores them."
+ − 820 (interactive)
+ − 821 nil)
+ − 822
+ − 823 (define-function 'eval-in-buffer 'with-current-buffer)
+ − 824 (make-obsolete 'eval-in-buffer 'with-current-buffer)
+ − 825
+ − 826 ;;; The real defn is in abbrev.el but some early callers
+ − 827 ;;; (eg lisp-mode-abbrev-table) want this before abbrev.el is loaded...
+ − 828
+ − 829 (if (not (fboundp 'define-abbrev-table))
+ − 830 (progn
+ − 831 (setq abbrev-table-name-list '())
+ − 832 (fset 'define-abbrev-table (function (lambda (name defs)
+ − 833 ;; These are fixed-up when abbrev.el loads.
+ − 834 (setq abbrev-table-name-list
+ − 835 (cons (cons name defs)
+ − 836 abbrev-table-name-list)))))))
+ − 837
+ − 838 ;;; `functionp' has been moved into C.
+ − 839
+ − 840 ;;(defun functionp (object)
+ − 841 ;; "Non-nil if OBJECT can be called as a function."
+ − 842 ;; (or (and (symbolp object) (fboundp object))
+ − 843 ;; (subrp object)
+ − 844 ;; (compiled-function-p object)
+ − 845 ;; (eq (car-safe object) 'lambda)))
+ − 846
+ − 847
+ − 848
+ − 849 (defun function-interactive (function)
+ − 850 "Return the interactive specification of FUNCTION.
+ − 851 FUNCTION can be any funcallable object.
+ − 852 The specification will be returned as the list of the symbol `interactive'
+ − 853 and the specs.
+ − 854 If FUNCTION is not interactive, nil will be returned."
+ − 855 (setq function (indirect-function function))
+ − 856 (cond ((compiled-function-p function)
+ − 857 (compiled-function-interactive function))
+ − 858 ((subrp function)
+ − 859 (subr-interactive function))
+ − 860 ((eq (car-safe function) 'lambda)
+ − 861 (let ((spec (if (stringp (nth 2 function))
+ − 862 (nth 3 function)
+ − 863 (nth 2 function))))
+ − 864 (and (eq (car-safe spec) 'interactive)
+ − 865 spec)))
+ − 866 (t
+ − 867 (error "Non-funcallable object: %s" function))))
+ − 868
442
+ − 869 (defun function-allows-args (function n)
+ − 870 "Return whether FUNCTION can be called with N arguments."
+ − 871 (and (<= (function-min-args function) n)
+ − 872 (or (null (function-max-args function))
+ − 873 (<= n (function-max-args function)))))
+ − 874
428
+ − 875 ;; This function used to be an alias to `buffer-substring', except
+ − 876 ;; that FSF Emacs 20.4 added a BUFFER argument in an incompatible way.
+ − 877 ;; The new FSF's semantics makes more sense, but we try to support
+ − 878 ;; both for backward compatibility.
+ − 879 (defun buffer-string (&optional buffer old-end old-buffer)
+ − 880 "Return the contents of the current buffer as a string.
+ − 881 If narrowing is in effect, this function returns only the visible part
+ − 882 of the buffer.
+ − 883
+ − 884 If BUFFER is specified, the contents of that buffer are returned.
+ − 885
+ − 886 The arguments OLD-END and OLD-BUFFER are supported for backward
+ − 887 compatibility with pre-21.2 XEmacsen times when arguments to this
+ − 888 function were (buffer-string &optional START END BUFFER)."
+ − 889 (cond
+ − 890 ((or (stringp buffer) (bufferp buffer))
+ − 891 ;; Most definitely the new way.
+ − 892 (buffer-substring nil nil buffer))
+ − 893 ((or (stringp old-buffer) (bufferp old-buffer)
+ − 894 (natnump buffer) (natnump old-end))
+ − 895 ;; Definitely the old way.
+ − 896 (buffer-substring buffer old-end old-buffer))
+ − 897 (t
+ − 898 ;; Probably the old way.
+ − 899 (buffer-substring buffer old-end old-buffer))))
+ − 900
+ − 901 ;; This was not present before. I think Jamie had some objections
+ − 902 ;; to this, so I'm leaving this undefined for now. --ben
+ − 903
+ − 904 ;;; The objection is this: there is more than one way to load the same file.
+ − 905 ;;; "foo", "foo.elc", "foo.el", and "/some/path/foo.elc" are all different
+ − 906 ;;; ways to load the exact same code. `eval-after-load' is too stupid to
+ − 907 ;;; deal with this sort of thing. If this sort of feature is desired, then
+ − 908 ;;; it should work off of a hook on `provide'. Features are unique and
+ − 909 ;;; the arguments to (load) are not. --Stig
+ − 910
+ − 911 ;; We provide this for FSFmacs compatibility, at least until we devise
+ − 912 ;; something better.
+ − 913
+ − 914 ;;;; Specifying things to do after certain files are loaded.
+ − 915
+ − 916 (defun eval-after-load (file form)
+ − 917 "Arrange that, if FILE is ever loaded, FORM will be run at that time.
+ − 918 This makes or adds to an entry on `after-load-alist'.
+ − 919 If FILE is already loaded, evaluate FORM right now.
+ − 920 It does nothing if FORM is already on the list for FILE.
+ − 921 FILE should be the name of a library, with no directory name."
+ − 922 ;; Make sure there is an element for FILE.
+ − 923 (or (assoc file after-load-alist)
+ − 924 (setq after-load-alist (cons (list file) after-load-alist)))
+ − 925 ;; Add FORM to the element if it isn't there.
+ − 926 (let ((elt (assoc file after-load-alist)))
+ − 927 (or (member form (cdr elt))
+ − 928 (progn
+ − 929 (nconc elt (list form))
+ − 930 ;; If the file has been loaded already, run FORM right away.
+ − 931 (and (assoc file load-history)
+ − 932 (eval form)))))
+ − 933 form)
+ − 934 (make-compatible 'eval-after-load "")
+ − 935
+ − 936 (defun eval-next-after-load (file)
+ − 937 "Read the following input sexp, and run it whenever FILE is loaded.
+ − 938 This makes or adds to an entry on `after-load-alist'.
+ − 939 FILE should be the name of a library, with no directory name."
+ − 940 (eval-after-load file (read)))
+ − 941 (make-compatible 'eval-next-after-load "")
+ − 942
+ − 943 ; alternate names (not obsolete)
+ − 944 (if (not (fboundp 'mod)) (define-function 'mod '%))
+ − 945 (define-function 'move-marker 'set-marker)
+ − 946 (define-function 'beep 'ding) ; preserve lingual purity
+ − 947 (define-function 'indent-to-column 'indent-to)
+ − 948 (define-function 'backward-delete-char 'delete-backward-char)
+ − 949 (define-function 'search-forward-regexp (symbol-function 're-search-forward))
+ − 950 (define-function 'search-backward-regexp (symbol-function 're-search-backward))
+ − 951 (define-function 'remove-directory 'delete-directory)
+ − 952 (define-function 'set-match-data 'store-match-data)
+ − 953 (define-function 'send-string-to-terminal 'external-debugging-output)
+ − 954
+ − 955 ;;; subr.el ends here
