85 lines
17 KiB
HTML
85 lines
17 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: Macro DEFMETHOD</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="m_defgen.htm">
|
|
<LINK REL=UP HREF="c_object.htm">
|
|
<LINK REL=NEXT HREF="f_find_c.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="m_defgen.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="c_object.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="f_find_c.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
<A NAME="defmethod"><I>Macro</I> <B>DEFMETHOD</B></A> <P>
|
|
<P>
|
|
<P><B>Syntax:</B><P>
|
|
<P>
|
|
|
|
<B>defmethod</B> <I><I>function-name</I> {<I>method-qualifier</I>}* <I>specialized-lambda-list</I> [[<I>declaration</I><B>*</B> | <I>documentation</I>]] <I>form</I><B>*</B></I><P> => <I>new-method</I><P>
|
|
<P>
|
|
<P><I>function-name</I>::= {<A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A> | <TT>(setf <A REL=DEFINITION HREF="26_glo_s.htm#symbol"></TT><I>symbol</I><TT></A>)</TT>} <P><I>method-qualifier</I>::= <A REL=DEFINITION HREF="26_glo_n.htm#non-list"><I>non-list</I></A> <P><PRE>
|
|
specialized-lambda-list::= ({var | (var parameter-specializer-name)}*
|
|
[&optional {var | (var [initform [supplied-p-parameter] ])}*]
|
|
[&rest var]
|
|
[&key{var | ({var | (<A REL=DEFINITION HREF="26_glo_k.htm#keyword">keyword</A>var)} [initform [supplied-p-parameter] ])}*
|
|
[&allow-other-keys] ]
|
|
[&aux {var | (var [initform] )}*] )
|
|
parameter-specializer-name::= <A REL=DEFINITION HREF="26_glo_s.htm#symbol">symbol</A> | (eql eql-specializer-form)
|
|
</PRE>
|
|
<P> <P>
|
|
<P><B>Arguments and Values:</B><P>
|
|
<P>
|
|
<I>declaration</I>---a <A REL=DEFINITION HREF="s_declar.htm#declare"><B>declare</B></A> <A REL=DEFINITION HREF="26_glo_e.htm#expression"><I>expression</I></A>; not evaluated. <P>
|
|
<I>documentation</I>---a <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>string</I></A>; not evaluated. <P>
|
|
<I>var</I>---a <A REL=DEFINITION HREF="26_glo_v.htm#variable"><I>variable</I></A> <A REL=DEFINITION HREF="26_glo_n.htm#name"><I>name</I></A>. <P>
|
|
<I>eql-specializer-form</I>---a <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>. <P>
|
|
<I>Form</I>---a <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>. <P>
|
|
<I>Initform</I>---a <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>. <P>
|
|
<I>Supplied-p-parameter</I>---variable name. <P>
|
|
<I>new-method</I>---the new <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> <A REL=DEFINITION HREF="26_glo_o.htm#object"><I>object</I></A>. <P>
|
|
<P><B>Description:</B><P>
|
|
<P>
|
|
The macro <A REL=DEFINITION HREF="#defmethod"><B>defmethod</B></A> defines a <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> on a <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A>. <P>
|
|
If <TT>(fboundp </TT><I>function-name</I><TT>)</TT> is <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A>, a <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A> is created with default values for the argument precedence order (each argument is more specific than the arguments to its right in the argument list), for the generic function class (the <A REL=DEFINITION HREF="26_glo_c.htm#class"><I>class</I></A> <A REL=DEFINITION HREF="t_std_ge.htm#standard-generic-function"><B>standard-generic-function</B></A>), for the method class (the <A REL=DEFINITION HREF="26_glo_c.htm#class"><I>class</I></A> <A REL=DEFINITION HREF="t_std_me.htm#standard-method"><B>standard-method</B></A>), and for the method combination type (the standard method combination type). The <A REL=DEFINITION HREF="26_glo_l.htm#lambda_list"><I>lambda list</I></A> of the <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A> is congruent with the <A REL=DEFINITION HREF="26_glo_l.htm#lambda_list"><I>lambda list</I></A> of the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> being defined; if the <A REL=DEFINITION HREF="#defmethod"><B>defmethod</B></A> form mentions keyword arguments, the <A REL=DEFINITION HREF="26_glo_l.htm#lambda_list"><I>lambda list</I></A> of the <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A> will mention <TT> ..... key</TT> (but no keyword arguments). If <I>function-name</I> names an <A REL=DEFINITION HREF="26_glo_o.htm#ordinary_function"><I>ordinary function</I></A>, a <A REL=DEFINITION HREF="26_glo_m.htm#macro"><I>macro</I></A>, or a <A REL=DEFINITION HREF="26_glo_s.htm#special_operator"><I>special operator</I></A>, an error is signaled. <P>
|
|
If a <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A> is currently named by <I>function-name</I>, the <A REL=DEFINITION HREF="26_glo_l.htm#lambda_list"><I>lambda list</I></A> of the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> must be congruent with the <A REL=DEFINITION HREF="26_glo_l.htm#lambda_list"><I>lambda list</I></A> of the <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A>. If this condition does not hold, an error is signaled. For a definition of congruence in this context, see <A REL=CHILD HREF="07_fd.htm">Section 7.6.4 (Congruent Lambda-lists for all Methods of a Generic Function)</A>. <P>
|
|
Each <I>method-qualifier</I> argument is an <A REL=DEFINITION HREF="26_glo_o.htm#object"><I>object</I></A> that is used by method combination to identify the given <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A>. The method combination type might further restrict what a method <A REL=DEFINITION HREF="26_glo_q.htm#qualifier"><I>qualifier</I></A> can be. The standard method combination type allows for <A REL=DEFINITION HREF="26_glo_u.htm#unqualified_method"><I>unqualified methods</I></A> and <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>methods</I></A> whose sole <A REL=DEFINITION HREF="26_glo_q.htm#qualifier"><I>qualifier</I></A> is one of the keywords <TT>:before</TT>, <TT>:after</TT>, or <TT>:around</TT>. <P>
|
|
The <I>specialized-lambda-list</I> argument is like an ordinary <A REL=DEFINITION HREF="26_glo_l.htm#lambda_list"><I>lambda list</I></A> except that the <A REL=DEFINITION HREF="26_glo_n.htm#name"><I>names</I></A> of required parameters can be replaced by specialized parameters. A specialized parameter is a list of the form <TT>(</TT><I>var</I><TT> </TT><I>parameter-specializer-name</I><TT>)</TT>. Only required parameters can be specialized. If <I>parameter-specializer-name</I> is a <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A> it names a <A REL=DEFINITION HREF="26_glo_c.htm#class"><I>class</I></A>; if it is a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A>, it is of the form <TT>(eql </TT><I>eql-specializer-form</I><TT>)</TT>. The parameter specializer name <TT>(eql </TT><I>eql-specializer-form</I><TT>)</TT> indicates that the corresponding argument must be <A REL=DEFINITION HREF="f_eql.htm#eql"><B>eql</B></A> to the <A REL=DEFINITION HREF="26_glo_o.htm#object"><I>object</I></A> that is the value of <I>eql-specializer-form</I> for the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> to be applicable. The <I>eql-specializer-form</I> is evaluated at the time that the expansion of the <A REL=DEFINITION HREF="#defmethod"><B>defmethod</B></A> macro is evaluated. If no <A REL=DEFINITION HREF="26_glo_p.htm#parameter_specializer_name"><I>parameter specializer name</I></A> is specified for a given required parameter, the <A REL=DEFINITION HREF="26_glo_p.htm#parameter_specializer"><I>parameter specializer</I></A> defaults to the <A REL=DEFINITION HREF="26_glo_c.htm#class"><I>class</I></A> <A REL=DEFINITION HREF="t_t.htm#t"><B>t</B></A>. For further discussion, see <A REL=CHILD HREF="07_fb.htm">Section 7.6.2 (Introduction to Methods)</A>. <P>
|
|
The <I>form</I> arguments specify the method body. The body of the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> is enclosed in an <A REL=DEFINITION HREF="26_glo_i.htm#implicit_block"><I>implicit block</I></A>. If <I>function-name</I> is a <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A>, this block bears the same <A REL=DEFINITION HREF="26_glo_n.htm#name"><I>name</I></A> as the <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A>. If <I>function-name</I> is a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> of the form <TT>(setf </TT><I>symbol</I><TT>)</TT>, the <A REL=DEFINITION HREF="26_glo_n.htm#name"><I>name</I></A> of the block is <I>symbol</I>. <P>
|
|
The <A REL=DEFINITION HREF="26_glo_c.htm#class"><I>class</I></A> of the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> <A REL=DEFINITION HREF="26_glo_o.htm#object"><I>object</I></A> that is created is that given by the method class option of the <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A> on which the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> is defined. <P>
|
|
If the <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A> already has a <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> that agrees with the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> being defined on <A REL=DEFINITION HREF="26_glo_p.htm#parameter_specializer"><I>parameter specializers</I></A> and <A REL=DEFINITION HREF="26_glo_q.htm#qualifier"><I>qualifiers</I></A>, <A REL=DEFINITION HREF="#defmethod"><B>defmethod</B></A> replaces the existing <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> with the one now being defined. For a definition of agreement in this context. see <A REL=CHILD HREF="07_fc.htm">Section 7.6.3 (Agreement on Parameter Specializers and Qualifiers)</A>. <P>
|
|
The <A REL=DEFINITION HREF="26_glo_p.htm#parameter_specializer"><I>parameter specializers</I></A> are derived from the <A REL=DEFINITION HREF="26_glo_p.htm#parameter_specializer_name"><I>parameter specializer names</I></A> as described in <A REL=CHILD HREF="07_fb.htm">Section 7.6.2 (Introduction to Methods)</A>. <P>
|
|
The expansion of the <A REL=DEFINITION HREF="#defmethod"><B>defmethod</B></A> macro ``refers to'' each specialized parameter (see the description of <A REL=DEFINITION HREF="d_ignore.htm#ignore"><B>ignore</B></A> within the description of <A REL=DEFINITION HREF="s_declar.htm#declare"><B>declare</B></A>). This includes parameters that have an explicit <A REL=DEFINITION HREF="26_glo_p.htm#parameter_specializer_name"><I>parameter specializer name</I></A> of <A REL=DEFINITION HREF="a_t.htm#t"><B>t</B></A>. This means that a compiler warning does not occur if the body of the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> does not refer to a specialized parameter, while a warning might occur if the body of the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> does not refer to an unspecialized parameter. For this reason, a parameter that specializes on <A REL=DEFINITION HREF="a_t.htm#t"><B>t</B></A> is not quite synonymous with an unspecialized parameter in this context. <P>
|
|
Declarations at the head of the method body that apply to the method's <A REL=DEFINITION HREF="26_glo_l.htm#lambda_variable"><I>lambda variables</I></A> are treated as <A REL=DEFINITION HREF="26_glo_b.htm#bound_declaration"><I>bound declarations</I></A> whose <A REL=DEFINITION HREF="26_glo_s.htm#scope"><I>scope</I></A> is the same as the corresponding <A REL=DEFINITION HREF="26_glo_b.htm#binding"><I>bindings</I></A>. <P>
|
|
Declarations at the head of the method body that apply to the functional bindings of <A REL=DEFINITION HREF="f_call_n.htm#call-next-method"><B>call-next-method</B></A> or <A REL=DEFINITION HREF="f_next_m.htm#next-method-p"><B>next-method-p</B></A> apply to references to those functions within the method body <I>forms</I>. Any outer <A REL=DEFINITION HREF="26_glo_b.htm#binding"><I>bindings</I></A> of the <A REL=DEFINITION HREF="26_glo_f.htm#function_name"><I>function names</I></A> <A REL=DEFINITION HREF="f_call_n.htm#call-next-method"><B>call-next-method</B></A> and <A REL=DEFINITION HREF="f_next_m.htm#next-method-p"><B>next-method-p</B></A>, and declarations associated with such <A REL=DEFINITION HREF="26_glo_b.htm#binding"><I>bindings</I></A> are <I>shadowed</I>[2] within the method body <I>forms</I>. <P>
|
|
The <A REL=DEFINITION HREF="26_glo_s.htm#scope"><I>scope</I></A> of <A REL=DEFINITION HREF="26_glo_f.htm#free_declaration"><I>free declarations</I></A> at the head of the method body is the entire method body, which includes any implicit local function definitions but excludes <A REL=DEFINITION HREF="26_glo_i.htm#initialization_form"><I>initialization forms</I></A> for the <A REL=DEFINITION HREF="26_glo_l.htm#lambda_variable"><I>lambda variables</I></A>. <P>
|
|
<A REL=DEFINITION HREF="#defmethod"><B>defmethod</B></A> is not required to perform any compile-time side effects. In particular, the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>methods</I></A> are not installed for invocation during compilation. An <A REL=DEFINITION HREF="26_glo_i.htm#implementation"><I>implementation</I></A> may choose to store information about the <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A> for the purposes of compile-time error-checking (such as checking the number of arguments on calls, or noting that a definition for the function name has been seen). <P>
|
|
<I>Documentation</I> is attached as a <A REL=DEFINITION HREF="26_glo_d.htm#documentation_string"><I>documentation string</I></A> to the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> <A REL=DEFINITION HREF="26_glo_o.htm#object"><I>object</I></A>. <P>
|
|
<P><B>Examples:</B> None.
|
|
<P>
|
|
<P><B>Affected By:</B><P>
|
|
<P>
|
|
The definition of the referenced <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A>. <P>
|
|
<P><B>Exceptional Situations:</B><P>
|
|
<P>
|
|
If <I>function-name</I> names an <A REL=DEFINITION HREF="26_glo_o.htm#ordinary_function"><I>ordinary function</I></A>, a <A REL=DEFINITION HREF="26_glo_m.htm#macro"><I>macro</I></A>, or a <A REL=DEFINITION HREF="26_glo_s.htm#special_operator"><I>special operator</I></A>, an error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_error.htm#error"><B>error</B></A> is signaled. <P>
|
|
If a <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A> is currently named by <I>function-name</I>, the <A REL=DEFINITION HREF="26_glo_l.htm#lambda_list"><I>lambda list</I></A> of the <A REL=DEFINITION HREF="26_glo_m.htm#method"><I>method</I></A> must be congruent with the <A REL=DEFINITION HREF="26_glo_l.htm#lambda_list"><I>lambda list</I></A> of the <A REL=DEFINITION HREF="26_glo_g.htm#generic_function"><I>generic function</I></A>, or an error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_error.htm#error"><B>error</B></A> is signaled. <P>
|
|
<P><B>See Also:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="m_defgen.htm#defgeneric"><B>defgeneric</B></A>, <A REL=DEFINITION HREF="f_docume.htm#documentation"><B>documentation</B></A>, <A REL=CHILD HREF="07_fb.htm">Section 7.6.2 (Introduction to Methods)</A>, <A REL=CHILD HREF="07_fd.htm">Section 7.6.4 (Congruent Lambda-lists for all Methods of a Generic Function)</A>, <A REL=CHILD HREF="07_fc.htm">Section 7.6.3 (Agreement on Parameter Specializers and Qualifiers)</A>, <A REL=CHILD HREF="03_dk.htm">Section 3.4.11 (Syntactic Interaction of Documentation Strings and Declarations)</A> <P>
|
|
<P><B>Notes:</B> None.
|
|
<P>
|
|
<P>
|
|
<P><HR>The following <A REL=META HREF="../Front/X3J13Iss.htm">X3J13 cleanup issues</A>, <I>not part of the specification</I>, apply to this section:<P><UL><LI> <A REL=CHILD HREF="../Issues/iss135.htm">DOCUMENTATION-FUNCTION-BUGS:FIX</A><LI> <A REL=CHILD HREF="../Issues/iss059.htm">COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY</A><LI> <A REL=CHILD HREF="../Issues/iss107.htm">DEFMETHOD-DECLARATION-SCOPE:CORRESPONDS-TO-BINDINGS</A><LI> <A REL=CHILD HREF="../Issues/iss097.htm">DECLS-AND-DOC</A><P></UL><HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|