[Guile-commits] 02/02: doc: Document how (ice-9 format) replaces 'format'.

[Ludovic Courtès]

civodul pushed a commit to branch main
in repository guile.

commit bc3b1a4e2d19cf9fd748297bcecf4f868499fa62
Author: Jean Abou Samra <jean@abou-samra.fr>
AuthorDate: Sat Oct 1 16:14:17 2022 +0200

    doc: Document how (ice-9 format) replaces 'format'.
    
    * doc/ref/misc-modules.texi (Formatted Output): Add paragraph.
    * module/ice-9/format.scm: Add comment.
    
    Co-authored-by: Ludovic Courtès <ludo@gnu.org>
---
 doc/ref/misc-modules.texi | 10 ++++++++++
 module/ice-9/format.scm   |  9 ++++++++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
index 6c899a905..9e99e610c 100644
--- a/doc/ref/misc-modules.texi
+++ b/doc/ref/misc-modules.texi
@@ -1122,6 +1122,16 @@ you try to use one of them.  The reason for two versions 
is that the
 full @code{format} is fairly large and requires some time to load.
 @code{simple-format} is often adequate too.
 
+@quotation Note
+Beware that when @code{(ice-9 format)} is loaded, it replaces the
+binding for @code{format} on the toplevel.  If your module loads
+another module that loads @code{(ice-9 format)}, then your module
+will see the @code{format} function from @code{(ice-9 format)},
+even if it does not itself import @code{(ice-9 format)}.
+
+@emph{This is legacy behavior and may be removed in a future Guile
+version.}
+@end quotation
 
 @node File Tree Walk
 @section File Tree Walk
diff --git a/module/ice-9/format.scm b/module/ice-9/format.scm
index ee7cba910..01da71e90 100644
--- a/module/ice-9/format.scm
+++ b/module/ice-9/format.scm
@@ -32,6 +32,8 @@
 (define-module (ice-9 format)
   #:autoload (ice-9 pretty-print) (pretty-print truncated-print)
   #:autoload (ice-9 i18n)         (%global-locale number->locale-string)
+  ;; Actually replaces the global format as soon as loaded; see the end
+  ;; of this file.
   #:replace (format))
 
 (define format:version "3.0")
@@ -1560,5 +1562,10 @@
           (close-port port)
           str)))))
 
-;; Thanks to Shuji Narazaki
+;; Set the format variable in the root module.  This is legacy and
+;; no longer necessary.  It means that as soon as (ice-9 format) is
+;; loaded somewhere by some module, the predefined binding for format
+;; becomes the extended format function, even in modules where (ice-9 format)
+;; isn't imported.  Because of this, removing this line should be done
+;; when a backwards compatibility break is allowed.
 (module-set! the-root-module 'format format)