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)