scm/define-music-properties.scm

   1 ;;;; This file is part of LilyPond, the GNU music typesetter.
   2 ;;;;
   3 ;;;; Copyright (C) 1998--2015  Han-Wen Nienhuys <hanwen@xs4all.nl>
   4 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
   5 ;;;;
   6 ;;;; LilyPond is free software: you can redistribute it and/or modify
   7 ;;;; it under the terms of the GNU General Public License as published by
   8 ;;;; the Free Software Foundation, either version 3 of the License, or
   9 ;;;; (at your option) any later version.
  10 ;;;;
  11 ;;;; LilyPond is distributed in the hope that it will be useful,
  12 ;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 ;;;; GNU General Public License for more details.
  15 ;;;;
  16 ;;;; You should have received a copy of the GNU General Public License
  17 ;;;; along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 (define (music-property-description symbol type? description)
  20   (if (not (equal? #f (object-property symbol 'music-doc)))
  21       (ly:error (_ "symbol ~S redefined") symbol))
  22   (set-object-property! symbol 'music-type? type?)
  23   (set-object-property! symbol 'music-doc description)
  24   symbol)
  25
  26 (define-public all-music-properties
  27   (map
  28    (lambda (x) (apply music-property-description x))
  29    `(
  30      (absolute-octave ,integer?
  31                       "The absolute octave for an octave check note.")
  32      (alteration ,number? "Alteration for figured bass.")
  33      (alternative-dir ,ly:dir? "Indicates if an AlternativeMusic is the
  34 First (-1), Middle (0), or Last (1) of group of alternate endings.")
  35      (alternative-increment ,integer? "The number of times an alternative's
  36 lettering should be incremented.")
  37      (articulation-type ,string? "Key for script definitions alist.
  38
  39 TODO: Consider making type into symbol.")
  40      (articulations ,ly:music-list?
  41                     "Articulation events specifically for this note.")
  42      (associated-context ,string? "Name of the context associated with
  43 this @code{\\lyricsto} section.")
  44      (associated-context-type ,symbol? "Type of the context associated with
  45 this @code{\\lyricsto} section.")
  46      (augmented ,boolean? "This figure is for an augmented figured
  47 bass (with @code{+} sign).")
  48      (augmented-slash ,boolean? "This figure is for an augmented
  49 figured bass (back-slashed number).")
  50      (automatically-numbered ,boolean? "Should a footnote be automatically
  51 numbered?")
  52      (autosplit-end ,boolean? "Duration of event was truncated by automatic
  53 splitting in @code{Completion_heads_engraver}.")
  54
  55      (bass ,boolean? "Set if this note is a bass note in a chord.")
  56      (beat-structure ,list? "A beatStructure to be used in autobeaming.")
  57      (bracket-start ,boolean? "Start a bracket here.
  58
  59 TODO: Use SpanEvents?")
  60      (bracket-stop ,boolean? "Stop a bracket here.")
  61      (break-penalty ,number? "Penalty for line break hint.")
  62      (break-permission ,symbol?
  63                        "Whether to allow, forbid or force a line break.")
  64
  65      (cautionary ,boolean? "If set, this alteration needs a
  66 cautionary accidental.")
  67      (change-to-id ,string? "Name of the context to change to.")
  68      (change-to-type ,symbol? "Type of the context to change to.")
  69      (class ,symbol? "The class name of an event class.")
  70      (context ,ly:context? "The context to which an event is sent.")
  71      (context-change-list ,list? "Context changes for @code{\\autochange} or @code{\\partcombine}.")
  72      (context-id ,string? "Name of context.")
  73      (context-type ,symbol?  "Type of context.")
  74      (create-new ,boolean? "Create a fresh context.")
  75
  76      (delta-step ,number? "How much should a fall change pitch?")
  77      (denominator ,integer? "Denominator in a time signature.")
  78      (descend-only ,boolean? "If set, this @code{\\context} only descends
  79 in the context tree.")
  80      (digit ,integer? "Digit for fingering.")
  81      (diminished ,boolean? "This bass figure should be slashed.")
  82      (direction ,ly:dir? "Print this up or down?")
  83      (drum-type ,symbol? "Which percussion instrument to play this note on.")
  84      (duration ,ly:duration? "Duration of this note or lyric.")
  85
  86      (element ,ly:music? "The single child of a Music_wrapper music object,
  87 or the body of a repeat.")
  88      (elements ,ly:music-list? "A list of elements for sequential of
  89 simultaneous music, or the alternatives of repeated music.")
  90      (elements-callback ,procedure? "Return a list of children, for use by
  91 a sequential iterator.  Takes a single music parameter.")
  92      (error-found ,boolean?
  93                   "If true, a parsing error was found in this expression.")
  94
  95      (figure ,integer? "A bass figure.")
  96      (footnote-text ,markup? "Text to appear in a footnote.")
  97      (force-accidental ,boolean? "If set, a cautionary accidental should
  98 always be printed on this note.")
  99
 100      (grob-property ,symbol? "The symbol of the grob property to set.")
 101      (grob-property-path ,list? "A list of symbols, locating a nested grob
 102 property, e.g., @code{(beamed-lengths details)}.")
 103      (grob-value ,scheme? "The value of the grob property to set.")
 104
 105      (id ,symbol? "The ID of an event.")
 106      (input-tag ,scheme? "Arbitrary marker to relate input and output.")
 107      (inversion ,boolean? "If set, this chord note is inverted.")
 108      (iterator-ctor ,procedure? "Function to construct a
 109 @code{music-event-iterator} object for this music.")
 110
 111      (label ,number-or-markup? "Label of a mark.")
 112      (last-pitch ,ly:pitch? "The last pitch after relativization.")
 113      (length ,ly:moment? "The duration of this music.")
 114      (length-callback ,procedure? "How to compute the duration of this music.
 115 This property can only be defined as initializer in
 116 @file{scm/@/define-music-types.scm}.")
 117      (line-break-permission ,symbol? "When the music is at top-level,
 118 whether to allow, forbid or force a line break.")
 119
 120      (metronome-count ,number-or-pair? "How many beats in a minute?")
 121      (midi-extra-velocity ,integer? "How much louder or softer should
 122 this note be in MIDI output? The default is 0.")
 123      (midi-length ,procedure? "Function to determine how long to play
 124 a note in MIDI. It should take a moment (the written length of the
 125 note) and a context, and return a moment (the length to play the
 126 note).")
 127      (moment ,ly:moment? "The moment at which an event happens.")
 128      (music-cause ,ly:music? "The music object that is the cause of
 129 an event.")
 130
 131      (name ,symbol? "Name of this music object.")
 132      (no-continuation ,boolean? "If set, disallow continuation lines.")
 133      (numerator ,integer? "Numerator of a time signature.")
 134
 135      (octavation ,integer? "This pitch was octavated by how many octaves?
 136 For chord inversions, this is negative.")
 137      (once ,boolean? "Apply this operation only during one time step?")
 138      (ops ,scheme? "The operations to apply during the creation of a
 139 context.")
 140      (origin ,ly:input-location? "Where was this piece of music defined?")
 141      (ottava-number ,integer? "The octavation for @code{\\ottava}.")
 142
 143      (page-break-permission ,symbol? "When the music is at top-level,
 144 whether to allow, forbid or force a page break.")
 145      (page-label ,symbol? "The label of a page marker.")
 146      (page-marker ,boolean? "If true, and the music expression is found at
 147 top-level, a page marker object is instanciated instead of a score.")
 148      (page-turn-permission ,symbol? "When the music is at top-level,
 149 whether to allow, forbid or force a page turn.")
 150      (parenthesize ,boolean? "Enclose resulting objects in parentheses?")
 151      (part-combine-status ,symbol? "Change to what kind of state?
 152 Options are @code{solo1}, @code{solo2} and @code{unisono}.")
 153      (pitch ,ly:pitch? "The pitch of this note.")
 154      (pitch-alist ,list? "A list of pitches jointly forming the scale
 155 of a key signature.")
 156      (pop-first ,boolean? "Do a revert before we try to do an override
 157 on some grob property.")
 158      (procedure ,procedure? "The function to run with @code{\\applycontext}.
 159 It must take a single argument, being the context.")
 160      (property-operations ,list? "Do these operations for instantiating
 161 the context.")
 162      (property-path ,symbol? "The path of a property.")
 163
 164      (quoted-context-id ,string? "The ID of the context to direct quotes to,
 165 e.g., @code{cue}.")
 166      (quoted-context-type ,symbol? "The name of the context to
 167 direct quotes to, e.g., @code{Voice}.")
 168      (quoted-events ,vector? "A vector of with @code{moment} and
 169 @code{event-list} entries.")
 170      (quoted-music-clef ,string? "The clef of the voice to quote.")
 171      (quoted-music-name ,string? "The name of the voice to quote.")
 172      (quoted-transposition ,ly:pitch? "The pitch used for the quote,
 173 overriding @code{\\transposition}.")
 174      (quoted-voice-direction ,ly:dir? "Should the quoted voice be up-stem
 175 or down-stem?")
 176
 177      (repeat-count ,integer? "Do a @code{\\repeat} how often?")
 178
 179      (slash-count ,integer? "The number of slashes in a single-beat repeat.
 180 If zero, signals a beat containing varying durations.")
 181      (span-direction ,ly:dir? "Does this start or stop a spanner?")
 182      (span-type ,symbol? "What kind of dynamic spanner should be created?
 183 Options are @code{'text} and @code{'hairpin}.")
 184      (span-text ,markup? "The displayed text for dynamic text
 185 spanners (e.g., cresc.)")
 186      (spanner-id ,key? "Identifier to distinguish concurrent spanners.")
 187      (start-callback ,procedure? "Function to compute the negative length
 188 of starting grace notes.  This property can only be defined as initializer
 189 in @file{scm/@/define-music-types.scm}.")
 190      (string-number ,integer? "The number of the string in
 191 a @code{StringNumberEvent}.")
 192      (symbol ,symbol? "Grob name to perform an override or revert on.")
 193
 194      (tags ,list? "List of symbols that for denoting extra details, e.g.,
 195 @code{\\tag #'part @dots{}} could tag a piece of music as only being active
 196 in a part.")
 197      (tempo-unit ,ly:duration? "The unit for the metronome count.")
 198      (text ,markup? "Markup expression to be printed.")
 199      (to-relative-callback ,procedure? "How to transform a piece of music
 200 to relative pitches.")
 201      (tonic ,ly:pitch? "Base of the scale.")
 202      (tremolo-type ,integer? "Speed of tremolo, e.g., 16 for @code{c4:16}.")
 203      (trill-pitch ,ly:pitch? "Pitch of other note of the trill.")
 204      (tweaks ,list? "An alist of properties to override in the backend
 205 for the grob made of this event.")
 206      (type ,symbol? "The type of this music object.
 207 Determines iteration in some cases.")
 208      (types ,list? "The types of this music object; determines by what
 209 engraver this music expression is processed.")
 210
 211      (untransposable ,boolean? "If set, this music is not transposed.")
 212
 213      (value ,scheme? "Assignment value for a translation property.")
 214      (void ,boolean? "If this property is @code{#t}, then the
 215 music expression is to be discarded by the toplevel music handler.")
 216      (volta-repeats ,list? "A list that is transformed into a volta
 217 repeat element list.")
 218
 219      (what ,symbol? "What to change for auto-change.
 220
 221 FIXME: Naming.")
 222
 223      (X-offset ,number?
 224                "Offset of resulting grob; only used for balloon texts.")
 225
 226      (Y-offset ,number?
 227                "Offset of resulting grob; only used for balloon texts.")
 228      )))