Issue 2067: Give all of \display{LilyMusic,Music,Scheme} optional port arguments.

diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely
index bad8d261b214cd4e6fc1aff56dafbed1af3b6938..7503306b1fa56f3e8c16b0f6d25b5f5e8d8f28a6 100644 (file)
--- a/Documentation/extending/scheme-tutorial.itely
+++ b/Documentation/extending/scheme-tutorial.itely
@@ -1134,23 +1134,30 @@ will display
 
 By default, LilyPond will print these messages to the console along
 with all the other messages.  To split up these messages and save
 
 By default, LilyPond will print these messages to the console along
 with all the other messages.  To split up these messages and save

-the results of @code{\display@{STUFF@}}, redirect the output to
-a file.
+the results of @code{\display@{STUFF@}}, you can specify an optional
+output port to use:

 
 @example
 
 @example

-lilypond file.ly >display.txt
+@{
+  \displayMusic #(open-output-file "display.txt") @{ c'4\f @}
+@}

 @end example
 
 @end example
 

-With a combined bit of Lilypond and Scheme magic, you can actually
-let Lilypond direct just this output to a file of its own:
-
+This will overwrite a previous output file whenever it is called; if you
+need to write more than one expression, you would use a variable for
+your port and reuse it:

 @example
 @{
 @example
 @{

-  #(with-output-to-file "display.txt"
-      (lambda () #@{ \displayMusic @{ c'4\f @} #@}))
+  port = #(open-output-file "display.txt")
+  \displayMusic \port @{ c'4\f @}
+  \displayMusic \port @{ d'4 @}
+  #(close-output-port port)

 @}
 @end example
 
 @}
 @end example
 

+Guile's manual describes ports in detail.  Closing the port is actually
+only necessary if you need to read the file before Lilypond finishes; in
+the first example, we did not bother to do so.

 
 A bit of reformatting makes the above information easier to read:
 
 
 A bit of reformatting makes the above information easier to read:
 

diff --git a/ly/music-functions-init.ly b/ly/music-functions-init.ly
index 83c2535af58909766ac617bb0aa3733a935cc9c3..7310b8d0ff880e3cc3dec444b7f5281bd21f2cc7 100644 (file)
--- a/ly/music-functions-init.ly
+++ b/ly/music-functions-init.ly
@@ -344,25 +344,30 @@ in a CueVoice oriented by @var{dir}.")
 
 
 displayLilyMusic =
 
 
 displayLilyMusic =

-#(define-music-function (parser location music) (ly:music?)
+#(define-music-function (parser location port music) ((output-port?) ly:music?)

    (_i "Display the LilyPond input representation of @var{music}
    (_i "Display the LilyPond input representation of @var{music}

-to the console.")
-   (newline)
-   (display-lily-music music parser)
+to @var{port}, defaulting to the console.")
+   (let ((port (or port (current-output-port))))
+     (newline port)
+     (display-lily-music music parser port))

    music)
 
 displayMusic =
    music)
 
 displayMusic =

-#(define-music-function (parser location music) (ly:music?)
-   (_i "Display the internal representation of @var{music} to the console.")
-   (newline)
-   (display-scheme-music music)
+#(define-music-function (parser location port music) ((output-port?) ly:music?)
+   (_i "Display the internal representation of @var{music} to
+@var{port}, default to the console.")
+   (let ((port (or port (current-output-port))))
+     (newline port)
+     (display-scheme-music music port))

    music)
 
 displayScheme =
    music)
 
 displayScheme =

-#(define-scheme-function (parser location expr) (scheme?)
-   (_i "Display the internal representation of @var{expr} to the console.")
-   (newline)
-   (display-scheme-music expr)
+#(define-scheme-function (parser location port expr) ((output-port?) scheme?)
+   (_i "Display the internal representation of @var{expr} to
+@var{port}, default to the console.")
+   (let ((port (or port (current-output-port))))
+     (newline port)
+     (display-scheme-music expr port))

    expr)
 
 
    expr)