documentation and regression test for #{ ... #}

[Nicolas Sceaux]

hi

Here are a piece of documentation for #{ ... #} syntax, a
regression test for it, and a patch for ly-from-scheme.scm.
Is the doc OK? May I commit it?

Index: Documentation/user/programming-interface.itely
===================================================================
RCS file: 
/cvsroot/lilypond/lilypond/Documentation/user/programming-interface.itely,v
retrieving revision 1.10
diff -u -r1.10 programming-interface.itely
--- Documentation/user/programming-interface.itely      18 Jun 2004 15:11:59 
-0000      1.10
+++ Documentation/user/programming-interface.itely      19 Jun 2004 12:19:30 
-0000
@@ -17,7 +17,8 @@
 * Input variables and Scheme::  
 * Internal music representation::  
 * Extending music syntax::      
-* Manipulating music expressions::  
+* Manipulating music expressions:: 
+* Using LilyPond syntax inside Scheme::   
 @end menu
 
 @node Input variables and Scheme
@@ -189,14 +190,25 @@
 @code{\applymusic} is selected by defining
 
 @example
-  apply = #(ly:make-music-function
-   (list procedure? ly:music?)
-   (lambda (where func music)
-     (func music)))
+  applymusic = #(ly:make-music-function
+                  (list procedure? ly:music?)
+                  (lambda (location func music)
+                    (func music)))
address@hidden example
+
+A @code{def-music-function} macro is introduced on top of
address@hidden:make-music-function} to ease the definition of music
+functions:
+
address@hidden
+  applymusic = #(def-music-function (location func music) (procedure? 
ly:music?)
+                  (func music))
 @end example
 
 Examples of the use of @code{\applymusic} are in the next section.
 
address@hidden
address@hidden/music-functions-init.ly}.
 
 @node Manipulating music expressions
 @appendixsubsec Manipulating music expressions
@@ -290,6 +302,112 @@
 @inputfileref{input/test,music-box.ly}.
 
 
address@hidden Using LilyPond syntax inside Scheme
address@hidden Using LilyPond syntax inside Scheme
+
+Creating music expressions in scheme can be tedious, as they are
+heavily nested and the resulting scheme code is large. For some
+simple tasks, this can be avoided, using LilyPond usual syntax inside
+scheme, with the dedicated @address@hidden ... address@hidden syntax.
+
+The following two expressions give equivalent music expressions:
address@hidden
+  mynotes = @{ \override Stem #'thickness = #4
+              \notes @{ c'8 d' @} @}
+  
+  #(define mynotes address@hidden \override Stem #'thickness = #4
+                      \notes @{ c'8 d' @} address@hidden)
address@hidden example
+
+The content of @address@hidden ... address@hidden is enclosed in an implicit 
@address@hidden
+... @}} block, which is parsed. The resulting music expression, a
address@hidden music object, is then returned and usable in scheme.
+
+Arbitrary scheme forms, including variables, can be used in @address@hidden 
... address@hidden
+expressions with the @code{$} character (@code{$$} can be used to
+produce a single $ character). This makes the creation of simple
+functions straightforward. In the following example, a function
+setting the TextScript's padding is defined:
+
address@hidden,raggedright]
+  #(use-modules (ice-9 optargs))
+  #(define* (textpad padding #:optional once?)
+    (ly:export   ; this is necessary for using the expression
+                 ; directly inside a \notes block
+      (if once?
+          #{ \once \override TextScript #'padding = #$padding #}
+          #{ \override TextScript #'padding = #$padding #})))
+  
+  \score {
+      \notes {
+          c'^"1"
+          #(textpad 3.0 #t) % only once
+          c'^"2"
+          c'^"3"
+          #(textpad 5.0)
+          c'^"4"
+          c'^"5"
+          
+      }
+  }
address@hidden lilypond
+
+Here, the variable @code{padding} is a number; music expression
+variables may also be used in a similar fashion, as in the following
+example:
+
address@hidden,raggedright]
+  #(define (with-padding padding)
+     (lambda (music)
+       #{ \override TextScript #'padding = #$padding
+          $music
+          \revert TextScript #'padding #}))
+  
+  \score {
+      \notes {
+          c'^"1"
+          \applymusic #(with-padding 3)
+            { c'^"2" c'^"3"}
+          c'^"4"
+      }
+  }
address@hidden lilypond
+
+The function created by @code{(with-padding 3)} adds @code{\override} and
address@hidden statements around the music given as an argument, and returns
+this new expression. Thus, this example is equivalent to:
+
address@hidden
+  \score @{
+      \notes @{
+          c'^"1"
+          @{ \override TextScript #'padding = #3
+            @{ c'^"2" c'^"3"@}
+            \revert TextScript #'padding
+          @}
+          c'^"4"
+      @}
+  @}
address@hidden example
+
+This function may also be defined as a music function:
+
address@hidden,raggedright]
+  withPadding = #(def-music-function (location padding music) (number? 
ly:music?)
+                   #{ \override TextScript #'padding = #$padding
+                      $music 
+                      \revert TextScript #'padding #})
+  
+  \score {
+      \notes {
+          c'^"1"
+          \withPadding #3
+            { c'^"2" c'^"3"}
+          c'^"4"
+      }
+  }
address@hidden lilypond
+
 
 @node Markup programmer interface
 @appendixsec Markup programmer interface
Index: scm/ly-from-scheme.scm
===================================================================
RCS file: /cvsroot/lilypond/lilypond/scm/ly-from-scheme.scm,v
retrieving revision 1.3
diff -u -r1.3 ly-from-scheme.scm
--- scm/ly-from-scheme.scm      14 May 2004 08:46:53 -0000      1.3
+++ scm/ly-from-scheme.scm      19 Jun 2004 12:19:52 -0000
@@ -70,7 +70,10 @@
                              (display (read-char port) out))  ;; pop the 
second $
                             ;; a #scheme expression
                             ((char=? c #\#)
-                             (format out "#~a" (remove-dollars! (read port))))
+                             (let ((expr (read port)))
+                               (format out "#~a" (if (eq? '$ expr)
+                                                     (create-binding! (read 
port))
+                                                     (remove-dollars! expr)))))
                             ;; other caracters
                             (else
                              (display c out))))))))

---------------- lily-in-scheme.ly ---------------
\header {
    texidoc = "LilyPond syntax can be used inside scheme to
build music expressions, with the @address@hidden ... address@hidden syntax.
Scheme forms can be introduced inside these blocks by escaping 
them with a @code{$}, both in a LilyPond context (see the @code{$music} 
variable) or in a Scheme 
context (see the @code{$padding} and @code{$(* padding 2)} forms.)"
}
\version "2.3.4"
\paper { raggedright = ##t }

withPaddingA = #(def-music-function (location padding music) (number? ly:music?)
                   #{ \override TextScript #'padding = #$padding
                      $music 
                      \revert TextScript #'padding #})
  
withPaddingB = #(def-music-function (location padding music) (number? ly:music?)
                   #{ \override TextScript #'padding = #$(* padding 2)
                      $music 
                      \revert TextScript #'padding #})
  
withPaddingC = #(def-music-function (location padding music) (number? ly:music?)
                   #{ \override TextScript #'padding = #(+ 1 $(* padding 2))
                      $music 
                      \revert TextScript #'padding #})
  
  \score {
      \notes {
          c'^"1"
          \withPaddingA #2
            { c'^"2" c'^"3"}
          c'^"4"
          \withPaddingB #2
            { c'^"5" c'^"6"}
          c'^"7"
          \withPaddingC #2
            { c'^"8" c'^"9"}
          c'^"10"
      }
  }
---------------- lily-in-scheme.ly ---------------

I apologize for not submitting that earlier.

nicolas