LilyPond program-reference: 4. Scheme functions

# 4. Scheme functions

Function: dispatcher x

  Is x a `Dispatcher` object?

Function: listener x

  Is x a `Listener` object?

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

  Add mappings for error messages from alist.

Function: ly:add-interface a b c

  Add an interface description.

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 with default val.

Function: ly:all-grob-interfaces

  Get a hash table with all 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

  Return value if key in alist, else `default-value` (or `#f` if not specified).

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-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: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 dfault

  Return value for key from a list of alists achain. If no entry is found, return dfault or `#f` if no dfault is specified.

Function: ly:clear-anonymous-modules

  Plug a GUILE 1.6 and 1.7 memory leak by breaking a weak reference pointer cycle explicitly.

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:command-line-verbose?

  Was `be_verbose_global` set?

Function: ly:connect-dispatchers to from

  Make the dispatcher to listen to events from from.

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-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 c name

  Return the value of name from context c.

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:context? x

  Is x a `Context` object?

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

  A type predicate. The direction `s` is `-1`, `0` or `1`, where `-1` represents left or down and `1` represents right or up.

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<? p1 p2

  Is p1 shorter than p2?

Function: ly:duration? x

  Is x a `Duration` object?

Function: ly:effective-prefix

  Return effective prefix.

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-deep-copy m

  Copy m and all sub expressions of m.

Function: ly:event-property sev sym

  Get the property sym of stream event mus. If sym is undefined, return `'()`.

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:export arg

  Export a Scheme object to the parser so it is treated as an identifier.

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 Aybabtu 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 Aybabtu 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 Aybabtu 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 Aybabtu 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`.

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-glyph font index

  Retrieve a stencil for the glyph numbered 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 Aybabtu fonts, corresponding to the font encodings `fetaMusic` and `fetaBraces`, respectively.

Function: ly:get-listened-event-classes

  Return a list of all event classes that some translator listens to.

Function: ly:get-option var

  Get a global option setting.

Function: ly:gettext original

  A Scheme wrapper function for `gettext`.

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-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-array? x

  Is x a `Grob_array` object?

Function: ly:grob-basic-properties grob

  Get the immutable properties of grob.

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 gr.

Function: ly:grob-extent grob refp axis

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

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 g of property sym. It returns `'()` (end-of-list) if sym is undefined in g.

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 deflt

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

Function: ly:grob-property-data grob sym

  Retrieve sym for grob but don’t process callbacks.

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-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 g on axis a over distance d.

Function: ly:grob? x

  Is x a `Grob` object?

Function: ly:gulp-file name size

  Read the file name, and return its contents in a string. 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: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:is-listened-event-class sym

  Is sym a listened event class?

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:item? g

  Is g an `Item` object?

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: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-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 num and den.

  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 n d gn gd

  Create the rational number with main timing n/d, and optional grace timing gn/gd.

  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.

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` is a list containing either `ly:music?` predicates or other type predicates.

Function: ly:make-output-def

  Make an output definition.

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

  Return page marker with 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. 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 score.

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-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 `(1000 . -1000)` 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: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-add a b

  Add two moments.

Function: ly:moment-div a b

  Divide two moments.

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-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:moment<? a b

  Compare two moments.

Function: ly:moment? x

  Is x a `Moment` 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.

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-extract x

  Return the Scheme function inside x.

Function: ly:music-function? x

  Is x a `music-function`?

Function: ly:music-length mus

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

Function: ly:music-list? lst

  Type predicate: Return true if lst is 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 dfault

  Get the property sym of music expression mus. If sym is undefined, return `'()`.

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:music? obj

  Type predicate.

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 num to a string without generating many decimals.

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

  Print `ly:set-option` usage.

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-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-font? font

  Is font an OpenType font?

Function: ly:otf-glyph-list font

  Return a list of glyph names for font.

Function: ly:output-def-clone def

  Clone output definition def.

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

  Look up sym in the pap output definition (e.g., `\paper`). Return the value or def (which defaults to `'()`) if undefined.

Function: ly:output-def-parent def

  Get the parent output definition of def.

Function: ly:output-def-scope def

  Get 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-def? def

  Is def a layout definition?

Function: ly:output-description output-def

  Return the description of translators 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-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-physical-fonts f

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

Function: ly:pango-font? f

  Is f a pango font?

Function: ly:paper-book-pages pb

  Return pages in book pb.

Function: ly:paper-book-paper pb

  Return pages in book pb.

Function: ly:paper-book-performances paper-book

  Return performances in book paper-book.

Function: ly:paper-book-scopes book

  Return scopes in layout book book.

Function: ly:paper-book-systems pb

  Return systems in book pb.

Function: ly:paper-book? x

  Is x a `Paper_book` object?

Function: ly:paper-fonts bp

  Return fonts from the `\paper` block bp.

Function: ly:paper-get-font paper-smob chain

  Return a font metric satisfying the font-qualifiers in the alist chain chain. (An alist chain is a list of alists, containing grob properties.)

Function: ly:paper-get-number layout-smob name

  Return the layout variable name.

Function: ly:paper-outputscale bp

  Get output-scale for bp.

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

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

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:paper-system? obj

  Type predicate.

Function: ly:parse-file name

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

Function: ly:parser-clear-error parser

  Clear the error flag for the parser.

Function: ly:parser-clone parser-smob

  Return a clone of parser-smob.

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-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 PFB file to PFA.

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-transpose p delta

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

Function: ly:pitch<? p1 p2

  Is p1 lexicographically smaller than p2?

Function: ly:pitch? x

  Is x a `Pitch` object?

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

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

Function: ly:prob-immutable-properties prob

  Retrieve an alist of mutable properties.

Function: ly:prob-mutable-properties prob

  Retrieve an alist of mutable properties.

Function: ly:prob-property obj sym dfault

  Return the value for sym.

Function: ly:prob-property? obj sym

  Is boolean prop 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:prob? x

  Is x a `Prob` object?

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-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. This function takes an optional `Object_key` argument.

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:score? x

  Is x a `Score` object?

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

  Type predicate.

Function: ly:skyline-pair? x

  Is x a `Skyline_pair` object?

Function: ly:skyline? x

  Is x a `Skyline` object?

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-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? g

  Is g a spanner object?

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

  Returns the line-thickness 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-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 minimum

  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. If this puts the reference points closer than minimum, they are moved by the latter amount. first and second may also be `'()` or `#f`.

Function: ly:stencil-empty? stil

  Return whether stil is empty.

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-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:stencil? x

  Is x a `Stencil` object?

Function: ly:stream-event? x

  Is x a `Stream_event` object?

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 Aybabtu 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:system-print system

  Draw the system and return the prob containing its stencil.

Function: ly:system-stretch system amount-scm

  Stretch the system vertically by the given amount. This must be called before the system is drawn (for example with `ly:system-print`).

Function: ly:text-dimension font text

  Given the font metric in font and the string text, compute the extents of that text in that font. The return value is a pair of number-pairs.

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: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:translator? x

  Is x a `Translator` object?

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:unit

  Return the unit used for lengths as a string.

Function: ly:usage

  Print usage message.

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:wide-char->utf-8 wc

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

#### Internals Reference