| 1 | ;;; byte-run.el --- byte-compiler support for inlining -*- lexical-binding: t -*- |
| 2 | |
| 3 | ;; Copyright (C) 1992, 2001-2012 Free Software Foundation, Inc. |
| 4 | |
| 5 | ;; Author: Jamie Zawinski <jwz@lucid.com> |
| 6 | ;; Hallvard Furuseth <hbf@ulrik.uio.no> |
| 7 | ;; Maintainer: FSF |
| 8 | ;; Keywords: internal |
| 9 | ;; Package: emacs |
| 10 | |
| 11 | ;; This file is part of GNU Emacs. |
| 12 | |
| 13 | ;; GNU Emacs is free software: you can redistribute it and/or modify |
| 14 | ;; it under the terms of the GNU General Public License as published by |
| 15 | ;; the Free Software Foundation, either version 3 of the License, or |
| 16 | ;; (at your option) any later version. |
| 17 | |
| 18 | ;; GNU Emacs is distributed in the hope that it will be useful, |
| 19 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 20 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 21 | ;; GNU General Public License for more details. |
| 22 | |
| 23 | ;; You should have received a copy of the GNU General Public License |
| 24 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
| 25 | |
| 26 | ;;; Commentary: |
| 27 | |
| 28 | ;; interface to selectively inlining functions. |
| 29 | ;; This only happens when source-code optimization is turned on. |
| 30 | |
| 31 | ;;; Code: |
| 32 | |
| 33 | ;; `macro-declaration-function' are both obsolete (as marked at the end of this |
| 34 | ;; file) but used in many .elc files. |
| 35 | |
| 36 | (defvar macro-declaration-function #'macro-declaration-function |
| 37 | "Function to process declarations in a macro definition. |
| 38 | The function will be called with two args MACRO and DECL. |
| 39 | MACRO is the name of the macro being defined. |
| 40 | DECL is a list `(declare ...)' containing the declarations. |
| 41 | The value the function returns is not used.") |
| 42 | |
| 43 | (defalias 'macro-declaration-function |
| 44 | #'(lambda (macro decl) |
| 45 | "Process a declaration found in a macro definition. |
| 46 | This is set as the value of the variable `macro-declaration-function'. |
| 47 | MACRO is the name of the macro being defined. |
| 48 | DECL is a list `(declare ...)' containing the declarations. |
| 49 | The return value of this function is not used." |
| 50 | ;; We can't use `dolist' or `cadr' yet for bootstrapping reasons. |
| 51 | (let (d) |
| 52 | ;; Ignore the first element of `decl' (it's always `declare'). |
| 53 | (while (setq decl (cdr decl)) |
| 54 | (setq d (car decl)) |
| 55 | (if (and (consp d) |
| 56 | (listp (cdr d)) |
| 57 | (null (cdr (cdr d)))) |
| 58 | (cond ((eq (car d) 'indent) |
| 59 | (put macro 'lisp-indent-function (car (cdr d)))) |
| 60 | ((eq (car d) 'debug) |
| 61 | (put macro 'edebug-form-spec (car (cdr d)))) |
| 62 | ((eq (car d) 'doc-string) |
| 63 | (put macro 'doc-string-elt (car (cdr d)))) |
| 64 | (t |
| 65 | (message "Unknown declaration %s" d))) |
| 66 | (message "Invalid declaration %s" d)))))) |
| 67 | |
| 68 | ;; We define macro-declaration-alist here because it is needed to |
| 69 | ;; handle declarations in macro definitions and this is the first file |
| 70 | ;; loaded by loadup.el that uses declarations in macros. |
| 71 | |
| 72 | (defvar defun-declarations-alist |
| 73 | ;; FIXME: Should we also add an `obsolete' property? |
| 74 | (list |
| 75 | ;; Too bad we can't use backquote yet at this stage of the bootstrap. |
| 76 | (list 'advertised-calling-convention |
| 77 | #'(lambda (f arglist when) |
| 78 | (list 'set-advertised-calling-convention |
| 79 | (list 'quote f) (list 'quote arglist) (list 'quote when)))) |
| 80 | (list 'doc-string |
| 81 | #'(lambda (f pos) |
| 82 | (list 'put (list 'quote f) ''doc-string-elt (list 'quote pos)))) |
| 83 | (list 'indent |
| 84 | #'(lambda (f val) |
| 85 | (list 'put (list 'quote f) |
| 86 | ''lisp-indent-function (list 'quote val))))) |
| 87 | "List associating function properties to their macro expansion. |
| 88 | Each element of the list takes the form (PROP FUN) where FUN is |
| 89 | a function. For each (PROP . VALUES) in a function's declaration, |
| 90 | the FUN corresponding to PROP is called with the function name |
| 91 | and the VALUES and should return the code to use to set this property.") |
| 92 | |
| 93 | (defvar macro-declarations-alist |
| 94 | (cons |
| 95 | (list 'debug |
| 96 | #'(lambda (name spec) |
| 97 | (list 'progn :autoload-end |
| 98 | (list 'put (list 'quote name) |
| 99 | ''edebug-form-spec (list 'quote spec))))) |
| 100 | defun-declarations-alist) |
| 101 | "List associating properties of macros to their macro expansion. |
| 102 | Each element of the list takes the form (PROP FUN) where FUN is |
| 103 | a function. For each (PROP . VALUES) in a macro's declaration, |
| 104 | the FUN corresponding to PROP is called with the function name |
| 105 | and the VALUES and should return the code to use to set this property.") |
| 106 | |
| 107 | (put 'defmacro 'doc-string-elt 3) |
| 108 | (defalias 'defmacro |
| 109 | (cons |
| 110 | 'macro |
| 111 | #'(lambda (name arglist &optional docstring decl &rest body) |
| 112 | "Define NAME as a macro. |
| 113 | When the macro is called, as in (NAME ARGS...), |
| 114 | the function (lambda ARGLIST BODY...) is applied to |
| 115 | the list ARGS... as it appears in the expression, |
| 116 | and the result should be a form to be evaluated instead of the original. |
| 117 | DECL is a declaration, optional, of the form (declare DECLS...) where |
| 118 | DECLS is a list of elements of the form (PROP . VALUES). These are |
| 119 | interpreted according to `macro-declarations-alist'." |
| 120 | (if (stringp docstring) nil |
| 121 | (if decl (setq body (cons decl body))) |
| 122 | (setq decl docstring) |
| 123 | (setq docstring nil)) |
| 124 | (if (or (null decl) (eq 'declare (car-safe decl))) nil |
| 125 | (setq body (cons decl body)) |
| 126 | (setq decl nil)) |
| 127 | (if (null body) (setq body '(nil))) |
| 128 | (if docstring (setq body (cons docstring body))) |
| 129 | ;; Can't use backquote because it's not defined yet! |
| 130 | (let* ((fun (list 'function (cons 'lambda (cons arglist body)))) |
| 131 | (def (list 'defalias |
| 132 | (list 'quote name) |
| 133 | (list 'cons ''macro fun))) |
| 134 | (declarations |
| 135 | (mapcar |
| 136 | #'(lambda (x) |
| 137 | (let ((f (cdr (assq (car x) macro-declarations-alist)))) |
| 138 | (if f (apply (car f) name (cdr x)) |
| 139 | (message "Warning: Unknown macro property %S in %S" |
| 140 | (car x) name)))) |
| 141 | (cdr decl)))) |
| 142 | (if declarations |
| 143 | (cons 'prog1 (cons def declarations)) |
| 144 | def))))) |
| 145 | |
| 146 | ;; Now that we defined defmacro we can use it! |
| 147 | (defmacro defun (name arglist &optional docstring &rest body) |
| 148 | "Define NAME as a function. |
| 149 | The definition is (lambda ARGLIST [DOCSTRING] BODY...). |
| 150 | See also the function `interactive'. |
| 151 | DECL is a declaration, optional, of the form (declare DECLS...) where |
| 152 | DECLS is a list of elements of the form (PROP . VALUES). These are |
| 153 | interpreted according to `defun-declarations-alist'. |
| 154 | |
| 155 | \(fn NAME ARGLIST &optional DOCSTRING DECL &rest BODY)" |
| 156 | ;; We can't just have `decl' as an &optional argument, because we need |
| 157 | ;; to distinguish |
| 158 | ;; (defun foo (arg) (toto) nil) |
| 159 | ;; from |
| 160 | ;; (defun foo (arg) (toto)). |
| 161 | (declare (doc-string 3)) |
| 162 | (let ((decls (cond |
| 163 | ((eq (car-safe docstring) 'declare) |
| 164 | (prog1 (cdr docstring) (setq docstring nil))) |
| 165 | ((eq (car-safe (car body)) 'declare) |
| 166 | (prog1 (cdr (car body)) (setq body (cdr body))))))) |
| 167 | (if docstring (setq body (cons docstring body)) |
| 168 | (if (null body) (setq body '(nil)))) |
| 169 | (let ((declarations |
| 170 | (mapcar |
| 171 | #'(lambda (x) |
| 172 | (let ((f (cdr (assq (car x) defun-declarations-alist)))) |
| 173 | (cond |
| 174 | (f (apply (car f) name (cdr x))) |
| 175 | ;; Yuck!! |
| 176 | ((and (featurep 'cl) |
| 177 | (memq (car x) ;C.f. cl-do-proclaim. |
| 178 | '(special inline notinline optimize warn))) |
| 179 | (if (null (stringp docstring)) |
| 180 | (push (list 'declare x) body) |
| 181 | (setcdr body (cons (list 'declare x) (cdr body)))) |
| 182 | nil) |
| 183 | (t (message "Warning: Unknown defun property %S in %S" |
| 184 | (car x) name))))) |
| 185 | decls)) |
| 186 | (def (list 'defalias |
| 187 | (list 'quote name) |
| 188 | (list 'function |
| 189 | (cons 'lambda |
| 190 | (cons arglist body)))))) |
| 191 | (if declarations |
| 192 | (cons 'prog1 (cons def declarations)) |
| 193 | def)))) |
| 194 | \f |
| 195 | ;; Redefined in byte-optimize.el. |
| 196 | ;; This is not documented--it's not clear that we should promote it. |
| 197 | (fset 'inline 'progn) |
| 198 | |
| 199 | ;;; Interface to inline functions. |
| 200 | |
| 201 | ;; (defmacro proclaim-inline (&rest fns) |
| 202 | ;; "Cause the named functions to be open-coded when called from compiled code. |
| 203 | ;; They will only be compiled open-coded when byte-compile-optimize is true." |
| 204 | ;; (cons 'eval-and-compile |
| 205 | ;; (mapcar (lambda (x) |
| 206 | ;; (or (memq (get x 'byte-optimizer) |
| 207 | ;; '(nil byte-compile-inline-expand)) |
| 208 | ;; (error |
| 209 | ;; "%s already has a byte-optimizer, can't make it inline" |
| 210 | ;; x)) |
| 211 | ;; (list 'put (list 'quote x) |
| 212 | ;; ''byte-optimizer ''byte-compile-inline-expand)) |
| 213 | ;; fns))) |
| 214 | |
| 215 | ;; (defmacro proclaim-notinline (&rest fns) |
| 216 | ;; "Cause the named functions to no longer be open-coded." |
| 217 | ;; (cons 'eval-and-compile |
| 218 | ;; (mapcar (lambda (x) |
| 219 | ;; (if (eq (get x 'byte-optimizer) 'byte-compile-inline-expand) |
| 220 | ;; (put x 'byte-optimizer nil)) |
| 221 | ;; (list 'if (list 'eq (list 'get (list 'quote x) ''byte-optimizer) |
| 222 | ;; ''byte-compile-inline-expand) |
| 223 | ;; (list 'put x ''byte-optimizer nil))) |
| 224 | ;; fns))) |
| 225 | |
| 226 | (defmacro defsubst (name arglist &rest body) |
| 227 | "Define an inline function. The syntax is just like that of `defun'." |
| 228 | (declare (debug defun) (doc-string 3)) |
| 229 | (or (memq (get name 'byte-optimizer) |
| 230 | '(nil byte-compile-inline-expand)) |
| 231 | (error "`%s' is a primitive" name)) |
| 232 | `(prog1 |
| 233 | (defun ,name ,arglist ,@body) |
| 234 | (eval-and-compile |
| 235 | (put ',name 'byte-optimizer 'byte-compile-inline-expand)))) |
| 236 | |
| 237 | (defvar advertised-signature-table (make-hash-table :test 'eq :weakness 'key)) |
| 238 | |
| 239 | (defun set-advertised-calling-convention (function signature _when) |
| 240 | "Set the advertised SIGNATURE of FUNCTION. |
| 241 | This will allow the byte-compiler to warn the programmer when she uses |
| 242 | an obsolete calling convention. WHEN specifies since when the calling |
| 243 | convention was modified." |
| 244 | (puthash (indirect-function function) signature |
| 245 | advertised-signature-table)) |
| 246 | |
| 247 | (defun make-obsolete (obsolete-name current-name &optional when) |
| 248 | "Make the byte-compiler warn that OBSOLETE-NAME is obsolete. |
| 249 | The warning will say that CURRENT-NAME should be used instead. |
| 250 | If CURRENT-NAME is a string, that is the `use instead' message |
| 251 | \(it should end with a period, and not start with a capital). |
| 252 | WHEN should be a string indicating when the function |
| 253 | was first made obsolete, for example a date or a release number." |
| 254 | (declare (advertised-calling-convention |
| 255 | ;; New code should always provide the `when' argument. |
| 256 | (obsolete-name current-name when) "23.1")) |
| 257 | (interactive "aMake function obsolete: \nxObsoletion replacement: ") |
| 258 | (put obsolete-name 'byte-obsolete-info |
| 259 | ;; The second entry used to hold the `byte-compile' handler, but |
| 260 | ;; is not used any more nowadays. |
| 261 | (purecopy (list current-name nil when))) |
| 262 | obsolete-name) |
| 263 | |
| 264 | (defmacro define-obsolete-function-alias (obsolete-name current-name |
| 265 | &optional when docstring) |
| 266 | "Set OBSOLETE-NAME's function definition to CURRENT-NAME and mark it obsolete. |
| 267 | |
| 268 | \(define-obsolete-function-alias 'old-fun 'new-fun \"22.1\" \"old-fun's doc.\") |
| 269 | |
| 270 | is equivalent to the following two lines of code: |
| 271 | |
| 272 | \(defalias 'old-fun 'new-fun \"old-fun's doc.\") |
| 273 | \(make-obsolete 'old-fun 'new-fun \"22.1\") |
| 274 | |
| 275 | See the docstrings of `defalias' and `make-obsolete' for more details." |
| 276 | (declare (doc-string 4) |
| 277 | (advertised-calling-convention |
| 278 | ;; New code should always provide the `when' argument. |
| 279 | (obsolete-name current-name when &optional docstring) "23.1")) |
| 280 | `(progn |
| 281 | (defalias ,obsolete-name ,current-name ,docstring) |
| 282 | (make-obsolete ,obsolete-name ,current-name ,when))) |
| 283 | |
| 284 | (defun make-obsolete-variable (obsolete-name current-name &optional when access-type) |
| 285 | "Make the byte-compiler warn that OBSOLETE-NAME is obsolete. |
| 286 | The warning will say that CURRENT-NAME should be used instead. |
| 287 | If CURRENT-NAME is a string, that is the `use instead' message. |
| 288 | WHEN should be a string indicating when the variable |
| 289 | was first made obsolete, for example a date or a release number. |
| 290 | ACCESS-TYPE if non-nil should specify the kind of access that will trigger |
| 291 | obsolescence warnings; it can be either `get' or `set'." |
| 292 | (declare (advertised-calling-convention |
| 293 | ;; New code should always provide the `when' argument. |
| 294 | (obsolete-name current-name when &optional access-type) "23.1")) |
| 295 | (put obsolete-name 'byte-obsolete-variable |
| 296 | (purecopy (list current-name access-type when))) |
| 297 | obsolete-name) |
| 298 | |
| 299 | |
| 300 | (defmacro define-obsolete-variable-alias (obsolete-name current-name |
| 301 | &optional when docstring) |
| 302 | "Make OBSOLETE-NAME a variable alias for CURRENT-NAME and mark it obsolete. |
| 303 | This uses `defvaralias' and `make-obsolete-variable' (which see). |
| 304 | See the Info node `(elisp)Variable Aliases' for more details. |
| 305 | |
| 306 | If CURRENT-NAME is a defcustom (more generally, any variable |
| 307 | where OBSOLETE-NAME may be set, e.g. in a .emacs file, before the |
| 308 | alias is defined), then the define-obsolete-variable-alias |
| 309 | statement should be evaluated before the defcustom, if user |
| 310 | customizations are to be respected. The simplest way to achieve |
| 311 | this is to place the alias statement before the defcustom (this |
| 312 | is not necessary for aliases that are autoloaded, or in files |
| 313 | dumped with Emacs). This is so that any user customizations are |
| 314 | applied before the defcustom tries to initialize the |
| 315 | variable (this is due to the way `defvaralias' works). |
| 316 | |
| 317 | For the benefit of `custom-set-variables', if OBSOLETE-NAME has |
| 318 | any of the following properties, they are copied to |
| 319 | CURRENT-NAME, if it does not already have them: |
| 320 | 'saved-value, 'saved-variable-comment." |
| 321 | (declare (doc-string 4) |
| 322 | (advertised-calling-convention |
| 323 | ;; New code should always provide the `when' argument. |
| 324 | (obsolete-name current-name when &optional docstring) "23.1")) |
| 325 | `(progn |
| 326 | (defvaralias ,obsolete-name ,current-name ,docstring) |
| 327 | ;; See Bug#4706. |
| 328 | (dolist (prop '(saved-value saved-variable-comment)) |
| 329 | (and (get ,obsolete-name prop) |
| 330 | (null (get ,current-name prop)) |
| 331 | (put ,current-name prop (get ,obsolete-name prop)))) |
| 332 | (make-obsolete-variable ,obsolete-name ,current-name ,when))) |
| 333 | |
| 334 | ;; FIXME This is only defined in this file because the variable- and |
| 335 | ;; function- versions are too. Unlike those two, this one is not used |
| 336 | ;; by the byte-compiler (would be nice if it could warn about obsolete |
| 337 | ;; faces, but it doesn't really do anything special with faces). |
| 338 | ;; It only really affects M-x describe-face output. |
| 339 | (defmacro define-obsolete-face-alias (obsolete-face current-face when) |
| 340 | "Make OBSOLETE-FACE a face alias for CURRENT-FACE and mark it obsolete. |
| 341 | The string WHEN gives the Emacs version where OBSOLETE-FACE became |
| 342 | obsolete." |
| 343 | `(progn |
| 344 | (put ,obsolete-face 'face-alias ,current-face) |
| 345 | ;; Used by M-x describe-face. |
| 346 | (put ,obsolete-face 'obsolete-face (or (purecopy ,when) t)))) |
| 347 | |
| 348 | (defmacro dont-compile (&rest body) |
| 349 | "Like `progn', but the body always runs interpreted (not compiled). |
| 350 | If you think you need this, you're probably making a mistake somewhere." |
| 351 | (declare (debug t) (indent 0)) |
| 352 | (list 'eval (list 'quote (if (cdr body) (cons 'progn body) (car body))))) |
| 353 | |
| 354 | \f |
| 355 | ;; interface to evaluating things at compile time and/or load time |
| 356 | ;; these macro must come after any uses of them in this file, as their |
| 357 | ;; definition in the file overrides the magic definitions on the |
| 358 | ;; byte-compile-macro-environment. |
| 359 | |
| 360 | (defmacro eval-when-compile (&rest body) |
| 361 | "Like `progn', but evaluates the body at compile time if you're compiling. |
| 362 | Thus, the result of the body appears to the compiler as a quoted constant. |
| 363 | In interpreted code, this is entirely equivalent to `progn'." |
| 364 | (declare (debug t) (indent 0)) |
| 365 | ;; Not necessary because we have it in b-c-initial-macro-environment |
| 366 | ;; (list 'quote (eval (cons 'progn body))) |
| 367 | (cons 'progn body)) |
| 368 | |
| 369 | (defmacro eval-and-compile (&rest body) |
| 370 | "Like `progn', but evaluates the body at compile time and at load time." |
| 371 | (declare (debug t) (indent 0)) |
| 372 | ;; Remember, it's magic. |
| 373 | (cons 'progn body)) |
| 374 | |
| 375 | (put 'with-no-warnings 'lisp-indent-function 0) |
| 376 | (defun with-no-warnings (&rest body) |
| 377 | "Like `progn', but prevents compiler warnings in the body." |
| 378 | ;; The implementation for the interpreter is basically trivial. |
| 379 | (car (last body))) |
| 380 | |
| 381 | \f |
| 382 | ;; I nuked this because it's not a good idea for users to think of using it. |
| 383 | ;; These options are a matter of installation preference, and have nothing to |
| 384 | ;; with particular source files; it's a mistake to suggest to users |
| 385 | ;; they should associate these with particular source files. |
| 386 | ;; There is hardly any reason to change these parameters, anyway. |
| 387 | ;; --rms. |
| 388 | |
| 389 | ;; (put 'byte-compiler-options 'lisp-indent-function 0) |
| 390 | ;; (defmacro byte-compiler-options (&rest args) |
| 391 | ;; "Set some compilation-parameters for this file. This will affect only the |
| 392 | ;; file in which it appears; this does nothing when evaluated, and when loaded |
| 393 | ;; from a .el file. |
| 394 | ;; |
| 395 | ;; Each argument to this macro must be a list of a key and a value. |
| 396 | ;; |
| 397 | ;; Keys: Values: Corresponding variable: |
| 398 | ;; |
| 399 | ;; verbose t, nil byte-compile-verbose |
| 400 | ;; optimize t, nil, source, byte byte-compile-optimize |
| 401 | ;; warnings list of warnings byte-compile-warnings |
| 402 | ;; Valid elements: (callargs redefine free-vars unresolved) |
| 403 | ;; file-format emacs18, emacs19 byte-compile-compatibility |
| 404 | ;; |
| 405 | ;; For example, this might appear at the top of a source file: |
| 406 | ;; |
| 407 | ;; (byte-compiler-options |
| 408 | ;; (optimize t) |
| 409 | ;; (warnings (- free-vars)) ; Don't warn about free variables |
| 410 | ;; (file-format emacs19))" |
| 411 | ;; nil) |
| 412 | |
| 413 | (make-obsolete-variable 'macro-declaration-function |
| 414 | 'macro-declarations-alist "24.2") |
| 415 | (make-obsolete 'macro-declaration-function |
| 416 | 'macro-declarations-alist "24.2") |
| 417 | |
| 418 | ;;; byte-run.el ends here |