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