[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
documentation and regression test for #{ ... #}
From: |
Nicolas Sceaux |
Subject: |
documentation and regression test for #{ ... #} |
Date: |
Sat, 19 Jun 2004 14:27:06 +0200 |
User-agent: |
Gnus/5.1006 (Gnus v5.10.6) Emacs/21.3 (gnu/linux) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- documentation and regression test for #{ ... #},
Nicolas Sceaux <=