From 3011960c3ee127d7a252900ad66f96f011e920c0 Mon Sep 17 00:00:00 2001 From: rob durst Date: Mon, 8 Sep 2025 20:02:38 -0600 Subject: [PATCH 1/2] clarify write-to-file and read-from-file documentation --- gui-doc/scribblings/gui/editor-intf.scrbl | 35 +++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/gui-doc/scribblings/gui/editor-intf.scrbl b/gui-doc/scribblings/gui/editor-intf.scrbl index 459e20a8c..ba02eff75 100644 --- a/gui-doc/scribblings/gui/editor-intf.scrbl +++ b/gui-doc/scribblings/gui/editor-intf.scrbl @@ -1970,6 +1970,24 @@ The stream provides either new mappings for names in the editor's when the editor was written to the stream; see also @method[editor<%> write-to-file]). +Leveraging @method[editor<%> read-from-file] to read from the editor stream + requires some ceremony which may not be obvious at first; calls to + @racket[read-editor-global-header] and @racket[read-editor-global-footer] + must bracket any call to @method[editor<%> read-from-file], and only one + stream at a time can be read from using these methods or written to using + @racket[write-editor-global-header] and @racket[write-editor-global-footer]. + +As a complete example consider the following: +@racketblock[ + (define (deserialize-text byte-stream) + (define editor (new text% [auto-wrap #t])) + (define editor-stream-in-bytes-base (make-object editor-stream-in-bytes-base% byte-stream)) + (define editor-stream-in (make-object editor-stream-in% editor-stream-in-bytes-base)) + (read-editor-global-header editor-stream-in) + (send editor read-from-file editor-stream-in) + (read-editor-global-footer editor-stream-in) + editor)] + @itemize[ @item{In the former case, if the @racket[overwrite-styles?] argument @@ -2658,4 +2676,21 @@ If the editor's style list has already been written to the stream, it is not re-written. Instead, the editor content indicates that the editor shares a previously-written style list. This sharing will be recreated when the stream is later read. + +Leveraging @method[editor<%> write-to-file] to write to the editor stream + requires some ceremony which may not be obvious at first; calls to + @racket[write-editor-global-header] and @racket[write-editor-global-footer] + must bracket any call to @method[editor<%> write-to-file], and only one + stream at a time can be written to using these methods or read from using + @racket[read-editor-global-header] and @racket[read-editor-global-footer]. + +As a complete example consider the following: +@racketblock[ + (define (serialize-text text) + (define editor-stream-out-bytes-base (new editor-stream-out-bytes-base%)) + (define editor-stream-out (make-object editor-stream-out% editor-stream-out-bytes-base)) + (write-editor-global-header editor-stream-out) + (send text write-to-file editor-stream-out) + (write-editor-global-footer editor-stream-out) + (send editor-stream-out-bytes-base get-bytes))] }} From 17a97bddf7d9a7b0f239f231466d6ba486a039fd Mon Sep 17 00:00:00 2001 From: rob durst Date: Mon, 8 Sep 2025 20:21:31 -0600 Subject: [PATCH 2/2] fix codeblock indentation --- gui-doc/scribblings/gui/editor-intf.scrbl | 30 +++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/gui-doc/scribblings/gui/editor-intf.scrbl b/gui-doc/scribblings/gui/editor-intf.scrbl index ba02eff75..2fdca31b6 100644 --- a/gui-doc/scribblings/gui/editor-intf.scrbl +++ b/gui-doc/scribblings/gui/editor-intf.scrbl @@ -1979,14 +1979,14 @@ Leveraging @method[editor<%> read-from-file] to read from the editor stream As a complete example consider the following: @racketblock[ - (define (deserialize-text byte-stream) - (define editor (new text% [auto-wrap #t])) - (define editor-stream-in-bytes-base (make-object editor-stream-in-bytes-base% byte-stream)) - (define editor-stream-in (make-object editor-stream-in% editor-stream-in-bytes-base)) - (read-editor-global-header editor-stream-in) - (send editor read-from-file editor-stream-in) - (read-editor-global-footer editor-stream-in) - editor)] +(define (deserialize-text byte-stream) + (define editor (new text% [auto-wrap #t])) + (define editor-stream-in-bytes-base (make-object editor-stream-in-bytes-base% byte-stream)) + (define editor-stream-in (make-object editor-stream-in% editor-stream-in-bytes-base)) + (read-editor-global-header editor-stream-in) + (send editor read-from-file editor-stream-in) + (read-editor-global-footer editor-stream-in) + editor)] @itemize[ @@ -2686,11 +2686,11 @@ Leveraging @method[editor<%> write-to-file] to write to the editor stream As a complete example consider the following: @racketblock[ - (define (serialize-text text) - (define editor-stream-out-bytes-base (new editor-stream-out-bytes-base%)) - (define editor-stream-out (make-object editor-stream-out% editor-stream-out-bytes-base)) - (write-editor-global-header editor-stream-out) - (send text write-to-file editor-stream-out) - (write-editor-global-footer editor-stream-out) - (send editor-stream-out-bytes-base get-bytes))] +(define (serialize-text text) + (define editor-stream-out-bytes-base (new editor-stream-out-bytes-base%)) + (define editor-stream-out (make-object editor-stream-out% editor-stream-out-bytes-base)) + (write-editor-global-header editor-stream-out) + (send text write-to-file editor-stream-out) + (write-editor-global-footer editor-stream-out) + (send editor-stream-out-bytes-base get-bytes))] }}