Changeset 13830


Ignore:
Timestamp:
Jun 15, 2010, 6:49:32 PM (9 years ago)
Author:
rme
Message:

Documentation for ccl:advise and friends. Largely copied from the MCL
manual.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/using.xml

    r13790 r13830  
    481481    space every this many levels of indentation.</para>
    482482
     483
     484  </sect1>
     485
     486  <sect1 id="Advising"><title>Advising</title>
     487  <para>
     488    The <literal>advise</literal> macro can be thought of as a more
     489    general version of <literal>trace</literal>. It allows code that
     490    you specify to run before, after, or around a given function, for
     491    the purpose of changing the behavior of the function. Each piece
     492    of added code is called a piece of advice. Each piece of advice
     493    has a unique name, so that you can have multiple pieces of advice
     494    on the same function, including multiple
     495    <literal>:before</literal>, <literal>:after</literal>, and
     496    <literal>:around</literal> pieces of advice.
     497  </para>
     498  <para>
     499    The <literal>:name</literal> and <literal>:when</literal>
     500    keywords serve to identify the piece of advice.  A later call to
     501    <literal>advise</literal> with the same values of
     502    <literal>:name</literal> and <literal>:when</literal> will replace
     503    the existing piece of advice; a call with different values will not.
     504  </para>
     505
     506  <refentry id="m_advise">
     507    <indexterm zone="m_advise">
     508      <primary>advise</primary>
     509    </indexterm>
     510
     511    <refnamediv>
     512      <refname>ADVISE</refname>
     513      <refpurpose>
     514        Add a piece of advice to the function or method specified by
     515        <varname>spec</varname> according to
     516        <varname>form</varname>.
     517      </refpurpose>
     518      <refclass>Macro</refclass>
     519    </refnamediv>
     520   
     521    <refsynopsisdiv>
     522      <synopsis><function>advise</function> spec form &key; when name</synopsis>
     523    </refsynopsisdiv>
     524
     525    <refsect1>
     526      <title>Arguments and Values</title>
     527      <variablelist>
     528        <varlistentry>
     529          <term>spec</term>
     530          <listitem>
     531            <para>
     532              A specification of the function on which to put the
     533              advice.  This is either a symbol that is the name of a
     534              function or generic function, or an expression of the
     535              form (setf <replaceable>symbol</replaceable>), or a
     536              specific method of a generic function in the form
     537              (:method symbol {qualifiers} (specializer {specializer})).
     538            </para>
     539          </listitem>
     540        </varlistentry>
     541        <varlistentry>
     542          <term>form</term>
     543          <listitem>
     544            <para>
     545              A form to execute before, after, or around the advised
     546              function. The form can refer to the variable arglist
     547              that is bound to the arguments with which the advised
     548              function was called. You can exit from form with
     549              (return).
     550            </para>
     551          </listitem>
     552        </varlistentry>
     553        <varlistentry>
     554          <term>name</term>
     555          <listitem>
     556            <para>
     557              A name that identifies the piece of advice.
     558            </para>
     559          </listitem>
     560        </varlistentry>
     561        <varlistentry>
     562          <term>when</term>
     563          <listitem>
     564            <para>
     565              An argument that specifies when the piece of advice is
     566              run. There are three allowable values. The default is
     567              <literal>:before</literal>, which specifies that form is
     568              executed before the advised function is called. Other
     569              possible values are <literal>:after</literal>, which
     570              specifies that form is executed after the advised
     571              function is called, and <literal>:around</literal>,
     572              which specifies that form is executed around the call to
     573              the advised function. Use <literal>(:do-it)</literal>
     574              within form to indicate invocation of the original
     575              definition.
     576            </para>
     577          </listitem>
     578        </varlistentry>
     579      </variablelist>
     580    </refsect1>
     581   
     582    <refsect1>
     583      <title>Examples</title>
     584      <para>
     585        The function <literal>foo</literal>, already defined, does
     586        something with a list of numbers. The following code uses a
     587        piece of advice to make foo return zero if any of its
     588        arguments is not a number. Using :around advice, you can do
     589        the following:
     590        <programlisting>
     591(advise foo (if (some #'(lambda (n) (not (numberp n))) arglist)
     592              0
     593              (:do-it))
     594        :when :around :name :zero-if-not-nums)
     595        </programlisting>
     596      </para>
     597      <para>
     598        To do the same thing using a :before piece of advice:
     599        <programlisting>
     600(advise foo (if (some #'(lambda (n) (not (numberp n))) arglist)
     601              (return 0))
     602        :when :before :name :zero-if-not-nums)
     603        </programlisting>
     604      </para>
     605    </refsect1>
     606  </refentry>
     607
     608  <refentry id="m_unadvise">
     609    <indexterm zone="m_unadvise">
     610      <primary>unadvise</primary>
     611    </indexterm>
     612
     613    <refnamediv>
     614      <refname>UNADVISE</refname>
     615      <refpurpose>
     616        Remove the piece or pieces of advice matching <varname>spec</varname>,
     617        <varname>when</varname>, and <varname>name</varname>.
     618      </refpurpose>
     619      <refclass>Macro</refclass>
     620    </refnamediv>
     621   
     622    <refsynopsisdiv>
     623      <synopsis><function>unadvise</function> spec &key; when name</synopsis>
     624    </refsynopsisdiv>
     625
     626    <refsect1>
     627      <title>Description</title>
     628      <para>
     629        The unadvise macro removes the piece or pieces of advice
     630        matching <literal>spec</literal>, <literal>when</literal>,
     631        and <literal>name</literal>. When the value of
     632        <literal>spec</literal> is t and the values of <literal>when</literal>
     633        and <literal>name</literal> are nil, unadvise
     634        removes every piece of advice; when <literal>spec</literal> is
     635        t, the argument <literal>when</literal> is nil, and
     636        <literal>name</literal> is non-nil, unadvise removes all
     637        pieces of advice with the given name.
     638      </para>
     639    </refsect1>
     640    <refsect1>
     641      <title>Arguments and Values</title>
     642      <para>
     643        The arguments have the same meaning as in
     644        <xref linkend="m_advise"/>.
     645      </para>
     646    </refsect1>
     647  </refentry>
     648
     649  <refentry id="m_advisedp">
     650    <indexterm zone="m_advisedp">
     651      <primary>advisedp</primary>
     652    </indexterm>
     653
     654    <refnamediv>
     655      <refname>ADVISEDP</refname>
     656      <refpurpose>
     657        Return a list of the pieces of advice matching <varname>spec</varname>,
     658        <varname>when</varname>, and <varname>name</varname>.
     659      </refpurpose>
     660      <refclass>Macro</refclass>
     661    </refnamediv>
     662   
     663    <refsynopsisdiv>
     664      <synopsis><function>advisedp</function> spec &key; when name</synopsis>
     665    </refsynopsisdiv>
     666
     667    <refsect1>
     668      <title>Description</title>
     669      <para>
     670        The advisedp macro returns a list of existing pieces of advice
     671        that match <literal>spec</literal>, <literal>when</literal>,
     672        and <literal>name</literal>. When the value of
     673        <literal>spec</literal> is t and the values of
     674        <literal>when</literal> and <literal>name</literal> are nil,
     675        advisedp returns all existing pieces of advice.
     676      </para>
     677    </refsect1>
     678    <refsect1>
     679      <title>Arguments and Values</title>
     680      <para>
     681        The arguments have the same meaning as in
     682        <xref linkend="m_advise"/>.
     683      </para>
     684    </refsect1>
     685  </refentry>
    483686
    484687  </sect1>
Note: See TracChangeset for help on using the changeset viewer.