Info Catalog elisp: Inline Functions elisp: Functions elisp: Declaring Functions

elisp: Declare Form

 
 12.14 The ‘declare’ Form
 ========================
 
 ‘declare’ is a special macro which can be used to add meta properties to
 a function or macro: for example, marking it as obsolete, or giving its
 forms a special <TAB> indentation convention in Emacs Lisp mode.
 
  -- Macro: declare specs...
      This macro ignores its arguments and evaluates to ‘nil’; it has no
      run-time effect.  However, when a ‘declare’ form occurs in the
      DECLARE argument of a ‘defun’ or ‘defsubst’ function definition
      (Defining Functions) or a ‘defmacro’ macro definition
      (Defining Macros), it appends the properties specified by
      SPECS to the function or macro.  This work is specially performed
      by ‘defun’, ‘defsubst’, and ‘defmacro’.
 
      Each element in SPECS should have the form ‘(PROPERTY ARGS...)’,
      which should not be quoted.  These have the following effects:
 
      ‘(advertised-calling-convention SIGNATURE WHEN)’
           This acts like a call to ‘set-advertised-calling-convention’
           (Obsolete Functions); SIGNATURE specifies the correct
           argument list for calling the function or macro, and WHEN
           should be a string indicating when the old argument list was
           first made obsolete.
 
      ‘(debug EDEBUG-FORM-SPEC)’
           This is valid for macros only.  When stepping through the
           macro with Edebug, use EDEBUG-FORM-SPEC.  Instrumenting
           Macro Calls.
 
      ‘(doc-string N)’
           This is used when defining a function or macro which itself
           will be used to define entities like functions, macros, or
           variables.  It indicates that the Nth argument, if any, should
           be considered as a documentation string.
 
      ‘(indent INDENT-SPEC)’
           Indent calls to this function or macro according to
           INDENT-SPEC.  This is typically used for macros, though it
           works for functions too.  Indenting Macros.
 
      ‘(interactive-only VALUE)’
           Set the function’s ‘interactive-only’ property to VALUE.
           The interactive-only property.
 
      ‘(obsolete CURRENT-NAME WHEN)’
           Mark the function or macro as obsolete, similar to a call to
           ‘make-obsolete’ (Obsolete Functions).  CURRENT-NAME
           should be a symbol (in which case the warning message says to
           use that instead), a string (specifying the warning message),
           or ‘nil’ (in which case the warning message gives no extra
           details).  WHEN should be a string indicating when the
           function or macro was first made obsolete.
 
      ‘(compiler-macro EXPANDER)’
           This can only be used for functions, and tells the compiler to
           use EXPANDER as an optimization function.  When encountering a
           call to the function, of the form ‘(FUNCTION ARGS...)’, the
           macro expander will call EXPANDER with that form as well as
           with ARGS..., and EXPANDER can either return a new expression
           to use instead of the function call, or it can return just the
           form unchanged, to indicate that the function call should be
           left alone.  EXPANDER can be a symbol, or it can be a form
           ‘(lambda (ARG) BODY)’ in which case ARG will hold the original
           function call expression, and the (unevaluated) arguments to
           the function can be accessed using the function’s formal
           arguments.
 
      ‘(gv-expander EXPANDER)’
           Declare EXPANDER to be the function to handle calls to the
           macro (or function) as a generalized variable, similarly to
           ‘gv-define-expander’.  EXPANDER can be a symbol or it can be
           of the form ‘(lambda (ARG) BODY)’ in which case that function
           will additionally have access to the macro (or function)’s
           arguments.
 
      ‘(gv-setter SETTER)’
           Declare SETTER to be the function to handle calls to the macro
           (or function) as a generalized variable.  SETTER can be a
           symbol in which case it will be passed to
           ‘gv-define-simple-setter’, or it can be of the form ‘(lambda
           (ARG) BODY)’ in which case that function will additionally
           have access to the macro (or function)’s arguments and it will
           passed to ‘gv-define-setter’.
 

Info Catalog elisp: Inline Functions elisp: Functions elisp: Declaring Functions