Macro

Summary

Establishes a parser for top level forms with the given definer.

Package

dspec

Signature

define-form-parser definer-and-options &optional parameters &body body => parser

Arguments

definer-and-options

A symbol definer naming a definer of functions, macros, variables and so on, or a list (definer options) where options is a plist of keys and values.

parameters

nil, or list of parameters params in the top level form, optionally ending with
&rest param-getter.

body

The body of a parser function.

Values

parser

A form parser function.

Description

The macro define-form-parser defines a form parser for forms beginning with definer.

options is a property list with the following keys allowed:

:parser

A parser function parser-function.

:alias

A dspec class or alias alias.

:anonymous

A boolean.

The parser function defined is named by parser-function. If the :parser option is omitted then the name defaults to a symbol in the current package whose symbol name is the symbol name of definer with "-FORM-PARSER" appended.

If parameters and body are given, then parser-function is defined as a global function that is expected to return a dspec for the defining form or nil if this is not possible. Within body, definer is bound to the car of the actual form being parsed. In simple cases, this is just definer, but if the form parser is used as in the :alias option of another form parser then the symbol will be bound to the car of that form instead.

The params are bound to subsequent subforms of the defining form. If &rest param-getter is supplied, then it is bound to a function of no arguments that returns two values: the next subform if there is one and a boolean to indicate if a subform was found.

If parameters and body are omitted, then parser-function is expected to be a form parser defined by a different define-form-parser form, or you can specify as an alias a definer with an existing form parser via the value alias of the :alias key in options.

If the :anonymous option is non-nil then definer is not associated with the form parser. This is useful in conjunction with parameters and body for defining generic form parsers that can be used in other define-form-parser forms.

LispWorks contains pre-defined form parser functions for the Common Lisp definers defun, defmethod, defgeneric, defvar, defparameter, defconstant, defstruct, defclass, defmacro and deftype and for LispWorks definers such as fli:define-foreign-type and dspec:define-form-parser itself.

When a defining symbol definer has an associated form parser, this parser function is used by the source location commands such as Expression > Find Source in the LispWorks IDE. Having identified the file where the definition was recorded, LispWorks parses the top level forms in the file looking for the one which matches the definition spec. When found, this match is displayed.

Example

Define a parser for def-foo forms which have a single name as the second element in the form:

(dspec:define-form-parser def-foo (name)

  `(,def-foo ,name))

Define a parser for def-other-foo forms which are like def-foo forms:

(dspec:define-form-parser 

    (def-other-foo (:parser def-foo-form-parser)))

Define a parser for def-bar forms whose name is made from the second element of the form and any subsequent keywords:

(dspec:define-form-parser def-bar (name &rest details)

  `(,def-bar (,name

              ,@(loop for detail = (funcall details)

                      while (keywordp detail)

                      collect detail))))

Define a parser for forms which have another name as the second element in the form:

(dspec:define-form-parser (two-names

                           (:anonymous t)) (name1 name2)

  `(,two-names ,name1 ,name2))

Define a new way to define CLOS methods, and tell the dspec system to treat them the same. Note the use of define-dspec-alias to inform the dspec system that my-defmethod is another way of naming defmethod dspecs:

(defmacro my-defmethod (name args &body body)

  `(defmethod ,name ,args 

     ,@body))

(dspec:define-dspec-alias my-defmethod 

    (name &rest args)

  `(defmethod ,name ,@args))

(my-defmethod foo ((x number)) 

  42)

(dspec:define-form-parser 

    (my-defmethod 

        (:parser 

         #.(dspec:get-form-parser 'defmethod))))

A simpler way to write the last form is:

(dspec:define-form-parser

    (my-defmethod

        (:alias defmethod)))

See also

get-form-parser
parse-form-dspec