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 reduceChords =
1510 #(define-music-function (music) (ly:music?)
1511    (_i "Reduce chords contained in @var{music} to single notes,
1512 intended mainly for reusing music in RhythmicStaff.  Does not
1513 reduce parallel music.")
1514    (event-chord-reduce music))
1515
1516 relative =
1517 #(define-music-function (pitch music)
1518    ((ly:pitch?) ly:music?)
1519    (_i "Make @var{music} relative to @var{pitch}.  If @var{pitch} is
1520 omitted, the first note in @var{music} is given in absolute pitch.")
1521    ;; When \relative has no clear decision (can only happen with
1522    ;; scales with an even number of steps), it goes down (see
1523    ;; pitch.cc).  The following formula puts out f for both the normal
1524    ;; 7-step scale as well as for a "shortened" scale missing the
1525    ;; final b.  In either case, a first note of c will end up as c,
1526    ;; namely pitch (-1, 0, 0).
1527    (ly:make-music-relative! music
1528                             (or pitch
1529                                 (ly:make-pitch
1530                                  -1
1531                                  (quotient
1532                                   ;; size of current scale:
1533                                   (ly:pitch-steps (ly:make-pitch 1 0))
1534                                   2))))
1535    (make-music 'RelativeOctaveMusic
1536                'element music))
1537
1538 removeWithTag =
1539 #(define-music-function (tags music)
1540    (symbol-list-or-symbol? ly:music?)
1541    (_i "Remove elements of @var{music} that are tagged with one of the
1542 tags in @var{tags}.  @var{tags} may be either a single symbol or a list
1543 of symbols.")
1544    (music-filter
1545     (tags-remove-predicate tags)
1546     music))
1547
1548 resetRelativeOctave =
1549 #(define-music-function (pitch) (ly:pitch?)
1550    (_i "Set the octave inside a \\relative section.")
1551
1552    (make-music 'SequentialMusic
1553                'to-relative-callback
1554                (lambda (music last-pitch) pitch)))
1555
1556 retrograde =
1557 #(define-music-function (music)
1558     (ly:music?)
1559     (_i "Return @var{music} in reverse order.")
1560     (retrograde-music
1561      (expand-repeat-notes!
1562       (expand-repeat-chords!
1563        (cons 'rhythmic-event
1564              (ly:parser-lookup '$chord-repeat-events))
1565        music))))
1566
1567 revertTimeSignatureSettings =
1568 #(define-music-function
1569    (time-signature)
1570    (pair?)
1571
1572    (_i "Revert @code{timeSignatureSettings}
1573 for time signatures of @var{time-signature}.")
1574    (revert-time-signature-setting time-signature))
1575
1576 rightHandFinger =
1577 #(define-event-function (finger) (number-or-markup?)
1578    (_i "Apply @var{finger} as a fingering indication.")
1579
1580    (make-music
1581             'StrokeFingerEvent
1582             (if (number? finger) 'digit 'text)
1583             finger))
1584
1585 scaleDurations =
1586 #(define-music-function (fraction music)
1587    (fraction? ly:music?)
1588    (_i "Multiply the duration of events in @var{music} by @var{fraction}.")
1589    (ly:music-compress music
1590                       (ly:make-moment (car fraction) (cdr fraction))))
1591
1592 settingsFrom =
1593 #(define-scheme-function (ctx music)
1594    ((symbol?) ly:music?)
1595    (_i "Take the layout instruction events from @var{music}, optionally
1596 restricted to those applying to context type @var{ctx}, and return
1597 a context modification duplicating their effect.")
1598    (let ((mods (ly:make-context-mod)))
1599      (define (musicop m)
1600        (if (music-is-of-type? m 'layout-instruction-event)
1601            (ly:add-context-mod
1602             mods
1603             (case (ly:music-property m 'name)
1604               ((PropertySet)
1605                (list 'assign
1606                      (ly:music-property m 'symbol)
1607                      (ly:music-property m 'value)))
1608               ((PropertyUnset)
1609                (list 'unset
1610                      (ly:music-property m 'symbol)))
1611               ((OverrideProperty)
1612                (cons* 'push
1613                       (ly:music-property m 'symbol)
1614                       (ly:music-property m 'grob-value)
1615                       (cond
1616                        ((ly:music-property m 'grob-property #f) => list)
1617                        (else
1618                         (ly:music-property m 'grob-property-path)))))
1619               ((RevertProperty)
1620                (cons* 'pop
1621                       (ly:music-property m 'symbol)
1622                       (cond
1623                        ((ly:music-property m 'grob-property #f) => list)
1624                        (else
1625                         (ly:music-property m 'grob-property-path)))))))
1626            (case (ly:music-property m 'name)
1627              ((ApplyContext)
1628               (ly:add-context-mod mods
1629                                   (list 'apply
1630                                         (ly:music-property m 'procedure))))
1631              ((ContextSpeccedMusic)
1632               (if (or (not ctx)
1633                       (eq? ctx (ly:music-property m 'context-type)))
1634                   (musicop (ly:music-property m 'element))))
1635              (else
1636               (let ((callback (ly:music-property m 'elements-callback)))
1637                 (if (procedure? callback)
1638                     (for-each musicop (callback m))))))))
1639      (musicop music)
1640      mods))
1641
1642 shape =
1643 #(define-music-function (offsets item)
1644    (list? key-list-or-music?)
1645    (_i "Offset control-points of @var{item} by @var{offsets}.  The
1646 argument is a list of number pairs or list of such lists.  Each
1647 element of a pair represents an offset to one of the coordinates of a
1648 control-point.  If @var{item} is a string, the result is
1649 @code{\\once\\override} for the specified grob type.  If @var{item} is
1650 a music expression, the result is the same music expression with an
1651 appropriate tweak applied.")
1652    (define (shape-curve grob coords)
1653      (let* ((orig (ly:grob-original grob))
1654             (siblings (if (ly:spanner? grob)
1655                           (ly:spanner-broken-into orig) '()))
1656             (total-found (length siblings)))
1657        (define (offset-control-points offsets)
1658          (if (null? offsets)
1659              coords
1660              (map coord-translate coords offsets)))
1661
1662        (define (helper sibs offs)
1663          (if (pair? offs)
1664              (if (eq? (car sibs) grob)
1665                  (offset-control-points (car offs))
1666                  (helper (cdr sibs) (cdr offs)))
1667              coords))
1668
1669        ;; we work with lists of lists
1670        (if (or (null? offsets)
1671                (not (list? (car offsets))))
1672            (set! offsets (list offsets)))
1673
1674        (if (>= total-found 2)
1675            (helper siblings offsets)
1676            (offset-control-points (car offsets)))))
1677    (once (propertyTweak 'control-points
1678                         (grob-transformer 'control-points shape-curve)
1679                         item)))
1680
1681 shiftDurations =
1682 #(define-music-function (dur dots arg)
1683    (integer? integer? ly:music?)
1684    (_i "Change the duration of @var{arg} by adding @var{dur} to the
1685 @code{durlog} of @var{arg} and @var{dots} to the @code{dots} of @var{arg}.")
1686
1687    (shift-duration-log arg dur dots))
1688
1689 single =
1690 #(define-music-function (overrides music)
1691    (ly:music? ly:music?)
1692    (_i "Convert @var{overrides} to tweaks and apply them to @var{music}.
1693 This does not convert @code{\\revert}, @code{\\set} or @code{\\unset}.")
1694    (set! (ly:music-property music 'tweaks)
1695          (fold-some-music
1696           (lambda (m) (eq? (ly:music-property m 'name)
1697                            'OverrideProperty))
1698           (lambda (m tweaks)
1699             (let ((p (cond
1700                       ((ly:music-property m 'grob-property #f) => list)
1701                       (else
1702                        (ly:music-property m 'grob-property-path)))))
1703               (acons (cons (ly:music-property m 'symbol) ;grob name
1704                            (if (pair? (cdr p))
1705                                p ;grob property path
1706                                (car p))) ;grob property
1707                      (ly:music-property m 'grob-value)
1708                      tweaks)))
1709           (ly:music-property music 'tweaks)
1710           overrides))
1711    music)
1712
1713 skip =
1714 #(define-music-function (dur) (ly:duration?)
1715   (_i "Skip forward by @var{dur}.")
1716   (make-music 'SkipMusic
1717               'duration dur))
1718
1719
1720 slashedGrace =
1721 #(def-grace-function startSlashedGraceMusic stopSlashedGraceMusic
1722    (_i "Create slashed graces (slashes through stems, but no slur) from
1723 the following music expression"))
1724
1725 spacingTweaks =
1726 #(define-music-function (parameters) (list?)
1727    (_i "Set the system stretch, by reading the 'system-stretch property of
1728 the `parameters' assoc list.")
1729    (overrideProperty
1730     '(Score NonMusicalPaperColumn line-break-system-details)
1731     (list (cons 'alignment-extra-space (cdr (assoc 'system-stretch parameters)))
1732           (cons 'system-Y-extent (cdr (assoc 'system-Y-extent parameters))))))
1733
1734 styledNoteHeads =
1735 #(define-music-function (style heads music)
1736    (symbol? symbol-list-or-symbol? ly:music?)
1737    (_i "Set @var{heads} in @var{music} to @var{style}.")
1738    (style-note-heads heads style music))
1739
1740 tag =
1741 #(define-music-function (tags music) (symbol-list-or-symbol? ly:music?)
1742    (_i "Tag the following @var{music} with @var{tags} and return the
1743 result, by adding the single symbol or symbol list @var{tags} to the
1744 @code{tags} property of @var{music}.")
1745
1746    (set!
1747     (ly:music-property music 'tags)
1748     ((if (symbol? tags) cons append)
1749      tags
1750      (ly:music-property music 'tags)))
1751    music)
1752
1753 tagGroup =
1754 #(define-void-function (tags) (symbol-list?)
1755    (_i "Define a tag group comprising the symbols in the symbol list
1756 @var{tags}.  Tag groups must not overlap.")
1757    (let ((err (define-tag-group tags)))
1758      (if err (ly:parser-error err (*location*)))))
1759
1760 temporary =
1761 #(define-music-function (music)
1762    (ly:music?)
1763    (_i "Make any @code{\\override} in @var{music} replace an existing
1764 grob property value only temporarily, restoring the old value when a
1765 corresponding @code{\\revert} is executed.  This is achieved by
1766 clearing the @samp{pop-first} property normally set on
1767 @code{\\override}s.
1768
1769 An @code{\\override}/@/@code{\\revert} sequence created by using
1770 @code{\\temporary} and @code{\\undo} on the same music containing
1771 overrides will cancel out perfectly or cause a@tie{}warning.
1772
1773 Non-property-related music is ignored, warnings are generated for any
1774 property-changing music that isn't an @code{\\override}.")
1775    (define warned #f)
1776    (for-some-music
1777     (lambda (m)
1778       (and (or (music-is-of-type? m 'layout-instruction-event)
1779                (music-is-of-type? m 'context-specification)
1780                (music-is-of-type? m 'apply-context)
1781                (music-is-of-type? m 'time-signature-music))
1782            (case (ly:music-property m 'name)
1783              ((OverrideProperty)
1784               (if (ly:music-property m 'pop-first #f)
1785                   (set! (ly:music-property m 'pop-first) '()))
1786               (if (ly:music-property m 'once #f)
1787                   (set! (ly:music-property m 'once) '()))
1788               #t)
1789              ((ContextSpeccedMusic)
1790               #f)
1791              (else
1792               (if (not warned)
1793                   (begin
1794                     (ly:input-warning (*location*) (_ "Cannot make ~a revertible")
1795                                       (ly:music-property m 'name))
1796                     (set! warned #t)))
1797               #t))))
1798     music)
1799    music)
1800
1801 time =
1802 #(define-music-function (beat-structure fraction)
1803    ((number-list? '()) fraction?)
1804    (_i "Set @var{fraction} as time signature, with optional
1805 number list @var{beat-structure} before it.")
1806   (make-music 'TimeSignatureMusic
1807               'numerator (car fraction)
1808               'denominator (cdr fraction)
1809               'beat-structure beat-structure))
1810
1811 times =
1812 #(define-music-function (fraction music)
1813    (fraction? ly:music?)
1814    (_i "Scale @var{music} in time by @var{fraction}.")
1815   (make-music 'TimeScaledMusic
1816               'element (ly:music-compress music (ly:make-moment (car fraction) (cdr fraction)))
1817               'numerator (car fraction)
1818               'denominator (cdr fraction)))
1819
1820 transpose =
1821 #(define-music-function
1822    (from to music)
1823    (ly:pitch? ly:pitch? ly:music?)
1824
1825    (_i "Transpose @var{music} from pitch @var{from} to pitch @var{to}.")
1826    (make-music 'TransposedMusic
1827                'element (ly:music-transpose music (ly:pitch-diff to from))))
1828
1829 transposedCueDuring =
1830 #(define-music-function
1831    (what dir pitch main-music)
1832    (string? ly:dir? ly:pitch? ly:music?)
1833
1834    (_i "Insert notes from the part @var{what} into a voice called @code{cue},
1835 using the transposition defined by @var{pitch}.  This happens
1836 simultaneously with @var{main-music}, which is usually a rest.  The
1837 argument @var{dir} determines whether the cue notes should be notated
1838 as a first or second voice.")
1839
1840    (make-music 'QuoteMusic
1841                'element main-music
1842                'quoted-context-type 'CueVoice
1843                'quoted-context-id "cue"
1844                'quoted-music-name what
1845                'quoted-voice-direction dir
1846                ;; following is inverse of instrumentTransposition for
1847                ;; historical reasons
1848                'quoted-transposition pitch))
1849
1850 transposition =
1851 #(define-music-function (pitch) (ly:pitch?)
1852    (_i "Set instrument transposition")
1853
1854    (context-spec-music
1855     (make-property-set 'instrumentTransposition pitch)
1856     'Staff))
1857
1858 tuplet =
1859 #(define-music-function (ratio tuplet-span music)
1860    (fraction? (ly:duration? '()) ly:music?)
1861    (_i "Scale the given @var{music} to tuplets.  @var{ratio} is a
1862 fraction that specifies how many notes are played in place of the
1863 nominal value: it will be @samp{3/2} for triplets, namely three notes
1864 being played in place of two.  If the optional duration
1865 @var{tuplet-span} is specified, it is used instead of
1866 @code{tupletSpannerDuration} for grouping the tuplets.
1867 For example,
1868 @example
1869 \\tuplet 3/2 4 @{ c8 c c c c c @}
1870 @end example
1871 will result in two groups of three tuplets, each group lasting for a
1872 quarter note.")
1873    (make-music 'TimeScaledMusic
1874                'element (ly:music-compress
1875                          music
1876                          (ly:make-moment (cdr ratio) (car ratio)))
1877                'numerator (cdr ratio)
1878                'denominator (car ratio)
1879                'duration tuplet-span))
1880
1881 tupletSpan =
1882 #(define-music-function (tuplet-span)
1883    ((ly:duration?))
1884    (_i "Set @code{tupletSpannerDuration}, the length into which
1885 @code{\\tuplet} without an explicit @samp{tuplet-span} argument of its
1886 own will group its tuplets, to the duration @var{tuplet-span}.  To
1887 revert to the default of not subdividing the contents of a @code{\\tuplet}
1888 command without explicit @samp{tuplet-span}, use
1889 @example
1890 \\tupletSpan \\default
1891 @end example
1892 ")
1893    (if tuplet-span
1894        #{ \set tupletSpannerDuration = #(ly:duration-length tuplet-span) #}
1895        #{ \unset tupletSpannerDuration #}))
1896
1897 tweak =
1898 #(define-music-function (prop value music)
1899    (key-list-or-symbol? scheme? ly:music?)
1900    (_i "Add a tweak to the following @var{music}.
1901 Layout objects created by @var{music} get their property @var{prop}
1902 set to @var{value}.  If @var{prop} has the form @samp{Grob.property}, like with
1903 @example
1904 \\tweak Accidental.color #red cis'
1905 @end example
1906 an indirectly created grob (@samp{Accidental} is caused by
1907 @samp{NoteHead}) can be tweaked; otherwise only directly created grobs
1908 are affected.
1909
1910 @var{prop} can contain additional elements in which case a nested
1911 property (inside of an alist) is tweaked.")
1912    (let ((p (check-grob-path prop (*location*)
1913                              #:start 1
1914                              #:default #t
1915                              #:min 2)))
1916      (cond ((not p))
1917            ;; p now contains at least two elements.  The first
1918            ;; element is #t when no grob has been explicitly
1919            ;; specified, otherwise it is a grob name.
1920            (else
1921             (set! (ly:music-property music 'tweaks)
1922                   (acons (cond ((pair? (cddr p)) p)
1923                                ((symbol? (car p))
1924                                 (cons (car p) (cadr p)))
1925                                (else (cadr p)))
1926                          value
1927                          (ly:music-property music 'tweaks)))))
1928      music))
1929
1930
1931 undo =
1932 #(define-music-function (music)
1933    (ly:music?)
1934    (_i "Convert @code{\\override} and @code{\\set} in @var{music} to
1935 @code{\\revert} and @code{\\unset}, respectively.  Any reverts and
1936 unsets already in @var{music} cause a warning.  Non-property-related music is ignored.")
1937    (define warned #f)
1938    (let loop
1939        ((music music))
1940      (let
1941          ((lst
1942            (fold-some-music
1943             (music-type-predicate '(layout-instruction-event
1944                                     context-specification
1945                                     apply-context
1946                                     time-signature-music))
1947             (lambda (m overrides)
1948               (case (ly:music-property m 'name)
1949                 ((OverrideProperty)
1950                  (cons
1951                   (make-music 'RevertProperty
1952                               'symbol (ly:music-property m 'symbol)
1953                               'grob-property-path
1954                               (cond
1955                                ((ly:music-property m 'grob-property #f) => list)
1956                                (else
1957                                 (ly:music-property m 'grob-property-path))))
1958                   overrides))
1959                 ((PropertySet)
1960                  (cons
1961                   (make-music 'PropertyUnset
1962                               'symbol (ly:music-property m 'symbol))
1963                   overrides))
1964                 ((ContextSpeccedMusic)
1965                  (cons
1966                   (make-music 'ContextSpeccedMusic
1967                               'element (loop (ly:music-property m 'element))
1968                               'context-type (ly:music-property m 'context-type))
1969                   overrides))
1970                 (else
1971                  (if (not warned)
1972                      (begin
1973                        (ly:input-warning (*location*) (_ "Cannot revert ~a")
1974                                          (ly:music-property m 'name))
1975                        (set! warned #t)))
1976                  overrides)))
1977             '()
1978             music)))
1979        (cond
1980         ((null? lst) (make-music 'Music))
1981         ((null? (cdr lst)) (car lst))
1982         (else (make-sequential-music lst))))))
1983
1984 unfoldRepeats =
1985 #(define-music-function (types music)
1986    ((symbol-list-or-symbol? '()) ly:music?)
1987    (_i "Force @code{\\repeat volta}, @code{\\repeat tremolo} or
1988 @code{\\repeat percent} commands in @var{music} to be interpreted
1989 as @code{\\repeat unfold}, if specified in the optional symbol-list @var{types}.
1990 The default for @var{types} is an empty list, which will force any of those
1991 commands in @var{music} to be interpreted as @code{\\repeat unfold}.  Possible
1992 entries are @code{volta}, @code{tremolo} or @code{percent}.  Multiple entries
1993 are possible.")
1994    (unfold-repeats types music))
1995
1996 void =
1997 #(define-void-function (arg) (scheme?)
1998    (_i "Accept a scheme argument, return a void expression.
1999 Use this if you want to have a scheme expression evaluated
2000 because of its side-effects, but its value ignored."))
2001
2002 withMusicProperty =
2003 #(define-music-function (sym val music)
2004    (symbol? scheme? ly:music?)
2005    (_i "Set @var{sym} to @var{val} in @var{music}.")
2006
2007    (set! (ly:music-property music sym) val)
2008    music)