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