]> git.donarmstrong.com Git - lilypond.git/blob - ly/music-functions-init.ly
Issue 4985: Avoid a few trivial lambda function wrappers
[lilypond.git] / ly / music-functions-init.ly
1 %%%% -*- Mode: Scheme -*-
2
3 %%%% This file is part of LilyPond, the GNU music typesetter.
4 %%%%
5 %%%% Copyright (C) 2003--2015 Han-Wen Nienhuys <hanwen@xs4all.nl>
6 %%%%                          Jan Nieuwenhuizen <janneke@gnu.org>
7 %%%%
8 %%%% LilyPond is free software: you can redistribute it and/or modify
9 %%%% it under the terms of the GNU General Public License as published by
10 %%%% the Free Software Foundation, either version 3 of the License, or
11 %%%% (at your option) any later version.
12 %%%%
13 %%%% LilyPond is distributed in the hope that it will be useful,
14 %%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
15 %%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 %%%% GNU General Public License for more details.
17 %%%%
18 %%%% You should have received a copy of the GNU General Public License
19 %%%% along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.
20
21 \version "2.19.25"
22
23
24 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
25 %% this file is alphabetically sorted.
26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
27
28 %% need SRFI-1 for filter; optargs for lambda*
29 #(use-modules (srfi srfi-1)
30               (ice-9 optargs))
31
32 absolute =
33 #(define-music-function (music)
34    (ly:music?)
35    (_i "Make @var{music} absolute.  This does not actually change the
36 music itself but rather hides it from surrounding @code{\\relative}
37 and @code{\\fixed} commands.")
38    (make-music 'RelativeOctaveMusic 'element music))
39
40 acciaccatura =
41 #(def-grace-function startAcciaccaturaMusic stopAcciaccaturaMusic
42    (_i "Create an acciaccatura from the following music expression"))
43
44 %% keep these two together
45 instrument-definitions = #'()
46 addInstrumentDefinition =
47 #(define-void-function
48    (name lst) (string? list?)
49    (_i "Create instrument @var{name} with properties @var{list}.")
50    (set! instrument-definitions (acons name lst instrument-definitions)))
51
52 addQuote =
53 #(define-void-function (name music) (string? ly:music?)
54    (_i "Define @var{music} as a quotable music expression named
55 @var{name}")
56    (add-quotable name music))
57
58 %% keep these two together
59 afterGraceFraction = 3/4
60 afterGrace =
61 #(define-music-function (fraction main grace) ((fraction?) ly:music? ly:music?)
62    (_i "Create @var{grace} note(s) after a @var{main} music expression.
63
64 The musical position of the grace expression is after a
65 given fraction of the main note's duration has passed.  If
66 @var{fraction} is not specified as first argument, it is taken from
67 @code{afterGraceFraction} which has a default value of @code{3/4}.")
68    (let ((main-length (ly:music-length main))
69          (fraction (or fraction (ly:parser-lookup 'afterGraceFraction))))
70      (make-simultaneous-music
71       (list
72        main
73        (make-sequential-music
74         (list
75
76          (make-music 'SkipMusic
77                      'duration (ly:make-duration
78                                 0 0
79                                 (* (ly:moment-main main-length)
80                                    (/ (car fraction) (cdr fraction)))))
81          (make-music 'GraceMusic
82                      'element grace)))))))
83
84
85 %% music identifiers not allowed at top-level,
86 %% so this is a music-function instead.
87 allowPageTurn =
88 #(define-music-function () ()
89    (_i "Allow a page turn. May be used at toplevel (ie between scores or
90 markups), or inside a score.")
91    (make-music 'EventChord
92                'page-marker #t
93                'page-turn-permission 'allow
94                'elements (list (make-music 'PageTurnEvent
95                                            'break-permission 'allow))))
96
97 alterBroken =
98 #(define-music-function (property arg item)
99   (key-list-or-symbol? list? key-list-or-music?)
100   (_i "Override @var{property} for pieces of broken spanner @var{item}
101 with values @var{arg}.  @var{item} may either be music in the form of
102 a starting spanner event, or a symbol list in the form
103 @samp{Context.Grob} or just @samp{Grob}.  Iff @var{item} is in the
104 form of a spanner event, @var{property} may also have the form
105 @samp{Grob.property} for specifying a directed tweak.")
106   (if (ly:music? item)
107       (if (eq? (ly:music-property item 'span-direction) START)
108           (tweak property (value-for-spanner-piece arg) item)
109           (begin
110             (ly:music-warning item (_ "not a spanner"))
111             item))
112       (let* ((p (check-grob-path item (*location*)
113                                  #:default 'Bottom
114                                  #:min 2
115                                  #:max 2))
116              (name (and p (second p)))
117              (description
118               (and name (assoc-get name all-grob-descriptions))))
119         (if (and description
120                  (member 'spanner-interface
121                          (assoc-get 'interfaces
122                                     (assoc-get 'meta description))))
123             (propertyOverride (append item (if (symbol? property)
124                                        (list property)
125                                        property))
126                       (value-for-spanner-piece arg))
127             (begin
128               (ly:input-warning (*location*) (_ "not a spanner name, `~a'") name)
129               (make-music 'Music))))))
130
131 appendToTag =
132 #(define-music-function (tag more music)
133    (symbol? ly:music? ly:music?)
134    (_i "Append @var{more} to the @code{elements} of all music
135 expressions in @var{music} that are tagged with @var{tag}.")
136    (music-map (lambda (m)
137                 (if (memq tag (ly:music-property m 'tags))
138                     (set! (ly:music-property m 'elements)
139                           (append (ly:music-property m 'elements)
140                                   (list more))))
141                 m)
142               music))
143
144 applyContext =
145 #(define-music-function (proc) (procedure?)
146    (_i "Modify context properties with Scheme procedure @var{proc}.")
147    (make-music 'ApplyContext
148                'procedure proc))
149
150 applyMusic =
151 #(define-music-function (func music) (procedure? ly:music?)
152    (_i"Apply procedure @var{func} to @var{music}.")
153    (func music))
154
155 applyOutput =
156 #(define-music-function (target proc) (symbol-list-or-symbol? procedure?)
157    (_i "Apply function @code{proc} to every layout object matched by
158 @var{target} which takes the form @code{Context} or @code{Context.Grob}.")
159    (let ((p (check-grob-path target (*location*) #:max 2)))
160      (if p
161          (make-music 'ApplyOutputEvent
162                      'procedure proc
163                      'context-type (car p)
164                      (if (pair? (cdr p))
165                          (list (cons 'symbol (cadr p)))
166                          '()))
167          (make-music 'Music))))
168
169 appoggiatura =
170 #(def-grace-function startAppoggiaturaMusic stopAppoggiaturaMusic
171    (_i "Create an appoggiatura from @var{music}"))
172
173 % for regression testing purposes.
174 assertBeamQuant =
175 #(define-music-function (l r) (pair? pair?)
176    (_i "Testing function: check whether the beam quants @var{l} and @var{r} are correct")
177    (make-grob-property-override 'Beam 'positions (check-quant-callbacks l r)))
178
179 % for regression testing purposes.
180 assertBeamSlope =
181 #(define-music-function (comp) (procedure?)
182    (_i "Testing function: check whether the slope of the beam is the same as @code{comp}")
183    (make-grob-property-override 'Beam 'positions (check-slope-callbacks comp)))
184
185 autochange =
186 #(define-music-function (pitch clef-1 clef-2 music)
187   ((ly:pitch? (ly:make-pitch 0 0)) (ly:context-mod?)(ly:context-mod?) ly:music?)
188   (_i "Make voices that switch between staves automatically.  As an option the
189 pitch where to switch staves may be specified.  The clefs for the staves are
190 optional as well.  Setting clefs  works only for implicitly instantiated
191 staves.")
192   (let ;; keep the contexts alive for the full duration
193        ((skip (make-duration-of-length (ly:music-length music)))
194         (clef-1 (or clef-1 #{ \with { \clef "treble" } #}))
195         (clef-2 (or clef-2 #{ \with { \clef "bass" } #})))
196     (make-simultaneous-music
197      (list
198       (descend-to-context (make-autochange-music pitch music) 'Staff
199                           "up" clef-1)
200       (context-spec-music (make-skip-music skip) 'Staff
201                           "up" clef-1)
202       (context-spec-music (make-skip-music skip) 'Staff
203                           "down" clef-2)))))
204
205 balloonGrobText =
206 #(define-music-function (grob-name offset text)
207    (symbol? number-pair? markup?)
208    (_i "Attach @var{text} to @var{grob-name} at offset @var{offset}
209  (use like @code{\\once})")
210    (make-event-chord
211     (list
212      (make-music 'AnnotateOutputEvent
213                  'symbol grob-name
214                  'X-offset (car offset)
215                  'Y-offset (cdr offset)
216                  'text text))))
217
218 balloonText =
219 #(define-event-function (offset text) (number-pair? markup?)
220    (_i "Attach @var{text} at @var{offset} (use like @code{\\tweak})")
221    (make-music 'AnnotateOutputEvent
222                'X-offset (car offset)
223                'Y-offset (cdr offset)
224                'text text))
225
226 bar =
227 #(define-music-function (type) (string?)
228    (_i "Insert a bar line of type @var{type}")
229    (context-spec-music
230     (make-property-set 'whichBar type)
231     'Timing))
232
233 barNumberCheck =
234 #(define-music-function (n) (integer?)
235    (_i "Print a warning if the current bar number is not @var{n}.")
236    (make-music 'ApplyContext
237                'procedure
238                (lambda (c)
239                  (let ((cbn (ly:context-property c 'currentBarNumber)))
240                    (if (and  (number? cbn) (not (= cbn n)))
241                        (ly:input-warning (*location*)
242                                          "Barcheck failed got ~a expect ~a"
243                                          cbn n))))))
244
245 beamExceptions =
246 #(define-scheme-function (music) (ly:music?)
247    (_i "Extract a value suitable for setting
248 @code{Timing.beamExceptions} from the given pattern with explicit
249 beams in @var{music}.  A bar check @code{|} has to be used between
250 bars of patterns in order to reset the timing.")
251    (extract-beam-exceptions music))
252
253 bendAfter =
254 #(define-event-function (delta) (real?)
255    (_i "Create a fall or doit of pitch interval @var{delta}.")
256    (make-music 'BendAfterEvent
257                'delta-step delta))
258
259 bookOutputName =
260 #(define-void-function (newfilename) (string?)
261    (_i "Direct output for the current book block to @var{newfilename}.")
262    (set! (paper-variable #f 'output-filename) newfilename))
263
264 bookOutputSuffix =
265 #(define-void-function (newsuffix) (string?)
266    (_i "Set the output filename suffix for the current book block to
267 @var{newsuffix}.")
268    (set! (paper-variable #f 'output-suffix) newsuffix))
269
270 %% \breathe is defined as a music function rather than an event identifier to
271 %% ensure it gets useful input location information: as an event identifier,
272 %% it would have to be wrapped in an EventChord to prevent it from being
273 %% treated as a post_event by the parser
274 breathe =
275 #(define-music-function () ()
276    (_i "Insert a breath mark.")
277    (make-music 'BreathingEvent))
278
279 clef =
280 #(define-music-function (type) (string?)
281    (_i "Set the current clef to @var{type}.")
282    (make-clef-set type))
283
284
285 compoundMeter =
286 #(define-music-function (args) (pair?)
287   (_i "Create compound time signatures. The argument is a Scheme list of
288 lists. Each list describes one fraction, with the last entry being the
289 denominator, while the first entries describe the summands in the
290 enumerator. If the time signature consists of just one fraction,
291 the list can be given directly, i.e. not as a list containing a single list.
292 For example, a time signature of (3+1)/8 + 2/4 would be created as
293 @code{\\compoundMeter #'((3 1 8) (2 4))}, and a time signature of (3+2)/8
294 as @code{\\compoundMeter #'((3 2 8))} or shorter
295 @code{\\compoundMeter #'(3 2 8)}.")
296   (let* ((mlen (calculate-compound-measure-length args))
297          (beat (calculate-compound-base-beat args))
298          (beatGrouping (calculate-compound-beat-grouping args))
299          (timesig (cons (ly:moment-main-numerator mlen)
300                         (ly:moment-main-denominator mlen))))
301   #{
302     \once \override Timing.TimeSignature.stencil = #(lambda (grob)
303       (grob-interpret-markup grob (make-compound-meter-markup args)))
304     \set Timing.timeSignatureFraction = #timesig
305     \set Timing.baseMoment = #beat
306     \set Timing.beatStructure = #beatGrouping
307     \set Timing.beamExceptions = #'()
308     \set Timing.measureLength = #mlen
309   #} ))
310
311 compressMMRests =
312 #(define-music-function (music) (ly:music?)
313   (_i "Remove the empty bars created by multi-measure rests,
314 leaving just the first bar containing the MM rest itself.")
315    (music-map
316     (lambda (m)
317       (if (eq? 'MultiMeasureRestMusic (ly:music-property m 'name))
318           #{ \once \set Score.skipBars = ##t #m #}
319           #{ #m #} ))
320     music))
321
322 crossStaff =
323 #(define-music-function (notes) (ly:music?)
324   (_i "Create cross-staff stems")
325   #{
326   \temporary \override Stem.cross-staff = #cross-staff-connect
327   \temporary \override Flag.style = #'no-flag
328   #notes
329   \revert Stem.cross-staff
330   \revert Flag.style
331 #})
332
333 cueClef =
334 #(define-music-function (type) (string?)
335   (_i "Set the current cue clef to @var{type}.")
336   (make-cue-clef-set type))
337
338 cueClefUnset =
339 #(define-music-function () ()
340   (_i "Unset the current cue clef.")
341   (make-cue-clef-unset))
342
343 cueDuring =
344 #(define-music-function
345    (what dir main-music) (string? ly:dir? ly:music?)
346    (_i "Insert contents of quote @var{what} corresponding to @var{main-music},
347 in a CueVoice oriented by @var{dir}.")
348    (make-music 'QuoteMusic
349                'element main-music
350                'quoted-context-type 'CueVoice
351                'quoted-context-id "cue"
352                'quoted-music-name what
353                'quoted-voice-direction dir))
354
355 cueDuringWithClef =
356 #(define-music-function
357    (what dir clef main-music) (string? ly:dir? string? ly:music?)
358    (_i "Insert contents of quote @var{what} corresponding to @var{main-music},
359 in a CueVoice oriented by @var{dir}.")
360    (make-music 'QuoteMusic
361                'element main-music
362                'quoted-context-type 'CueVoice
363                'quoted-context-id "cue"
364                'quoted-music-name what
365                'quoted-music-clef clef
366                'quoted-voice-direction dir))
367
368
369
370 displayLilyMusic =
371 #(define-music-function (port music) ((output-port?) ly:music?)
372    (_i "Display the LilyPond input representation of @var{music}
373 to @var{port}, defaulting to the console.")
374    (let ((port (or port (current-output-port))))
375      (newline port)
376      (display-lily-music music port))
377    music)
378
379 displayMusic =
380 #(define-music-function (port music) ((output-port?) ly:music?)
381    (_i "Display the internal representation of @var{music} to
382 @var{port}, default to the console.")
383    (let ((port (or port (current-output-port))))
384      (newline port)
385      (display-scheme-music music port))
386    music)
387
388 displayScheme =
389 #(define-scheme-function (port expr) ((output-port?) scheme?)
390    (_i "Display the internal representation of @var{expr} to
391 @var{port}, default to the console.")
392    (let ((port (or port (current-output-port))))
393      (newline port)
394      (display-scheme-music expr port))
395    expr)
396
397
398
399 endSpanners =
400 #(define-music-function (music) (ly:music?)
401    (_i "Terminate the next spanner prematurely after exactly one note
402 without the need of a specific end spanner.")
403    (let* ((start-span-evs (filter (lambda (ev)
404                                     (equal? (ly:music-property ev 'span-direction)
405                                             START))
406                                   (extract-typed-music music 'span-event)))
407           (stop-span-evs
408            (map (lambda (m)
409                   (music-clone m 'span-direction STOP))
410                 start-span-evs))
411           (end-ev-chord (make-music 'EventChord
412                                     'elements stop-span-evs))
413           (total (make-music 'SequentialMusic
414                              'elements (list music
415                                              end-ev-chord))))
416      total))
417
418 eventChords =
419 #(define-music-function (music) (ly:music?)
420    (_i "Compatibility function wrapping @code{EventChord} around
421 isolated rhythmic events occuring since version 2.15.28, after
422 expanding repeat chords @samp{q}.")
423    (event-chord-wrap! music))
424
425 featherDurations=
426 #(define-music-function (factor argument) (ly:moment? ly:music?)
427    (_i "Adjust durations of music in @var{argument} by rational @var{factor}.")
428    (let ((orig-duration (ly:music-length argument))
429          (multiplier (ly:make-moment 1 1)))
430
431      (for-each
432       (lambda (mus)
433         (if (< 0 (ly:moment-main-denominator (ly:music-length mus)))
434             (begin
435               (ly:music-compress mus multiplier)
436               (set! multiplier (ly:moment-mul factor multiplier)))))
437       (extract-named-music argument '(EventChord NoteEvent RestEvent SkipEvent)))
438      (ly:music-compress
439       argument
440       (ly:moment-div orig-duration (ly:music-length argument)))
441
442      argument))
443
444 finger =
445 #(define-event-function (finger) (number-or-markup?)
446    (_i "Apply @var{finger} as a fingering indication.")
447
448    (make-music
449             'FingeringEvent
450             (if (number? finger) 'digit 'text)
451             finger))
452
453 fixed =
454 #(define-music-function (pitch music)
455    (ly:pitch? ly:music?)
456    (_i "Use the octave of @var{pitch} as the default octave for @var{music}.")
457    (let ((octave-marks (1+ (ly:pitch-octave pitch))))
458      (cond ((not (= 0 octave-marks))
459             (ly:music-transpose music (ly:make-pitch octave-marks 0 0))
460             ;;In order to leave unchanged the notes in any enclosed
461             ;; \absolute or \fixed or \relative, make a cancelling shift
462             (map (lambda (m)
463                    (ly:music-transpose m (ly:make-pitch (- octave-marks) 0 0)))
464                  (extract-named-music music 'RelativeOctaveMusic)))))
465    (make-music 'RelativeOctaveMusic 'element music))
466
467 footnote =
468 #(define-music-function (mark offset footnote item)
469    ((markup?) number-pair? markup? symbol-list-or-music?)
470    (_i "Make the markup @var{footnote} a footnote on @var{item}.  The
471 footnote is marked with a markup @var{mark} moved by @var{offset} with
472 respect to the marked music.
473
474 If @var{mark} is not given or specified as @var{\\default}, it is
475 replaced by an automatically generated sequence number.  If @var{item}
476 is a symbol list of form @samp{Grob} or @samp{Context.Grob}, then
477 grobs of that type will be marked at the current time step in the
478 given context (default @code{Bottom}).
479
480 If @var{item} is music, the music will get a footnote attached to a
481 grob immediately attached to the event, like @var{\\tweak} does.  For
482 attaching a footnote to an @emph{indirectly} caused grob, write
483 @code{\\single\\footnote}, use @var{item} to specify the grob, and
484 follow it with the music to annotate.
485
486 Like with @code{\\tweak}, if you use a footnote on a following
487 post-event, the @code{\\footnote} command itself needs to be attached
488 to the preceding note or rest as a post-event with @code{-}.")
489    (let ((mus (make-music
490                'FootnoteEvent
491                'X-offset (car offset)
492                'Y-offset (cdr offset)
493                'automatically-numbered (not mark)
494                'text (or mark (make-null-markup))
495                'footnote-text footnote)))
496      (once (propertyTweak 'footnote-music mus item))))
497
498 grace =
499 #(def-grace-function startGraceMusic stopGraceMusic
500    (_i "Insert @var{music} as grace notes."))
501
502 grobdescriptions =
503 #(define-scheme-function (descriptions) (list?)
504    (_i "Create a context modification from @var{descriptions}, a list
505 in the format of @code{all-grob-descriptions}.")
506    (ly:make-context-mod
507     (map (lambda (p)
508            (list 'assign (car p) (ly:make-grob-properties (cdr p))))
509          descriptions)))
510
511 harmonicByFret = #(define-music-function (fret music) (number? ly:music?)
512   (_i "Convert @var{music} into mixed harmonics; the resulting notes resemble
513 harmonics played on a fretted instrument by touching the strings at @var{fret}.")
514   #{
515     \set harmonicDots = ##t
516     \temporary \override TabNoteHead.stencil = #(tab-note-head::print-custom-fret-label (number->string fret))
517     \temporary \override NoteHead.Y-extent = #grob::always-Y-extent-from-stencil
518     \temporary \override NoteHead.stencil = #(lambda (grob) (ly:grob-set-property! grob 'style 'harmonic-mixed)
519                                             (ly:note-head::print grob))
520     #(make-harmonic
521        (calc-harmonic-pitch (fret->pitch (number->string fret)) music))
522     \unset harmonicDots
523     \revert TabNoteHead.stencil
524     \revert NoteHead.Y-extent
525     \revert NoteHead.stencil
526   #})
527
528 harmonicByRatio = #(define-music-function (ratio music) (number? ly:music?)
529     (_i "Convert @var{music} into mixed harmonics; the resulting notes resemble
530 harmonics played on a fretted instrument by touching the strings at the point
531 given through @var{ratio}.")
532   #{
533     \set harmonicDots = ##t
534     \temporary \override TabNoteHead.stencil = #(tab-note-head::print-custom-fret-label (ratio->fret ratio))
535     \temporary \override NoteHead.Y-extent = #(ly:make-unpure-pure-container ly:grob::stencil-height)
536     \temporary \override NoteHead.stencil = #(lambda (grob) (ly:grob-set-property! grob 'style 'harmonic-mixed)
537                                             (ly:note-head::print grob))
538     #(make-harmonic
539       (calc-harmonic-pitch (ratio->pitch ratio) music))
540     \unset harmonicDots
541     \revert TabNoteHead.stencil
542     \revert NoteHead.Y-extent
543     \revert NoteHead.stencil
544   #})
545
546 hide =
547 #(define-music-function (item) (symbol-list-or-music?)
548    (_i "Set @var{item}'s @samp{transparent} property to @code{#t},
549 making it invisible while still retaining its dimensions.
550
551 If @var{item} is a symbol list of form @code{GrobName} or
552 @code{Context.GrobName}, the result is an override for the grob name
553 specified by it.  If @var{item} is a music expression, the result is
554 the same music expression with an appropriate tweak applied to it.")
555    (propertyTweak 'transparent #t item))
556
557 inStaffSegno =
558 #(define-music-function () ()
559    (_i "Put the segno variant 'varsegno' at this position into the staff,
560 compatible with the repeat command.")
561    (make-music 'ApplyContext
562                'procedure
563                (lambda (ctx)
564                  (let ((score-ctx (ly:context-find ctx 'Score)))
565                    (if (ly:context? score-ctx)
566                      (let ((old-rc (ly:context-property score-ctx 'repeatCommands '())))
567                        (if (eq? (memq 'segno-display old-rc) #f)
568                          (ly:context-set-property! score-ctx 'repeatCommands (cons 'segno-display old-rc)))))))))
569
570 instrumentSwitch =
571 #(define-music-function
572    (name) (string?)
573    (_i "Switch instrument to @var{name}, which must be predefined with
574 @code{\\addInstrumentDefinition}.")
575    (let* ((handle (assoc name instrument-definitions))
576           (instrument-def (if handle (cdr handle) '())))
577
578      (if (not handle)
579          (ly:input-warning (*location*) "No such instrument: ~a" name))
580      (context-spec-music
581       (make-music 'SimultaneousMusic
582                   'elements
583                   (map (lambda (kv)
584                          (make-property-set
585                           (car kv)
586                           (cdr kv)))
587                        instrument-def))
588       'Staff)))
589
590
591
592 keepWithTag =
593 #(define-music-function (tags music)
594    (symbol-list-or-symbol? ly:music?)
595    (_i "Include only elements of @var{music} that are tagged with one
596 of the tags in @var{tags}.  @var{tags} may be either a single symbol
597 or a list of symbols.
598
599 Each tag may be declared as a member of at most one tag group (defined
600 with @code{\\tagGroup}).  If none of a @var{music} element's tags
601 share a tag group with one of the specified @var{tags}, the element is
602 retained.")
603    (music-filter
604     (tags-keep-predicate tags)
605     music))
606
607 key =
608 #(define-music-function (tonic pitch-alist)
609    ((ly:pitch? '()) (list? '()))
610    (_i "Set key to @var{tonic} and scale @var{pitch-alist}.
611 If both are null, just generate @code{KeyChangeEvent}.")
612    (cond ((null? tonic) (make-music 'KeyChangeEvent))
613          ((null? pitch-alist)
614           (ly:parser-error (_ "second argument must be pitch list")
615                            (*location*))
616           (make-music 'SequentialMusic 'void #t))
617          (else
618           (ly:music-transpose
619            (make-music 'KeyChangeEvent
620                 'tonic (ly:make-pitch 0 0 0)
621                 'pitch-alist pitch-alist)
622            tonic))))
623
624 killCues =
625 #(define-music-function (music) (ly:music?)
626    (_i "Remove cue notes from @var{music}.")
627    (music-map
628     (lambda (mus)
629       (if (and (string? (ly:music-property mus 'quoted-music-name))
630                (string=? (ly:music-property mus 'quoted-context-id "") "cue"))
631           (ly:music-property mus 'element)
632           mus))
633     music))
634
635
636
637 label =
638 #(define-music-function (label) (symbol?)
639    (_i "Create @var{label} as a bookmarking label.")
640    (make-music 'EventChord
641                'page-marker #t
642                'page-label label
643                'elements (list (make-music 'LabelEvent
644                                            'page-label label))))
645
646
647 language =
648 #(define-void-function (language) (string?)
649    (_i "Set note names for language @var{language}.")
650    (note-names-language language))
651
652 languageSaveAndChange =
653 #(define-void-function (language) (string?)
654   (_i "Store the previous pitchnames alist, and set a new one.")
655   (set! previous-pitchnames pitchnames)
656   (note-names-language language))
657
658 languageRestore =
659 #(define-void-function () ()
660    (_i "Restore a previously-saved pitchnames alist.")
661    (if previous-pitchnames
662        (begin
663         (set! pitchnames previous-pitchnames)
664         (ly:parser-set-note-names pitchnames))
665       (ly:input-warning (*location*) (_ "No other language was defined previously. Ignoring."))))
666
667
668 magnifyMusic =
669 #(define-music-function (mag music) (positive? ly:music?)
670    (_i "Magnify the notation of @var{music} without changing the
671 staff-size, using @var{mag} as a size factor.  Stems, beams,
672 slurs, ties, and horizontal spacing are adjusted automatically.")
673
674    ;; these props are NOT allowed to shrink below default size
675    (define unshrinkable-props
676      '(
677        ;; stems
678        (Stem thickness)
679
680        ;; slurs
681        (Slur line-thickness)
682        (Slur thickness)
683        (PhrasingSlur line-thickness)
684        (PhrasingSlur thickness)
685
686        ;; ties
687        (Tie line-thickness)
688        (Tie thickness)
689        (LaissezVibrerTie line-thickness)
690        (LaissezVibrerTie thickness)
691        (RepeatTie line-thickness)
692        (RepeatTie thickness)
693        ))
694
695    ;; these props ARE allowed to shrink below default size
696    (define shrinkable-props
697      (let ((baseline-skip-props
698              (find-named-props 'baseline-skip all-grob-descriptions))
699            (word-space-props
700              (find-named-props 'word-space all-grob-descriptions)))
701        (append
702          baseline-skip-props
703          word-space-props
704          '(
705            ;; TODO: uncomment spacing-increment here once Issue 3987 is fixed
706            ;; override at the 'Score level
707            ;(SpacingSpanner spacing-increment)
708
709            ;; lengths and heights
710            (Beam length-fraction)
711            (Stem length-fraction)
712            (Stem beamlet-default-length)
713            (Stem double-stem-separation)
714            (Slur height-limit)
715            (Slur minimum-length)
716            (PhrasingSlur height-limit)
717            (PhrasingSlur minimum-length)
718
719            ;; Beam.beam-thickness is dealt with separately below
720            ))))
721    #{
722      \context Bottom {
723        %% TODO: uncomment \newSpacingSection once Issue 3990 is fixed
724        %\newSpacingSection
725        #(scale-fontSize 'magnifyMusic mag)
726        #(scale-props    'magnifyMusic mag #f unshrinkable-props)
727        #(scale-props    'magnifyMusic mag #t shrinkable-props)
728        #(scale-beam-thickness mag)
729
730        #music
731
732        %% TODO: uncomment \newSpacingSection once Issue 3990 is fixed
733        %\newSpacingSection
734        %% reverse engineer the former fontSize value instead of using \unset
735        #(revert-fontSize 'magnifyMusic mag)
736        #(revert-props    'magnifyMusic mag (append unshrinkable-props
737                                                    shrinkable-props
738                                                    '((Beam beam-thickness))))
739      }
740    #})
741
742 magnifyStaff =
743 #(define-music-function (mag) (positive?)
744    (_i "Change the size of the staff, adjusting notation size and
745 horizontal spacing automatically, using @var{mag} as a size factor.")
746
747    ;; these props are NOT allowed to shrink below default size
748    (define unshrinkable-props
749      '((StaffSymbol thickness)))
750
751    ;; these props ARE allowed to shrink below default size
752    (define shrinkable-props
753      (let* ((baseline-skip-props
754               (find-named-props 'baseline-skip all-grob-descriptions))
755             (word-space-props
756               (find-named-props 'word-space all-grob-descriptions))
757             (space-alist-props
758               (find-named-props 'space-alist all-grob-descriptions)))
759        (append
760          baseline-skip-props
761          word-space-props
762          space-alist-props
763          '(
764            ;; override at the 'Score level
765            (SpacingSpanner spacing-increment)
766
767            (StaffSymbol staff-space)
768            (BarLine kern)
769            (BarLine segno-kern)
770            (BarLine hair-thickness)
771            (BarLine thick-thickness)
772            (Stem beamlet-default-length)
773            (Stem double-stem-separation)
774            ))))
775
776    #{
777      \stopStaff
778
779      %% revert settings from last time
780      %% (but only if \magnifyStaff has already been used
781      %% and the staff magnification is changing)
782      #(revert-fontSize 'magnifyStaff mag)
783      #(revert-props    'magnifyStaff mag (append unshrinkable-props
784                                                  shrinkable-props))
785
786      %% scale settings
787      %% (but only if staff magnification is changing
788      %% and does not equal 1)
789      #(scale-fontSize 'magnifyStaff mag)
790      #(scale-props    'magnifyStaff mag #f unshrinkable-props)
791      #(scale-props    'magnifyStaff mag #t shrinkable-props)
792
793      %% this might cause problems until Issue 3990 is fixed
794      \newSpacingSection
795
796      \startStaff
797      \set Staff.magnifyStaffValue = #mag
798    #})
799
800 makeClusters =
801 #(define-music-function (arg) (ly:music?)
802    (_i "Display chords in @var{arg} as clusters.")
803    (music-map note-to-cluster arg))
804
805 modalInversion =
806 #(define-music-function (around to scale music)
807     (ly:pitch? ly:pitch? ly:music? ly:music?)
808     (_i "Invert @var{music} about @var{around} using @var{scale} and
809 transpose from @var{around} to @var{to}.")
810     (let ((inverter (make-modal-inverter around to scale)))
811       (change-pitches music inverter)
812       music))
813
814 modalTranspose =
815 #(define-music-function (from to scale music)
816     (ly:pitch? ly:pitch? ly:music? ly:music?)
817     (_i "Transpose @var{music} from pitch @var{from} to pitch @var{to}
818 using @var{scale}.")
819     (let ((transposer (make-modal-transposer from to scale)))
820       (change-pitches music transposer)
821       music))
822
823 inversion =
824 #(define-music-function
825    (around to music) (ly:pitch? ly:pitch? ly:music?)
826    (_i "Invert @var{music} about @var{around} and
827 transpose from @var{around} to @var{to}.")
828    (music-invert around to music))
829
830 mark =
831 #(define-music-function
832    (label) ((number-or-markup?))
833   "Make the music for the \\mark command."
834   (let* ((set (and (integer? label)
835                    (context-spec-music (make-property-set 'rehearsalMark label)
836                                       'Score)))
837          (ev (make-music 'MarkEvent
838                          'origin (*location*))))
839
840     (if set
841         (make-sequential-music (list set ev))
842         (begin
843           (if label (set! (ly:music-property ev 'label) label))
844           ev))))
845
846 markupMap =
847 #(define-music-function (path markupfun music)
848    (symbol-list-or-symbol? markup-function? ly:music?)
849    (_i "This applies the given markup function @var{markupfun} to all markup
850 music properties matching @var{path} in @var{music}.
851
852 For example,
853 @example
854 \\new Voice @{ g'2 c'' @}
855 \\addlyrics @{
856   \\markupMap LyricEvent.text
857              \\markup \\with-color #red \\etc
858              @{ Oh yes! @}
859 @}
860 @end example
861 ")
862    (let* ((p (check-music-path path (*location*)))
863           (name (and p (car p)))
864           (prop (and p (cadr p))))
865      (if p
866          (for-some-music
867           (lambda (m)
868             (if (or (not name) (eq? (ly:music-property m 'name) name))
869                 (let ((text (ly:music-property m prop)))
870                   (if (markup? text)
871                       (set! (ly:music-property m prop)
872                             (list markupfun text)))))
873             #f)
874           music)))
875    music)
876
877 musicMap =
878 #(define-music-function (proc mus) (procedure? ly:music?)
879    (_i "Apply @var{proc} to @var{mus} and all of the music it contains.")
880    (music-map proc mus))
881
882 %% noPageBreak and noPageTurn are music functions (not music indentifiers),
883 %% because music identifiers are not allowed at top-level.
884 noPageBreak =
885 #(define-music-function () ()
886    (_i "Forbid a page break.  May be used at toplevel (i.e., between scores or
887 markups), or inside a score.")
888    (make-music 'EventChord
889                'page-marker #t
890                'page-break-permission 'forbid
891                'elements (list (make-music 'PageBreakEvent
892                                            'break-permission '()))))
893
894 noPageTurn =
895 #(define-music-function () ()
896    (_i "Forbid a page turn.  May be used at toplevel (i.e., between scores or
897 markups), or inside a score.")
898    (make-music 'EventChord
899                'page-marker #t
900                'page-turn-permission 'forbid
901                'elements (list (make-music 'PageTurnEvent
902                                            'break-permission '()))))
903
904
905
906 octaveCheck =
907 #(define-music-function (pitch) (ly:pitch?)
908    (_i "Octave check.")
909    (make-music 'RelativeOctaveCheck
910                'pitch pitch))
911
912 offset =
913 #(define-music-function (property offsets item)
914   (symbol-list-or-symbol? scheme? key-list-or-music?)
915    (_i "Offset the default value of @var{property} of @var{item} by
916 @var{offsets}.  If @var{item} is a string, the result is
917 @code{\\override} for the specified grob type.  If @var{item} is
918 a music expression, the result is the same music expression with an
919 appropriate tweak applied.")
920   (if (ly:music? item)
921       ; In case of a tweak, grob property path is Grob.property
922       (let ((prop-path (check-grob-path
923                          (if (symbol? property)
924                              (list property)
925                              property) (*location*)
926                          #:start 1 #:default #t #:min 2 #:max 2)))
927         (if prop-path
928             ; If the head of the grob property path is a symbol--i.e.,
929             ; a grob name, produce a directed tweak.  Otherwise, create
930             ; an ordinary tweak.
931             (if (symbol? (car prop-path))
932                 (tweak prop-path (offsetter (second prop-path) offsets) item)
933                 (tweak (second prop-path)
934                        (offsetter (second prop-path) offsets)
935                        item))
936             item))
937       ; In case of an override, grob property path is Context.Grob.property.
938       (let ((prop-path (check-grob-path
939                          (append item
940                                  (if (symbol? property)
941                                      (list property)
942                                      property)) (*location*)
943                          #:default 'Bottom #:min 3 #:max 3)))
944         (if prop-path
945             (propertyOverride prop-path (offsetter (third prop-path) offsets))
946             (make-music 'Music)))))
947
948 omit =
949 #(define-music-function (item) (symbol-list-or-music?)
950    (_i "Set @var{item}'s @samp{stencil} property to @code{#f},
951 effectively omitting it without taking up space.
952
953 If @var{item} is a symbol list of form @code{GrobName} or
954 @code{Context.GrobName}, the result is an override for the grob name
955 specified by it.  If @var{item} is a music expression, the result is
956 the same music expression with an appropriate tweak applied to it.")
957    (propertyTweak 'stencil #f item))
958
959 once =
960 #(define-music-function (music) (ly:music?)
961    (_i "Set @code{once} to @code{#t} on all layout instruction events
962 in @var{music}.  This will complain about music with an actual
963 duration.  As a special exception, if @var{music} contains
964 @samp{tweaks} it will be silently ignored in order to allow for
965 @code{\\once \\propertyTweak} to work as both one-time override and proper
966 tweak.")
967    (if (not (pair? (ly:music-property music 'tweaks)))
968        (for-some-music
969         (lambda (m)
970           (cond ((music-is-of-type? m 'layout-instruction-event)
971                  (set! (ly:music-property m 'once) #t)
972                  #t)
973                 ((ly:duration? (ly:music-property m 'duration))
974                  (ly:music-warning m (_ "Cannot apply \\once to timed music"))
975                  #t)
976                 (else #f)))
977         music))
978    music)
979
980 ottava =
981 #(define-music-function (octave) (integer?)
982    (_i "Set the octavation.")
983    (make-music 'OttavaMusic
984                'ottava-number octave))
985
986 overrideTimeSignatureSettings =
987 #(define-music-function
988    (time-signature base-moment beat-structure beam-exceptions)
989    (fraction? fraction? list? list?)
990
991    (_i "Override @code{timeSignatureSettings}
992 for time signatures of @var{time-signature} to have settings
993 of @var{base-moment}, @var{beat-structure}, and @var{beam-exceptions}.")
994
995    ;; TODO -- add warning if largest value of grouping is
996    ;;       greater than time-signature.
997   (let ((setting (make-setting base-moment beat-structure beam-exceptions)))
998     (override-time-signature-setting time-signature setting)))
999
1000 overrideProperty =
1001 #(define-music-function (grob-property-path value)
1002    (key-list? scheme?)
1003
1004    (_i "Set the grob property specified by @var{grob-property-path} to
1005 @var{value}.  @var{grob-property-path} is a symbol list of the form
1006 @code{Context.GrobName.property} or @code{GrobName.property}, possibly
1007 with subproperties given as well.
1008
1009 As opposed to @code{\\override} which overrides the context-dependent
1010 defaults with which a grob is created, this command uses
1011 @code{Output_property_engraver} at the grob acknowledge stage.  This
1012 may be necessary for overriding values set after the initial grob
1013 creation.")
1014    (let ((p (check-grob-path grob-property-path (*location*)
1015                              #:default 'Bottom
1016                              #:min 3)))
1017      (if p
1018          (make-music 'ApplyOutputEvent
1019                      'context-type (first p)
1020                      'symbol (second p)
1021                      'procedure
1022                      (lambda (grob orig-context context)
1023                        (ly:grob-set-nested-property! grob (cddr p) value)))
1024          (make-music 'Music))))
1025
1026
1027
1028
1029
1030
1031 %% pageBreak and pageTurn are music functions (iso music indentifiers),
1032 %% because music identifiers are not allowed at top-level.
1033 pageBreak =
1034 #(define-music-function () ()
1035    (_i "Force a page break.  May be used at toplevel (i.e., between scores or
1036 markups), or inside a score.")
1037    (make-music 'EventChord
1038                'page-marker #t
1039                'line-break-permission 'force
1040                'page-break-permission 'force
1041                'elements (list (make-music 'LineBreakEvent
1042                                            'break-permission 'force)
1043                                (make-music 'PageBreakEvent
1044                                            'break-permission 'force))))
1045
1046 pageTurn =
1047 #(define-music-function () ()
1048    (_i "Force a page turn between two scores or top-level markups.")
1049    (make-music 'EventChord
1050                'page-marker #t
1051                'line-break-permission 'force
1052                'page-break-permission 'force
1053                'page-turn-permission 'force
1054                'elements (list (make-music 'LineBreakEvent
1055                                            'break-permission 'force)
1056                                (make-music 'PageBreakEvent
1057                                            'break-permission 'force)
1058                                (make-music 'PageTurnEvent
1059                                            'break-permission 'force))))
1060
1061 parallelMusic =
1062 #(define-void-function (voice-ids music) (list? ly:music?)
1063    (_i "Define parallel music sequences, separated by '|' (bar check signs),
1064 and assign them to the identifiers provided in @var{voice-ids}.
1065
1066 @var{voice-ids}: a list of music identifiers (symbols containing only letters)
1067
1068 @var{music}: a music sequence, containing BarChecks as limiting expressions.
1069
1070 Example:
1071
1072 @verbatim
1073   \\parallelMusic #'(A B C) {
1074     c c | d d | e e |
1075     d d | e e | f f |
1076   }
1077 <==>
1078   A = { c c | d d }
1079   B = { d d | e e }
1080   C = { e e | f f }
1081 @end verbatim
1082
1083 The last bar checks in a sequence are not copied to the result in
1084 order to facilitate ending the last entry at non-bar boundaries.
1085 ")
1086    (define voice-count (length voice-ids))
1087    (define (bar-check? m)
1088      "Checks whether m is a bar check."
1089      (eq? (ly:music-property m 'name) 'BarCheck))
1090    (define (recurse-and-split-list lst)
1091      "Return either a list of music lists split along barchecks, or @code{#f}."
1092      (if (any bar-check? lst)
1093          (let* ((voices (apply circular-list (make-list voice-count '())))
1094                 (current-voices voices)
1095                 (current-sequence '()))
1096            ;;
1097            ;; utilities
1098            (define (push-music m)
1099              "Push the music expression into the current sequence"
1100              (set! current-sequence (cons m current-sequence)))
1101            (define (change-voice)
1102              "Store the previously built sequence into the current voice and
1103 change to the following voice."
1104              (set-car! current-voices
1105                        (cons current-sequence
1106                              (car current-voices)))
1107              (set! current-sequence '())
1108              (set! current-voices (cdr current-voices)))
1109            (for-each (lambda (m)
1110                        (let ((split? (recurse-and-split m)))
1111                          (if split?
1112                              (for-each
1113                               (lambda (m)
1114                                 (push-music m)
1115                                 (change-voice))
1116                               split?)
1117                              (begin
1118                                (push-music m)
1119                                (if (bar-check? m) (change-voice))))))
1120                      lst)
1121            (if (pair? current-sequence) (change-voice))
1122            ;; Un-circularize voices
1123            (set! voices (list-head voices voice-count))
1124
1125            ;; Remove trailing bar checks to facilitate ending a
1126            ;; sequence on a non-bar, reverse partial sequences and sequences
1127            (set! voices (map!
1128                          (lambda (l)
1129                            (map! reverse!
1130                                  (reverse!
1131                                   (if (and (pair? l) (pair? (car l))
1132                                            (bar-check? (caar l)))
1133                                       (cons (cdar l) (cdr l))
1134                                       l))))
1135                          voices))
1136
1137            ;; check sequence length
1138            (apply for-each (lambda seqs
1139                              (define (seq-len seq)
1140                                (reduce ly:moment-add
1141                                        (ly:make-moment 0)
1142                                        (map ly:music-length seq)))
1143                              (let ((moment-reference (seq-len (car seqs))))
1144                                (for-each (lambda (seq)
1145                                            (if (not (equal? (seq-len seq)
1146                                                             moment-reference))
1147                                                (ly:music-warning
1148                                                 (if (pair? seq)
1149                                                     (last seq)
1150                                                     (caar seqs))
1151                                                 (_ "Bars in parallel music don't have the same length"))))
1152                                          seqs)))
1153                   voices)
1154            (map concatenate! voices))
1155          (let ((deeper (map recurse-and-split lst)))
1156            (and (any pair? deeper)
1157                 (apply zip (map
1158                             (lambda (m split)
1159                               (or split
1160                                   (ly:music-deep-copy (make-list voice-count m))))
1161                             lst deeper))))))
1162    (define (recurse-and-split music)
1163      "This returns either a list of music split along barchecks, or
1164 @code{#f}."
1165      (let* ((elt (ly:music-property music 'element))
1166             (elts (ly:music-property music 'elements))
1167             (split-elt (and (ly:music? elt) (recurse-and-split elt)))
1168             (split-elts (and (pair? elts) (recurse-and-split-list elts))))
1169        (and (or split-elt split-elts)
1170             (map
1171              (lambda (e es)
1172                (let ((m (ly:music-deep-copy music
1173                        ;;; reassigning the origin of the parent only
1174                        ;;; makes sense if the first expression in the
1175                        ;;; result is from a distributed origin
1176                                             (or (and (ly:music? e) e)
1177                                                 (and (pair? es) (car es))))))
1178                  (if (ly:music? e)
1179                      (set! (ly:music-property m 'element) e))
1180                  (if (pair? es)
1181                      (set! (ly:music-property m 'elements) es))
1182                  m))
1183              (or split-elt (circular-list #f))
1184              (or split-elts (circular-list #f))))))
1185    (let ((voices (recurse-and-split music)))
1186      (if voices
1187          ;;
1188          ;; bind voice identifiers to the voices
1189          (for-each (lambda (voice-id voice)
1190                      (ly:parser-define! voice-id voice))
1191                    voice-ids voices)
1192          (ly:music-warning music
1193                            (_ "ignoring parallel music without barchecks")))))
1194
1195 parenthesize =
1196 #(define-music-function (arg) (ly:music?)
1197    (_i "Tag @var{arg} to be parenthesized.")
1198
1199    (if (memq 'event-chord (ly:music-property arg 'types))
1200        ;; arg is an EventChord -> set the parenthesize property
1201        ;; on all child notes and rests
1202        (for-each
1203         (lambda (ev)
1204           (if (or (memq 'note-event (ly:music-property ev 'types))
1205                   (memq 'rest-event (ly:music-property ev 'types)))
1206               (set! (ly:music-property ev 'parenthesize) #t)))
1207         (ly:music-property arg 'elements))
1208        ;; No chord, simply set property for this expression:
1209        (set! (ly:music-property arg 'parenthesize) #t))
1210    arg)
1211
1212 #(define (make-directed-part-combine-music direction chord-range part1 part2
1213           one-context-settings
1214           two-context-settings
1215           shared-context-settings)
1216
1217    (let* ((pc-music (make-music 'PartCombineMusic))
1218           (m1 (context-spec-music (make-non-relative-music part1) 'Voice "one"))
1219           (m2 (context-spec-music (make-non-relative-music part2) 'Voice "two"))
1220           (listener (ly:parser-lookup 'partCombineListener))
1221           (evs2 (recording-group-emulate m2 listener))
1222           (evs1 (recording-group-emulate m1 listener))
1223           (split-list
1224            (if (and (assoc "one" evs1) (assoc "two" evs2))
1225                (determine-split-list (reverse! (assoc-get "one" evs1) '())
1226                                      (reverse! (assoc-get "two" evs2) '())
1227                                      chord-range)
1228                '()))
1229           (L1 (ly:music-length part1))
1230           (L2 (ly:music-length part2))
1231           ;; keep the contexts alive for the full duration
1232           (skip (make-skip-music (make-duration-of-length
1233                                   (if (ly:moment<? L1 L2) L2 L1)))))
1234
1235      (set! (ly:music-property pc-music 'elements)
1236            (list (make-music
1237                   'PartCombinePartMusic
1238                   'element m1
1239                   'context-change-list
1240                   (make-part-combine-context-changes
1241                    default-part-combine-context-change-state-machine-one
1242                    split-list))
1243                  (make-music
1244                   'PartCombinePartMusic
1245                   'element m2
1246                   'context-change-list
1247                   (make-part-combine-context-changes
1248                    default-part-combine-context-change-state-machine-two
1249                    split-list))))
1250
1251      (set! (ly:music-property pc-music 'direction) direction)
1252
1253      #{ \context Staff <<
1254           \context Voice = "one" \with #one-context-settings { #skip }
1255           \context Voice = "two" \with #two-context-settings { #skip }
1256           \context Voice = "shared" \with #shared-context-settings { #skip }
1257           \context Voice = "solo" { #skip }
1258           \context NullVoice = "null" { #skip }
1259           #pc-music
1260           #(make-part-combine-marks
1261             default-part-combine-mark-state-machine split-list)
1262         >> #} ))
1263
1264 partcombine =
1265 #(define-music-function (chord-range part1 part2)
1266    ((number-pair? '(0 . 8)) ly:music? ly:music?)
1267    (_i "Take the music in @var{part1} and @var{part2} and return
1268 a music expression containing simultaneous voices, where @var{part1}
1269 and @var{part2} are combined into one voice where appropriate.
1270 Optional @var{chord-range} sets the distance in steps between notes
1271 that may be combined into a chord or unison.")
1272    (make-directed-part-combine-music #f chord-range part1 part2
1273     #{ \with { \voiceOne \override DynamicLineSpanner.direction = #UP } #}
1274     #{ \with { \voiceTwo \override DynamicLineSpanner.direction = #DOWN } #}
1275     #{ #} ))
1276
1277 partcombineUp =
1278 #(define-music-function (chord-range part1 part2)
1279    ((number-pair? '(0 . 8)) ly:music? ly:music?)
1280    (_i "Take the music in @var{part1} and @var{part2} and typeset so
1281 that they share a staff with stems directed upward.")
1282    (make-directed-part-combine-music UP chord-range part1 part2
1283     #{ \with { \voiceOne \override DynamicLineSpanner.direction = #UP } #}
1284     #{ \with { \voiceThree \override DynamicLineSpanner.direction = #UP } #}
1285     #{ \with { \voiceOne \override DynamicLineSpanner.direction = #UP } #} ))
1286
1287 partcombineDown =
1288 #(define-music-function (chord-range part1 part2)
1289    ((number-pair? '(0 . 8)) ly:music? ly:music?)
1290    (_i "Take the music in @var{part1} and @var{part2} and typeset so
1291 that they share a staff with stems directed downward.")
1292    (make-directed-part-combine-music DOWN chord-range part1 part2
1293     #{ \with { \voiceFour \override DynamicLineSpanner.direction = #DOWN } #}
1294     #{ \with { \voiceTwo \override DynamicLineSpanner.direction = #DOWN } #}
1295     #{ \with { \voiceTwo \override DynamicLineSpanner.direction = #DOWN } #} ))
1296
1297 %% Part combine forcing to be found in ly/property-init.ly
1298
1299 partial =
1300 #(define-music-function (dur) (ly:duration?)
1301   (_i "Make a partial measure.")
1302
1303   ;; We use `descend-to-context' here instead of `context-spec-music' to
1304   ;; ensure \partial still works if the Timing_translator is moved
1305     (descend-to-context
1306      (context-spec-music (make-music 'PartialSet
1307                                      'origin (*location*)
1308                                      'duration dur)
1309                          'Timing)
1310      'Score))
1311
1312 pitchedTrill =
1313 #(define-music-function
1314    (main-note secondary-note)
1315    (ly:music? ly:music?)
1316    (_i "Print a trill with @var{main-note} as the main note of the trill and
1317 print @var{secondary-note} as a stemless note head in parentheses.")
1318    (let* ((get-notes (lambda (ev-chord)
1319                        (extract-named-music ev-chord 'NoteEvent)))
1320           (sec-note-events (get-notes secondary-note))
1321           (trill-events (extract-named-music main-note 'TrillSpanEvent)))
1322      (if (pair? sec-note-events)
1323          (begin
1324            (let* ((trill-pitch (ly:music-property (car sec-note-events) 'pitch))
1325                   (forced (ly:music-property (car sec-note-events) 'force-accidental)))
1326
1327              (if (ly:pitch? trill-pitch)
1328                  (for-each (lambda (m)
1329                              (ly:music-set-property! m 'pitch trill-pitch)) trill-events)
1330                  (begin
1331                    (ly:input-warning (*location*) (_ "Second argument of \\pitchedTrill should be single note: "))
1332                    (display sec-note-events)))
1333
1334              (if (eq? forced #t)
1335                  (for-each (lambda (m)
1336                              (ly:music-set-property! m 'force-accidental forced))
1337                            trill-events)))))
1338      main-note))
1339
1340 propertyOverride =
1341 #(define-music-function (grob-property-path value)
1342    (key-list? scheme?)
1343    (_i "Set the grob property specified by @var{grob-property-path} to
1344 @var{value}.  @var{grob-property-path} is a symbol list of the form
1345 @code{Context.GrobName.property} or @code{GrobName.property}, possibly
1346 with subproperties given as well.  This music function is mostly intended
1347 for use from Scheme as a substitute for the built-in @code{\\override}
1348 command.")
1349    (let ((p (check-grob-path grob-property-path (*location*)
1350                              #:default 'Bottom
1351                              #:min 3)))
1352      (if p
1353          (context-spec-music
1354           (make-music 'OverrideProperty
1355                       'symbol (cadr p)
1356                       'origin (*location*)
1357                       'grob-value value
1358                       'grob-property-path (cddr p)
1359                       'pop-first #t)
1360           (car p))
1361          (make-music 'Music))))
1362
1363 propertyRevert =
1364 #(define-music-function (grob-property-path)
1365    (key-list?)
1366    (_i "Revert the grob property specified by @var{grob-property-path} to
1367 its previous value.  @var{grob-property-path} is a symbol list of the form
1368 @code{Context.GrobName.property} or @code{GrobName.property}, possibly
1369 with subproperties given as well.  This music function is mostly intended
1370 for use from Scheme as a substitute for the built-in @code{\\revert}
1371 command.")
1372    (let ((p (check-grob-path grob-property-path (*location*)
1373                              #:default 'Bottom
1374                              #:min 3)))
1375      (if p
1376          (context-spec-music
1377           (make-music 'RevertProperty
1378                       'symbol (cadr p)
1379                       'origin (*location*)
1380                       'grob-property-path (cddr p))
1381           (car p))
1382          (make-music 'Music))))
1383
1384 propertySet =
1385 #(define-music-function (property-path value)
1386    (symbol-list-or-symbol? scheme?)
1387    (_i "Set the context property specified by @var{property-path} to
1388 @var{value}.  This music function is mostly intended for use from
1389 Scheme as a substitute for the built-in @code{\\set} command.")
1390    (let ((p (check-context-path property-path (*location*))))
1391      (if p
1392          (context-spec-music
1393           (make-music 'PropertySet
1394                       'symbol (cadr p)
1395                       'value value
1396                       'origin (*location*))
1397           (car p))
1398          (make-music 'Music))))
1399
1400 propertyTweak =
1401 #(define-music-function (prop value item)
1402    (key-list-or-symbol? scheme? key-list-or-music?)
1403    (_i "Add a tweak to the following @var{item}, usually music.
1404 This generally behaves like @code{\\tweak} but will turn into an
1405 @code{\\override} when @var{item} is a symbol list.
1406
1407 In that case, @var{item} specifies the grob path to override.  This is
1408 mainly useful when using @code{\\propertyTweak} as as a component for
1409 building other functions like @code{\\omit}.  It is not the default
1410 behavior for @code{\\tweak} since many input strings in
1411 @code{\\lyricmode} can serve equally as music or as symbols which
1412 causes surprising behavior when tweaking lyrics using the less
1413 specific semantics of @code{\\propertyTweak}.
1414
1415 @var{prop} can contain additional elements in which case a nested
1416 property (inside of an alist) is tweaked.")
1417    ;; Why not instead make the parser treat strings preferably as
1418    ;; music in lyrics mode rather than as symbol?  Because then
1419    ;;
1420    ;; \tweak text "whatever" mylyrics
1421    ;;
1422    ;; will try putting a lyric event with text "whatever" in the text
1423    ;; property of lyrics.  So we want expressions allowing both
1424    ;; strings and lyrics to deliver strings: more complex conversions
1425    ;; should only be attempted when the simple uses don't match the
1426    ;; given predicate.
1427    (if (ly:music? item)
1428        (if (music-is-of-type? item 'context-specification)
1429            ;; This is essentially dealing with the case
1430            ;; \propertyTweak color #red \propertyTweak font-size #3 NoteHead
1431            ;; namely when stacked tweaks end in a symbol list
1432            ;; rather than a music expression.
1433            ;;
1434            ;; We have a tweak here to convert into an override,
1435            ;; so we need to know the grob to apply it to.  That's
1436            ;; easy if we have a directed tweak, and otherwise we
1437            ;; need to find the symbol in the expression itself.
1438            (let* ((p (check-grob-path prop (*location*)
1439                                       #:start 1
1440                                       #:default #t
1441                                       #:min 2))
1442                   (elt (ly:music-property item 'element))
1443                   (seq (if (music-is-of-type? elt 'sequential-music)
1444                            elt
1445                            (make-sequential-music (list elt))))
1446                   (elts (ly:music-property seq 'elements))
1447                   (symbol (if (symbol? (car p))
1448                               (car p)
1449                               (and (pair? elts)
1450                                    (ly:music-property (car elts)
1451                                                       'symbol)))))
1452              (if (symbol? symbol)
1453                  (begin
1454                    (set! (ly:music-property seq 'elements)
1455                          (cons (make-music 'OverrideProperty
1456                                            'symbol symbol
1457                                            'grob-property-path (cdr p)
1458                                            'pop-first #t
1459                                            'grob-value value
1460                                            'origin (*location*))
1461                                elts))
1462                    (set! (ly:music-property item 'element) seq))
1463                  (begin
1464                    (ly:parser-error (_ "Cannot \\propertyTweak")
1465                                     (*location*))
1466                    (ly:music-message item (_ "untweakable"))))
1467              item)
1468            (tweak prop value item))
1469        (propertyOverride (append item (if (symbol? prop) (list prop) prop))
1470                          value)))
1471
1472 propertyUnset =
1473 #(define-music-function (property-path)
1474    (symbol-list-or-symbol?)
1475    (_i "Unset the context property specified by @var{property-path}.
1476 This music function is mostly intended for use from Scheme as a
1477 substitute for the built-in @code{\\unset} command.")
1478    (let ((p (check-context-path property-path (*location*))))
1479      (if p
1480          (context-spec-music
1481           (make-music 'PropertyUnset
1482                       'symbol (cadr p)
1483                       'origin (*location*))
1484           (car p))
1485          (make-music 'Music))))
1486
1487 pushToTag =
1488 #(define-music-function (tag more music)
1489    (symbol? ly:music? ly:music?)
1490    (_i "Add @var{more} to the front of @code{elements} of all music
1491 expressions in @var{music} that are tagged with @var{tag}.")
1492    (music-map (lambda (m)
1493                 (if (memq tag (ly:music-property m 'tags))
1494                     (set! (ly:music-property m 'elements)
1495                           (cons more (ly:music-property m 'elements))))
1496                 m)
1497               music))
1498
1499 quoteDuring =
1500 #(define-music-function (what main-music) (string? ly:music?)
1501    (_i "Indicate a section of music to be quoted.  @var{what} indicates the name
1502 of the quoted voice, as specified in an @code{\\addQuote} command.
1503 @var{main-music} is used to indicate the length of music to be quoted;
1504 usually contains spacers or multi-measure rests.")
1505    (make-music 'QuoteMusic
1506                'element main-music
1507                'quoted-music-name what))
1508
1509
1510 relative =
1511 #(define-music-function (pitch music)
1512    ((ly:pitch?) ly:music?)
1513    (_i "Make @var{music} relative to @var{pitch}.  If @var{pitch} is
1514 omitted, the first note in @var{music} is given in absolute pitch.")
1515    ;; When \relative has no clear decision (can only happen with
1516    ;; scales with an even number of steps), it goes down (see
1517    ;; pitch.cc).  The following formula puts out f for both the normal
1518    ;; 7-step scale as well as for a "shortened" scale missing the
1519    ;; final b.  In either case, a first note of c will end up as c,
1520    ;; namely pitch (-1, 0, 0).
1521    (ly:make-music-relative! music
1522                             (or pitch
1523                                 (ly:make-pitch
1524                                  -1
1525                                  (quotient
1526                                   ;; size of current scale:
1527                                   (ly:pitch-steps (ly:make-pitch 1 0))
1528                                   2))))
1529    (make-music 'RelativeOctaveMusic
1530                'element music))
1531
1532 removeWithTag =
1533 #(define-music-function (tags music)
1534    (symbol-list-or-symbol? ly:music?)
1535    (_i "Remove elements of @var{music} that are tagged with one of the
1536 tags in @var{tags}.  @var{tags} may be either a single symbol or a list
1537 of symbols.")
1538    (music-filter
1539     (tags-remove-predicate tags)
1540     music))
1541
1542 resetRelativeOctave =
1543 #(define-music-function (pitch) (ly:pitch?)
1544    (_i "Set the octave inside a \\relative section.")
1545
1546    (make-music 'SequentialMusic
1547                'to-relative-callback
1548                (lambda (music last-pitch) pitch)))
1549
1550 retrograde =
1551 #(define-music-function (music)
1552     (ly:music?)
1553     (_i "Return @var{music} in reverse order.")
1554     (retrograde-music
1555      (expand-repeat-notes!
1556       (expand-repeat-chords!
1557        (cons 'rhythmic-event
1558              (ly:parser-lookup '$chord-repeat-events))
1559        music))))
1560
1561 revertTimeSignatureSettings =
1562 #(define-music-function
1563    (time-signature)
1564    (pair?)
1565
1566    (_i "Revert @code{timeSignatureSettings}
1567 for time signatures of @var{time-signature}.")
1568    (revert-time-signature-setting time-signature))
1569
1570 rightHandFinger =
1571 #(define-event-function (finger) (number-or-markup?)
1572    (_i "Apply @var{finger} as a fingering indication.")
1573
1574    (make-music
1575             'StrokeFingerEvent
1576             (if (number? finger) 'digit 'text)
1577             finger))
1578
1579 scaleDurations =
1580 #(define-music-function (fraction music)
1581    (fraction? ly:music?)
1582    (_i "Multiply the duration of events in @var{music} by @var{fraction}.")
1583    (ly:music-compress music
1584                       (ly:make-moment (car fraction) (cdr fraction))))
1585
1586 settingsFrom =
1587 #(define-scheme-function (ctx music)
1588    ((symbol?) ly:music?)
1589    (_i "Take the layout instruction events from @var{music}, optionally
1590 restricted to those applying to context type @var{ctx}, and return
1591 a context modification duplicating their effect.")
1592    (let ((mods (ly:make-context-mod)))
1593      (define (musicop m)
1594        (if (music-is-of-type? m 'layout-instruction-event)
1595            (ly:add-context-mod
1596             mods
1597             (case (ly:music-property m 'name)
1598               ((PropertySet)
1599                (list 'assign
1600                      (ly:music-property m 'symbol)
1601                      (ly:music-property m 'value)))
1602               ((PropertyUnset)
1603                (list 'unset
1604                      (ly:music-property m 'symbol)))
1605               ((OverrideProperty)
1606                (cons* 'push
1607                       (ly:music-property m 'symbol)
1608                       (ly:music-property m 'grob-value)
1609                       (cond
1610                        ((ly:music-property m 'grob-property #f) => list)
1611                        (else
1612                         (ly:music-property m 'grob-property-path)))))
1613               ((RevertProperty)
1614                (cons* 'pop
1615                       (ly:music-property m 'symbol)
1616                       (cond
1617                        ((ly:music-property m 'grob-property #f) => list)
1618                        (else
1619                         (ly:music-property m 'grob-property-path)))))))
1620            (case (ly:music-property m 'name)
1621              ((ApplyContext)
1622               (ly:add-context-mod mods
1623                                   (list 'apply
1624                                         (ly:music-property m 'procedure))))
1625              ((ContextSpeccedMusic)
1626               (if (or (not ctx)
1627                       (eq? ctx (ly:music-property m 'context-type)))
1628                   (musicop (ly:music-property m 'element))))
1629              (else
1630               (let ((callback (ly:music-property m 'elements-callback)))
1631                 (if (procedure? callback)
1632                     (for-each musicop (callback m))))))))
1633      (musicop music)
1634      mods))
1635
1636 shape =
1637 #(define-music-function (offsets item)
1638    (list? key-list-or-music?)
1639    (_i "Offset control-points of @var{item} by @var{offsets}.  The
1640 argument is a list of number pairs or list of such lists.  Each
1641 element of a pair represents an offset to one of the coordinates of a
1642 control-point.  If @var{item} is a string, the result is
1643 @code{\\once\\override} for the specified grob type.  If @var{item} is
1644 a music expression, the result is the same music expression with an
1645 appropriate tweak applied.")
1646    (define (shape-curve grob coords)
1647      (let* ((orig (ly:grob-original grob))
1648             (siblings (if (ly:spanner? grob)
1649                           (ly:spanner-broken-into orig) '()))
1650             (total-found (length siblings)))
1651        (define (offset-control-points offsets)
1652          (if (null? offsets)
1653              coords
1654              (map coord-translate coords offsets)))
1655
1656        (define (helper sibs offs)
1657          (if (pair? offs)
1658              (if (eq? (car sibs) grob)
1659                  (offset-control-points (car offs))
1660                  (helper (cdr sibs) (cdr offs)))
1661              coords))
1662
1663        ;; we work with lists of lists
1664        (if (or (null? offsets)
1665                (not (list? (car offsets))))
1666            (set! offsets (list offsets)))
1667
1668        (if (>= total-found 2)
1669            (helper siblings offsets)
1670            (offset-control-points (car offsets)))))
1671    (once (propertyTweak 'control-points
1672                         (grob-transformer 'control-points shape-curve)
1673                         item)))
1674
1675 shiftDurations =
1676 #(define-music-function (dur dots arg)
1677    (integer? integer? ly:music?)
1678    (_i "Change the duration of @var{arg} by adding @var{dur} to the
1679 @code{durlog} of @var{arg} and @var{dots} to the @code{dots} of @var{arg}.")
1680
1681    (shift-duration-log arg dur dots))
1682
1683 single =
1684 #(define-music-function (overrides music)
1685    (ly:music? ly:music?)
1686    (_i "Convert @var{overrides} to tweaks and apply them to @var{music}.
1687 This does not convert @code{\\revert}, @code{\\set} or @code{\\unset}.")
1688    (set! (ly:music-property music 'tweaks)
1689          (fold-some-music
1690           (lambda (m) (eq? (ly:music-property m 'name)
1691                            'OverrideProperty))
1692           (lambda (m tweaks)
1693             (let ((p (cond
1694                       ((ly:music-property m 'grob-property #f) => list)
1695                       (else
1696                        (ly:music-property m 'grob-property-path)))))
1697               (acons (cons (ly:music-property m 'symbol) ;grob name
1698                            (if (pair? (cdr p))
1699                                p ;grob property path
1700                                (car p))) ;grob property
1701                      (ly:music-property m 'grob-value)
1702                      tweaks)))
1703           (ly:music-property music 'tweaks)
1704           overrides))
1705    music)
1706
1707 skip =
1708 #(define-music-function (dur) (ly:duration?)
1709   (_i "Skip forward by @var{dur}.")
1710   (make-music 'SkipMusic
1711               'duration dur))
1712
1713
1714 slashedGrace =
1715 #(def-grace-function startSlashedGraceMusic stopSlashedGraceMusic
1716    (_i "Create slashed graces (slashes through stems, but no slur) from
1717 the following music expression"))
1718
1719 spacingTweaks =
1720 #(define-music-function (parameters) (list?)
1721    (_i "Set the system stretch, by reading the 'system-stretch property of
1722 the `parameters' assoc list.")
1723    (overrideProperty
1724     '(Score NonMusicalPaperColumn line-break-system-details)
1725     (list (cons 'alignment-extra-space (cdr (assoc 'system-stretch parameters)))
1726           (cons 'system-Y-extent (cdr (assoc 'system-Y-extent parameters))))))
1727
1728 styledNoteHeads =
1729 #(define-music-function (style heads music)
1730    (symbol? symbol-list-or-symbol? ly:music?)
1731    (_i "Set @var{heads} in @var{music} to @var{style}.")
1732    (style-note-heads heads style music))
1733
1734 tag =
1735 #(define-music-function (tags music) (symbol-list-or-symbol? ly:music?)
1736    (_i "Tag the following @var{music} with @var{tags} and return the
1737 result, by adding the single symbol or symbol list @var{tags} to the
1738 @code{tags} property of @var{music}.")
1739
1740    (set!
1741     (ly:music-property music 'tags)
1742     ((if (symbol? tags) cons append)
1743      tags
1744      (ly:music-property music 'tags)))
1745    music)
1746
1747 tagGroup =
1748 #(define-void-function (tags) (symbol-list?)
1749    (_i "Define a tag group comprising the symbols in the symbol list
1750 @var{tags}.  Tag groups must not overlap.")
1751    (let ((err (define-tag-group tags)))
1752      (if err (ly:parser-error err (*location*)))))
1753
1754 temporary =
1755 #(define-music-function (music)
1756    (ly:music?)
1757    (_i "Make any @code{\\override} in @var{music} replace an existing
1758 grob property value only temporarily, restoring the old value when a
1759 corresponding @code{\\revert} is executed.  This is achieved by
1760 clearing the @samp{pop-first} property normally set on
1761 @code{\\override}s.
1762
1763 An @code{\\override}/@/@code{\\revert} sequence created by using
1764 @code{\\temporary} and @code{\\undo} on the same music containing
1765 overrides will cancel out perfectly or cause a@tie{}warning.
1766
1767 Non-property-related music is ignored, warnings are generated for any
1768 property-changing music that isn't an @code{\\override}.")
1769    (define warned #f)
1770    (for-some-music
1771     (lambda (m)
1772       (and (or (music-is-of-type? m 'layout-instruction-event)
1773                (music-is-of-type? m 'context-specification)
1774                (music-is-of-type? m 'apply-context)
1775                (music-is-of-type? m 'time-signature-music))
1776            (case (ly:music-property m 'name)
1777              ((OverrideProperty)
1778               (if (ly:music-property m 'pop-first #f)
1779                   (set! (ly:music-property m 'pop-first) '()))
1780               (if (ly:music-property m 'once #f)
1781                   (set! (ly:music-property m 'once) '()))
1782               #t)
1783              ((ContextSpeccedMusic)
1784               #f)
1785              (else
1786               (if (not warned)
1787                   (begin
1788                     (ly:input-warning (*location*) (_ "Cannot make ~a revertible")
1789                                       (ly:music-property m 'name))
1790                     (set! warned #t)))
1791               #t))))
1792     music)
1793    music)
1794
1795 time =
1796 #(define-music-function (beat-structure fraction)
1797    ((number-list? '()) fraction?)
1798    (_i "Set @var{fraction} as time signature, with optional
1799 number list @var{beat-structure} before it.")
1800   (make-music 'TimeSignatureMusic
1801               'numerator (car fraction)
1802               'denominator (cdr fraction)
1803               'beat-structure beat-structure))
1804
1805 times =
1806 #(define-music-function (fraction music)
1807    (fraction? ly:music?)
1808    (_i "Scale @var{music} in time by @var{fraction}.")
1809   (make-music 'TimeScaledMusic
1810               'element (ly:music-compress music (ly:make-moment (car fraction) (cdr fraction)))
1811               'numerator (car fraction)
1812               'denominator (cdr fraction)))
1813
1814 transpose =
1815 #(define-music-function
1816    (from to music)
1817    (ly:pitch? ly:pitch? ly:music?)
1818
1819    (_i "Transpose @var{music} from pitch @var{from} to pitch @var{to}.")
1820    (make-music 'TransposedMusic
1821                'element (ly:music-transpose music (ly:pitch-diff to from))))
1822
1823 transposedCueDuring =
1824 #(define-music-function
1825    (what dir pitch main-music)
1826    (string? ly:dir? ly:pitch? ly:music?)
1827
1828    (_i "Insert notes from the part @var{what} into a voice called @code{cue},
1829 using the transposition defined by @var{pitch}.  This happens
1830 simultaneously with @var{main-music}, which is usually a rest.  The
1831 argument @var{dir} determines whether the cue notes should be notated
1832 as a first or second voice.")
1833
1834    (make-music 'QuoteMusic
1835                'element main-music
1836                'quoted-context-type 'CueVoice
1837                'quoted-context-id "cue"
1838                'quoted-music-name what
1839                'quoted-voice-direction dir
1840                ;; following is inverse of instrumentTransposition for
1841                ;; historical reasons
1842                'quoted-transposition pitch))
1843
1844 transposition =
1845 #(define-music-function (pitch) (ly:pitch?)
1846    (_i "Set instrument transposition")
1847
1848    (context-spec-music
1849     (make-property-set 'instrumentTransposition pitch)
1850     'Staff))
1851
1852 tuplet =
1853 #(define-music-function (ratio tuplet-span music)
1854    (fraction? (ly:duration? '()) ly:music?)
1855    (_i "Scale the given @var{music} to tuplets.  @var{ratio} is a
1856 fraction that specifies how many notes are played in place of the
1857 nominal value: it will be @samp{3/2} for triplets, namely three notes
1858 being played in place of two.  If the optional duration
1859 @var{tuplet-span} is specified, it is used instead of
1860 @code{tupletSpannerDuration} for grouping the tuplets.
1861 For example,
1862 @example
1863 \\tuplet 3/2 4 @{ c8 c c c c c @}
1864 @end example
1865 will result in two groups of three tuplets, each group lasting for a
1866 quarter note.")
1867    (make-music 'TimeScaledMusic
1868                'element (ly:music-compress
1869                          music
1870                          (ly:make-moment (cdr ratio) (car ratio)))
1871                'numerator (cdr ratio)
1872                'denominator (car ratio)
1873                'duration tuplet-span))
1874
1875 tupletSpan =
1876 #(define-music-function (tuplet-span)
1877    ((ly:duration?))
1878    (_i "Set @code{tupletSpannerDuration}, the length into which
1879 @code{\\tuplet} without an explicit @samp{tuplet-span} argument of its
1880 own will group its tuplets, to the duration @var{tuplet-span}.  To
1881 revert to the default of not subdividing the contents of a @code{\\tuplet}
1882 command without explicit @samp{tuplet-span}, use
1883 @example
1884 \\tupletSpan \\default
1885 @end example
1886 ")
1887    (if tuplet-span
1888        #{ \set tupletSpannerDuration = #(ly:duration-length tuplet-span) #}
1889        #{ \unset tupletSpannerDuration #}))
1890
1891 tweak =
1892 #(define-music-function (prop value music)
1893    (key-list-or-symbol? scheme? ly:music?)
1894    (_i "Add a tweak to the following @var{music}.
1895 Layout objects created by @var{music} get their property @var{prop}
1896 set to @var{value}.  If @var{prop} has the form @samp{Grob.property}, like with
1897 @example
1898 \\tweak Accidental.color #red cis'
1899 @end example
1900 an indirectly created grob (@samp{Accidental} is caused by
1901 @samp{NoteHead}) can be tweaked; otherwise only directly created grobs
1902 are affected.
1903
1904 @var{prop} can contain additional elements in which case a nested
1905 property (inside of an alist) is tweaked.")
1906    (let ((p (check-grob-path prop (*location*)
1907                              #:start 1
1908                              #:default #t
1909                              #:min 2)))
1910      (cond ((not p))
1911            ;; p now contains at least two elements.  The first
1912            ;; element is #t when no grob has been explicitly
1913            ;; specified, otherwise it is a grob name.
1914            (else
1915             (set! (ly:music-property music 'tweaks)
1916                   (acons (cond ((pair? (cddr p)) p)
1917                                ((symbol? (car p))
1918                                 (cons (car p) (cadr p)))
1919                                (else (cadr p)))
1920                          value
1921                          (ly:music-property music 'tweaks)))))
1922      music))
1923
1924
1925 undo =
1926 #(define-music-function (music)
1927    (ly:music?)
1928    (_i "Convert @code{\\override} and @code{\\set} in @var{music} to
1929 @code{\\revert} and @code{\\unset}, respectively.  Any reverts and
1930 unsets already in @var{music} cause a warning.  Non-property-related music is ignored.")
1931    (define warned #f)
1932    (let loop
1933        ((music music))
1934      (let
1935          ((lst
1936            (fold-some-music
1937             (music-type-predicate '(layout-instruction-event
1938                                     context-specification
1939                                     apply-context
1940                                     time-signature-music))
1941             (lambda (m overrides)
1942               (case (ly:music-property m 'name)
1943                 ((OverrideProperty)
1944                  (cons
1945                   (make-music 'RevertProperty
1946                               'symbol (ly:music-property m 'symbol)
1947                               'grob-property-path
1948                               (cond
1949                                ((ly:music-property m 'grob-property #f) => list)
1950                                (else
1951                                 (ly:music-property m 'grob-property-path))))
1952                   overrides))
1953                 ((PropertySet)
1954                  (cons
1955                   (make-music 'PropertyUnset
1956                               'symbol (ly:music-property m 'symbol))
1957                   overrides))
1958                 ((ContextSpeccedMusic)
1959                  (cons
1960                   (make-music 'ContextSpeccedMusic
1961                               'element (loop (ly:music-property m 'element))
1962                               'context-type (ly:music-property m 'context-type))
1963                   overrides))
1964                 (else
1965                  (if (not warned)
1966                      (begin
1967                        (ly:input-warning (*location*) (_ "Cannot revert ~a")
1968                                          (ly:music-property m 'name))
1969                        (set! warned #t)))
1970                  overrides)))
1971             '()
1972             music)))
1973        (cond
1974         ((null? lst) (make-music 'Music))
1975         ((null? (cdr lst)) (car lst))
1976         (else (make-sequential-music lst))))))
1977
1978 unfoldRepeats =
1979 #(define-music-function (music) (ly:music?)
1980    (_i "Force any @code{\\repeat volta}, @code{\\repeat tremolo} or
1981 @code{\\repeat percent} commands in @var{music} to be interpreted
1982 as @code{\\repeat unfold}.")
1983    (unfold-repeats music))
1984
1985 void =
1986 #(define-void-function (arg) (scheme?)
1987    (_i "Accept a scheme argument, return a void expression.
1988 Use this if you want to have a scheme expression evaluated
1989 because of its side-effects, but its value ignored."))
1990
1991 withMusicProperty =
1992 #(define-music-function (sym val music)
1993    (symbol? scheme? ly:music?)
1994    (_i "Set @var{sym} to @var{val} in @var{music}.")
1995
1996    (set! (ly:music-property music sym) val)
1997    music)