Info Catalog elisp: Advising Functions elisp: Advising Named Functions

elisp: Core Advising Primitives

 
 12.11.1 Primitives to manipulate advices
 ----------------------------------------
 
  -- Macro: add-function where place function &optional props
      This macro is the handy way to add the advice FUNCTION to the
      function stored in PLACE (Generalized Variables).
 
      WHERE determines how FUNCTION is composed with the existing
      function, e.g., whether FUNCTION should be called before, or after
      the original function.  Advice combinators, for the list of
      available ways to compose the two functions.
 
      When modifying a variable (whose name will usually end with
      ‘-function’), you can choose whether FUNCTION is used globally or
      only in the current buffer: if PLACE is just a symbol, then
      FUNCTION is added to the global value of PLACE.  Whereas if PLACE
      is of the form ‘(local SYMBOL)’, where SYMBOL is an expression
      which returns the variable name, then FUNCTION will only be added
      in the current buffer.  Finally, if you want to modify a lexical
      variable, you will have to use ‘(var VARIABLE)’.
 
      Every function added with ‘add-function’ can be accompanied by an
      association list of properties PROPS.  Currently only two of those
      properties have a special meaning:
 
      ‘name’
           This gives a name to the advice, which ‘remove-function’ can
           use to identify which function to remove.  Typically used when
           FUNCTION is an anonymous function.
 
      ‘depth’
           This specifies how to order the advice, should several pieces
           of advice be present.  By default, the depth is 0.  A depth of
           100 indicates that this piece of advice should be kept as deep
           as possible, whereas a depth of -100 indicates that it should
           stay as the outermost piece.  When two pieces of advice
           specify the same depth, the most recently added one will be
           outermost.
 
           For ‘:before’ advice, being outermost means that this advice
           will be run first, before any other advice, whereas being
           innermost means that it will run right before the original
           function, with no other advice run between itself and the
           original function.  Similarly, for ‘:after’ advice innermost
           means that it will run right after the original function, with
           no other advice run in between, whereas outermost means that
           it will be run right at the end after all other advice.  An
           innermost ‘:override’ piece of advice will only override the
           original function and other pieces of advice will apply to it,
           whereas an outermost ‘:override’ piece of advice will override
           not only the original function but all other advice applied to
           it as well.
 
      If FUNCTION is not interactive, then the combined function will
      inherit the interactive spec, if any, of the original function.
      Else, the combined function will be interactive and will use the
      interactive spec of FUNCTION.  One exception: if the interactive
      spec of FUNCTION is a function (rather than an expression or a
      string), then the interactive spec of the combined function will be
      a call to that function with as sole argument the interactive spec
      of the original function.  To interpret the spec received as
      argument, use ‘advice-eval-interactive-spec’.
 
      Note: The interactive spec of FUNCTION will apply to the combined
      function and should hence obey the calling convention of the
      combined function rather than that of FUNCTION.  In many cases, it
      makes no difference since they are identical, but it does matter
      for ‘:around’, ‘:filter-args’, and ‘filter-return’, where FUNCTION.
 
  -- Macro: remove-function place function
      This macro removes FUNCTION from the function stored in PLACE.
      This only works if FUNCTION was added to PLACE using
      ‘add-function’.
 
      FUNCTION is compared with functions added to PLACE using ‘equal’,
      to try and make it work also with lambda expressions.  It is
      additionally compared also with the ‘name’ property of the
      functions added to PLACE, which can be more reliable than comparing
      lambda expressions using ‘equal’.
 
  -- Function: advice-function-member-p advice function-def
      Return non-‘nil’ if ADVICE is already in FUNCTION-DEF.  Like for
      ‘remove-function’ above, instead of ADVICE being the actual
      function, it can also be the ‘name’ of the piece of advice.
 
  -- Function: advice-function-mapc f function-def
      Call the function F for every piece of advice that was added to
      FUNCTION-DEF.  F is called with two arguments: the advice function
      and its properties.
 
  -- Function: advice-eval-interactive-spec spec
      Evaluate the interactive SPEC just like an interactive call to a
      function with such a spec would, and then return the corresponding
      list of arguments that was built.  E.g.,
      ‘(advice-eval-interactive-spec "r\nP")’ will return a list of three
      elements, containing the boundaries of the region and the current
      prefix argument.
 

Info Catalog elisp: Advising Functions elisp: Advising Named Functions