From f3a51e126539b398e48ac49805d88d9e49b4f602 Mon Sep 17 00:00:00 2001 From: Chris Hanson Date: Sat, 12 May 2018 21:36:32 -0700 Subject: [PATCH] Update document to reflect new print-method implementation. --- doc/ref-manual/io.texi | 192 +++++++++++++----------------- doc/ref-manual/special-forms.texi | 7 +- 2 files changed, 84 insertions(+), 115 deletions(-) diff --git a/doc/ref-manual/io.texi b/doc/ref-manual/io.texi index 5a0c359a4..7dfdab840 100644 --- a/doc/ref-manual/io.texi +++ b/doc/ref-manual/io.texi @@ -1460,131 +1460,103 @@ the control string are suppressed because each is preceded by a tilde. @node Custom Output, Prompting, Format, Input/Output @section Custom Output -MIT/GNU Scheme provides hooks for specifying that certain kinds of objects -have special written representations. There are no restrictions on the -written representations, but only a few kinds of objects may have custom -representation specified for them, specifically: records -(@pxref{Records}), vectors that have special tags in their zero-th -elements (@pxref{Vectors}), and pairs that have special tags in their -car fields (@pxref{Lists}). There is a different procedure for -specifying the written representation of each of these types. - -@deffn procedure set-record-type-unparser-method! record-type unparser-method -Changes the unparser method of the type represented by @var{record-type} -to be @var{unparser-method}, and returns an unspecified value. -Subsequently, when the unparser encounters a record of this type, it -will invoke @var{unparser-method} to generate the written -representation. -@end deffn - -@deffn procedure unparser/set-tagged-vector-method! tag unparser-method -Changes the unparser method of the vector type represented by @var{tag} -to be @var{unparser-method}, and returns an unspecified value. -Subsequently, when the unparser encounters a vector with @var{tag} as -its zero-th element, it will invoke @var{unparser-method} to generate -the written representation. -@end deffn - -@deffn procedure unparser/set-tagged-pair-method! tag unparser-method -Changes the unparser method of the pair type represented by @var{tag} to -be @var{unparser-method}, and returns an unspecified value. -Subsequently, when the unparser encounters a pair with @var{tag} in its -car field, it will invoke @var{unparser-method} to generate the written -representation. -@end deffn - -@cindex unparser method (defn) -@cindex method, unparser (defn) -An @dfn{unparser method} is a procedure that is invoked with two -arguments: an unparser state and an object. An unparser method -generates a written representation for the object, writing it to the -output port specified by the unparser state. The value yielded by an -unparser method is ignored. Note that an unparser state is not an -output port, rather it is an object that contains an output port as one -of its components. Application programs generally do not construct or -examine unparser state objects, but just pass them along. - -There are two ways to create an unparser method (which is then -registered by one of the above procedures). The first, and easiest, is -to use @code{standard-unparser-method}. The second is to define your -own method using the procedure @code{with-current-unparser-state}. We -encourage the use of the first method, as it results in a more uniform -appearance for objects. Many predefined datatypes, for example -procedures and environments, already have this appearance. - -@deffn procedure standard-unparser-method name procedure -Returns a standard unparser method. @var{Name} may be any object, and -is used as the name of the type with which the unparser method is -associated; @var{name} is usually a symbol. @var{Procedure} must be -@code{#f} or a procedure of two arguments. +MIT/GNU Scheme provides hooks for specifying that specified objects +have special written representations. There are no restrictions on +the written representations. + +@deffn procedure define-print-method predicate print-method +Defines the print method for objects satisfying @var{predicate} to be +@var{print-method}. The @var{predicate} argument must be a unary +procedure that returns true for the objects to print specially, and +@var{print-method} must be a binary procedure that accepts one of +those objects and a textual output port. + +Although @var{print-method} can print the object in any way, we +strongly recomment using one of the following special printers. +@end deffn + +@deffn procedure standard-print-method name [get-parts] +The @var{name} argument may be a unary procedure, a string, or a +symbol; if it is a procedure it is called with the object to be +printed as its argument and should return a string or a symbol. The +@var{get-parts} argument, if provided, must be a unary procedure that +is called with the object to be printed and must return a list of +objects. If @var{get-parts} is not provided, it defaults to a +procedure that returns an empty list. @cindex #[ as external representation -If @var{procedure} is @code{#f}, the returned method generates an -external representation of this form: - +The output generated by this method is in a standard format: @example -#[@var{name} @var{hash}] +#[ @dots{}] @end example - -@noindent -@findex write -@findex write-string -@findex hash -Here @var{name} is the external representation of the argument -@var{name}, as generated by @code{write},@footnote{Except that if the -argument @var{name} is a string, its external representation is -generated by @code{write-string}.} and @var{hash} is the external -representation of an exact non-negative integer unique to the object -being printed (specifically, it is the result of calling @code{hash} on -the object). Subsequently, the expression - +where @code{} is the string or symbol from @var{name} as printed by +@code{display}, @code{} is a unique nonnegative integer generated +by calling @code{hash-object} on the object, and the @code{}s are +the result of calling @var{get-parts} as printed by @code{write} and +separated by spaces. + +One significant advantage of print methods generated by +@code{standard-print-method} is that the parts returned by +@var{get-parts} are examined when searching for circular structure (as +by @code{write}) or shared structure (as by @code{write-shared}). In +effect the printer sees one of these objects as a compound object +containing those parts. +@end deffn + +@deffn procedure bracketed-print-method name printer +The @var{name} argument may be a unary procedure, a string, or a +symbol; if it is a procedure it is called with the object to be +printed as its argument and should return a string or a symbol. The +@var{printer} argument must be a binary procedure, which is called +with the object to print and a textual output port as its arguments. + +Similar to @code{standard-print-method}, this procedure prints an object @example -#@@@var{hash} +#[ ] @end example +where @code{} is the string or symbol from @var{name} as printed by +@code{display}, @code{} is a unique nonnegative integer generated +by calling @code{hash-object} on the object, and @code{} is the +text written by @var{printer}. -@noindent -is notation for an expression evaluating to the object. +This procedure has the benefit of printing objects using the standard +bracketed form, but because its @var{output} is unstructured can not +be examined for sharing or circularity. Generally speaking it's +preferable to use @code{standard-print-method} instead. +@end deffn -If @var{procedure} is supplied, the returned method generates a slightly -different external representation: +The following are deprecated procedures that have been replaced by the +above. +@deffn {obsolete procedure} set-record-type-unparser-method! record-type unparser-method +This procedure is @strong{deprecated}; instead use @example -#[@var{name} @var{hash} @var{output}] +@group +(define-print-method (record-constructor @var{record-type}) + @var{unparser-method}) +@end group @end example +provided that @var{unparser-method} is really a print method. +@end deffn -@noindent -Here @var{name} and @var{hash} are as above, and @var{output} is the -output generated by @var{procedure}. The representation is constructed -in three stages: - -@enumerate -@item -The first part of the format (up to @var{output}) is written to the -output port specified by the unparser state. This is @code{"#["}, -@var{name}, @code{" "}, and @var{hash}. - -@item -@var{Procedure} is invoked on two arguments: the object and an output -port. +@deffn {obsolete procedure} unparser/set-tagged-vector-method! tag unparser-method +@deffnx {obsolete procedure} unparser/set-tagged-pair-method! tag unparser-method +These procedures arg @strong{deprecated}. There is no direct replacement for them. -@item -The closing bracket is written to the output port. -@end enumerate +These were primarily used by @code{define-structure}, which now +generates new-style print methods. If you have other uses of these, +it should be possible to translate them to use +@code{define-print-method} with hand-written predicates. @end deffn -The following procedure is useful for writing more general kinds of -unparser methods. - -@deffn procedure with-current-unparser-state unparser-state procedure -This procedure calls @var{procedure} with one argument, the output port -from @var{unparser-state}. Additionally, it arranges for the remaining -components of @var{unparser-state} to be given to the printer when they -are needed. The @var{procedure} generates some output by writing to the -output port using the usual output operations, and the value yielded by -@var{procedure} is returned from @code{with-current-unparser-state}. +@deffn {obsolete procedure} standard-unparser-method name procedure +This procedure is @strong{deprecated}; it is currently an alias for +@code{bracketed-print-method}. +@end deffn -The port passed to @var{procedure} should only be used within the -dynamic extent of @var{procedure}. +@deffn {obsolete procedure} with-current-unparser-state unparser-state procedure +This procedure is @strong{deprecated}, with no direct replacement. In +general just use @var{procedure} without wrapping it. @end deffn @node Prompting, Textual Port Primitives, Custom Output, Input/Output @@ -1626,7 +1598,7 @@ If @var{environment} is given, it is passed as the second argument to The default behavior of this procedure is to print a fresh line, a newline, and the prompt string; flush the output buffer; then read an object and return it. - +v Under Edwin and Emacs, before the object is read, the interaction buffer is put into a mode that allows expressions to be edited and submitted for input using specific editor commands. The first expression that is diff --git a/doc/ref-manual/special-forms.texi b/doc/ref-manual/special-forms.texi index 14eb883c6..baec78340 100644 --- a/doc/ref-manual/special-forms.texi +++ b/doc/ref-manual/special-forms.texi @@ -1401,11 +1401,8 @@ defined with that symbol as its name. @deffn {structure option} print-procedure expression Evaluating @var{expression} must yield a procedure of two arguments, -which is used to print instances of the structure. The procedure is an -@dfn{unparser method} (@pxref{Custom Output}). If the structure -instances are records, this option has the same effect as calling -@code{set-record-type-unparser-method!}. -@findex set-record-type-unparser-method! +which is used to print instances of the structure. The procedure is a +@dfn{print method} (@pxref{Custom Output}). @end deffn @deffn {structure option} constructor [name [argument-list]] -- 2.25.1