176 lines
12 KiB
HTML
176 lines
12 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: Issue DESCRIBE-UNDERSPECIFIED Writeup</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="../Issues/iss127_w.htm">
|
|
<LINK REL=UP HREF="../Issues/iss128.htm">
|
|
<LINK REL=NEXT HREF="../Issues/iss129_w.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="../Issues/iss127_w.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="../Issues/iss128.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="../Issues/iss129_w.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
<H2>Issue DESCRIBE-UNDERSPECIFIED Writeup</H2>
|
|
|
|
<PRE><B>Status:</B> Passed, as amended, Mar 89 X3J13<P>
|
|
<B>Forum:</B> Cleanup<P>
|
|
<B>Issue:</B> <A HREF="iss128.htm">DESCRIBE-UNDERSPECIFIED</A><P>
|
|
<B>References:</B> CLtL p441-2<P>
|
|
88-002R, <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> function<P>
|
|
<B>Category:</B> CHANGE, ADDITION<P>
|
|
<B>Edit history:</B> Version 1, 10-Mar-89, Kim A. Barrett<P>
|
|
Version 2, 9-Apr-89, Masinter (as per Mar 89 X3J13)<P>
|
|
<P>
|
|
<B>Problem description:<P>
|
|
</B><P>
|
|
The CLOS Specification (X3J13 Document 88-002R) changes the definition of the<P>
|
|
function <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A>, making it a generic function. However, it does not specify<P>
|
|
any of the protocol needed to make user-defined methods interact properly to<P>
|
|
produce some of the effects mentioned in CLtL. For example, CLtL says that<P>
|
|
sometimes the <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> for describing an object will involve describing<P>
|
|
something that it finds inside the object, and that such recursive<P>
|
|
descriptions are indented appropriately. How do user-written methods achieve<P>
|
|
this indentation? Must they arrange for the indentation explicitly, or is<P>
|
|
there some automatic mechanism that handles it?<P>
|
|
<P>
|
|
The new specification does not easily lend itself to certain kinds of features<P>
|
|
which some implementations have included in their versions of <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A>, such<P>
|
|
as analogues to the printer's depth limits (*PRINT-DEPTH*) and circular<P>
|
|
<A REL=DEFINITION HREF="../Body/f_docume.htm#structure"><B>structure</B></A> detection during recursion (<A REL=DEFINITION HREF="../Body/v_pr_cir.htm#STprint-circleST"><B>*PRINT-CIRCLE*</B></A>).<P>
|
|
<P>
|
|
In addition, <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> does not take a stream argument, instead always doing<P>
|
|
output to <A REL=DEFINITION HREF="../Body/v_debug_.htm#STstandard-outputST"><B>*STANDARD-OUTPUT*</B></A>. This means that a program which wants to use<P>
|
|
<A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> to output some information to a particular stream must rebind<P>
|
|
<A REL=DEFINITION HREF="../Body/v_debug_.htm#STstandard-outputST"><B>*STANDARD-OUTPUT*</B></A> around the call to <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A>. This is a nuisance, and is<P>
|
|
also potentially a bad idea in implementations which have interrupts and such.<P>
|
|
<P>
|
|
<B>Proposal DESCRIBE-UNDERSPECIFIED:DESCRIBE-OBJECT:<P>
|
|
</B><P>
|
|
Remove the section of 88-002R which specifies that <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> is a generic<P>
|
|
function. Modify <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> to accept an optional second stream argument, which<P>
|
|
defaults to <A REL=DEFINITION HREF="../Body/v_debug_.htm#STstandard-outputST"><B>*STANDARD-OUTPUT*</B></A>, and which is handled in the same way as the<P>
|
|
stream argument to <A REL=DEFINITION HREF="../Body/f_wr_pr.htm#print"><B>PRINT</B></A> (that is, permitting arguments of <A REL=DEFINITION HREF="../Body/a_nil.htm#nil"><B>NIL</B></A> and T).<P>
|
|
The value of this argument is the stream which output will be directed to. <P>
|
|
Specify that <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> is implemented in terms of the generic function<P>
|
|
<A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A>, described below.<P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> object stream [Generic Function]<P>
|
|
<P>
|
|
The generic function <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> writes a description of an object to a<P>
|
|
stream. The function <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> is called by the <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> function; it<P>
|
|
should not be called by the user.<P>
|
|
<P>
|
|
Each implementation is required to <A REL=DEFINITION HREF="../Body/f_provid.htm#provide"><B>provide</B></A> a <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> on the <A REL=DEFINITION HREF="../Body/t_class.htm#class"><B>class</B></A><P>
|
|
<A REL=DEFINITION HREF="../Body/t_std_ob.htm#standard-object"><B>STANDARD-OBJECT</B></A> and methods on enough other classes so as to ensure that<P>
|
|
there is always an applicable <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A>. Implementations are free to add<P>
|
|
methods for other classes. Users can write methods for <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> for<P>
|
|
their own classes if they do not wish to inherit an implementation-supplied<P>
|
|
<A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A>.<P>
|
|
<P>
|
|
ARGUMENTS:<P>
|
|
<P>
|
|
The first argument is any Lisp object. The second argument is a stream; it<P>
|
|
cannot be T or <A REL=DEFINITION HREF="../Body/a_nil.htm#nil"><B>NIL</B></A>.<P>
|
|
<P>
|
|
VALUES:<P>
|
|
<P>
|
|
The values returned by <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> are unspecified.<P>
|
|
<P>
|
|
REMARKS:<P>
|
|
<P>
|
|
Methods on <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> may recursively call <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A>. Indentation,<P>
|
|
depth limits, and circularity detection are all taken care of automatically,<P>
|
|
provided that each <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> handles exactly one level of <A REL=DEFINITION HREF="../Body/f_docume.htm#structure"><B>structure</B></A> and calls<P>
|
|
<A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> recursively if there are more structural levels.<P>
|
|
<P>
|
|
If this rule is not obeyed, the results are undefined.<P>
|
|
<P>
|
|
In some implementations the stream argument passed to a <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A><P>
|
|
<A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> is not the original stream, but is an intermediate stream that<P>
|
|
implements parts of <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A>. Methods should therefore not depend on the<P>
|
|
identity of this stream.<P>
|
|
<P>
|
|
<B>Rationale:<P>
|
|
</B><P>
|
|
This proposal was closely modeled on the CLOS description of <A REL=DEFINITION HREF="../Body/f_pr_obj.htm#print-object"><B>PRINT-OBJECT</B></A>,<P>
|
|
which was well thought out and provides a great deal of functionality and<P>
|
|
implementation freedom. The same implementation techniques applicable to<P>
|
|
<A REL=DEFINITION HREF="../Body/f_pr_obj.htm#print-object"><B>PRINT-OBJECT</B></A> will be applicable to <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A>.<P>
|
|
<P>
|
|
The reason for making the return values for <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> unspecified is to<P>
|
|
avoid forcing users to include explicit (<A REL=DEFINITION HREF="../Body/a_values.htm#values"><B>VALUES</B></A>) in all their methods.<P>
|
|
<A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> will take care of that.<P>
|
|
<P>
|
|
<B>Current practice:<P>
|
|
</B><P>
|
|
Probably nobody does precisely what this proposal suggests.<P>
|
|
<P>
|
|
<B>Cost to Implementors:<P>
|
|
</B><P>
|
|
A fair amount of work may be required, since every method/subfunction of<P>
|
|
<A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> in an implementation may need at least some fixing to be in line with<P>
|
|
this proposal. On the other hand, that work may already be needed in order to<P>
|
|
conform to 88-002R, and this proposal may make the conversion easier by<P>
|
|
simplifying the translation of an existing implementation of <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A>.<P>
|
|
<P>
|
|
<B>Cost to Users:<P>
|
|
</B><P>
|
|
Any users who are using an implementation which supports the current CLOS<P>
|
|
specification of <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> and have defined their own methods will have to<P>
|
|
change them. CLOS is sufficiently recent that this probably isn't a big<P>
|
|
problem.<P>
|
|
<P>
|
|
Those users who have made use of implementation-specific hooks into <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A><P>
|
|
to define their own methods will likely have to change, but that was already<P>
|
|
the case.<P>
|
|
<P>
|
|
Users who are currently binding <A REL=DEFINITION HREF="../Body/v_debug_.htm#STstandard-outputST"><B>*STANDARD-OUTPUT*</B></A> around calls to <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> may<P>
|
|
wish to change their code.<P>
|
|
<P>
|
|
<B>Cost of non-adoption:<P>
|
|
</B><P>
|
|
Portable <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> methods may be difficult to write because the protocol they<P>
|
|
must follow is insufficiently specified.<P>
|
|
<P>
|
|
<B>Benefits:<P>
|
|
</B><P>
|
|
The constraints on <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> methods are better specified, making it easier to<P>
|
|
write such methods properly.<P>
|
|
<P>
|
|
<B>Aesthetics:<P>
|
|
</B><P>
|
|
Minimal.<P>
|
|
<P>
|
|
<B>Discussion:<P>
|
|
</B><P>
|
|
An additional change which is not included in the present proposal would be to<P>
|
|
make the syntax of <A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> and <A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> be<P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="../Body/f_descri.htm#describe"><B>DESCRIBE</B></A> object &optional stream &key<P>
|
|
<A REL=DEFINITION HREF="../Body/f_desc_1.htm#describe-object"><B>DESCRIBE-OBJECT</B></A> object stream &key<P>
|
|
<P>
|
|
allowing implementation-specific extensions to the arguments. A possible<P>
|
|
<A REL=DEFINITION HREF="../Body/07_ffb.htm#standard"><B>standard</B></A> keyword argument is :VERBOSE, which might be used to specify how much<P>
|
|
output to produce.<P>
|
|
<P>
|
|
It might be desirable to define some new describe control variables analogous<P>
|
|
to the printer control variables, ie. *DESCRIBE-LEVEL* and *DESCRIBE-CIRCLE*,<P>
|
|
and possibly *DESCRIBE-LENGTH*.<P>
|
|
-------<P>
|
|
</PRE>
|
|
<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>
|