lisp/emacs-lisp/cl-specs.el

   1 ;;; cl-specs.el --- Edebug specs for cl.el -*- no-byte-compile: t -*-
   2
   3 ;; Copyright (C) 1993, 2001, 2002, 2003, 2004, 2005,
   4 ;;   2006, 2007 Free Software Foundation, Inc.
   5 ;; Author: Daniel LaLiberte <liberte@holonexus.org>
   6 ;; Keywords: lisp, tools, maint
   7
   8 ;; LCD Archive Entry:
   9 ;; cl-specs.el|Daniel LaLiberte|liberte@holonexus.org
  10 ;; |Edebug specs for cl.el
  11
  12 ;; This file is part of GNU Emacs.
  13
  14 ;; GNU Emacs is free software; you can redistribute it and/or modify
  15 ;; it under the terms of the GNU General Public License as published by
  16 ;; the Free Software Foundation; either version 3, or (at your option)
  17 ;; any later version.
  18
  19 ;; GNU Emacs is distributed in the hope that it will be useful,
  20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22 ;; GNU General Public License for more details.
  23
  24 ;; You should have received a copy of the GNU General Public License
  25 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  26 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  27 ;; Boston, MA 02110-1301, USA.
  28
  29 ;;; Commentary:
  30
  31 ;; These specs are to be used with edebug.el version 3.3 or later and
  32 ;; cl.el version 2.03 or later, by Dave Gillespie <daveg@synaptics.com>.
  33
  34 ;; This file need not be byte-compiled, but it shouldn't hurt.
  35
  36 ;;; Code:
  37
  38 (provide 'cl-specs)
  39 ;; Do the above provide before the following require.
  40 ;; Otherwise if you load this before edebug if cl is already loaded
  41 ;; an infinite loading loop would occur.
  42 (require 'edebug)
  43
  44 ;; Blocks
  45
  46 (def-edebug-spec block (symbolp body))
  47 (def-edebug-spec return (&optional form))
  48 (def-edebug-spec return-from (symbolp &optional form))
  49
  50 ;; Loops
  51
  52 (def-edebug-spec case (form &rest (sexp body)))
  53 (def-edebug-spec ecase case)
  54 (def-edebug-spec do
  55   ((&rest &or symbolp (symbolp &optional form form))
  56    (form body)
  57    cl-declarations body))
  58 (def-edebug-spec do* do)
  59 (def-edebug-spec dolist
  60   ((symbolp form &optional form) cl-declarations body))
  61 (def-edebug-spec dotimes dolist)
  62 (def-edebug-spec do-symbols
  63   ((symbolp &optional form form) cl-declarations body))
  64 (def-edebug-spec do-all-symbols
  65   ((symbolp &optional form) cl-declarations body))
  66
  67 ;; Multiple values
  68
  69 (def-edebug-spec multiple-value-list (form))
  70 (def-edebug-spec multiple-value-call (function-form body))
  71 (def-edebug-spec multiple-value-bind
  72   ((&rest symbolp) form cl-declarations body))
  73 (def-edebug-spec multiple-value-setq ((&rest symbolp) form))
  74 (def-edebug-spec multiple-value-prog1 (form body))
  75
  76 ;; Bindings
  77
  78 (def-edebug-spec lexical-let let)
  79 (def-edebug-spec lexical-let* let)
  80
  81 (def-edebug-spec psetq setq)
  82 (def-edebug-spec progv (form form body))
  83
  84 (def-edebug-spec flet ((&rest (defun*)) cl-declarations body))
  85 (def-edebug-spec labels flet)
  86
  87 (def-edebug-spec macrolet
  88   ((&rest (&define name (&rest arg) cl-declarations-or-string def-body))
  89    cl-declarations body))
  90
  91 (def-edebug-spec symbol-macrolet
  92   ((&rest (symbol sexp)) cl-declarations body))
  93
  94 (def-edebug-spec destructuring-bind
  95   (&define cl-macro-list form cl-declarations def-body))
  96
  97 ;; Setf
  98
  99 (def-edebug-spec setf (&rest [place form])) ;; sexp is not specific enough
 100 (def-edebug-spec psetf setf)
 101
 102 (def-edebug-spec letf  ;; *not* available in Common Lisp
 103   ((&rest (gate place &optional form))
 104    body))
 105 (def-edebug-spec letf* letf)
 106
 107
 108 (def-edebug-spec defsetf
 109   (&define name
 110            [&or [symbolp &optional stringp]
 111                 [cl-lambda-list (symbolp)]]
 112            cl-declarations-or-string def-body))
 113
 114 (def-edebug-spec define-setf-method
 115   (&define name cl-lambda-list cl-declarations-or-string def-body))
 116
 117 (def-edebug-spec define-modify-macro
 118   (&define name cl-lambda-list ;; should exclude &key
 119            symbolp &optional stringp))
 120
 121 (def-edebug-spec callf (function* place &rest form))
 122 (def-edebug-spec callf2 (function* form place &rest form))
 123
 124 ;; Other operations on places
 125
 126 (def-edebug-spec remf (place form))
 127
 128 (def-edebug-spec incf (place &optional form))
 129 (def-edebug-spec decf incf)
 130 (def-edebug-spec push (form place))     ; different for CL
 131 (def-edebug-spec pushnew
 132   (form place &rest
 133         &or [[&or ":test" ":test-not" ":key"] function-form]
 134         [keywordp form]))
 135 (def-edebug-spec pop (place))           ; different for CL
 136
 137 (def-edebug-spec shiftf (&rest place))  ;; really [&rest place] form
 138 (def-edebug-spec rotatef (&rest place))
 139
 140
 141 ;; Functions with function args.  These are only useful if the
 142 ;; function arg is quoted with ' instead of function.
 143
 144 (def-edebug-spec some (function-form form &rest form))
 145 (def-edebug-spec every some)
 146 (def-edebug-spec notany some)
 147 (def-edebug-spec notevery some)
 148
 149 ;; Mapping
 150
 151 (def-edebug-spec map (form function-form form &rest form))
 152 (def-edebug-spec maplist (function-form form &rest form))
 153 (def-edebug-spec mapc maplist)
 154 (def-edebug-spec mapl maplist)
 155 (def-edebug-spec mapcan maplist)
 156 (def-edebug-spec mapcon maplist)
 157
 158 ;; Sequences
 159
 160 (def-edebug-spec reduce (function-form form &rest form))
 161
 162 ;; Types and assertions
 163
 164 (def-edebug-spec cl-type-spec (sexp)) ;; not worth the trouble to specify, yet.
 165
 166 (def-edebug-spec deftype defmacro*)
 167 (def-edebug-spec check-type (place cl-type-spec &optional stringp))
 168 ;; (def-edebug-spec assert (form &optional form stringp &rest form))
 169 (def-edebug-spec assert (form &rest form))
 170 (def-edebug-spec typecase (form &rest ([&or cl-type-spec "otherwise"] body)))
 171 (def-edebug-spec etypecase typecase)
 172
 173 (def-edebug-spec ignore-errors t)
 174
 175 ;; Time of Evaluation
 176
 177 (def-edebug-spec eval-when
 178   ((&rest &or "compile" "load" "eval") body))
 179 (def-edebug-spec load-time-value (form &optional &or "t" "nil"))
 180
 181 ;; Declarations
 182
 183 (def-edebug-spec cl-decl-spec
 184   ((symbolp &rest sexp)))
 185
 186 (def-edebug-spec cl-declarations
 187   (&rest ("declare" &rest cl-decl-spec)))
 188
 189 (def-edebug-spec cl-declarations-or-string
 190   (&or stringp cl-declarations))
 191
 192 (def-edebug-spec declaim (&rest cl-decl-spec))
 193 (def-edebug-spec declare (&rest cl-decl-spec))  ;; probably not needed.
 194 (def-edebug-spec locally (cl-declarations &rest form))
 195 (def-edebug-spec the (cl-type-spec form))
 196
 197 ;;======================================================
 198 ;; Lambda things
 199
 200 (def-edebug-spec cl-lambda-list
 201   (([&rest arg]
 202     [&optional ["&optional" cl-&optional-arg &rest cl-&optional-arg]]
 203     [&optional ["&rest" arg]]
 204     [&optional ["&key" [cl-&key-arg &rest cl-&key-arg]
 205                 &optional "&allow-other-keys"]]
 206     [&optional ["&aux" &rest
 207                 &or (symbolp &optional def-form) symbolp]]
 208     )))
 209
 210 (def-edebug-spec cl-&optional-arg
 211   (&or (arg &optional def-form arg) arg))
 212
 213 (def-edebug-spec cl-&key-arg
 214   (&or ([&or (symbolp arg) arg] &optional def-form arg) arg))
 215
 216 ;; The lambda list for macros is different from that of normal lambdas.
 217 ;; Note that &environment is only allowed as first or last items in the
 218 ;; top level list.
 219
 220 (def-edebug-spec cl-macro-list
 221   (([&optional "&environment" arg]
 222     [&rest cl-macro-arg]
 223     [&optional ["&optional" &rest
 224                 &or (cl-macro-arg &optional def-form cl-macro-arg) arg]]
 225     [&optional [[&or "&rest" "&body"] cl-macro-arg]]
 226     [&optional ["&key" [&rest
 227                         [&or ([&or (symbolp cl-macro-arg) arg]
 228                               &optional def-form cl-macro-arg)
 229                              arg]]
 230                 &optional "&allow-other-keys"]]
 231     [&optional ["&aux" &rest
 232                 &or (symbolp &optional def-form) symbolp]]
 233     [&optional "&environment" arg]
 234     )))
 235
 236 (def-edebug-spec cl-macro-arg
 237   (&or arg cl-macro-list1))
 238
 239 (def-edebug-spec cl-macro-list1
 240   (([&optional "&whole" arg]  ;; only allowed at lower levels
 241     [&rest cl-macro-arg]
 242     [&optional ["&optional" &rest
 243                 &or (cl-macro-arg &optional def-form cl-macro-arg) arg]]
 244     [&optional [[&or "&rest" "&body"] cl-macro-arg]]
 245     [&optional ["&key" [&rest
 246                         [&or ([&or (symbolp cl-macro-arg) arg]
 247                               &optional def-form cl-macro-arg)
 248                              arg]]
 249                 &optional "&allow-other-keys"]]
 250     [&optional ["&aux" &rest
 251                 &or (symbolp &optional def-form) symbolp]]
 252     . [&or arg nil])))
 253
 254
 255 (def-edebug-spec defun*
 256   ;; Same as defun but use cl-lambda-list.
 257   (&define [&or name
 258                 ("setf" :name setf name)]
 259            cl-lambda-list
 260            cl-declarations-or-string
 261            [&optional ("interactive" interactive)]
 262            def-body))
 263 (def-edebug-spec defsubst* defun*)
 264
 265 (def-edebug-spec defmacro*
 266   (&define name cl-macro-list cl-declarations-or-string def-body))
 267 (def-edebug-spec define-compiler-macro defmacro*)
 268
 269
 270 (def-edebug-spec function*
 271   (&or symbolp cl-lambda-expr))
 272
 273 (def-edebug-spec cl-lambda-expr
 274   (&define ("lambda" cl-lambda-list
 275             ;;cl-declarations-or-string
 276             ;;[&optional ("interactive" interactive)]
 277             def-body)))
 278
 279 ;; Redefine function-form to also match function*
 280 (def-edebug-spec function-form
 281   ;; form at the end could also handle "function",
 282   ;; but recognize it specially to avoid wrapping function forms.
 283   (&or ([&or "quote" "function"] &or symbolp lambda-expr)
 284        ("function*" function*)
 285        form))
 286
 287 ;;======================================================
 288 ;; Structures
 289 ;; (def-edebug-spec defstruct (&rest sexp)) would be sufficient, but...
 290
 291 ;; defstruct may contain forms that are evaluated when a structure is created.
 292 (def-edebug-spec defstruct
 293   (&define  ; makes top-level form not be wrapped
 294    [&or symbolp
 295         (gate
 296          symbolp &rest
 297                  (&or [":conc-name" &or stringp "nil"]
 298                       [":constructor" symbolp &optional cl-lambda-list]
 299                       [":copier" symbolp]
 300                       [":predicate" symbolp]
 301                       [":include" symbolp &rest sexp];; not finished
 302                       ;; The following are not supported.
 303                       ;; [":print-function" ...]
 304                       ;; [":type" ...]
 305                       ;; [":initial-offset" ...]
 306                       ))]
 307    [&optional stringp]
 308    ;; All the above is for the following def-form.
 309    &rest &or symbolp (symbolp def-form &optional ":read-only" sexp)))
 310
 311 ;;======================================================
 312 ;; Loop
 313
 314 ;; The loop macro is very complex, and a full spec is found below.
 315 ;; The following spec only minimally specifies that
 316 ;; parenthesized forms are executable, but single variables used as
 317 ;; expressions will be missed.  You may want to use this if the full
 318 ;; spec causes problems for you.
 319
 320 (def-edebug-spec loop
 321   (&rest &or symbolp form))
 322
 323 ;; Below is a complete spec for loop, in several parts that correspond
 324 ;; to the syntax given in CLtL2.  The specs do more than specify where
 325 ;; the forms are; it also specifies, as much as Edebug allows, all the
 326 ;; syntactically legal loop clauses.  The disadvantage of this
 327 ;; completeness is rigidity, but the "for ... being" clause allows
 328 ;; arbitrary extensions of the form: [symbolp &rest &or symbolp form].
 329
 330 (def-edebug-spec loop
 331   ([&optional ["named" symbolp]]
 332    [&rest
 333     &or
 334     ["repeat" form]
 335     loop-for-as
 336     loop-with
 337     loop-initial-final]
 338    [&rest loop-clause]
 339    ))
 340
 341 (def-edebug-spec loop-with
 342   ("with" loop-var
 343    loop-type-spec
 344    [&optional ["=" form]]
 345    &rest ["and" loop-var
 346           loop-type-spec
 347           [&optional ["=" form]]]))
 348
 349 (def-edebug-spec loop-for-as
 350   ([&or "for" "as"] loop-for-as-subclause
 351    &rest ["and" loop-for-as-subclause]))
 352
 353 (def-edebug-spec loop-for-as-subclause
 354   (loop-var
 355    loop-type-spec
 356    &or
 357    [[&or "in" "on" "in-ref" "across-ref"]
 358     form &optional ["by" function-form]]
 359
 360    ["=" form &optional ["then" form]]
 361    ["across" form]
 362    ["being"
 363     [&or "the" "each"]
 364     &or
 365     [[&or "element" "elements"]
 366      [&or "of" "in" "of-ref"] form
 367      &optional "using" ["index" symbolp]];; is this right?
 368     [[&or "hash-key" "hash-keys"
 369           "hash-value" "hash-values"]
 370      [&or "of" "in"]
 371      hash-table-p &optional ["using" ([&or "hash-value" "hash-values"
 372                                            "hash-key" "hash-keys"] sexp)]]
 373
 374     [[&or "symbol" "present-symbol" "external-symbol"
 375           "symbols" "present-symbols" "external-symbols"]
 376      [&or "in" "of"] package-p]
 377
 378     ;; Extensions for Emacs Lisp, including Lucid Emacs.
 379     [[&or "frame" "frames"
 380           "screen" "screens"
 381           "buffer" "buffers"]]
 382
 383     [[&or "window" "windows"]
 384      [&or "of" "in"] form]
 385
 386     [[&or "overlay" "overlays"
 387           "extent" "extents"]
 388      [&or "of" "in"] form
 389      &optional [[&or "from" "to"] form]]
 390
 391     [[&or "interval" "intervals"]
 392      [&or "in" "of"] form
 393      &optional [[&or "from" "to"] form]
 394      ["property" form]]
 395
 396     [[&or "key-code" "key-codes"
 397           "key-seq" "key-seqs"
 398           "key-binding" "key-bindings"]
 399      [&or "in" "of"] form
 400      &optional ["using" ([&or "key-code" "key-codes"
 401                               "key-seq" "key-seqs"
 402                               "key-binding" "key-bindings"]
 403                          sexp)]]
 404     ;; For arbitrary extensions, recognize anything else.
 405     [symbolp &rest &or symbolp form]
 406     ]
 407
 408    ;; arithmetic - must be last since all parts are optional.
 409    [[&optional [[&or "from" "downfrom" "upfrom"] form]]
 410     [&optional [[&or "to" "downto" "upto" "below" "above"] form]]
 411     [&optional ["by" form]]
 412     ]))
 413
 414 (def-edebug-spec loop-initial-final
 415   (&or ["initially"
 416         ;; [&optional &or "do" "doing"]  ;; CLtL2 doesn't allow this.
 417         &rest loop-non-atomic-expr]
 418        ["finally" &or
 419         [[&optional &or "do" "doing"] &rest loop-non-atomic-expr]
 420         ["return" form]]))
 421
 422 (def-edebug-spec loop-and-clause
 423   (loop-clause &rest ["and" loop-clause]))
 424
 425 (def-edebug-spec loop-clause
 426   (&or
 427    [[&or "while" "until" "always" "never" "thereis"] form]
 428
 429    [[&or "collect" "collecting"
 430          "append" "appending"
 431          "nconc" "nconcing"
 432          "concat" "vconcat"] form
 433          [&optional ["into" loop-var]]]
 434
 435    [[&or "count" "counting"
 436          "sum" "summing"
 437          "maximize" "maximizing"
 438          "minimize" "minimizing"] form
 439          [&optional ["into" loop-var]]
 440          loop-type-spec]
 441
 442    [[&or "if" "when" "unless"]
 443     form loop-and-clause
 444     [&optional ["else" loop-and-clause]]
 445     [&optional "end"]]
 446
 447    [[&or "do" "doing"] &rest loop-non-atomic-expr]
 448
 449    ["return" form]
 450    loop-initial-final
 451    ))
 452
 453 (def-edebug-spec loop-non-atomic-expr
 454   ([&not atom] form))
 455
 456 (def-edebug-spec loop-var
 457   ;; The symbolp must be last alternative to recognize e.g. (a b . c)
 458   ;; loop-var =>
 459   ;; (loop-var . [&or nil loop-var])
 460   ;; (symbolp . [&or nil loop-var])
 461   ;; (symbolp . loop-var)
 462   ;; (symbolp . (symbolp . [&or nil loop-var]))
 463   ;; (symbolp . (symbolp . loop-var))
 464   ;; (symbolp . (symbolp . symbolp)) == (symbolp symbolp . symbolp)
 465   (&or (loop-var . [&or nil loop-var]) [gate symbolp]))
 466
 467 (def-edebug-spec loop-type-spec
 468   (&optional ["of-type" loop-d-type-spec]))
 469
 470 (def-edebug-spec loop-d-type-spec
 471   (&or (loop-d-type-spec . [&or nil loop-d-type-spec]) cl-type-spec))
 472
 473 ;;; arch-tag: b29aa3c2-cf67-4af8-9ee1-318fea61b478
 474 ;;; cl-specs.el ends here