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