# 4. Scheme functions

Function: ly:add-context-mod contextmods modification

  Adds the given context modification to the list contextmods of context modifications.

Function: ly:add-file-name-alist alist

  Add mappings for error messages from alist.

Function: ly:add-interface iface desc props

  Add a new grob interface. iface is the interface name, desc is the interface description, and props is the list of user-settable properties for the interface.

Function: ly:add-listener list disp cl

  Add the listener list to the dispatcher disp. Whenever disp hears an event of class cl, it is forwarded to list.

Function: ly:add-option sym val description

  Add a program option sym. val is the default value and description is a string description.

Function: ly:all-grob-interfaces

  Return the hash table with all grob interface descriptions.

Function: ly:all-options

  Get all option settings in an alist.

Function: ly:all-stencil-expressions

  Return all symbols recognized as stencil expressions.

Function: ly:assoc-get key alist default-value strict-checking

  Return value if key in alist, else default-value (or `#f` if not specified). If strict-checking is set to `#t` and key is not in alist, a programming_error is output.

Function: ly:axis-group-interface::add-element grob grob-element

  Set grob the parent of grob-element on all axes of grob.

Function: ly:basic-progress str rest

  A Scheme callable function to issue a basic progress message str. The message is formatted with `format` and rest.

Function: ly:beam-score-count

  count number of beam scores.

Function: ly:book? x

  Is x a `Book` object?

Function: ly:book-add-bookpart! book-smob book-part

  Add book-part to book-smob book part list.

Function: ly:book-add-score! book-smob score

  Add score to book-smob score list.

Function: ly:book-book-parts book

  Return book parts in book.

Function: ly:book-header book

  Return header in book.

Function: ly:book-paper book

  Return paper in book.

Function: ly:book-process book-smob default-paper default-layout output

  Print book. output is passed to the backend unchanged. For example, it may be a string (for file based outputs) or a socket (for network based output).

Function: ly:book-process-to-systems book-smob default-paper default-layout output

  Print book. output is passed to the backend unchanged. For example, it may be a string (for file based outputs) or a socket (for network based output).

Function: ly:book-scores book

  Return scores in book.

Function: ly:book-set-header! book module

  Set the book header.

Function: ly:box? x

  Is x a `Box` object?

Function: ly:bp num

  num bigpoints (1/72th inch).

Function: ly:bracket a iv t p

  Make a bracket in direction a. The extent of the bracket is given by iv. The wings protrude by an amount of p, which may be negative. The thickness is given by t.

Function: ly:broadcast disp ev

  Send the stream event ev to the dispatcher disp.

Function: ly:camel-case->lisp-identifier name-sym

  Convert `FooBar_Bla` to `foo-bar-bla` style symbol.

Function: ly:chain-assoc-get key achain default-value strict-checking

  Return value for key from a list of alists achain. If no entry is found, return default-value or `#f` if default-value is not specified. With strict-checking set to `#t`, a programming_error is output in such cases.

Function: ly:check-expected-warnings

  Check whether all expected warnings have really been triggered.

Function: ly:cm num

  num cm.

Function: ly:command-line-code

  The Scheme code specified on command-line with ‘`-e`’.

Function: ly:command-line-options

  The Scheme options specified on command-line with ‘`-d`’.

Function: ly:connect-dispatchers to from

  Make the dispatcher to listen to events from from.

Function: ly:context? x

  Is x a `Context` object?

Function: ly:context-current-moment context

  Return the current moment of context.

Function: ly:context-def? x

  Is x a `Context_def` object?

Function: ly:context-def-lookup def sym val

  Return the value of sym in context definition def (e.g., `\Voice`). If no value is found, return val or `'()` if val is undefined. sym can be any of ‘`default-child`’, ‘`consists`’, ‘`description`’, ‘`aliases`’, ‘`accepts`’, ‘`property-ops`’, ‘`context-name`’, ‘`group-type`’.

Function: ly:context-def-modify def mod

  Return the result of applying the context-mod mod to the context definition def. Does not change def.

Function: ly:context-event-source context

  Return `event-source` of context context.

Function: ly:context-events-below context

  Return a `stream-distributor` that distributes all events from context and all its subcontexts.

Function: ly:context-find context name

  Find a parent of context that has name or alias name. Return `#f` if not found.

Function: ly:context-grob-definition context name

  Return the definition of name (a symbol) within context as an alist.

Function: ly:context-id context

  Return the ID string of context, i.e., for `\context Voice = "one" …` return the string `one`.

Function: ly:context-mod? x

  Is x a `Context_mod` object?

Function: ly:context-mod-apply! context mod

  Apply the context modification mod to context.

Function: ly:context-name context

  Return the name of context, i.e., for `\context Voice = "one" …` return the symbol `Voice`.

Function: ly:context-now context

  Return `now-moment` of context context.

Function: ly:context-parent context

  Return the parent of context, `#f` if none.

Function: ly:context-property context sym def

  Return the value for property sym in context. If def is given, and property value is `'()`, return def.

Function: ly:context-property-where-defined context name

  Return the context above context where name is defined.

Function: ly:context-pushpop-property context grob eltprop val

  Do a single `\override` or `\revert` operation in context. The grob definition grob is extended with eltprop (if val is specified) or reverted (if unspecified).

Function: ly:context-set-property! context name val

  Set value of property name in context context to val.

Function: ly:context-unset-property context name

  Unset value of property name in context context.

Function: ly:debug str rest

  A Scheme callable function to issue a debug message str. The message is formatted with `format` and rest.

Function: ly:default-scale

  Get the global default scale.

Function: ly:dimension? d

  Return d as a number. Used to distinguish length variables from normal numbers.

Function: ly:dir? s

  Is s a direction? Valid directions are `-1`, `0`, or `1`, where `-1` represents left or down, `1` represents right or up, and `0` represents a neutral direction.

Function: ly:dispatcher? x

  Is x a `Dispatcher` object?

Function: ly:duration? x

  Is x a `Duration` object?

Function: ly:duration<? p1 p2

  Is p1 shorter than p2?

Function: ly:duration->string dur

  Convert dur to a string.

Function: ly:duration-dot-count dur

  Extract the dot count from dur.

Function: ly:duration-factor dur

  Extract the compression factor from dur. Return it as a pair.

Function: ly:duration-length dur

  The length of the duration as a `moment`.

Function: ly:duration-log dur

  Extract the duration log from dur.

Function: ly:duration-scale dur

  Extract the compression factor from dur. Return it as a rational.

Function: ly:effective-prefix

  Return effective prefix.

Function: ly:encode-string-for-pdf str

  Encode the given string to either Latin1 (which is a subset of the PDFDocEncoding) or if that’s not possible to full UTF-16BE with Byte-Order-Mark (BOM).

Function: ly:engraver-announce-end-grob engraver grob cause

  Announce the end of a grob (i.e., the end of a spanner) originating from given engraver instance, with grob being a grob. cause should either be another grob or a music event.

Function: ly:engraver-make-grob engraver grob-name cause

  Create a grob originating from given engraver instance, with given grob-name, a symbol. cause should either be another grob or a music event.

Function: ly:error str rest

  A Scheme callable function to issue the error str. The error is formatted with `format` and rest.

Function: ly:eval-simple-closure delayed closure scm-start scm-end

  Evaluate a simple closure with the given delayed argument. If scm-start and scm-end are defined, evaluate it purely with those start and end points.

Function: ly:event? obj

  Is obj a proper (non-rhythmic) event object?

Function: ly:event-deep-copy m

  Copy m and all sub expressions of m.

Function: ly:event-property sev sym val

  Get the property sym of stream event sev. If sym is undefined, return val or `'()` if val is not specified.

Function: ly:event-set-property! ev sym val

  Set property sym in event ev to val.

Function: ly:expand-environment str

  Expand `$VAR` and `${VAR}` in str.

Function: ly:expect-warning str rest

  A Scheme callable function to register a warning to be expected and subsequently suppressed. If the warning is not encountered, a warning about the missing warning will be shown. The message should be translated with `(_ ...)` and changing parameters given after the format string.

Function: ly:find-file name

  Return the absolute file name of name, or `#f` if not found.

Function: ly:font-config-add-directory dir

  Add directory dir to FontConfig.

Function: ly:font-config-add-font font

  Add font font to FontConfig.

Function: ly:font-config-display-fonts

  Dump a list of all fonts visible to FontConfig.

Function: ly:font-config-get-font-file name

  Get the file for font name.

Function: ly:font-design-size font

  Given the font metric font, return the design size, relative to the current output-scale.

Function: ly:font-file-name font

  Given the font metric font, return the corresponding file name.

Function: ly:font-get-glyph font name

  Return a stencil from font for the glyph named name. If the glyph is not available, return an empty stencil.

  Note that this command can only be used to access glyphs from fonts loaded with `ly:system-font-load`; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:font-glyph-name-to-charcode font name

  Return the character code for glyph name in font.

  Note that this command can only be used to access glyphs from fonts loaded with `ly:system-font-load`; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:font-glyph-name-to-index font name

  Return the index for name in font.

  Note that this command can only be used to access glyphs from fonts loaded with `ly:system-font-load`; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:font-index-to-charcode font index

  Return the character code for index in font.

  Note that this command can only be used to access glyphs from fonts loaded with `ly:system-font-load`; currently, this means either the Emmentaler or Emmentaler-Brace fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:font-magnification font

  Given the font metric font, return the magnification, relative to the current output-scale.

Function: ly:font-metric? x

  Is x a `Font_metric` object?

Function: ly:font-name font

  Given the font metric font, return the corresponding name.

Function: ly:font-sub-fonts font

  Given the font metric font of an OpenType font, return the names of the subfonts within font.

Function: ly:format str rest

  LilyPond specific format, supporting `~a` and `~[0-9]f`. Basic support for `~s` is also provided.

Function: ly:format-output context

  Given a global context in its final state, process it and return the `Music_output` object in its final state.

Function: ly:get-all-function-documentation

  Get a hash table with all LilyPond Scheme extension functions.

Function: ly:get-all-translators

  Return a list of all translator objects that may be instantiated.

Function: ly:get-context-mods contextmod

  Returns the list of context modifications stored in contextmod.

Function: ly:get-option var

  Get a global option setting.

Function: ly:get-spacing-spec from-scm to-scm

  Return the spacing spec going between the two given grobs, from_scm and to_scm.

Function: ly:get-undead undead

  Get back object from undead.

Function: ly:gettext original

  A Scheme wrapper function for `gettext`.

Function: ly:grob? x

  Is x a `Grob` object?

Function: ly:grob-alist-chain grob global

  Get an alist chain for grob grob, with global as the global default. If unspecified, `font-defaults` from the layout block is taken.

Function: ly:grob-array? x

  Is x a `Grob_array` object?

Function: ly:grob-array->list grob-arr

  Return the elements of grob-arr as a Scheme list.

Function: ly:grob-array-length grob-arr

  Return the length of grob-arr.

Function: ly:grob-array-ref grob-arr index

  Retrieve the indexth element of grob-arr.

Function: ly:grob-basic-properties grob

  Get the immutable properties of grob.

Function: ly:grob-chain-callback grob proc sym

  Find the callback that is stored as property sym of grob grob and chain proc to the head of this, meaning that it is called using grob and the previous callback’s result.

Function: ly:grob-common-refpoint grob other axis

  Find the common refpoint of grob and other for axis.

Function: ly:grob-common-refpoint-of-array grob others axis

  Find the common refpoint of grob and others (a grob-array) for axis.

Function: ly:grob-default-font grob

  Return the default font for grob grob.

Function: ly:grob-extent grob refp axis

  Get the extent in axis direction of grob relative to the grob refp.

Function: ly:grob-get-vertical-axis-group-index grob

  Get the index of the vertical axis group the grob grob belongs to; return `-1` if none is found.

Function: ly:grob-interfaces grob

  Return the interfaces list of grob grob.

Function: ly:grob-layout grob

  Get `\layout` definition from grob grob.

Function: ly:grob-object grob sym

  Return the value of a pointer in grob grob of property sym. It returns `'()` (end-of-list) if sym is undefined in grob.

Function: ly:grob-original grob

  Return the unbroken original grob of grob.

Function: ly:grob-parent grob axis

  Get the parent of grob. axis is 0 for the X-axis, 1 for the Y-axis.

Function: ly:grob-pq<? a b

  Compare two grob priority queue entries. This is an internal function.

Function: ly:grob-properties grob

  Get the mutable properties of grob.

Function: ly:grob-property grob sym val

  Return the value for property sym of grob. If no value is found, return val or `'()` if val is not specified.

Function: ly:grob-property-data grob sym

  Return the value for property sym of grob, but do not process callbacks.

Function: ly:grob-pure-height grob refp beg end val

  Return the pure height of grob given refpoint refp. If no value is found, return val or `'()` if val is not specified.

Function: ly:grob-pure-property grob sym beg end val

  Return the pure value for property sym of grob. If no value is found, return val or `'()` if val is not specified.

Function: ly:grob-relative-coordinate grob refp axis

  Get the coordinate in axis direction of grob relative to the grob refp.

Function: ly:grob-robust-relative-extent grob refp axis

  Get the extent in axis direction of grob relative to the grob refp, or `(0,0)` if empty.

Function: ly:grob-script-priority-less a b

  Compare two grobs by script priority. For internal use.

Function: ly:grob-set-nested-property! grob symlist val

  Set nested property symlist in grob grob to value val.

Function: ly:grob-set-object! grob sym val

  Set sym in grob grob to value val.

Function: ly:grob-set-parent! grob axis parent-grob

  Set parent-grob the parent of grob grob in axis axis.

Function: ly:grob-set-property! grob sym val

  Set sym in grob grob to value val.

Function: ly:grob-staff-position sg

  Return the Y-position of sg relative to the staff.

Function: ly:grob-suicide! grob

  Kill grob.

Function: ly:grob-system grob

  Return the system grob of grob.

Function: ly:grob-translate-axis! grob d a

  Translate grob on axis a over distance d.

Function: ly:grob-vertical<? a b

  Does a lie above b on the page?

Function: ly:gulp-file name size

  Read size characters from the file name, and return its contents in a string. If size is undefined, the entire file is read. The file is looked up using the search path.

Function: ly:hash-table-keys tab

  Return a list of keys in tab.

Function: ly:inch num

  num inches.

Function: ly:input-both-locations sip

  Return input location in sip as `(file-name first-line first-column last-line last-column)`.

Function: ly:input-file-line-char-column sip

  Return input location in sip as `(file-name line char column)`.

Function: ly:input-location? x

  Is x an `input-location`?

Function: ly:input-message sip msg rest

  Print msg as a GNU compliant error message, pointing to the location in sip. msg is interpreted similar to `format`’s argument, using rest.

Function: ly:input-warning sip msg rest

  Print msg as a GNU compliant warning message, pointing to the location in sip. msg is interpreted similar to `format`’s argument, using rest.

Function: ly:interpret-music-expression mus ctx

  Interpret the music expression mus in the global context ctx. The context is returned in its final state.

Function: ly:interpret-stencil-expression expr func arg1 offset

  Parse expr, feed bits to func with first arg arg1 having offset offset.

Function: ly:intlog2 d

  The 2-logarithm of 1/d.

Function: ly:item? g

  Is g an `Item` object?

Function: ly:item-break-dir it

  The break status direction of item it. `-1` means end of line, `0` unbroken, and `1` beginning of line.

Function: ly:iterator? x

  Is x a `Music_iterator` object?

Function: ly:lexer-keywords lexer

  Return a list of `(KEY . CODE)` pairs, signifying the LilyPond reserved words list.

Function: ly:lily-lexer? x

  Is x a `Lily_lexer` object?

Function: ly:lily-parser? x

  Is x a `Lily_parser` object?

Function: ly:listened-event-class? disp cl

  Does disp listen to any event type in the list cl?

Function: ly:listened-event-types disp

  Return a list of all event types that disp listens to.

Function: ly:listener? x

  Is x a `Listener` object?

Function: ly:make-book paper header scores

  Make a `\book` of paper and header (which may be `#f` as well) containing `\scores`.

Function: ly:make-book-part scores

  Make a `\bookpart` containing `\scores`.

Function: ly:make-context-mod mod-list

  Creates a context modification, optionally initialized via the list of modifications mod-list.

Function: ly:make-dispatcher

  Return a newly created dispatcher.

Function: ly:make-duration length dotcount num den

  length is the negative logarithm (base 2) of the duration: 1 is a half note, 2 is a quarter note, 3 is an eighth note, etc. The number of dots after the note is given by the optional argument dotcount.

  The duration factor is optionally given by integers num and den, alternatively by a single rational number.

  A duration is a musical duration, i.e., a length of time described by a power of two (whole, half, quarter, etc.) and a number of augmentation dots.

Function: ly:make-global-context output-def

  Set up a global interpretation context, using the output block output-def. The context is returned.

Function: ly:make-global-translator global

  Create a translator group and connect it to the global context global. The translator group is returned.

Function: ly:make-listener callback

  Create a listener. Any time the listener hears an object, it will call callback with that object.

  callback should take exactly one argument.

Function: ly:make-moment m g gn gd

  Create the moment with rational main timing m, and optional grace timing g.

  A moment is a point in musical time. It consists of a pair of rationals (m, g), where m is the timing for the main notes, and g the timing for grace notes. In absence of grace notes, g is zero.

  For compatibility reasons, it is possible to write two numbers specifying numerator and denominator instead of the rationals. These forms cannot be mixed, and the two-argument form is disambiguated by the sign of the second argument: if it is positive, it can only be a denominator and not a grace timing.

Function: ly:make-music props

  Make a C++ `Music` object and initialize it with props.

  This function is for internal use and is only called by `make-music`, which is the preferred interface for creating music objects.

Function: ly:make-music-function signature func

  Make a function to process music, to be used for the parser. func is the function, and signature describes its arguments. signature’s cdr is a list containing either `ly:music?` predicates or other type predicates. Its car is the syntax function to call.

Function: ly:make-music-relative! music pitch

  Make music relative to pitch, return final pitch.

Function: ly:make-output-def

  Make an output definition.

Function: ly:make-page-label-marker label

  Return page marker with label label.

Function: ly:make-page-permission-marker symbol permission

  Return page marker with page breaking and turning permissions.

Function: ly:make-pango-description-string chain size

  Make a `PangoFontDescription` string for the property alist chain at size size.

Function: ly:make-paper-outputter port format

  Create an outputter that evaluates within `output-`format, writing to port.

Function: ly:make-pitch octave note alter

  octave is specified by an integer, zero for the octave containing middle C. note is a number indexing the global default scale, with 0 corresponding to pitch C and 6 usually corresponding to pitch B. Optional alter is a rational number of 200-cent whole tones for alteration.

Function: ly:make-prob type init rest

  Create a `Prob` object.

Function: ly:make-scale steps

  Create a scale. The argument is a vector of rational numbers, each of which represents the number of 200 cent tones of a pitch above the tonic.

Function: ly:make-score music

  Return score with music encapsulated in it.

Function: ly:make-simple-closure expr

  Make a simple closure. expr should be form of `(func a1 a2 …)`, and will be invoked as `(func delayed-arg a1 a2 …)`.

Function: ly:make-spring ideal min-dist

  Make a spring. ideal is the ideal distance of the spring, and min-dist is the minimum distance.

Function: ly:make-stencil expr xext yext

  Stencils are device independent output expressions. They carry two pieces of information:

  1. A specification of how to print this object. This specification is processed by the output backends, for example ‘`scm/output-ps.scm`’.
  2. The vertical and horizontal extents of the object, given as pairs. If an extent is unspecified (or if you use `empty-interval` as its value), it is taken to be empty.

Function: ly:make-stream-event cl proplist

  Create a stream event of class cl with the given mutable property list.

Function: ly:make-undead object

  This packages object in a manner that keeps it from triggering "Parsed object should be dead" messages.

Function: ly:make-unpure-pure-container unpure pure

  Make an unpure-pure container. unpure should be an unpure expression, and pure should be a pure expression. If pure is omitted, the value of unpure will be used twice, except that a callback is given two extra arguments that are ignored for the sake of pure calculations.

Function: ly:message str rest

  A Scheme callable function to issue the message str. The message is formatted with `format` and rest.

Function: ly:minimal-breaking pb

  Break (pages and lines) the `Paper_book` object pb without looking for optimal spacing: stack as many lines on a page before moving to the next one.

Function: ly:mm num

  num mm.

Function: ly:module->alist mod

  Dump the contents of module mod as an alist.

Function: ly:module-copy dest src

  Copy all bindings from module src into dest.

Function: ly:modules-lookup modules sym def

  Look up sym in the list modules, returning the first occurence. If not found, return def or `#f` if def isn’t specified.

Function: ly:moment? x

  Is x a `Moment` object?

Function: ly:moment<? a b

  Compare two moments.

Function: ly:moment-add a b

  Add two moments.

Function: ly:moment-div a b

  Divide two moments.

Function: ly:moment-grace mom

  Extract grace timing as a rational number from mom.

Function: ly:moment-grace-denominator mom

  Extract denominator from grace timing.

Function: ly:moment-grace-numerator mom

  Extract numerator from grace timing.

Function: ly:moment-main mom

  Extract main timing as a rational number from mom.

Function: ly:moment-main-denominator mom

  Extract denominator from main timing.

Function: ly:moment-main-numerator mom

  Extract numerator from main timing.

Function: ly:moment-mod a b

  Modulo of two moments.

Function: ly:moment-mul a b

  Multiply two moments.

Function: ly:moment-sub a b

  Subtract two moments.

Function: ly:music? obj

  Is obj a music object?

Function: ly:music-compress m factor

  Compress music object m by moment factor.

Function: ly:music-deep-copy m

  Copy m and all sub expressions of m. m may be an arbitrary type; cons cells and music are copied recursively.

Function: ly:music-duration-compress mus fact

  Compress mus by factor fact, which is a `Moment`.

Function: ly:music-duration-length mus

  Extract the duration field from mus and return the length.

Function: ly:music-function? x

  Is x a `music-function`?

Function: ly:music-function-extract x

  Return the Scheme function inside x.

Function: ly:music-function-signature x

  Return the function signature inside x.

Function: ly:music-length mus

  Get the length of music expression mus and return it as a `Moment` object.

Function: ly:music-list? lst

  Is lst a list of music objects?

Function: ly:music-mutable-properties mus

  Return an alist containing the mutable properties of mus. The immutable properties are not available, since they are constant and initialized by the `make-music` function.

Function: ly:music-output? x

  Is x a `Music_output` object?

Function: ly:music-property mus sym val

  Return the value for property sym of music expression mus. If no value is found, return val or `'()` if val is not specified.

Function: ly:music-set-property! mus sym val

  Set property sym in music expression mus to val.

Function: ly:music-transpose m p

  Transpose m such that central C is mapped to p. Return m.

Function: ly:note-column-accidentals note-column

  Return the `AccidentalPlacement` grob from note-column if any, or `SCM_EOL` otherwise.

Function: ly:note-column-dot-column note-column

  Return the `DotColumn` grob from note-column if any, or `SCM_EOL` otherwise.

Function: ly:note-head::stem-attachment font-metric glyph-name

  Get attachment in font-metric for attaching a stem to notehead glyph-name.

Function: ly:number->string s

  Convert s to a string without generating many decimals.

Function: ly:one-line-breaking pb

  Put each score on a single line, and put each line on its own page. The paper-width setting will be modified so that every page will be wider than the widest line.

Function: ly:optimal-breaking pb

  Optimally break (pages and lines) the `Paper_book` object pb to minimize badness in bother vertical and horizontal spacing.

Function: ly:option-usage port

  Print `ly:set-option` usage. Optional port argumentfor the destination defaults to current output port.

Function: ly:otf->cff otf-file-name

  Convert the contents of an OTF file to a CFF file, returning it as a string.

Function: ly:otf-font? font

  Is font an OpenType font?

Function: ly:otf-font-glyph-info font glyph

  Given the font metric font of an OpenType font, return the information about named glyph glyph (a string).

Function: ly:otf-font-table-data font tag

  Extract a table tag from font. Return empty string for non-existent tag.

Function: ly:otf-glyph-count font

  Return the number of glyphs in font.

Function: ly:otf-glyph-list font

  Return a list of glyph names for font.

Function: ly:output-def? def

  Is def an output definition?

Function: ly:output-def-clone def

  Clone output definition def.

Function: ly:output-def-lookup def sym val

  Return the value of sym in output definition def (e.g., `\paper`). If no value is found, return val or `'()` if val is undefined.

Function: ly:output-def-parent def

  Return the parent output definition of def.

Function: ly:output-def-scope def

  Return the variable scope inside def.

Function: ly:output-def-set-variable! def sym val

  Set an output definition def variable sym to val.

Function: ly:output-description output-def

  Return the description of translators in output-def.

Function: ly:output-find-context-def output-def context-name

  Return an alist of all context defs (matching context-nameif given) in output-def.

Function: ly:output-formats

  Formats passed to ‘`--format`’ as a list of strings, used for the output.

Function: ly:outputter-close outputter

  Close port of outputter.

Function: ly:outputter-dump-stencil outputter stencil

  Dump stencil expr onto outputter.

Function: ly:outputter-dump-string outputter str

  Dump str onto outputter.

Function: ly:outputter-module outputter

  Return output module of outputter.

Function: ly:outputter-output-scheme outputter expr

  Eval expr in module of outputter.

Function: ly:outputter-port outputter

  Return output port for outputter.

Function: ly:page-marker? x

  Is x a `Page_marker` object?

Function: ly:page-turn-breaking pb

  Optimally break (pages and lines) the `Paper_book` object pb such that page turns only happen in specified places, returning its pages.

Function: ly:pango-font? f

  Is f a pango font?

Function: ly:pango-font-physical-fonts f

  Return alist of `(ps-name file-name font-index)` lists for Pango font f.

Function: ly:paper-book? x

  Is x a `Paper_book` object?

Function: ly:paper-book-header pb

  Return the header definition (`\header`) in `Paper_book` object pb.

Function: ly:paper-book-pages pb

  Return pages in `Paper_book` object pb.

Function: ly:paper-book-paper pb

  Return the paper output definition (`\paper`) in `Paper_book` object pb.

Function: ly:paper-book-performances pb

  Return performances in `Paper_book` object pb.

Function: ly:paper-book-scopes pb

  Return scopes in `Paper_book` object pb.

Function: ly:paper-book-systems pb

  Return systems in `Paper_book` object pb.

Function: ly:paper-fonts def

  Return a list containing the fonts from output definition def (e.g., `\paper`).

Function: ly:paper-get-font def chain

  Find a font metric in output definition def satisfying the font-qualifiers in alist chain chain, and return it. (An alist chain is a list of alists, containing grob properties.)

Function: ly:paper-get-number def sym

  Return the value of variable sym in output definition def as a double.

Function: ly:paper-outputscale def

  Return the output-scale for output definition def.

Function: ly:paper-score-paper-systems paper-score

  Return vector of `paper_system` objects from paper-score.

Function: ly:paper-system? obj

  Is obj a C++ `Prob` object of type `paper-system`?

Function: ly:paper-system-minimum-distance sys1 sys2

  Measure the minimum distance between these two paper-systems, using their stored skylines if possible and falling back to their extents otherwise.

Function: ly:parse-file name

  Parse a single `.ly` file. Upon failure, throw `ly-file-failed` key.

Function: ly:parse-string-expression parser-smob ly-code filename line

  Parse the string ly-code with parser-smob. Return the contained music expression. filename and line are optional source indicators.

Function: ly:parsed-undead-list!

  Return the list of objects that have been found live that should have been dead, and clear that list.

Function: ly:parser-clear-error parser

  Clear the error flag for the parser.

Function: ly:parser-clone parser-smob closures location

  Return a clone of parser-smob. An association list of port positions to closures can be specified in closures in order to have `$` and `#` interpreted in their original lexical environment. If location is a valid location, it becomes the source of all music expressions inside.

Function: ly:parser-define! parser-smob symbol val

  Bind symbol to val in parser-smob’s module.

Function: ly:parser-error parser msg input

  Display an error message and make the parser fail.

Function: ly:parser-has-error? parser

  Does parser have an error flag?

Function: ly:parser-include-string parser-smob ly-code

  Include the string ly-code into the input stream for parser-smob. Can only be used in immediate Scheme expressions (`$` instead of `#`).

Function: ly:parser-lexer parser-smob

  Return the lexer for parser-smob.

Function: ly:parser-lookup parser-smob symbol

  Look up symbol in parser-smob’s module. Return `'()` if not defined.

Function: ly:parser-output-name parser

  Return the base name of the output file.

Function: ly:parser-parse-string parser-smob ly-code

  Parse the string ly-code with parser-smob. Upon failure, throw `ly-file-failed` key.

Function: ly:parser-set-note-names parser names

  Replace current note names in parser. names is an alist of symbols. This only has effect if the current mode is notes.

Function: ly:performance-write performance filename

  Write performance to filename.

Function: ly:pfb->pfa pfb-file-name

  Convert the contents of a Type 1 font in PFB format to PFA format.

Function: ly:pitch? x

  Is x a `Pitch` object?

Function: ly:pitch<? p1 p2

  Is p1 lexicographically smaller than p2?

Function: ly:pitch-alteration pp

  Extract the alteration from pitch pp.

Function: ly:pitch-diff pitch root

  Return pitch delta such that pitch transposed by delta equals root.

Function: ly:pitch-negate p

  Negate p.

Function: ly:pitch-notename pp

  Extract the note name from pitch pp.

Function: ly:pitch-octave pp

  Extract the octave from pitch pp.

Function: ly:pitch-quartertones pp

  Calculate the number of quarter tones of pp from middle C.

Function: ly:pitch-semitones pp

  Calculate the number of semitones of pp from middle C.

Function: ly:pitch-steps p

  Number of steps counted from middle C of the pitch p.

Function: ly:pitch-tones pp

  Calculate the number of tones of pp from middle C as a rational number.

Function: ly:pitch-transpose p delta

  Transpose p by the amount delta, where delta is relative to middle C.

Function: ly:pointer-group-interface::add-grob grob sym grob-element

  Add grob-element to grob’s sym grob array.

Function: ly:position-on-line? sg spos

  Return whether spos is on a line of the staff associated with the grob sg (even on an extender line).

Function: ly:prob? x

  Is x a `Prob` object?

Function: ly:prob-immutable-properties prob

  Retrieve an alist of immutable properties.

Function: ly:prob-mutable-properties prob

  Retrieve an alist of mutable properties.

Function: ly:prob-property prob sym val

  Return the value for property sym of Prob object prob. If no value is found, return val or `'()` if val is not specified.

Function: ly:prob-property? obj sym

  Is boolean prop sym of sym set?

Function: ly:prob-set-property! obj sym value

  Set property sym of obj to value.

Function: ly:prob-type? obj type

  Is obj the specified prob-type?

Function: ly:programming-error str rest

  A Scheme callable function to issue the internal warning str. The message is formatted with `format` and rest.

Function: ly:progress str rest

  A Scheme callable function to print progress str. The message is formatted with `format` and rest.

Function: ly:property-lookup-stats sym

  Return hash table with a property access corresponding to sym. Choices are `prob`, `grob`, and `context`.

Function: ly:protects

  Return hash of protected objects.

Function: ly:pt num

  num printer points.

Function: ly:register-stencil-expression symbol

  Add symbol as head of a stencil expression.

Function: ly:relative-group-extent elements common axis

  Determine the extent of elements relative to common in the axis direction.

Function: ly:reset-all-fonts

  Forget all about previously loaded fonts.

Function: ly:round-filled-box xext yext blot

  Make a `Stencil` object that prints a black box of dimensions xext, yext and roundness blot.

Function: ly:round-filled-polygon points blot

  Make a `Stencil` object that prints a black polygon with corners at the points defined by points (list of coordinate pairs) and roundness blot.

Function: ly:run-translator mus output-def

  Process mus according to output-def. An interpretation context is set up, and mus is interpreted with it. The context is returned in its final state.

  Optionally, this routine takes an object-key to to uniquely identify the score block containing it.

Function: ly:score? x

  Is x a `Score` object?

Function: ly:score-add-output-def! score def

  Add an output definition def to score.

Function: ly:score-embedded-format score layout

  Run score through layout (an output definition) scaled to correct output-scale already, returning a list of layout-lines.

Function: ly:score-error? score

  Was there an error in the score?

Function: ly:score-header score

  Return score header.

Function: ly:score-music score

  Return score music.

Function: ly:score-output-defs score

  All output definitions in a score.

Function: ly:score-set-header! score module

  Set the score header.

Function: ly:set-default-scale scale

  Set the global default scale. This determines the tuning of pitches with no accidentals or key signatures. The first pitch is C. Alterations are calculated relative to this scale. The number of pitches in this scale determines the number of scale steps that make up an octave. Usually the 7-note major scale.

Function: ly:set-grob-modification-callback cb

  Specify a procedure that will be called every time LilyPond modifies a grob property. The callback will receive as arguments the grob that is being modified, the name of the C++ file in which the modification was requested, the line number in the C++ file in which the modification was requested, the name of the function in which the modification was requested, the property to be changed, and the new value for the property.

Function: ly:set-middle-C! context

  Set the `middleCPosition` variable in context based on the variables `middleCClefPosition` and `middleCOffset`.

Function: ly:set-option var val

  Set a program option.

Function: ly:set-property-cache-callback cb

  Specify a procedure that will be called whenever lilypond calculates a callback function and caches the result. The callback will receive as arguments the grob whose property it is, the name of the property, the name of the callback that calculated the property, and the new (cached) value of the property.

Function: ly:simple-closure? clos

  Is clos a simple closure?

Function: ly:skyline? x

  Is x a `Skyline` object?

Function: ly:skyline-empty? sky

  Return whether sky is empty.

Function: ly:skyline-pair? x

  Is x a `Skyline_pair` object?

Function: ly:slur-score-count

  count number of slur scores.

Function: ly:smob-protects

  Return LilyPond’s internal smob protection list.

Function: ly:solve-spring-rod-problem springs rods length ragged

  Solve a spring and rod problem for count objects, that are connected by count-1 springs, and an arbitrary number of rods. count is implicitly given by springs and rods. The springs argument has the format `(ideal, inverse_hook)` and rods is of the form `(idx1, idx2, distance)`.

  length is a number, ragged a boolean.

  The function returns a list containing the force (positive for stretching, negative for compressing and `#f` for non-satisfied constraints) followed by spring-count+1 positions of the objects.

Function: ly:source-file? x

  Is x a `Source_file` object?

Function: ly:spanner? g

  Is g a spanner object?

Function: ly:spanner-bound spanner dir

  Get one of the bounds of spanner. dir is `-1` for left, and `1` for right.

Function: ly:spanner-broken-into spanner

  Return broken-into list for spanner.

Function: ly:spanner-set-bound! spanner dir item

  Set grob item as bound in direction dir for spanner.

Function: ly:spawn command rest

  Simple interface to g_spawn_sync str. The error is formatted with `format` and rest.

Function: ly:spring? x

  Is x a `Spring` object?

Function: ly:spring-set-inverse-compress-strength! spring strength

  Set the inverse compress strength of spring.

Function: ly:spring-set-inverse-stretch-strength! spring strength

  Set the inverse stretch strength of spring.

Function: ly:staff-symbol-line-thickness grob

  Returns the `line-thickness` of the staff associated with grob.

Function: ly:staff-symbol-staff-radius grob

  Returns the radius of the staff associated with grob.

Function: ly:staff-symbol-staff-space grob

  Returns the `staff-space` of the staff associated with grob.

Function: ly:start-environment

  Return the environment (a list of strings) that was in effect at program start.

Function: ly:stderr-redirect file-name mode

  Redirect stderr to file-name, opened with mode.

Function: ly:stencil? x

  Is x a `Stencil` object?

Function: ly:stencil-add args

  Combine stencils. Takes any number of arguments.

Function: ly:stencil-aligned-to stil axis dir

  Align stil using its own extents. dir is a number. `-1` and `1` are left and right, respectively. Other values are interpolated (so `0` means the center).

Function: ly:stencil-combine-at-edge first axis direction second padding

  Construct a stencil by putting second next to first. axis can be 0 (x-axis) or 1 (y-axis). direction can be -1 (left or down) or 1 (right or up). The stencils are juxtaposed with padding as extra space. first and second may also be `'()` or `#f`.

Function: ly:stencil-empty? stil axis

  Return whether stil is empty. If an optional axis is supplied, the emptiness check is restricted to that axis.

Function: ly:stencil-expr stil

  Return the expression of stil.

Function: ly:stencil-extent stil axis

  Return a pair of numbers signifying the extent of stil in axis direction (`0` or `1` for x and y axis, respectively).

Function: ly:stencil-fonts s

  Analyze s, and return a list of fonts used in s.

Function: ly:stencil-in-color stc r g b

  Put stc in a different color.

Function: ly:stencil-rotate stil angle x y

  Return a stencil stil rotated angle degrees around the relative offset (x, y). E.g., an offset of (-1, 1) will rotate the stencil around the left upper corner.

Function: ly:stencil-rotate-absolute stil angle x y

  Return a stencil stil rotated angle degrees around point (x, y), given in absolute coordinates.

Function: ly:stencil-scale stil x y

  Scale stil using the horizontal and vertical scaling factors x and y.

Function: ly:stencil-stack first axis direction second padding mindist

  Construct a stencil by stacking second next to first. axis can be 0 (x-axis) or 1 (y-axis). direction can be -1 (left or down) or 1 (right or up). The stencils are juxtaposed with padding as extra space. first and second may also be `'()` or `#f`. As opposed to `ly:stencil-combine-at-edge`, metrics are suited for successively accumulating lines of stencils. Also, second stencil is drawn last.

  If mindist is specified, reference points are placed apart at least by this distance. If either of the stencils is spacing, padding and mindist do not apply.

Function: ly:stencil-translate stil offset

  Return a stil, but translated by offset (a pair of numbers).

Function: ly:stencil-translate-axis stil amount axis

  Return a copy of stil but translated by amount in axis direction.

Function: ly:stream-event? obj

  Is `obj` a `Stream_event` object?

Function: ly:string-percent-encode str

  Encode all characters in string str with hexadecimal percent escape sequences, with the following exceptions: characters `-`, `.`, `/`, and `_`; and characters in ranges `0-9`, `A-Z`, and `a-z`.

Function: ly:string-substitute a b s

  Replace string a by string b in string s.

Function: ly:system-font-load name

  Load the OpenType system font ‘`name.otf`’. Fonts loaded with this command must contain three additional SFNT font tables called `LILC`, `LILF`, and `LILY`, needed for typesetting musical elements. Currently, only the Emmentaler and the Emmentaler-Brace fonts fulfill these requirements.

  Note that only `ly:font-get-glyph` and derived code (like `\lookup`) can access glyphs from the system fonts; text strings are handled exclusively via the Pango interface.

Function: ly:text-interface::interpret-markup

  Convert a text markup into a stencil. Takes three arguments, layout, props, and markup.

  layout is a `\layout` block; it may be obtained from a grob with `ly:grob-layout`. props is an alist chain, i.e. a list of alists. This is typically obtained with `(ly:grob-alist-chain grob (ly:output-def-lookup layout 'text-font-defaults))`. markup is the markup text to be processed.

Function: ly:translate-cpp-warning-scheme str

  Translates a string in C++ printf format and modifies it to use it for scheme formatting.

Function: ly:translator? x

  Is x a `Translator` object?

Function: ly:translator-context trans

  Return the context of the translator object trans.

Function: ly:translator-description me

  Return an alist of properties of translator me.

Function: ly:translator-group? x

  Is x a `Translator_group` object?

Function: ly:translator-name trans

  Return the type name of the translator object trans. The name is a symbol.

Function: ly:transpose-key-alist l pit

  Make a new key alist of l transposed by pitch pit.

Function: ly:truncate-list! lst i

  Take at most the first i of list lst.

Function: ly:ttf->pfa ttf-file-name idx

  Convert the contents of a TrueType font file to PostScript Type 42 font, returning it as a string. The optional idx argument is useful for TrueType collections (TTC) only; it specifies the font index within the TTC. The default value of idx is 0.

Function: ly:ttf-ps-name ttf-file-name idx

  Extract the PostScript name from a TrueType font. The optional idx argument is useful for TrueType collections (TTC) only; it specifies the font index within the TTC. The default value of idx is 0.

Function: ly:undead? x

  Is x a `Undead` object?

Function: ly:unit

  Return the unit used for lengths as a string.

Function: ly:unpure-pure-container? clos

  Is clos an unpure pure container?

Function: ly:unpure-pure-container-pure-part pc

  Return the pure part of pc.

Function: ly:unpure-pure-container-unpure-part pc

  Return the unpure part of pc.

Function: ly:usage

  Print usage message.

Function: ly:verbose-output?

  Was verbose output requested, i.e. loglevel at least `DEBUG`?

Function: ly:version

  Return the current lilypond version as a list, e.g., `(1 3 127 uu1)`.

Function: ly:warning str rest

  A Scheme callable function to issue the warning str. The message is formatted with `format` and rest.

Function: ly:warning-located location str rest

  A Scheme callable function to issue the warning str at the specified location in an input file. The message is formatted with `format` and rest.

Function: ly:wide-char->utf-8 wc

  Encode the Unicode codepoint wc, an integer, as UTF-8.

#### Internals Reference v2.18.2 (稳定分支).