diff options
Diffstat (limited to 'lisp/emacs-lisp')
30 files changed, 391 insertions, 250 deletions
diff --git a/lisp/emacs-lisp/advice.el b/lisp/emacs-lisp/advice.el index 8e8d0e22651..1f276c7f7a3 100644 --- a/lisp/emacs-lisp/advice.el +++ b/lisp/emacs-lisp/advice.el @@ -36,12 +36,12 @@ ;; @ Introduction: ;; =============== ;; This package implements a full-fledged Lisp-style advice mechanism -;; for Emacs Lisp. Advice is a clean and efficient way to modify the +;; for Emacs Lisp. Advice is a clean and efficient way to modify the ;; behavior of Emacs Lisp functions without having to keep personal -;; modified copies of such functions around. A great number of such +;; modified copies of such functions around. A great number of such ;; modifications can be achieved by treating the original function as a ;; black box and specifying a different execution environment for it -;; with a piece of advice. Think of a piece of advice as a kind of fancy +;; with a piece of advice. Think of a piece of advice as a kind of fancy ;; hook that you can attach to any function/macro/subr. ;; @ Highlights: @@ -95,7 +95,7 @@ ;; @ Restrictions: ;; =============== ;; - Advised functions/macros/subrs will only exhibit their advised behavior -;; when they are invoked via their function cell. This means that advice will +;; when they are invoked via their function cell. This means that advice will ;; not work for the following: ;; + advised subrs that are called directly from other subrs or C-code ;; + advised subrs that got replaced with their byte-code during @@ -107,7 +107,7 @@ ;; ========== ;; This package is an extension and generalization of packages such as ;; insert-hooks.el written by Noah S. Friedman, and advise.el written by -;; Raul J. Acevedo. Some ideas used in here come from these packages, +;; Raul J. Acevedo. Some ideas used in here come from these packages, ;; others come from the various Lisp advice mechanisms I've come across ;; so far, and a few are simply mine. @@ -235,10 +235,10 @@ ;; found in the list of before/around/after advices will be used. ;; <flags> is a list of symbols that specify further information about the -;; advice. All flags can be specified with unambiguous initial substrings. +;; advice. All flags can be specified with unambiguous initial substrings. ;; `activate': Specifies that the advice information of the advised ;; function should be activated right after this advice has been -;; defined. In forward advices `activate' will be ignored. +;; defined. In forward advices `activate' will be ignored. ;; `protect': Specifies that this advice should be protected against ;; non-local exits and errors in preceding code/advices. ;; `compile': Specifies that the advised function should be byte-compiled. @@ -347,7 +347,7 @@ ;; argument list redefinition given in a piece of advice. While this simple ;; method might be sufficient in many cases, it has the disadvantage that it ;; is not very portable because it hardcodes the argument names into the -;; advice. If the definition of the original function changes the advice +;; advice. If the definition of the original function changes the advice ;; might break even though the code might still be correct. Situations like ;; that arise, for example, if one advises a subr like `eval-region' which ;; gets redefined in a non-advice style into a function by the edebug @@ -443,7 +443,7 @@ ;; of the advised function we need a mapping mechanism that maps this ;; argument list onto that of the original function. Hence SYM and ;; NEWDEF have to be properly mapped onto the &rest variable when the -;; original definition is called. Advice automatically takes care of +;; original definition is called. Advice automatically takes care of ;; that mapping, hence, the advice programmer can specify an argument ;; list without having to know about the exact structure of the ;; original argument list as long as the new argument list takes a @@ -467,7 +467,7 @@ ;; The advised definition will get compiled either if `ad-activate' was called ;; interactively with a prefix argument, or called explicitly with its second ;; argument as t, or, if `ad-default-compilation-action' justifies it according -;; to the current system state. If the advised definition was +;; to the current system state. If the advised definition was ;; constructed during "preactivation" (see below) then that definition will ;; be already compiled because it was constructed during byte-compilation of ;; the file that contained the `defadvice' with the `preactivate' flag. @@ -707,7 +707,7 @@ ;; @@ Adding a piece of advice with `ad-add-advice': ;; ================================================= ;; The non-interactive function `ad-add-advice' can be used to add a piece of -;; advice to some function without using `defadvice'. This is useful if advice +;; advice to some function without using `defadvice'. This is useful if advice ;; has to be added somewhere by a function (also look at `ad-make-advice'). ;; @@ Activation/deactivation advices, file load hooks: @@ -739,7 +739,7 @@ ;; A piece of advice gets defined with `defadvice' and added to the ;; `advice-info' property of a function. ;; - Enablement: -;; Every piece of advice has an enablement flag associated with it. Only +;; Every piece of advice has an enablement flag associated with it. Only ;; enabled advices are considered during construction of an advised ;; definition. ;; - Activation: @@ -808,9 +808,9 @@ ;; argument access text macros to get/set the values of ;; actual arguments at a certain position ;; ad-arg-bindings text macro that returns the actual names, values -;; and types of the arguments as a list of bindings. The +;; and types of the arguments as a list of bindings. The ;; order of the bindings corresponds to the order of the -;; arguments. The individual fields of every binding (name, +;; arguments. The individual fields of every binding (name, ;; value and type) can be accessed with the function ;; `ad-arg-binding-field' (see example above). ;; ad-do-it text macro that identifies the place where the original @@ -839,20 +839,20 @@ ;; use the macro `defadvice' which takes a function name, a list of advice ;; specifiers and a list of body forms as arguments. The first element of ;; the advice specifiers is the class of the advice, the second is its name, -;; the third its position and the rest are some flags. The class of our +;; the third its position and the rest are some flags. The class of our ;; first advice is `before', its name is `fg-add2', its position among the ;; currently defined before advices (none so far) is `first', and the advice -;; will be `activate'ed immediately. Advice names are global symbols, hence, -;; the name space conventions used for function names should be applied. All +;; will be `activate'ed immediately. Advice names are global symbols, hence, +;; the name space conventions used for function names should be applied. All ;; advice names in this tutorial will be prefixed with `fg' for `Foo Games' ;; (because everybody has the right to be inconsistent all the function names ;; used in this tutorial do NOT follow this convention). ;; ;; In the body of an advice we can refer to the argument variables of the -;; original function by name. Here we add 1 to X so the effect of calling +;; original function by name. Here we add 1 to X so the effect of calling ;; `foo' will be to actually add 2. All of the advice definitions below only ;; have one body form for simplicity, but there is no restriction to that -;; extent. Every piece of advice can have a documentation string which will +;; extent. Every piece of advice can have a documentation string which will ;; be combined with the documentation of the original function. ;; ;; (defadvice foo (before fg-add2 first activate) @@ -866,11 +866,11 @@ ;; @@ Specifying the position of an advice: ;; ======================================== ;; Now we define the second before advice which will cancel the effect of -;; the previous advice. This time we specify the position as 0 which is -;; equivalent to `first'. A number can be used to specify the zero-based -;; position of an advice among the list of advices in the same class. This +;; the previous advice. This time we specify the position as 0 which is +;; equivalent to `first'. A number can be used to specify the zero-based +;; position of an advice among the list of advices in the same class. This ;; time we already have one before advice hence the position specification -;; actually has an effect. So, after the following definition the position +;; actually has an effect. So, after the following definition the position ;; of the previous advice will be 1 even though we specified it with `first' ;; above, the reason for this is that the position argument is relative to ;; the currently defined pieces of advice which by now has changed. @@ -886,7 +886,7 @@ ;; @@ Redefining a piece of advice: ;; ================================ ;; Now we define an advice with the same class and same name but with a -;; different position. Defining an advice in a class in which an advice with +;; different position. Defining an advice in a class in which an advice with ;; that name already exists is interpreted as a redefinition of that ;; particular advice, in which case the position argument will be ignored ;; and the previous position of the redefined piece of advice is used. @@ -919,7 +919,7 @@ ;; ================================= ;; We can make a function interactive (or change its interactive behavior) ;; by specifying an interactive form in one of the before or around -;; advices (there could also be body forms in this advice). The particular +;; advices (there could also be body forms in this advice). The particular ;; definition always assigns 5 as an argument to X which gives us 6 as a ;; result when we call foo interactively: ;; @@ -945,13 +945,13 @@ ;; ;; @@ Around advices: ;; ================== -;; Now we'll try some `around' advices. An around advice is a wrapper around -;; the original definition. It can shadow or establish bindings for the +;; Now we'll try some `around' advices. An around advice is a wrapper around +;; the original definition. It can shadow or establish bindings for the ;; original definition, and it can look at and manipulate the value returned -;; by the original function. The position of the special keyword `ad-do-it' -;; specifies where the code of the original function will be executed. The +;; by the original function. The position of the special keyword `ad-do-it' +;; specifies where the code of the original function will be executed. The ;; keyword can appear multiple times which will result in multiple calls of -;; the original function in the resulting advised code. Note, that if we don't +;; the original function in the resulting advised code. Note, that if we don't ;; specify a position argument (i.e., `first', `last' or a number), then ;; `first' (or 0) is the default): ;; @@ -967,7 +967,7 @@ ;; Around advices are assembled like onion skins where the around advice ;; with position 0 is the outermost skin and the advice at the last position ;; is the innermost skin which is directly wrapped around the call of the -;; original definition of the function. Hence, after the next `defadvice' we +;; original definition of the function. Hence, after the next `defadvice' we ;; will first multiply X by 2 then add 1 and then call the original ;; definition (i.e., add 1 again): ;; @@ -984,8 +984,8 @@ ;; ================================= ;; In every `defadvice' so far we have used the flag `activate' to activate ;; the advice immediately after its definition, and that's what we want in -;; most cases. However, if we define multiple pieces of advice for a single -;; function then activating every advice immediately is inefficient. A +;; most cases. However, if we define multiple pieces of advice for a single +;; function then activating every advice immediately is inefficient. A ;; better way to do this is to only activate the last defined advice. ;; For example: ;; @@ -1077,7 +1077,7 @@ ;; neutralize the effect of the advice of one of the packages. ;; ;; The following disables the after advice `fg-times-x' in the function `foo'. -;; All that does is to change a flag for this particular advice. All the +;; All that does is to change a flag for this particular advice. All the ;; other information defining it will be left unchanged (e.g., its relative ;; position in this advice class, etc.). ;; @@ -1094,9 +1094,9 @@ ;; 24 ;; ;; If we want to disable all multiplication advices in `foo' we can use a -;; regular expression that matches the names of such advices. Actually, any +;; regular expression that matches the names of such advices. Actually, any ;; advice name that contains a match for the regular expression will be -;; called a match. A special advice class `any' can be used to consider +;; called a match. A special advice class `any' can be used to consider ;; all advice classes: ;; ;; (ad-disable-advice 'foo 'any "^fg-.*times") @@ -1122,7 +1122,7 @@ ;; 9 ;; ;; The following will activate all currently active advised functions that -;; contain some advice matched by the regular expression. This is a save +;; contain some advice matched by the regular expression. This is a save ;; way to update the activation of advised functions whose advice changed ;; in some way or other without accidentally also activating currently ;; inactive functions: @@ -1136,7 +1136,7 @@ ;; ;; Another use for the dis/enablement mechanism is to define a piece of advice ;; and keep it "dormant" until a particular condition is satisfied, i.e., until -;; then the advice will not be used during activation. The `disable' flag lets +;; then the advice will not be used during activation. The `disable' flag lets ;; one do that with `defadvice': ;; ;; (defadvice foo (before fg-1-more dis) @@ -1165,7 +1165,7 @@ ;; =========== ;; Advised definitions get cached to allow efficient activation/deactivation ;; without having to reconstruct them if nothing in the advice-info of a -;; function has changed. The following idiom can be used to temporarily +;; function has changed. The following idiom can be used to temporarily ;; deactivate functions that have a piece of advice defined by a certain ;; package (we save the old definition to check out caching): ;; @@ -1350,9 +1350,9 @@ ;; @@ Portable argument access: ;; ============================ ;; So far, we always used the actual argument variable names to access an -;; argument in a piece of advice. For many advice applications this is -;; perfectly ok and keeps advices simple. However, it decreases portability -;; of advices because it assumes specific argument variable names. For example, +;; argument in a piece of advice. For many advice applications this is +;; perfectly ok and keeps advices simple. However, it decreases portability +;; of advices because it assumes specific argument variable names. For example, ;; if one advises a subr such as `eval-region' which then gets redefined by ;; some package (e.g., edebug) into a function with different argument names, ;; then a piece of advice written for `eval-region' that was written with @@ -1360,7 +1360,7 @@ ;; ;; Argument access text macros allow one to access arguments of an advised ;; function in a portable way without having to worry about all these -;; possibilities. These macros will be translated into the proper access forms +;; possibilities. These macros will be translated into the proper access forms ;; at activation time, hence, argument access will be as efficient as if ;; the arguments had been used directly in the definition of the advice. ;; @@ -1386,7 +1386,7 @@ ;; (fuu 1 1 1) ;; 6 ;; -;; Now suppose somebody redefines `fuu' with a rest argument. Our advice +;; Now suppose somebody redefines `fuu' with a rest argument. Our advice ;; will still work because we used access macros (note, that automatic ;; advice activation is still in effect, hence, the redefinition of `fuu' ;; will automatically activate all its advice): @@ -1444,9 +1444,9 @@ ;; give it an extra argument that controls the advised code, for example, one ;; might want to make an interactive function sensitive to a prefix argument. ;; For such cases `defadvice' allows the specification of an argument list -;; for the advised function. Similar to the redefinition of interactive +;; for the advised function. Similar to the redefinition of interactive ;; behavior, the first argument list specification found in the list of before/ -;; around/after advices will be used. Of course, the specified argument list +;; around/after advices will be used. Of course, the specified argument list ;; should be downward compatible with the original argument list, otherwise ;; functions that call the advised function with the original argument list ;; in mind will break. @@ -1457,9 +1457,9 @@ ;; fii ;; ;; Now we advise `fii' to use an optional second argument that controls the -;; amount of incrementing. A list following the (optional) position +;; amount of incrementing. A list following the (optional) position ;; argument of the advice will be interpreted as an argument list -;; specification. This means you cannot specify an empty argument list, and +;; specification. This means you cannot specify an empty argument list, and ;; why would you want to anyway? ;; ;; (defadvice fii (before fg-inc-x (x &optional incr) act) @@ -1476,22 +1476,22 @@ ;; @@ Advising interactive subrs: ;; ============================== ;; For the most part there is no difference between advising functions and -;; advising subrs. There is one situation though where one might have to write -;; slightly different advice code for subrs than for functions. This case +;; advising subrs. There is one situation though where one might have to write +;; slightly different advice code for subrs than for functions. This case ;; arises when one wants to access subr arguments in a before/around advice ;; when the arguments were determined by an interactive call to the subr. ;; Advice cannot determine what `interactive' form determines the interactive ;; behavior of the subr, hence, when it calls the original definition in an ;; interactive subr invocation it has to use `call-interactively' to generate -;; the proper interactive behavior. Thus up to that call the arguments of the -;; interactive subr will be nil. For example, the following advice for +;; the proper interactive behavior. Thus up to that call the arguments of the +;; interactive subr will be nil. For example, the following advice for ;; `kill-buffer' will not work in an interactive invocation... ;; ;; (defadvice kill-buffer (before fg-kill-buffer-hook first act preact comp) ;; (my-before-kill-buffer-hook (ad-get-arg 0))) ;; kill-buffer ;; -;; ...because the buffer argument will be nil in that case. The way out of +;; ...because the buffer argument will be nil in that case. The way out of ;; this dilemma is to provide an `interactive' specification that mirrors ;; the interactive behavior of the unadvised subr, for example, the following ;; will do the right thing even when `kill-buffer' is called interactively: @@ -1508,10 +1508,10 @@ ;; For an advised macro instead of evaluating the original definition we ;; use `macroexpand', that is, changing argument values and binding ;; environments by pieces of advice has an affect during macro expansion -;; but not necessarily during evaluation. In particular, any side effects +;; but not necessarily during evaluation. In particular, any side effects ;; of pieces of advice will occur during macro expansion. To also affect ;; the behavior during evaluation time one has to change the value of -;; `ad-return-value' in a piece of after advice. For example: +;; `ad-return-value' in a piece of after advice. For example: ;; ;; (defmacro foom (x) ;; `(list ,x)) @@ -1562,7 +1562,7 @@ ;; because it allows one to influence macro expansion as well as evaluation. ;; In general, advising macros should be a rather rare activity anyway, in ;; particular, because compile-time macro expansion takes away a lot of the -;; flexibility and effectiveness of the advice mechanism. Macros that were +;; flexibility and effectiveness of the advice mechanism. Macros that were ;; compile-time expanded before the advice was activated will of course never ;; exhibit the advised behavior. diff --git a/lisp/emacs-lisp/byte-opt.el b/lisp/emacs-lisp/byte-opt.el index ff512cca36f..966ef266b9a 100644 --- a/lisp/emacs-lisp/byte-opt.el +++ b/lisp/emacs-lisp/byte-opt.el @@ -310,13 +310,6 @@ Earlier variables shadow later ones with the same name.") ;;; implementing source-level optimizers -(defvar byte-optimize--vars-outside-condition nil - "Alist of variables lexically bound outside conditionally executed code. -Variables here are sensitive to mutation inside the conditional code, -since their contents in sequentially later code depends on the path taken -and may no longer be statically known. -Same format as `byte-optimize--lexvars', with shared structure and contents.") - (defvar byte-optimize--vars-outside-loop nil "Alist of variables lexically bound outside the innermost `while' loop. Variables here are sensitive to mutation inside the loop, since this can @@ -327,6 +320,13 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") (defvar byte-optimize--dynamic-vars nil "List of variables declared as dynamic during optimisation.") +(defvar byte-optimize--aliased-vars nil + "List of variables which may be aliased by other lexical variables. +If an entry in `byte-optimize--lexvars' has another variable as its VALUE, +then that other variable must be in this list. +This variable thus carries no essential information but is maintained +for speeding up processing.") + (defun byte-optimize--substitutable-p (expr) "Whether EXPR is a constant that can be propagated." ;; Only consider numbers, symbols and strings to be values for substitution @@ -425,19 +425,19 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") (`(,(or 'let 'let*) . ,rest) (cons fn (byte-optimize-let-form fn rest for-effect))) (`(cond . ,clauses) - ;; The condition in the first clause is always executed, but - ;; right now we treat all of them as conditional for simplicity. - (let ((byte-optimize--vars-outside-condition byte-optimize--lexvars)) - (cons fn - (mapcar (lambda (clause) - (if (consp clause) - (cons - (byte-optimize-form (car clause) nil) - (byte-optimize-body (cdr clause) for-effect)) - (byte-compile-warn "malformed cond form: `%s'" - (prin1-to-string clause)) - clause)) - clauses)))) + ;; FIXME: The condition in the first clause is always executed, and + ;; clause bodies are mutually exclusive -- use this for improved + ;; optimisation (see comment about `if' below). + (cons fn + (mapcar (lambda (clause) + (if (consp clause) + (cons + (byte-optimize-form (car clause) nil) + (byte-optimize-body (cdr clause) for-effect)) + (byte-compile-warn "malformed cond form: `%s'" + (prin1-to-string clause)) + clause)) + clauses))) (`(progn . ,exps) ;; As an extra added bonus, this simplifies (progn <x>) --> <x>. (if (cdr exps) @@ -463,22 +463,15 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") ;; FIXME: We are conservative here: any variable changed in the ;; THEN branch will be barred from substitution in the ELSE ;; branch, despite the branches being mutually exclusive. - - ;; The test is always executed. (let* ((test-opt (byte-optimize-form test nil)) (const (macroexp-const-p test-opt)) - ;; The branches are traversed unconditionally when possible. - (byte-optimize--vars-outside-condition - (if const - byte-optimize--vars-outside-condition - byte-optimize--lexvars)) ;; Avoid traversing dead branches. (then-opt (and test-opt (byte-optimize-form then for-effect))) (else-opt (and (not (and test-opt const)) (byte-optimize-body else for-effect)))) `(if ,test-opt ,then-opt . ,else-opt))) - (`(,(or 'and 'or) . ,exps) ; Remember, and/or are control structures. + (`(,(or 'and 'or) . ,exps) ;; FIXME: We have to traverse the expressions in left-to-right ;; order (because that is the order of evaluation and variable ;; mutations must be found prior to their use), but doing so we miss @@ -487,19 +480,11 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") ;; Then A could be optimised in a for-effect context too. (let ((tail exps) (args nil)) - (when tail - ;; The first argument is always unconditional. + (while tail (push (byte-optimize-form (car tail) (and for-effect (null (cdr tail)))) args) - (setq tail (cdr tail)) - ;; Remaining arguments are conditional. - (let ((byte-optimize--vars-outside-condition byte-optimize--lexvars)) - (while tail - (push (byte-optimize-form - (car tail) (and for-effect (null (cdr tail)))) - args) - (setq tail (cdr tail))))) + (setq tail (cdr tail))) (cons fn (nreverse args)))) (`(while ,exp . ,exps) @@ -508,13 +493,11 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") ;; but this misses many opportunities: variables not mutated in the ;; loop at all, and variables affecting the initial condition (which ;; is always executed unconditionally). - (let* ((byte-optimize--vars-outside-condition byte-optimize--lexvars) - (byte-optimize--vars-outside-loop byte-optimize--lexvars) + (let* ((byte-optimize--vars-outside-loop byte-optimize--lexvars) (condition (byte-optimize-form exp nil)) (body (byte-optimize-body exps t))) `(while ,condition . ,body))) - (`(interactive . ,_) (byte-compile-warn "misplaced interactive spec: `%s'" (prin1-to-string form)) @@ -526,19 +509,18 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") form) (`(condition-case ,var ,exp . ,clauses) - (let ((byte-optimize--vars-outside-condition byte-optimize--lexvars)) - `(condition-case ,var ;Not evaluated. - ,(byte-optimize-form exp for-effect) - ,@(mapcar (lambda (clause) - (let ((byte-optimize--lexvars - (and lexical-binding - (if var - (cons (list var t) - byte-optimize--lexvars) - byte-optimize--lexvars)))) - (cons (car clause) - (byte-optimize-body (cdr clause) for-effect)))) - clauses)))) + `(condition-case ,var ;Not evaluated. + ,(byte-optimize-form exp for-effect) + ,@(mapcar (lambda (clause) + (let ((byte-optimize--lexvars + (and lexical-binding + (if var + (cons (list var t) + byte-optimize--lexvars) + byte-optimize--lexvars)))) + (cons (car clause) + (byte-optimize-body (cdr clause) for-effect)))) + clauses))) (`(unwind-protect ,exp . ,exps) ;; The unwinding part of an unwind-protect is compiled (and thus @@ -547,8 +529,7 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") ;; protected part has the same for-effect status as the ;; unwind-protect itself. (The unwinding part is always for effect, ;; but that isn't handled properly yet.) - (let* ((byte-optimize--vars-outside-condition byte-optimize--lexvars) - (bodyform (byte-optimize-form exp for-effect))) + (let ((bodyform (byte-optimize-form exp for-effect))) (pcase exps (`(:fun-body ,f) `(unwind-protect ,bodyform @@ -558,9 +539,8 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") . ,(byte-optimize-body exps t)))))) (`(catch ,tag . ,exps) - (let ((byte-optimize--vars-outside-condition byte-optimize--lexvars)) - `(catch ,(byte-optimize-form tag nil) - . ,(byte-optimize-body exps for-effect)))) + `(catch ,(byte-optimize-form tag nil) + . ,(byte-optimize-body exps for-effect))) ;; Needed as long as we run byte-optimize-form after cconv. (`(internal-make-closure . ,_) @@ -595,7 +575,15 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") (value (byte-optimize-form expr nil))) (when lexvar (setcar (cdr lexvar) t) ; Mark variable to be kept. - (setcdr (cdr lexvar) nil)) ; Inhibit further substitution. + (setcdr (cdr lexvar) nil) ; Inhibit further substitution. + + (when (memq var byte-optimize--aliased-vars) + ;; Cancel aliasing of variables aliased to this one. + (dolist (v byte-optimize--lexvars) + (when (eq (nth 2 v) var) + ;; V is bound to VAR but VAR is now mutated: + ;; cancel aliasing. + (setcdr (cdr v) nil))))) (push var var-expr-list) (push value var-expr-list)) @@ -666,34 +654,142 @@ Same format as `byte-optimize--lexvars', with shared structure and contents.") (not (eq new old)))))))) form) +(defun byte-optimize--rename-var-body (var new-var body) + "Replace VAR with NEW-VAR in BODY." + (mapcar (lambda (form) (byte-optimize--rename-var var new-var form)) body)) + +(defun byte-optimize--rename-var (var new-var form) + "Replace VAR with NEW-VAR in FORM." + (pcase form + ((pred symbolp) (if (eq form var) new-var form)) + (`(setq . ,args) + (let ((new-args nil)) + (while args + (push (byte-optimize--rename-var var new-var (car args)) new-args) + (push (byte-optimize--rename-var var new-var (cadr args)) new-args) + (setq args (cddr args))) + `(setq . ,(nreverse new-args)))) + ;; In binding constructs like `let', `let*' and `condition-case' we + ;; rename everything for simplicity, even new bindings named VAR. + (`(,(and head (or 'let 'let*)) ,bindings . ,body) + `(,head + ,(mapcar (lambda (b) (byte-optimize--rename-var-body var new-var b)) + bindings) + ,@(byte-optimize--rename-var-body var new-var body))) + (`(condition-case ,res-var ,protected-form . ,handlers) + `(condition-case ,(byte-optimize--rename-var var new-var res-var) + ,(byte-optimize--rename-var var new-var protected-form) + ,@(mapcar (lambda (h) + (cons (car h) + (byte-optimize--rename-var-body var new-var (cdr h)))) + handlers))) + (`(internal-make-closure ,vars ,env . ,rest) + `(internal-make-closure + ,vars ,(byte-optimize--rename-var-body var new-var env) . ,rest)) + (`(defvar ,name . ,rest) + ;; NAME is not renamed here; we only care about lexical variables. + `(defvar ,name . ,(byte-optimize--rename-var-body var new-var rest))) + + (`(cond . ,clauses) + `(cond ,@(mapcar (lambda (c) + (byte-optimize--rename-var-body var new-var c)) + clauses))) + + (`(function . ,_) form) + (`(quote . ,_) form) + (`(lambda . ,_) form) + + ;; Function calls and special forms not handled above. + (`(,head . ,args) + `(,head . ,(byte-optimize--rename-var-body var new-var args))) + (_ form))) + (defun byte-optimize-let-form (head form for-effect) ;; Recursively enter the optimizer for the bindings and body ;; of a let or let*. This for depth-firstness: forms that ;; are more deeply nested are optimized first. (if lexical-binding (let* ((byte-optimize--lexvars byte-optimize--lexvars) + (byte-optimize--aliased-vars byte-optimize--aliased-vars) (new-lexvars nil) - (let-vars nil)) - (dolist (binding (car form)) - (let* ((name (car binding)) - (expr (byte-optimize-form (cadr binding) nil)) - (value (and (byte-optimize--substitutable-p expr) - (list expr))) - (lexical (not (or (special-variable-p name) - (memq name byte-compile-bound-variables) - (memq name byte-optimize--dynamic-vars)))) - (lexinfo (and lexical (cons name (cons nil value))))) - (push (cons name (cons expr (cdr lexinfo))) let-vars) - (when lexinfo - (push lexinfo (if (eq head 'let*) - byte-optimize--lexvars - new-lexvars))))) + (new-aliased-vars nil) + (let-vars nil) + (body (cdr form)) + (bindings (car form))) + (while bindings + (let* ((binding (car bindings)) + (name (car binding)) + (expr (byte-optimize-form (cadr binding) nil))) + (setq bindings (cdr bindings)) + (when (and (eq head 'let*) + (memq name byte-optimize--aliased-vars)) + ;; New variable shadows an aliased variable -- α-rename + ;; it in this and all subsequent bindings. + (let ((new-name (make-symbol (symbol-name name)))) + (setq bindings + (mapcar (lambda (b) + (list (byte-optimize--rename-var + name new-name (car b)) + (byte-optimize--rename-var + name new-name (cadr b)))) + bindings)) + (setq body (byte-optimize--rename-var-body name new-name body)) + (setq name new-name))) + (let* ((aliased nil) + (value (and + (or (byte-optimize--substitutable-p expr) + ;; Aliasing another lexvar. + (setq aliased + (and (symbolp expr) + (assq expr byte-optimize--lexvars)))) + (list expr))) + (lexical (not (or (special-variable-p name) + (memq name byte-compile-bound-variables) + (memq name byte-optimize--dynamic-vars)))) + (lexinfo (and lexical (cons name (cons nil value))))) + (push (cons name (cons expr (cdr lexinfo))) let-vars) + (when lexinfo + (push lexinfo (if (eq head 'let*) + byte-optimize--lexvars + new-lexvars))) + (when aliased + (push expr (if (eq head 'let*) + byte-optimize--aliased-vars + new-aliased-vars)))))) + + (setq byte-optimize--aliased-vars + (append new-aliased-vars byte-optimize--aliased-vars)) + (when (and (eq head 'let) byte-optimize--aliased-vars) + ;; Find new variables that shadow aliased variables. + (let ((shadowing-vars nil)) + (dolist (lexvar new-lexvars) + (let ((name (car lexvar))) + (when (and (memq name byte-optimize--aliased-vars) + (not (memq name shadowing-vars))) + (push name shadowing-vars)))) + ;; α-rename them + (dolist (name shadowing-vars) + (let ((new-name (make-symbol (symbol-name name)))) + (setq new-lexvars + (mapcar (lambda (lexvar) + (if (eq (car lexvar) name) + (cons new-name (cdr lexvar)) + lexvar)) + new-lexvars)) + (setq let-vars + (mapcar (lambda (v) + (if (eq (car v) name) + (cons new-name (cdr v)) + v)) + let-vars)) + (setq body (byte-optimize--rename-var-body + name new-name body)))))) (setq byte-optimize--lexvars (append new-lexvars byte-optimize--lexvars)) ;; Walk the body expressions, which may mutate some of the records, ;; and generate new bindings that exclude unused variables. (let* ((byte-optimize--dynamic-vars byte-optimize--dynamic-vars) - (opt-body (byte-optimize-body (cdr form) for-effect)) + (opt-body (byte-optimize-body body for-effect)) (bindings nil)) (dolist (var let-vars) ;; VAR is (NAME EXPR [KEEP [VALUE]]) diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el index 8ea591b5d0e..776e84dfebb 100644 --- a/lisp/emacs-lisp/bytecomp.el +++ b/lisp/emacs-lisp/bytecomp.el @@ -26,7 +26,7 @@ ;;; Commentary: -;; The Emacs Lisp byte compiler. This crunches lisp source into a sort +;; The Emacs Lisp byte compiler. This crunches Lisp source into a sort ;; of p-code (`lapcode') which takes up less space and can be interpreted ;; faster. [`LAP' == `Lisp Assembly Program'.] ;; The user entry points are byte-compile-file and byte-recompile-directory. @@ -319,7 +319,7 @@ Elements of the list may be: lexical global/dynamic variables lacking a prefix. lexical-dynamic lexically bound variable declared dynamic elsewhere - make-local calls to make-variable-buffer-local that may be incorrect. + make-local calls to `make-variable-buffer-local' that may be incorrect. mapcar mapcar called for effect. constants let-binding of, or assignment to, constants/nonvariables. docstrings docstrings that are too wide (longer than @@ -2257,6 +2257,9 @@ With argument ARG, insert value in current buffer after the form." (push `(native-comp-speed . ,native-comp-speed) byte-native-qualities) (defvar native-comp-debug) (push `(native-comp-debug . ,native-comp-debug) byte-native-qualities) + (defvar native-comp-compiler-options) + (push `(native-comp-compiler-options . ,native-comp-compiler-options) + byte-native-qualities) (defvar native-comp-driver-options) (push `(native-comp-driver-options . ,native-comp-driver-options) byte-native-qualities) @@ -3559,7 +3562,7 @@ for symbols generated by the byte compiler itself." "Warn if symbol VAR refers to a free variable. VAR must not be lexically bound. If optional argument ASSIGNMENT is non-nil, this is treated as an -assignment (i.e. `setq'). " +assignment (i.e. `setq')." (unless (or (not (byte-compile-warning-enabled-p 'free-vars var)) (boundp var) (memq var byte-compile-bound-variables) @@ -4332,7 +4335,7 @@ that suppresses all warnings during execution of BODY." (and (symbolp obj2) (macroexp-const-p obj1) (cons obj2 (eval obj1))))) (defun byte-compile--common-test (test-1 test-2) - "Most specific common test of `eq', `eql' and `equal'" + "Most specific common test of `eq', `eql' and `equal'." (cond ((or (eq test-1 'equal) (eq test-2 'equal)) 'equal) ((or (eq test-1 'eql) (eq test-2 'eql)) 'eql) (t 'eq))) diff --git a/lisp/emacs-lisp/cconv.el b/lisp/emacs-lisp/cconv.el index 3abbf716875..ba29e4ec85e 100644 --- a/lisp/emacs-lisp/cconv.el +++ b/lisp/emacs-lisp/cconv.el @@ -32,7 +32,7 @@ ;; Here is a brief explanation how this code works. ;; Firstly, we analyze the tree by calling cconv-analyze-form. ;; This function finds all mutated variables, all functions that are suitable -;; for lambda lifting and all variables captured by closure. It passes the tree +;; for lambda lifting and all variables captured by closure. It passes the tree ;; once, returning a list of three lists. ;; ;; Then we calculate the intersection of the first and third lists returned by diff --git a/lisp/emacs-lisp/check-declare.el b/lisp/emacs-lisp/check-declare.el index bec4ad92503..83a9d3ea6ae 100644 --- a/lisp/emacs-lisp/check-declare.el +++ b/lisp/emacs-lisp/check-declare.el @@ -119,7 +119,7 @@ don't know how to recognize (e.g. some macros)." (autoload 'byte-compile-arglist-signature "bytecomp") (defgroup check-declare nil - "Check declare-function statements." + "Check `declare-function' statements." :group 'tools) (defcustom check-declare-ext-errors nil @@ -230,8 +230,8 @@ fset\\|\\(?:cl-\\)?defmethod\\)\\>" type) errlist)) (defun check-declare-sort (alist) - "Sort a list with elements FILE (FNFILE ...). -Returned list has elements FNFILE (FILE ...)." + "Sort list ALIST with elements FILE (FNFILE ...). +Return list with elements FNFILE (FILE ...)." (let (file fnfile rest sort a) (dolist (e alist) (setq file (car e)) diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el index 00cc7777e1a..e10ea736cd2 100644 --- a/lisp/emacs-lisp/checkdoc.el +++ b/lisp/emacs-lisp/checkdoc.el @@ -304,13 +304,22 @@ variable `checkdoc-common-verbs-wrong-voice' if you wish to add your own." Do not set this by hand, use a function like `checkdoc-current-buffer' with a universal argument.") -(defcustom checkdoc-symbol-words nil +(defcustom checkdoc-symbol-words '("byte-code" "command-line" "top-level") "A list of symbol names (strings) which also happen to make good words. These words are ignored when unquoted symbols are searched for. This should be set in an Emacs Lisp file's local variables." - :type '(repeat (symbol :tag "Word"))) + :type '(repeat (string :tag "Word")) + :version "28.1") ;;;###autoload(put 'checkdoc-symbol-words 'safe-local-variable #'checkdoc-list-of-strings-p) +(defcustom checkdoc-column-zero-backslash-before-paren t + "Non-nil means to warn if there is no '\\' before '(' in column zero. +This backslash is no longer needed on Emacs 27.1 or later. + +See Info node `(elisp) Documentation Tips' for background." + :type 'boolean + :version "28.1") + ;;;###autoload (defun checkdoc-list-of-strings-p (obj) "Return t when OBJ is a list of strings." @@ -320,7 +329,7 @@ This should be set in an Emacs Lisp file's local variables." (not (memq nil (mapcar #'stringp obj))))) (defvar checkdoc-proper-noun-list - '("ispell" "xemacs" "emacs" "lisp") + '("ispell" "emacs" "lisp") "List of words (not capitalized) which should be capitalized.") (defvar checkdoc-proper-noun-regexp @@ -1402,16 +1411,17 @@ buffer, otherwise stop after the first error." (match-beginning 1) (match-end 1))))) ;; * Check for '(' in column 0. - (save-excursion - (when (re-search-forward "^(" e t) - (if (checkdoc-autofix-ask-replace (match-beginning 0) - (match-end 0) - (format-message "Escape this `('? ") - "\\(") - nil - (checkdoc-create-error - "Open parenthesis in column 0 should be escaped" - (match-beginning 0) (match-end 0))))) + (when checkdoc-column-zero-backslash-before-paren + (save-excursion + (when (re-search-forward "^(" e t) + (if (checkdoc-autofix-ask-replace (match-beginning 0) + (match-end 0) + (format-message "Escape this `('? ") + "\\(") + nil + (checkdoc-create-error + "Open parenthesis in column 0 should be escaped" + (match-beginning 0) (match-end 0)))))) ;; * Do not start or end a documentation string with whitespace. (let (start end) (if (or (if (looking-at "\"\\([ \t\n]+\\)") @@ -1998,6 +2008,32 @@ The text checked is between START and LIMIT." (setq c (1+ c))) (and (< 0 c) (= (% c 2) 0)))))) +(defun checkdoc-in-abbreviation-p (begin) + "Return non-nil if point is at an abbreviation. +Examples of abbreviations handled: \"e.g.\", \"i.e.\", \"cf.\"." + (save-excursion + (goto-char begin) + (condition-case nil + (progn + (forward-sexp -1) + ;; Piece of an abbreviation. + (looking-at + (rx (or letter ; single letter, as in "a." + (seq + ;; There might exist an escaped parenthesis, as + ;; this is often used in docstrings. In this + ;; case, `forward-sexp' will have skipped over it, + ;; so we need to skip it here too. + (? "\\(") + ;; The abbreviations: + (or (seq (any "cC") "f") ; cf. + (seq (any "eE") ".g") ; e.g. + (seq (any "iI") "." (any "eE")))) ; i.e. + "etc" ; etc. + "vs") ; vs. + "."))) + (error t)))) + (defun checkdoc-proper-noun-region-engine (begin end) "Check all text between BEGIN and END for lower case proper nouns. These are Emacs centric proper nouns which should be capitalized for @@ -2060,16 +2096,7 @@ If the offending word is in a piece of quoted text, then it is skipped." (e (match-end 1))) (unless (or (checkdoc-in-sample-code-p begin end) (checkdoc-in-example-string-p begin end) - (save-excursion - (goto-char b) - (condition-case nil - (progn - (forward-sexp -1) - ;; piece of an abbreviation - ;; FIXME etc - (looking-at - "\\([a-zA-Z]\\|[iI]\\.?e\\|[eE]\\.?g\\|[cC]f\\)\\.")) - (error t)))) + (checkdoc-in-abbreviation-p b)) (if (checkdoc-autofix-ask-replace b e "There should be two spaces after a period. Fix? " diff --git a/lisp/emacs-lisp/cl-indent.el b/lisp/emacs-lisp/cl-indent.el index c88e15d5a8b..9d8aae28441 100644 --- a/lisp/emacs-lisp/cl-indent.el +++ b/lisp/emacs-lisp/cl-indent.el @@ -162,9 +162,9 @@ is set to `defun'.") (error t))) (defun lisp-indent-find-method (symbol &optional no-compat) - "Find the lisp indentation function for SYMBOL. + "Find the Lisp indentation function for SYMBOL. If NO-COMPAT is non-nil, do not retrieve indenters intended for -the standard lisp indent package." +the standard Lisp indent package." (or (and (derived-mode-p 'emacs-lisp-mode) (get symbol 'common-lisp-indent-function-for-elisp)) (get symbol 'common-lisp-indent-function) diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el index 4ea583d28f1..16308b3a595 100644 --- a/lisp/emacs-lisp/cl-macs.el +++ b/lisp/emacs-lisp/cl-macs.el @@ -3277,7 +3277,7 @@ the form NAME which is a shorthand for (NAME NAME)." (defun cl-struct-sequence-type (struct-type) "Return the sequence used to build STRUCT-TYPE. STRUCT-TYPE is a symbol naming a struct type. Return `record', -`vector`, or `list' if STRUCT-TYPE is a struct type, nil otherwise." +`vector', or `list' if STRUCT-TYPE is a struct type, nil otherwise." (declare (side-effect-free t) (pure t)) (cl--struct-class-type (cl--struct-get-class struct-type))) diff --git a/lisp/emacs-lisp/comp.el b/lisp/emacs-lisp/comp.el index 80a1da5ad8c..bb135457e20 100644 --- a/lisp/emacs-lisp/comp.el +++ b/lisp/emacs-lisp/comp.el @@ -166,6 +166,16 @@ if `confirm-kill-processes' is non-nil." :type 'boolean :version "28.1") +(defcustom native-comp-compiler-options nil + "Command line options passed verbatim to GCC compiler. +Note that not all options are meaningful and some options might even +break your Emacs. Use at your own risk. + +Passing these options is only available in libgccjit version 9 +and above." + :type '(repeat string) + :version "28.1") + (defcustom native-comp-driver-options nil "Options passed verbatim to the native compiler's back-end driver. Note that not all options are meaningful; typically only the options @@ -755,6 +765,8 @@ Returns ELT." :documentation "Default speed for this compilation unit.") (debug native-comp-debug :type number :documentation "Default debug level for this compilation unit.") + (compiler-options native-comp-compiler-options :type list + :documentation "Options for the GCC compiler.") (driver-options native-comp-driver-options :type list :documentation "Options for the GCC driver.") (top-level-forms () :type list @@ -1347,6 +1359,8 @@ clashes." byte-native-qualities) (comp-ctxt-debug comp-ctxt) (alist-get 'native-comp-debug byte-native-qualities) + (comp-ctxt-compiler-options comp-ctxt) (alist-get 'native-comp-compiler-options + byte-native-qualities) (comp-ctxt-driver-options comp-ctxt) (alist-get 'native-comp-driver-options byte-native-qualities) (comp-ctxt-top-level-forms comp-ctxt) @@ -3663,6 +3677,8 @@ Prepare every function for final compilation and drive the C back-end." comp-libgccjit-reproducer ,comp-libgccjit-reproducer comp-ctxt ,comp-ctxt native-comp-eln-load-path ',native-comp-eln-load-path + native-comp-compiler-options + ',native-comp-compiler-options native-comp-driver-options ',native-comp-driver-options load-path ',load-path) @@ -3926,6 +3942,8 @@ display a message." comp-libgccjit-reproducer ,comp-libgccjit-reproducer comp-async-compilation t native-comp-eln-load-path ',native-comp-eln-load-path + native-comp-compiler-options + ',native-comp-compiler-options native-comp-driver-options ',native-comp-driver-options load-path ',load-path diff --git a/lisp/emacs-lisp/copyright.el b/lisp/emacs-lisp/copyright.el index d2e4891acee..9da370a725d 100644 --- a/lisp/emacs-lisp/copyright.el +++ b/lisp/emacs-lisp/copyright.el @@ -120,7 +120,7 @@ When this is `function', only ask when called non-interactively." (re-search-forward regexp bound noerror count))) (defun copyright-start-point () - "Return point-min or point-max, depending on `copyright-at-end-flag'." + "Return `point-min' or `point-max', depending on `copyright-at-end-flag'." (if copyright-at-end-flag (point-max) (point-min))) @@ -135,7 +135,7 @@ When this is `function', only ask when called non-interactively." (defun copyright-find-copyright () "Return non-nil if a copyright header suitable for updating is found. The header must match `copyright-regexp' and `copyright-names-regexp', if set. -This function sets the match-data that `copyright-update-year' uses." +This function sets the match data that `copyright-update-year' uses." (widen) (goto-char (copyright-start-point)) ;; In case the regexp is rejected. This is useful because diff --git a/lisp/emacs-lisp/debug.el b/lisp/emacs-lisp/debug.el index f76ae3fe69f..8da9fb76821 100644 --- a/lisp/emacs-lisp/debug.el +++ b/lisp/emacs-lisp/debug.el @@ -390,7 +390,7 @@ Include the reason for debugger entry from ARGS." (`(set ,buffer) (format "setting %s in buffer %s to %s" symbol buffer (backtrace-print-to-string newval))) - (_ (error "unrecognized watchpoint triggered %S" (cdr args)))) + (_ (error "Unrecognized watchpoint triggered %S" (cdr args)))) ": ") (insert ?\n)) ;; Debugger entered for an error. diff --git a/lisp/emacs-lisp/disass.el b/lisp/emacs-lisp/disass.el index 712fa511707..6c019e7387c 100644 --- a/lisp/emacs-lisp/disass.el +++ b/lisp/emacs-lisp/disass.el @@ -114,7 +114,7 @@ redefine OBJECT if it is a symbol." (if (eq (car-safe obj) 'byte-code) (setq obj `(lambda () ,obj))) (when (consp obj) - (unless (functionp obj) (error "not a function")) + (unless (functionp obj) (error "Not a function")) (if (assq 'byte-code obj) nil (if interactive-p (message (if name @@ -183,7 +183,7 @@ redefine OBJECT if it is a symbol." (defun disassemble-1 (obj indent) - "Prints the byte-code call OBJ in the current buffer. + "Print the byte-code call OBJ in the current buffer. OBJ should be a call to BYTE-CODE generated by the byte compiler." (let (bytes constvec) (if (consp obj) diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el index d9b5ea74f6e..dfbae746cc1 100644 --- a/lisp/emacs-lisp/easy-mmode.el +++ b/lisp/emacs-lisp/easy-mmode.el @@ -32,7 +32,7 @@ ;; natural for the minor-mode end-users. ;; For each mode, easy-mmode defines the following: -;; <mode> : The minor mode predicate. A buffer-local variable. +;; <mode> : The minor mode predicate. A buffer-local variable. ;; <mode>-map : The keymap possibly associated to <mode>. ;; see `define-minor-mode' documentation ;; @@ -182,7 +182,7 @@ BODY contains code to execute each time the mode is enabled or disabled. be assigned to PLACE. If you specify a :variable, this function does not define a MODE variable (nor any of the terms used in :variable). -:after-hook A single lisp form which is evaluated after the mode hooks +:after-hook A single Lisp form which is evaluated after the mode hooks have been run. It should not be quoted. For example, you could write diff --git a/lisp/emacs-lisp/eieio-custom.el b/lisp/emacs-lisp/eieio-custom.el index d7d078b2d94..4813ce8c33f 100644 --- a/lisp/emacs-lisp/eieio-custom.el +++ b/lisp/emacs-lisp/eieio-custom.el @@ -333,7 +333,7 @@ Optional argument GROUP is the sub-group of slots to display." (let ((map (make-sparse-keymap))) (set-keymap-parent map widget-keymap) map) - "Keymap for EIEIO Custom mode") + "Keymap for EIEIO Custom mode.") (define-derived-mode eieio-custom-mode fundamental-mode "EIEIO Custom" "Major mode for customizing EIEIO objects. diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el index cec89cf3bc5..21f262adc6e 100644 --- a/lisp/emacs-lisp/eldoc.el +++ b/lisp/emacs-lisp/eldoc.el @@ -437,7 +437,7 @@ return any documentation.") (defvar eldoc-display-functions '(eldoc-display-in-echo-area eldoc-display-in-buffer) "Hook of functions tasked with displaying ElDoc results. -Each function is passed two arguments: DOCS and INTERACTIVE. DOCS +Each function is passed two arguments: DOCS and INTERACTIVE. DOCS is a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2 VALUE2 ...). STRING is a string containing the documentation's text and the remainder of DOC is an optional list of diff --git a/lisp/emacs-lisp/elp.el b/lisp/emacs-lisp/elp.el index c2b026dc822..8c33b7c9948 100644 --- a/lisp/emacs-lisp/elp.el +++ b/lisp/emacs-lisp/elp.el @@ -407,11 +407,11 @@ original definition, use \\[elp-restore-function] or \\[elp-restore-all]." (>= (aref vec1 0) (aref vec2 0))) (defun elp-sort-by-total-time (vec1 vec2) - "Predicate to sort by highest total time spent in function. See `sort'." + "Predicate to sort by highest total time spent in function. See `sort'." (>= (aref vec1 1) (aref vec2 1))) (defun elp-sort-by-average-time (vec1 vec2) - "Predicate to sort by highest average time spent in function. See `sort'." + "Predicate to sort by highest average time spent in function. See `sort'." (>= (aref vec1 2) (aref vec2 2))) (defsubst elp-pack-number (number width) diff --git a/lisp/emacs-lisp/ewoc.el b/lisp/emacs-lisp/ewoc.el index d3ace97945f..ca29b6d8c9b 100644 --- a/lisp/emacs-lisp/ewoc.el +++ b/lisp/emacs-lisp/ewoc.el @@ -55,7 +55,7 @@ ;; ;; Ewoc can be considered as the `view' part of a model-view-controller. ;; -;; A `element' can be any lisp object. When you use the ewoc +;; An `element' can be any Lisp object. When you use the ewoc ;; package you specify a pretty-printer, a function that inserts ;; a printable representation of the element in the buffer. (The ;; pretty-printer should use "insert" and not @@ -67,7 +67,7 @@ ;; fixed when the ewoc is created). The header and the footer ;; are constant strings. They appear before and after the elements. ;; -;; Ewoc does not affect the mode of the buffer in any way. It +;; Ewoc does not affect the mode of the buffer in any way. It ;; merely makes it easy to connect an underlying data representation ;; to the buffer contents. ;; @@ -117,7 +117,7 @@ (unless (eq dll L) L))) (defun ewoc--node-nth (dll n) - "Return the Nth node from the doubly linked list `dll'. + "Return the Nth node from the doubly linked list DLL. N counts from zero. If N is negative, return the -(N+1)th last element. If N is out of range, return nil. Thus, (ewoc--node-nth dll 0) returns the first node, diff --git a/lisp/emacs-lisp/find-func.el b/lisp/emacs-lisp/find-func.el index 7bc3e6b25ff..303039d6534 100644 --- a/lisp/emacs-lisp/find-func.el +++ b/lisp/emacs-lisp/find-func.el @@ -145,13 +145,16 @@ in which case the function is called with one argument (the object we're looking for) and it should search for it.") (put 'find-function-regexp-alist 'risky-local-variable t) -(defcustom find-function-source-path nil - "The default list of directories where `find-function' searches. +(define-obsolete-variable-alias 'find-function-source-path + 'find-library-source-path "28.1") +(defcustom find-library-source-path nil + "The default list of directories where `find-library' searches. -If this variable is nil then `find-function' searches `load-path' by +If this variable is nil then `find-library' searches `load-path' by default." :type '(repeat directory) - :group 'find-function) + :group 'find-function + :version "28.1") (defcustom find-function-recenter-line 1 "The window line-number from which to start displaying a symbol definition. @@ -200,20 +203,20 @@ LIBRARY should be a string (the name of the library)." (setq library (gethash (file-name-nondirectory library) comp-eln-to-el-h)))) (or (locate-file library - (or find-function-source-path load-path) + (or find-library-source-path load-path) (find-library-suffixes)) (locate-file library - (or find-function-source-path load-path) + (or find-library-source-path load-path) load-file-rep-suffixes) (when (file-name-absolute-p library) (let ((rel (find-library--load-name library))) (when rel (or (locate-file rel - (or find-function-source-path load-path) + (or find-library-source-path load-path) (find-library-suffixes)) (locate-file rel - (or find-function-source-path load-path) + (or find-library-source-path load-path) load-file-rep-suffixes))))) (find-library--from-load-history library) (signal 'file-error (list "Can't find library" library)))) @@ -286,7 +289,10 @@ TYPE should be nil to find a function, or `defvar' to find a variable." (defun find-library (library) "Find the Emacs Lisp source of LIBRARY. -Interactively, prompt for LIBRARY using the one at or near point." +Interactively, prompt for LIBRARY using the one at or near point. + +This function searches `find-library-source-path' if non-nil, and +`load-path' otherwise." (interactive (list (read-library-name))) (prog1 (switch-to-buffer (find-file-noselect (find-library-name library))) @@ -297,9 +303,9 @@ Interactively, prompt for LIBRARY using the one at or near point." "Read and return a library name, defaulting to the one near point. A library name is the filename of an Emacs Lisp library located -in a directory under `load-path' (or `find-function-source-path', +in a directory under `load-path' (or `find-library-source-path', if non-nil)." - (let* ((dirs (or find-function-source-path load-path)) + (let* ((dirs (or find-library-source-path load-path)) (suffixes (find-library-suffixes)) (table (apply-partially 'locate-file-completion-table dirs suffixes)) @@ -521,11 +527,7 @@ the buffer, returns (BUFFER). If FUNCTION is a built-in function, this function normally attempts to find it in the Emacs C sources; however, if LISP-ONLY -is non-nil, signal an error instead. - -If the file where FUNCTION is defined is not known, then it is -searched for in `find-function-source-path' if non-nil, otherwise -in `load-path'." +is non-nil, signal an error instead." (if (not function) (error "You didn't specify a function")) (let ((func-lib (find-function-library function lisp-only t))) @@ -589,8 +591,6 @@ near point (selected by `function-called-at-point') in a buffer and places point before the definition. Set mark before moving, if the buffer already existed. -The library where FUNCTION is defined is searched for in -`find-function-source-path', if non-nil, otherwise in `load-path'. See also `find-function-recenter-line' and `find-function-after-hook'." (interactive (find-function-read)) (find-function-do-it function nil 'switch-to-buffer)) @@ -617,10 +617,7 @@ See `find-function' for more details." Finds the library containing the definition of VARIABLE in a buffer and the point of the definition. The buffer is not selected. -If the variable's definition can't be found in the buffer, return (BUFFER). - -The library where VARIABLE is defined is searched for in FILE or -`find-function-source-path', if non-nil, otherwise in `load-path'." +If the variable's definition can't be found in the buffer, return (BUFFER)." (if (not variable) (error "You didn't specify a variable") (let ((library (or file @@ -638,8 +635,6 @@ places point before the definition. Set mark before moving, if the buffer already existed. -The library where VARIABLE is defined is searched for in -`find-function-source-path', if non-nil, otherwise in `load-path'. See also `find-function-recenter-line' and `find-function-after-hook'." (interactive (find-function-read 'defvar)) (find-function-do-it variable 'defvar 'switch-to-buffer)) @@ -666,10 +661,7 @@ See `find-variable' for more details." If the definition can't be found in the buffer, return (BUFFER). TYPE says what type of definition: nil for a function, `defvar' for a variable, `defface' for a face. This function does not switch to the -buffer nor display it. - -The library where SYMBOL is defined is searched for in FILE or -`find-function-source-path', if non-nil, otherwise in `load-path'." +buffer nor display it." (cond ((not symbol) (error "You didn't specify a symbol")) @@ -693,8 +685,6 @@ places point before the definition. Set mark before moving, if the buffer already existed. -The library where FACE is defined is searched for in -`find-function-source-path', if non-nil, otherwise in `load-path'. See also `find-function-recenter-line' and `find-function-after-hook'." (interactive (find-function-read 'defface)) (find-function-do-it face 'defface 'switch-to-buffer)) @@ -765,7 +755,7 @@ See `find-function-on-key'." ;;;###autoload (defun find-function-setup-keys () - "Define some key bindings for the find-function family of functions." + "Define some key bindings for the `find-function' family of functions." (define-key ctl-x-map "F" 'find-function) (define-key ctl-x-4-map "F" 'find-function-other-window) (define-key ctl-x-5-map "F" 'find-function-other-frame) diff --git a/lisp/emacs-lisp/generator.el b/lisp/emacs-lisp/generator.el index 4ae20ba4205..2acf939bed7 100644 --- a/lisp/emacs-lisp/generator.el +++ b/lisp/emacs-lisp/generator.el @@ -467,7 +467,7 @@ DYNAMIC-VAR bound to STATIC-VAR." (guard (cps--special-form-p name)) (guard (not (memq name cps-standard-special-forms)))) name ; Shut up byte compiler - (error "special form %S incorrect or not supported" form)) + (error "Special form %S incorrect or not supported" form)) ;; Process regular function applications with nontrivial ;; parameters, converting them to applications of trivial @@ -633,7 +633,7 @@ modified copy." ;; If we're exiting non-locally (error, quit, ;; etc.) close the iterator. ,(cps--make-close-iterator-form terminal-state))))) - (t (error "unknown iterator operation %S" op)))))) + (t (error "Unknown iterator operation %S" op)))))) ,(when finalizer-symbol '(funcall iterator :stash-finalizer @@ -711,7 +711,7 @@ iterator cannot supply more values." (defun iter-close (iterator) "Terminate an iterator early. -Run any unwind-protect handlers in scope at the point ITERATOR +Run any `unwind-protect' handlers in scope at the point ITERATOR is blocked." (funcall iterator :close nil)) diff --git a/lisp/emacs-lisp/let-alist.el b/lisp/emacs-lisp/let-alist.el index 433b37d7923..2d634b7b037 100644 --- a/lisp/emacs-lisp/let-alist.el +++ b/lisp/emacs-lisp/let-alist.el @@ -57,7 +57,7 @@ ;; .site.contents)) ;; ;; If you nest `let-alist' invocations, the inner one can't access -;; the variables of the outer one. You can, however, access alists +;; the variables of the outer one. You can, however, access alists ;; inside the original alist by using dots inside the symbol, as ;; displayed in the example above by the `.site.contents'. ;; @@ -137,7 +137,7 @@ essentially expands to .site.contents)) If you nest `let-alist' invocations, the inner one can't access -the variables of the outer one. You can, however, access alists +the variables of the outer one. You can, however, access alists inside the original alist by using dots inside the symbol, as displayed in the example above." (declare (indent 1) (debug t)) diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el index 51fb88502ab..42e943a60df 100644 --- a/lisp/emacs-lisp/lisp-mode.el +++ b/lisp/emacs-lisp/lisp-mode.el @@ -624,7 +624,7 @@ Value for `adaptive-fill-function'." (if (looking-at "\\s-+\"[^\n\"]+\"\\s-*$") "")) ;; Maybe this should be discouraged/obsoleted and users should be -;; encouraged to use `lisp-data-mode` instead. +;; encouraged to use 'lisp-data-mode' instead. (defun lisp-mode-variables (&optional lisp-syntax keywords-case-insensitive elisp) "Common initialization routine for lisp modes. @@ -824,7 +824,7 @@ function is `common-lisp-indent-function'." "Return Parse-Partial-Sexp State at POS, defaulting to point. Like `syntax-ppss' but includes the character address of the last complete sexp in the innermost containing list at position -2 (counting from 0). This is important for lisp indentation." +2 (counting from 0). This is important for Lisp indentation." (unless pos (setq pos (point))) (let ((pss (syntax-ppss pos))) (if (nth 9 pss) diff --git a/lisp/emacs-lisp/macroexp.el b/lisp/emacs-lisp/macroexp.el index 61c1ea490f0..1e4fdd126cb 100644 --- a/lisp/emacs-lisp/macroexp.el +++ b/lisp/emacs-lisp/macroexp.el @@ -243,19 +243,19 @@ is executed without being compiled first." (while arglist (cond ((eq (car arglist) '&optional) ;; ok, I'll let this slide because funcall_lambda() does... - ;; (if optionalp (error "multiple &optional keywords in %s" name)) + ;; (if optionalp (error "Multiple &optional keywords in %s" name)) (if restp (error "&optional found after &rest in %s" name)) (if (null (cdr arglist)) - (error "nothing after &optional in %s" name)) + (error "Nothing after &optional in %s" name)) (setq optionalp t)) ((eq (car arglist) '&rest) ;; ...but it is by no stretch of the imagination a reasonable ;; thing that funcall_lambda() allows (&rest x y) and ;; (&rest x &optional y) in arglists. (if (null (cdr arglist)) - (error "nothing after &rest in %s" name)) + (error "Nothing after &rest in %s" name)) (if (cdr (cdr arglist)) - (error "multiple vars after &rest in %s" name)) + (error "Multiple vars after &rest in %s" name)) (setq restp t)) (restp (setq bindings (cons (list (car arglist) diff --git a/lisp/emacs-lisp/nadvice.el b/lisp/emacs-lisp/nadvice.el index 41a9c7242b3..a2a5aaed046 100644 --- a/lisp/emacs-lisp/nadvice.el +++ b/lisp/emacs-lisp/nadvice.el @@ -245,7 +245,7 @@ WHERE is a symbol to select an entry in `advice--where-alist'." (list (advice--remove-function rest function))))))) (defvar advice--buffer-local-function-sample nil - "keeps an example of the special \"run the default value\" functions. + "Keeps an example of the special \"run the default value\" functions. These functions play the same role as t in buffer-local hooks, and to recognize them, we keep a sample here against which to compare. Each instance is different, but `function-equal' will hopefully ignore those differences.") diff --git a/lisp/emacs-lisp/package-x.el b/lisp/emacs-lisp/package-x.el index 2e327d16de4..0175857b7f5 100644 --- a/lisp/emacs-lisp/package-x.el +++ b/lisp/emacs-lisp/package-x.el @@ -34,7 +34,7 @@ ;; (possibly one on a remote machine, accessed via Tramp). ;; Then call M-x package-upload-file, which prompts for a file to -;; upload. Alternatively, M-x package-upload-buffer uploads the +;; upload. Alternatively, M-x package-upload-buffer uploads the ;; current buffer, if it's visiting a package file. ;; Once a package is uploaded, users can access it via the Package diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el index 617e941dba5..c6cb8f058bc 100644 --- a/lisp/emacs-lisp/package.el +++ b/lisp/emacs-lisp/package.el @@ -3601,8 +3601,10 @@ packages list, respectively." (defun package-menu-execute (&optional noquery) "Perform marked Package Menu actions. -Packages marked for installation are downloaded and installed; -packages marked for deletion are removed. +Packages marked for installation are downloaded and installed, +packages marked for deletion are removed, +and packages marked for upgrading are downloaded and upgraded. + Optional argument NOQUERY non-nil means do not ask the user to confirm." (interactive nil package-menu-mode) (package--ensure-package-menu-mode) diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el index 63b187be02b..c6173c710f7 100644 --- a/lisp/emacs-lisp/pcase.el +++ b/lisp/emacs-lisp/pcase.el @@ -86,7 +86,7 @@ (funcall pf (and me (symbolp me) (edebug-get-spec me)))))) (defun pcase--get-macroexpander (s) - "Return the macroexpander for pcase pattern head S, or nil" + "Return the macroexpander for pcase pattern head S, or nil." (get s 'pcase-macroexpander)) ;;;###autoload diff --git a/lisp/emacs-lisp/shadow.el b/lisp/emacs-lisp/shadow.el index 02f2ad3d816..e2a24e9949c 100644 --- a/lisp/emacs-lisp/shadow.el +++ b/lisp/emacs-lisp/shadow.el @@ -31,13 +31,13 @@ ;; a file with the same name in a later load-path directory. When ;; this is unintentional, it may result in problems that could have ;; been easily avoided. This occurs often (to me) when installing a -;; new version of emacs and something in the site-lisp directory -;; has been updated and added to the emacs distribution. The old -;; version, now outdated, shadows the new one. This is obviously +;; new version of Emacs and something in the site-lisp directory +;; has been updated and added to the Emacs distribution. The old +;; version, now outdated, shadows the new one. This is obviously ;; undesirable. ;; ;; The `list-load-path-shadows' function was run when you installed -;; this version of emacs. To run it by hand in emacs: +;; this version of Emacs. To run it by hand in emacs: ;; ;; M-x list-load-path-shadows ;; @@ -181,7 +181,7 @@ See the documentation for `list-load-path-shadows' for further information." "Keywords to highlight in `load-path-shadows-mode'.") (define-derived-mode load-path-shadows-mode fundamental-mode "LP-Shadows" - "Major mode for load-path shadows buffer." + "Major mode for `load-path' shadows buffer." (setq-local font-lock-defaults '((load-path-shadows-font-lock-keywords))) (setq buffer-undo-list t diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index 7d4a69f42a9..adee6be379d 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -889,6 +889,9 @@ There can be any number of :example/:result elements." :eg-result 67) (char-after :eval (char-after 45)) + (get-byte + :no-eval (get-byte 45) + :eg-result-string "#xff") "Altering Buffers" (delete-region :no-value (delete-region (point-min) (point-max))) diff --git a/lisp/emacs-lisp/testcover.el b/lisp/emacs-lisp/testcover.el index e75f15140aa..f5a624bb61b 100644 --- a/lisp/emacs-lisp/testcover.el +++ b/lisp/emacs-lisp/testcover.el @@ -20,7 +20,6 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. - ;;; Commentary: ;; * Use `testcover-start' to instrument a Lisp file for coverage testing. @@ -62,6 +61,8 @@ ;; error if these "potentially" 1-valued forms actually return differing ;; values. +;;; Code: + (eval-when-compile (require 'cl-lib)) (require 'edebug) (provide 'testcover) @@ -80,8 +81,9 @@ (defcustom testcover-constants '(nil t emacs-build-time emacs-version emacs-major-version emacs-minor-version) - "Variables whose values never change. No brown splotch is shown for -these. This list is quite incomplete!" + "Variables whose values never change. +No brown splotch is shown for these. This list is quite +incomplete!" :group 'testcover :type '(repeat variable)) @@ -103,8 +105,8 @@ incomplete! Notes: Nobody ever changes the current global map." (defcustom testcover-noreturn-functions '(error noreturn throw signal) - "Subset of `testcover-1value-functions' -- these never return. We mark -them as having returned nil just before calling them." + "Subset of `testcover-1value-functions' -- these never return. +We mark them as having returned nil just before calling them." :group 'testcover :type '(repeat symbol)) @@ -126,25 +128,26 @@ side-effect-free functions should be here." set set-default set-marker-insertion-type setq setq-default with-current-buffer with-output-to-temp-buffer with-syntax-table with-temp-buffer with-temp-file with-temp-message with-timeout) - "Functions whose return value is the same as their last argument. No -brown splotch is shown for these if the last argument is a constant or a -call to one of the `testcover-1value-functions'. This list is probably -incomplete!" + "Functions whose return value is the same as their last argument. +No brown splotch is shown for these if the last argument is a +constant or a call to one of the `testcover-1value-functions'. +This list is probably incomplete!" :group 'testcover :type '(repeat symbol)) (defcustom testcover-prog1-functions '(prog1 unwind-protect) - "Functions whose return value is the same as their first argument. No -brown splotch is shown for these if the first argument is a constant or a -call to one of the `testcover-1value-functions'." + "Functions whose return value is the same as their first argument. +No brown splotch is shown for these if the first argument is a +constant or a call to one of the `testcover-1value-functions'." :group 'testcover :type '(repeat symbol)) (defcustom testcover-potentially-1value-functions '(add-hook and beep or remove-hook unless when) - "Functions that are potentially 1-valued. No brown splotch if actually -1-valued, no error if actually multi-valued." + "Functions that are potentially 1-valued. +No brown splotch if actually 1-valued, no error if actually +multi-valued." :group 'testcover :type '(repeat symbol)) @@ -164,8 +167,7 @@ call to one of the `testcover-1value-functions'." ;;;========================================================================= (defvar testcover-module-constants nil - "Symbols declared with defconst in the last file processed by -`testcover-start'.") + "Symbols declared with defconst in the last file processed by `testcover-start'.") (defvar testcover-module-1value-functions nil "Symbols declared with defun in the last file processed by @@ -388,7 +390,7 @@ coverage tests. This function creates many overlays." (error nil))) ;Ignore "No such buffer" errors (defun testcover-next-mark () - "Moves point to next line in current buffer that has a splotch." + "Move point to next line in current buffer that has a splotch." (interactive) (goto-char (next-overlay-change (point))) (end-of-line)) diff --git a/lisp/emacs-lisp/thunk.el b/lisp/emacs-lisp/thunk.el index 7e349d22a49..6f2e42af50b 100644 --- a/lisp/emacs-lisp/thunk.el +++ b/lisp/emacs-lisp/thunk.el @@ -30,7 +30,7 @@ ;; forms. ;; ;; Use `thunk-delay' to delay the evaluation of a form (requires -;; lexical-binding), and `thunk-force' to evaluate it. The result of +;; lexical-binding), and `thunk-force' to evaluate it. The result of ;; the evaluation is cached, and only happens once. ;; ;; Here is an example of a form which evaluation is delayed: |