From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#66267: Document cl-print.el in the CL manual. Date: Mon, 9 Oct 2023 17:41:04 +0000 Message-ID: References: <83fs2wyl5p.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="9348"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 66267@debbugs.gnu.org, Stefan Monnier To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Oct 09 19:42:09 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qpuGb-00021j-Pg for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 09 Oct 2023 19:42:05 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qpuGG-0006Gw-Ng; Mon, 09 Oct 2023 13:41:45 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qpuGE-0006GI-Ad for bug-gnu-emacs@gnu.org; Mon, 09 Oct 2023 13:41:42 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qpuGD-000724-Cw for bug-gnu-emacs@gnu.org; Mon, 09 Oct 2023 13:41:41 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qpuGY-0000R9-2J for bug-gnu-emacs@gnu.org; Mon, 09 Oct 2023 13:42:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 09 Oct 2023 17:42:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66267 X-GNU-PR-Package: emacs Original-Received: via spool by 66267-submit@debbugs.gnu.org id=B66267.16968732981642 (code B ref 66267); Mon, 09 Oct 2023 17:42:02 +0000 Original-Received: (at 66267) by debbugs.gnu.org; 9 Oct 2023 17:41:38 +0000 Original-Received: from localhost ([127.0.0.1]:33086 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qpuG9-0000QQ-IF for submit@debbugs.gnu.org; Mon, 09 Oct 2023 13:41:38 -0400 Original-Received: from mail.muc.de ([193.149.48.3]:58343) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qpuG4-0000Q5-4q for 66267@debbugs.gnu.org; Mon, 09 Oct 2023 13:41:36 -0400 Original-Received: (qmail 97679 invoked by uid 3782); 9 Oct 2023 19:41:05 +0200 Original-Received: from acm.muc.de (pd953a1c9.dip0.t-ipconnect.de [217.83.161.201]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 09 Oct 2023 19:41:04 +0200 Original-Received: (qmail 12496 invoked by uid 1000); 9 Oct 2023 17:41:04 -0000 Content-Disposition: inline In-Reply-To: <83fs2wyl5p.fsf@gnu.org> X-Submission-Agent: TMDA/1.3.x (Ph3nix) X-Primary-Address: acm@muc.de X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:272158 Archived-At: Hello, Eli and Stefan. On Fri, Sep 29, 2023 at 19:54:58 +0300, Eli Zaretskii wrote: > > Date: Fri, 29 Sep 2023 16:40:24 +0000 > > From: Alan Mackenzie > > cl-print.el isn't documented in the cl manual at all. This needs doing. > I think just a short description should be fine, given that it wasn't > documented at all. AFAICT, it has just 2 methods. Hah! I found a bit more to document than that. My first draught of a new "Printing" chapter is below. Review and criticism will be welcome. diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 5de33350f4f..20227679c67 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -258,6 +258,159 @@ Naming Conventions @noindent [3] Only for one sequence argument or two list arguments. +@node Printing +@chapter Printing + +@noindent +This chapter describes some enhancements to Emacs Lisp's +@dfn{printing}, the action of representing Lisp objects in text form. +The functions documented here are intended to produce output more for +human readers than the standard printing functions such as +@code{prin1} and @code{princ} (@pxref{Output Functions,,,elisp,GNU +Emacs Lisp Reference Manual}). + +Several of these functions have a parameter @var{stream}; this +specifies what to do with the characters printing produces. For +example, it might be a buffer, a marker, @code{nil} (meaning use +standard output), or @code{t} (use the echo area). @xref{Output +Streams,,,elisp,GNU Emacs Lisp Reference Manual} for a full +description. + +@defvar cl-print-readably +When this variable is non-@code{nil}, @code{cl-prin1} and other +functions described here try to produce output which can later be read +by the Lisp reader (@pxref{Input Functions,,,elisp,GNU Emacs Lisp +Reference Manual}). +@end defvar + +@defvar cl-print-compiled +This variable controls how to print byte-compiled functions. Valid +values are: +@itemize @bullet +@item +@code{nil}, the default: Just an internal hex identifier is printed. +@item +The symbol @code{static}: The internal hex identifier together with +the function's constant vector are printed. +@item +The symbol @code{disassemble}: The byte code gets disassembled. +@item +The symbol @code{raw}: The raw form of the function is printed by +@code{prin1}. +@end itemize +Sometimes, a button is set on the output to allow you to disassemble +the function. See @code{cl-print-compile-button}. +@end defvar + +@defvar cl-print-compile-button +When this variable is non-@code{nil} and a byte-compiled function has +been printed to a buffer, you can click with the mouse or type +@key{RET} on that output to disassemble the code. This doesn't apply +when @code{cl-print-compiled} is set to @code{disassemble}. +@end defvar + +@defvar cl-print-string-length +The maximum length of a string to print before abbreviating it. A +value of @code{nil} means no limit. + +When the CL printing functions abbreviate a string, they print the +first @code{cl-print-string-length} characters of the string, followed +by @samp{...}. When the printing is to a buffer, you can click with +the mouse or type @key{RET} on this ellipsis to expand the string. + +This variable has effect only in the `cl-prin*' functions, not in +primitives such as `prin1'. +@end defvar + +@defun cl-prin1 object &option stream +Print @var{object} on @var{stream} (see above) according to its type +and the settings described above. The variables @code{print-length} +and @code{print-level} and the other standard Emacs settings also +affect the printing (@pxref{Output Variables,,,elisp,GNU Emacs Lisp +Reference Manual}). +@end defun + +@defun cl-prin1-to-string object +This function is like @code{cl-prin1}, except the output characters +are returned as a string from this function rather than being passed +to a stream. +@end defun + +@defun cl-print-to-string-with-limit print-function value limit +Return a string containing a printed representation of @var{value}. +Attempt to get the length of the returned string under @var{limit} +characters with successively more restrictive settings of +@code{print-level}, @code{print-length}, and +@code{cl-print-string-length}. Use @var{print-function} to print, +which should take the arguments @var{value} and @var{stream} and which +should respect @code{print-length}, @code{print-level}, and +@code{cl-print-string-length}. @var{limit} may be @code{nil} or zero +in which case @var{print-function} will be called with these settings +bound to @code{nil}, and it can also be @code{t} in which case +@var{print-function} will be called with their current values. + +Use this function with @code{cl-prin1} to print an object, +abbreviating it with ellipses to fit within a size limit. +@end defun + +@defun cl-print-object object stream +Print OBJECT on STREAM (see above). This function is actually a +@code{cl-defgeneric} which is defined for several types of +@var{object} +@c (@pxref{cl-defgeneric}) This macro is currently not documented, +@c but certainly ought to be. ACM, 2023-10-08. +. Normally, you just call @code{cl-prin1} to print an @var{object} +rather than calling this function directly. + +You can write @code{cl-print-object} @code{cl-defmethod}s for other +types of @var{object}, thus extending @code{cl-prin1}. If you write +such a method which uses ellipses, you should also write a +@code{cl-print-object-contents} method for the same type. For +examples of these methods, see @file{emacs-lisp/cl-print.el} in the +Emacs source directory. +@end defun + +@defun cl-print-object-contents object start stream +Replace an ellipsis in @var{stream} beginning at @var{start} with the +text from the partially printed @var{object} it represents. This +function is also a @code{cl-defgeneric} defined for several types of +@var{object}. @var{stream} is a buffer containing the text with the +ellipsis. @var{start} specifies the starting position of the ellipsis +in a manner dependent on the type; it will have been obtained from a +text property on the ellipsis, having been put there by +@code{cl-print-insert-ellipsis}. +@end defun + +@defun cl-print-insert-ellipsis object start stream +Print an ellipsis (@samp{...}) to @var{stream} (see above). When +@var{stream} is a buffer, the ellipsis will be given the +@code{cl-print-ellipsis} text property. The value of the text +property will contain state (including @var{start}) in order to print +the elided part of OBJECT later. START should be nil if the whole +OBJECT is being elided, otherwise it should be an index or other +pointer into the internals of OBJECT which can be passed to +`cl-print-object-contents' at a later time. +@end defun + +@defvar cl-print-expand-ellipsis-function +This variable holds a function which expands an ellipsis in the +current buffer. The function takes four arguments: @var{begin} and +@var{end}, which are the bounds of the ellipsis; @var{value}, which is +the value of the @code{cl-print-ellipsis} text property on the +ellipsis (typically set earlier by @code{cl-prin1}); and +@var{line-length}, the desired maximum length of the output. Its +return value is the buffer position after the expanded text. +@end defvar + +@defun cl-print-expand-ellipsis &optional button +This command expands the ellipsis at point. Non-interactively, if +@var{button} is supplied, it should be either a buffer position or a +button made by @code{cl-print-insert-ellipsis} +(@pxref{Buttons,,,elisp,GNU Emacs Lisp Reference Manual}), which +indicates the position of the ellipsis. The return value is the +buffer position after the expanded text. +@end defun + @node Program Structure @chapter Program Structure -- Alan Mackenzie (Nuremberg, Germany).